ESP-MQTT

概述

ESP-MQTT 是 MQTT 协议客户端的实现，MQTT 是一种基于发布/订阅模式的轻量级消息传输协议。ESP-MQTT 当前支持 MQTT v5.0。

特性

支持基于 TCP 的 MQTT、基于 Mbed TLS 的 SSL、基于 WebSocket 的 MQTT 以及基于 WebSocket Secure 的 MQTT

通过 URI 简化配置流程

多个实例（一个应用程序中有多个客户端）

支持订阅、发布、认证、遗嘱消息、保持连接心跳机制以及 3 个服务质量 (QoS) 级别（组成全功能客户端）

应用示例

tcp 演示了如何通过 TCP 实现 MQTT 通信（默认端口 1883）。

ssl 演示了如何使用 SSL 传输来实现基于 TLS 的 MQTT 通信（默认端口 8883）。

ssl_ds 演示了如何使用数字签名外设进行身份验证，以实现基于 TLS 的 MQTT 通信（默认端口 8883）。

ssl_mutual_auth 演示了如何使用证书进行身份验证实现 MQTT 通信（默认端口 8883）。

ssl_psk 演示了如何使用预共享密钥进行身份验证，以实现基于 TLS 的 MQTT 通信（默认端口 8883）。

ws 演示了如何通过 WebSocket 实现 MQTT 通信（默认端口 80）。

wss 演示了如何通过 WebSocket Secure 实现 MQTT 通信（默认端口 443）。

mqtt5 演示了如何使用 ESP-MQTT 库通过 MQTT v5.0 连接到代理。

custom_outbox 演示了如何自定义 ESP-MQTT 库中的 outbox。

MQTT 消息重传

调用 esp_mqtt_client_publish 或其非阻塞形式 esp_mqtt_client_enqueue，可以创建新的 MQTT 消息。

QoS 0 的消息将只发送一次，QoS 1 和 2 具有不同行为，因为协议需要执行额外步骤来完成该过程。

ESP-MQTT 库将始终重新传输未确认的 QoS 1 和 2 发布消息，以避免连接错误导致信息丢失，虽然 MQTT 规范要求仅在重新连接且 Clean Session 标志设置为 0 时重新传输（针对此行为，将 disable_clean_session 设置为 true）。

可能需要重传的 QoS 1 和 2 消息总是处于排队状态，但若使用 esp_mqtt_client_publish 则会立即进行第一次传输尝试。未确认消息的重传将在 message_retransmit_timeout 之后进行。在 CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS 之后，消息会过期并被删除。如已设置 CONFIG_MQTT_REPORT_DELETED_MESSAGES，则会发送事件来通知用户。

配置

通过设置 esp_mqtt_client_config_t 结构体中的字段来进行配置。配置结构体包含以下子结构体，用于配置客户端的多种操作。

esp_mqtt_client_config_t::broker_t - 允许设置地址和安全验证。

esp_mqtt_client_config_t::credentials_t - 用于身份验证的客户端凭据。

esp_mqtt_client_config_t::session_t - MQTT 会话相关配置。

esp_mqtt_client_config_t::network_t - 网络相关配置。

esp_mqtt_client_config_t::task_t - 允许配置 FreeRTOS 任务。

esp_mqtt_client_config_t::buffer_t - 输入输出的缓冲区大小。

下文将详细介绍不同配置。

服务器

地址

通过 address 结构体的 uri 字段或者 hostname、transport 以及 port 的组合，可以设置服务器地址。也可以选择设置 path，该字段对 WebSocket 连接而言非常有用。

使用 uri 字段的格式为 scheme://hostname:port/path。

当前支持 mqtt、mqtts、ws 和 wss 协议
基于 TCP 的 MQTT 示例：
- mqtt://mqtt.eclipseprojects.io：基于 TCP 的 MQTT，默认端口 1883
- mqtt://mqtt.eclipseprojects.io:1884：基于 TCP 的 MQTT，端口 1884
- mqtt://username:password@mqtt.eclipseprojects.io:1884：基于 TCP 的 MQTT，端口 1884，带有用户名和密码
基于 SSL 的 MQTT 示例：
- mqtts://mqtt.eclipseprojects.io：基于 SSL 的 MQTT，端口 8883
- mqtts://mqtt.eclipseprojects.io:8884：基于 SSL 的 MQTT，端口 8884
基于 WebSocket 的 MQTT 示例：
- ws://mqtt.eclipseprojects.io:80/mqtt
基于 WebSocket Secure 的 MQTT 示例：
- wss://mqtt.eclipseprojects.io:443/mqtt
最简配置：

const esp_mqtt_client_config_t mqtt_cfg = {
    .broker.address.uri = "mqtt://mqtt.eclipseprojects.io",
};
esp_mqtt_client_handle_t client = esp_mqtt_client_init(&mqtt_cfg);
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, client);
esp_mqtt_client_start(client);

备注

默认情况下，MQTT 客户端使用事件循环库来发布相关 MQTT 事件（已连接、已订阅、已发布等）。

验证

为验证服务器身份，对于使用 TLS 的安全链接，必须设置 verification 结构体。服务器证书可设置为 PEM 或 DER 格式。如要选择 DER 格式，必须设置等效 certificate_len 字段，否则应在 certificate 字段传入以空字符结尾的 PEM 格式字符串。

从服务器获取证书，例如：mqtt.eclipseprojects.io

openssl s_client -showcerts -connect mqtt.eclipseprojects.io:8883 < /dev/null \
2> /dev/null | openssl x509 -outform PEM > mqtt_eclipse_org.pem

检查示例应用程序：ssl
配置：

const esp_mqtt_client_config_t mqtt_cfg = {
    .broker = {
      .address.uri = "mqtts://mqtt.eclipseprojects.io:8883",
      .verification.certificate = (const char *)mqtt_eclipse_org_pem_start,
    },
};

了解其他字段的详细信息，请查看 API 参考以及 esp_tls_server_verification。

客户端凭据

credentials 字段下包含所有客户端相关凭据。

username：指向用于连接服务器用户名的指针，也可通过 URI 设置

client_id：指向客户端 ID 的指针，默认为 ESP32_%CHIPID%，其中 %CHIPID% 是十六进制 MAC 地址的最后 3 个字节

