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

Data Structures
struct	MQTTClient_OperationMetaDataCB

struct	MQTTClient_RecvMetaDataCB

struct	MQTTClient_ConnParams

struct	MQTTClient_Params

struct	MQTTClient_SubscribeParams

struct	MQTTClient_UnsubscribeParams

struct	MQTTClient_Will

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

Typedefs
typedef struct MQTTClient_OperationMetaDataCB	MQTTClient_OperationMetaDataCB

typedef struct MQTTClient_RecvMetaDataCB	MQTTClient_RecvMetaDataCB

typedef struct MQTTClient_ConnParams	MQTTClient_ConnParams

typedef struct MQTTClient_Params	MQTTClient_Params

typedef void(*	MQTTClient_CallBack) (int32_t event, void metaData, uint32_t metaDateLen, void data, uint32_t dataLen)

typedef void *	MQTTClient_Handle

typedef struct MQTTClient_SubscribeParams	MQTTClient_SubscribeParams

typedef struct MQTTClient_UnsubscribeParams	MQTTClient_UnsubscribeParams

typedef struct MQTTClient_Will	MQTTClient_Will

Enumerations
enum	MQTTClient_Option { MQTTClient_USER_NAME = 0, MQTTClient_PASSWORD = 1, MQTTClient_WILL_PARAM = 2, MQTTClient_CALLBACKS = 3, MQTTClient_KEEPALIVE_TIME = 4, MQTTClient_CLEAN_CONNECT = 5, MQTTClient_MAX_PARAM = 6 }

enum	MQTTClient_EventCB { MQTTClient_RECV_CB_EVENT = 0, MQTTClient_OPERATION_CB_EVENT = 1, MQTTClient_DISCONNECT_CB_EVENT = 2 }

Functions
MQTTClient_Handle	MQTTClient_create (MQTTClient_CallBack defaultCallback, MQTTClient_Params *params)
	Create an MQTTClient instance. More...

int16_t	MQTTClient_delete (MQTTClient_Handle handle)
	Delete an MQTTClient instance. More...

int16_t	MQTTClient_run (MQTTClient_Handle handle)
	MQTTClient state machine. More...

int16_t	MQTTClient_connect (MQTTClient_Handle handle)
	Connect to a broker. More...

int16_t	MQTTClient_disconnect (MQTTClient_Handle handle)
	Disconnect from a broker. More...

int16_t	MQTTClient_publish (MQTTClient_Handle handle, char topic, uint16_t topicLen, char msg, uint16_t msgLen, uint32_t flags)
	Publish a named message to the broker. More...

int16_t	MQTTClient_subscribe (MQTTClient_Handle handle, MQTTClient_SubscribeParams *value, uint8_t numberOfTopics)
	Subscribe to a set of topics. More...

int16_t	MQTTClient_unsubscribe (MQTTClient_Handle handle, MQTTClient_UnsubscribeParams *value, uint8_t numberOfTopics)
	Unsubscribe from a set of topics. More...

int16_t	MQTTClient_set (MQTTClient_Handle handle, uint16_t option, void *value, uint16_t valueLength)
	Set client parameters. More...

int16_t	MQTTClient_get (MQTTClient_Handle handle, uint16_t option, void *value, uint16_t valueLength)
	Get client parameters. More...

Detailed Description

The 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

In addition to providing services to the application, each MQTTClient instance 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 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 MQTTClient 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 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

Typedef Documentation

§ MQTTClient_OperationMetaDataCB

typedef struct MQTTClient_OperationMetaDataCB MQTTClient_OperationMetaDataCB

§ MQTTClient_RecvMetaDataCB

typedef struct MQTTClient_RecvMetaDataCB MQTTClient_RecvMetaDataCB

§ MQTTClient_ConnParams

typedef struct MQTTClient_ConnParams MQTTClient_ConnParams

Secure Socket Parameters to open a secure connection

§ MQTTClient_Params

typedef struct MQTTClient_Params MQTTClient_Params

§ MQTTClient_CallBack

typedef void(* MQTTClient_CallBack) (int32_t event, void *metaData, uint32_t metaDateLen, void *data, uint32_t dataLen)

§ MQTTClient_Handle

typedef void* MQTTClient_Handle

§ MQTTClient_SubscribeParams

typedef struct MQTTClient_SubscribeParams MQTTClient_SubscribeParams

§ MQTTClient_UnsubscribeParams

typedef struct MQTTClient_UnsubscribeParams MQTTClient_UnsubscribeParams

