WOLFMQTT USER MANUAL

Download wolfMQTT Manual (PDF)

wolfMQTT User Manual

May 25, 2018

Version 1.0

Table of Contents


Chapter 1: Introduction

1.1 Protocol Overview

Chapter 2:  Building wolfMQTT

2.1 Getting the Source Code

2.2 Building on *nix

2.3 Building on Windows

2.4 Building on Other Systems

2.5 Building in a non-standard environment

2.6 Cross Compiling

2.7 Install to Custom Directory

Chapter 3 : Getting Started

3.1 Client Example

3.2 Firmware Update Example

3.3 Azure IoT Hub Example

3.4 AWS IoT Example

3.4 Watson IoT Example

Chapter 4: Library Design

1. mqtt_client

2. mqtt_packet

3. mqtt_socket

4.1 Example Design

Chapter 5: API Reference

5.1 MqttPacketResponseCodes (enum)

5.2 MqttClient_Init

5.3 MqttClient_Connect

5.4 MqttClient_Publish

5.5 MqttClient_Subscribe

5.6 MqttClient_Unsubscribe

5.7 MqttClient_Ping

5.8 MqttClient_Disconnect

5.9 MqttClient_WaitMessage

5.10 MqttClient_NetConnect

5.11 MqttClient_NetDisconnect

5.12 MqttClient_ReturnCodeToString

5.13 MqttClient_SetDisconnectCallback


Chapter 1: Introduction


This is an implementation of the MQTT (Message Queuing Telemetry Transport) Client written in C. This library 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 is based on the MQTT v3.1.1 specification.

1.1 Protocol Overview


MQTT is a lightweight open messaging protocol that was developed for constrained environments such as M2M (Machine to Machine) and IoT (Internet of Things), where a small code footprint is required. MQTT is based on the Pub/Sub messaging principle of publishing messages and subscribing to topics. The protocol efficiently packs messages to keep the overhead very low. The MQTT specification recommends TLS as a transport option to secure the protocol using port 8883 (secure-mqtt). Constrained devices can benefit from using TLS session resumption to reduce the reconnection cost.

MQTT defines QoS levels 0-2 to specify the delivery integrity required:

0 = At most once delivery: No acknowledgment.

1 = At least once delivery: Sends acknowledgment (PUBLISH_ACK).

2 = Exactly once delivery: Sends received (PUBLISH_REC), gets back released (PUBLISH_REL) and then sends complete (PUBLISH_COMP).

Highlights:

  • A publish message payload can be up to 256MB (28 bits).
  • Packet header remaining length is encoded using a scheme where the most significant bit (7) indicates an additional length byte.
  • Packets which require a response must include a 16-bit packet Id. This needs to be unique for any outstanding transactions. Typically an incremented value.
  • A client can provide a last will and testament upon connect, which will be delivered when the broker sees the client has disconnected or network keep-alive has expired.
  • The packet types are: CONNECT, CONNECT_ACK, PUBLISH, PUBLISH_ACK, PUBLISH_REC, PUBLISH_REL, PUBLISH_COMP, SUBSCRIBE, SUBSCRIBE_ACK, UNSUBSCRIBE, UNSUBSCRIBE_ACK, PING_REQ, PING_RESP and DISCONNECT.
  • The connect packet contains the ASCII string “MQTT” to define the protocol name. This can be useful for wireshark/sniffing.
  • Multiple topics can be subscribed or unsubscribed in the same packet request.
  • Each subscription topic must define a QoS level. The QoS level is confirmed in the subscription acknowledgment.
  • A publish message can be sent or received by either the client or the broker.
  • Publish messages can be flagged for retention on the broker.
  • A QoS level 2 requires two round-trips to complete the delivery exchange confirmation.
  • Strings are UTF-8 encoded.

See http://mqtt.org/documentation for additional MQTT documentation.


Chapter 2:  Building wolfMQTT