认证

可以通过 authentication 字段设置认证参数。客户端支持以下认证方式：

password：使用密码

certificate 和 key：进行双向 TLS 身份验证，PEM 或 DER 格式均可

use_secure_element：使用 ESP32 系列中的安全元素 (ATECC608A)

ds_data：使用某些乐鑫设备的数字签名外设

会话

使用 session 字段进行 MQTT 会话相关配置。

遗嘱消息 (LWT)

通过设置 last_will 结构体的以下字段，MQTT 会在一个客户端意外断开连接时通过遗嘱消息通知其他客户端。

topic：指向 LWT 消息主题的指针

msg：指向 LWT 消息的指针

msg_len：LWT 消息的长度，msg 不以空字符结尾时需要该字段

qos：LWT 消息的服务质量

retain：指定 LWT 消息的保留标志

在项目配置菜单中设置 MQTT

通过 idf.py menuconfig，可以在 Component config > ESP-MQTT Configuration 中找到 MQTT 设置。

内存分配位置

在具有外部 RAM（PSRAM）的芯片上，可以将客户端占用内存最多的部分从内部 RAM 移出：

CONFIG_MQTT_OUTBOX_DATA_ON_EXTERNAL_MEMORY：将 outbox 中保存的消息负载分配在外部内存中。
CONFIG_MQTT_BUFFERS_ON_EXTERNAL_MEMORY：将客户端的输入和输出缓冲区（大小由 buffer.size 和 buffer.out_size 决定）分配在外部内存中。
CONFIG_MQTT_TASK_STACK_ON_EXTERNAL_MEMORY：将 MQTT 任务栈分配在外部内存中。任务控制块始终位于内部 RAM 中。该选项需要启用 CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM。

flash cache 被禁用时无法访问外部内存。因此，当任务栈位于外部内存中时，MQTT 任务不能执行任何会禁用 cache 的代码：不允许在 MQTT 任务上下文中进行 flash 和 NVS 操作，也不允许进入 deep sleep 或 light sleep。这也包括由 MQTT 任务分发的事件处理函数中运行的用户代码。

查询客户端状态

使用 esp_mqtt_client_get_state() 可读取客户端句柄的当前生命周期。常见返回值如下：

MQTT_CLIENT_STATE_NOT_INITIALIZED — 句柄为 NULL。
MQTT_CLIENT_STATE_NOT_STARTED — 客户端已初始化，但其任务未运行（从未启动，或已经停止）。
MQTT_CLIENT_STATE_CONNECTING — 任务正在运行，并且正在尝试连接。
MQTT_CLIENT_STATE_CONNECTED — 客户端已连接到服务器。
MQTT_CLIENT_STATE_WAITING_RECONNECT — 客户端正在等待重连超时（或调用 esp_mqtt_client_reconnect()）。
MQTT_CLIENT_STATE_DISCONNECTED — 任务仍在运行，但客户端未连接到服务器（例如 stop 尚未完成时）。

该查询独立于事件处理函数：需要重新配置服务器 URI 或运行看门狗的应用，无需镜像全部事件即可判断客户端是已停止、正在连接、已连接，还是正在等待重连。

事件

MQTT 客户端可能会发布以下事件：

MQTT_EVENT_BEFORE_CONNECT：客户端已初始化并即将开始连接至服务器。
MQTT_EVENT_CONNECTED：客户端已成功连接至服务器。客户端已准备好收发数据。
MQTT_EVENT_DISCONNECTED：由于无法读取或写入数据，例如因为服务器无法使用，客户端已终止连接。
MQTT_EVENT_SUBSCRIBED：服务器已确认客户端的订阅请求。事件数据将包含订阅消息的消息 ID。
MQTT_EVENT_UNSUBSCRIBED：服务器已确认客户端的退订请求。事件数据将包含退订消息的消息 ID。
MQTT_EVENT_PUBLISHED：服务器已确认客户端的发布消息。消息将仅针对 QoS 级别 1 和 2 发布，因为级别 0 不会进行确认。事件数据将包含发布消息的消息 ID。
MQTT_EVENT_DATA：客户端已收到发布消息。事件数据包含：消息 ID、发布消息所属主题名称、收到的数据及其长度。对于超出内部缓冲区的数据，将发布多个 MQTT_EVENT_DATA，并更新事件数据的 current_data_offset 和 total_data_len 以跟踪碎片化消息。
MQTT_EVENT_ERROR：客户端遇到错误。使用事件数据 error_handle 字段中的 error_type，可以发现错误。错误类型决定 error_handle 结构体的哪些部分会被填充。
MQTT_EVENT_KEEPALIVE：客户端已发送 keepalive PINGREQ 或已收到 PINGRESP。data 指向一个 esp_mqtt_keepalive_kind_t 字节（MQTT_KEEPALIVE_PINGREQ 或 MQTT_KEEPALIVE_PINGRESP），data_len 为 1。Keepalive 超时以及发送 PINGREQ 失败仍会发布 MQTT_EVENT_DISCONNECTED``（传输写入失败时还会发布 ``MQTT_EVENT_ERROR），不会发布本事件。

API 参考

Header File

include/mqtt_client.h

Functions

esp_mqtt_client_handle_t esp_mqtt_client_init(const esp_mqtt_client_config_t *config)

Creates MQTT client handle based on the configuration.

参数:

config – MQTT configuration structure

返回:

MQTT client handle on success
NULL on error

esp_err_t esp_mqtt_client_set_uri(esp_mqtt_client_handle_t client, const char *uri)

Sets MQTT connection URI. This API is usually used to overrides the URI configured in esp_mqtt_client_init.

参数:

client – MQTT client handle
uri –

返回:

ESP_OK on success
ESP_FAIL if URI parse error

esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client)

Starts MQTT client with already created client handle.

参数:

client – MQTT client handle

返回:

ESP_OK on success
ESP_ERR_INVALID_ARG on wrong initialization
ESP_FAIL on other error

esp_err_t esp_mqtt_client_reconnect(esp_mqtt_client_handle_t client)

This api is typically used to force reconnection upon a specific event.

参数:

client – MQTT client handle

返回:

ESP_OK on success
ESP_ERR_INVALID_ARG on wrong initialization
ESP_FAIL if client is not waiting for reconnection

