The SimpleLink MQTTClient Module provides an easy-to-use API to enable constrained and deeply embedded micro-controller based products to interact with cloud or network based MQTT servers. The users of MQTTClient services, while benefiting from the abstraction of the MQTT protocol, will find them suitable for varied deployments of MQTT subscribers and/or publishers. More...

Macros
#define	MQTTCLIENT_ERR_NETWORK MQTT_PACKET_ERR_NETWORK

#define	MQTTCLIENT_ERR_TIMEOUT MQTT_PACKET_ERR_TIMEOUT

#define	MQTTCLIENT_ERR_NET_OPS MQTT_PACKET_ERR_NET_OPS

#define	MQTTCLIENT_ERR_FNPARAM MQTT_PACKET_ERR_FNPARAM

#define	MQTTCLIENT_ERR_PKT_AVL MQTT_PACKET_ERR_PKT_AVL

#define	MQTTCLIENT_ERR_PKT_LEN MQTT_PACKET_ERR_PKT_LEN

#define	MQTTCLIENT_ERR_NOTCONN MQTT_PACKET_ERR_NOTCONN

#define	MQTTCLIENT_ERR_BADCALL MQTT_PACKET_ERR_BADCALL

#define	MQTTCLIENT_ERR_CONTENT MQTT_PACKET_ERR_CONTENT

#define	MQTTCLIENT_ERR_LIBQUIT MQTT_PACKET_ERR_LIBQUIT

#define	MQTTCLIENT_ERR_REMLSTN MQTT_PACKET_ERR_REMLSTN

#define	MQTTCLIENT_OPERATION_CONNACK MQTT_CONNACK

#define	MQTTCLIENT_OPERATION_EVT_PUBACK MQTT_PUBACK

#define	MQTTCLIENT_OPERATION_PUBCOMP MQTT_PUBCOMP

#define	MQTTCLIENT_OPERATION_SUBACK MQTT_SUBACK

#define	MQTTCLIENT_OPERATION_UNSUBACK MQTT_UNSUBACK

#define	MQTTCLIENT_NETCONN_IP4 MQTT_DEV_NETCONN_OPT_IP4

#define	MQTTCLIENT_NETCONN_IP6 MQTT_DEV_NETCONN_OPT_IP6

#define	MQTTCLIENT_NETCONN_URL MQTT_DEV_NETCONN_OPT_URL

#define	MQTTCLIENT_NETCONN_SEC MQTT_DEV_NETCONN_OPT_SEC

#define	MQTTCLIENT_NETCONN_SKIP_DOMAIN_NAME_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_DOMAIN_NAME_VERIFICATION

#define	MQTTCLIENT_NETCONN_SKIP_CERTIFICATE_CATALOG_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_CERTIFICATE_CATALOG_VERIFICATION

#define	MQTTCLIENT_NETCONN_SKIP_DATE_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_DATE_VERIFICATION

Detailed Description

The SimpleLink MQTTClient Module provides an easy-to-use API to enable constrained and deeply embedded micro-controller based products to interact with cloud or network based MQTT servers. The users of MQTTClient services, while benefiting from the abstraction of the MQTT protocol, will find them suitable for varied deployments of MQTT subscribers and/or publishers.

Description

The SL MQTT Client Layer, in addition to providing services to the application, encompasses a RTOS task to handle the incoming messages from the server. Such a dedicated context to process the messages from the server facilitates the apps to receive data (i.e. PUBLISH messages) even when they are blocked, whilst awaiting ACK for a previous transaction with the server. The receive task in the SL MQTT Layer can not be disabled anytime, however its system wide priority is configurable and can be set.

Some of the salient features of the SL MQTT Layer are

Easy-to-use, intuitive and small set of MQTT API
App can indicate its choice to await ACK for a message transaction
Supports MQTT 3.1 protocol

Configuration

The SL implementation enables the application developers to configure the following parameters using the compile line flags (-D option)

CFG_SL_CL_MAX_MQP: the count of TX + RX resources in the buffer pool for the library to use.
CFG_SL_CL_BUF_LEN: the length of the TX and RX buffers in the pool.
CFG_SL_CL_STACK: Max stack (bytes) for RX Task executed by SL-MQTT.
CFG_CL_MQTT_CTXS: the max number of simultaneous network connections to one or more servers.

Note
An app that has chosen not to await an ACK from the server for an scheduled transaction can benefit from the availability of control to pursue other activities to make overall progress in the system. However, an attempt to schedule another transaction with the server, while the previous one is still active, will depend on the availability of buffers for transaction.

Typical Sequences:

Publishers: INIT –> CONTEXT_CREATE –> CONNECT –> PUBLISH (TX) –> DISCONNECT –> CONTEXT_DELETE –> EXIT
Subscribers: INIT –> CONTEXT_CREATE –> CONNECT –> SUBSCRIBE –> PUBLISH (RX) –> UNSUBSCRIBE –> DISCONNECT –> CONTEXT_DELETE –> EXIT

Library Usage