wolfMQTT was written with portability in mind, and should generally be easy to build on most systems. If you have difficulty building, please don’t hesitate to seek support through our support forums (http://www.wolfssl.com/forums) or contact us directly at support@wolfssl.com.

This chapter explains how to build wolfMQTT on Unix and Windows, and provides guidance for building in a non-standard environment.  You will find a getting started guide and example client in Chapter 3.

When using the autoconf / automake system to build, wolfMQTT uses a single Makefile to build all parts and examples of the library, which is both simpler and faster than using Makefiles recursively.

If using the TLS features or the Firmware/Azure IoT Hub examples you’ll need to have wolfSSL installed. For wolfSSL and wolfMQTT we recommend using config options ./configure --enable-ecc --enable-supportedcurves --enable-base64encode. For wolfSSL use make && sudo make install. If you get an error locating the libwolfssl.so run sudo ldconfig from the wolfSSL directory.

2.1 Getting the Source Code


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

https://github.com/wolfSSL/wolfMQTT

Either click the “Download ZIP” button or use the command:

git clone https://github.com/wolfSSL/wolfMQTT.git

2.2 Building on *nix


When building on Linux, *BSD, OS X, Solaris, or other *nix-like systems, use the autoconf system. If cloned from github run the following three commands:

./autogen.sh

./configure
make

Otherwise, just run these two commands:

./configure
make

You can append any number of build options to ./configure.  For a list of available build options run:

./configure --help

From the command line to see a list of possible options to pass to the ./configure script.  

To build wolfMQTT, run:

make

To install wolfMQTT run:

make install

 

You may need superuser privileges to install, in which case precede the command with sudo:

sudo make install

 

To test the build, run the mqttclient program from the root wolfMQTT source directory:

./examples/mqttclient/mqttclient

If you want to build only the wolfMQTT library and not the additional items (examples), you can run the following command from the wolfMQTT root directory:

make src/libwolfmqtt.la

2.3 Building on Windows


 

Visual Studio 2015:

  1. Open the wolfssl-root>/wolfssl64.sln.
  2. Re-target for your Visual Studio version (right-click on solution and choose “Retarget solution”).
  3. Make sure the Debug DLL or Release DLL configuration is selected. Make note if you are building 32-bit x86 or 64-bit x64.
  4. Build the wolfSSL solution.
  5. Copy the wolfssl.lib and wolfssl.dll files into <wolfmqtt-root>.
  • For DLL Debug with x86 the files are in: DLL Debug.
  • For DLL Release with x86 the files are in: DLL Release.
  • For DLL Debug with x64 the files are in: x64/DLL Debug.
  • For DLL Release with x64 the files are in: x64/DLL Release.
  1. Open the <wolfmqtt-root>/wolfmqtt.sln solution.
  2. Make sure you have the same architecture (x86 or x64 selected) as used in wolfSSL above.
  3. By default the include path for the wolfssl headers is ./../wolfssl/. If your wolfssl root location is different you can go into the project settings and adjust this in C/C++ -> General -> Additional Include Directories.
  4. Build the wolfMQTT solution.

The wolfmqtt.sln solution is included for Visual Studio 2015 in the root directory of the install.

To test each build, choose “Build All” from the Visual Studio menu and then run the mqttclient program.  To edit build options in the Visual Studio project, select your desired project (wolfmqtt, mqttclient) and browse to the “Properties” panel.

For instructions on building the required wolfssl.dll see https://www.wolfssl.com/wolfSSL/Docs-wolfssl-visual-studio.html. When done copy the wolfssl.dll and wolfssl.lib into the wolfMQTT root. The project also assumes the wolfSSL headers are located ../wolfssl/.

Cygwin:  If using Cygwin, or other toolsets for Windows that provides *nix-like commands and functionality, please follow the instructions in Section 2.2, above, for “Building on *nix”.  If building wolfMQTT for Windows on a Windows development machine, we recommend using the included Visual Studio project files to build wolfMQTT.

2.4 Building on Other Systems


Arduino:  See README.md at wolfMQTT/IDE/ARDUINO/

Microchip Harmony:  See README.md at wolfMQTT/IDE/Microchip-Harmony/

2.5 Building in a non-standard environment


While not officially supported, we try to help users wishing to build wolfMQTT in a non-standard environment, particularly with embedded and cross-compilation systems. Below are some notes on getting started with this.

 

  1. The source and header files need to remain in the same directory structure as they are in the wolfMQTT download package.

  1. Some build systems will want to explicitly know where the wolfMQTT header files are located, so you may need to specify that.  They are located in the <wolfmqtt_root>/wolfmqtt directory.  Typically, you can add the <wolfmqtt_root> directory to your include path to resolve header problems.

  1. wolfMQTT defaults to a little endian system unless the configure process detects big endian.  Since users building in a non-standard environment aren't using the configure process, BIG_ENDIAN_ORDER will need to be defined if using a big endian system.

  1. Try to build the library, and let us know if you run into any problems. If you need help, contact us at support@wolfssl.com.

2.6 Cross Compiling


Many users on embedded platforms cross compile for their environment.  The easiest way to cross compile the library is to use the ./configure system.  It will generate a Makefile which can then be used to build wolfMQTT.

When cross compiling, you’ll need to specify the host to ./configure, such as:

./configure --host=arm-linux

You may also need to specify the compiler, linker, etc. that you want to use:

./configure --host=arm-linux CC=arm-linux-gcc AR=arm-linux-ar RANLIB=arm-linux

After correctly configuring wolfMQTT for cross-compilation, you should be able to follow standard autoconf practices for building and installing the library:

make
sudo make install

If you have any additional tips or feedback about cross compiling wolfMQTT, please let us know at info@wolfssl.com.

2.7 Install to Custom Directory


To setup a custom install directory for wolfSSL use the following:

In wolfSSL:

./configure --prefix=~/wolfssl
make
make install

This will place the libs in ~/wolfssl/lib and includes in ~/wolfssl/include

To setup a custom install directory for wolfMQTT and specify custom wolfSSL lib/include directories use the following:

In wolfMQTT:

./configure --prefix=~/wolfmqtt --libdir=~/wolfssl/lib  \ --includedir=~/wolfssl/include
make
make install

Make sure the paths above match your actual location.


Chapter 3 : Getting Started


Here are the steps for creating your own implementation:

  1. Create network callback functions for Connect, Read, Write and Disconnect. See examples/mqttnet.c and examples/mqttnet.h for reference implementation.
  2. Define the network callback functions and context in a MqttNet structure.
  3. Call MqttClient_Init passing in a MqttClient structure pointer, MqttNet structure pointer, MqttMsgCb function callback pointer, TX/RX buffers with maximum length and command timeout.
  4. Call MqttClient_NetConnect to connect to broker over network. If use_tls is non-zero value then it will perform a TLS connection. The TLS callback MqttTlsCb should be defined for WolfSSL certificate configuration.
  5. Call MqttClient_Connect passing pointer to MqttConnect structure to send MQTT connect command and wait for Connect Ack.
  6. Call MqttClient_Subscribe passing pointer to MqttSubscribe structure to send MQTT Subscribe command and wait for Subscribe Ack (depending on QoS level).
  7. Call MqttClient_WaitMessage passing pointer to MqttMessage to wait for incoming MQTT Publish message.

3.1 Client Example


The example MQTT client is located in /examples/mqttclient/. This example exercises all exposed API’s and prints any incoming publish messages for subscription topic: wolfMQTT/example/testTopic.

Usage

./examples/mqttclient/mqttclient -?

mqttclient:
-?                 Help, print this usage
-h <host>        Host to connect to, default iot.eclipse.org
-p <num>        Port to connect on, default: Normal 1883, TLS 8883
-t                 Enable TLS
-c <file>        Use provided certificate file
-q <num>        Qos Level 0-2, default 0
-s                 Disable clean session connect flag
-k <num>        Keep alive seconds, default 60
-i <id>        Client Id, default WolfMQTTClient
-l                 Enable LWT (Last Will and Testament)
-u <str>        Username
-w <str>        Password
-n <str>        Topic name, default wolfMQTT/example/testTopic
-r                Set Retain flag on publish message
-C <num>        Command Timeout, default 30000ms
-T                Test mode

Output (no TLS):

./examples/mqttclient/mqttclient

MQTT Client: QoS 0
MQTT Net Init: Success (0)
MQTT Init: Success (0)
MQTT Socket Connect: Success (0)
MQTT Connect: Success (0)
MQTT Connect Ack: Return Code 0, Session Present 0
MQTT Subscribe: Success (0)
 Topic wolfMQTT/example/testTopic, Qos 0, Return Code 0
MQTT Publish: Topic wolfMQTT/example/testTopic, Success (0)
MQTT Waiting for message...
MQTT Message: Topic wolfMQTT/example/testTopic, Qos 0, Len 4
Payload (0 - 4): test
MQTT Message: Done
asdf
MQTT Publish: Topic wolfMQTT/example/testTopic, Success (0)
MQTT Message: Topic wolfMQTT/example/testTopic, Qos 0, Len 1
Payload (0 - 1): asdf
MQTT Message: Done
^CReceived SIGINT
MQTT Unsubscribe: Success (0)
MQTT Disconnect: Success (0)
MQTT Socket Disconnect: Success (0)

Output (with TLS - peer has self signed cert)

./examples/mqttclient/mqttclient -t


MQTT Client: QoS 0
MQTT Net Init: Success (0)
MQTT Init: Success (0)
MQTT TLS Setup (1)
MQTT TLS Verify Callback:
 PreVerify 0, Error -188 (ASN no signer error to confirm failure)
 Subject's domain name is iot.eclipse.org
 Allowing cert anyways
MQTT Socket Connect: Success (0)
MQTT Connect: Success (0)
MQTT Connect Ack: Return Code 0, Session Present 0
MQTT Subscribe: Success (0)
 Topic wolfMQTT/example/testTopic, Qos 0, Return Code 0
MQTT Publish: Topic wolfMQTT/example/testTopic, Success (0)
MQTT Waiting for message...
MQTT Message: Topic wolfMQTT/example/testTopic, Qos 0, Len 4
Payload (0 - 4): test
MQTT Message: Done
asdf
MQTT Publish: Topic wolfMQTT/example/testTopic, Success (0)
MQTT Message: Topic wolfMQTT/example/testTopic, Qos 0, Len 1
Payload (0 - 1):  asdf
MQTT Message: Done
^CReceived SIGINT
MQTT Unsubscribe: Success (0)
MQTT Disconnect: Success (0)
MQTT Socket Disconnect: Success (0)

3.2 Firmware Update Example


The MQTT firmware update  is located in /examples/firmware/. This example has two parts. The first is called fwpush, which publishes a signed firmware image. The second is called fwclient, which receives the firmware image and verifies the signature. This example publishes message on the topic wolfMQTT/example/firmware.

Usage

./examples/firmware/fwpush -?
fwpush:
-?                Help, print this usage
-h <host>        Host to connect to, default iot.eclipse.org
-p <num>        Port to connect on, default: Normal 1883, TLS 8883
-t                Enable TLS
-c <file>        Use provided certificate file
-q <num>         Qos Level 0-2, default 0
-s                Disable clean session connect flag
-k <num>        Keep alive seconds, default 60
-i <id>                Client Id, default WolfMQTTFwPush
-l                Enable LWT (Last Will and Testament)
-u <str>        Username
-w <str>        Password
-n <str>        Topic name, default wolfMQTT/example/firmware
-r                Set Retain flag on firmware publish message
-C <num>        Command Timeout, default 30000ms
-T                Test mode
-f <file>   Use file for publish, default README.md

fwpush output:

./examples/firmware/fwpush -t -f README.md
MQTT Firmware Push Client: QoS 2
Firmware Message: Sig 74 bytes, Key 65 bytes, File 4271 bytes
MQTT Net Init: Success (0)
MQTT Init: Success (0)
MQTT TLS Setup (1)
MQTT TLS Verify Callback: PreVerify 0,
 Error -188 (ASN no signer error to confirm failure)
 Subject's domain name is iot.eclipse.org
 Allowing cert anyways
MQTT Socket Connect: Success (0)
MQTT Connect: Success (0)
MQTT Connect Ack: Return Code 0, Session Present 0
MQTT Publish: Topic wolfMQTT/example/firmware, Success (0)
MQTT Disconnect: Success (0)
MQTT Socket Disconnect: Success (0)
MQTT Net DeInit: Success (0)

fwclient output:

./examples/firmware/fwclient -t -f README.md
MQTT Firmware Client: QoS 2
MQTT Net Init: Success (0)
MQTT Init: Success (0)
MQTT TLS Setup (1)
MQTT TLS Verify Callback: PreVerify 0,
 Error -188 (ASN no signer error to confirm failure)
 Subject's domain name is iot.eclipse.org
 Allowing cert anyways
MQTT Socket Connect: Success (0)
MQTT Connect: Success (0)
MQTT Connect Ack: Return Code 0, Session Present 0
MQTT Subscribe: Success (0)
 Topic wolfMQTT/example/firmware, Qos 2, Return Code 2
MQTT Waiting for message...
MQTT Firmware Message: Qos 2, Len 4415
Firmware Signature Verification: Pass (0)
Saved 4271 bytes to README.md

^CReceived SIGINT
MqttSocket_NetRead: Error 0
MQTT Message Wait: Error (Network) (-8)
MQTT Disconnect: Success (0)
MQTT Socket Disconnect: Success (0)
MQTT Net DeInit: Success (0)

3.3 Azure IoT Hub Example


We setup a wolfMQTT IoT Hub on the Azure server for testing. We added a device called demoDevice, which you can connect and publish to. The example demonstrates creation of a SasToken, which is used as the password for the MQTT connect packet. It also shows the topic names for publishing events and listening to devicebound messages. This example only works with ENABLE_MQTT_TLS set and the wolfSSL library present because it requires Base64 Encode/Decode and HMAC-SHA256.

Note: The wolfSSL library must be built with ./configure --enable-base64encode or #define WOLFSSL_BASE64_ENCODE. The wc_GetTime API was added in 3.9.1 and if not present you'll need to implement your own version of this to get current UTC seconds or update your wolfSSL library.

Usage

./examples/azure/azureiothub -?
azureiothub:
-?                Help, print this usage
-h <host>        Host to connect to, default wolfMQTT.azure-devices.net
-p <num>        Port to connect on, default: Normal 1883, TLS 8883
-t                Enable TLS
-c <file>        Use provided certificate file
-q <num>        Qos Level 0-2, default 1
-s                Disable clean session connect flag
-k <num>        Keep alive seconds, default 60
-i <id>                Client Id, default demoDevice
-l                Enable LWT (Last Will and Testament)
-u <str>        Username
-w <str>        Password
-n <str>        Topic name, default devices/demoDevice/messages/devicebound/#
-r                Set Retain flag on publish message
-C <num>        Command Timeout, default 30000ms
-T                Test mode

azureiothub output:

./examples/azure/azureiothub
AzureIoTHub Client: QoS 1, Use TLS 1
MQTT Net Init: Success (0)
SharedAccessSignature sr=wolfMQTT.azure-devices.net%2fdevices%2fdemoDevice&sig=iy8al9ZPBLLZdMT38SIGy8Qx7k5jY%2f5nTpBo8Mw84PA%3d&se=1482274308
MQTT Init: Success (0)
MQTT TLS Setup (1)
MQTT TLS Verify Callback: PreVerify 0, Error -188 (ASN no signer error to confirm failure)
 Subject's domain name is *.azure-devices.net
 Allowing cert anyways
MQTT Socket Connect: Success (0)
MQTT Connect: Success (0)
MQTT Connect Ack: Return Code 0, Session Present 0
MQTT Subscribe: Success (0)
 Topic devices/demoDevice/messages/devicebound/#, Qos 1, Return Code 1
MQTT Publish: Topic devices/demoDevice/messages/events/, Success (0)
MQTT Waiting for message...
^CReceived SIGINT
MQTT Exiting...
MQTT Disconnect: Success (0)
MQTT Socket Disconnect: Success (0)

3.4 AWS IoT Example


We setup an AWS IoT endpoint and testing device certificate for testing. The AWS server uses TLS client certificate for authentication. The example is located in /examples/aws/. The example subscribes to $aws/things/"AWSIOT_DEVICE_ID"/shadow/update/delta and publishes to $aws/things/"AWSIOT_DEVICE_ID"/shadow/update. The AWS IoT broker requires TLS and only supports QoS levels 0-1.

Usage

./examples/aws/awsiot -?
awsiot:
-?                Help, print this usage
-h <host>        Host to connect to, default a2dujmi05ideo2.iot.us-west-2.amazonaws.com
-p <num>        Port to connect on, default: Normal 1883, TLS 8883
-t                Enable TLS
-c <file>        Use provided certificate file
-q <num>        Qos Level 0-2, default 1
-s                Disable clean session connect flag
-k <num>        Keep alive seconds, default 60
-i <id>                Client Id, default demoDevice
-l                Enable LWT (Last Will and Testament)
-u <str>        Username
-w <str>        Password
-n <str>        Topic name, default $aws/things/demoDevice/shadow/update/delta
-r                Set Retain flag on publish message
-C <num>        Command Timeout, default 30000ms
-T                Test mode

awsiot output:

./examples/aws/awsiot
AwsIoT Client: QoS 1, Use TLS 1
MQTT Net Init: Success (0)
MQTT Init: Success (0)
MQTT TLS Setup (1)
MQTT Socket Connect: Success (0)
MQTT Connect: Success (0)
MQTT Connect Ack: Return Code 0, Session Present 0
MQTT Subscribe: Success (0)
 Topic $aws/things/demoDevice/shadow/update/delta, Qos 1, Return Code 1
MQTT Publish: Topic $aws/things/demoDevice/shadow/update, Success (0)
MQTT Waiting for message...

^CReceived SIGINT
MQTT Exiting...
MQTT Disconnect: Success (0)
MQTT Socket Disconnect: Success (0)


3.4 Watson IoT Example


This example enables the wolfMQTT client to connect to the IBM Watson Internet of Things (WIOT) Platform. The WIOT Platform has a limited test broker called "Quickstart" that allows non-secure connections to exercise the component.

Usage

./examples/wiot/wiot

awsiot output:

./examples/wiot/wiot

MQTT Client: QoS 0, Use TLS 0

MQTT Net Init: Success (0)

MQTT Init: Success (0)

MQTT Socket Connect: Success (0)

MQTT Connect: Success (0)

MQTT Connect Ack: Return Code 0, Session Present 0

To view the published sample data visit:

https://quickstart.internetofthings.ibmcloud.com/#/device/wolftestid/sensor/

MQTT Subscribe: Success (0)

  Topic iot-2/type/wolfMQTT/id/wolftestid/evt/sensor/fmt/json, Qos 0, Return Code 0

MQTT Publish: Topic iot-2/type/wolfMQTT/id/wolftestid/evt/sensor/fmt/json, Success (0)

MQTT Waiting for message...

MQTT Message: Topic iot-2/type/wolfMQTT/id/wolftestid/evt/sensor/fmt/json, Qos 0, Len 12

Payload (0 - 12): {"sensor":1}

MQTT Message: Done

^CReceived SIGINT

Disconnect (error -8)

MQTT Exiting...

MQTT Unsubscribe: Success (0)

MQTT Disconnect: Success (0)

MQTT Socket Disconnect: Success (0)

Chapter 4: 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:

1. mqtt_client

This is where the top level application interfaces for the MQTT client reside. If the API performs a network write it will block on a network read if an acknowledgment is expected.

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 MqttNet.read 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);

