谷动谷力

标题: ESP-MQTT浅析 [打印本页]

作者: sunsili 时间: 2024-3-26 11:20
标题: ESP-MQTT浅析
本帖最后由 sunsili 于 2024-3-26 11:22 编辑

ESP-MQTT浅析

概述

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

特性

支持基于 TCP 的 MQTT、基于 Mbed TLS 的 SSL、基于 WebSocket 的 MQTT 以及基于 WebSocket Secure 的 MQTT
通过 URI 简化配置流程
多个实例（一个应用程序中有多个客户端）
支持订阅、发布、认证、遗嘱消息、保持连接心跳机制以及 3 个服务质量 (QoS) 级别（组成全功能客户端）

应用示例

protocols/mqtt/tcp：基于 TCP 的 MQTT，默认端口 1883
protocols/mqtt/ssl：基于 TLS 的 MQTT，默认端口 8883
protocols/mqtt/ssl_ds：基于 TLS 的 MQTT，使用数字签名外设进行身份验证，默认端口 8883
protocols/mqtt/ssl_mutual_auth：基于 TLS 的 MQTT，使用证书进行身份验证，默认端口 8883
protocols/mqtt/ssl_psk：基于 TLS 的 MQTT，使用预共享密钥进行身份验证，默认端口 8883
protocols/mqtt/ws：基于 WebSocket 的 MQTT，默认端口 80
protocols/mqtt/wss：基于 WebSocket Secure 的 MQTT，默认端口 443
protocols/mqtt5: 使用 ESP-MQTT 库连接 MQTT v5.0 的服务器

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.ioopenssl s_client -showcerts -connect mqtt.eclipseprojects.io:8883 < /dev/null \2> /dev/null | openssl x509 -outform PEM > mqtt_eclipse_org.pem
检查示例应用程序：protocols/mqtt/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 参考以及 TLS 服务器验证。

客户端凭据

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

username：指向用于连接服务器用户名的指针，也可通过 URI 设置
client_id：指向客户端 ID 的指针，默认为 ESP32_%CHIPID%，其中 %CHIPID% 是十六进制 MAC 地址的最后 3 个字节

认证

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

password：使用密码

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

use_secure_element：使用 ESP32-WROOM-32SE 中的安全元素
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 设置。