MQTT Client Implementation on the Nordic nRF platforms. More...

Data Structures
struct	mqtt_utf8_t
	Abstracts UTF-8 encoded strings. More...

struct	mqtt_binstr_t
	Abstracts binary strings. More...

struct	mqtt_topic_t
	Abstracts MQTT UTF-8 encoded topic that can be subscribed to or published. More...

struct	mqtt_publish_message_t
	Parameters for a publish message. More...

struct	mqtt_connack_param_t
	Parameters for a connection acknowledgment (connack). More...

struct	mqtt_puback_param_t
	Parameters for MQTT publish acknowledgment(puback). More...

struct	mqtt_pubrec_param_t
	Parameters for MQTT publish receive(pubrec). More...

struct	mqtt_pubrel_param_t
	Parameters for MQTT publish release(pubrec). More...

struct	mqtt_pubcomp_param_t
	Parameters for MQTT publish complete(pubcomp). More...

struct	mqtt_suback_param_t
	Parameters for MQTT subscription acknowledgment (suback). More...

struct	mqtt_unsuback_param_t
	Parameters for MQTT unsubscription acknowledgment (unsuback). More...

struct	mqtt_publish_param_t
	Parameters for a publish message. More...

struct	mqtt_subscription_list_t
	List of topics in a subscription request. More...

union	mqtt_evt_param_t
	Defines event parameters notified along with asynchronous events to the application. Currently, only MQTT_EVT_PUBLISH is accompanied with parameters. More...

struct	mqtt_evt_t
	Defined MQTT asynchronous event notified to the application. More...

struct	mqtt_client_t
	MQTT Client definition to maintain information relevant to the client. More...

Typedefs
typedef struct mqtt_client_t	mqtt_client_t
	MQTT client forward declaration mqtt_client_t for details.

typedef mqtt_utf8_t	mqtt_client_id_t
	Abstracts MQTT UTF-8 encoded unique client identifier.

typedef mqtt_utf8_t	mqtt_password_t
	Abstracts MQTT UTF-8 encoded password to be used for the client connection.

typedef mqtt_utf8_t	mqtt_username_t
	Abstracts MQTT UTF-8 encoded user name to be used for the client connection.

typedef mqtt_utf8_t	mqtt_will_message_t
	Abstracts will message used in mqtt_connect request. More...

typedef mqtt_binstr_t	mqtt_message_t
	Abstracts message in binary encoded string received or published on a topic.

typedef void(*	mqtt_evt_cb_t )(mqtt_client_t const p_client, const mqtt_evt_t p_evt)
	Asynchronous event notification callback registered by the application with the module to receive module events. More...

Enumerations
enum	mqtt_evt_id_t { MQTT_EVT_CONNACK, MQTT_EVT_DISCONNECT, MQTT_EVT_PUBLISH, MQTT_EVT_PUBACK, MQTT_EVT_PUBREC, MQTT_EVT_PUBREL, MQTT_EVT_PUBCOMP, MQTT_EVT_SUBACK, MQTT_EVT_UNSUBACK }
	MQTT Asynchronous Events notified to the application from the module through the callback registered by the application. More...

enum	mqtt_version_t { MQTT_VERSION_3_1_0 = 3, MQTT_VERSION_3_1_1 = 4 }
	MQTT version protocol level. More...

enum	mqtt_transport_type_t { MQTT_TRANSPORT_NON_SECURE = 0x00, MQTT_TRANSPORT_SECURE = 0x01, MQTT_TRANSPORT_MAX = 0x02 }
	MQTT transport type. More...

enum	mqtt_qos_t { MQTT_QoS_0_AT_MOST_ONCE = 0x00, MQTT_QoS_1_ATLEAST_ONCE = 0x01, MQTT_QoS_2_EACTLY_ONCE = 0x02 }
	MQTT Quality of Service types. More...

enum	mqtt_conn_return_code_t { MQTT_CONNECTION_ACCEPTED = 0x00, MQTT_UNACCEPTABLE_PROTOCOL_VERSION = 0x01, MQTT_IDENTIFIER_REJECTED = 0x02, MQTT_SERVER_UNAVAILABLE = 0x03, MQTT_BAD_USER_NAME_OR_PASSWORD = 0x04, MQTT_NOT_AUTHORIZED = 0x05 }
	MQTT Asynchronous Events notified to the application from the module through the callback registered by the application. More...