esp_err_t esp_mqtt_client_disconnect(esp_mqtt_client_handle_t client)

This api is typically used to force disconnection from the broker.

参数:

client – MQTT client handle

返回:

ESP_OK on success
ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_mqtt_client_stop(esp_mqtt_client_handle_t client)

Stops MQTT client tasks.

Notes:
Cannot be called from the MQTT event handler

参数:

client – MQTT client handle

返回:

ESP_OK on success
ESP_ERR_INVALID_ARG on wrong initialization
ESP_FAIL if client is in invalid state

int esp_mqtt_client_subscribe_single(esp_mqtt_client_handle_t client, const char *topic, int qos)

Subscribe the client to defined topic with defined qos.

Notes:

Client must be connected to send subscribe message
This API is could be executed from a user task or from a MQTT event callback i.e. internal MQTT task (API is protected by internal mutex, so it might block if a longer data receive operation is in progress.
esp_mqtt_client_subscribe could be used to call this function.

参数:

client – MQTT client handle
topic – topic filter to subscribe
qos – Max qos level of the subscription

返回:

MQTT Packet Identifier of the SUBSCRIBE packet on success (>= 0)
-1 on failure
-2 if the outbox is full

int esp_mqtt_client_subscribe_multiple(esp_mqtt_client_handle_t client, const esp_mqtt_topic_t *topic_list, int size)

Subscribe the client to a list of defined topics with defined qos.

Notes:

Client must be connected to send subscribe message
This API is could be executed from a user task or from a MQTT event callback i.e. internal MQTT task (API is protected by internal mutex, so it might block if a longer data receive operation is in progress.
esp_mqtt_client_subscribe could be used to call this function.

参数:

client – MQTT client handle
topic_list – List of topics to subscribe
size – size of topic_list

返回:

MQTT Packet Identifier of the SUBSCRIBE packet on success (>= 0)
-1 on failure
-2 if the outbox is full

int esp_mqtt_client_unsubscribe(esp_mqtt_client_handle_t client, const char *topic)

Unsubscribe the client from defined topic.

Notes:

Client must be connected to send unsubscribe message
It is thread safe, please refer to esp_mqtt_client_subscribe_single for details

参数:

client – MQTT client handle
topic –

返回:

MQTT Packet Identifier of the UNSUBSCRIBE packet on success (>= 0)
-1 on failure

int esp_mqtt_client_publish(esp_mqtt_client_handle_t client, const char *topic, const char *data, int len, int qos, int retain)

Client to send a publish message to the broker.

Notes:

This API might block for several seconds, either due to network timeout (10s) or if publishing payloads longer than internal buffer (due to message fragmentation)
Client doesn’t have to be connected for this API to work, enqueueing the messages with qos>0 (returning -1 for all the qos=0 messages if disconnected).
In case of MQTT v5, if the server quota for inflight messages is exceeded, message will be enqueued and sent later when quota is available.
QoS 0 messages are sent immediately in the calling task, not via the outbox.
If MQTT_SKIP_PUBLISH_IF_DISCONNECTED is enabled, this API will not attempt to publish when the client is not connected and will always return -1.
It is thread safe, please refer to esp_mqtt_client_subscribe for details

参数:

client – MQTT client handle
topic – topic string
data – payload string (set to NULL, sending empty payload message)
len – data length, if set to 0, length is calculated from payload string
qos – QoS of publish message
retain – retain flag

返回:

MQTT Packet Identifier of the PUBLISH packet on success (>= 0; 0 for QoS 0)
-1 on failure
-2 if the outbox is full

int esp_mqtt_client_enqueue(esp_mqtt_client_handle_t client, const char *topic, const char *data, int len, int qos, int retain, bool store)

Enqueue a message to the outbox, to be sent later. Typically used for messages with qos>0, but could be also used for qos=0 messages if store=true.

This API generates and stores the publish message into the internal outbox and the actual sending to the network is performed in the mqtt-task context (in contrast to the esp_mqtt_client_publish() which sends the publish message immediately in the user task’s context). Thus, it could be used as a non blocking version of esp_mqtt_client_publish().

When MQTT v5 inflight quota is exceeded, queued QoS 1/2 messages are held in the outbox. QoS 0 messages enqueued with store=true are not affected.

参数:

client – MQTT client handle
topic – topic string
data – payload string (set to NULL, sending empty payload message)
len – data length, if set to 0, length is calculated from payload string
qos – QoS of publish message
retain – retain flag
store – if true, all messages are enqueued; otherwise only QoS 1 and QoS 2 are enqueued

返回:

MQTT Packet Identifier of the queued PUBLISH packet on success (>= 0)
-1 on failure
-2 if the outbox is full

esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client)

Destroys the client handle.

Notes:

Cannot be called from the MQTT event handler

参数:

client – MQTT client handle

返回:

ESP_OK on success
ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_mqtt_set_config(esp_mqtt_client_handle_t client, const esp_mqtt_client_config_t *config)

Set configuration structure, typically used when updating the config (i.e. on “before_connect” event.

Notes:

When calling this function make sure to have all the intended configurations set, otherwise default values are set.

参数:

client – MQTT client handle
config – MQTT configuration structure

返回:

ESP_OK on success
ESP_ERR_INVALID_ARG if conflicts on transport configuration
ESP_ERR_NO_MEM if failed to allocate

esp_err_t esp_mqtt_client_register_event(esp_mqtt_client_handle_t client, esp_mqtt_event_id_t event, esp_event_handler_t event_handler, void *event_handler_arg)

Registers MQTT event.

参数:

client – MQTT client handle
event – event type
event_handler – handler callback
event_handler_arg – handlers context

返回:

ESP_OK on success
ESP_ERR_INVALID_ARG on wrong initialization
ESP_ERR_NO_MEM if failed to allocate

esp_err_t esp_mqtt_client_unregister_event(esp_mqtt_client_handle_t client, esp_mqtt_event_id_t event, esp_event_handler_t event_handler)

Unregisters mqtt event.

参数:

client – mqtt client handle
event – event ID
event_handler – handler to unregister

返回:

ESP_OK on success
ESP_ERR_INVALID_ARG on invalid event ID
ESP_ERR_NO_MEM if failed to allocate

int esp_mqtt_client_get_outbox_size(esp_mqtt_client_handle_t client)

Get outbox size.

参数:

client – MQTT client handle

返回:

outbox size in bytes
0 on wrong initialization

esp_err_t esp_mqtt_dispatch_custom_event(esp_mqtt_client_handle_t client, esp_mqtt_event_t *event)

Dispatch user event to the mqtt internal event loop.

参数:

client – MQTT client handle
event – MQTT event handle structure

返回:

ESP_OK on success
ESP_ERR_TIMEOUT if the event couldn’t be queued (see also CONFIG_MQTT_EVENT_QUEUE_SIZE)

esp_transport_handle_t esp_mqtt_client_get_transport(esp_mqtt_client_handle_t client, char *transport_scheme)

Get a transport from the scheme.

Allows extra settings to be made on the selected transport, for convenience the scheme used by the mqtt client are defined as MQTT_OVER_TCP_SCHEME, MQTT_OVER_SSL_SCHEME, MQTT_OVER_WS_SCHEME and MQTT_OVER_WSS_SCHEME If the transport_scheme is NULL and the client was set with a custom transport the custom transport will be returned.

Notes:

This function should be called only on MQTT_EVENT_BEFORE_CONNECT.
The intetion is to provide a way to set different configurations than the ones available from client config.
If esp_mqtt_client_destroy is called the returned pointer will be invalidated.
All the required settings should be made in the MQTT_EVENT_BEFORE_CONNECT event handler

参数:

client – MQTT client handle
transport_scheme – Transport handle to search for.

返回:

transport handle on success
NULL on error

esp_mqtt_client_connection_state_t esp_mqtt_client_get_state(esp_mqtt_client_handle_t client)

Get MQTT client’s current state.

Get the current state of MQTT client.

参数:

client – MQTT client handle

返回:

MQTT_CLIENT_STATE_NOT_INITIALIZED if client handle is NULL
MQTT_CLIENT_STATE_NOT_STARTED if the client task is not running
MQTT_CLIENT_STATE_CONNECTING if connecting to the broker
MQTT_CLIENT_STATE_DISCONNECTED if started but not connected to the broker
MQTT_CLIENT_STATE_CONNECTED if connected to the broker
MQTT_CLIENT_STATE_WAITING_RECONNECT if waiting for the reconnection timeout

Structures

struct esp_mqtt_error_codes

MQTT error code structure to be passed as a contextual information into ERROR event

Important: This structure extends esp_tls_last_error error structure and is backward compatible with it (so might be down-casted and treated as esp_tls_last_error error, but recommended to update applications if used this way previously)

Use this structure directly checking error_type first and then appropriate error code depending on the source of the error:

Public Members

esp_err_t esp_tls_last_esp_err: last esp_err code reported from esp-tls component

int esp_tls_stack_err: tls specific error code reported from underlying tls stack

int esp_tls_cert_verify_flags: tls flags reported from underlying tls stack during certificate verification

esp_mqtt_error_type_t error_type: error type referring to the source of the error

esp_mqtt_connect_return_code_t connect_return_code: connection refused error code reported from MQTT* broker on connection

int esp_transport_sock_errno: errno from the underlying socket

struct esp_mqtt_event_t

MQTT event configuration structure

Public Members

esp_mqtt_event_id_t event_id: MQTT event type

esp_mqtt_client_handle_t client: MQTT client handle for this event

char *data: Data associated with this event

int data_len: Length of the data for this event

int total_data_len: Total length of the data (longer data are supplied with multiple events)

int current_data_offset: Actual offset for the data associated with this event

char *topic: Topic associated with this event

int topic_len: Length of the topic for this event associated with this event

int msg_id: MQTT messaged id of message

int session_present: MQTT session_present flag for connection event

esp_mqtt_error_codes_t *error_handle: esp-mqtt error handle including esp-tls errors as well as internal MQTT errors

bool retain: Retained flag of the message associated with this event

int qos: QoS of the messages associated with this event

bool dup: dup flag of the message associated with this event

esp_mqtt_protocol_ver_t protocol_ver: MQTT protocol version used for connection, defaults to value from menuconfig

struct esp_mqtt_client_config_t

MQTT client configuration structure

Default values can be set via menuconfig
All certificates and key data could be passed in PEM or DER format. PEM format must have a terminating NULL character and the related len field set to 0. DER format requires a related len field set to the correct length.

Public Members

struct esp_mqtt_client_config_t::broker_t broker: Broker address and security verification

struct esp_mqtt_client_config_t::credentials_t credentials: User credentials for broker

struct esp_mqtt_client_config_t::session_t session: MQTT session configuration.

struct esp_mqtt_client_config_t::network_t network: Network configuration

struct esp_mqtt_client_config_t::task_t task: FreeRTOS task configuration.

struct esp_mqtt_client_config_t::buffer_t buffer: Buffer size configuration.

struct esp_mqtt_client_config_t::outbox_config_t outbox: Outbox configuration.

struct broker_t

Broker related configuration

Public Members

struct esp_mqtt_client_config_t::broker_t::address_t address: Broker address configuration

struct esp_mqtt_client_config_t::broker_t::verification_t verification: Security verification of the broker

struct address_t

Broker address

uri have precedence over other fields
If uri isn’t set at least hostname, transport and port should.

Public Members

const char *uri: Complete MQTT broker URI

const char *hostname: Hostname, to set ipv4 pass it as string)

esp_mqtt_transport_t transport: Selects transport

const char *path: Path in the URI

uint32_t port: MQTT server port

struct verification_t

Broker identity verification

If fields are not set broker’s identity isn’t verified. it’s recommended to set the options in this struct for security reasons.

Public Members

bool use_global_ca_store: Use a global ca_store, look esp-tls documentation for details.

esp_err_t (*crt_bundle_attach)(void *conf): Pointer to ESP x509 Certificate Bundle attach function for the usage of certificate bundles. Client only attach the bundle, the clean up must be done by the user.

const char *certificate: Certificate data, default is NULL. It’s not copied nor freed by the client, user needs to clean up.

size_t certificate_len: Length of the buffer pointed to by certificate.

const struct psk_key_hint *psk_hint_key: Pointer to PSK struct defined in esp_tls.h to enable PSK authentication (as alternative to certificate verification). PSK is enabled only if there are no other ways to verify broker. It’s not copied nor freed by the client, user needs to clean up.

bool skip_cert_common_name_check: Skip any validation of server certificate CN field, this reduces the security of TLS and makes the MQTT client susceptible to MITM attacks

const char **alpn_protos: NULL-terminated list of supported application protocols to be used for ALPN.

const char *common_name: Pointer to the string containing server certificate common name. If non-NULL, server certificate CN must match this name, If NULL, server certificate CN must match hostname. This is ignored if skip_cert_common_name_check=true. It’s not copied nor freed by the client, user needs to clean up.

const int *ciphersuites_list: Pointer to a zero-terminated array of IANA identifiers of TLS cipher suites. Please ensure the validity of the list, and note that it is not copied or freed by the client.

struct credentials_t

Client related credentials for authentication.

Public Members

const char *username: MQTT username

const char *client_id: Set MQTT client identifier. Ignored if set_null_client_id == true If NULL set the default client id. Default client id is ESP32_CHIPID% where CHIPID% are last 3 bytes of MAC address in hex format

bool set_null_client_id: Selects a NULL client id

struct esp_mqtt_client_config_t::credentials_t::authentication_t authentication: Client authentication

struct authentication_t

Client authentication

Fields related to client authentication by broker

For mutual authentication using TLS, user could select certificate and key, secure element or digital signature peripheral if available.

Public Members

const char *password: MQTT password

const char *certificate: Certificate for ssl mutual authentication, not required if mutual authentication is not needed. Must be provided with key. It’s not copied nor freed by the client, user needs to clean up.

size_t certificate_len: Length of the buffer pointed to by certificate.

const char *key: Private key for SSL mutual authentication, not required if mutual authentication is not needed. If it is not NULL, also certificate has to be provided. It’s not copied nor freed by the client, user needs to clean up.

size_t key_len: Length of the buffer pointed to by key.

const char *key_password: Client key decryption password, not PEM nor DER, if provided key_password_len must be correctly set.

int key_password_len: Length of the password pointed to by key_password

bool use_secure_element: Enable secure element, available in ESP32-ROOM-32SE, for SSL connection

void *ds_data: Carrier of handle for digital signature parameters, digital signature peripheral is available in some Espressif devices. It’s not copied nor freed by the client, user needs to clean up.

bool use_ecdsa_peripheral: Enable ECDSA peripheral, available in some Espressif devices.

uint8_t ecdsa_key_efuse_blk: ECDSA key block number from efuse, available in some Espressif devices.

struct session_t

MQTT Session related configuration

Public Members

struct esp_mqtt_client_config_t::session_t::last_will_t last_will: Last will configuration

bool disable_clean_session: MQTT clean session, default clean_session is true

int keepalive: MQTT keepalive, default is 120 seconds When configuring this value, keep in mind that the client attempts to communicate with the broker at half the interval that is actually set. This conservative approach allows for more attempts before the broker’s timeout occurs

bool disable_keepalive: Set disable_keepalive=true to turn off keep-alive mechanism, keepalive is active by default. Note: setting the config value keepalive to 0 doesn’t disable keepalive feature, but uses a default keepalive period

esp_mqtt_protocol_ver_t protocol_ver: MQTT protocol version used for connection.

int message_retransmit_timeout: timeout for retransmitting of failed packet, default: 1000 ms

struct last_will_t

Last Will and Testament message configuration.

Public Members

const char *topic: LWT (Last Will and Testament) message topic

const char *msg: LWT message, may be NULL terminated

int msg_len: LWT message length, if msg isn’t NULL terminated must have the correct length

int qos: LWT message QoS

int retain: LWT retained message flag

struct network_t

Network related configuration

Public Members

int reconnect_timeout_ms: Reconnect to the broker after this value in milliseconds if auto reconnect is not disabled (default: 10000 ms)

int timeout_ms: Abort network operation if it is not completed after this value, in milliseconds (default: 10000 ms).

int refresh_connection_after_ms: Refresh connection after this value (in milliseconds)

bool disable_auto_reconnect: Client will reconnect to server (when errors/disconnect). Set disable_auto_reconnect=true to disable

esp_transport_keep_alive_t tcp_keep_alive_cfg: Transport keep-alive config

esp_transport_handle_t transport: Custom transport handle to use, leave it NULL to allow MQTT client create or recreate its own. Warning: The transport should be valid during the client lifetime and is destroyed when esp_mqtt_client_destroy is called.

struct ifreq *if_name: The name of interface for data to go through. Use the default interface without setting

struct task_t

Client task configuration

Public Members

int priority: MQTT task priority

int stack_size: MQTT task stack size

struct buffer_t

Client buffer size configuration

Client have two buffers for input and output respectively.

Public Members

int size: size of MQTT send/receive buffer, default: 1024

int out_size: size of MQTT output buffer. If not defined, defaults to the size defined by buffer_size

struct outbox_config_t

Client outbox configuration options.

Public Members

uint64_t limit: Size limit for the outbox in bytes.

Macros

MQTT_ERROR_TYPE_ESP_TLS: MQTT_ERROR_TYPE_TCP_TRANSPORT error type hold all sorts of transport layer errors, including ESP-TLS error, but in the past only the errors from MQTT_ERROR_TYPE_ESP_TLS layer were reported, so the ESP-TLS error type is re-defined here for backward compatibility

esp_mqtt_client_subscribe(client_handle, topic_type, qos_or_size)

Convenience macro to select subscribe function to use.

Notes:

Usage of esp_mqtt_client_subscribe_single is the same as previous esp_mqtt_client_subscribe, refer to it for details.

参数:

client_handle – MQTT client handle
topic_type – Needs to be char* for single subscription or esp_mqtt_topic_t for multiple topics
qos_or_size – It’s either a qos when subscribing to a single topic or the size of the subscription array when subscribing to multiple topics.

返回:

MQTT Packet Identifier of the SUBSCRIBE packet on success (>= 0)
-1 on failure
-2 if the outbox is full

Type Definitions

typedef struct esp_mqtt_client *esp_mqtt_client_handle_t

typedef enum esp_mqtt_event_id_t esp_mqtt_event_id_t

MQTT event types.

User event handler receives context data in esp_mqtt_event_t structure with

client - MQTT client handle
various other data depending on event type

typedef enum esp_mqtt_connect_return_code_t esp_mqtt_connect_return_code_t: MQTT connection error codes propagated via ERROR event

typedef enum esp_mqtt_error_type_t esp_mqtt_error_type_t: MQTT connection error codes propagated via ERROR event

typedef enum esp_mqtt_transport_t esp_mqtt_transport_t

typedef enum esp_mqtt_client_connection_state_t esp_mqtt_client_connection_state_t: States of MQTT client connection

typedef struct esp_mqtt_error_codes esp_mqtt_error_codes_t

MQTT error code structure to be passed as a contextual information into ERROR event

Important: This structure extends esp_tls_last_error error structure and is backward compatible with it (so might be down-casted and treated as esp_tls_last_error error, but recommended to update applications if used this way previously)

Use this structure directly checking error_type first and then appropriate error code depending on the source of the error:

typedef struct esp_mqtt_event_t esp_mqtt_event_t: MQTT event configuration structure

typedef esp_mqtt_event_t *esp_mqtt_event_handle_t

typedef struct esp_mqtt_client_config_t esp_mqtt_client_config_t

MQTT client configuration structure

Default values can be set via menuconfig
All certificates and key data could be passed in PEM or DER format. PEM format must have a terminating NULL character and the related len field set to 0. DER format requires a related len field set to the correct length.

Enumerations

enum esp_mqtt_event_id_t

MQTT event types.

User event handler receives context data in esp_mqtt_event_t structure with

client - MQTT client handle
various other data depending on event type

Values:

enumerator MQTT_EVENT_ANY

enumerator MQTT_EVENT_ERROR: on error event, additional context: connection return code, error handle from esp_tls (if supported)

enumerator MQTT_EVENT_CONNECTED: connected event, additional context: session_present flag

enumerator MQTT_EVENT_DISCONNECTED: disconnected event

enumerator MQTT_EVENT_SUBSCRIBED

subscribed event, additional context:

msg_id message id
error_handle error_type in case subscribing failed
data pointer to broker response, check for errors.
data_len length of the data for this event

enumerator MQTT_EVENT_UNSUBSCRIBED: unsubscribed event, additional context: msg_id

enumerator MQTT_EVENT_PUBLISHED: published event, additional context: msg_id

enumerator MQTT_EVENT_DATA

data event, additional context:

msg_id message id
topic pointer to the received topic
topic_len length of the topic
data pointer to the received data
data_len length of the data for this event
current_data_offset offset of the current data for this event
total_data_len total length of the data received
retain retain flag of the message
qos QoS level of the message
dup dup flag of the message Note: Multiple MQTT_EVENT_DATA could be fired for one message, if it is longer than internal buffer. In that case only first event contains topic pointer and length, other contain data only with current data length and current data offset updating.

enumerator MQTT_EVENT_BEFORE_CONNECT: The event occurs before connecting

enumerator MQTT_EVENT_DELETED

Notification on delete of one message from the internal outbox, if the message couldn’t have been sent or acknowledged before expiring defined in OUTBOX_EXPIRED_TIMEOUT_MS. (events are not posted upon deletion of successfully acknowledged messages)

This event id is posted only if MQTT_REPORT_DELETED_MESSAGES==1
Additional context: msg_id (id of the deleted message, always 0 for QoS = 0 messages).

enumerator MQTT_USER_EVENT: Custom event used to queue tasks into mqtt event handler All fields from the esp_mqtt_event_t type could be used to pass an additional context data to the handler.

enumerator MQTT_EVENT_KEEPALIVE

Keepalive PINGREQ sent or PINGRESP received. Additional context:

data pointer to one byte, an :cpp:type:esp_mqtt_keepalive_kind_t
data_len always 1 The pointer remains valid for the duration of the event handler.

enum esp_mqtt_keepalive_kind_t

Kind of keepalive traffic reported in :cpp:enumerator:MQTT_EVENT_KEEPALIVE. Encoded as a single byte in :cpp:member:esp_mqtt_event_t::data.

Values:

enumerator MQTT_KEEPALIVE_PINGREQ: Client sent a PINGREQ

enumerator MQTT_KEEPALIVE_PINGRESP: Client received a PINGRESP

enum esp_mqtt_connect_return_code_t

MQTT connection error codes propagated via ERROR event

Values:

enumerator MQTT_CONNECTION_ACCEPTED: Connection accepted

enumerator MQTT_CONNECTION_REFUSE_PROTOCOL: MQTT connection refused reason: Wrong protocol

enumerator MQTT_CONNECTION_REFUSE_ID_REJECTED: MQTT connection refused reason: ID rejected

enumerator MQTT_CONNECTION_REFUSE_SERVER_UNAVAILABLE: MQTT connection refused reason: Server unavailable

enumerator MQTT_CONNECTION_REFUSE_BAD_USERNAME: MQTT connection refused reason: Wrong user

enumerator MQTT_CONNECTION_REFUSE_NOT_AUTHORIZED: MQTT connection refused reason: Wrong username or password

enum esp_mqtt_error_type_t

MQTT connection error codes propagated via ERROR event

Values:

enumerator MQTT_ERROR_TYPE_NONE

enumerator MQTT_ERROR_TYPE_TCP_TRANSPORT

enumerator MQTT_ERROR_TYPE_CONNECTION_REFUSED

enumerator MQTT_ERROR_TYPE_SUBSCRIBE_FAILED

enum esp_mqtt_transport_t

Values:

enumerator MQTT_TRANSPORT_UNKNOWN

enumerator MQTT_TRANSPORT_OVER_TCP: MQTT over TCP, using scheme: MQTT

enumerator MQTT_TRANSPORT_OVER_SSL: MQTT over SSL, using scheme: MQTTS

enumerator MQTT_TRANSPORT_OVER_WS: MQTT over Websocket, using scheme:: ws

enumerator MQTT_TRANSPORT_OVER_WSS: MQTT over Websocket Secure, using scheme: wss

enum esp_mqtt_client_connection_state_t

States of MQTT client connection

Values:

enumerator MQTT_CLIENT_STATE_NOT_INITIALIZED: MQTT Client is not initialized

enumerator MQTT_CLIENT_STATE_NOT_STARTED: MQTT Client is initialized, but the client task is not running

enumerator MQTT_CLIENT_STATE_DISCONNECTED: MQTT Client task is running, but not connected to the broker

enumerator MQTT_CLIENT_STATE_CONNECTED: MQTT Client is connected to the broker

enumerator MQTT_CLIENT_STATE_WAITING_RECONNECT: MQTT Client is waiting for reconnection request

enumerator MQTT_CLIENT_STATE_CONNECTING: MQTT Client is connecting to the broker

Header File

include/mqtt5_client.h

Functions

esp_err_t esp_mqtt5_client_set_connect_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_connection_property_config_t *connect_property)

