Skip to content
MQTT ClientMQTT

wolfMQTT - MQTT Client Library Encyclopedia

by David Garske
6 min read

The wolfMQTT library is an MQTT client implementation written in C for embedded use. It supports SSL/TLS via the wolfSSL library. It was built from the ground up to be multi-platform, space conscience and extensible. It supports all Packet Types, all Quality of Service (QoS) levels 0-2 and supports SSL/TLS using the wolfSSL library. This implementation supports the MQTT v3.1.1, MQTT v5.0 and MQTT-SN v1.2 specifications.

Why Use wolfMQTT Client Library?

wolfMQTT
Language C
License GPL v2
Website wolfssl.com/products/wolfmqtt/
API Style Blocking or Non-Blocking

The wolfMQTT library was created in October 2015 due to many requests from wolfSSL customers for us to have an MQTT client library with TLS support.

Features Supported by wolfMQTT Client Library

Feature
MQTT 3.1 No
MQTT 3.1.1 Yes
MQTT 5.0 Yes
MQTT-SN v1.2 Yes
LWT Yes
Automatic Reconnect No

Advanced Features: wolfMQTT Client Library

Feature
QoS 0 Yes
QoS 1 Yes
QoS 2 Yes
Authentication Yes
Throttling No
SSL/TLS Yes

Additional Features

  • Built from scratch by wolfSSL engineers

  • Supports MQTT v3.1.1 specification

  • Support for MQTT v5.0

  • Support for MQTT Sensor Network (MQTT-SN) v1.2

  • Supports all client side packet types and protocol options

  • QoS Levels 0-2 (guarenteed delivery)

  • Supports plain TCP or TLS (via the wolfSSL library)

  • Single threaded model and single message callback

  • Written in Native C89 with portability/compatibility in mind

  • Space conscience design (Compiled size is about 3.6KB)

  • User manual with build instructions, example overview and API documentation

  • Example MQTT client implementations

  • Network interface is abstracted via callbacks for extensibility

  • Packet parsing encoding/decoding structured for custom use

  • Minimal external dependencies (strlen, memcpy, memset) (overridable macros)

  • Detailed error checking/handling

  • Doxygen style inline documentation

  • Less than 1200 lines of well structured C code

  • Tested on multiple variants of MQTT broker servers, QoS levels 0-2 with/without TLS.

  • Tested on Linux, Mac OS X and Freescale Kinetis K64.

  • Inherits wolfSSL library features such as lightweight TLS using ChaCha20/Poly1305 AEAD, small size and portability.

  • Open source (GPLv2)

  • Support for FreeRTOS+TCP

  • Includes an example Arduino IDE project

  • IBM Watson IoT example with an IBM developer recipe.

Usage of wolfMQTT Client Library

Installation of wolfMQTT Client Library

The most recent version can be downloaded from the GitHub website here:

Either click the “Download ZIP” button or use the command
git clone git@github.com:wolfSSL/wolfMQTT.git

When building on Linux, BSD, OS X, Solaris, or other nix-like systems, use the autoconf system. To build wolfMQTT you only need to run three commands:

./configure
make
make install

When building on Windows there is a Visual Studio 2015 solution included.

For additional help, see the wolfMQTT User Manual.

Connect 

int MqttClient_Connect(
	MqttClient *client,
	MqttConnect *connect);

Encodes and sends the MQTT Connect packet and waits for the Connect Acknowledgement packet. This is a blocking function that will wait for MqttNet.read data.

Return Values:

See MqttPacketResponseCodes in /wolfmqtt/mqtt_types.h
MQTT_CODE_SUCCESS - Success

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.
connect - Pointer to MqttConnect structure populated with connection options.

Example:

#include <wolfmqtt/mqtt_client.h>;
int rc = 0;
MqttClient client;
MqttConnect connect;
MqttMessage lwt_msg;

/* Define connect parameters */
connect.keep_alive_sec = keep_alive_sec;
connect.clean_session = clean_session;
connect.client_id = client_id;

/* Last will and testament sent by broker to subscribers of topic when broker connection is lost */
memset(&lwt_msg, 0, sizeof(lwt_msg));
connect.lwt_msg = &lwt_msg;
connect.enable_lwt = enable_lwt;
if (enable_lwt) {
lwt_msg.qos = qos;
lwt_msg.retain = 0;
lwt_msg.topic_name = "lwttopic";
lwt_msg.message = (byte*)DEFAULT_CLIENT_ID;
lwt_msg.message_len = strlen(DEFAULT_CLIENT_ID);
}
/* Optional authentication */
connect.username = username;
connect.password = password;

