基础 AT 命令¶
AT:测试 AT 启动
AT+RST:重启模块
AT+GMR:查看版本信息
AT+CMD:查询当前固件支持的所有命令及命令类型
AT+GSLP:进⼊ Deep-sleep 模式
ATE:开启或关闭 AT 回显功能
AT+RESTORE:恢复出厂设置
AT+UART_CUR:设置 UART 当前临时配置,不保存到 flash
AT+UART_DEF:设置 UART 默认配置, 保存到 flash
AT+SLEEP:设置 sleep 模式
AT+SYSRAM:查询当前剩余堆空间和最小堆空间
AT+SYSMSG:查询/设置系统提示信息
AT+USERRAM:操作用户的空闲 RAM
AT+SYSFLASH:查询或读写 flash 用户分区
[ESP32 Only] AT+FS:文件系统操作
AT+RFPOWER:查询/设置 RF TX Power
AT+SYSROLLBACK:回滚到以前的固件
AT+SYSTIMESTAMP:查询/设置本地时间戳
AT+SYSLOG:启用或禁用 AT 错误代码提示
AT+SLEEPWKCFG:设置 Light-sleep 唤醒源和唤醒 GPIO
AT+SYSSTORE:设置参数存储模式
AT+SYSREG:读写寄存器
[ESP32-S2 Only] AT+SYSTEMP:查询 ESP32-S2 内部温度
AT:测试 AT 启动¶
执行命令¶
命令:
AT
响应:
OK
AT+RST:重启模块¶
执行命令¶
命令:
AT+RST
响应:
OK
AT+GMR:查看版本信息¶
执行命令¶
命令:
AT+GMR
响应:
<AT version info>
<SDK version info>
<compile time>
<Bin version>
OK
参数¶
<AT version info>:AT 核心库的版本信息,它们在
esp-at/components/at/lib/
目录下。代码是闭源的,无开放计划。<SDK version info>:AT 使用的平台 SDK 版本信息,它们定义在
esp-at/module_config/module_{platform}_default/IDF_VERSION
文件中。<compile time>:固件生成时间。
<Bin version>: AT 固件版本信息。版本信息可以在 menuconfig 中修改。
说明¶
如果您在使用 ESP-AT 固件中有任何问题,请先提供
AT+GMR
版本信息。
示例¶
AT+GMR
AT version:2.2.0.0-dev(ca41ec4 - ESP32 - Sep 16 2020 11:28:17)
SDK version:v4.0.1-193-ge7ac221b4
compile time(98b95fc):Oct 29 2020 11:23:25
Bin version:2.1.0(MINI-1)
OK
AT+CMD:查询当前固件支持的所有命令及命令类型¶
查询命令¶
命令:
AT+CMD?
响应:
+CMD:<index>,<AT command name>,<support test command>,<support query command>,<support set command>,<support execute command>
OK
参数¶
<index>:AT 命令序号
<AT command name>:AT 命令名称
<support test command>:0 表示不支持,1 表示支持
<support query command>:0 表示不支持,1 表示支持
<support set command>:0 表示不支持,1 表示支持
<support execute command>:0 表示不支持,1 表示支持
AT+GSLP:进入 Deep-sleep 模式¶
设置命令¶
命令:
AT+GSLP=<time>
响应:
<time>
OK
参数¶
<time>:设备进入 Deep-sleep 的时长,单位:毫秒。设定时间到后,设备自动唤醒,调用深度睡眠唤醒桩,然后加载应用程序。
ESP32 和 ESP32-S2 设备:最大 Deep-sleep 时长约为 28.8 天(2 31-1 毫秒)。
ESP8266 设备:最大 Deep-sleep 时长约为 3 小时,由于硬件条件限制,更长的睡眠时间会造成设置失败或内部时间溢出。
说明¶
ESP8266 设备必须将 GPIO16 连接到 RST 管脚才能在睡眠时长结束后自行唤醒。
由于外部因素的影响,所有设备进入 Deep-sleep 的实际时长与理论时长之间会存在差异。
也可通过直接触发 ESP8266 的 RST 管脚的低电平脉冲将其从 Deep-sleep 中唤醒。
ATE:开启或关闭 AT 回显功能¶
执行命令¶
命令:
ATE0
或
ATE1
响应:
OK
参数¶
ATE0:关闭回显
ATE1:开启回显
AT+RESTORE:恢复出厂设置¶
执行命令¶
命令:
AT+RESTORE
响应:
OK
说明¶
该命令将擦除所有保存到 flash 的参数,并恢复为默认参数。
运行该命令会重启设备。
AT+UART_CUR:设置 UART 当前临时配置,不保存到 flash¶
查询命令¶
命令:
AT+UART_CUR?
响应:
+UART_CUR:<baudrate>,<databits>,<stopbits>,<parity>,<flow control>
OK
设置命令¶
命令:
AT+UART_CUR=<baudrate>,<databits>,<stopbits>,<parity>,<flow control>
响应:
OK
参数¶
<baudrate>:UART 波特率
ESP32 和 ESP32-S2 设备:支持范围为 80 ~ 5000000
ESP8266 设备:支持范围为 80 ~ 4500000
<databits>:数据位
5:5 bit 数据位
6:6 bit 数据位
7:7 bit 数据位
8:8 bit 数据位
<stopbits>:停止位
1:1 bit 停止位
2:1.5 bit 停止位
3:2 bit 停止位
<parity>:校验位
0:None
1:Odd
2:Even
<flow control>:流控
0:不使能流控
1:使能 RTS
2:使能 CTS
3:同时使能 RTS 和 CTS
说明¶
查询命令返回的是 UART 配置参数的实际值,由于时钟分频的原因,可能与设定值有细微的差异。
本设置不保存到 flash。
使用硬件流控功能需要连接设备的 CTS/RTS 管脚,详情请见 硬件连接 和
components/customized_partitions/raw_data/factory_param/factory_param_data.csv
。
示例¶
AT+UART_CUR=115200,8,1,0,3
AT+UART_DEF:设置 UART 默认配置,保存到 flash¶
查询命令¶
命令:
AT+UART_DEF?
响应:
+UART_DEF:<baudrate>,<databits>,<stopbits>,<parity>,<flow control>
OK
设置命令¶
命令:
AT+UART_DEF=<baudrate>,<databits>,<stopbits>,<parity>,<flow control>
响应:
OK
参数¶
<baudrate>:UART 波特率
ESP32 和 ESP32-S2 设备:支持范围为 80 ~ 5000000
ESP8266 设备:支持范围为 80 ~ 4500000
<databits>:数据位
5:5 bit 数据位
6:6 bit 数据位
7:7 bit 数据位
8:8 bit 数据位
<stopbits>:停止位
1:1 bit 停止位
2:1.5 bit 停止位
3:2 bit 停止位
<parity>:校验位
0:None
1:Odd
2:Even
<flow control>:流控
0:不使能流控
1:使能 RTS
2:使能 CTS
3:同时使能 RTS 和 CTS
说明¶
配置更改将保存在 NVS 分区,当设备再次上电时仍然有效。
使用硬件流控功能需要连接设备的 CTS/RTS 管脚,详情请见 硬件连接 和
components/customized_partitions/raw_data/factory_param/factory_param_data.csv
。
示例¶
AT+UART_DEF=115200,8,1,0,3
AT+SLEEP:设置睡眠模式¶
查询命令¶
命令:
AT+SLEEP?
响应:
+SLEEP:<sleep mode>
OK
设置命令¶
命令:
AT+SLEEP=<sleep mode>
响应:
OK
参数¶
说明¶
只有在 station 模式,才可以设置 Modem-sleep 和 Light-sleep 睡眠模式
设置 Light-sleep 模式前,建议提前通过 AT+SLEEPWKCFG 命令设置好唤醒源,否则没法唤醒,设备将一直处于睡眠状态
设置 Light-sleep 模式后,如果 Light-sleep 唤醒条件不满足时,设备将自动进入睡眠模式,当 Light-sleep 唤醒条件满足时,设备将自动从睡眠模式中唤醒
查询命令可以返回 0、1、3,但不能返回 2(由于 ESP-IDF 不支持此查询)。换句话说,如果设置
AT+SLEEP=2
,那么AT+SLEEP?
会返回 3,而不是 2
示例¶
AT+SLEEP=0
AT+SYSRAM:查询当前剩余堆空间和最小堆空间¶
查询命令¶
命令:
AT+SYSRAM?
响应:
+SYSRAM:<remaining RAM size>,<minimum heap size>
OK
参数¶
<remaining RAM size>:当前剩余堆空间,单位:byte
<minimum heap size>:最小堆空间,单位:byte
示例¶
AT+SYSRAM?
+SYSRAM:148408,84044
OK
AT+SYSMSG:查询/设置系统提示信息¶
查询命令¶
功能:
查询当前系统提示信息状态
命令:
AT+SYSMSG?
响应:
+SYSMSG:<state>
OK
设置命令¶
功能:
设置系统提示信息
命令:
AT+SYSMSG=<state>
响应:
OK
参数¶
<state>:
Bit0:退出 Wi-Fi 透传模式 时是否打印提示信息
0:不打印
1:打印
+QUITT
Bit1:连接时提示信息类型
0:使用简单版提示信息,如
XX,CONNECT
1:使用详细版提示信息,如
+LINK_CONN:status_type,link_id,ip_type,terminal_type,remote_ip,remote_port,local_port
Bit2:连接状态提示信息,适用于 Wi-Fi 透传模式、Bluetooth LE SPP 及 Bluetooth SPP
0:不打印提示信息
1:当 Wi-Fi、socket、Bluetooth LE 或 Bluetooth 状态发生改变时,打印提示信息,如:
- "CONNECT\r\n" 或以 "+LINK_CONN:" 开头的提示信息 - "CLOSED\r\n" - "WIFI CONNECTED\r\n" - "WIFI GOT IP\r\n" - "WIFI GOT IPv6 LL\r\n" - "WIFI GOT IPv6 GL\r\n" - "WIFI DISCONNECT\r\n" - "+ETH_CONNECTED\r\n" - "+ETH_DISCONNECTED\r\n" - 以 "+ETH_GOT_IP:" 开头的提示信息 - 以 "+STA_CONNECTED:" 开头的提示信息 - 以 "+STA_DISCONNECTED:" 开头的提示信息 - 以 "+DIST_STA_IP:" 开头的提示信息 - 以 "+BLECONN:" 开头的提示信息 - 以 "+BLEDISCONN:" 开头的提示信息
说明¶
若 AT+SYSSTORE=1,配置更改将被保存在 NVS 分区。
若设 Bit0 为 1,退出 Wi-Fi 透传模式 时会提示
+QUITT
。若设 Bit1 为 1,将会影响 AT+CIPSTART 和 AT+CIPSERVER 命令,系统将提示 “+LINK_CONN:status_type,link_id,ip_type,terminal_type,remote_ip,remote_port,local_port”,而不是 “XX,CONNECT”。
示例¶
// 退出 Wi-Fi 透传模式时不打印提示信息
// 连接时打印详细版提示信息
// 连接状态发生改变时不打印信息
AT+SYSMSG=2
AT+USERRAM: 操作用户的空闲 RAM¶
查询命令¶
功能:
查询用户当前可用的空闲 RAM 大小
命令:
AT+USERRAM?
响应:
+USERRAM:<size>
OK
设置命令¶
功能:
分配、读、写、擦除、释放用户 RAM 空间
命令:
AT+USERRAM=<operation>,<size>[,<offset>]
响应:
+USERRAM:<length>,<data> // 只有是读操作时,才会有这个回复
OK
参数¶
<operation>:
0:释放用户 RAM 空间
1:分配用户 RAM 空间
2:向用户 RAM 写数据
3:从用户 RAM 读数据
4:清除用户 RAM 上的数据
<size>: 分配/读/写的用户 RAM 大小
<offset>: 读/写 RAM 的偏移量。默认:0
说明¶
请在执行任何其他操作之前分配用户 RAM 空间。
当
<operator>
为write
时,系统收到此命令后先换行返回>
,此时您可以输入要写的数据,数据长度应与<length>
一致。当
<operator>
为read
时并且长度大于 1024,ESP-AT 会以同样格式多次回复,每次回复最多携带 1024 字节数据,最终以\r\nOK\r\n
结束。
示例¶
// 分配 1 KB 用户 RAM 空间
AT+USERRAM=1,1024
// 向 RAM 空间开始位置写入 500 字节数据
AT+USERRAM=2,500
// 从 RAM 空间偏移 100 位置读取 64 字节数据
AT+USERRAM=3,64,100
// 释放用户 RAM 空间
AT+USERRAM=0
AT+SYSFLASH:查询或读写 flash 用户分区¶
查询命令¶
功能:
查询 flash 用户分区
命令:
AT+SYSFLASH?
响应:
+SYSFLASH:<partition>,<type>,<subtype>,<addr>,<size>
OK
设置命令¶
功能:
读、写、擦除 flash 用户分区
命令:
AT+SYSFLASH=<operation>,<partition>,<offset>,<length>
响应:
+SYSFLASH:<length>,<data>
OK
参数¶
<operation>:
0:擦除分区
1:写分区
2:读分区
<partition>:用户分区名称
<offset>:偏移地址
<length>:数据长度
<type>:用户分区类型
<subtype>:用户分区子类型
<addr>:用户分区地址
<size>:用户分区大小
说明¶
使用本命令需烧录 at_customize.bin,详细信息可参考 如何自定义分区。
擦除分区时,设置指令可省略
<offset>
和<length>
参数,用于完整擦除该目标分区。例如,指令AT+SYSFLASH=0,"ble_data"
可擦除整个 “ble_data” 区域。如果擦除分区时不省略<offset>
和<length>
参数,则这两个参数值要求是 4 KB 的整数倍。关于分区的定义可参考 ESP-IDF 分区表。
当
<operator>
为write
时,系统收到此命令后先换行返回>
,此时您可以输入要写的数据,数据长度应与<length>
一致。写分区前,请先擦除该分区。
写 PKI bin 时,参数
<length>
应为 4 字节的整数倍。
示例¶
// 从 "ble_data" 分区偏移地址 0 处读取 100 字节
AT+SYSFLASH=2,"ble_data",0,100
// 在 "ble_data" 分区偏移地址 100 处写入 10 字节
AT+SYSFLASH=1,"ble_data",100,10
// 从 "ble_data" 分区偏移地址 4096 处擦除 8192 字节
AT+SYSFLASH=0,"ble_data",4096,8192
[ESP32 Only] AT+FS:文件系统操作¶
设置命令¶
命令:
AT+FS=<type>,<operation>,<filename>,<offset>,<length>
响应:
OK
参数¶
<type>:目前仅支持 FATFS
0:FATFS
<operation>:
0:删除文件
1:写文件
2:读文件
3:查询文件大小
4:查询路径下文件,目前仅支持根目录
<offset>:偏移地址,仅针对读写操作设置
<length>:长度,仅针对读写操作设置
说明¶
使用本命令需烧录 at_customize.bin,详细信息可参考 ESP-IDF 分区表 和 如何自定义分区。
若读取数据的长度大于实际文件大小,仅返回实际长度的数据。
当
<operator>
为write
时,系统收到此命令后先换行返回>
,此时您可以输入要写的数据,数据长度应与<length>
一致。
示例¶
// 删除某个文件
AT+FS=0,0,"filename"
// 在某个文件偏移地址 100 处写入 10 字节
AT+FS=0,1,"filename",100,10
// 从某个文件偏移地址 0 处读取 100 字节
AT+FS=0,2,"filename",0,100
// 列出根目录下所有文件
AT+FS=0,4,"."
AT+RFPOWER:查询/设置 RF TX Power¶
查询命令¶
功能:
查询 RF TX Power
命令:
AT+RFPOWER?
响应:
+RFPOWER:<wifi_power>,<ble_adv_power>,<ble_scan_power>,<ble_conn_power>
OK
设置命令¶
命令:
AT+RFPOWER=<wifi_power>[,<ble_adv_power>,<ble_scan_power>,<ble_conn_power>]
响应:
OK
参数¶
<wifi_power>:单位为 0.25 dBm,比如设定的参数值为 78,则实际的 RF Power 值为 78 * 0.25 dBm = 19.5 dBm。配置后可运行
AT+RFPOWER?
命令确认实际的 RF Power 值。ESP32 和 ESP32-S2 设备的取值范围为 [40,78]:
设定值
实际值
实际 dBm
[34,43]
34
8.5
[44,51]
44
11
[52,55]
52
13
[56,59]
56
14
[60,65]
60
15
[66,71]
66
16.5
[72,77]
72
18
78
78
19.5
ESP32-C3 设备的取值范围为 [40,84]:
设定值
实际值
实际 dBm
[40,80]
<设定值>
<设定值> * 0.25
[81,84]
80
20
ESP8266 设备的取值范围为 [40,82]:
设定值
实际值
实际 dBm
[40,47]
32
8
[48,55]
48
12
[56,63]
56
14
[64,67]
64
16
[68,73]
68
17
[74,77]
74
18.5
[78,81]
78
19.5
82
82
20.5
<ble_adv_power>:Bluetooth LE 广播的 RF TX Power,取值范围为 [0,7]。
0:7 dBm
1:4 dBm
2:1 dBm
3:-2 dBm
4:-5 dBm
5:-8 dBm
6:-11 dBm
7:-14 dBm
<ble_scan_power>:Bluetooth LE 扫描的 RF TX Power,取值范围及对应值同
<ble_adv_power>
参数。<ble_conn_power>:Bluetooth LE 连接的 RF TX Power,取值范围及对应值同
<ble_adv_power>
参数。
说明¶
由于 RF TX Power 分为不同的等级,而每个等级都有与之对应的取值范围,所以通过
esp_wifi_get_max_tx_power
查询到的wifi_power
的值可能与esp_wifi_set_max_tx_power
设定的值存在差异,但不会比该值大。
AT+SYSROLLBACK:回滚到以前的固件¶
执行命令¶
命令:
AT+SYSROLLBACK
响应:
OK
说明¶
本命令不通过 OTA 升级,只会回滚到另一 OTA 分区的固件。
AT+SYSTIMESTAMP:查询/设置本地时间戳¶
查询命令¶
功能:
查询本地时间戳
命令:
AT+SYSTIMESTAMP?
响应:
+SYSTIMESTAMP:<Unix_timestamp>
OK
设置命令¶
功能:
设置本地时间戳,当 SNTP 时间更新后,将与之同步更新
命令:
AT+SYSTIMESTAMP=<Unix_timestamp>
响应:
OK
参数¶
<Unix-timestamp>:Unix 时间戳,单位:秒。
示例¶
AT+SYSTIMESTAMP=1565853509 //2019-08-15 15:18:29
AT+SYSLOG:启用或禁用 AT 错误代码提示¶
查询命令¶
功能:
查询 AT 错误代码提示是否启用
命令:
AT+SYSLOG?
响应:
+SYSLOG:<status>
OK
设置命令¶
功能:
启用或禁用 AT 错误代码提示
命令:
AT+SYSLOG=<status>
响应:
OK
参数¶
<status>:错误代码提示状态
0:禁用
1:启用
示例¶
// 启用 AT 错误代码提示
AT+SYSLOG=1
OK
AT+FAKE
ERR CODE:0x01090000
ERROR
// 禁用 AT 错误代码提示
AT+SYSLOG=0
OK
AT+FAKE
// 不提示 `ERR CODE:0x01090000`
ERROR
AT 错误代码是一个 32 位十六进制数值,定义如下:
类型 |
子类型 |
扩展 |
---|---|---|
bit32 ~ bit24 |
bit23 ~ bit16 |
bit15 ~ bit0 |
category: 固定值 0x01
subcategory: 错误类型
错误类型
错误代码
说明
ESP_AT_SUB_OK
0x00
OK
ESP_AT_SUB_COMMON_ERROR
0x01
保留
ESP_AT_SUB_NO_TERMINATOR
0x02
未找到结束符(应以 “rn” 结尾)
ESP_AT_SUB_NO_AT
0x03
未找到起始 AT(输入的可能是 at、At 或 aT)
ESP_AT_SUB_PARA_LENGTH_MISMATCH
0x04
参数长度不匹配
ESP_AT_SUB_PARA_TYPE_MISMATCH
0x05
参数类型不匹配
ESP_AT_SUB_PARA_NUM_MISMATCH
0x06
参数数量不匹配
ESP_AT_SUB_PARA_INVALID
0x07
无效参数
ESP_AT_SUB_PARA_PARSE_FAIL
0x08
解析参数失败
ESP_AT_SUB_UNSUPPORT_CMD
0x09
不支持该命令
ESP_AT_SUB_CMD_EXEC_FAIL
0x0A
执行命令失败
ESP_AT_SUB_CMD_PROCESSING
0x0B
仍在执行上一条命令
ESP_AT_SUB_CMD_OP_ERROR
0x0C
命令操作类型错误
extension: 错误扩展信息,不同的子类型有不同的扩展信息,详情请见
components/at/include/esp_at.h
。
例如,错误代码 ERR CODE:0x01090000
表示“不支持该命令”。
AT+SLEEPWKCFG:设置 Light-sleep 唤醒源和唤醒 GPIO¶
设置命令¶
命令:
AT+SLEEPWKCFG=<wakeup source>,<param1>[,<param2>]
响应:
OK
参数¶
<wakeup source>: 唤醒源
0:保留配置,暂不支持
1:保留配置,暂不支持
2:GPIO 唤醒
<param1>:
当唤醒源为定时器时,该参数表示睡眠时间,单位:毫秒
当唤醒源为 GPIO 时,该参数表示 GPIO 管脚
<param2>:
当唤醒源为 GPIO 时,该参数表示唤醒电平
0:低电平
1:高电平
说明¶
在 ESP8266 平台上,作为 RTC IO 的 GPIO16 不能设为唤醒 ESP8266 设备的 GPIO 管脚。
示例¶
// GPIO12 置为低电平时唤醒
AT+SLEEPWKCFG=2,12,0
AT+SYSSTORE:设置参数存储模式¶
查询命令¶
功能:
查询 AT 参数存储模式
命令:
AT+SYSSTORE?
响应:
+SYSSTORE:<store_mode>
OK
设置命令¶
命令:
AT+SYSSTORE=<store_mode>
响应:
OK
参数¶
<store_mode>:参数存储模式
0:命令配置不存入 flash
1:命令配置存入 flash(默认)
说明¶
该命令只影响设置命令,不影响查询命令,因为查询命令总是从 RAM 中调用。
本命令会影响以下命令:
示例¶
AT+SYSSTORE=0
AT+CWMODE=1 // 不存入 flash
AT+CWJAP="test","1234567890" // 不存入 flash
AT+SYSSTORE=1
AT+CWMODE=3 // 存入 flash
AT+CWJAP="test","1234567890" // 存入 flash
AT+SYSREG:读写寄存器¶
设置命令¶
命令:
AT+SYSREG=<direct>,<address>[,<write value>]
响应:
+SYSREG:<read value> // 仅适用于读寄存器时
OK
参数¶
<direct>:读或写寄存器
0:读寄存器
1:写寄存器
<address>:(uint32) 寄存器地址,详情请参考相关的《技术参考手册》
<write value>:(uint32) 写入值,仅适用于写寄存器时
说明¶
AT 不检查寄存器地址,因此请确保操作的寄存器地址有效
示例¶
// ESP32-S2 IO33 输出,0x3F40402C 由基础地址 0x3F404000 与相对地址 0x2C (GPIO_ENABLE1_REG) 相加而来
AT+SYSREG=1,0x3F40402C,0x2
// ESP32-S2 IO33 输出高电平
AT+SYSREG=1,0x3F404010,0x2
// ESP32-S2 IO33 输出低电平
AT+SYSREG=1,0x3F404010,0x0
[ESP32-S2 Only] AT+SYSTEMP:查询 ESP32-S2 内部温度¶
查询命令¶
命令:
AT+SYSTEMP?
响应:
+SYSTEMP:<temperature>
OK
参数¶
<temperature>:测量输出值,单位:摄氏度
说明¶
测量范围:-10℃ ~ 80℃,误差小于 1℃
示例¶
AT+SYSTEMP?
+SYSTEMP:21.59
OK