Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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)    ((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

Since
1.14
Version
0.8.0

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]literalLiteral 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]clientIdentifies the client for which the event is notified.
[in]evtEvent description along with result and associated parameters (if any).

Enumeration Type Documentation

◆ 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

#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

#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

#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

#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]clientIdentifies 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]clientClient 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]clientClient 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]clientIdentifies 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]clientClient 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]clientClient 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]clientClient 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]clientIdentifies 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]clientClient instance for which the procedure is requested. Shall not be NULL.
[in]paramParameters 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]clientClient instance for which the procedure is requested. Shall not be NULL.
[in]paramIdentifies 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]clientIdentifies client instance for which the procedure is requested. Shall not be NULL.
[in]paramIdentifies 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]clientIdentifies client instance for which the procedure is requested. Shall not be NULL.
[in]paramIdentifies 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]clientClient instance for which the procedure is requested. Shall not be NULL.
[in]paramIdentifies 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]clientClient instance for which the procedure is requested. Shall not be NULL.
[out]bufferBuffer where payload should be stored.
[in]lengthLength 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]clientClient instance for which the procedure is requested. Shall not be NULL.
[out]bufferBuffer where payload should be stored.
[in]lengthLength 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]clientClient instance for which the procedure is requested. Shall not be NULL.
[out]bufferBuffer where payload should be stored.
[in]lengthNumber 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]clientIdentifies client instance for which the procedure is requested. Shall not be NULL.
[in]paramSubscription 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]clientIdentifies client instance for which the procedure is requested. Shall not be NULL.
[in]paramParameters 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.