Set MQTT5 client connect property configuration.

参数:

client – mqtt client handle, must not be NULL
connect_property – connect property, must not be NULL

返回:

ESP_OK on success
ESP_ERR_NO_MEM if failed to allocate
ESP_ERR_INVALID_ARG if client or connect_property is NULL
ESP_FAIL on fail

esp_err_t esp_mqtt5_client_set_publish_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_publish_property_config_t *property)

Set MQTT5 client publish property configuration.

This API stages a borrowed property pointer for one successful publish or enqueue serialization by the calling task. The property and all referenced data must remain valid until then. A call from the same task replaces its staged pointer. Publish or enqueue calls from another task proceed without this property and do not consume it. The owner task must not terminate before consuming the property; otherwise the slot remains reserved until client destruction. Reuse of a terminated task’s handle cannot currently be detected.

参数:

client – mqtt client handle, must not be NULL
property – publish property, must not be NULL

返回:

ESP_OK on success
ESP_ERR_INVALID_ARG if client or property is NULL
ESP_ERR_INVALID_STATE if another task owns the staged publish property
ESP_FAIL on fail

esp_err_t esp_mqtt5_client_set_subscribe_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_subscribe_property_config_t *property)

Set MQTT5 client subscribe property configuration.

This API stages a borrowed property pointer for one successful subscribe serialization by the calling task. The property and all referenced data must remain valid until then. A call from the same task replaces its staged pointer. Subscribe calls from another task proceed without this property and do not consume it. The owner task must not terminate before consuming the property; otherwise the slot remains reserved until client destruction. Reuse of a terminated task’s handle cannot currently be detected.

