MQTT Client Implementation on the Nordic nRF platforms.
More...
|
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...
|
|
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.
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). |
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.
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.
|
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.
|
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.
|
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.
|
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.
|
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. |
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.
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.
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. |
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.
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.
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.
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.
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.
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. |
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. |