esp-idf/docs/zh_CN/api-reference/protocols/mqtt.rst

179 lines
7.9 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

ESP-MQTT
========
概述
--------
ESP-MQTT 是 `MQTT <https://mqtt.org/>`_ 协议客户端的实现。MQTT 是一种基于发布/订阅模式的轻量级消息传输协议。
特性
--------
* 支持基于 TCP 的 MQTT、基于 Mbed TLS 的 SSL、基于 WebSocket 的 MQTT 以及基于 WebSocket Secure 的 MQTT
* 通过 URI 简化配置流程
* 多个实例(一个应用程序中有多个客户端)
* 支持订阅、发布、认证、遗嘱消息、保持连接心跳机制以及 3 个服务质量 (QoS) 级别(组成全功能客户端)
应用示例
-------------------
* :example:`protocols/mqtt/tcp`:基于 TCP 的 MQTT默认端口 1883
* :example:`protocols/mqtt/ssl`:基于 TLS 的 MQTT默认端口 8883
* :example:`protocols/mqtt/ssl_ds`:基于 TLS 的 MQTT使用数字签名外设进行身份验证默认端口 8883
* :example:`protocols/mqtt/ssl_mutual_auth`:基于 TLS 的 MQTT使用证书进行身份验证默认端口 8883
* :example:`protocols/mqtt/ssl_psk`:基于 TLS 的 MQTT使用预共享密钥进行身份验证默认端口 8883
* :example:`protocols/mqtt/ws`:基于 WebSocket 的 MQTT默认端口 80
* :example:`protocols/mqtt/wss`:基于 WebSocket Secure 的 MQTT默认端口 443
配置
-------------
通过设置 ``esp_mqtt_client_config_t`` 结构体中的字段来进行配置。配置结构体包含以下子结构体,用于配置客户端的多种操作。
* :cpp:member:`broker<esp_mqtt_client_config::broker>` - 允许设置地址和安全验证。
* :cpp:member:`credentials<esp_mqtt_client_config::credentials>` - 用于身份验证的客户端凭据。
* :cpp:member:`session<esp_mqtt_client_config::session>` - MQTT 会话相关配置。
* :cpp:member:`network<esp_mqtt_client_config::network>` - 网络相关配置。
* :cpp:member:`task<esp_mqtt_client_config::task>` - 允许配置 FreeRTOS 任务。
* :cpp:member:`buffer<esp_mqtt_client_config::buffer>` - 输入输出的缓冲区大小。
下文将详细介绍不同配置。
服务器
^^^^^^^^^^^^
===========
地址
===========
通过 ``broker.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``
- 最简配置:
.. code:: c
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);
.. note:: 默认情况下MQTT 客户端使用事件循环库来发布相关 MQTT 事件(已连接、已订阅、已发布等)。
=============
验证
=============
为验证服务器身份,对于使用 TLS 的安全链接,必须设置 ``broker.verification`` 结构体。
服务器证书可设置为 PEM 或 DER 格式。如要选择 DER 格式,必须设置等效 ``_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``
- 检查示例应用程序:``examples/mqtt_ssl``
- 配置:
.. code:: c
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 参考`_ 以及 :ref:`esp_tls_server_verification`
客户端凭据
^^^^^^^^^^^^^^^^^^^^^^^^
``credentials`` 字段下包含所有客户端相关凭据。
* ``username``:指向用于连接服务器用户名的指针,也可通过 URI 设置
* ``client_id``:指向客户端 ID 的指针,默认为 ``ESP32_%CHIPID%``,其中 ``%CHIPID%`` 是十六进制 MAC 地址的最后 3 个字节
===============
认证
===============
可以通过 ``authentication`` 字段设置认证参数。客户端支持以下认证方式:
* ``authentication.password``:使用密码
* ``authentication.certificate````authentication.key``:进行双向 TLS 身份验证PEM 或 DER 格式均可
* ``authentication.use_secure_element``:使用 ESP32-WROOM-32SE 中的安全元素
* ``authentication.ds_data``:使用某些乐鑫设备的数字签名外设
会话
^^^^^^^^^^^^
使用 ``section`` 字段进行 MQTT 会话相关配置。
========================
遗嘱消息 (LWT)
========================
通过设置 ``esp_mqtt_client_config_t.session.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 设置。
相关设置如下:
- :ref:`CONFIG_MQTT_PROTOCOL_311`:启用 MQTT 协议 3.1.1 版本
- :ref:`CONFIG_MQTT_TRANSPORT_SSL`:ref:`CONFIG_MQTT_TRANSPORT_WEBSOCKET`:启用特定 MQTT 传输层,例如 SSL、WEBSOCKET 和 WEBSOCKET_SECURE
- :ref:`CONFIG_MQTT_CUSTOM_OUTBOX`:禁用 mqtt_outbox 默认实现,因此可以提供特定实现
事件
------------
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`` 中的 ``esp_mqtt_error_type_t``,可以进一步判断错误类型。错误类型决定 ``error_handle`` 结构体的哪些部分会被填充。
API 参考
-------------
.. include-build-file:: inc/mqtt_client.inc