The latest development version of this page may be more current than this released 0.4.2 version.

MQTT Client

MQTT Client Programming Model

The MQTT Client programming model for W800 is shown below:

MQTT Client program can be seen as a black box that is unaware of the upper-layer code (such as the TCP/IP protocol stack, application tasks, event tasks, etc.). The application task is responsible for calling the MQTT Client program API to implement MQTT Client initialization, triggering events in the MQTT Client, and the application uses the triggered events to perform the next API call.

MQTT Client Overview

MQTT Client is an implementation of the MQTT protocol client. MQTT is a lightweight messaging protocol based on the publish/subscribe model.

MQTT Client Features

Supports MQTT implementation based on TCP, SSL, Websocket, and Websocket Secure.

Supports subscription, publishing, will, keep-alive, and three service quality (QoS) levels.

Simplifies the configuration process through URI.。

MQTT Client Initialization

Before using the MQTT Client connection, initialization must be performed. Call the wm_mqtt_client_init() function to complete the initialization configuration of the wm_mqtt_client_config_t structure and generate a handle for starting the MQTT Client.
Use the wm_mqtt_client_deinit() function to destroy the client handle.

Initialization Configuration

Initialize the wm_mqtt_client_config_t structure with the following configuration:

Field	Description
uri	Uniform Resource Locator
client_id	Client ID
username	Username
password	Password
will_topic	Will topic
will_msg	Will message
will_qos	Will message service quality
will_retain	Message retain flag
keep_alive	Keep-alive period
clean_session	Clean session
debug	Debug print
auth_mode	Connection authentication mode

Connection Authentication Mode

WM_MQTT_CLIENT_AUTH_MODE_NOT_CERT	No certificate
WM_MQTT_CLIENT_AUTH_MODE_AUTH_SERVER_CERT	Validate server certificate
WM_MQTT_CLIENT_AUTH_MODE_PROVIDE_CLIENT_CERT	Provide client certificate
WM_MQTT_CLIENT_AUTH_MODE_MUTUAL_AUTH	Mutual authentication

Message Service Quality

QoS 0 (At most once)

Messages are delivered according to the best efforts of the operating environment. Message loss can occur.

QoS 1 (At least once)

Guarantees that the message is delivered at least once to the receiver. There might be duplicates.

QoS 2 (Only deliver once)

Every delivery of QoS 2 messages requires at least two request/response processes between the sender and receiver. Solved the issue of potentially duplicate QoS 1 messages.

Connection Address

MQTT connection addresses usually contain: server IP or domain name, server port, and connection protocol.

TCP-based MQTT Connection

mqtt is a standard TCP connection, usually on port 1883.
mqtts is a secure connection based on TLS/SSL, usually on port 8883.

Example:  mqtt://broker.emqx.io:1883 is a TCP-based MQTT connection address.

WebSocket-based Connection

ws is a standard WebSocket connection, usually on port 8083.
wss is a secure WebSocket connection, usually on port 8084.

Example: ws://broker.emqx.io:8083 is a WebSocket-based MQTT connection address.

MQTT Client Connection

Call the wm_mqtt_client_connect() function, passing the initialized handle as a function parameter to complete the MQTT Client connection.
Call the wm_mqtt_client_disconnect() function to disconnect the MQTT Client.

MQTT Client Subscription

Hint

The client must be connected before subscribing.

Call the wm_mqtt_client_subscribe() function to subscribe to a topic. The function parameters are as follows:

Parameter	Description
handle	The handle generated during client initialization
topic	The topic to subscribe to
qos	The message service quality

Call the wm_mqtt_client_unsubcribe() function to unsubscribe from a topic. The function parameters are the same as above.

MQTT Client Publishing

Call the wm_mqtt_client_publish() function to publish a message to the MQTT broker. The function parameters are as follows:

Parameter	Description
handle	The handle generated during client initialization
topic	The topic to publish to
message	The message string to publish
msg_len	The length of the message
qos	The message service quality
retain	Message retain flag

Events

MQTT Client may publish the following events:

Event	Description
WM_EVENT_MQTT_CLIENT_CONNECTED	Client successfully connected to the server
WM_EVENT_MQTT_CLIENT_DISCONNECTED	Client disconnected from the server
WM_EVENT_MQTT_CLIENT_DATA	Client received a published message
WM_EVENT_MQTT_CLIENT_PUBLISHED	Server received the client’s published message

Error Codes

MQTT Client error codes are numerous. Here are some explanations:

Error Code	Description
WM_MQTT_CLIENT_ERROR_SUCCESS	Indicates no error, successfully completed the operation.
WM_MQTT_CLIENT_ERROR_FAILURE	Indicates an operation failure.
WM_MQTT_CLIENT_ERROR_PERSISTENCE_ERROR	Indicates an application-specific persistence error.
WM_MQTT_CLIENT_ERROR_DISCONNECTED	Indicates the client is not connected.
WM_MQTT_CLIENT_ERROR_MAX_MESSAGES_INFLIGHT	Indicates the maximum number of in-flight messages has been reached.
WM_MQTT_CLIENT_ERROR_BAD_UTF8_STRING	Indicates an invalid `UTF-8` was detected.
WM_MQTT_CLIENT_ERROR_NULL_PARAMETER	Indicates a null parameter was passed.
WM_MQTT_CLIENT_ERROR_TOPICNAME_TRUNCATED	Indicates the topic name was truncated due to an embedded NULL character.
WM_MQTT_CLIENT_ERROR_BAD_STRUCTURE	Indicates an incorrect parameter structure.
WM_MQTT_CLIENT_ERROR_BAD_QOS	Indicates the QoS value is out of the specified range (0, 1, 2`)
WM_MQTT_CLIENT_ERROR_SSL_NOT_SUPPORTED	Indicates an attempt to use an SSL connection with a non-SSL library.
WM_MQTT_CLIENT_ERROR_BAD_MQTT_VERSION	Indicates an unrecognized MQTT version.
WM_MQTT_CLIENT_ERROR_BAD_PROTOCOL	Indicates an incorrect access protocol prefix( mqtt 、 mqtt 、 ws 、 wss )
WM_MQTT_CLIENT_ERROR_BAD_MQTT_OPTION	Indicates an MQTT option is not applicable for the requested version.
WM_MQTT_CLIENT_ERROR_WRONG_MQTT_VERSION	Indicates an operation not applicable for the requested version.
WM_MQTT_CLIENT_ERROR_0_LEN_WILL_TOPIC	Indicates a WILL topic string length of 0.