一 特性

•支持多种传输层协议如：TCP,SSL,Websocket,wws.
•使用url建立连接
•允许一个应用中多个客户端
•支持订阅，发布，认证，遗嘱，保活和3个消息质量

二 应用示例

•protocols/mqtt.tcp:使用tcp，1883 端口
•protocols/mqtt/ssl:使用tcp，端口8883，比较安全
•protocols/mqtt/ssl_psk:使用tcp，基于公钥加密认证，端口8883
•protocols/mqtt/ws:使用websocket，端口80
•protocols/mqtt/wss:使用wss，端口443

三 初始化配置

3.1 URI

当前支持mqtt，mqtts，ws，wss方式

mqtt 使用tcp例子：

•mqtt://mqtt.eclipse.org: MQTT over TCP, default port 1883
•mqtt://mqtt.eclipse.org:1884 MQTT over TCP, port 1884
•mqtt://username:password@mqtt.eclipse.org:1884 MQTT over TCP, port 1884, with username and password

MQTT over SSL samples:

•mqtts://mqtt.eclipse.org: MQTT over SSL, port 8883
•mqtts://mqtt.eclipse.org:8884: MQTT over SSL, port 8884

MQTT over Websocket samples:

•ws://mqtt.eclipse.org:80/mqtt

MQTT over Websocket Secure samples:

•wss://mqtt.eclipse.org:443/mqtt

最小配置:

const esp_mqtt_client_config_t mqtt_cfg = {
    .uri = "mqtt://mqtt.eclipse.org",
    // .user_context = (void *)your_context
};
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的事件，如连接，订阅，发布等等。

3.2 SSL

3.3 遗嘱

MQTT支持使用遗嘱消息，当客户端意外断开连接时，遗嘱消息被服务端发送并用于通知其他客户端。在 esp_mqtt_client_config_t 中可配置遗嘱消息：

•lwt_topic ：指向遗嘱消息的主题
•lwt_msg：指向遗嘱消息
•lwt_msg_len：消息有效载荷长度
•lwt_qos：消息服务质量
•lwt_retain：是否保留

3.4 其他配置参数

•disable_clean_session：默认清除会话，对于连接消息，该参数关闭清除会话标志
•keepalive：保活时间，默认120s
•disable_auto_reconnect：关闭自动重连
•user_context：本地参数，用于传递到事件处理句柄
•task_prio：mqtt任务等级，默认5
•task_stack：mqtt堆栈默认6144 bytes，menuconfig可配置
•buffer_size：接收和缓存的长度，默认1024 bytes
•username：连接到broker的用户名（服务器）
•password：连接到broker的密码（服务器）
•client_id：指向客户端id，一般是一个唯一的字符串，可从broker中获取
•host：MQTT broker的ip地址，域名。设置了url会重写该参数
•port：MQTT broker的端口。设置了url会重写该参数
•transport：设置传输协议。设置了url会重写该参数
•refresh_connection_after_ms：在多少时间（ms）后刷新连接
•event_handle：处理mqtt事件的回调函数
•event_loop_handle：mqtt事件组库

更多esp_mqtt_client_config_t的选项，请参考下面API：

3.5 项目配置菜单来配置mqtt

通过idf.py menuconfig项目配置菜单来配置mqtt，在Component config -> ESP-MQTT Configuration

下面的设置是可行的：

•CONFIG_MQTT_PROTOCOL_311：使用3.1.1版本的MQTT协议
•CONFIG_MQTT_TRANSPORT_SSL, CONFIG_MQTT_TRANSPORT_WEBSOCKET：选择传输层协议
•CONFIG_MQTT_CUSTOM_OUTBOX：使用本地邮箱

3.6 事件

mqtt主要围绕以下事件进行数据的处理：

•MQTT_EVENT_BEFORE_CONNECT：客户端初始化完成并开始连接到broker
•MQTT_EVENT_CONNECTED：客户端成功与broker建立连接，客户端准备好接收发送数据
•MQTT_EVENT_DISCONNECTED：客户端由于无法接收或者发送消息而断开连接
•MQTT_EVENT_SUBSCRIBED：broker 确认客户端的订阅请求。保留订阅消息的id
•MQTT_EVENT_UNSUBSCRIBED：broker确认了客户端的取消订阅消息。保留取消订阅消息的id
•MQTT_EVENT_PUBLISHED：broker确认了用户发布的消息。仅对qos为1和2的消息有效，保留发布消息的id
•MQTT_EVENT_DATA：客户端已接收到一个发布的消息。event data包括：消息id，主题名称，数据及数据长度。若数据长度超过buffer大小，则多个MQTT_EVENT_DATA事件会被触发，*current_data_offset和*total_data_len用于保持对数据的追踪。在此可将数据读到缓存中。
•MQTT_EVENT_ERROR：客户端遇到错误。esp_mqtt_error_type_t from error_handle in the event data 可用于判断是哪个类型的错误。

四 API参考

esp_mqtt_client_handle_t esp_mqtt_client_init(const esp_mqtt_client_config_t *config)

根据配置创建mqtt 客户端句柄。

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

设置mqtt连接的url，这个函数通常会重写esp_mqtt_client_init里的配置。

esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client);

开启mqtt客户端

esp_err_t esp_mqtt_client_reconnect(esp_mqtt_client_handle_t client);

用于强制重新连接

esp_err_t esp_mqtt_client_disconnect(esp_mqtt_client_handle_t client);

用于强制从broker中断开连接

esp_err_t esp_mqtt_client_stop(esp_mqtt_client_handle_t client);

停止mqtt客户端任务，不能再event handle中调用。

int esp_mqtt_client_subscribe(esp_mqtt_client_handle_t client, const char *topic, int qos);

客户端订阅指向服务质量的主题。

客户端必须已经连接，该API可被用户任务或mqtt event 回调函数调用。该API使用信号量，所以可能导致一段时间的阻塞。

返回：消息id

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

取消订阅指定主题

•客户端必须连接
•线程安全。参考上面
•返回：消息id

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

客户端发布消息到broker

•该API可能会阻塞几秒钟（由于网络，数据长度问题）
•客户端不必连接
•线程安全
•返回：消息id

参数：

•client：客户端句柄
•topic：主题字符串
•data：有效载荷字符串
•len：有效载荷字符串长度
•qos：消息服务质量
•retain：保留消息标志

esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client);

销毁mqtt客户端，不能再mqtt回调函数中调用

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

设置配置结构体，通常用于更新mqtt配置，再连接之前的回调事件中。

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

注册mqtt事件

参数：

client：

event：事件类型

event_handler:事件处理回调函数

event_handler_arg:事件处理回调函数传入参数

int esp_mqtt_client_get_outbox_size(esp_mqtt_client_handle_t client);

获取邮箱大小