MQTT Client Implementation. More...

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

struct	mqtt_binstr
	Abstracts binary strings. More...

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

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

struct	mqtt_connack_param
	Parameters for a connection acknowledgment (CONNACK). More...

struct	mqtt_puback_param
	Parameters for MQTT publish acknowledgment (PUBACK). More...

struct	mqtt_pubrec_param
	Parameters for MQTT publish receive (PUBREC). More...

struct	mqtt_pubrel_param
	Parameters for MQTT publish release (PUBREL). More...

struct	mqtt_pubcomp_param
	Parameters for MQTT publish complete (PUBCOMP). More...

struct	mqtt_suback_param
	Parameters for MQTT subscription acknowledgment (SUBACK). More...

struct	mqtt_unsuback_param
	Parameters for MQTT unsubscribe acknowledgment (UNSUBACK). More...

struct	mqtt_publish_param
	Parameters for a publish message (PUBLISH). More...

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

union	mqtt_evt_param
	Defines event parameters notified along with asynchronous events to the application. More...

struct	mqtt_evt
	Defines MQTT asynchronous event notified to the application. More...

struct	mqtt_sec_config
	TLS configuration for secure MQTT transports. More...

struct	mqtt_transport
	MQTT transport specific data. More...

struct	mqtt_internal
	MQTT internal state. More...

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

Macros
#define	MQTT_UTF8_LITERAL(literal) ((struct mqtt_utf8) {literal, sizeof(literal) - 1})
	Initialize UTF-8 encoded string from C literal string.

Typedefs
typedef void(*	mqtt_evt_cb_t) (struct mqtt_client client, const struct mqtt_evt evt)
	Asynchronous event notification callback registered by the application.

Enumerations
enum	mqtt_evt_type { 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_EVT_PINGRESP }
	MQTT Asynchronous Events notified to the application from the module through the callback registered by the application. More...

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

enum	mqtt_qos { MQTT_QOS_0_AT_MOST_ONCE = 0x00 , MQTT_QOS_1_AT_LEAST_ONCE = 0x01 , MQTT_QOS_2_EXACTLY_ONCE = 0x02 }
	MQTT Quality of Service types. More...