Functions
uint32_t	mqtt_init (void)
	Initializes the module. More...

void	mqtt_client_init (mqtt_client_t *const p_client)
	Initializes the client instance. More...

uint32_t	mqtt_connect (mqtt_client_t *const p_client)
	API to request new MQTT client connection. More...

uint32_t	mqtt_publish (mqtt_client_t const p_client, mqtt_publish_param_t const const p_param)
	API to publish messages on topics. More...

uint32_t	mqtt_publish_ack (mqtt_client_t const p_client, mqtt_puback_param_t const const p_param)
	API used by subscribing client to send acknowledgment to the broker. Applicable only to QoS 1 publish messages. More...

uint32_t	mqtt_publish_receive (mqtt_client_t const p_client, mqtt_pubrec_param_t const const p_param)
	API to send assured acknowledgment from a subscribing client to the broker. Should be called on reception of MQTT_EVT_PUBLISH with QoS set to MQTT_QoS_2_EACTLY_ONCE. More...

uint32_t	mqtt_publish_release (mqtt_client_t const p_client, mqtt_pubrel_param_t const const p_param)
	API to used by publishing client to request releasing published data. Shall be used only after MQTT_EVT_PUBREC is received and is valid only for QoS level MQTT_QoS_2_EACTLY_ONCE. More...

uint32_t	mqtt_publish_complete (mqtt_client_t const p_client, mqtt_pubcomp_param_t const const p_param)
	API used by subscribing clients to acknowledge reception of a released message. Should be used on reception MQTT_EVT_PUBREL event. More...

uint32_t	mqtt_subscribe (mqtt_client_t const p_client, mqtt_subscription_list_t const const p_param)
	API to request subscribing to a topic on the connection. More...

uint32_t	mqtt_unsubscribe (mqtt_client_t const p_client, mqtt_subscription_list_t const const p_param)
	API to request un-subscribe from a topic on the connection. More...

uint32_t	mqtt_abort (mqtt_client_t *const p_client)
	API to abort MQTT connection. More...

uint32_t	mqtt_disconnect (mqtt_client_t *const p_client)
	API to disconnect MQTT connection. More...

uint32_t	mqtt_live (void)
	This API should be called periodically for the module to be able to keep the connection alive by sending Ping Requests if need be. More...

uint32_t	mqtt_input (mqtt_client_t *const p_client, uint32_t timeout)
	Wait for an incoming MQTT packet. The registered callback will be called with the packet payload. More...

Detailed Description

MQTT Client Implementation on the Nordic nRF platforms.

MQTT Client's Application interface is defined in this header.

Note: The implementation assumes LwIP Stack is available with TCP module enabled.; By default the implementation uses MQTT version 3.1.0. However few cloud services like the Xively use the version 3.1.1. For this please set p_client.protocol_version = MQTT_VERSION_3_1_1.

Typedef Documentation

typedef void(* mqtt_evt_cb_t)(mqtt_client_t *const p_client, const mqtt_evt_t *p_evt)

Asynchronous event notification callback registered by the application with the module to receive module events.

Parameters

[in]	p_client	Identifies the client for which the event is notified.
[in]	p_evet	Event description along with result and associated parameters (if any).

typedef mqtt_utf8_t mqtt_will_message_t

Abstracts will message used in mqtt_connect request.

Note: utf8 is used here instead of binary string as a zero length encoding is expected in will message is empty.

Enumeration Type Documentation

enum mqtt_conn_return_code_t

MQTT Asynchronous Events notified to the application from the module through the callback registered by the application.

Enumerator
MQTT_CONNECTION_ACCEPTED	Connection accepted.
MQTT_UNACCEPTABLE_PROTOCOL_VERSION	The Server does not support the level of the MQTT protocol requested by the Client.
MQTT_IDENTIFIER_REJECTED	The Client identifier is correct UTF-8 but not allowed by the Server.
MQTT_SERVER_UNAVAILABLE	The Network Connection has been made but the MQTT service is unavailable.
MQTT_BAD_USER_NAME_OR_PASSWORD	The data in the user name or password is malformed.
MQTT_NOT_AUTHORIZED	The Client is not authorized to connect.