/* Send Connect and wait for Connect Ack */
rc = MqttClient_Connect(&client, &connect);
if (rc != MQTT_CODE_SUCCESS) {
   printf("MQTT Connect: %s (%d)\n", MqttClient_ReturnCodeToString(rc), rc);
}

Connect with LWT

See Connect example above.

Connect with Username/Password

See Connect example above.

Publish

int MqttClient_Publish(
        MqttClient *client, 
        MqttPublish *publish);

Encodes and sends the MQTT Publish packet and waits for the Publish response (if QoS > 0). This is a blocking function that will wait for MqttNet.read data. If QoS level = 1 then will wait for PUBLISH_ACK. If QoS level = 2 then will wait for PUBLISH_REC then send PUBLISH_REL and wait for PUBLISH_COMP.

Return Values:

See enum MqttPacketResponseCodes in /wolfmqtt/mqtt_types.h
MQTT_CODE_SUCCESS - success

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.
publish - Pointer to MqttPublish structure initialized with message data. Note: MqttPublish and MqttMessage are same structure.

Example:

#include <wolfmqtt/mqtt_client.h>
#define TEST_MESSAGE            "test" /* NULL */

int rc = 0;
MqttPublish publish;
word16 packet_id = 0;

/* Publish Topic */
publish.retain = 0;
publish.qos = qos;
publish.duplicate = 0;
publish.topic_name = "pubtopic";
publish.packet_id = ++packet_id;
publish.message = (byte*)TEST_MESSAGE;
publish.message_len = strlen(TEST_MESSAGE);
rc = MqttClient_Publish(&client, &publish);
if (rc != MQTT_CODE_SUCCESS) {
	printf("MQTT Publish: %s (%d)\n", MqttClient_ReturnCodeToString(rc), rc);
}

Publish a Retained Message

See publish example. Set publish.retain = 1.

Subscribe

int MqttClient_Subscribe(
        MqttClient *client, 
        MqttSubscribe *subscribe);

Encodes and sends the MQTT Subscribe packet and waits for the Subscribe Acknowledgement packet. This is a blocking function that will wait for MqttNet.read data.

Return Values: 

enum MqttPacketResponseCodes

in

/wolfmqtt/mqtt_types.h
MQTT_CODE_SUCCESS - Success

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.
subscribe - Pointer to MqttSubscribe structure initialized with subscription topic list and desired QoS.

Example:

#include <wolfmqtt/mqtt_client.h>
#define TEST_TOPIC_COUNT        2

int rc = 0;
MqttSubscribe subscribe;
MqttTopic topics[TEST_TOPIC_COUNT], *topic;
word16 packet_id = 0;

/* Build list of topics */
topics[0].topic_filter = "subtopic1";
topics[0].qos = qos;
topics[1].topic_filter = "subtopic2";
topics[1].qos = qos;

/* Subscribe Topic */
subscribe.packet_id = ++packet_id;
subscribe.topic_count = TEST_TOPIC_COUNT;
subscribe.topics = topics;
rc = MqttClient_Subscribe(&client, &subscribe);

if (rc == MQTT_CODE_SUCCESS) {
 	for (i = 0; i < subscribe.topic_count; i++) {
		topic = &subscribe.topics[i];
		printf("  Topic %s, Qos %u, Return Code %u\n",
		topic->topic_filter, topic->qos, topic->return_code);
	}
}
else {
	printf("MQTT Subscribe: %s (%d)\n", MqttClient_ReturnCodeToString(rc), rc);
}

Unsubscribe

int MqttClient_Unsubscribe(
        MqttClient *client, 
        MqttUnsubscribe *unsubscribe);

Encodes and sends the MQTT Unsubscribe packet and waits for the Unsubscribe Acknowledgement packet. This is a blocking function that will wait for MqttNet.read data.

Return Values: 

enum MqttPacketResponseCodes

in

