MQTT Client library

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)
	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

Since

1.14

Version

0.8.0

Macro Definition Documentation

MQTT_UTF8_LITERAL

#define MQTT_UTF8_LITERAL

(

literal

)

#include <zephyr/net/mqtt.h>

Value:

        ((struct mqtt_utf8) {literal, sizeof(literal) - 1})

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.