For additional information see Chapter 5 for API reference

2. mqtt_packet

This is where all the packet encoding/decoding is handled. This contains the MQTT Packet structures for:

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

3. mqtt_socket

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.

4.1 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.

Chapter 5: API Reference


This describes the public application interfaces for the wolfMQTT library.

5.1 MqttPacketResponseCodes (enum)


These are the API response codes:

MQTT_CODE_SUCCESS = 0:   Success

MQTT_CODE_ERROR_BAD_ARG = -1:   Invalid argument provided

MQTT_CODE_ERROR_OUT_OF_BUFFER = -2:   Rx or Tx buffer out of space

MQTT_CODE_ERROR_MALFORMED_DATA = -3:   Malformed packet remaining length

MQTT_CODE_ERROR_PACKET_TYPE = -4:   Invalid packet type in header

MQTT_CODE_ERROR_PACKET_ID = -5:   Packet Id mismatch

MQTT_CODE_ERROR_TLS_CONNECT = -6:   TLS connect error.

MQTT_CODE_ERROR_TIMEOUT = -7:   Net read/write/connect timeout

MQTT_CODE_ERROR_NETWORK = -8:   Network error

MQTT_CODE_ERROR_MEMORY = -9:   Memory error

MQTT_CODE_ERROR_STAT = -10:   State error

