/**
* Copyright (c) 2015 - 2019, Nordic Semiconductor ASA
*
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification,
* are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice, this
* list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form, except as embedded into a Nordic
* Semiconductor ASA integrated circuit in a product or a software update for
* such product, must reproduce the above copyright notice, this list of
* conditions and the following disclaimer in the documentation and/or other
* materials provided with the distribution.
*
* 3. Neither the name of Nordic Semiconductor ASA nor the names of its
* contributors may be used to endorse or promote products derived from this
* software without specific prior written permission.
*
* 4. This software, with or without modification, must only be used with a
* Nordic Semiconductor ASA integrated circuit.
*
* 5. Any software provided in binary form under this license must not be reverse
* engineered, decompiled, modified and/or disassembled.
*
* THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
* OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
* GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
*/
/** @file mqtt.h
*
* @defgroup iot_sdk_mqtt_api MQTT Client on nRF5x
* @ingroup iot_sdk_mqtt
* @{
* @brief MQTT Client Implementation on the Nordic nRF platforms.
*
* @details
* MQTT Client's Application interface is defined in this header.
*
* @note The implementation assumes LwIP Stack is available with TCP module enabled.
*
* @note 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.
*/
#ifndef MQTT_H_
#define MQTT_H_
#include <stdint.h>
#include "iot_defines.h"
#include "iot_timer.h"
#include "nrf_tls.h"
#ifdef __cplusplus
extern "C" {
#endif
/**@brief MQTT Asynchronous Events notified to the application from the module
* through the callback registered by the application. */
typedef enum
{
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_evt_id_t;
/**@brief MQTT version protocol level. */
typedef enum
{
MQTT_VERSION_3_1_0 = 3, /**< Protocol level for 3.1.0. */
MQTT_VERSION_3_1_1 = 4 /**< Protocol level for 3.1.1. */
} mqtt_version_t;
/**@brief MQTT transport type. */
typedef enum
{
MQTT_TRANSPORT_NON_SECURE = 0x00, /**< Use non secure TCP transport for MQTT connection. */
MQTT_TRANSPORT_SECURE = 0x01, /**< Use secure TCP transport (TLS) for MQTT connection. */
MQTT_TRANSPORT_MAX = 0x02 /**< Shall not be used as a transport type. Indicator of maximum transport types possible. */
} mqtt_transport_type_t;
/**@brief MQTT Quality of Service types. */
typedef enum
{
MQTT_QoS_0_AT_MOST_ONCE = 0x00, /**< Lowest Quality of Service, no acknowledgment needed for published message. */
MQTT_QoS_1_ATLEAST_ONCE = 0x01, /**< Medium Quality of Service, if acknowledgment expected for published message, duplicate messages permitted. */
MQTT_QoS_2_EACTLY_ONCE = 0x02 /**< 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_qos_t;
/**@brief MQTT Asynchronous Events notified to the application from the module
* through the callback registered by the application. */
typedef enum
{
MQTT_CONNECTION_ACCEPTED = 0x00, /**< Connection accepted. */
MQTT_UNACCEPTABLE_PROTOCOL_VERSION = 0x01, /**< The Server does not support the level of the MQTT protocol requested by the Client. */
MQTT_IDENTIFIER_REJECTED = 0x02, /**< The Client identifier is correct UTF-8 but not allowed by the Server. */
MQTT_SERVER_UNAVAILABLE = 0x03, /**< The Network Connection has been made but the MQTT service is unavailable. */
MQTT_BAD_USER_NAME_OR_PASSWORD = 0x04, /**< The data in the user name or password is malformed. */
MQTT_NOT_AUTHORIZED = 0x05 /**< The Client is not authorized to connect. */
} mqtt_conn_return_code_t;
/**@brief MQTT client forward declaration @ref mqtt_client_t for details. */
typedef struct mqtt_client_t mqtt_client_t;
/**@brief Abstracts UTF-8 encoded strings. */
typedef struct
{
uint8_t * p_utf_str; /**< Pointer to UTF-8 string. */
uint32_t utf_strlen; /**< Length of UTF string. */
} mqtt_utf8_t;
/**@brief Abstracts binary strings. */
typedef struct
{
uint8_t * p_bin_str; /**< Pointer to binary stream. */
uint32_t bin_strlen; /**< Length of binary stream. */
} mqtt_binstr_t;
/**@brief Abstracts MQTT UTF-8 encoded topic that can be subscribed to or published. */
typedef struct
{
mqtt_utf8_t topic; /**< Topic on to be published or subscribed to. */
uint8_t qos; /**< Quality of service requested for the subscription. @ref mqtt_qos_t for details. */
} mqtt_topic_t;
/**@brief Abstracts MQTT UTF-8 encoded unique client identifier. */
typedef mqtt_utf8_t mqtt_client_id_t;
/**@brief Abstracts MQTT UTF-8 encoded password to be used for the client connection. */
typedef mqtt_utf8_t mqtt_password_t;
/**@brief Abstracts MQTT UTF-8 encoded user name to be used for the client connection. */
typedef mqtt_utf8_t mqtt_username_t;
/**@brief Abstracts will message used in @ref mqtt_connect request.
*
* @note utf8 is used here instead of binary string as a zero length encoding is expected in
* will message is empty.
*/
typedef mqtt_utf8_t mqtt_will_message_t;
/**@brief Abstracts message in binary encoded string received or published on a topic. */
typedef mqtt_binstr_t mqtt_message_t;
/**@brief Parameters for a publish message. */
typedef struct
{
mqtt_topic_t topic; /**< Topic on which data was published. */
mqtt_message_t payload; /**< Payload on the topic published. */
} mqtt_publish_message_t;
/**@brief Parameters for a connection acknowledgment (connack). */
typedef struct
{
uint8_t session_present_flag; /**< The Session Present flag enables a Client to establish whether the Client and Server have a consistent view about whether there is already stored Session state. */
mqtt_conn_return_code_t return_code; /**< The appropriate non-zero Connect return code indicates if the Server is unable to process a connection request for some reason. */
} mqtt_connack_param_t;
/**@brief Parameters for MQTT publish acknowledgment(puback). */
typedef struct
{
uint16_t message_id;
} mqtt_puback_param_t;
/**@brief Parameters for MQTT publish receive(pubrec). */
typedef struct
{
uint16_t message_id;
} mqtt_pubrec_param_t;
/**@brief Parameters for MQTT publish release(pubrec). */
typedef struct
{
uint16_t message_id;
} mqtt_pubrel_param_t;
/**@brief Parameters for MQTT publish complete(pubcomp). */
typedef struct
{
uint16_t message_id;
} mqtt_pubcomp_param_t;
/**@brief Parameters for MQTT subscription acknowledgment (suback). */
typedef struct
{
uint16_t message_id;
} mqtt_suback_param_t;
/**@brief Parameters for MQTT unsubscription acknowledgment (unsuback). */
typedef struct
{
uint16_t message_id;
} mqtt_unsuback_param_t;
/**@brief Parameters for a publish message. */
typedef struct
{
mqtt_publish_message_t message; /**< Messages including topic, QoS and its payload (if any) to be published. */
uint16_t message_id; /**< Message id used for the publish message. Redundant for QoS 0. */
uint8_t dup_flag:1; /**< Duplicate flag. If 1, it indicates the message is being retransmitted. Has no meaning with QoS 0. */
uint8_t retain_flag:1; /**< retain flag. If 1, the message shall be stored persistently by the broker. */
} mqtt_publish_param_t;
/**@brief List of topics in a subscription request. */
typedef struct
{
mqtt_topic_t * p_list; /**< Array containing topics along with QoS for each. */
uint32_t list_count; /**< Number of topics in the subscription list */
uint16_t message_id; /**< Message id used to identify subscription request. */
} mqtt_subscription_list_t;
/**
* @brief Defines event parameters notified along with asynchronous events to the application.
* Currently, only MQTT_EVT_PUBLISH is accompanied with parameters.
*/
typedef union
{
mqtt_connack_param_t connack; /**< Parameters accompanying MQTT_EVT_CONNACK event. */
mqtt_publish_param_t publish; /**< Parameters accompanying MQTT_EVT_PUBLISH event. */
mqtt_puback_param_t puback; /**< Parameters accompanying MQTT_EVT_PUBACK event. */
mqtt_pubrec_param_t pubrec; /**< Parameters accompanying MQTT_EVT_PUBREC event. */
mqtt_pubrel_param_t pubrel; /**< Parameters accompanying MQTT_EVT_PUBREL event. */
mqtt_pubcomp_param_t pubcomp; /**< Parameters accompanying MQTT_EVT_PUBCOMP event. */
mqtt_suback_param_t suback; /**< Parameters accompanying MQTT_EVT_SUBACK event. */
mqtt_suback_param_t unsuback; /**< Parameters accompanying MQTT_EVT_UNSUBACK event. */
} mqtt_evt_param_t;
/**@brief Defined MQTT asynchronous event notified to the application. */
typedef struct
{
mqtt_evt_id_t id; /**< Identifies the event. */
mqtt_evt_param_t param; /**< Contains parameters (if any) accompanying the event. */
uint32_t result; /**< Event result. For example, MQTT_EVT_CONNACK has a result code indicating success or failure code of connection procedure. */
} mqtt_evt_t;
/**@brief Asynchronous event notification callback registered by the application with
* the module to receive module events.
*
* @param[in] p_client Identifies the client for which the event is notified.
* @param[in] p_evet Event description along with result and associated parameters (if any).
*/
typedef void (*mqtt_evt_cb_t)(mqtt_client_t * const p_client, const mqtt_evt_t * p_evt);
/**@brief MQTT Client definition to maintain information relevant to the client. */
struct mqtt_client_t
{
mqtt_client_id_t client_id; /**< Unique client identification to be used for the connection. Shall be zero length or NULL valued. */
mqtt_username_t * p_user_name; /**< User name (if any) to be used for the connection. NULL indicates no user name. */
mqtt_password_t * p_password; /**< Password (if any) to be used for the connection. Note that if password is provided, user name shall also be provided. NULL indicates no password. */
mqtt_topic_t * p_will_topic; /**< Will topic and QoS. Can be NULL. */
mqtt_will_message_t * p_will_message; /**< Will message. Can be NULL. Non NULL value valid only if will topic is not NULL. */
nrf_tls_key_settings_t * p_security_settings; /**< Provide security settings like PSK, own certificate etc here. The memory provided for the settings shall be resident. */
mqtt_evt_cb_t evt_cb; /**< Application callback registered with the module to get MQTT events. */
ipv6_addr_t broker_addr; /**< IPv6 Address of MQTT broker to which client connection is requested. */
uint16_t broker_port; /**< Broker's Port number. */
uint8_t poll_abort_counter; /**< Poll abort counter maintained for the TCP connection. */
uint8_t protocol_version; /**< MQTT protocol version. */
uint8_t transport_type; /**< Transport type selection for client instance. @ref mqtt_transport_type_t for possible values. MQTT_TRANSPORT_MAX is not a valid type.*/
uint8_t will_retain:1; /**< Will retain flag, 1 if will message shall be retained persistently. */
uint8_t clean_session:1; /**< Clean session flag indicating a fresh (1) or a retained session (0). Default is 1. */
iot_timer_time_in_ms_t last_activity; /**< Internal. Ticks maintaining wallcock in last activity that occurred. Needed for periodic PING. */
uint32_t state; /**< Internal. Shall not be touched by the application. Client's state in the connection. */
int socket_fd; /**< Internal. Shall not be touched by the application. TCP socket file descriptor. */
uint32_t tcp_id; /**< Internal. Shall not be touched by the application. TCP Connection Reference provided by the IP stack. */
uint8_t * p_packet; /**< Internal. Shall not be touched by the application. Used for creating MQTT packet in TX path. */
uint8_t * p_pending_packet; /**< Internal. Shall not be touched by the application. */
nrf_tls_instance_t tls_instance; /**< Internal. Shall not be touched by the application. TLS instance identifier. Valid only if transport is a secure one. */
uint32_t pending_packetlen; /**< Internal. Shall not be touched by the application. */
};
/**
* @brief Initializes the module.
*
* @retval NRF_SUCCESS or an error code indicating reason for failure.
*
* @note Shall be called before initiating any procedures on the module.
* @note If module initialization fails, no module APIs shall be called.
*/
uint32_t mqtt_init(void);
/**
* @brief Initializes the client instance.
*
* @param[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.
*/
void mqtt_client_init(mqtt_client_t * const p_client);
/**
* @brief API to request new MQTT client connection.
*
* @param[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.
* @note Any subsequent changes to parameters like broker address, user name, device id, etc. have
* no effect once MQTT connection is established.
*
* @retval 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.
* @note If more than one simultaneous client connections are needed, please define
* MQTT_MAX_CLIENTS to override default of 1.
* @note Please define MQTT_KEEPALIVE time to override default of 1 minute.
* @note 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_connect(mqtt_client_t * const p_client);
/**
* @brief API to publish messages on topics.
*
* @param[in] p_client Client instance for which the procedure is requested.
* Shall not be NULL.
* @param[in] p_param Parameters to be used for the publish message.
* Shall not be NULL.
*
* @retval 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(mqtt_client_t * const p_client,
mqtt_publish_param_t const * const p_param);
/**
* @brief API used by subscribing client to send acknowledgment to the broker.
* Applicable only to QoS 1 publish messages.
*
* @param[in] p_client Client instance for which the procedure is requested.
* Shall not be NULL.
* @param[in] p_param Identifies message being acknowledged.
*
* @retval 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);
/**
* @brief API to send assured acknowledgment from a subscribing client to the broker.
* Should be called on reception of @ref MQTT_EVT_PUBLISH with QoS set to
* @ref MQTT_QoS_2_EACTLY_ONCE.
*
* @param[in] p_client Identifies client instance for which the procedure is requested.
* Shall not be NULL.
* @param[in] p_param Identifies message being acknowledged.
*
* @retval 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);
/**
* @brief API to used by publishing client to request releasing published data.
* Shall be used only after @ref MQTT_EVT_PUBREC is received and is valid
* only for QoS level @ref MQTT_QoS_2_EACTLY_ONCE.
*
* @param[in] p_client Client instance for which the procedure is requested.
* Shall not be NULL.
* @param[in] p_param Identifies message being released.
*
* @retval 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);
/**
* @brief API used by subscribing clients to acknowledge reception of a released message.
* Should be used on reception @ref MQTT_EVT_PUBREL event.
*
* @param[in] p_client Identifies client instance for which the procedure is requested.
* Shall not be NULL.
* @param[in] p_param Identifies message being completed.
*
* @retval 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);
/**
* @brief API to request subscribing to a topic on the connection.
*
* @param[in] p_client Identifies client instance for which the procedure is requested.
* Shall not be NULL.
* @param[in] p_param Subscription parameters. Shall not be NULL.
*
* @retval NRF_SUCCESS or an error code indicating reason for failure.
*/
uint32_t mqtt_subscribe(mqtt_client_t * const p_client,
mqtt_subscription_list_t const * const p_param);
/**
* @brief API to request un-subscribe from a topic on the connection.
*
* @param[in] p_client Identifies client instance for which the procedure is requested.
* Shall not be NULL.
* @param[in] p_param Parameters describing topics being unsubscribed from.
* Shall not be NULL.
*
* @note QoS included in topic description is unused in this API.
*
* @retval 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);
/**
* @brief API to abort MQTT connection.
*
* @param[in] p_client Identifies client instance for which procedure is requested.
*
* @retval NRF_SUCCESS or an error code indicating reason for failure.
*/
uint32_t mqtt_abort(mqtt_client_t * const p_client);
/**
* @brief API to disconnect MQTT connection.
*
* @param[in] p_client Identifies client instance for which procedure is requested.
*
* @retval NRF_SUCCESS or an error code indicating reason for failure.
*/
uint32_t mqtt_disconnect(mqtt_client_t * const p_client);
/**
* @brief 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.
* @ref mqtt_connect for details on Keep Alive time.
*
* @retval NRF_SUCCESS or an result code indicating reason for failure.
*/
uint32_t mqtt_live(void);
/**
* @brief Wait for an incoming MQTT packet.
* The registered callback will be called with the packet payload.
*
* @param[in] p_client Client instance for which the procedure is requested.
* Shall not be NULL.
* @param[in] timeout Maximum interval (in milliseconds) to wait for a packet.
* If timeout is 0, the interval is indefinitely.
*
* @retval 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_input(mqtt_client_t * const p_client, uint32_t timeout);
#ifdef __cplusplus
}
#endif
#endif // MQTT_H_
/**@} */