参数:

client – mqtt client handle, must not be NULL
property – subscribe property, must not be NULL

返回:

ESP_OK on success
ESP_ERR_INVALID_ARG if client or property is NULL
ESP_ERR_INVALID_STATE if another task owns the staged subscribe property
ESP_FAIL on fail

esp_err_t esp_mqtt5_client_set_unsubscribe_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_unsubscribe_property_config_t *property)

Set MQTT5 client unsubscribe property configuration.

This API stages a borrowed property pointer for one successful unsubscribe serialization by the calling task. The property and all referenced data must remain valid until then. A call from the same task replaces its staged pointer. Unsubscribe calls from another task proceed without this property and do not consume it. The owner task must not terminate before consuming the property; otherwise the slot remains reserved until client destruction. Reuse of a terminated task’s handle cannot currently be detected.

参数:

client – mqtt client handle, must not be NULL
property – unsubscribe property, must not be NULL

返回:

ESP_OK on success
ESP_ERR_INVALID_ARG if client or property is NULL
ESP_ERR_INVALID_STATE if another task owns the staged unsubscribe property
ESP_FAIL on fail

esp_err_t esp_mqtt5_client_set_disconnect_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_disconnect_property_config_t *property)

Set MQTT5 client disconnect property configuration.

This API will not store the disconnect property, it is one-time configuration. Before call esp_mqtt_client_disconnect to disconnect connection, call this API to set disconnect property if have