MQTT_CODE_CONTINUE = -101:   Non-blocking mode, perform IO and call again.

MQTT_CODE_STDIN_WAKE = -102:  Normal blocking mode only, used in the examples to accept input from the terminal

5.2 MqttClient_Init


Synopsis:

#include <wolfmqtt/mqtt_client.h>

typedef int (*MqttMsgCb)(struct _MqttClient *client, MqttMessage *message, byte msg_new, byte msg_done);

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);

Description:

Initializes the wolfMQTT library for use.  Must be called once per application and before any other calls to the library.

Return Values:

MQTT_CODE_SUCCESS - Success

MQTT_CODE_ERROR_BAD_ARG - Invalid argument provided

MQTT_CODE_ERROR_* - (See enum MqttPacketResponseCodes)

Parameters:

client - Pointer to MqttClient structure (okay if not initialized).

net - Pointer to MqttNet structure populated with network callbacks and context.

msg_cb - Pointer to MqttMsgCb callback function.

tx_buf - Pointer to transmit buffer used during encoding.

tx_buf_len  - Maximum length of the transmit buffer.

rx_buf - Pointer to receive buffer used during decoding.

rx_buf_len  - Maximum length of the receive buffer.

connect_timeout_ms  - Maximum command wait timeout in milliseconds.