enum mqtt_evt_id_t

MQTT Asynchronous Events notified to the application from the module through the callback registered by the application.

Enumerator
MQTT_EVT_CONNACK	Acknowledgment of connection request. Event result accompanying the event indicates whether the connection failed or succeeded.
MQTT_EVT_DISCONNECT	Disconnection Event. MQTT Client Reference is no longer valid once this event is received for the client.
MQTT_EVT_PUBLISH	Publish event received when message is published on a topic client is subscribed to.
MQTT_EVT_PUBACK	Acknowledgment for published message with QoS 1.
MQTT_EVT_PUBREC	Reception confirmation for published message with QoS 2.
MQTT_EVT_PUBREL	Release of published published messages with QoS 2.
MQTT_EVT_PUBCOMP	Confirmation to a publish release message. Applicable only to QoS 2 messages.
MQTT_EVT_SUBACK	Acknowledgment to a subscription request.
MQTT_EVT_UNSUBACK	Acknowledgment to a unsubscription request.

enum mqtt_qos_t

MQTT Quality of Service types.

Enumerator
MQTT_QoS_0_AT_MOST_ONCE	Lowest Quality of Service, no acknowledgment needed for published message.
MQTT_QoS_1_ATLEAST_ONCE	Medium Quality of Service, if acknowledgment expected for published message, duplicate messages permitted.
MQTT_QoS_2_EACTLY_ONCE	Highest Quality of Service, acknowledgment expected and message shall be published only once. Message not published to interested parties unless client issues a PUBREL.

enum mqtt_transport_type_t

MQTT transport type.

Enumerator
MQTT_TRANSPORT_NON_SECURE	Use non secure TCP transport for MQTT connection.
MQTT_TRANSPORT_SECURE	Use secure TCP transport (TLS) for MQTT connection.
MQTT_TRANSPORT_MAX	Shall not be used as a transport type. Indicator of maximum transport types possible.

enum mqtt_version_t

MQTT version protocol level.

Enumerator
MQTT_VERSION_3_1_0	Protocol level for 3.1.0.
MQTT_VERSION_3_1_1	Protocol level for 3.1.1.

Function Documentation

uint32_t mqtt_abort ( mqtt_client_t *const p_client )

API to abort MQTT connection.

Parameters

[in] p_client Identifies client instance for which procedure is requested.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

void mqtt_client_init ( mqtt_client_t *const p_client )

Initializes the client instance.

Parameters

[in] p_client Client instance for which the procedure is requested. Shall not be NULL.

Note: Shall be called before connecting the client in order to avoid unexpected behavior caused by uninitialized parameters.

uint32_t mqtt_connect ( mqtt_client_t *const p_client )

API to request new MQTT client connection.

Parameters

[out] p_client Client instance for which the procedure is requested. Shall not be NULL.

Note: This memory is assumed to be resident until mqtt_disconnect is called.; Any subsequent changes to parameters like broker address, user name, device id, etc. have no effect once MQTT connection is established.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

Note: Default protocol revision used for connection request is 3.1.0. Please set p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.; If more than one simultaneous client connections are needed, please define MQTT_MAX_CLIENTS to override default of 1.; Please define MQTT_KEEPALIVE time to override default of 1 minute.; Please define MQTT_MAX_PACKET_LENGTH time to override default of 128 bytes. Ensure the system has enough memory for the new length per client.

uint32_t mqtt_disconnect ( mqtt_client_t *const p_client )

API to disconnect MQTT connection.

Parameters

[in] p_client Identifies client instance for which procedure is requested.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

uint32_t mqtt_init ( void )

Initializes the module.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

Note: Shall be called before initiating any procedures on the module.; If module initialization fails, no module APIs shall be called.

uint32_t mqtt_input	(	mqtt_client_t *const	p_client,
		uint32_t	timeout
	)