§ MQTTClient_Will

typedef struct MQTTClient_Will MQTTClient_Will

Enumeration Type Documentation

§ MQTTClient_Option

enum MQTTClient_Option

Enumerator
MQTTClient_USER_NAME
MQTTClient_PASSWORD
MQTTClient_WILL_PARAM
MQTTClient_CALLBACKS
MQTTClient_KEEPALIVE_TIME
MQTTClient_CLEAN_CONNECT
MQTTClient_MAX_PARAM

§ MQTTClient_EventCB

enum MQTTClient_EventCB

Enumerator
MQTTClient_RECV_CB_EVENT
MQTTClient_OPERATION_CB_EVENT
MQTTClient_DISCONNECT_CB_EVENT

Function Documentation

§ MQTTClient_create()

MQTTClient_Handle MQTTClient_create	(	MQTTClient_CallBack	defaultCallback,
		MQTTClient_Params *	params
	)

Create an MQTTClient instance.

Parameters

[in]	defaultCallback	async event handler
[in]	params	parameters

Returns: Success Handle or Failure NULL

See also: MQTTClient_delete()

§ MQTTClient_delete()

int16_t MQTTClient_delete ( MQTTClient_Handle handle )

Delete an MQTTClient instance.

Parameters

[in] handle handle to the MQTTClient instance

Remarks: If the MQTTClient instance has an existing connection, it is dropped.

Returns: Success (0) or Failure (-1)

See also: MQTTClient_create()

§ MQTTClient_run()

int16_t MQTTClient_run ( MQTTClient_Handle handle )

MQTTClient state machine.

This function need to be called from the context created by the user in case of OS environment.

Parameters

[in] handle handle to the MQTTClient instance

Returns: Success (0) or Failure (Negative number)

§ MQTTClient_connect()

int16_t MQTTClient_connect ( MQTTClient_Handle handle )

Connect to a broker.

Parameters

[in] handle handle to the MQTTClient instance

Returns: Success (0) or Failure (Negative number)

§ MQTTClient_disconnect()

int16_t MQTTClient_disconnect ( MQTTClient_Handle handle )

Disconnect from a broker.

Parameters

[in] handle handle to the MQTTClient instance

Returns: Success (0) or Failure (Negative number)

§ MQTTClient_publish()

int16_t MQTTClient_publish	(	MQTTClient_Handle	handle,
		char *	topic,
		uint16_t	topicLen,
		char *	msg,
		uint16_t	msgLen,
		uint32_t	flags
	)

Publish a named message to the broker.

In addition to the PUBLISH specific parameters, the caller can indicate whether the routine should block until the time, the message has been acknowledged by the server. This is applicable only for non-QoS0 messages.

In case, the app has chosen not to await for the ACK from the server, the MQTT implementation will notify the app about the subscription through the callback routine.

Parameters

[in]	handle	handle to the MQTTClient instance
[in]	topic	topic of the data to be published. It is NULL terminated.
[in]	topicLen	topic length.
[in]	msg	binary data to be published
[in]	msgLen	length of the msg
[in]	flags	QOS define MQTT_PUBLISH_QOS_0, MQTT_PUBLISH_QOS_1 or MQTT_PUBLISH_QOS_2 use MQTT_PUBLISH_RETAIN is message should be retained

Returns: Success(transaction Message ID) or Failure(Negative number)

§ MQTTClient_subscribe()

int16_t MQTTClient_subscribe	(	MQTTClient_Handle	handle,
		MQTTClient_SubscribeParams *	value,
		uint8_t	numberOfTopics
	)

Subscribe to a set of topics.

To receive data about a set of topics from the server, the app through this routine must subscribe to those topic names with the server. The caller can indicate whether the routine should block until a time, the message has been acknowledged by the server.

In case, the app has chosen not to await for the ACK from the server, the MQTT implementation will notify the app about the subscription through the callback routine.

Parameters

[in]	handle	handle to the MQTTClient instance
[in]	value	a pointer to a struct of subscribe parameters which hold: Topic name to subscribe. It is a pointer to NULL terminated strings. Qos value for the topic. persistent session flag in order to enable or disable persistent session. callback function which is optional - if NULL use the default callback
[in]	numberOfTopics	number of such topics

Returns: Success(transaction Message ID) or Failure(Negative number)

§ MQTTClient_unsubscribe()

int16_t MQTTClient_unsubscribe	(	MQTTClient_Handle	handle,
		MQTTClient_UnsubscribeParams *	value,
		uint8_t	numberOfTopics
	)