/wolfmqtt/mqtt_types.h
`MQTT_CODE_SUCCESS - Success

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.
unsubscribe - Pointer to MqttUnsubscribe structure initialized with topic list.

Example:

#include <wolfmqtt/mqtt_client.h>
#define TEST_TOPIC_COUNT        2

int rc = 0;
MqttUnsubscribe unsubscribe;
MqttTopic topics[TEST_TOPIC_COUNT], *topic;
word16 packet_id = 0;

/* Build list of topics */
topics[0].topic_filter = "subtopic1";
topics[1].topic_filter = "subtopic2";

/* Unsubscribe Topics */
unsubscribe.packet_id = ++packet_id;
unsubscribe.topic_count = TEST_TOPIC_COUNT;
unsubscribe.topics = topics;
rc = MqttClient_Unsubscribe(&client, &unsubscribe);
if (rc != MQTT_CODE_SUCCESS) {
	printf("MQTT Unsubscribe: %s (%d)\n", MqttClient_ReturnCodeToString(rc), rc);
}

Disconnect

int MqttClient_Disconnect(
        MqttClient *client);

Encodes and sends the MQTT Disconnect packet (no response).

Return Values: See enum

MqttPacketResponseCodes

in

/wolfmqtt/mqtt_types.h
MQTT_CODE_SUCCESS - Success

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.

Example:

#include <wolfmqtt/mqtt_client.h>

int rc = MqttClient_Disconnect(&client);
if (rc != MQTT_CODE_SUCCESS) {
	printf("MQTT Disconnect: %s (%d)\n", MqttClient_ReturnCodeToString(rc),
rc);
}

Using SSL/TLS

/* Connect to broker */
rc = MqttClient_NetConnect(&client, host, port,
	DEFAULT_CON_TIMEOUT_MS, use_tls, mqttclient_tls_cb);
printf("MQTT Socket Connect: %s (%d)\n",
	MqttClient_ReturnCodeToString(rc), rc);

Full Example Application 

#include <wolfmqtt/mqtt_client.h>

int rc;
MqttNet net;
MqttClient client;

/* Start example MQTT Client */
printf("MQTT Client\n");

/* Initialize Network */
rc = MqttClientNet_Init(&net);
printf("MQTT Net Init: %s (%d)\n",
    MqttClient_ReturnCodeToString(rc), rc);

/* Initialize MqttClient structure */
tx_buf = malloc(MAX_BUFFER_SIZE);
rx_buf = malloc(MAX_BUFFER_SIZE);
rc = MqttClient_Init(&client, &net, mqttclient_message_cb,
    tx_buf, MAX_BUFFER_SIZE, rx_buf, MAX_BUFFER_SIZE,
    DEFAULT_CMD_TIMEOUT_MS);
printf("MQTT Init: %s (%d)\n",
    MqttClient_ReturnCodeToString(rc), rc);

/* Connect to broker */
rc = MqttClient_NetConnect(&client, host, port,
    DEFAULT_CON_TIMEOUT_MS, use_tls, mqttclient_tls_cb);
printf("MQTT Socket Connect: %s (%d)\n",
    MqttClient_ReturnCodeToString(rc), rc);

if (rc == 0) {
    /* Define connect parameters */
    MqttConnect connect;
    MqttMessage lwt_msg;
    connect.keep_alive_sec = keep_alive_sec;
    connect.clean_session = clean_session;
    connect.client_id = client_id;
    /* Last will and testament sent by broker to subscribers
        of topic when broker connection is lost */
    memset(&lwt_msg, 0, sizeof(lwt_msg));
    connect.lwt_msg = &lwt_msg;
    connect.enable_lwt = enable_lwt;
    if (enable_lwt) {
        lwt_msg.qos = qos;
        lwt_msg.retain = 0;
        lwt_msg.topic_name = "lwttopic";
        lwt_msg.buffer = (byte*)DEFAULT_CLIENT_ID;
        lwt_msg.total_len = (word16)strlen(DEFAULT_CLIENT_ID);
    }
    /* Optional authentication */
    connect.username = username;
    connect.password = password;

    /* Send Connect and wait for Connect Ack */
    rc = MqttClient_Connect(&client, &connect);
    printf("MQTT Connect: %s (%d)\n",
        MqttClient_ReturnCodeToString(rc), rc);
    if (rc == MQTT_CODE_SUCCESS) {
        MqttSubscribe subscribe;
        MqttUnsubscribe unsubscribe;
        MqttTopic topics[TEST_TOPIC_COUNT], *topic;
        MqttPublish publish;
        int i;

        /* Build list of topics */
        topics[0].topic_filter = "subtopic1";
        topics[0].qos = qos;
        topics[1].topic_filter = "subtopic2";
        topics[1].qos = qos;

        /* Validate Connect Ack info */
        printf("MQTT Connect Ack: Return Code %u, Session Present %d\n",
            connect.ack.return_code,
            (connect.ack.flags & MQTT_CONNECT_ACK_FLAG_SESSION_PRESENT) ?
                1 : 0
        );

        /* Subscribe Topic */
        subscribe.packet_id = mqttclient_get_packetid();
        subscribe.topic_count = TEST_TOPIC_COUNT;
        subscribe.topics = topics;
        rc = MqttClient_Subscribe(&client, &subscribe);
        printf("MQTT Subscribe: %s (%d)\n",
            MqttClient_ReturnCodeToString(rc), rc);
        for (i = 0; i < subscribe.topic_count; i++) {
            topic = &subscribe.topics[i];
            printf("  Topic %s, Qos %u, Return Code %u\n",
                topic->topic_filter, topic->qos, topic->return_code);
        }

        /* Publish Topic */
        publish.retain = 0;
        publish.qos = qos;
        publish.duplicate = 0;
        publish.topic_name = "pubtopic";
        publish.packet_id = mqttclient_get_packetid();
        publish.buffer = (byte*)TEST_MESSAGE;
        publish.total_len = (word16)strlen(TEST_MESSAGE);
        rc = MqttClient_Publish(&client, &publish);
        printf("MQTT Publish: Topic %s, %s (%d)\n",
            publish.topic_name, MqttClient_ReturnCodeToString(rc), rc);

        /* Read Loop */
        printf("MQTT Waiting for message...\n");
        while (mStopRead == 0) {
            /* Try and read packet */
            rc = MqttClient_WaitMessage(&client, DEFAULT_CMD_TIMEOUT_MS);
            if (rc != MQTT_CODE_SUCCESS && rc != MQTT_CODE_ERROR_TIMEOUT) {
                /* There was an error */
                printf("MQTT Message Wait: %s (%d)\n",
                    MqttClient_ReturnCodeToString(rc), rc);
                break;
            }
        }

        /* Unsubscribe Topics */
        unsubscribe.packet_id = mqttclient_get_packetid();
        unsubscribe.topic_count = TEST_TOPIC_COUNT;
        unsubscribe.topics = topics;
        rc = MqttClient_Unsubscribe(&client, &unsubscribe);
        printf("MQTT Unsubscribe: %s (%d)\n",
            MqttClient_ReturnCodeToString(rc), rc);

        rc = MqttClient_Disconnect(&client);
        printf("MQTT Disconnect: %s (%d)\n",
            MqttClient_ReturnCodeToString(rc), rc);
    }

    rc = MqttClient_NetDisconnect(&client);
    printf("MQTT Socket Disconnect: %s (%d)\n",
         MqttClient_ReturnCodeToString(rc), rc);
}

/* Free resources */
if (tx_buf) free(tx_buf);
if (rx_buf) free(rx_buf);

/* Cleanup network */
rc = MqttClientNet_DeInit(&net);
printf("MQTT Net DeInit: %s (%d)\n",
    MqttClient_ReturnCodeToString(rc), rc);

Check out HiveMQ MQTT Client libraries and other featured MQTT client libraries.

David Garske

David Garske works for wolfSSL and has been in IoT embedded software development since 2005. wolfSSL, founded in 2004, is an Open Source Internet security company with products including the wolfSSL embedded SSL/TLS library, wolfCrypt crypto engine, SSL Inspection, and wolfMQTT.

Related content:

Load Balancing MQTT Clients: A Beginner’s Guide

A beginner’s guide to load balancing MQTT clients. Explore best practices, techniques, and tools to achieve a scalable and reliable MQTT infrastructure.

Blog

Async.MQTT5: A New C++20 MQTT Client Implementation

Explore Async.MQTT5, a modern C++ MQTT client that works out of the box with HiveMQ Cloud. Learn how to implement it for MQTT implementation.

Blog

Implementing MQTT in C

Get started with MQTT in C. Learn to configure an MQTT Broker in C with code examples and security best practices.

Blog
HiveMQ logo
Review HiveMQ on G2