MQTT AT 指令说明
AT 工程: https://github.com/espressif/esp-at
AT 文档: https://github.com/espressif/esp-at/tree/master/docs
自 commit: 8ebdee924 之后, ESP-AT 支持 MQTT 系列 AT 指令, 基于 AT 开发的客户可以直接参考本文下述命令, 快速使用 AT+MQTT 连接对应的 Broker.
使用 AT+MQTT 前, 请先开启 AT+MQTT 功能:
make menuconfig -> Component config -> AT -> AT MQTT command support
命令列表
AT+MQTTUSERCFG- 配置 MQTT 用户属性AT+MQTTCONNCFG- 配置 MQTT 连接属性AT+MQTTCLIENTID- 配置 MQTT 客户端 IDAT+MQTTUSERNAME- 配置 MQTT 登录用户名AT+MQTTPASSWORD- 配置 MQTT 登录密码AT+MQTTCONN- 连接/查询 MQTT BrokerAT+MQTTPUB- 发布字符串消息AT+MQTTPUBRAW- 发布二进制消息AT+MQTTSUB- 订阅/查询主题AT+MQTTUNSUB- 取消订阅主题AT+MQTTCLEAN- 关闭连接, 释放资源
AT+MQTTUSERCFG - 配置 MQTT 用户属性
设置指令:
AT+MQTTUSERCFG=<LinkID>,<scheme>,<"client_id">,<"username">,<"password">,<cert_key_ID>,<CA_ID>,<"path">
功能:
设置 MQTT 用户配置
响应:
OK
或
ERROR
参数说明:
- LinkID: 当前只支持 0
- scheme:
- 1:
MQTT over TCP - 2:
MQTT over TLS(no certificate verify) - 3:
MQTT over TLS(verify server certificate) - 4:
MQTT over TLS(provide client certificate) - 5:
MQTT over TLS(verify server certificate and provide client certificate) - 6:
MQTT over WebSocket(based on TCP) - 7:
MQTT over WebSocket Secure(based on TLS, no certificate verify) - 8:
MQTT over WebSocket Secure(based on TLS, verify server certificate) - 9:
MQTT over WebSocket Secure(based on TLS, provide client certificate) - 10:
MQTT over WebSocket Secure(based on TLS, verify server certificate and provide client certificate)
- 1:
- client_id: 对应
MQTTclientID, 用于标志client身份, 最长 256 字节 - username: 用于登录
MQTTbroker的username, 最长 64 字节 - password: 用于登录
MQTTbroker的password, 最长 64 字节 - cert_key_ID: 证书
ID, 目前支持一套cert证书, 参数为 0 - CA_ID:
CA ID, 目前支持一套CA证书, 参数为 0 - path: 资源路径, 最长 32 字节
AT+MQTTCLIENTID - 配置 MQTT 客户端 ID
设置指令:
AT+MQTTCLIENTID=<LinkID><"client_id">
功能:
设置 MQTT 客户端 ID, 将会覆盖 AT+MQTTUSERCFG 中 clientID 参数,
用户可通过 AT+MQTTCLIENTID 设置较长的 clientID.
响应:
OK
或
ERROR
参数说明:
- LinkID: 当前只支持 0
- client_id: 对应
MQTTclientID, 用于标志client身份, 最长 256 字节
AT+MQTTUSERNAME - 配置 MQTT 登录用户名
设置指令:
AT+MQTTUSERNAME=<LinkID><"username">
功能:
设置 MQTT 登录用户名, 将会覆盖 AT+MQTTUSERCFG 中 username 参数,
用户可通过 AT+MQTTUSERNAME 设置较长的用户名.
响应:
OK
或
ERROR
参数说明:
- LinkID: 当前只支持 0
- username: 对应
MQTTusername, 用于登录 MQTT broker, 最长 256 字节
AT+MQTTPASSWORD - 配置 MQTT 登录密码
设置指令:
AT+MQTTPASSWORD=<LinkID><"password">
功能:
设置 MQTT 登录密码, 将会覆盖 AT+MQTTUSERCFG 中 password 参数,
用户可通过 AT+MQTTPASSWORD 设置较长的密码.
响应:
OK
或
ERROR
参数说明:
- LinkID: 当前只支持 0
- password: 对应
MQTTpassword, 用于登录 MQTT broker, 最长 256 字节
AT+MQTTCONNCFG - 配置 MQTT 连接属性
设置指令:
AT+MQTTCONNCFG=<LinkID>,<keepalive>,<disable_clean_session>,<"lwt_topic">,<"lwt_msg">,<lwt_qos>,<lwt_retain>
功能:
设置 MQTT 连接配置
响应:
OK
或
ERROR
参数说明:
- LinkID: 当前只支持 0
- keepalive:
MQTTPING超时时间,范围为 [60, 7200], 单位为秒. 默认120 - disable_clean_session:
MQTT清理会话标志, 参数为 0 或 1, 默认为 0 - lwt_topic: 遗嘱
topic, 最长 64 字节 - lwt_msg: 遗嘱
message, 最长 64 字节 - lwt_qos: 遗嘱
QoS, 参数可选 0, 1, 2, 默认为 0 - lwt_retain: 遗嘱
retain, 参数可选 0, 1, 默认为 0
AT+MQTTCONN
设置指令:
AT+MQTTCONN=<LinkID>,<"host">,<port>,<reconnect>
功能:
连接指定 MQTT broker
响应:
OK
或
ERROR
查询指令:
AT+MQTTCONN?
功能:
查询 AT 已连接的 MQTT broker
响应:
+MQTTCONN:<LinkID>,<state>,<scheme><"host">,<port>,<"path">,<reconnect>
OK
参数说明:
- LinkID: 当前只支持 0
- host: 连接
MQTT broker域名, 最大 128 字节 - port: 连接
MQTT broker端口, 最大 65535 - path: 资源路径, 最长 32 字节
- reconnect: 是否重连 MQTT, 若设置为 1, 需要消耗较多内存资源
- state:
MQTT当前状态, 状态说明如下:- 0: 连接未初始化
- 1: 已设置
MQTTUSERCFG - 2: 已设置
MQTTCONNCFG - 3: 连接已断开
- 4: 已建立连接
- 5: 已连接, 但未订阅
topic - 6: 已连接, 已订阅过
topic
- scheme:
- 1:
MQTT over TCP - 2:
MQTT over TLS(no certificate verify) - 3:
MQTT over TLS(verify server certificate) - 4:
MQTT over TLS(provide client certificate) - 5:
MQTT over TLS(verify server certificate and provide client certificate) - 6:
MQTT over WebSocket(based on TCP) - 7:
MQTT over WebSocket Secure(based on TLS, no certificate verify) - 8:
MQTT over WebSocket Secure(based on TLS, verify server certificate) - 9:
MQTT over WebSocket Secure(based on TLS, provide client certificate) - 10:
MQTT over WebSocket Secure(based on TLS, verify server certificate and provide client certificate)
- 1:
AT+MQTTPUB
设置指令:
AT+MQTTPUB=<LinkID>,<"topic">,<"data">,<qos>,<retain>
功能:
在 LinkID上通过 topic 发布数据 data, 其中 data 为字符串消息, 若要发布二进制,请使用 AT+MQTTPUBRAW
响应:
OK
或
ERROR
参数说明:
- LinkID: 当前只支持 0
- topic: 发布主题, 最长 64 字节
- data: 发布消息,
data不能包含\0, 请确保整条AT+MQTTPUB不超过 AT 指令的最大长度限制 - qos: 发布服务质量, 参数可选 0,1,2, 默认为 0
- retain: 发布
retain
AT+MQTTPUBRAW
设置指令:
AT+MQTTPUBRAW=<LinkID>,<"topic">,<length>,<qos>,<retain>
功能:
在 LinkID 上通过 topic 发布数据 data, 其中 data 为二进制数据
响应:
OK
>
或
ERROR
等待用户输入 length 大小数据, 之后响应如下:
+MQTTPUB:FAIL
或
+MQTTPUB:OK
参数说明:
- LinkID: 当前只支持 0
- topic: 发布主题, 最长 64 字节
- length: 要发布消息长度, 默认最长为 1024, 可通过
make menuconfig的MQTT_BUFFER_SIZE_BYTE配置 - qos: 发布服务质量, 参数可选 0,1,2, 默认为 0
- retain: 发布
retain
AT port 未收到指定 length 长度的数据, 将一直等待, 在此期间接收到的数据都会当成普通数据
AT+MQTTSUB
设置指令:
AT+MQTTSUB=<LinkID>,<"topic">,<qos>
功能:
订阅指定连接的 MQTT 主题, 可重复多次订阅不同 topic
响应:
OK
或
ERROR
当收到对应主题订阅的
MQTT消息时, 将按照如下格式打印消息内容
+MQTTSUBRECV:<LinkID>,<"topic">,<data_length>,data
如果订阅已订阅过的主题, 仍无条件向
MQTT broker订阅,Log口打印ALREADY SUBSCRIBE
查询指令:
AT+MQTTSUB?
功能:
查询 MQTT 所有连接上已订阅的 topic
响应:
+MQTTSUB:<LinkID>,<state>,<"topic1">,<qos>
+MQTTSUB:<LinkID>,<state>,<"topic2">,<qos>
+MQTTSUB:<LinkID>,<state>,<"topic3">,<qos>
...
OK
或
ERROR
参数说明:
- LinkID: 当前只支持 0
- state:
MQTT当前状态, 状态说明如下:- 0: 连接未初始化
- 1: 已设置
MQTTUSERCFG - 2: 已设置
MQTTCONNCFG - 3: 连接已断开
- 4: 已建立连接
- 5: 已连接, 但未订阅
topic - 6: 已连接, 已订阅过
topic
- topic*: 订阅过的主题
- qos: 订阅过的
QoS
AT+MQTTUNSUB
设置指令:
AT+MQTTUNSUB=<LinkID>,<"topic">
功能:
取消订阅指定连接的 MQTT 主题, 可多次取消不同订阅 topic
响应:
OK
或
ERROR
参数说明:
- LinkID: 当前只支持 0
- topic: 取消订阅主题, 最长 64 字节
如果取消未订阅的主题, 仍无条件向
MQTT broker取消订阅,Log口打印NO UNSUBSCRIBE
AT+MQTTCLEAN
设置指令:
AT+MQTTCLEAN=<LinkID>
功能:
关闭 MQTT Client 为 LinkID 的连接, 并释放内部占用的资源
响应:
OK
或
ERROR
参数说明:
- LinkID: 当前只支持 0
MQTT 状态码说明
用户可在 AT LOG 口(默认 UART0) 或 AT 命令口( 默认 UART1, 查看 LOG 需使能 AT+SYSLOG=1), 查看 MQTT 相关状态反馈.
AT 管脚, 接线, UART 等配置请参考 How to Set AT Port Pin
在 MQTT 配置交互等过程中, 若出现 ERR CODE:0x<%08x>, 请查阅如下 MQTT 状态码.
AT_MQTT_NO_CONFIGURED, // 0x6001
AT_MQTT_NOT_IN_CONFIGURED_STATE, // 0x6002
AT_MQTT_UNINITIATED_OR_ALREADY_CLEAN, // 0x6003
AT_MQTT_ALREADY_CONNECTED, // 0x6004
AT_MQTT_MALLOC_FAILED, // 0x6005
AT_MQTT_NULL_LINK, // 0x6006
AT_MQTT_NULL_PARAMTER, // 0x6007
AT_MQTT_PARAMETER_COUNTS_IS_WRONG, // 0x6008
AT_MQTT_TLS_CONFIG_ERROR, // 0x6009
AT_MQTT_PARAM_PREPARE_ERROR, // 0x600A
AT_MQTT_CLIENT_START_FAILED, // 0x600B
AT_MQTT_CLIENT_PUBLISH_FAILED, // 0x600C
AT_MQTT_CLIENT_SUBSCRIBE_FAILED, // 0x600D
AT_MQTT_CLIENT_UNSUBSCRIBE_FAILED, // 0x600E
AT_MQTT_CLIENT_DISCONNECT_FAILED, // 0x600F
AT_MQTT_LINK_ID_READ_FAILED, // 0x6010
AT_MQTT_LINK_ID_VALUE_IS_WRONG, // 0x6011
AT_MQTT_SCHEME_READ_FAILED, // 0x6012
AT_MQTT_SCHEME_VALUE_IS_WRONG, // 0x6013
AT_MQTT_CLIENT_ID_READ_FAILED, // 0x6014
AT_MQTT_CLIENT_ID_IS_NULL, // 0x6015
AT_MQTT_CLIENT_ID_IS_OVERLENGTH, // 0x6016
AT_MQTT_USERNAME_READ_FAILED, // 0x6017
AT_MQTT_USERNAME_IS_NULL, // 0x6018
AT_MQTT_USERNAME_IS_OVERLENGTH, // 0x6019
AT_MQTT_PASSWORD_READ_FAILED, // 0x601A
AT_MQTT_PASSWORD_IS_NULL, // 0x601B
AT_MQTT_PASSWORD_IS_OVERLENGTH, // 0x601C
AT_MQTT_CERT_KEY_ID_READ_FAILED, // 0x601D
AT_MQTT_CERT_KEY_ID_VALUE_IS_WRONG, // 0x601E
AT_MQTT_CA_ID_READ_FAILED, // 0x601F
AT_MQTT_CA_ID_VALUE_IS_WRONG, // 0x6020
AT_MQTT_CA_LENGTH_ERROR, // 0x6021
AT_MQTT_CA_READ_FAILED, // 0x6022
AT_MQTT_CERT_LENGTH_ERROR, // 0x6023
AT_MQTT_CERT_READ_FAILED, // 0x6024
AT_MQTT_KEY_LENGTH_ERROR, // 0x6025
AT_MQTT_KEY_READ_FAILED, // 0x6026
AT_MQTT_PATH_READ_FAILED, // 0x6027
AT_MQTT_PATH_IS_NULL, // 0x6028
AT_MQTT_PATH_IS_OVERLENGTH, // 0x6029
AT_MQTT_VERSION_READ_FAILED, // 0x602A
AT_MQTT_KEEPALIVE_READ_FAILED, // 0x602B
AT_MQTT_KEEPALIVE_IS_NULL, // 0x602C
AT_MQTT_KEEPALIVE_VALUE_IS_WRONG, // 0x602D
AT_MQTT_DISABLE_CLEAN_SESSION_READ_FAILED, // 0x602E
AT_MQTT_DISABLE_CLEAN_SESSION_VALUE_IS_WRONG, // 0x602F
AT_MQTT_LWT_TOPIC_READ_FAILED, // 0x6030
AT_MQTT_LWT_TOPIC_IS_NULL, // 0x6031
AT_MQTT_LWT_TOPIC_IS_OVERLENGTH, // 0x6032
AT_MQTT_LWT_MSG_READ_FAILED, // 0x6033
AT_MQTT_LWT_MSG_IS_NULL, // 0x6034
AT_MQTT_LWT_MSG_IS_OVERLENGTH, // 0x6035
AT_MQTT_LWT_QOS_READ_FAILED, // 0x6036
AT_MQTT_LWT_QOS_VALUE_IS_WRONG, // 0x6037
AT_MQTT_LWT_RETAIN_READ_FAILED, // 0x6038
AT_MQTT_LWT_RETAIN_VALUE_IS_WRONG, // 0x6039
AT_MQTT_HOST_READ_FAILED, // 0x603A
AT_MQTT_HOST_IS_NULL, // 0x603B
AT_MQTT_HOST_IS_OVERLENGTH, // 0x603C
AT_MQTT_PORT_READ_FAILED, // 0x603D
AT_MQTT_PORT_VALUE_IS_WRONG, // 0x603E
AT_MQTT_RECONNECT_READ_FAILED, // 0x603F
AT_MQTT_RECONNECT_VALUE_IS_WRONG, // 0x6040
AT_MQTT_TOPIC_READ_FAILED, // 0x6041
AT_MQTT_TOPIC_IS_NULL, // 0x6042
AT_MQTT_TOPIC_IS_OVERLENGTH, // 0x6043
AT_MQTT_DATA_READ_FAILED, // 0x6044
AT_MQTT_DATA_IS_NULL, // 0x6045
AT_MQTT_DATA_IS_OVERLENGTH, // 0x6046
AT_MQTT_QOS_READ_FAILED, // 0x6047
AT_MQTT_QOS_VALUE_IS_WRONG, // 0x6048
AT_MQTT_RETAIN_READ_FAILED, // 0x6049
AT_MQTT_RETAIN_VALUE_IS_WRONG, // 0x604A
AT_MQTT_PUBLISH_LENGTH_READ_FAILED, // 0x604B
AT_MQTT_PUBLISH_LENGTH_VALUE_IS_WRONG, // 0x604C
AT_MQTT_RECV_LENGTH_IS_WRONG, // 0x604D
AT_MQTT_CREATE_SEMA_FAILED, // 0x604E
AT_MQTT_CREATE_EVENT_GROUP_FAILED, // 0x604F
其他说明
- 除
AT+MQTTCONN之外, MQTT 相关命令最长会在 10s 内返回, 例如路由已无法连接因特网,AT+MQTTPUB将在 10s 内返回. - 如果
AT+MQTTCONN是基于 TLS 连接的, 每个步骤的超时时间为 10s, 总的超时时间取决于服务器的交互步骤. - 一旦 MQTT 连接断开, 将打印
+MQTTDISCONNECTED:<LinkID> - 一旦 MQTT 连接成功, 将打印
+MQTTCONNECTED:<LinkID>,<scheme>,<"host">,port,<"path">,<reconnect>
测试命令一: MQTT over TCP (需要本地创建 MQTT Broker)
使用 MQTT over TCP 连接 MQTT broker, 假设 MQTT broker IP 为 192.168.31.113, 端口为 1883, 则订阅和发布 topic 参考步骤如下：
AT+MQTTUSERCFG=0,1,"ESP32","espressif","1234567890",0,0,""
AT+MQTTCONN=0,"192.168.31.113",1883,0
AT+MQTTSUB=0,"topic",1
AT+MQTTPUB=0,"topic","test",1,0
AT+MQTTCLEAN=0
测试命令二: MQTT over TLS (需要本地创建 MQTT Broker)
使用 MQTT over TLS 连接 MQTT broker, 假设 MQTT broker IP 为 192.168.31.113, 端口为 1883, 则订阅和发布 topic 参考步骤如下：
AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com"
AT+CIPSNTPTIME?
AT+MQTTUSERCFG=0,3,"ESP32","espressif","1234567890",0,0,""
AT+MQTTCONNCFG=0,0,0,"lwtt","lwtm",0,0
AT+MQTTCONN=0,"192.168.31.113",1883,0
AT+MQTTSUB=0,"topic",1
AT+MQTTPUB=0,"topic","test",1,0
AT+MQTTCLEAN=0
测试命令三: MQTT over WSS
使用 MQTT over WSS 连接 MQTT broker: iot.eclipse.org（当前 iot.eclipse.org 开放测试端口为 443）,则订阅和发布 topic 参考步骤如下：
AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com"
AT+CIPSNTPTIME?
AT+MQTTUSERCFG=0,7,"ESP32","espressif","1234567890",0,0,"wss"
AT+MQTTCONN=0,"iot.eclipse.org",443,0
AT+MQTTSUB=0,"topic",1
AT+MQTTPUB=0,"topic","test",1,0
AT+MQTTCLEAN=0
