MQTT-C: MQTT-C

MQTT-C

MQTT-C

MQTT-C is an MQTT v3.1.1 client written in C. MQTT is a lightweight publisher-subscriber-based messaging protocol that is commonly used in IoT and networking applications where high-latency and low data-rate links are expected. The purpose of MQTT-C is to provide a portable MQTT client, written in C, for embedded systems and PC's alike. MQTT-C does this by providing a transparent Platform Abstraction Layer (PAL) which makes porting to new platforms easy. MQTT-C is completely thread-safe but can also run perfectly fine on single-threaded systems making MQTT-C well-suited for embedded systems and microcontrollers. Finally, MQTT-C is small; there are only two source files totalling less than 2000 lines.

#### A note from the author

It's been great to hear about all the places MQTT-C is being used! Please don't hesitate to get in touch with me or submit issues on GitHub!

## Getting Started

To use MQTT-C you must first instantiate a `struct mqtt_client` and initialize it by calling mqtt_init.

struct mqtt_client client; /* instantiate the client */
mqtt_init(&client, ...); /* initialize the client */

Once your client is initialized you must connect to an MQTT broker.

mqtt_connect(&client, ...); /* send a connection request to the broker. */

At this point the client is ready to use! For example, we can subscribe to like so:

/* subscribe to "toaster/temperature" with a max QoS level of 0 */
mqtt_subscribe(&client, "toaster/temperature", 0);

And we can publish, say the coffee maker's temperature, like so:

/* publish coffee temperature with a QoS level of 1 */
int temperature = 67;
mqtt_publish(&client, "coffee/temperature", &temperature, sizeof(int), MQTT_PUBLISH_QOS_1);

## Building

There are only two source files that need to be built, `mqtt.c` and `mqtt_pal.c`. These files are ANSI C (C89) compatible, and should compile with any C compiler.

Then, simply `#include <mqtt.h>`.

## Documentation

Pre-built documentation can be found here: https://liambindle.ca/MQTT-C.

The API documentation contains all the documentation application programmers should need. The Platform abstraction layer documentation contains everything you should need to port MQTT-C to a new platform, and the other modules contain documentation for MQTT-C developers.

## Testing and Building the Tests

The MQTT-C unit tests use the cmocka unit testing framework. Therefore, cmocka must be installed on your machine to build and run the unit tests. For convenience, a simple `"makefile"` is included to build the unit tests and examples on UNIX-like machines. The unit tests and examples can be built as follows:

$ make all

The unit tests and examples will be built in the `"bin/"` directory. The unit tests can be run like so:

$ ./bin/tests [address [port]]

Note that the `address` and `port` arguments are both optional to specify the location of the MQTT broker that is to be used for the tests. If no `address` is given then the Mosquitto MQTT Test Server will be used. If no `port` is given, port 1883 will be used.

## Portability

MQTT-C provides a transparent platform abstraction layer (PAL) in `mqtt_pal.h` and `mqtt_pal.c`. These files declare and implement the types and calls that MQTT-C requires. Refer to Platform abstraction layer for the complete documentation of the PAL.

## Contributing

Please feel free to submit issues and pull-requests here. When submitting a pull-request please ensure you have fully documented your changes and added the appropriate unit tests.

## License

This project is licensed under the MIT License. See the `"LICENSE"` file for more details.

## Authors

MQTT-C was initially developed as a CMPT 434 (Winter Term, 2018) final project at the University of Saskatchewan by:

- Liam Bindle
- Demilade Adeoye