参数:

client – mqtt client handle, must not be NULL
property – disconnect property, must not be NULL

返回:

ESP_OK on success
ESP_ERR_NO_MEM if failed to allocate
ESP_ERR_INVALID_ARG if client or property is NULL
ESP_FAIL on fail

esp_err_t esp_mqtt5_client_set_user_property(mqtt5_user_property_handle_t *user_property, esp_mqtt5_user_property_item_t item[], uint8_t item_num)

Set MQTT5 client user property configuration.

This API will allocate memory for user_property, please DO NOT forget call esp_mqtt5_client_delete_user_property after you use it. Before publish data, subscribe topic, unsubscribe, etc, call this API to set user property if have

参数:

user_property – user_property handle
item – array of user property data (eg. {{“var”,”val”},{“other”,”2”}})
item_num – number of items in user property data

返回:

ESP_OK on success
ESP_ERR_NO_MEM if failed to allocate
ESP_FAIL on fail

esp_err_t esp_mqtt5_client_get_user_property(mqtt5_user_property_handle_t user_property, esp_mqtt5_user_property_item_t *item, uint8_t *item_num)

Get MQTT5 client user property.

This API can use with esp_mqtt5_client_get_user_property_count to get list count of user property. And malloc number of count item array memory to store the user property data. Please DO NOT forget the item memory, key and value point in item memory when get user property data successfully.

