MQTT Client Library Encyclopedia – wolfMQTT

Guest post by David Garske

wolfMQTT
LanguageC
LicenseGPL v2
Websitehttps://wolfssl.com/wolfSSL/Products-wolfmqtt.html
API StyleBlocking

Description

The wolfMQTT library is a client implementation of the MQTT 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 is based on the MQTT v3.1.1 specification.

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

MQTT 3.1nok
MQTT 3.1.1ok
LWTok
SSL/TLSok
Automatic Reconnectnok
QoS 0ok
QoS 1ok
QoS 2ok
Authenticationok
Throttlingnok
Additional Features
  • Built from scratch by wolfSSL engineers
  • Based on MQTT v3.1.1 specification
  • 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)
  • 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)

Usage

Installation

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:

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

For additional help see the wolfMQTT User Manual:

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:

Connect with LWT

See Connect example above.

Connect with Username / Password

See Connect example above.

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:

Publish a retained message

See publish example. Set publish.retain = 1.

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:
See 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:

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:
See 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:

Disconnect

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:

Using SSL / TLS

Full example application

Author Information

David Garske
David Garske works for wolfSSL and has been in IoT embedded software development for over 8 years. 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.
  Website

Leave a Reply

Your email address will not be published. Required fields are marked *