ESP-AT 是乐鑫开发的可直接用于量产的物联网应用固件，旨在降低客户开发成本，快速形成产品。通过 ESP-AT 指令，您可以快速加入无线网络、连接云平台、实现数据通信以及远程控制等功能，真正的通过无线通讯实现万物互联。

ESP-AT 是基于 ESP-IDF 实现的软件工程。它使 ESP32 模组作为从机，MCU 作为主机。MCU 发送 AT 命令给 ESP32 模组，控制 ESP32 模组执行不同的操作，并接收 ESP32 模组返回的 AT 响应。ESP-AT 提供了大量功能不同的 AT 命令，如 Wi-Fi 命令、TCP/IP 命令、Bluetooth LE 命令、Bluetooth 命令、MQTT 命令、HTTP 命令、Ethernet 命令等。

AT 命令以 “AT” 开始，代表 Attention，以新的一行 (CR LF) 为结尾。输入的每条命令都会返回 OK 或 ERROR 的响应，表示当前命令的最终执行结果。注意，所有 AT 命令均为串行执行，每次只能执行一条命令。因此，在使用 AT 命令时，应等待上一条命令执行完毕后，再发送下一条命令。如果上一条命令未执行完毕，又发送了新的命令，则会返回 busy p... 提示。

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 已获取到当前时间。（您可以发送 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","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 设备已连接的 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","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 设备的最大长度受到可利用内存的限制。
  • <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_CONFIGURED0x6001
AT_MQTT_NOT_IN_CONFIGURED_STATE0x6002
AT_MQTT_UNINITIATED_OR_ALREADY_CLEAN0x6003
AT_MQTT_ALREADY_CONNECTED0x6004
AT_MQTT_MALLOC_FAILED0x6005
AT_MQTT_NULL_LINK0x6006
AT_MQTT_NULL_PARAMTER0x6007
AT_MQTT_PARAMETER_COUNTS_IS_WRONG0x6008
AT_MQTT_TLS_CONFIG_ERROR0x6009
AT_MQTT_PARAM_PREPARE_ERROR0x600A
AT_MQTT_CLIENT_START_FAILED0x600B
AT_MQTT_CLIENT_PUBLISH_FAILED0x600C
AT_MQTT_CLIENT_SUBSCRIBE_FAILED0x600D
AT_MQTT_CLIENT_UNSUBSCRIBE_FAILED0x600E
AT_MQTT_CLIENT_DISCONNECT_FAILED0x600F
AT_MQTT_LINK_ID_READ_FAILED0x6010
AT_MQTT_LINK_ID_VALUE_IS_WRONG0x6011
AT_MQTT_SCHEME_READ_FAILED0x6012
AT_MQTT_SCHEME_VALUE_IS_WRONG0x6013
AT_MQTT_CLIENT_ID_READ_FAILED0x6014
AT_MQTT_CLIENT_ID_IS_NULL0x6015
AT_MQTT_CLIENT_ID_IS_OVERLENGTH0x6016
AT_MQTT_USERNAME_READ_FAILED0x6017
AT_MQTT_USERNAME_IS_NULL0x6018
AT_MQTT_USERNAME_IS_OVERLENGTH0x6019
AT_MQTT_PASSWORD_READ_FAILED0x601A
AT_MQTT_PASSWORD_IS_NULL0x601B
AT_MQTT_PASSWORD_IS_OVERLENGTH0x601C
AT_MQTT_CERT_KEY_ID_READ_FAILED0x601D
AT_MQTT_CERT_KEY_ID_VALUE_IS_WRONG0x601E
AT_MQTT_CA_ID_READ_FAILED0x601F
AT_MQTT_CA_ID_VALUE_IS_WRONG0x6020
AT_MQTT_CA_LENGTH_ERROR0x6021
AT_MQTT_CA_READ_FAILED0x6022
AT_MQTT_CERT_LENGTH_ERROR0x6023
AT_MQTT_CERT_READ_FAILED0x6024
AT_MQTT_KEY_LENGTH_ERROR0x6025
AT_MQTT_KEY_READ_FAILED0x6026
AT_MQTT_PATH_READ_FAILED0x6027
AT_MQTT_PATH_IS_NULL0x6028
AT_MQTT_PATH_IS_OVERLENGTH0x6029
AT_MQTT_VERSION_READ_FAILED0x602A
AT_MQTT_KEEPALIVE_READ_FAILED0x602B
AT_MQTT_KEEPALIVE_IS_NULL0x602C
AT_MQTT_KEEPALIVE_VALUE_IS_WRONG0x602D
AT_MQTT_DISABLE_CLEAN_SESSION_READ_FAILED0x602E
AT_MQTT_DISABLE_CLEAN_SESSION_VALUE_IS_WRONG0x602F
AT_MQTT_LWT_TOPIC_READ_FAILED0x6030
AT_MQTT_LWT_TOPIC_IS_NULL0x6031
AT_MQTT_LWT_TOPIC_IS_OVERLENGTH0x6032
AT_MQTT_LWT_MSG_READ_FAILED0x6033
AT_MQTT_LWT_MSG_IS_NULL0x6034
AT_MQTT_LWT_MSG_IS_OVERLENGTH0x6035
AT_MQTT_LWT_QOS_READ_FAILED0x6036
AT_MQTT_LWT_QOS_VALUE_IS_WRONG0x6037
AT_MQTT_LWT_RETAIN_READ_FAILED0x6038
AT_MQTT_LWT_RETAIN_VALUE_IS_WRONG0x6039
AT_MQTT_HOST_READ_FAILED0x603A
AT_MQTT_HOST_IS_NULL0x603B
AT_MQTT_HOST_IS_OVERLENGTH0x603C
AT_MQTT_PORT_READ_FAILED0x603D
AT_MQTT_PORT_VALUE_IS_WRONG0x603E
AT_MQTT_RECONNECT_READ_FAILED0x603F
AT_MQTT_RECONNECT_VALUE_IS_WRONG0x6040
AT_MQTT_TOPIC_READ_FAILED0x6041
AT_MQTT_TOPIC_IS_NULL0x6042
AT_MQTT_TOPIC_IS_OVERLENGTH0x6043
AT_MQTT_DATA_READ_FAILED0x6044
AT_MQTT_DATA_IS_NULL0x6045
AT_MQTT_DATA_IS_OVERLENGTH0x6046
AT_MQTT_QOS_READ_FAILED0x6047
AT_MQTT_QOS_VALUE_IS_WRONG0x6048
AT_MQTT_RETAIN_READ_FAILED0x6049
AT_MQTT_RETAIN_VALUE_IS_WRONG0x604A
AT_MQTT_PUBLISH_LENGTH_READ_FAILED0x604B
AT_MQTT_PUBLISH_LENGTH_VALUE_IS_WRONG0x604C
AT_MQTT_RECV_LENGTH_IS_WRONG0x604D
AT_MQTT_CREATE_SEMA_FAILED0x604E
AT_MQTT_CREATE_EVENT_GROUP_FAILED0x604F
AT_MQTT_URI_PARSE_FAILED0x6050
AT_MQTT_IN_DISCONNECTED_STATE0x6051
AT_MQTT_HOSTNAME_VERIFY_FAILED0x6052

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

总之，ESP32 提供了丰富的 MQTT AT 命令集，为用户提供了对其 MQTT 会话的细粒度控制。这些命令对于 IoT 实现至关重要，其中有效的设备-broker 通信是必不可少的。始终确保命令按照规定的正确顺序执行，以获得最佳性能。

打赏微海报分享