参数:

user_property – user_property handle
item – point that store user property data
item_num – number of items in user property data

返回:

ESP_OK on success
ESP_ERR_NO_MEM if failed to allocate
ESP_FAIL on fail

uint8_t esp_mqtt5_client_get_user_property_count(mqtt5_user_property_handle_t user_property)

Get MQTT5 client user property list count.

参数:

user_property – user_property handle

返回:

number of items in the user property list

void esp_mqtt5_client_delete_user_property(mqtt5_user_property_handle_t user_property)

Free the user property list.

This API will free the memory in user property list and free user_property itself

参数:: user_property – user_property handle

Structures

struct esp_mqtt5_connection_property_config_t

MQTT5 protocol connect properties and will properties configuration, more details refer to MQTT5 protocol document section 3.1.2.11 and 3.3.2.3

Public Members

uint32_t session_expiry_interval: The interval time of session expiry

uint32_t maximum_packet_size: The maximum packet size that we can receive

uint16_t receive_maximum: The maximum pakcket count that we process concurrently

uint16_t topic_alias_maximum: The maximum topic alias that we support

bool request_resp_info: This value to request Server to return Response information

bool request_problem_info: This value to indicate whether the reason string or user properties are sent in case of failures

mqtt5_user_property_handle_t user_property: The handle for user property, call function esp_mqtt5_client_set_user_property to set it