To use the MQTTClient APIs, the application should include its header file as follows:

#include <ti/net/mqtt/mqttclient.h>

And, add the following MQTT library to the link line:

.../source/ti/net/mqtt/{toolchain}/{isa}/mqtt_{profile}.a

Macro Definition Documentation

§ MQTTCLIENT_ERR_NETWORK

#define MQTTCLIENT_ERR_NETWORK MQTT_PACKET_ERR_NETWORK

Problem in network (sock err)

§ MQTTCLIENT_ERR_TIMEOUT

#define MQTTCLIENT_ERR_TIMEOUT MQTT_PACKET_ERR_TIMEOUT

Net transaction has timed out

§ MQTTCLIENT_ERR_NET_OPS

#define MQTTCLIENT_ERR_NET_OPS MQTT_PACKET_ERR_NET_OPS

Platform Net Ops un-available

§ MQTTCLIENT_ERR_FNPARAM

#define MQTTCLIENT_ERR_FNPARAM MQTT_PACKET_ERR_FNPARAM

Invalid parameter(s) provided

§ MQTTCLIENT_ERR_PKT_AVL

#define MQTTCLIENT_ERR_PKT_AVL MQTT_PACKET_ERR_PKT_AVL

No pkts are available in pool

§ MQTTCLIENT_ERR_PKT_LEN

#define MQTTCLIENT_ERR_PKT_LEN MQTT_PACKET_ERR_PKT_LEN

Inadequate free buffer in pkt

§ MQTTCLIENT_ERR_NOTCONN

#define MQTTCLIENT_ERR_NOTCONN MQTT_PACKET_ERR_NOTCONN

Lib isn't CONNECTED to server

§ MQTTCLIENT_ERR_BADCALL

#define MQTTCLIENT_ERR_BADCALL MQTT_PACKET_ERR_BADCALL

Irrelevant call for LIB state

§ MQTTCLIENT_ERR_CONTENT

#define MQTTCLIENT_ERR_CONTENT MQTT_PACKET_ERR_CONTENT

MSG / Data content has errors

§ MQTTCLIENT_ERR_LIBQUIT

#define MQTTCLIENT_ERR_LIBQUIT MQTT_PACKET_ERR_LIBQUIT

Needs reboot library has quit

§ MQTTCLIENT_ERR_REMLSTN

#define MQTTCLIENT_ERR_REMLSTN MQTT_PACKET_ERR_REMLSTN

No remote listener for socket

§ MQTTCLIENT_OPERATION_CONNACK

#define MQTTCLIENT_OPERATION_CONNACK MQTT_CONNACK

CONNACK has been received from the server

§ MQTTCLIENT_OPERATION_EVT_PUBACK

#define MQTTCLIENT_OPERATION_EVT_PUBACK MQTT_PUBACK

PUBACK has been received from the server

§ MQTTCLIENT_OPERATION_PUBCOMP

#define MQTTCLIENT_OPERATION_PUBCOMP MQTT_PUBCOMP

PUBCOMP has been received from the server

§ MQTTCLIENT_OPERATION_SUBACK

#define MQTTCLIENT_OPERATION_SUBACK MQTT_SUBACK

SUBACK has been received from the server

§ MQTTCLIENT_OPERATION_UNSUBACK

#define MQTTCLIENT_OPERATION_UNSUBACK MQTT_UNSUBACK

UNSUBACK has been received from the server

§ MQTTCLIENT_NETCONN_IP4

#define MQTTCLIENT_NETCONN_IP4 MQTT_DEV_NETCONN_OPT_IP4

Assert for IPv4 connection

§ MQTTCLIENT_NETCONN_IP6

#define MQTTCLIENT_NETCONN_IP6 MQTT_DEV_NETCONN_OPT_IP6

Assert for IPv6 connection, otherwise IPv4

§ MQTTCLIENT_NETCONN_URL

#define MQTTCLIENT_NETCONN_URL MQTT_DEV_NETCONN_OPT_URL

Server address is an URL and not IP address

§ MQTTCLIENT_NETCONN_SEC

#define MQTTCLIENT_NETCONN_SEC MQTT_DEV_NETCONN_OPT_SEC

Connection to server must be secure (TLS)

§ MQTTCLIENT_NETCONN_SKIP_DOMAIN_NAME_VERIFICATION

#define MQTTCLIENT_NETCONN_SKIP_DOMAIN_NAME_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_DOMAIN_NAME_VERIFICATION

Assert to skip domain name verification

§ MQTTCLIENT_NETCONN_SKIP_CERTIFICATE_CATALOG_VERIFICATION

#define MQTTCLIENT_NETCONN_SKIP_CERTIFICATE_CATALOG_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_CERTIFICATE_CATALOG_VERIFICATION

Assert to skip certificate catalog verification

§ MQTTCLIENT_NETCONN_SKIP_DATE_VERIFICATION

#define MQTTCLIENT_NETCONN_SKIP_DATE_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_DATE_VERIFICATION

Assert to skip date verification

Macros