Example:

#define MAX_BUFFER_SIZE         1024
#define DEFAULT_CMD_TIMEOUT_MS  1000

static int mqttclient_message_cb(MqttClient *client, MqttMessage *msg, byte msg_new, byte msg_done)
{
   
if (msg_new) {
       
/* Message new */
   }
   
if (msg_done) {
       
/* Message done */
   }

   return MQTT_CODE_SUCCESS;
   
/* Return negative to terminate publish processing */
}

int rc = 0;
MqttClient client;
MqttNet net;
byte *tx_buf = NULL, *rx_buf = NULL;

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);
if (rc != MQTT_CODE_SUCCESS) {
   printf(
"MQTT Init: %s (%d)\n", MqttClient_ReturnCodeToString(rc), rc);
}

See Also:

None

5.3 MqttClient_Connect


Synopsis:

#include <wolfmqtt/mqtt_client.h>

int MqttClient_Connect(

MqttClient *client,

MqttConnect *connect);

Description:

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 unless non-blocking is enabled (WOLFMQTT_NONBLOCK) and MQTT_CODE_CONTINUE is returned.

Return Values:

MQTT_CODE_SUCCESS - Success

MQTT_CODE_CONTINUE - Non-blocking mode, perform IO and call again.

MQTT_CODE_ERROR_* - (See enum MqttPacketResponseCodes)

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.

