AT 命令集

[English]

本章将具体介绍如何使用各类 AT 命令。如果命令前标注,如 [ESP32 Only],则表示该(类)命令只适用于 ESP32 系列,若命令前无任何标注,则表示支持所有 ESP 系列,包括 ESP32、ESP32-C3。

强烈建议在使用命令之前先阅读以下内容,了解 AT 命令的一些基本信息。

AT 命令分类

通用 AT 命令有四种类型:

类型 命令格式 说明
测试命令 AT+<命令名称>=? 查询设置命令的内部参数及其取值范围
查询命令 AT+<命令名称>? 返回当前参数值
设置命令 AT+<命令名称>=<…> 设置用户自定义的参数值,并运行命令
执行命令 AT+<命令名称> 运行无用户自定义参数的命令
  • 不是每条 AT 命令都具备上述四种类型的命令。

  • 命令里输入参数,当前只支持字符串参数和整形数字参数。

  • 尖括号 < > 内的参数不可以省略。

  • 方括号 [ ] 内的参数可以省略,省略时使用默认值。例如,运行 AT+CWJAP 命令时省略某些参数:

    AT+CWJAP="ssid","password"
    AT+CWJAP="ssid","password","11:22:33:44:55:66"
    
  • 当省略的参数后仍有参数要填写时,必须使用 ,,以示分隔,如:

    AT+CWJAP="ssid","password",,1
    
  • 使用双引号表示字符串参数,如:

    AT+CWSAP="ESP756290","21030826",1,4
    
  • 特殊字符需作转义处理,如 ,"\ 等。

    • \\:转义反斜杠。
    • \,:转义逗号,分隔参数的逗号无需转义。
    • \":转义双引号,表示字符串参数的双引号无需转义。
    • \<any>:转义 <any> 字符,即只使用 <any> 字符,不使用反斜杠。
  • 只有 AT 命令 中的特殊字符需要转义,其它地方无需转义。例如,AT 命令口打印 > 等待输入数据时,该数据不需要转义。

    AT+CWJAP="comma\,backslash\\ssid","1234567890"
    AT+MQTTPUB=0,"topic","\"{\"sensor\":012}\"",1,0
    
  • AT 命令的默认波特率为 115200。

  • 每条 AT 命令的长度不应超过 256 字节。

  • AT 命令以新行 (CR-LF) 结束,所以串口工具应设置为“新行模式”。

  • AT 命令错误代码的定义请见 AT API Reference

参数信息保存在 flash 中的 AT 命令

以下 AT 命令的参数更改将始终保存在 flash 的 NVS 区域中,因此重启后,会直接使用。

其它一些命令的参数更改是否保存到 flash 可以通过 AT+SYSSTORE 命令来配置,具体请参见命令的详细说明。

AT 消息

从 ESP-AT 命令端口返回的 ESP-AT 消息有两种类型:ESP-AT 响应(被动)和 ESP-AT 消息报告(主动)。

  • ESP-AT 响应(被动)

    每个输入的 ESP-AT 命令都会返回响应,告诉发送者 ESP-AT 命令的执行结果。

    ESP-AT 响应
    AT 响应 说明
    OK AT 命令处理完毕,返回 OK
    ERROR AT 命令错误或执行过程中发生错误
    SEND OK 数据已发送到协议栈(针对于 AT+CIPSENDAT+CIPSENDEX 命令),但不代表数据已经发到对端
    SEND FAIL 向协议栈发送数据时发生错误(针对于 AT+CIPSENDAT+CIPSENDEX 命令)
    +<Command Name>:... 详细描述 AT 命令处理结果
  • ESP-AT 消息报告(主动)

    ESP-AT 会报告系统中重要的状态变化或消息。

    ESP-AT 消息报告
    ESP-AT 消息报告 说明
    ready ESP-AT 固件已经准备就绪
    busy p… 系统繁忙,正在处理上一条命令,无法处理新的命令
    ERR CODE:<0x%08x> 不同命令的错误代码
    Will force to restart!!! 立即重启模块
    smartconfig type:<xxx> Smartconfig 类型
    Smart get wifi info Smartconfig 已获取 SSID 和 PASSWORD
    +SCRD:<length>,``<reserved data>`` ESP-Touch v2 已获取自定义数据
    smartconfig connected wifi Smartconfig 完成,ESP-AT 已连接到 Wi-Fi
    WIFI CONNECTED Wi-Fi station 接口已连接到 AP
    WIFI GOT IP Wi-Fi station 接口已获取 IPv4 地址
    WIFI GOT IPv6 LL Wi-Fi station 接口已获取 IPv6 链路本地地址
    WIFI GOT IPv6 GL Wi-Fi station 接口已获取 IPv6 全局地址
    WIFI DISCONNECT Wi-Fi station 接口已与 AP 断开连接
    +ETH_CONNECTED 以太网接口已连接
    +ETH_GOT_IP 以太网接口已获取 IPv4 地址
    +ETH_DISCONNECTED 以太网接口已断开
    [<conn_id>,]CONNECT ID 为 <conn_id> 的网络连接已建立(默认情况下,ID 为 0)
    [<conn_id>,]CLOSED ID 为 <conn_id> 的网络连接已断开(默认情况下,ID 为 0)
    +LINK_CONN TCP/UDP/SSL 连接的详细信息
    +STA_CONNECTED: <sta_mac> station 已连接到 ESP-AT 的 Wi-Fi softAP 接口
    +DIST_STA_IP: <sta_mac>,<sta_ip> ESP-AT 的 Wi-Fi softAP 接口给 station 分配 IP 地址
    +STA_DISCONNECTED: <sta_mac> station 与 ESP-AT 的 Wi-Fi softAP 接口的连接断开
    > ESP-AT 正在等待用户输入数据
    Recv <xxx> bytes ESP-AT 从命令端口已接收到 <xxx> 字节
    +IPD ESP-AT 已收到来自网络的数据
    SEND Canceled 取消在 Wi-Fi 普通传输模式 下发送数据
    Have <xxx> Connections 已达到服务器的最大连接数
    +QUITT ESP-AT 退出 Wi-Fi 透传模式
    NO CERT FOUND 在自定义分区中没有找到有效的设备证书
    NO PRVT_KEY FOUND 在自定义分区中没有找到有效的私钥
    NO CA FOUND 在自定义分区中没有找到有效的 CA 证书
    +MQTTCONNECTED MQTT 已连接到 broker
    +MQTTDISCONNECTED MQTT 与 broker 已断开连接
    +MQTTSUBRECV MQTT 已从 broker 收到数据
    +MQTTPUB:FAIL MQTT 发布数据失败
    +MQTTPUB:OK MQTT 发布数据完成
    +BLECONN Bluetooth LE 连接已建立
    +BLEDISCONN Bluetooth LE 连接已断开
    +READ 通过 Bluetooth LE 连接进行读取操作
    +WRITE 通过 Bluetooth LE 进行写入操作
    +NOTIFY 来自 Bluetooth LE 连接的 notification
    +INDICATE 来自 Bluetooth LE 连接的 indication
    +BLESECNTFYKEY Bluetooth LE SMP 密钥
    +BLESECREQ:<conn_index> 收到来自 Bluetooth LE 连接的加密配对请求
    +BLEAUTHCMPL:<conn_index>,<enc_result> Bluetooth LE SMP 配对完成