Skip to content

Library Design

Library header files are located in the /wolfmqtt directory. Only the /wolfmqtt/mqtt_client.h header is required to be included:

#include <wolfmqtt/mqtt_client.h>

The library has three components:


This is where the top level application interfaces for the MQTT client reside.

  • int MqttClient_Init(MqttClient *client, MqttNet *net, MqttMsgCb msg_cb, byte *tx_buf, int tx_buf_len, byte *rx_buf, int rx_buf_len, int cmd_timeout_ms);

These API's are blocking on until error/timeout (cmd_timeout_ms):

  • int MqttClient_Connect(MqttClient *client, MqttConnect *connect);
  • int MqttClient_Publish(MqttClient *client, MqttPublish *publish);
  • int MqttClient_Subscribe(MqttClient *client, MqttSubscribe *subscribe);
  • int MqttClient_Unsubscribe(MqttClient *client, MqttUnsubscribe *unsubscribe);
  • int MqttClient_Ping(MqttClient *client);
  • int MqttClient_Disconnect(MqttClient *client);

This function blocks waiting for a new publish message to arrive for a maximum duration of timeout_ms.

  • int MqttClient_WaitMessage(MqttClient *client, MqttMessage *message, int timeout_ms);

These are the network connect / disconnect interfaces that wrap the MqttNet callbacks and handle WolfSSL TLS:

  • int MqttClient_NetConnect(MqttClient *client, const char* host, word16 port, int timeout_ms, int use_tls, MqttTlsCb cb);
  • int MqttClient_NetDisconnect(MqttClient *client);

Helper functions:

  • const char* MqttClient_ReturnCodeToString(int return_code);


This is where all the packet encoding/decoding is handled.

The header contains the MQTT Packet structures for:

  • Connect: MqttConnect
  • Publish / Message: MqttPublish / MqttMessage (they are the same)
  • Subscribe: MqttSubscribe
  • Unsubscribe: MqttUnsubscribe


This is where the transport socket optionally wraps TLS and uses the MqttNet callbacks for the platform specific network handling.

The header contains the MQTT Network structure MqttNet for network callback and context.

Example Design

The examples use a common examples/mqttnet.c to handle the network callbacks on the clients. This reference supports Linux (BSD sockets), FreeRTOS/LWIP, MQX RTCS, Harmony and Windows.