connect - Pointer to MqttConnect structure initialized with connection parameters.

Example:

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.buffer = (
byte*)DEFAULT_CLIENT_ID;
lwt_msg.buffer_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);
}

See Also:

MqttClient_Init

MqttClient_Disconnect

5.4 MqttClient_Publish


Synopsis:

#include <wolfmqtt/mqtt_client.h>

int MqttClient_Publish(

MqttClient *client,

MqttPublish *publish);

Description:

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 unless non-blocking is enabled (WOLFMQTT_NONBLOCK) and MQTT_CODE_CONTINUE is returned.

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:

MQTT_CODE_SUCCESS - success

MQTT_CODE_CONTINUE - Non-blocking mode, perform IO and call again.

MQTT_CODE_ERROR_* - (See enum MqttPacketResponseCodes)

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:

#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.buffer = (
byte*)TEST_MESSAGE;
publish.buffer_len = strlen(TEST_MESSAGE);
rc = MqttClient_Publish(&client, &publish);
if (rc != MQTT_CODE_SUCCESS) {
   printf(
"MQTT Publish: %s (%d)\n", MqttClient_ReturnCodeToString(rc), rc);
}

See Also:

MqttClient_Init

MqttClient_Subscribe

5.5 MqttClient_Subscribe


Synopsis:

