MQTT Client on nRF5x

nRF5 SDK v14.1.0
Data Structures | Typedefs | Enumerations | Functions

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.