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_publish_param_t

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 username 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_CONNECT, MQTT_EVT_DISCONNECT, MQTT_EVT_PUBLISH, MQTT_EVT_PUBLISH_ACK, MQTT_EVT_PUBLISH_REC, MQTT_EVT_PUBLISH_REL, MQTT_EVT_PUBLISH_COMP, MQTT_EVT_SUBSCRIBE_ACK, MQTT_EVT_UNSUBSCRIBE_ACK }
	MQTT Asynchronous Events notified to the application from the module through the callback registered by the application. More...

enum	mqtt_transport_type_t { MQTT_TRANSPORT_NON_SECURE = 0x00, MQTT_TRANSPORT_SECURE = 0x01, MQTT_TRASNPORT_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...

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, uint16_t message_id)
	API used by subscribing client to send acknowledgement to the broker. Applicable only to QoS 1 publish messages. More...

uint32_t	mqtt_publish_receive (mqtt_client_t *const p_client, uint16_t message_id)
	API to send assured acknowledgement 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, uint16_t message_id)
	API to used by publishing client to request releasing published data. Shall be used only after MQTT_EVT_PUBLISH_REC 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, uint16_t message_id)
	API used by subscribing clients to acknowledge reception of a released message. Should be used on reception MQTT_EVT_PUBLISH_REL 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...

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 define MQTT_3_1_1 and recompile the example.

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_evt_id_t

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

Enumerator
MQTT_EVT_CONNECT	Connection Event. 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_PUBLISH_ACK	Acknowledgement for published message with QoS 1.
MQTT_EVT_PUBLISH_REC	Reception confirmation for published message with QoS 2.
MQTT_EVT_PUBLISH_REL	Release of published published messages with QoS 2.
MQTT_EVT_PUBLISH_COMP	Confirmation to a publish release message. Applicable only to QoS 2 messages.
MQTT_EVT_SUBSCRIBE_ACK	Acknowledgement to a subscription request.
MQTT_EVT_UNSUBSCRIBE_ACK	Acknowledgement 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 acknowledgement needed for published message.
MQTT_QoS_1_ATLEAST_ONCE	Medium Quality of Service, if acknowledgement expected for published message, duplicate messages permitted.
MQTT_QoS_2_EACTLY_ONCE	Highest Quality of Service, acknowledgement 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_TRASNPORT_MAX	Shall not be used as a transport type. Indicator of maximum transport types possible.

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 behaviour caused by unitialized 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 define MQTT_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_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 define MQTT_3_1_1 to use protocol 3.1.1.

uint32_t mqtt_publish_ack	(	mqtt_client_t *const	p_client,
		uint16_t	message_id
	)

API used by subscribing client to send acknowledgement 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]	message_id	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 define MQTT_3_1_1 to use protocol 3.1.1.

uint32_t mqtt_publish_complete	(	mqtt_client_t *const	p_client,
		uint16_t	message_id
	)

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

Parameters

[in]	p_client	Identifies client instance for which the procedure is requested. Shall not be NULL.
[in]	message_id	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 define MQTT_3_1_1 to use protocol 3.1.1.

uint32_t mqtt_publish_receive	(	mqtt_client_t *const	p_client,
		uint16_t	message_id
	)

API to send assured acknowledgement 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]	message_id	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 define MQTT_3_1_1 to use protocol 3.1.1.

uint32_t mqtt_publish_release	(	mqtt_client_t *const	p_client,
		uint16_t	message_id
	)

API to used by publishing client to request releasing published data. Shall be used only after MQTT_EVT_PUBLISH_REC 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]	message_id	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 define MQTT_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