#include <wolfmqtt/mqtt_client.h>

int MqttClient_Subscribe(

MqttClient *client,

MqttSubscribe *subscribe);

Description:

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 unless non-blocking is enabled (WOLFMQTT_NONBLOCK) and MQTT_CODE_CONTINUE is returned.

Return Values:

MQTT_CODE_SUCCESS - Success

MQTT_CODE_CONTINUE - Non-blocking mode, perform IO and call again.

MQTT_CODE_ERROR_* - (See enum MqttPacketResponseCodes)

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:

#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);
}

See Also:

MqttClient_Init

MqttClient_Unsubscribe

5.6 MqttClient_Unsubscribe


Synopsis:

#include <wolfmqtt/mqtt_client.h>

int MqttClient_Unsubscribe(

MqttClient *client,

MqttUnsubscribe *unsubscribe);

Description:

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 unless non-blocking is enabled (WOLFMQTT_NONBLOCK) and MQTT_CODE_CONTINUE is returned.

Return Values:

MQTT_CODE_SUCCESS - Success

MQTT_CODE_CONTINUE - Non-blocking mode, perform IO and call again.

MQTT_CODE_ERROR_* - (See enum MqttPacketResponseCodes)

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.

unsubscribe - Pointer to MqttUnsubscribe structure initialized with topic list.

Example:

#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);
}

See Also:

MqttClient_Init

MqttClient_Subscribe

5.7 MqttClient_Ping


Synopsis:

#include <wolfmqtt/mqtt_client.h>

int MqttClient_Ping(

MqttClient *client);

Description:

Encodes and sends the MQTT Ping Request packet and waits for the Ping Response packet. This is a blocking function that will wait for MqttNet.read unless non-blocking is enabled (WOLFMQTT_NONBLOCK) and MQTT_CODE_CONTINUE is returned.

Return Values:

MQTT_CODE_SUCCESS - Success

MQTT_CODE_CONTINUE - Non-blocking mode, perform IO and call again.

MQTT_CODE_ERROR_* - (See enum MqttPacketResponseCodes)

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.

Example:

/* Send Ping */
int rc = MqttClient_Ping(&client);
if (rc != MQTT_CODE_SUCCESS) {
   printf(
"MQTT Ping: %s (%d)\n", MqttClient_ReturnCodeToString(rc), rc);
}

See Also:

MqttClient_Init

5.8 MqttClient_Disconnect


Synopsis:

#include <wolfmqtt/mqtt_client.h>

int MqttClient_Disconnect(

MqttClient *client);

Description:

Encodes and sends the MQTT Disconnect packet (no response). This is a non-blocking function that will try and send using MqttNet.write.

Return Values:

MQTT_CODE_SUCCESS - Success

MQTT_CODE_CONTINUE - Non-blocking mode, perform IO and call again.

MQTT_CODE_ERROR_* - (See enum MqttPacketResponseCodes)

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.

Example:

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

See Also:

MqttClient_Init

MqttClient_Connect

5.9 MqttClient_WaitMessage


Synopsis:

#include <wolfmqtt/mqtt_client.h>

int MqttClient_WaitMessage(

MqttClient *client,

int timeout_ms);

Description:

Waits for Publish packets to arrive. Incoming publish messages will arrive via callback provided in MqttClient_Init. This is a blocking function that will wait for MqttNet.read unless non-blocking is enabled (WOLFMQTT_NONBLOCK) and MQTT_CODE_CONTINUE is returned. If a timeout_ms is provided it will be passed up to MqttNet.read which can be used for network select() with timeout or if non-blocking is enabled can return MQTT_CODE_CONTINUE.

Return Values:

MQTT_CODE_SUCCESS - Success

MQTT_CODE_CONTINUE - Non-blocking mode, perform IO and call again.

MQTT_CODE_ERROR_* - (See enum MqttPacketResponseCodes)

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.

timeout_ms - Milliseconds until read timeout.

Example:

#define DEFAULT_CMD_TIMEOUT_MS  1000

int rc = 0;
MqttMessage msg;