enum	mqtt_conn_return_code { 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 CONNACK return codes. More...

enum	mqtt_suback_return_code { MQTT_SUBACK_SUCCESS_QoS_0 = 0x00 , MQTT_SUBACK_SUCCESS_QoS_1 = 0x01 , MQTT_SUBACK_SUCCESS_QoS_2 = 0x02 , MQTT_SUBACK_FAILURE = 0x80 }
	MQTT SUBACK return codes. More...

enum	mqtt_transport_type { MQTT_TRANSPORT_NON_SECURE , MQTT_TRANSPORT_NUM }
	MQTT transport type. More...

Functions
void	mqtt_client_init (struct mqtt_client *client)
	Initializes the client instance.

int	mqtt_connect (struct mqtt_client *client)
	API to request new MQTT client connection.

int	mqtt_publish (struct mqtt_client client, const struct mqtt_publish_param param)
	API to publish messages on topics.

int	mqtt_publish_qos1_ack (struct mqtt_client client, const struct mqtt_puback_param param)
	API used by client to send acknowledgment on receiving QoS1 publish message.

int	mqtt_publish_qos2_receive (struct mqtt_client client, const struct mqtt_pubrec_param param)
	API used by client to send acknowledgment on receiving QoS2 publish message.

int	mqtt_publish_qos2_release (struct mqtt_client client, const struct mqtt_pubrel_param param)
	API used by client to request release of QoS2 publish message.

int	mqtt_publish_qos2_complete (struct mqtt_client client, const struct mqtt_pubcomp_param param)
	API used by client to send acknowledgment on receiving QoS2 publish release message.

int	mqtt_subscribe (struct mqtt_client client, const struct mqtt_subscription_list param)
	API to request subscription of one or more topics on the connection.

int	mqtt_unsubscribe (struct mqtt_client client, const struct mqtt_subscription_list param)
	API to request unsubscription of one or more topics on the connection.

int	mqtt_ping (struct mqtt_client *client)
	API to send MQTT ping.

int	mqtt_disconnect (struct mqtt_client *client)
	API to disconnect MQTT connection.

int	mqtt_abort (struct mqtt_client *client)
	API to abort MQTT connection.

int	mqtt_live (struct mqtt_client *client)
	This API should be called periodically for the client to be able to keep the connection alive by sending Ping Requests if need be.

int	mqtt_keepalive_time_left (const struct mqtt_client *client)
	Helper function to determine when next keep alive message should be sent.

int	mqtt_input (struct mqtt_client *client)
	Receive an incoming MQTT packet.

int	mqtt_read_publish_payload (struct mqtt_client client, void buffer, size_t length)
	Read the payload of the received PUBLISH message.

int	mqtt_read_publish_payload_blocking (struct mqtt_client client, void buffer, size_t length)
	Blocking version of mqtt_read_publish_payload function.

int	mqtt_readall_publish_payload (struct mqtt_client client, uint8_t buffer, size_t length)
	Blocking version of mqtt_read_publish_payload function which runs until the required number of bytes are read.

Detailed Description

MQTT Client Implementation.

Since: 1.14

Version: 0.8.0

Note: The implementation assumes TCP module is enabled.; By default the implementation uses MQTT version 3.1.1.

Macro Definition Documentation

◆ MQTT_UTF8_LITERAL

#define MQTT_UTF8_LITERAL ( literal ) ((struct mqtt_utf8) {literal, sizeof(literal) - 1})

#include <zephyr/net/mqtt.h>

Initialize UTF-8 encoded string from C literal string.

Use it as follows:

struct mqtt_utf8 password = MQTT_UTF8_LITERAL("my_pass");

Parameters

[in] literal Literal string from which to generate mqtt_utf8 object.

Typedef Documentation

◆ mqtt_evt_cb_t

typedef void(* mqtt_evt_cb_t) (struct mqtt_client *client, const struct mqtt_evt *evt)

#include <zephyr/net/mqtt.h>

Asynchronous event notification callback registered by the application.

Parameters

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

Enumeration Type Documentation

◆ mqtt_conn_return_code

enum mqtt_conn_return_code

#include <zephyr/net/mqtt.h>

MQTT CONNACK return codes.

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_evt_type

enum mqtt_evt_type

#include <zephyr/net/mqtt.h>

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. Note PUBLISH event structure only contains payload size, the payload data parameter should be ignored. Payload content has to be read manually with mqtt_read_publish_payload function.
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 message with QoS 2.
MQTT_EVT_PUBCOMP	Confirmation to a publish release message with QoS 2.
MQTT_EVT_SUBACK	Acknowledgment to a subscribe request.
MQTT_EVT_UNSUBACK	Acknowledgment to a unsubscribe request.
MQTT_EVT_PINGRESP	Ping Response from server.

◆ mqtt_qos

enum mqtt_qos

#include <zephyr/net/mqtt.h>

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_AT_LEAST_ONCE

Medium Quality of Service, if acknowledgment expected for published message, duplicate messages permitted.

MQTT_QOS_2_EXACTLY_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_suback_return_code

enum mqtt_suback_return_code

#include <zephyr/net/mqtt.h>

MQTT SUBACK return codes.

Enumerator
MQTT_SUBACK_SUCCESS_QoS_0	Subscription with QoS 0 succeeded.
MQTT_SUBACK_SUCCESS_QoS_1	Subscription with QoS 1 succeeded.
MQTT_SUBACK_SUCCESS_QoS_2	Subscription with QoS 2 succeeded.
MQTT_SUBACK_FAILURE	Subscription for a topic failed.

◆ mqtt_transport_type

enum mqtt_transport_type

#include <zephyr/net/mqtt.h>

MQTT transport type.

Enumerator

MQTT_TRANSPORT_NON_SECURE

Use non secure TCP transport for MQTT connection.

MQTT_TRANSPORT_NUM

Shall not be used as a transport type.

Indicator of maximum transport types possible.

◆ mqtt_version

enum mqtt_version

#include <zephyr/net/mqtt.h>

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

◆ mqtt_abort()

int mqtt_abort ( struct mqtt_client * client )

#include <zephyr/net/mqtt.h>

API to abort MQTT connection.

This will close the corresponding transport without closing the connection gracefully at the MQTT level (with disconnect message).

Parameters

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

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_client_init()

void mqtt_client_init ( struct mqtt_client * client )

#include <zephyr/net/mqtt.h>

Initializes the client instance.

Parameters

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

Note: Shall be called to initialize client structure, before setting any client parameters and before connecting to broker.

◆ mqtt_connect()

int mqtt_connect ( struct mqtt_client * client )

#include <zephyr/net/mqtt.h>

API to request new MQTT client connection.

Parameters

[in] 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.

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

Note: Default protocol revision used for connection request is 3.1.1. Please set client.protocol_version = MQTT_VERSION_3_1_0 to use protocol 3.1.0.; Please modify CONFIG_MQTT_KEEPALIVE time to override default of 1 minute.

◆ mqtt_disconnect()

int mqtt_disconnect ( struct mqtt_client * client )

#include <zephyr/net/mqtt.h>

API to disconnect MQTT connection.

Parameters

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

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_input()

int mqtt_input ( struct mqtt_client * client )

#include <zephyr/net/mqtt.h>

Receive an incoming MQTT packet.

The registered callback will be called with the packet content.

Note: In case of PUBLISH message, the payload has to be read separately with mqtt_read_publish_payload function. The size of the payload to read is provided in the publish event structure.; This is a non-blocking call.

Parameters

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

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_keepalive_time_left()

int mqtt_keepalive_time_left ( const struct mqtt_client * client )

#include <zephyr/net/mqtt.h>

Helper function to determine when next keep alive message should be sent.

Can be used for instance as a source for poll timeout.

Parameters

[in] client Client instance for which the procedure is requested.

Returns: Time in milliseconds until next keep alive message is expected to be sent. Function will return -1 if keep alive messages are not enabled.

◆ mqtt_live()

int mqtt_live ( struct mqtt_client * client )

#include <zephyr/net/mqtt.h>

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

Parameters

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

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.

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_ping()

int mqtt_ping ( struct mqtt_client * client )

#include <zephyr/net/mqtt.h>

API to send MQTT ping.

The use of this API is optional, as the library handles the connection keep-alive on it's own, see mqtt_live.

Parameters

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

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_publish()

int mqtt_publish	(	struct mqtt_client *	client,
		const struct mqtt_publish_param *	param
	)

#include <zephyr/net/mqtt.h>

API to publish messages on topics.

Parameters

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

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_publish_qos1_ack()

int mqtt_publish_qos1_ack	(	struct mqtt_client *	client,
		const struct mqtt_puback_param *	param
	)

#include <zephyr/net/mqtt.h>

API used by client to send acknowledgment on receiving QoS1 publish message.

Should be called on reception of MQTT_EVT_PUBLISH with QoS level MQTT_QOS_1_AT_LEAST_ONCE.

Parameters

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

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_publish_qos2_complete()

int mqtt_publish_qos2_complete	(	struct mqtt_client *	client,
		const struct mqtt_pubcomp_param *	param
	)

#include <zephyr/net/mqtt.h>

API used by client to send acknowledgment on receiving QoS2 publish release message.

Should be called on reception of MQTT_EVT_PUBREL.

Parameters

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

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_publish_qos2_receive()

int mqtt_publish_qos2_receive	(	struct mqtt_client *	client,
		const struct mqtt_pubrec_param *	param
	)

#include <zephyr/net/mqtt.h>

API used by client to send acknowledgment on receiving QoS2 publish message.

Should be called on reception of MQTT_EVT_PUBLISH with QoS level MQTT_QOS_2_EXACTLY_ONCE.

Parameters

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

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_publish_qos2_release()

int mqtt_publish_qos2_release	(	struct mqtt_client *	client,
		const struct mqtt_pubrel_param *	param
	)

#include <zephyr/net/mqtt.h>

API used by client to request release of QoS2 publish message.

Should be called on reception of MQTT_EVT_PUBREC.

Parameters

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

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_read_publish_payload()

int mqtt_read_publish_payload	(	struct mqtt_client *	client,
		void *	buffer,
		size_t	length
	)

#include <zephyr/net/mqtt.h>

Read the payload of the received PUBLISH message.

This function should be called within the MQTT event handler, when MQTT PUBLISH message is notified.

Note: This is a non-blocking call.

Parameters

[in]	client	Client instance for which the procedure is requested. Shall not be NULL.
[out]	buffer	Buffer where payload should be stored.
[in]	length	Length of the buffer, in bytes.

Returns: Number of bytes read or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_read_publish_payload_blocking()

int mqtt_read_publish_payload_blocking	(	struct mqtt_client *	client,
		void *	buffer,
		size_t	length
	)

#include <zephyr/net/mqtt.h>

Blocking version of mqtt_read_publish_payload function.

Parameters

[in]	client	Client instance for which the procedure is requested. Shall not be NULL.
[out]	buffer	Buffer where payload should be stored.
[in]	length	Length of the buffer, in bytes.

Returns: Number of bytes read or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_readall_publish_payload()

int mqtt_readall_publish_payload	(	struct mqtt_client *	client,
		uint8_t *	buffer,
		size_t	length
	)

#include <zephyr/net/mqtt.h>

Blocking version of mqtt_read_publish_payload function which runs until the required number of bytes are read.

Parameters

[in]	client	Client instance for which the procedure is requested. Shall not be NULL.
[out]	buffer	Buffer where payload should be stored.
[in]	length	Number of bytes to read.

Returns: 0 if success, otherwise a negative error code (errno.h) indicating reason of failure.

◆ mqtt_subscribe()

int mqtt_subscribe	(	struct mqtt_client *	client,
		const struct mqtt_subscription_list *	param
	)

#include <zephyr/net/mqtt.h>

API to request subscription of one or more topics on the connection.

Parameters

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

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

◆ mqtt_unsubscribe()

int mqtt_unsubscribe	(	struct mqtt_client *	client,
		const struct mqtt_subscription_list *	param
	)

#include <zephyr/net/mqtt.h>

API to request unsubscription of one or more topics on the connection.

Parameters

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

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

Returns: 0 or a negative error code (errno.h) indicating reason of failure.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MQTT_UTF8_LITERAL

Typedef Documentation

◆ mqtt_evt_cb_t

Enumeration Type Documentation

◆ mqtt_conn_return_code

◆ mqtt_evt_type

◆ mqtt_qos

◆ mqtt_suback_return_code

◆ mqtt_transport_type

◆ mqtt_version

Function Documentation

◆ mqtt_abort()

◆ mqtt_client_init()

◆ mqtt_connect()

◆ mqtt_disconnect()

◆ mqtt_input()

◆ mqtt_keepalive_time_left()

◆ mqtt_live()

◆ mqtt_ping()

◆ mqtt_publish()

◆ mqtt_publish_qos1_ack()

◆ mqtt_publish_qos2_complete()

◆ mqtt_publish_qos2_receive()

◆ mqtt_publish_qos2_release()

◆ mqtt_read_publish_payload()

◆ mqtt_read_publish_payload_blocking()

◆ mqtt_readall_publish_payload()

◆ mqtt_subscribe()

◆ mqtt_unsubscribe()