uint32_t will_delay_interval: The time interval that server delays publishing will message

uint32_t message_expiry_interval: The time interval that message expiry

bool payload_format_indicator: This value is to indicator will message payload format

const char *content_type: This value is to indicator will message content type, use a MIME content type string

const char *response_topic: Topic name for a response message

const char *correlation_data: Binary data for receiver to match the response message

uint16_t correlation_data_len: The length of correlation data

mqtt5_user_property_handle_t will_user_property: The handle for will message user property, call function esp_mqtt5_client_set_user_property to set it

struct esp_mqtt5_server_resp_property_t

MQTT5 server response properties from CONNACK (section 3.2.2.3)

These properties indicate the server’s capabilities and limits. Available in MQTT_EVENT_CONNECTED via event->property->server.

Public Members

uint32_t maximum_packet_size: Maximum packet size the server will accept (0 = no limit imposed)

uint16_t receive_maximum: Maximum number of QoS 1/2 messages the server will process concurrently

uint16_t topic_alias_maximum: Maximum topic alias value the client may use (0 = topic aliases not supported)

uint8_t max_qos: Maximum QoS level the server supports (0, 1, or 2)

bool retain_available: true if the server supports retained messages

bool wildcard_subscribe_available: true if the server supports wildcard subscriptions

bool subscribe_identifiers_available: true if the server supports subscription identifiers

bool shared_subscribe_available: true if the server supports shared subscriptions

const char *response_info: Response information string for request/response (NULL if not provided)

int response_info_len: Length of response_info

struct esp_mqtt5_event_property_t

MQTT5 protocol for event properties

Public Members

bool payload_format_indicator: Payload format of the message

char *response_topic: Response topic of the message

int response_topic_len: Response topic length of the message

char *correlation_data: Correlation data of the message

uint16_t correlation_data_len: Correlation data length of the message

char *content_type: Content type of the message

int content_type_len: Content type length of the message

uint16_t subscribe_id: Subscription identifier of the message

mqtt5_user_property_handle_t user_property: The handle for user property, call function esp_mqtt5_client_delete_user_property to free the memory

esp_mqtt5_server_resp_property_t server: Server response properties from CONNACK (valid only in MQTT_EVENT_CONNECTED)

Type Definitions

typedef struct esp_mqtt_client *esp_mqtt5_client_handle_t

typedef enum mqtt5_reason_code_t esp_mqtt5_reason_code_t: MQTT5 protocol error reason code, more details refer to MQTT5 protocol document section 2.4

typedef esp_mqtt5_reason_code_t esp_mqtt5_error_reason_code_t

Deprecated:: alias esp_mqtt5_error_reason_code_t for esp_mqtt5_reason_code_t exists for backwards compatibility reasons and will be removed in subsequent updates.

Enumerations

enum mqtt5_reason_code_t

MQTT5 protocol error reason code, more details refer to MQTT5 protocol document section 2.4

Values:

enumerator MQTT5_SUCCESS

enumerator MQTT5_NORMAL_DISCONNECT

enumerator MQTT5_GRANTED_QOS0

enumerator MQTT5_GRANTED_QOS1

enumerator MQTT5_GRANTED_QOS2

enumerator MQTT5_DISCONNECT_WITH_WILL

enumerator MQTT5_NO_MATCHING_SUBSCRIBERS

enumerator MQTT5_NO_SUBSCRIPTION_EXISTED

enumerator MQTT5_CONTINUE_AUTHENTICATION

enumerator MQTT5_REAUTHENTICATE

enumerator MQTT5_UNSPECIFIED_ERROR

enumerator MQTT5_MALFORMED_PACKET

enumerator MQTT5_PROTOCOL_ERROR

enumerator MQTT5_IMPLEMENT_SPECIFIC_ERROR

enumerator MQTT5_UNSUPPORTED_PROTOCOL_VER

enumerator MQTT5_INVAILD_CLIENT_ID

enumerator MQTT5_INVALID_CLIENT_ID

enumerator MQTT5_BAD_USERNAME_OR_PWD

enumerator MQTT5_NOT_AUTHORIZED

enumerator MQTT5_SERVER_UNAVAILABLE

enumerator MQTT5_SERVER_BUSY

enumerator MQTT5_BANNED

enumerator MQTT5_SERVER_SHUTTING_DOWN

enumerator MQTT5_BAD_AUTH_METHOD

enumerator MQTT5_KEEP_ALIVE_TIMEOUT

enumerator MQTT5_SESSION_TAKEN_OVER

enumerator MQTT5_TOPIC_FILTER_INVAILD

enumerator MQTT5_TOPIC_FILTER_INVALID

enumerator MQTT5_TOPIC_NAME_INVAILD

enumerator MQTT5_TOPIC_NAME_INVALID

enumerator MQTT5_PACKET_IDENTIFIER_IN_USE

enumerator MQTT5_PACKET_IDENTIFIER_NOT_FOUND

enumerator MQTT5_RECEIVE_MAXIMUM_EXCEEDED

enumerator MQTT5_TOPIC_ALIAS_INVAILD

enumerator MQTT5_TOPIC_ALIAS_INVALID

enumerator MQTT5_PACKET_TOO_LARGE

enumerator MQTT5_MESSAGE_RATE_TOO_HIGH

enumerator MQTT5_QUOTA_EXCEEDED

enumerator MQTT5_ADMINISTRATIVE_ACTION

enumerator MQTT5_PAYLOAD_FORMAT_INVAILD

enumerator MQTT5_PAYLOAD_FORMAT_INVALID

enumerator MQTT5_RETAIN_NOT_SUPPORT

enumerator MQTT5_QOS_NOT_SUPPORT

enumerator MQTT5_USE_ANOTHER_SERVER

enumerator MQTT5_SERVER_MOVED

enumerator MQTT5_SHARED_SUBSCR_NOT_SUPPORTED

enumerator MQTT5_CONNECTION_RATE_EXCEEDED

enumerator MQTT5_MAXIMUM_CONNECT_TIME

enumerator MQTT5_SUBSCRIBE_IDENTIFIER_NOT_SUPPORT

enumerator MQTT5_WILDCARD_SUBSCRIBE_NOT_SUPPORT