/* Read Loop */
while (mStopRead == 0) {
/* Try and read packet */
rc = MqttClient_WaitMessage(&client, &msg, DEFAULT_CMD_TIMEOUT_MS);
if (rc >= 0) {
/* Print incoming message */
printf(
"MQTT Message: Topic %s, Len %u\n", msg.topic_name, msg.buffer_len);
}
else if (rc != MQTT_CODE_ERROR_TIMEOUT) {
/* There was an error */
printf(
"MQTT Message Wait: %s (%d)\n", MqttClient_ReturnCodeToString(rc), rc);
break;
}
}

See Also:

MqttClient_Init

MqttClient_Publish

5.10 MqttClient_NetConnect


Synopsis:

#include <wolfmqtt/mqtt_client.h>

typedef int (*MqttTlsCb)(struct _MqttClient* client);

int MqttClient_NetConnect(

MqttClient *client,

const char *host,

word16 port,

int timeout_ms,

int use_tls,

MqttTlsCb cb);

Description:

Performs network connect with TLS (if use_tls is non-zero value). Will perform the MqttTlsCb callback if use_tls is non-zero value.

Return Values:

MQTT_CODE_SUCCESS - Success

MQTT_CODE_CONTINUE - Non-blocking mode, perform IO and call again.

MQTT_CODE_ERROR_* - (See enum MqttPacketResponseCodes)

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.

host - Address of the broker server

port - Optional custom port. If zero will use defaults (1883=normal, 8883=TLS)

use_tls - If non-zero value will connect with and use TLS for encryption of data.

cb - A function callback for configuration of the SSL context certificate checking.

Example:

#define DEFAULT_CON_TIMEOUT_MS  5000
#define DEFAULT_MQTT_HOST       "iot.eclipse.org"

word16 port = 0;
const char* host = DEFAULT_MQTT_HOST;

static int mqttclient_tls_cb(MqttClient* client)
{
   (
void)client; /* Supress un-used argument */
   
return SSL_SUCCESS;
}

/* Connect to broker */
int rc = MqttClient_NetConnect(&client, host, port, DEFAULT_CON_TIMEOUT_MS,
use_tls, mqttclient_tls_cb);
if (rc != MQTT_CODE_SUCCESS) {
   printf(
"MQTT Net Connect: %s (%d)\n", MqttClient_ReturnCodeToString(rc), rc);
}

See Also:

MqttClient_NetDisconnect

5.11 MqttClient_NetDisconnect


Synopsis:

#include <wolfmqtt/mqtt_client.h>

int MqttClient_NetDisconnect(

MqttClient *client);

Description:

Performs a network disconnect.

Return Values:

MQTT_CODE_SUCCESS - Success

MQTT_CODE_CONTINUE - Non-blocking mode, perform IO and call again.

MQTT_CODE_ERROR_* - (See enum MqttPacketResponseCodes)

Parameters:

client - Pointer to MqttClient structure already initialized using MqttClient_Init.

Example:

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

See Also:

MqttClient_NetConnect

5.12 MqttClient_ReturnCodeToString


Synopsis:

#include <wolfmqtt/mqtt_client.h>

const char* MqttClient_ReturnCodeToString(

int return_code);

Description:

Performs lookup of a WOLFMQTT_API return values.

Return Values:

String representation of the return code.

Parameters:

return_code - The return value from a WOLFMQTT_API function.

Example:

printf("Return: %s (%d)\n", MqttClient_ReturnCodeToString(rc), rc);

See Also:

None

5.13 MqttClient_SetDisconnectCallback


Synopsis

#include <wolfmqtt/mqtt_client.h>

int MqttClient_SetDisconnectCallback(

        MqttClient *client,

        MqttDisconnectCb cb,

        void* ctx);

Description:

Sets a disconnect callback with custom context.

Return Values:

MQTT_CODE_SUCCESS - Success

MQTT_CODE_ERROR_* - (See enum MqttPacketResponseCodes)

Parameters:

client - Pointer to MqttClient structure (uninitialized is okay)

cb - Pointer to disconnect callback function

ctx - Pointer to your own context

Example:

#ifdef WOLFMQTT_DISCONNECT_CB
static int mqtt_disconnect_cb(MqttClient* client, int error_code, void* ctx)
{
    (
void)client;
    (
void)ctx;
    PRINTF(
"Disconnect (error %d)", error_code);
   
return 0;
}
#endif

#ifdef WOLFMQTT_DISCONNECT_CB
/* setup disconnect callback */
rc = MqttClient_SetDisconnectCallback(&mqttCtx->client, mqtt_disconnect_cb, NULL);
if (rc != MQTT_CODE_SUCCESS) {
   
goto exit;
}
#endif

See also:

None 

Copyright 2018 wolfSSL Inc.  All rights reserved.