Unsubscribe from a set of topics.

The app should use this service to stop receiving data for the named topics from the server.

Parameters

[in]	handle	handle to the MQTTClient instance
[in]	value	topics set of topics to be unsubscribed. It is an array of pointers to NULL terminated strings.
[in]	numberOfTopics	count number of topics to be unsubscribed

Returns: Success(transaction Message ID) or Failure(Negative number)

§ MQTTClient_set()

int16_t MQTTClient_set	(	MQTTClient_Handle	handle,
		uint16_t	option,
		void *	value,
		uint16_t	valueLength
	)

Set client parameters.

This function can set different parameters to the client. Will message params, user name and password, keep alive time and clean/persistent session.

Parameters

[in]	handle	handle to the MQTTClient instance
[in]	option	Define the actual option to set. Applicable values: MQTTClient_USER_NAME MQTTClient_PASSWORD MQTTClient_WILL_PARAM MQTTClient_KEEPALIVE_TIME MQTTClient_CLEAN_CONNECT
[in]	value	Specifies a value for the option
[in]	valueLength	Specifies the length of the value

Returns: Success(0) or Failure(Negative number)

See also: MQTTClient_Will

§ MQTTClient_get()

int16_t MQTTClient_get	(	MQTTClient_Handle	handle,
		uint16_t	option,
		void *	value,
		uint16_t	valueLength
	)

Get client parameters.

This function can get different parameters from the client. Will message params, user name and password, keep alive time and clean/persistent session.

Parameters

[in]	handle	handle to the MQTTClient instance
[in]	option	Define the actual option to set. Applicable values: MQTTClient_USER_NAME MQTTClient_PASSWORD MQTTClient_WILL_PARAM MQTTClient_KEEPALIVE_TIME MQTTClient_CLEAN_CONNECT
[in]	value	Specifies a value for the option
[in]	valueLength	Specifies the length of the value

Returns: Success(0) or Failure(Negative number)

See also: MQTTClient_Will

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Description

Configuration

Typical Sequences:

Library Usage

Macro Definition Documentation

§ MQTTCLIENT_ERR_NETWORK

§ MQTTCLIENT_ERR_TIMEOUT

§ MQTTCLIENT_ERR_NET_OPS

§ MQTTCLIENT_ERR_FNPARAM

§ MQTTCLIENT_ERR_PKT_AVL

§ MQTTCLIENT_ERR_PKT_LEN

§ MQTTCLIENT_ERR_NOTCONN

§ MQTTCLIENT_ERR_BADCALL

§ MQTTCLIENT_ERR_CONTENT

§ MQTTCLIENT_ERR_LIBQUIT

§ MQTTCLIENT_ERR_REMLSTN

§ MQTTCLIENT_OPERATION_CONNACK

§ MQTTCLIENT_OPERATION_EVT_PUBACK

§ MQTTCLIENT_OPERATION_PUBCOMP

§ MQTTCLIENT_OPERATION_SUBACK

§ MQTTCLIENT_OPERATION_UNSUBACK

§ MQTTCLIENT_NETCONN_IP4

§ MQTTCLIENT_NETCONN_IP6

§ MQTTCLIENT_NETCONN_URL

§ MQTTCLIENT_NETCONN_SEC

§ MQTTCLIENT_NETCONN_SKIP_DOMAIN_NAME_VERIFICATION

§ MQTTCLIENT_NETCONN_SKIP_CERTIFICATE_CATALOG_VERIFICATION

§ MQTTCLIENT_NETCONN_SKIP_DATE_VERIFICATION

Typedef Documentation

§ MQTTClient_OperationMetaDataCB

§ MQTTClient_RecvMetaDataCB

§ MQTTClient_ConnParams

§ MQTTClient_Params

§ MQTTClient_CallBack

§ MQTTClient_Handle

§ MQTTClient_SubscribeParams

§ MQTTClient_UnsubscribeParams

§ MQTTClient_Will

Enumeration Type Documentation

§ MQTTClient_Option

§ MQTTClient_EventCB

Function Documentation

§ MQTTClient_create()

§ MQTTClient_delete()

§ MQTTClient_run()

§ MQTTClient_connect()

§ MQTTClient_disconnect()

§ MQTTClient_publish()

§ MQTTClient_subscribe()

§ MQTTClient_unsubscribe()

§ MQTTClient_set()

§ MQTTClient_get()