Wait for an incoming MQTT packet. The registered callback will be called with the packet payload.

Parameters

[in]	p_client	Client instance for which the procedure is requested. Shall not be NULL.
[in]	timeout	Maximum interval (in milliseconds) to wait for a packet. If timeout is 0, the interval is indefinitely.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

Note: This API is only supported when using the socket transport layer.

uint32_t mqtt_live ( void )

This API should be called periodically for the module to be able to keep the connection alive by sending Ping Requests if need be.

Note: Application shall ensure that the periodicity of calling this function makes it possible to respect the Keep Alive time agreed with the broker on connection. mqtt_connect for details on Keep Alive time.

Return values

NRF_SUCCESS or an result code indicating reason for failure.

uint32_t mqtt_publish	(	mqtt_client_t *const	p_client,
		mqtt_publish_param_t const *const	p_param
	)

API to publish messages on topics.

Parameters

[in]	p_client	Client instance for which the procedure is requested. Shall not be NULL.
[in]	p_param	Parameters to be used for the publish message. Shall not be NULL.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

Note: Default protocol revision used for connection request is 3.1.0. Please set p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.

uint32_t mqtt_publish_ack	(	mqtt_client_t *const	p_client,
		mqtt_puback_param_t const *const	p_param
	)

API used by subscribing client to send acknowledgment to the broker. Applicable only to QoS 1 publish messages.

Parameters

[in]	p_client	Client instance for which the procedure is requested. Shall not be NULL.
[in]	p_param	Identifies message being acknowledged.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

Note: Default protocol revision used for connection request is 3.1.0. Please set p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.

uint32_t mqtt_publish_complete	(	mqtt_client_t *const	p_client,
		mqtt_pubcomp_param_t const *const	p_param
	)

API used by subscribing clients to acknowledge reception of a released message. Should be used on reception MQTT_EVT_PUBREL event.

Parameters

[in]	p_client	Identifies client instance for which the procedure is requested. Shall not be NULL.
[in]	p_param	Identifies message being completed.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

Note: Default protocol revision used for connection request is 3.1.0. Please set p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.

uint32_t mqtt_publish_receive	(	mqtt_client_t *const	p_client,
		mqtt_pubrec_param_t const *const	p_param
	)

API to send assured acknowledgment from a subscribing client to the broker. Should be called on reception of MQTT_EVT_PUBLISH with QoS set to MQTT_QoS_2_EACTLY_ONCE.

Parameters

[in]	p_client	Identifies client instance for which the procedure is requested. Shall not be NULL.
[in]	p_param	Identifies message being acknowledged.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

Note: Default protocol revision used for connection request is 3.1.0. Please set p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.

uint32_t mqtt_publish_release	(	mqtt_client_t *const	p_client,
		mqtt_pubrel_param_t const *const	p_param
	)

API to used by publishing client to request releasing published data. Shall be used only after MQTT_EVT_PUBREC is received and is valid only for QoS level MQTT_QoS_2_EACTLY_ONCE.

Parameters

[in]	p_client	Client instance for which the procedure is requested. Shall not be NULL.
[in]	p_param	Identifies message being released.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

Note: Default protocol revision used for connection request is 3.1.0. Please set p_client.protocol_version = MQTT_VERSION_3_1_1 to use protocol 3.1.1.

uint32_t mqtt_subscribe	(	mqtt_client_t *const	p_client,
		mqtt_subscription_list_t const *const	p_param
	)

API to request subscribing to a topic on the connection.

Parameters

[in]	p_client	Identifies client instance for which the procedure is requested. Shall not be NULL.
[in]	p_param	Subscription parameters. Shall not be NULL.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

uint32_t mqtt_unsubscribe	(	mqtt_client_t *const	p_client,
		mqtt_subscription_list_t const *const	p_param
	)

API to request un-subscribe from a topic on the connection.

Parameters

[in]	p_client	Identifies client instance for which the procedure is requested. Shall not be NULL.
[in]	p_param	Parameters describing topics being unsubscribed from. Shall not be NULL.

Note: QoS included in topic description is unused in this API.

Return values

NRF_SUCCESS or an error code indicating reason for failure.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation