MQTT AT 命令集

[English]

介绍

重要

默认的 AT 固件支持此页面下的所有 AT 命令。如果您不需要 ESP32-C3 支持 MQTT 命令,请自行 编译 ESP-AT 工程,在第五步配置工程里选择:

  • 禁用 Component config -> AT -> AT MQTT command support

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 字节。

  • 如果 <scheme> 配置为 3、5、8、10,为了校验服务器的证书有效期,请在发送 AT+MQTTCONN 命令前确保 ESP32-C3 已获取到当前时间。(您可以发送 AT+CIPSNTPCFG 命令来配置 SNTP,获取当前时间,发送 AT+CIPSNTPTIME? 命令查询当前时间。)

AT+MQTTLONGCLIENTID:设置 MQTT 客户端 ID

设置命令

功能:

设置 MQTT 客户端 ID

命令:

AT+MQTTLONGCLIENTID=<LinkID>,<length>

响应:

OK

>

上述响应表示 AT 已准备好接收 MQTT 客户端 ID,此时您可以输入客户端 ID,当 AT 接收到的客户端 ID 长度达到 <length> 后,返回:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <length>:MQTT 客户端 ID 长度。范围:[1,1024]。

说明

  • AT+MQTTUSERCFG 命令也可以设置 MQTT 客户端 ID,二者之间的差别包括:

    • AT+MQTTLONGCLIENTID 命令可以用来设置相对较长的客户端 ID,因为 AT+MQTTUSERCFG 命令的长度受限;

    • 应在设置 AT+MQTTUSERCFG 后再使用 AT+MQTTLONGCLIENTID

AT+MQTTLONGUSERNAME:设置 MQTT 登陆用户名

设置命令

功能:

设置 MQTT 用户名

命令:

AT+MQTTLONGUSERNAME=<LinkID>,<length>

响应:

OK

>

上述响应表示 AT 已准备好接收 MQTT 用户名,此时您可以输入 MQTT 用户名,当 AT 接收到的 MQTT 用户名长度达到 <length> 后,返回:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <length>:MQTT 用户名长度。范围:[1,1024]。

说明

  • AT+MQTTUSERCFG 命令也可以设置 MQTT 用户名,二者之间的差别包括:

    • AT+MQTTLONGUSERNAME 命令可以用来设置相对较长的用户名,因为 AT+MQTTUSERCFG 命令的长度受限。

    • 应在设置 AT+MQTTUSERCFG 后再使用 AT+MQTTLONGUSERNAME

AT+MQTTLONGPASSWORD:设置 MQTT 登陆密码

设置命令

功能:

设置 MQTT 密码

命令:

AT+MQTTLONGPASSWORD=<LinkID>,<length>

响应:

OK

>

上述响应表示 AT 已准备好接收 MQTT 密码,此时您可以输入 MQTT 密码,当 AT 接收到的 MQTT 密码长度达到 <length> 后,返回:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <length>:MQTT 密码长度。范围:[1,1024]。

说明

  • AT+MQTTUSERCFG 命令也可以设置 MQTT 密码,二者之间的差别包括:

    • AT+MQTTLONGPASSWORD 可以用来设置相对较长的密码,因为 AT+MQTTUSERCFG 命令的长度受限;

    • 应在设置 AT+MQTTUSERCFG 后再使用 AT+MQTTLONGPASSWORD

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+MQTTALPN:设置 MQTT 应用层协议协商(ALPN)

设置命令

功能:

设置 MQTT 应用层协议协商(ALPN)

命令:

AT+MQTTALPN=<LinkID>,<alpn_counts>[,<"alpn">][,<"alpn">][,<"alpn">]

响应:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <alpn_counts>:<”alpn”> 参数个数。范围:[0,5]。

    • 0:清除 MQTT ALPN 配置

    • [1,5]:设置 MQTT ALPN 配置

  • <”alpn”>:字符串参数,表示 ClientHello 中的 ALPN,用户可以发送多个 ALPN 字段到服务器。

说明

  • 整条 AT 命令长度应小于 256 字节。

  • 只有在 MQTT 基于 TLS 或 WSS 时,MQTT ALPN 字段才会生效。

  • 应在设置 AT+MQTTUSERCFG 后再使用 AT+MQTTALPN

示例

AT+CWMODE=1
AT+CWJAP="ssid","password"
AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com","ntp2.aliyun.com"
AT+MQTTUSERCFG=0,5,"ESP32-C3","espressif","1234567890",0,0,""
AT+MQTTALPN=0,2,"mqtt-ca.cn","mqtt-ca.us"
AT+MQTTCONN=0,"192.168.200.2",8883,1

AT+MQTTCONN:连接 MQTT Broker

查询命令

功能:

查询 ESP32-C3 设备已连接的 MQTT broker

命令:

AT+MQTTCONN?

响应:

+MQTTCONN:<LinkID>,<state>,<scheme><"host">,<port>,<"path">,<reconnect>
OK

设置命令

功能:

连接 MQTT Broker

命令:

AT+MQTTCONN=<LinkID>,<"host">,<port>,<reconnect>

响应:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <host>:MQTT broker 域名,最大长度:128 字节。

  • <port>:MQTT broker 端口,最大端口:65535。

  • <path>:资源路径,最大长度:32 字节。

  • <reconnect>

    • 0: MQTT 不自动重连。如果 MQTT 建立连接后又断开,则无法再次使用本命令重新建立连接,您需要先发送 AT+MQTTCLEAN=0 命令清理信息,重新配置参数,再建立新的连接。

    • 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 指令的长度阈值 256 字节,请使用 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+CWMODE=1
AT+CWJAP="ssid","password"
AT+MQTTUSERCFG=0,1,"ESP32-C3","espressif","1234567890",0,0,""
AT+MQTTCONN=0,"192.168.10.234",1883,0
AT+MQTTPUB=0,"topic","\"{\"timestamp\":\"20201121085253\"}\"",0,0  // 发送此命令时,请注意特殊字符是否需要转义。

AT+MQTTPUBRAW:发布长 MQTT 消息

设置命令

功能:

通过 topic 发布长 MQTT 消息。如果您发布消息的数据量相对较少,不大于单条 AT 指令的长度阈值 256 字节,也可以使用 AT+MQTTPUB 命令。

命令:

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 消息长度,不同 ESP32-C3 设备的最大长度受到可利用内存的限制。

  • <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 连接

设置命令

功能:

断开 MQTT 连接,释放资源。

命令:

AT+MQTTCLEAN=<LinkID>

响应:

OK

参数

  • <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> 消息。