MQTT AT Commands¶
- AT+MQTTUSERCFG：设置 MQTT 用户属性
- AT+MQTTCLIENTID：设置 MQTT 客户端 ID
- AT+MQTTUSERNAME：设置 MQTT 登陆用户名
- AT+MQTTPASSWORD：设置 MQTT 登陆密码
- AT+MQTTCONNCFG：设置 MQTT 连接属性
- AT+MQTTCONN：连接 MQTT Broker
- AT+MQTTPUB：发布 MQTT 消息（字符串）
- AT+MQTTPUBRAW：发布 MQTT 消息（二进制）
- AT+MQTTSUB：订阅 MQTT Topic
- AT+MQTTUNSUB：取消订阅 MQTT Topic
- AT+MQTTCLEAN：断开 MQTT 连接
- MQTT AT 错误码
- MQTT AT 说明
AT+MQTTUSERCFG：设置 MQTT 用户属性¶
设置命令¶
功能：
配置 MQTT 用户属性
命令：
AT+MQTTUSERCFG=<LinkID>,<scheme>,<"client_id">,<"username">,<"password">,<cert_key_ID>,<CA_ID>,<"path">
响应：
OK
参数¶
- <LinkID>：当前仅支持 link ID 0。
- <scheme>：
- 1: MQTT over TCP；
- 2: MQTT over TLS（不校验证书）；
- 3: MQTT over TLS（校验 server 证书）；
- 4: MQTT over TLS（提供 client 证书）；
- 5: MQTT over TLS（校验 server 证书并且提供 client 证书）；
- 6: MQTT over WebSocket（基于 TCP）；
- 7: MQTT over WebSocket Secure（基于 TLS，不校验证书）；
- 8: MQTT over WebSocket Secure（基于 TLS，校验 server 证书）；
- 9: MQTT over WebSocket Secure（基于 TLS，提供 client 证书）；
- 10: MQTT over WebSocket Secure（基于 TLS，校验 server 证书并且提供 client 证书）。
- <client_id>：MQTT 客户端 ID，最大长度：256 字节。
- <username>：用户名，用于登陆 MQTT broker，最大长度：64 字节。
- <password>：密码，用于登陆 MQTT broker，最大长度：64 字节。
- <cert_key_ID>：证书 ID，目前 ESP-AT 仅支持一套 cert 证书，参数为 0。
- <CA_ID>：CA ID，目前 ESP-AT 仅支持一套 CA 证书，参数为 0。
- <path>：资源路径，最大长度：32 字节。
说明¶
- 每条 AT 命令的总长度不能超过 256 字节。
AT+MQTTCLIENTID：设置 MQTT 客户端 ID¶
参数¶
- <LinkID>：当前仅支持 link ID 0。
- <client_id>：MQTT 客户端 ID。
说明¶
- 每条 AT 命令的总长度不能超过 256 字节。
- AT+MQTTUSERCFG 命令也可以设置 MQTT 客户端 ID，二者之间的差别包括：
AT+MQTTCLIENTID命令可以用来设置相对较长的客户端 ID，因为AT+MQTTUSERCFG命令的长度受限；- 应在设置
AT+MQTTUSERCFG后再使用AT+MQTTCLIENTID。
AT+MQTTUSERNAME：设置 MQTT 登陆用户名¶
参数¶
- <LinkID>：当前仅支持 link ID 0。
- <username>：用于登陆 MQTT broker 的用户名。
说明¶
- 每条 AT 命令的总长度不能超过 256 字节。
- AT+MQTTUSERCFG 命令也可以设置 MQTT 用户名，二者之间的差别包括：
AT+MQTTUSERNAME命令可以用来设置相对较长的用户名，因为AT+MQTTUSERCFG命令的长度受限。- 应在设置
AT+MQTTUSERCFG后再使用AT+MQTTUSERNAME。
AT+MQTTPASSWORD：设置 MQTT 登陆密码¶
参数¶
- <LinkID>：当前仅支持 link ID 0。
- <password>：用于登陆 MQTT broker 的密码。
说明¶
- 每条 AT 命令的总长度不能超过 256 字节。
- AT+MQTTUSERCFG 命令也可以设置 MQTT 密码，二者之间的差别包括：
AT+MQTTPASSWORD可以用来设置相对较长的密码，因为AT+MQTTUSERCFG命令的长度受限；- 应在设置
AT+MQTTUSERCFG后再使用AT+MQTTPASSWORD。
AT+MQTTCONNCFG：设置 MQTT 连接属性¶
设置命令¶
功能：
设置 MQTT 连接属性
命令：
AT+MQTTCONNCFG=<LinkID>,<keepalive>,<disable_clean_session>,<"lwt_topic">,<"lwt_msg">,<lwt_qos>,<lwt_retain>
响应：
OK
参数¶
- <LinkID>：当前仅支持 link ID 0。
- <keepalive>：MQTT ping 超时时间，单位：秒。范围：[0,7200]。默认值：0，会被强制改为 120 秒。
- <disable_clean_session>：设置 MQTT 清理会话标志，有关该参数的更多信息请参考 MQTT 3.1.1 协议中的 Clean Session 章节。
- 0: 使能清理会话
- 1: 禁用清理会话
- <lwt_topic>：遗嘱 topic，最大长度：128 字节。
- <lwt_msg>：遗嘱 message，最大长度：64 字节。
- <lwt_qos>：遗嘱 QoS，参数可选 0、1、2，默认值：0。
- <lwt_retain>：遗嘱 retain，参数可选 0 或 1，默认值：0。
AT+MQTTCONN：连接 MQTT Broker¶
查询命令¶
功能：
查询 ESP 设备已连接的 MQTT broker
命令：
AT+MQTTCONN?
响应：
+MQTTCONN:<LinkID>,<state>,<scheme><"host">,<port>,<"path">,<reconnect>
OK
参数¶
- <LinkID>：当前仅支持 link ID 0。
- <host>：MQTT broker 域名，最大长度：128 字节。
- <port>：MQTT broker 端口，最大端口：65535。
- <path>：资源路径，最大长度：32 字节。
- <reconnect>：
- 0: MQTT 不自动重连；
- 1: MQTT 自动重连，会消耗较多的内存资源。
- <state>：MQTT 状态：
- 0: MQTT 未初始化；
- 1: 已设置
AT+MQTTUSERCFG； - 2: 已设置
AT+MQTTCONNCFG； - 3: 连接已断开；
- 4: 已建立连接；
- 5: 已连接，但未订阅 topic；
- 6: 已连接，已订阅过 topic。
- <scheme>：
- 1: MQTT over TCP；
- 2: MQTT over TLS（不校验证书）；
- 3: MQTT over TLS（校验 server 证书）；
- 4: MQTT over TLS（提供 client 证书）；
- 5: MQTT over TLS（校验 server 证书并且提供 client 证书）；
- 6: MQTT over WebSocket（基于 TCP）；
- 7: MQTT over WebSocket Secure（基于 TLS，不校验证书）；
- 8: MQTT over WebSocket Secure（基于 TLS，校验 server 证书）；
- 9: MQTT over WebSocket Secure（基于 TLS，提供 client 证书）；
- 10: MQTT over WebSocket Secure（基于 TLS，校验 server 证书并且提供 client 证书）。
AT+MQTTPUB：发布 MQTT 消息（字符串）¶
设置命令¶
功能：
通过 topic 发布 MQTT 字符串 消息，若要发布 二进制 消息，请使用 AT+MQTTPUBRAW 命令。
命令：
AT+MQTTPUB=<LinkID>,<"topic">,<"data">,<qos>,<retain>
响应：
OK
参数¶
- <LinkID>：当前仅支持 link ID 0。
- <topic>：MQTT topic，最大长度：128 字节。
- <data>：MQTT 字符串消息。
- <qos>：发布消息的 QoS，参数可选 0、1、或 2，默认值：0。
- <retain>：发布 retain。
说明¶
- 每条 AT 命令的总长度不能超过 256 字节。
- 本命令不能发送数据
\0，若需要发送该数据，请使用 AT+MQTTPUBRAW 命令。
AT+MQTTPUBRAW：发布 MQTT 消息（二进制）¶
设置命令¶
功能：
通过 topic 发布 MQTT 二进制 消息
命令：
AT+MQTTPUBRAW=<LinkID>,<"topic">,<length>,<qos>,<retain>
响应：
OK
>
符号 > 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 <length> 的值时，数据传输开始。
若传输成功，则 AT 返回：
+MQTTPUB:OK
若传输失败，则 AT 返回：
+MQTTPUB:FAIL
参数¶
- <LinkID>：当前仅支持 link ID 0。
- <topic>：MQTT topic，最大长度：128 字节。
- <length>：MQTT 消息长度，不同 ESP 设备的最大长度不同：
- 对于 ESP32 设备：最大长度受到可利用内存的限制；
- 对于 ESP8266 设备，最大长度受到可利用内存和
MQTT_BUFFER_SIZE_BYTE宏的限制。该宏的默认值为512，可在build.py menuconfig中设置它的值，以此更改对最大长度的限制。该宏的值 = 消息的最大长度 + MQTT 报头长度（取决于 topic 名称的长度）。
- <qos>：发布消息的 QoS，参数可选 0、1、或 2，默认值：0。
- <retain>：发布 retain。
AT+MQTTSUB：订阅 MQTT Topic¶
查询命令¶
功能：
查询已订阅的 topic
命令：
AT+MQTTSUB?
响应：
+MQTTSUB:<LinkID>,<state>,<"topic1">,<qos>
+MQTTSUB:<LinkID>,<state>,<"topic2">,<qos>
+MQTTSUB:<LinkID>,<state>,<"topic3">,<qos>
...
OK
设置命令¶
功能：
订阅指定 MQTT topic 的指定 QoS，支持订阅多个 topic
命令：
AT+MQTTSUB=<LinkID>,<"topic">,<qos>
响应：
OK
当 AT 接收到已订阅的 topic 的 MQTT 消息时，返回：
+MQTTSUBRECV:<LinkID>,<"topic">,<data_length>,data
若已订阅过该 topic，则返回：
ALREADY SUBSCRIBE
参数¶
- <LinkID>：当前仅支持 link ID 0。
- <state>：MQTT 状态：
- 0: MQTT 未初始化；
- 1: 已设置
AT+MQTTUSERCFG； - 2: 已设置
AT+MQTTCONNCFG； - 3: 连接已断开；
- 4: 已建立连接；
- 5: 已连接，但未订阅 topic；
- 6: 已连接，已订阅过 MQTT topic。
- <topic>：订阅的 topic。
- <qos>：订阅的 QoS。
AT+MQTTUNSUB：取消订阅 MQTT Topic¶
设置命令¶
功能：
客户端取消订阅指定 topic，可多次调用本命令，以取消订阅不同的 topic。
命令：
AT+MQTTUNSUB=<LinkID>,<"topic">
响应：
OK
若未订阅过该 topic，则返回：
NO UNSUBSCRIBE
OK
参数¶
- <LinkID>：当前仅支持 link ID 0。
- <topic>：MQTT topic，最大长度：128 字节。
AT+MQTTCLEAN：断开 MQTT 连接¶
参数¶
- <LinkID>：当前仅支持 link ID 0。
MQTT AT 错误码¶
MQTT 错误码以 ERR CODE:0x<%08x> 形式打印。
| 错误类型 | 错误码 |
|---|---|
| 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_MQTT_URI_PARSE_FAILED | 0x6050 |
| AT_MQTT_IN_DISCONNECTED_STATE | 0x6051 |
| AT_MQTT_HOSTNAME_VERIFY_FAILED | 0x6052 |
MQTT AT 说明¶
- 一般来说，AT MQTT 命令都会在 10 秒内响应，但
AT+MQTTCONN命令除外。例如，如果路由器不能上网，命令AT+MQTTPUB会在 10 秒内响应，但AT+MQTTCONN命令在网络环境不好的情况下，可能需要更多的时间用来重传数据包。 - 如果
AT+MQTTCONN是基于 TLS 连接，每个数据包的超时时间为 10 秒，则总超时时间会根据握手数据包的数量而变得更长。 - 当 MQTT 连接断开时，会提示
+MQTTDISCONNECTED:<LinkID>消息。 - 当 MQTT 连接建立时，会提示
+MQTTCONNECTED:<LinkID>,<scheme>,<"host">,port,<"path">,<reconnect>消息。