ESP-AT 用户指南¶

本文档为 ESP-AT 官方文档。若要查看某一版本的 AT 固件或某一芯片系列的文档，可点击页面左下角的三角符号进行选择。


入门	AT Binary 列表	AT 命令集

AT 命令示例	编译和开发	第三方定制化 AT 命令和固件

入门指南¶

[English]

本指南详细介绍 ESP-AT 是什么、如何连接硬件、以及如何下载和烧录 AT 固件，由以下章节组成：

ESP-AT 是什么¶

[English]

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

ESP-AT 是基于 ESP-IDF 实现的软件工程。它使 ESP 模组作为从机，MCU 作为主机。MCU 发送 AT 命令给 ESP 模组，控制 ESP 模组执行不同的操作，并接收 ESP 模组返回的 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 命令的信息可参见 AT 命令集。

默认配置下，MCU 通过 UART 连接至 ESP 模组、发送 AT 命令以及接收 AT 响应。但是，您也可以根据实际使用情况修改程序，使用其他的通信接口，例如 SDIO。

同样，您也可以基于 ESP-AT 工程，自行开发更多的 AT 命令，以实现更多的功能。

硬件连接¶

[English]

本文档主要介绍下载和烧录 AT 固件、发送 AT 命令和接收 AT 响应所需要的硬件以及硬件之间该如何连接，主要涉及以下 ESP 系列的模组：

ESP32 系列
ESP32-C3 系列

对于不同系列的模组，AT 默认固件所支持的命令会有所差异。具体可参考 ESP-AT 固件差异。

硬件准备¶

ESP-AT 测试所需硬件¶
硬件	功能
ESP 开发板	从机
USB 数据线（连接 ESP 开发板和 PC）	下载固件、输出日志数据连接
PC	主机，将固件下载至从机
USB 数据线（连接 PC 和 USB 转 UART 串口模块）	发送 AT 命令、接收 AT 响应数据连接
USB 转 UART 串口模块	转换 USB 信号和 TTL 信号
杜邦线（连接 USB 转 UART 串口模块和 ESP 开发板）	发送 AT 命令、接收 AT 响应数据连接

注意：上图使用 4 根杜邦线连接 ESP 开发板和 USB 转 UART 串口模块，但如果您不使用硬件流控功能，只需 2 根杜邦线连接 TX/RX 即可。

ESP32 系列¶

ESP32 AT 采用两个 UART 接口：UART0 用于下载固件和输出日志，UART1 用于发送 AT 命令和接收 AT 响应。默认情况下，UART0 和 UART1 均使用 115200 波特率进行通信。

所有 ESP32 模组均连接 GPIO1 和 GPIO3 作为 UART0，但连接不同的 GPIO 作为 UART1，下文将详细介绍如何连接 ESP32 系列模组。

更多有关 ESP32 模组和开发板的信息可参考 ESP32 系列模组和开发板。

ESP32-WROOM-32 系列¶

ESP32-WROOM-32 系列硬件连接管脚分配¶
功能	ESP 开发板管脚	其它设备管脚
下载固件/输出日志 ¹	UART0 GPIO3 (RX) GPIO1 (TX)	PC TX RX
AT 命令/响应 ²	UART1 GPIO16 (RX) GPIO17 (TX) GPIO15 (CTS) GPIO14 (RTS)	USB 转 UART 串口模块 TX RX RTS CTS

说明 1：ESP 开发板和 PC 之间的管脚连接已内置在 ESP 开发板上，您只需使用 USB 数据线连接开发板和 PC 即可。

说明 2：CTS/RTS 管脚只有在使用硬件流控功能时才需连接。

如果需要直接基于 ESP32-WROOM-32 模组进行连接，请参考《ESP32-WROOM-32 技术规格书》。

ESP32-WROVER 系列¶

ESP32-WROVER 系列硬件连接管脚分配¶
功能	ESP 开发板管脚	其它设备管脚
下载固件/输出日志 ¹	UART0 GPIO3 (RX) GPIO1 (TX)	PC TX RX
AT 命令/响应 ²	UART1 GPIO19 (RX) GPIO22 (TX) GPIO15 (CTS) GPIO14 (RTS)	USB 转 UART 串口模块 TX RX RTS CTS

说明 1：ESP 开发板和 PC 之间的管脚连接已内置在 ESP 开发板上，您只需使用 USB 数据线连接开发板和 PC 即可。

说明 2：CTS/RTS 管脚只有在使用硬件流控功能时才需连接。

如果需要直接基于 ESP32-WROVER 模组进行连接，请参考《ESP32-WROVER 技术规格书》。

ESP32-PICO 系列¶

ESP32-PICO 系列硬件连接管脚分配¶
功能	ESP 开发板管脚	其它设备管脚
下载固件/输出日志 ¹	UART0 GPIO3 (RX) GPIO1 (TX)	PC TX RX
AT 命令/响应 ²	UART1 GPIO19 (RX) GPIO22 (TX) GPIO15 (CTS) GPIO14 (RTS)	USB 转 UART 串口模块 TX RX RTS CTS

说明 1：ESP 开发板和 PC 之间的管脚连接已内置在 ESP 开发板上，您只需使用 USB 数据线连接开发板和 PC 即可。

说明 2：CTS/RTS 管脚只有在使用硬件流控功能时才需连接。

如果需要直接基于 ESP32-PICO-D4 进行连接，请参考《ESP32-PICO-D4 技术规格书》。

ESP32-SOLO 系列¶

ESP32-SOLO 系列硬件连接管脚分配¶
功能	ESP 开发板管脚	其它设备管脚
下载固件/输出日志 ¹	UART0 GPIO3 (RX) GPIO1 (TX)	PC TX RX
AT 命令/响应 ²	UART1 GPIO16 (RX) GPIO17 (TX) GPIO15 (CTS) GPIO14 (RTS)	USB 转 UART 串口模块 TX RX RTS CTS

说明 1：ESP 开发板和 PC 之间的管脚连接已内置在 ESP 开发板上，您只需使用 USB 数据线连接开发板和 PC 即可。

说明 2：CTS/RTS 管脚只有在使用硬件流控功能时才需连接。

如果需要直接基于 ESP32-SOLO-1 进行连接，请参考《ESP32-SOLO-1 技术规格书》。

ESP32-C3 系列¶

ESP32-C3 AT 采用两个 UART 接口：UART0 用于下载固件和输出日志，UART1 用于发送 AT 命令和接收 AT 响应。默认情况下，UART0 和 UART1 均使用 115200 波特率进行通信。

ESP32-C3 Series 系列硬件连接管脚分配¶
功能	ESP 开发板管脚	其它设备管脚
下载固件/输出日志 ¹	UART0 GPIO20 (RX) GPIO21 (TX)	PC TX RX
AT 命令/响应 ²	UART1 GPIO6 (RX) GPIO7 (TX) GPIO5 (CTS) GPIO4 (RTS)	USB 转 UART 串口模块 TX RX RTS CTS

说明 1：ESP 开发板和 PC 之间的管脚连接已内置在 ESP 开发板上，您只需使用 USB 数据线连接开发板和 PC 即可。

说明 2：CTS/RTS 管脚只有在使用硬件流控功能时才需连接。

如果需要直接基于 ESP32-C3-MINI-1 模组进行连接，请参考《ESP32-C3-MINI-1 技术规格书》。

下载指导¶

[English]

本文档以 ESP32-WROOM-32 模组为例，介绍如何下载 ESP 模组对应的 AT 固件，以及如何将固件烧录到模组上，其它 ESP 系列模组也可参考本文档。

下载和烧录 AT 固件之前，请确保您已正确连接所需硬件，具体可参考硬件连接。

对于不同系列的模组，AT 默认固件所支持的命令会有所差异。具体可参考 ESP-AT 固件差异。

下载 AT 固件¶

请按照以下步骤将 AT 固件下载至 PC：

前往 AT 固件
找到您的模组所对应的 AT 固件
点击相应链接进行下载

此处，我们下载了 ESP32-WROOM-32 对应的 ESP32-WROOM-32_AT_Bin_V2.1 固件，该固件的目录结构及其中各个 bin 文件介绍如下，其它 ESP 系列模组固件的目录结构及 bin 文件也可参考如下介绍：

.
├── at_customize.bin                 // 二级分区表
├── bootloader                       // bootloader
│   └── bootloader.bin
├── customized_partitions            // AT 自定义 bin 文件
│   ├── ble_data.bin
│   ├── client_ca.bin
│   ├── client_cert.bin
│   ├── client_key.bin
│   ├── factory_param.bin
│   ├── factory_param_WROOM-32.bin
│   ├── mqtt_ca.bin
│   ├── mqtt_cert.bin
│   ├── mqtt_key.bin
│   ├── server_ca.bin
│   ├── server_cert.bin
│   └── server_key.bin
├── download.config                  // 烧录固件的参数
├── esp-at.bin                       // AT 应用固件
├── factory                          // 量产所需打包好的 bin 文件
│   ├── factory_WROOM-32.bin
│   └── factory_parameter.log
├── flasher_args.json                // 下载参数信息新的格式
├── ota_data_initial.bin             // ota data 区初始值
├── partition_table                  // 一级分区列表
│   └── partition-table.bin
└── phy_init_data.bin                // phy 初始值信息

其中，download.config 文件包含烧录固件的参数：

--flash_mode dio --flash_freq 40m --flash_size 4MB
0x8000 partition_table/partition-table.bin
0x10000 ota_data_initial.bin
0xf000 phy_init_data.bin
0x1000 bootloader/bootloader.bin
0x100000 esp-at.bin
0x20000 at_customize.bin
0x24000 customized_partitions/server_cert.bin
0x39000 customized_partitions/mqtt_key.bin
0x26000 customized_partitions/server_key.bin
0x28000 customized_partitions/server_ca.bin
0x2e000 customized_partitions/client_ca.bin
0x30000 customized_partitions/factory_param.bin
0x21000 customized_partitions/ble_data.bin
0x3B000 customized_partitions/mqtt_ca.bin
0x37000 customized_partitions/mqtt_cert.bin
0x2a000 customized_partitions/client_cert.bin
0x2c000 customized_partitions/client_key.bin

--flash_mode dio 代表此固件采用的 flash dio 模式进行编译；
--flash_freq 40m 代表此固件采用的 flash 通讯频率为 40 MHz；
--flash_size 4MB 代表此固件适用的 flash 最小为 4 MB；
0x10000 ota_data_initial.bin 代表在 0x10000 地址烧录 ota_data_initial.bin 文件。

烧录 AT 固件至设备¶

请根据您的操作系统选择对应的烧录方法。

Windows¶

开始烧录之前，请下载 Flash 下载工具。更多有关 Flash 下载工具的介绍，请参考压缩包中 readme.pdf 文件或 doc 文件夹。

打开 Flash 下载工具；
根据您的需求选择一种模式；（此处，我们选择 Developer Mode。)

选择对应的 ESP 下载工具。本文以 ESP32 为例，则选择 ESP32 DownloadTool，请您注意根据实际采用的芯片选择对应的下载工具。

将 AT 固件烧录至设备，以下两种方式任选其一：
- 直接下载打包好的量产固件至 0x0 地址：勾选 “DoNotChgBin”，使用量产固件的默认配置；
  
  下载至单个地址界面图¶
- 分开下载多个 bin 文件至不同的地址：根据 download.config 文件进行配置，请勿勾选 “DoNotChgBin”；
  
  下载至多个地址界面图¶

为了避免烧录出现问题，请查看开发板的下载接口的 COM 端口号，并从 “COM:” 下拉列表中选择该端口号。有关如何查看端口号的详细介绍请参考在 Windows 上查看端口。

烧录完成后, 请检查 AT 固件是否烧录成功。

Linux 或 macOS¶

开始烧录之前，请安装 esptool.py。

以下两种方式任选其一，将 AT 固件烧录至设备：

分开下载多个 bin 文件至不同的地址：输入以下命令，替换 PORTNAME 和 download.config 参数；

esptool.py --chip auto --port PORTNAME --baud 115200 --before default_reset --after hard_reset write_flash -z download.config

将 PORTNAME 替换成开发板的下载接口名称，若您无法确定该接口名称，请参考在 Linux 和 macOS 上查看端口。

将 download.config 替换成该文件里的参数列表。

以下是将固件烧录至 ESP32-WROOM-32 模组输入的命令：

esptool.py --chip auto --port /dev/tty.usbserial-0001 --baud 115200 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size 4MB 0x8000 partition_table/partition-table.bin 0x10000 ota_data_initial.bin 0xf000 phy_init_data.bin 0x1000 bootloader/bootloader.bin 0x100000 esp-at.bin 0x20000 at_customize.bin 0x24000 customized_partitions/server_cert.bin 0x39000 customized_partitions/mqtt_key.bin 0x26000 customized_partitions/server_key.bin 0x28000 customized_partitions/server_ca.bin 0x2e000 customized_partitions/client_ca.bin 0x30000 customized_partitions/factory_param.bin 0x21000 customized_partitions/ble_data.bin 0x3B000 customized_partitions/mqtt_ca.bin 0x37000 customized_partitions/mqtt_cert.bin 0x2a000 customized_partitions/client_cert.bin 0x2c000 customized_partitions/client_key.bin

直接下载打包好的量产固件至 0x0 地址：输入以下命令，替换 PORTNAME 和 FILEDIRECTORY 参数；
```
esptool.py --chip auto --port PORTNAME --baud 115200 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size 4MB 0x0 FILEDIRECTORY
```
将 PORTNAME 替换成开发板的下载接口名称，若您无法确定该接口名称，请参考在 Linux 和 macOS 上查看端口。

将 FILEDIRECTORY 替换成打包好的量产固件的文件路径，通常情况下，文件路径是 factory/XXX.bin。

以下是将固件烧录至 ESP32-WROOM-32 模组输入的命令：
```
esptool.py --chip auto --port /dev/tty.usbserial-0001 --baud 115200 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size 4MB 0x0 factory/factory_WROOM-32.bin
```

烧录完成后，请检查 AT 固件是否烧录成功。

检查 AT 固件是否烧录成功¶

请按照以下步骤检查 AT 固件是否烧录成功：

打开串口工具，如 SecureCRT；
串口：选择用于发送或接收“AT 命令/响应”的串口（详情请见硬件连接）；
波特率：115200；
数据位：8；
检验位：None；
停止位：1；
流控：None；
输入 “AT+GMR” 命令，并且换行 (CR LF)；

若如下图所示，响应是 OK, 则表示 AT 固件烧录成功。

否则，您需要检查 ESP 设备开机日志，可以通过“下载/输出日志”串口在电脑上查看。若日志和下面的日志相似，则说明 ESP-AT 固件已经正确初始化了。

ESP32 开机日志：

ets Jun  8 2016 00:22:57
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0030,len:4
load:0x3fff0034,len:7184
ho 0 tail 12 room 4
load:0x40078000,len:13200
load:0x40080400,len:4564
entry 0x400806f4
I (30) boot: ESP-IDF v4.2 2nd stage bootloader
I (31) boot: compile time 11:23:19
I (31) boot: chip revision: 0
I (33) boot.esp32: SPI Speed      : 40MHz
I (38) boot.esp32: SPI Mode       : DIO
I (42) boot.esp32: SPI Flash Size : 4MB
I (47) boot: Enabling RNG early entropy source...
I (52) boot: Partition Table:
I (56) boot: ## Label            Usage          Type ST Offset   Length
I (63) boot:  0 phy_init         RF data          01 01 0000f000 00001000
I (71) boot:  1 otadata          OTA data         01 00 00010000 00002000
I (78) boot:  2 nvs              WiFi data        01 02 00012000 0000e000
I (86) boot:  3 at_customize     unknown          40 00 00020000 000e0000
I (93) boot:  4 ota_0            OTA app          00 10 00100000 00180000
I (101) boot:  5 ota_1            OTA app          00 11 00280000 00180000
I (108) boot: End of partition table
I (112) esp_image: segment 0: paddr=0x00100020 vaddr=0x3f400020 size=0x2a300 (172800) map
I (187) esp_image: segment 1: paddr=0x0012a328 vaddr=0x3ffbdb60 size=0x039e8 ( 14824) load
I (194) esp_image: segment 2: paddr=0x0012dd18 vaddr=0x40080000 size=0x00404 (  1028) load
I (194) esp_image: segment 3: paddr=0x0012e124 vaddr=0x40080404 size=0x01ef4 (  7924) load
I (206) esp_image: segment 4: paddr=0x00130020 vaddr=0x400d0020 size=0x10a470 (1090672) map
I (627) esp_image: segment 5: paddr=0x0023a498 vaddr=0x400822f8 size=0x1c3a0 (115616) load
I (678) esp_image: segment 6: paddr=0x00256840 vaddr=0x400c0000 size=0x00064 (   100) load
I (695) boot: Loaded app from partition at offset 0x100000
I (695) boot: Disabling RNG early entropy source...
max tx power=78,ret=0
2.1.0

ESP32-C3 开机日志:

ESP-ROM:esp32c3-20200918
Build:Sep 18 2020
rst:0x1 (POWERON),boot:0xc (SPI_FAST_FLASH_BOOT)
SPIWP:0xee
mode:DIO, clock div:2
load:0x3fcd6100,len:0x14
load:0x3fcd6114,len:0x179c
load:0x403ce000,len:0x894
load:0x403d0000,len:0x2bf8
entry 0x403ce000
I (54) boot: ESP-IDF v4.3-beta1 2nd stage bootloader
I (55) boot: compile time 12:09:42
I (55) boot: chip revision: 1
I (57) boot_comm: chip revision: 1, min. bootloader chip revision: 0
I (64) boot.esp32c3: SPI Speed      : 40MHz
I (68) boot.esp32c3: SPI Mode       : DIO
I (73) boot.esp32c3: SPI Flash Size : 4MB
I (78) boot: Enabling RNG early entropy source...
I (83) boot: Partition Table:
I (87) boot: ## Label            Usage          Type ST Offset   Length
I (94) boot:  0 phy_init         RF data          01 01 0000f000 00001000
I (102) boot:  1 otadata          OTA data         01 00 00010000 00002000
I (109) boot:  2 nvs              WiFi data        01 02 00012000 0000e000
I (117) boot:  3 at_customize     unknown          40 00 00020000 000e0000
I (124) boot:  4 ota_0            OTA app          00 10 00100000 00180000
I (132) boot:  5 ota_1            OTA app          00 11 00280000 00180000
I (139) boot: End of partition table
I (144) boot: No factory image, trying OTA 0
I (149) boot_comm: chip revision: 1, min. application chip revision: 0
I (156) esp_image: segment 0: paddr=00100020 vaddr=3c140020 size=29cc8h (171208) map
I (201) esp_image: segment 1: paddr=00129cf0 vaddr=3fc8f000 size=03be8h ( 15336) load
I (205) esp_image: segment 2: paddr=0012d8e0 vaddr=40380000 size=02738h ( 10040) load
I (210) esp_image: segment 3: paddr=00130020 vaddr=42000020 size=135bf0h (1268720) map
I (489) esp_image: segment 4: paddr=00265c18 vaddr=40382738 size=0c778h ( 51064) load
I (502) esp_image: segment 5: paddr=00272398 vaddr=50000000 size=00004h (     4) load
I (508) boot: Loaded app from partition at offset 0x100000
I (544) boot: Set actual ota_seq=1 in otadata[0]
I (544) boot: Disabling RNG early entropy source...
max tx power=78,ret=0
2.1.0

如果您尚不了解 ESP-AT 工程，请阅读 ESP-AT 是什么。

如果您想学习如何使用 ESP-AT，请首先阅读硬件连接，了解所需的硬件以及硬件之间如何连接，然后再阅读下载指导，了解如何下载和烧录 AT 固件。

AT 固件¶

[English]

发布的固件¶

[English]

推荐下载最新版本的固件。目前，乐鑫只发布了以下 ESP32 系列模组的 AT 固件。

注解

如果您的模组没有发布的固件，可以使用相同硬件配置的模组的固件（点击 ESP-AT 固件差异查看与您的模组硬件配置相同的固件），或者为您的模组创建出厂参数二进制文件（如何生成出厂参数二进制文件)。

ESP32-WROOM-32 系列¶

v2.2.0.0 ESP32-WROOM-32_AT_Bin_V2.2.0.0.zip （推荐）
v2.1.0.0 ESP32-WROOM-32_AT_Bin_V2.1.0.0.zip
v2.0.0.0 ESP32-WROOM-32_AT_Bin_V2.0.0.0.zip
v1.1.2.0 ESP32-WROOM-32_AT_Bin_V1.1.2.0.zip
v1.1.1.0 ESP32-WROOM-32_AT_Bin_V1.1.1.0.zip
v1.1.0.0 ESP32-WROOM-32_AT_Bin_V1.1.0.0.zip
v1.0.0.0 ESP32-WROOM-32_AT_Bin_V1.0.0.0.zip
v0.10.0.0 ESP32-WROOM-32_AT_Bin_V0.10.0.0.zip

ESP32-MINI-1 系列¶

v2.2.0.0 ESP32-MINI-1_AT_Bin_V2.2.0.0.zip （推荐）

ESP32-WROVER-32 系列¶

由于硬件限制，不推荐使用 ESP32-WROVER-B 模组，请使用其他 WROVER 系列模组。

v2.2.0.0 ESP32-WROVER_AT_Bin_V2.2.0.0.zip （推荐）
v2.1.0.0 ESP32-WROVER_AT_Bin_V2.1.0.0.zip
v2.0.0.0 ESP32-WROVER_AT_Bin_V2.0.0.0.zip
v0.10.0.0 ESP32-WROVER_AT_Bin_V0.10.0.0.zip

推荐下载最新版本的固件。目前，乐鑫只发布了以下 ESP32-C3 系列模组的 AT 固件。

注解

如果您的模组没有发布的固件，可以使用相同硬件配置的模组的固件（点击 ESP-AT 固件差异查看与您的模组硬件配置相同的固件），或者为您的模组创建出厂参数二进制文件（如何生成出厂参数二进制文件)。

ESP32-C3-MINI-1 系列¶

v2.3.0.0 ESP32-C3-MINI-1_AT_Bin_V2.3.0.0.zip （推荐）
v2.2.0.0 ESP32-C3-MINI-1_AT_Bin_V2.2.0.0.zip

以上链接中下载的 ESP-AT 固件包含了若干个特定功能的二进制文件，factory/factory_xxx.bin 文件是这些特定功能的二进制文件的合集。您可以仅烧录 factory/factory_xxx.bin 到起始地址为 0 的 flash 空间中，或者根据 download.config 文件中的信息将若干个二进制文件烧录到 flash 中对应起始地址的空间中。关于如何下载，请参考下载 AT 固件。

at_customize.bin 提供了用户分区表，该表列出了 ble_data.bin 分区、SSL 证书分区、MQTT 证书分区以及 factory_param_XXX.bin 分区和其它一些分区的的起始地址和分区大小。您可以通过 AT 命令 AT+FS 和 AT+SYSFLASH 来读和写该文件中罗列的分区里的内容。

factory_param_XXX.bin 指出了不同 ESP 模组之间的硬件配置（见下表）。请确保您的模组使用了正确的固件。

注解

如果您设计了自己的模组，那么可以参考如何生成出厂参数二进制文件对自定义模组进行配置，编译后会自动生成固件。或者，您也可以根据 UART 管脚/PSRAM/Flash 配置选择相似配置的固件（前提是要确保硬件满足要求，有关哪些固件适用于您的模组，请参考 ESP-AT 固件差异）。

当您根据 download.config 文件内容将固件下载到自定义模组中时，请使用自定义参数固件 customized_partitions/factory_param_XXX.bin 来代替 customized_partitions/factory_param.bin。UART CTS 和 RTS 管脚是可选的。

ESP32 系列

模组

UART 管脚（TX, RX, CTS, RTS）

Factory Parameter Bin

ESP32-WROOM-32 系列（ESP32 默认模组）

GPIO17

GPIO16

GPIO15

GPIO14

factory_param_WROOM-32.bin

ESP32-WROVER 系列（支持经典蓝牙）

GPIO22

GPIO19

GPIO15

GPIO14

factory_param_WROVER-32.bin

ESP32-PICO 系列

GPIO22

GPIO19

GPIO15

GPIO14

factory_param_PICO-D4.bin

ESP32-SOLO 系列

GPIO17

GPIO16

GPIO15

GPIO14

factory_param_SOLO-1.bin

ESP32-C3 系列

模组

UART 管脚（TX, RX, CTS, RTS）

Factory Parameter Bin

ESP32-C3-MINI 系列

GPIO7

GPIO6

GPIO5

GPIO4

factory_param_MINI-1.bin

ble_data.bin 在 ESP 工作于 Bluetooth LE 服务端的时候提供蓝牙服务；
server_cert.bin、server_key.bin 和 server_ca.bin 是 SSL 服务端示例证书；
client_cert.bin、client_key.bin 和 client_ca.bin 是 SSL 客户端示例证书；
mqtt_cert.bin、mqtt_key.bin 和 mqtt_ca.bin 是 MQTT SSL 客户端示例证书；

如果某些功能没有使用到，则不需要将相应的二进制文件下载到 flash 中。

AT 命令集¶

[English]

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

基础 AT 命令¶

[English]

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+SYSFLASH：查询或读写 flash 用户分区
AT+FS：文件系统操作
AT+RFPOWER：查询/设置 RF TX Power
AT+SYSROLLBACK：回滚到以前的固件
AT+SYSTIMESTAMP：查询/设置本地时间戳
AT+SYSLOG：启用或禁用 AT 错误代码提示
AT+SLEEPWKCFG：设置 Light-sleep 唤醒源和唤醒 GPIO
AT+SYSSTORE：设置参数存储模式
AT+SYSREG：读写寄存器

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 的时长，单位：毫秒。设定时间到后，设备自动唤醒，调用深度睡眠唤醒桩，然后加载应用程序。
- 0 表示立即重启
- 最大 Deep-sleep 时长约为 28.8 天（2 ³¹-1 毫秒）。

说明¶

由于外部因素的影响，所有设备进入 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-C3 设备：支持范围为 80 ~ 5000000
<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-C3 设备：支持范围为 80 ~ 5000000
<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

参数¶

<sleep mode>：
- 0：禁用睡眠模式
- 1：Modem-sleep 模式
  - 单 Wi-Fi 模式
    - 射频模块将根据 AP 的 DTIM 定期关闭
  - 单 BLE 模式
    - 在 BLE 广播态下，射频模块将根据广播间隔定期关闭
    - 在 BLE 连接态下，射频模块将根据连接间隔定期关闭
- 2：Light-sleep 模式
  - 单 Wi-Fi 模式
    - CPU 将自动进入睡眠，射频模块也将根据 AT+CWJAP 命令设置的 listen interval 参数定期关闭
  - 单 BLE 模式
    - 在 BLE 广播态下，CPU 将自动进入睡眠，射频模块也将根据广播间隔定期关闭
    - 在 BLE 连接态下，CPU 将自动进入睡眠，射频模块也将根据连接间隔定期关闭
- 3：Modem-sleep listen interval 模式
  - 单 Wi-Fi 模式
    - 射频模块将根据 AT+CWJAP 命令设置的 listen interval 参数定期关闭
  - 单 BLE 模式
    - 在 BLE 广播态下，射频模块将根据广播间隔定期关闭
    - 在 BLE 连接态下，射频模块将根据连接间隔定期关闭

说明¶

Modem-sleep 模式和 Light-sleep 模式均可以在 Wi-Fi 模式或者 BLE 模式下设置，但在 Wi-Fi 模式下，这两种模式只能在 station 模式下设置
设置 Light-sleep 模式前，建议提前通过 AT+SLEEPWKCFG 命令设置好唤醒源，否则没法唤醒，设备将一直处于睡眠状态
设置 Light-sleep 模式后，如果 Light-sleep 唤醒条件不满足时，设备将自动进入睡眠模式，当 Light-sleep 唤醒条件满足时，设备将自动从睡眠模式中唤醒
对于 BLE 模式下的 Light-sleep 模式，用户必须确保外接 32KHz 晶振，否则，Light-sleep 模式会以 Modem-sleep 模式工作。目前 AT 仅支持 ESP32 模块下的 Light-sleep 模式以 Modem-sleep 模式工作。
AT+SLEEP 更多示例请参考文档 Sleep AT 示例。

示例¶

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 透传模式, Bluetooth LE SPP 及 Bluetooth SPP 时是否打印提示信息
  - 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

或

// 透传模式下，Wi-Fi、socket、Bluetooth LE 或 Bluetooth 状态改变时会打印提示信息
AT+SYSMSG=4

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，详细信息可参考如何自定义分区。
烧录二级用户分区前，请参考如何生成 PKI 文件生成二进制用户分区文件。
擦除分区时，设置指令可省略 <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

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 设备的取值范围为 [40,84]：

设定值	读取值	实际值	实际 dBm
[40,43]	34	34	8.5
[44,51]	44	44	11
[52,55]	52	52	13
[56,59]	56	56	14
[60,65]	60	60	15
[66,71]	66	66	16.5
[72,77]	72	72	18
[78,84]	78	78	19.5

ESP32-C3 设备的取值范围为 [40,84]：

设定值

读取值

实际值

实际 dBm

[40,80]

<设定值>

<设定值>

<设定值> * 0.25

[81,84]

<设定值>

80

20

<ble_adv_power>：Bluetooth LE 广播的 RF TX Power。
- ESP32 设备的参数值：
  - 0: 7 dBm
  - 1: 4 dBm
  - 2: 1 dBm
  - 3: -2 dBm
  - 4: -5 dBm
  - 5: -8 dBm
  - 6: -11 dBm
  - 7: -14 dBm
- ESP32C3 设备的参数值：
  - 0: -27 dBm
  - 1: -24 dBm
  - 2: -21 dBm
  - 3: -18 dBm
  - 4: -15 dBm
  - 5: -12 dBm
  - 6: -9 dBm
  - 7: -6 dBm
  - 8: -3 dBm
  - 9: -0 dBm
  - 10: 3 dBm
  - 11: 6 dBm
  - 12: 9 dBm
  - 13: 12 dBm
  - 14: 15 dBm
  - 15: 18 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：高电平

示例¶

// 定时器唤醒
AT+SLEEPWKCFG=0,1000

// 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 不检查寄存器地址，因此请确保操作的寄存器地址有效

Wi-Fi AT 命令集¶

[English]

AT+CWMODE：查询/设置 Wi-Fi 模式 (Station/SoftAP/Station+SoftAP)
AT+CWSTATE：查询 Wi-Fi 状态和 Wi-Fi 信息
AT+CWJAP：连接 AP
AT+CWRECONNCFG：查询/设置 Wi-Fi 重连配置
AT+CWLAPOPT：设置 AT+CWLAP 命令扫描结果的属性
AT+CWLAP：扫描当前可用的 AP
AT+CWQAP：断开与 AP 的连接
AT+CWSAP：配置 ESP32 SoftAP 参数
AT+CWLIF：查询连接到 ESP SoftAP 的 station 信息
AT+CWQIF：断开 station 与 ESP SoftAP 的连接
AT+CWDHCP：启用/禁用 DHCP
AT+CWDHCPS：查询/设置 ESP SoftAP DHCP 分配的 IP 地址范围
AT+CWAUTOCONN：上电是否自动连接 AP
AT+CWAPPROTO：查询/设置 SoftAP 模式下 802.11 b/g/n 协议标准
AT+CWSTAPROTO：设置 Station 模式下 802.11 b/g/n 协议标准
AT+CIPSTAMAC：查询/设置 ESP Station 的 MAC 地址
AT+CIPAPMAC：查询/设置 ESP SoftAP 的 MAC 地址
AT+CIPSTA：查询/设置 ESP Station 的 IP 地址
AT+CIPAP：查询/设置 ESP SoftAP 的 IP 地址
AT+CWSTARTSMART：开启 SmartConfig
AT+CWSTOPSMART：停止 SmartConfig
AT+WPS：设置 WPS 功能
AT+MDNS：设置 mDNS 功能
AT+CWJEAP：连接 WPA2 企业版 AP
AT+CWHOSTNAME：查询/设置 ESP Station 的主机名称
AT+CWCOUNTRY：查询/设置 Wi-Fi 国家代码

AT+CWMODE：查询/设置 Wi-Fi 模式 (Station/SoftAP/Station+SoftAP)¶

查询命令¶

功能：

查询 ESP 设备的 Wi-Fi 模式

命令：

AT+CWMODE?

响应：

+CWMODE:<mode>
OK

设置命令¶

功能：

设置 ESP 设备的 Wi-Fi 模式

命令：

AT+CWMODE=<mode>[,<auto_connect>]

响应：

OK

参数¶

<mode>：模式
- 0: 无 Wi-Fi 模式，并且关闭 Wi-Fi RF
- 1: Station 模式
- 2: SoftAP 模式
- 3: SoftAP+Station 模式
<auto_connect>：切换 ESP 设备的 Wi-Fi 模式时（例如，从 SoftAP 或无 Wi-Fi 模式切换为 Station 模式或 SoftAP+Station 模式），是否启用自动连接 AP 的功能，默认值：1。参数缺省时，使用默认值，也就是能自动连接。
- 0: 禁用自动连接 AP 的功能
- 1: 启用自动连接 AP 的功能，若之前已经将自动连接 AP 的配置保存到 flash 中，则 ESP 设备将自动连接 AP

说明¶

若 AT+SYSSTORE=1，本设置将保存在 NVS 分区

示例¶

AT+CWMODE=3

AT+CWSTATE：查询 Wi-Fi 状态和 Wi-Fi 信息¶

查询命令¶

功能：

查询 ESP 设备的 Wi-Fi 状态和 Wi-Fi 信息

命令：

AT+CWSTATE?

响应：

+CWSTATE:<state>,<"ssid">

OK

参数¶

<state>：当前 Wi-Fi 状态
- 0: ESP station 尚未进行任何 Wi-Fi 连接
- 1: ESP station 已经连接上 AP，但尚未获取到 IPv4 地址
- 2: ESP station 已经连接上 AP，并已经获取到 IPv4 地址
- 3: ESP station 正在进行 Wi-Fi 连接或 Wi-Fi 重连
- 4: ESP station 处于 Wi-Fi 断开状态
<”ssid”>：目标 AP 的 SSID

说明¶

当 ESP station 没有连接上 AP 时，推荐使用此命令查询 Wi-Fi 信息；当 ESP station 已连接上 AP 后，推荐使用 AT+CWJAP 命令查询 Wi-Fi 信息

AT+CWJAP：连接 AP¶

查询命令¶

功能：

查询与 ESP Station 连接的 AP 信息

命令：

AT+CWJAP?

响应：

+CWJAP:<ssid>,<bssid>,<channel>,<rssi>,<pci_en>,<reconn_interval>,<listen_interval>,<scan_mode>,<pmf>
OK

设置命令¶

功能：

设置 ESP Station 需连接的 AP

命令：

AT+CWJAP=[<ssid>],[<pwd>][,<bssid>][,<pci_en>][,<reconn_interval>][,<listen_interval>][,<scan_mode>][,<jap_timeout>][,<pmf>]

响应：

WIFI CONNECTED
WIFI GOT IP

OK
[WIFI GOT IPv6 LL]
[WIFI GOT IPv6 GL]

或

+CWJAP:<error code>
ERROR

执行命令¶

功能：

将 ESP station 连接至上次 Wi-Fi 配置中的 AP

命令：

AT+CWJAP

响应：

WIFI CONNECTED
WIFI GOT IP

OK
[WIFI GOT IPv6 LL]
[WIFI GOT IPv6 GL]

或

+CWJAP:<error code>
ERROR

参数¶

<ssid>：目标 AP 的 SSID
- 如果 SSID 和密码中有 ,、"、\\ 等特殊字符，需转义
<pwd>：密码最长 63 字节 ASCII
<bssid>：目标 AP 的 MAC 地址，当多个 AP 有相同的 SSID 时，该参数不可省略
<channel>：信道号
<rssi>：信号强度
<pci_en>：PCI 认证
- 0: ESP station 可与任何一种加密方式的 AP 连接，包括 OPEN 和 WEP
- 1: ESP station 可与除 OPEN 和 WEP 之外的任何一种加密方式的 AP 连接
<reconn_interval>：Wi-Fi 重连间隔，单位：秒，默认值：1，最大值：7200
- 0: 断开连接后，ESP station 不重连 AP
- [1,7200]: 断开连接后，ESP station 每隔指定的时间与 AP 重连
<listen_interval>：监听 AP beacon 的间隔，单位为 AP beacon 间隔，默认值：3，范围：[1,100]
<scan_mode>：扫描模式
- 0: 快速扫描，找到目标 AP 后终止扫描，ESP station 与第一个扫描到的 AP 连接
- 1: 全信道扫描，所有信道都扫描后才终止扫描，ESP station 与扫描到的信号最强的 AP 连接
<jap_timeout>：AT+CWJAP 命令超时的最大值，单位：秒，默认值：15，范围：[3,600]
<pmf>：PMF（Protected Management Frames，受保护的管理帧），默认值 0
- 0 表示禁用 PMF
- bit 0: 具有 PMF 功能，提示支持 PMF，如果其他设备具有 PMF 功能，则 ESP 设备将优先选择以 PMF 模式连接
- bit 1: 需要 PMF，提示需要 PMF，设备将不会关联不支持 PMF 功能的设备
<error code>：错误码，仅供参考
- 1: 连接超时
- 2: 密码错误
- 3: 无法找到目标 AP
- 4: 连接失败
- 其它值: 发生未知错误

说明¶

如果 AT+SYSSTORE=1，配置更改将保存到 NVS 分区
使用本命令需要开启 station 模式
当 ESP station 已连接上 AP 后，推荐使用此命令查询 Wi-Fi 信息；当 ESP station 没有连接上 AP 时，推荐使用 AT+CWSTATE 命令查询 Wi-Fi 信息
本命令中的 <reconn_interval> 参数与 AT+CWRECONNCFG 命令中的 <interval_second> 参数相同。如果运行本命令时不设置 <reconn_interval> 参数，Wi-Fi 重连间隔时间将采用默认值 1
如果同时省略 <ssid> 和 <password> 参数，将使用上一次设置的值
执行命令与设置命令的超时时间相同，默认为 15 秒，可通过参数 <jap_timeout> 设置
想要获取 IPv6 地址，需要先设置 AT+CIPV6=1
回复 OK 代表 IPv4 网络已经准备就绪，而不代表 IPv6 网络准备就绪。当前 ESP-AT 以 IPv4 网络为主，IPv6 网络为辅。
WIFI GOT IPv6 LL 代表已经获取到本地链路 IPv6 地址，这个地址是通过 EUI-64 本地计算出来的，不需要路由器参与。由于并行时序，这个打印可能在 OK 之前，也可能在 OK 之后。
WIFI GOT IPv6 GL 代表已经获取到全局 IPv6 地址，该地址是由 AP 下发的前缀加上内部计算出来的后缀进行组合而来的，需要路由器参与。由于并行时序，这个打印可能在 OK 之前，也可能在 OK 之后；也可能由于 AP 不支持 IPv6 而不打印。

示例¶

// 如果目标 AP 的 SSID 是 "abc"，密码是 "0123456789"，则命令是：
AT+CWJAP="abc","0123456789"

// 如果目标 AP 的 SSID 是 "ab\,c"，密码是 "0123456789"\"，则命令是：
AT+CWJAP="ab\\\,c","0123456789\"\\"

// 如果多个 AP 有相同的 SSID "abc"，可通过 BSSID 找到目标 AP：
AT+CWJAP="abc","0123456789","ca:d7:19:d8:a6:44"

// 如果 ESP-AT 要求通过 PMF 连接 AP，则命令是：
AT+CWJAP="abc","0123456789",,,,,,,3

AT+CWRECONNCFG：查询/设置 Wi-Fi 重连配置¶

查询命令¶

功能：

查询 Wi-Fi 重连配置

命令：

AT+CWRECONNCFG?

响应：

+CWRECONNCFG:<interval_second>,<repeat_count>
OK

设置命令¶

功能：

设置 Wi-Fi 重连配置

命令：

AT+CWRECONNCFG=<interval_second>,<repeat_count>

响应：

OK

参数¶

<interval_second>：Wi-Fi 重连间隔，单位：秒，默认值：0，最大值 7200
- 0: 断开连接后，ESP station 不重连 AP
- [1,7200]: 断开连接后，ESP station 每隔指定的时间与 AP 重连
<repeat_count>：ESP 设备尝试重连 AP 的次数，本参数在 <interval_second> 不为 0 时有效，默认值：0，最大值：1000
- 0: ESP station 始终尝试连接 AP
- [1,1000]: ESP station 按照本参数指定的次数重连 AP

示例¶

// ESP station 每隔 1 秒尝试重连 AP，共尝试 100 次
AT+CWRECONNCFG=1,100

// ESP station 在断开连接后不重连 AP
AT+CWRECONNCFG=0,0

说明¶

本命令中的 <interval_second> 参数与 AT+CWJAP 中的 [<reconn_interval>] 参数相同
该命令适用于被动断开 AP、Wi-Fi 模式切换和开机后 Wi-Fi 自动连接

AT+CWLAPOPT：设置 AT+CWLAP 命令扫描结果的属性¶

设置命令¶

命令：

AT+CWLAPOPT=<reserved>,<print mask>[,<rssi filter>][,<authmode mask>]

响应：

OK

或者

ERROR

参数¶

<reserved>：保留项
<print mask>：AT+CWLAP 的扫描结果是否显示以下参数，默认值：0x7FF，若 bit 设为 1，则显示对应参数，若设为 0，则不显示对应参数
- bit 0: 是否显示 <ecn>
- bit 1: 是否显示 <ssid>
- bit 2: 是否显示 <rssi>
- bit 3: 是否显示 <mac>
- bit 4: 是否显示 <channel>
- bit 5: 是否显示 <freq_offset>
- bit 6: 是否显示 <freqcal_val>
- bit 7: 是否显示 <pairwise_cipher>
- bit 8: 是否显示 <group_cipher>
- bit 9: 是否显示 <bgn>
- bit 10: 是否显示 <wps>
[<rssi filter>]：AT+CWLAP 的扫描结果是否按照本参数过滤，也即，是否过滤掉信号强度低于 rssi filter 参数值的 AP，单位：dBm，默认值：–100，范围：[–100,40]
[<authmode mask>]：AT+CWLAP 的扫描结果是否显示以下认证方式的 AP，默认值：0xFFFF，如果 bit x 设为 1，则显示对应认证方式的 AP，若设为 0，则不显示
- bit 0: 是否显示 OPEN 认证方式的 AP
- bit 1: 是否显示 WEP 认证方式的 AP
- bit 2: 是否显示 WPA_PSK 认证方式的 AP
- bit 3: 是否显示 WPA2_PSK 认证方式的 AP
- bit 4: 是否显示 WPA_WPA2_PSK 认证方式的 AP
- bit 5: 是否显示 WPA2_ENTERPRISE 认证方式的 AP
- bit 6: 是否显示 WPA3_PSK 认证方式的 AP
- bit 7: 是否显示 WPA2_WPA3_PSK 认证方式的 AP
- [ESP32-C3 Only] bit 8: 是否显示 WAPI_PSK 认证方式的 AP

示例¶

// 第一个参数为 1，表示 AT+CWLAP 命令扫描结果按照信号强度 RSSI 值排序
// 第二个参数为 31，即 0x1F，表示所有值为 1 的 bit 对应的参数都会显示出来
AT+CWLAPOPT=1,31
AT+CWLAP

// 只显示认证方式为 OPEN 的 AP
AT+CWLAPOPT=1,31,-100,1
AT+CWLAP

AT+CWLAP：扫描当前可用的 AP¶

设置命令¶

功能：

列出符合特定条件的 AP，如指定 SSID、MAC 地址或信道号

命令：

AT+CWLAP=[<ssid>,<mac>,<channel>,<scan_type>,<scan_time_min>,<scan_time_max>]

执行命令¶

功能：

列出当前可用的 AP

命令：

AT+CWLAP

响应：

+CWLAP:<ecn>,<ssid>,<rssi>,<mac>,<channel>,<freq_offset>,<freqcal_val>,<pairwise_cipher>,<group_cipher>,<bgn>,<wps>
OK

参数¶

<ecn>：加密方式
- 0: OPEN
- 1: WEP
- 2: WPA_PSK
- 3: WPA2_PSK
- 4: WPA_WPA2_PSK
- 5: WPA2_ENTERPRISE
- 6: WPA3_PSK
- 7: WPA2_WPA3_PSK
- [ESP32-C3 Only] 8: WAPI_PSK
<ssid>：字符串参数，AP 的 SSID
<rssi>：信号强度
<mac>：字符串参数，AP 的 MAC 地址
<channel>：信道号
<scan_type>：Wi-Fi 扫描类型，默认值为：0
- 0: 主动扫描
- 1: 被动扫描
<scan_time_min>：每个信道最短扫描时间，单位：毫秒，范围：[0,1500]，如果扫描类型为被动扫描，本参数无效
<scan_time_max>：每个信道最长扫描时间，单位：毫秒，范围：[0,1500]，如果设为 0，固件采用参数默认值，主动扫描为 120 ms，被动扫描为 360 ms
<freq_offset>：频偏（保留项目）
<freqcal_val>：频率校准值（保留项目）
<pairwise_cipher>：成对加密类型
- 0: None
- 1: WEP40
- 2: WEP104
- 3: TKIP
- 4: CCMP
- 5: TKIP and CCMP
- 6: AES-CMAC-128
- 7: 未知
<group_cipher>：组加密类型，与 <pairwise_cipher> 参数的枚举值相同
<bgn>：802.11 b/g/n，若 bit 设为 1，则表示使能对应模式，若设为 0，则表示禁用对应模式
- bit 0: 是否使能 802.11b 模式
- bit 1: 是否使能 802.11g 模式
- bit 2: 是否使能 802.11n 模式
<wps>：wps flag
- 0: 不支持 WPS
- 1: 支持 WPS

示例¶

AT+CWLAP="Wi-Fi","ca:d7:19:d8:a6:44",6,0,400,1000

// 寻找指定 SSID 的 AP
AT+CWLAP="Wi-Fi"

AT+CWQAP：断开与 AP 的连接¶

执行命令¶

命令：

AT+CWQAP

响应：

OK

AT+CWSAP：配置 ESP SoftAP 参数¶

查询命令¶

功能：

查询 ESP SoftAP 的配置参数

命令：

AT+CWSAP?

响应：

+CWSAP:<ssid>,<pwd>,<channel>,<ecn>,<max conn>,<ssid hidden>
OK

设置命令¶

功能：

设置 ESP SoftAP 的配置参数

命令：

AT+CWSAP=<ssid>,<pwd>,<chl>,<ecn>[,<max conn>][,<ssid hidden>]

响应：

OK

参数¶

<ssid>：字符串参数，接入点名称
<pwd>：字符串参数，密码，范围：8 ~ 63 字节 ASCII
<channel>：信道号
<ecn>：加密方式，不支持 WEP
- 0: OPEN
- 2: WPA_PSK
- 3: WPA2_PSK
- 4: WPA_WPA2_PSK
[<max conn>]：允许连入 ESP SoftAP 的最多 station 数目，取值范围：[1,10]
[<ssid hidden>]：
- 0: 广播 SSID（默认）
- 1: 不广播 SSID

说明¶

本指令只有当 AT+CWMODE=2 或者 AT+CWMODE=3 时才有效
若 AT+SYSSTORE=1，配置更改将保存在 NVS 分区
默认 SSID 因设备而异，因为它由设备的 MAC 地址组成。您可以使用 AT+CWSAP? 查询默认的SSID。

示例¶

AT+CWSAP="ESP","1234567890",5,3

AT+CWLIF：查询连接到 ESP SoftAP 的 station 信息¶

执行命令¶

命令：

AT+CWLIF

响应：

+CWLIF:<ip addr>,<mac>

OK

参数¶

<ip addr>：连接到 ESP SoftAP 的 station 的 IP 地址
<mac>：连接到 ESP SoftAP 的 station 的 MAC 地址

说明¶

本指令无法查询静态 IP，仅支持在 ESP SoftAP 和连入的 station DHCP 均使能的情况下有效

AT+CWQIF：断开 station 与 ESP SoftAP 的连接¶

执行命令¶

功能：

断开所有连入 ESP SoftAP 的 station

命令：

AT+CWQIF

响应：

OK

设置命令¶

功能：

断开某个连入 ESP SoftAP 的 station

命令：

AT+CWQIF=<mac>

响应：

OK

参数¶

<mac>：需断开连接的 station 的 MAC 地址

AT+CWDHCP：启用/禁用 DHCP¶

查询命令¶

命令：

AT+CWDHCP?

响应：

+CWDHCP:<state>
OK

设置命令¶

功能：

启用/禁用 DHCP

命令：

AT+CWDHCP=<operate>,<mode>

响应：

OK

参数¶

<operate>：
- 0: 禁用
- 1: 启用
<mode>：
- Bit0: Station 的 DHCP
- Bit1: SoftAP 的 DHCP
<state>：DHCP 的状态
- Bit0:
  - 0: 禁用 Station 的 DHCP
  - 1: 启用 Station 的 DHCP
- Bit1:
  - 0: 禁用 SoftAP 的 DHCP
  - 1: 启用 SoftAP 的 DHCP
- Bit2:
  - 0: 禁用 Ethernet 的 DHCP
  - 1: 启用 Ethernet 的 DHCP

说明¶

若 AT+SYSSTORE=1，配置更改将保存到 NVS 分区
本设置命令与设置静态 IP 地址的命令会相互影响，如 AT+CIPSTA 和 AT+CIPAP
- 若启用 DHCP，则静态 IP 地址会被禁用
- 若启用静态 IP，则 DHCP 会被禁用
- 最后一次配置会覆盖上一次配置

示例¶

// 启用 Station DHCP，如果原 DHCP mode 为 2，则现 DHCP mode 为 3
AT+CWDHCP=1,1

// 禁用 SoftAP DHCP，如果原 DHCP mode 为 3，则现 DHCP mode 为 1
AT+CWDHCP=0,2

AT+CWDHCPS：查询/设置 ESP SoftAP DHCP 分配的 IP 地址范围¶

查询命令¶

命令：

AT+CWDHCPS?

响应：

+CWDHCPS=<lease time>,<start IP>,<end IP>
OK

设置命令¶

功能：

设置 ESP SoftAP DHCP 服务器分配的 IP 地址范围

命令：

AT+CWDHCPS=<enable>,<lease time>,<start IP>,<end IP>

响应：

OK

参数¶

<enable>：
- 1: 设置 DHCP server 信息，后续参数必须填写
- 0: 清除 DHCP server 信息，恢复默认值，后续参数无需填写
<lease time>：租约时间，单位：分钟，取值范围：[1,2880]
<start IP>：ESP SoftAP DHCP 服务器 IP 地址池的起始 IP
<end IP>：ESP SoftAP DHCP 服务器 IP 地址池的结束 IP

说明¶

若 AT+SYSSTORE=1，配置更改将保存到 NVS 分区
本命令必须在 ESP SoftAP 模式使能，且开启 DHCP server 的情况下使用
设置的 IP 地址范围必须与 ESP SoftAP 在同一网段

示例¶

AT+CWDHCPS=1,3,"192.168.4.10","192.168.4.15"

AT+CWDHCPS=0 // 清除设置，恢复默认值

AT+CWAUTOCONN：上电是否自动连接 AP¶

设置命令¶

命令：

AT+CWAUTOCONN=<enable>

响应：

OK

参数¶

<enable>：
- 1: 上电自动连接 AP（默认）
- 0: 上电不自动连接 AP

说明¶

本设置保存到 NVS 区域

示例¶

AT+CWAUTOCONN=1

AT+CWAPPROTO：查询/设置 SoftAP 模式下 802.11 b/g/n 协议标准¶

查询命令¶

命令：

AT+CWAPPROTO?

响应：

+CWAPPROTO=<protocol>
OK

设置命令¶

命令：

AT+CWAPPROTO=<protocol>

响应：

OK

参数¶

<protocol>：
- bit0: 802.11b 协议标准
- bit1: 802.11g 协议标准
- bit2: 802.11n 协议标准

说明¶

当前，ESP 设备只支持 802.11b、802.11bg 或 802.11bgn 协议标准
默认情况下，ESP 设备的 PHY mode 是 802.11bgn 模式

AT+CWSTAPROTO：设置 Station 模式下 802.11 b/g/n 协议标准¶

查询命令¶

命令：

AT+CWSTAPROTO?

响应：

+CWSTAPROTO=<protocol>
OK

设置命令¶

命令：

AT+CWSTAPROTO=<protocol>

响应：

OK

参数¶

<protocol>：
- bit0: 802.11b 协议标准
- bit1: 802.11g 协议标准
- bit2: 802.11n 协议标准

说明¶

当前，ESP 设备只支持 802.11b、802.11bg 或 802.11bgn 协议标准
默认情况下，ESP 设备的 PHY mode 是 802.11bgn 模式
从 ESP-AT v2.1.0.0 开始支持本命令

AT+CIPSTAMAC：查询/设置 ESP Station 的 MAC 地址¶

查询命令¶

功能：

查询 ESP Station 的 MAC 地址

命令：

AT+CIPSTAMAC?

响应：

+CIPSTAMAC:<mac>
OK

设置命令¶

功能：

设置 ESP Station 的 MAC 地址

命令：

AT+CIPSTAMAC=<mac>

响应：

OK

参数¶

<mac>：字符串参数，表示 ESP Station 的 MAC 地址

说明¶

若 AT+SYSSTORE=1，配置更改将保存到 NVS 分区
ESP SoftAP 的 MAC 地址与 ESP Station 不同，不要为二者设置同样的 MAC 地址
MAC 地址的 Bit 0 不能为 1，例如，MAC 地址可以是 “1a:…”，但不可以是 “15:…”
FF:FF:FF:FF:FF:FF 和 00:00:00:00:00:00 是无效地址，不能设置

示例¶

AT+CIPSTAMAC="1a:fe:35:98:d3:7b"

AT+CIPAPMAC：查询/设置 ESP SoftAP 的 MAC 地址¶

查询命令¶

功能：

查询 ESP SoftAP 的 MAC 地址

命令：

AT+CIPAPMAC?

响应：

+CIPAPMAC:<mac>
OK

设置命令¶

功能：

设置 ESP SoftAP 的 MAC 地址

命令：

AT+CIPAPMAC=<mac>

响应：

OK

参数¶

<mac>：字符串参数，表示 ESP SoftAP 的 MAC 地址

说明¶

若 AT+SYSSTORE=1，配置更改将保存到 NVS 分区
ESP SoftAP 的 MAC 地址与 ESP Station 不同，不要为二者设置同样的 MAC 地址
MAC 地址的 Bit 0 不能为 1，例如，MAC 地址可以是 “18:…”，但不可以是 “15:…”
FF:FF:FF:FF:FF:FF 和 00:00:00:00:00:00 是无效地址，不能设置

示例¶

AT+CIPAPMAC="18:fe:35:98:d3:7b"

AT+CIPSTA：查询/设置 ESP Station 的 IP 地址¶

查询命令¶

功能：

查询 ESP Station 的 IP 地址

命令：

AT+CIPSTA?

响应：

+CIPSTA:ip:<"ip">
+CIPSTA:gateway:<"gateway">
+CIPSTA:netmask:<"netmask">
+CIPSTA:ip6ll:<"ipv6 addr">
+CIPSTA:ip6gl:<"ipv6 addr">

OK

设置命令¶

功能：

设置 ESP Station 的 IPv4 地址

命令：

AT+CIPSTA=<"ip">[,<"gateway">,<"netmask">]

响应：

OK

参数¶

<”ip”>：字符串参数，表示 ESP station 的 IPv4 地址
<”gateway”>：网关
<”netmask”>：子网掩码
<”ipv6 addr”>：ESP station 的 IPv6 地址

说明¶

使用查询命令时，只有当 ESP station 连入 AP 或者配置过静态 IP 地址后，才能查询到它的 IP 地址
若 AT+SYSSTORE=1，配置更改将保存到 NVS 分区
本设置命令与设置 DHCP 的命令相互影响，如 AT+CWDHCP
- 若启用静态 IP 地址，则禁用 DHCP
- 若启用 DHCP，则禁用静态 IP 地址
- 最后一次配置会覆盖上一次配置

示例¶

AT+CIPSTA="192.168.6.100","192.168.6.1","255.255.255.0"

AT+CIPAP：查询/设置 ESP SoftAP 的 IP 地址¶

查询命令¶

功能：

查询 ESP SoftAP 的 IP 地址

命令：

AT+CIPAP?

响应：

+CIPAP:ip:<"ip">
+CIPAP:gateway:<"gateway">
+CIPAP:netmask:<"netmask">
+CIPAP:ip6ll:<"ipv6 addr">
+CIPAP:ip6gl:<"ipv6 addr">

OK

设置命令¶

功能：

设置 ESP SoftAP 的 IPv4 地址

命令：

AT+CIPAP=<"ip">[,<"gateway">,<"netmask">]

响应：

OK

参数¶

<”ip”>：字符串参数，表示 ESP SoftAP 的 IPv4 地址
<”gateway”>：网关
<”netmask”>：子网掩码
<”ipv6 addr”>：ESP SoftAP 的 IPv6 地址

说明¶

若 AT+SYSSTORE=1，配置更改将保存到 NVS 分区
本设置命令与设置 DHCP 的命令相互影响，如 AT+CWDHCP
- 若启用静态 IP 地址，则禁用 DHCP
- 若启用 DHCP，则禁用静态 IP 地址
- 最后一次配置会覆盖上一次配置

示例¶

AT+CIPAP="192.168.5.1","192.168.5.1","255.255.255.0"

AT+CWSTARTSMART：开启 SmartConfig¶

执行命令¶

功能：

开启 ESP-TOUCH+AirKiss 兼容模式

命令：

AT+CWSTARTSMART

设置命令¶

功能：

开启某指定类型的 SmartConfig

命令：

AT+CWSTARTSMART=<type>[,<auth floor>][,<"esptouch v2 key">]

响应：

OK

参数¶

<type>：类型
- 1: ESP-TOUCH
- 2: AirKiss
- 3: ESP-TOUCH+AirKiss
- [ESP32-C3 Only] 4: ESP-TOUCH v2
<auth floor>：Wi-Fi 认证模式阈值，ESP-AT 不会连接到 authmode 低于此阈值的 AP
- 0: OPEN（默认）
- 1: WEP
- 2: WPA_PSK
- 3: WPA2_PSK
- 4: WPA_WPA2_PSK
- 5: WPA2_ENTERPRISE
- 6: WPA3_PSK
- 7: WPA2_WPA3_PSK
[ESP32-C3 Only] <”esptouch v2 key”>：ESP-TOUCH v2 的解密秘钥，用于解密 Wi-Fi 密码和自定义数据。长度应为 16 字节。

说明¶

更多有关 SmartConfig 的信息，请参考 ESP-TOUCH 使用指南；
SmartConfig 仅支持在 ESP Station 模式下调用；
消息 Smart get Wi-Fi info 表示 SmartConfig 成功获取到 AP 信息，之后 ESP 尝试连接 AP；
消息 +SCRD:<length>,<rvd data> 表示 ESP-Touch v2 成功获取到自定义数据；
消息 Smartconfig connected Wi-Fi 表示成功连接到 AP；
因为 ESP 设备需要将 SmartConfig 配网结果同步给手机端，所以建议在消息 Smartconfig connected Wi-Fi 输出后延迟超过 6 秒再调用 AT+CWSTOPSMART；
可调用 AT+CWSTOPSMART 停止 SmartConfig，然后再执行其他命令。注意，在 SmartConfig 过程中请勿执行其他命令。

示例¶

AT+CWMODE=1
AT+CWSTARTSMART

AT+CWSTOPSMART：停止 SmartConfig¶

执行命令¶

命令：

AT+CWSTOPSMART

响应：

OK

说明¶

无论 SmartConfig 成功与否，都请在执行其他命令之前调用 AT+CWSTOPSMART 释放 SmartConfig 占用的内存

示例¶

AT+CWMODE=1
AT+CWSTARTSMART
AT+CWSTOPSMART

AT+WPS：设置 WPS 功能¶

设置命令¶

命令：

AT+WPS=<enable>[,<auth floor>]

响应：

OK

参数¶

<enable>：
- 1: 开启 PBC 类型的 WPS
- 0: 关闭 PBC 类型的 WPS
<auth floor>: Wi-Fi 认证模式阈值，ESP-AT 不会连接到 authmode 低于此阈值的 AP
- 0: OPEN（默认）
- 1: WEP
- 2: WPA_PSK
- 3: WPA2_PSK
- 4: WPA_WPA2_PSK
- 5: WPA2_ENTERPRISE
- 6: WPA3_PSK
- 7: WPA2_WPA3_PSK

说明¶

WPS 功能必须在 ESP Station 使能的情况下调用
WPS 不支持 WEP 加密方式

示例¶

AT+CWMODE=1
AT+WPS=1

AT+MDNS：设置 mDNS 功能¶

设置命令¶

命令：

AT+MDNS=<enable>[,<hostname>,<service_name>,<port>]

响应：

OK

参数¶

<enable>：
- 1: 开启 mDNS 功能，后续参数需要填写
- 0: 关闭 mDNS 功能，后续参数无需填写
<hostname>：mDNS 主机名称
<service_name>：mDNS 服务名称
<port>：mDNS 端口

示例¶

AT+CWMODE=1
AT+CWJAP="1234567890","1234567890"
AT+MDNS=1,"espressif","_iot",8080
AT+MDNS=0

AT+CWJEAP：连接 WPA2 企业版 AP¶

查询命令¶

功能：

查询 ESP station 连入的企业版 AP 的配置信息

命令：

AT+CWJEAP?

响应：

+CWJEAP:<ssid>,<method>,<identity>,<username>,<password>,<security>
OK

设置命令¶

功能：

连接到目标企业版 AP

命令：

AT+CWJEAP=<ssid>,<method>,<identity>,<username>,<password>,<security>[,<jeap_timeout>]

响应：

OK

或

+CWJEAP:Timeout
ERROR

参数¶

<ssid>：企业版 AP 的 SSID
- 如果 SSID 或密码中包含 ,、"、\\ 等特殊字符，需转义
<method>：WPA2 企业版认证方式
- 0: EAP-TLS
- 1: EAP-PEAP
- 2: EAP-TTLS
<identity>：阶段 1 的身份，字符串限制为 1 ~ 32
<username>：阶段 2 的用户名，范围：1 ~ 32 字节，EAP-PEAP、EAP-TTLS 两种认证方式需设置本参数，EAP-TLS 方式无需设置本参数
<password>：阶段 2 的密码，范围：1 ~ 32 字节，EAP-PEAP、EAP-TTLS 两种认证方式需设置本参数，EAP-TLS 方式无需设置本参数
<security>：
- Bit0: 客户端证书
- Bit1: 服务器证书
[<jeap_timeout>]：AT+CWJEAP 命令的最大超时时间，单位：秒，默认值：15，范围：[3,600]

示例¶

// 连接至 EAP-TLS 认证方式的企业版 AP，设置身份，验证服务器证书，加载客户端证书
AT+CWJEAP="dlink11111",0,"example@espressif.com",,,3

// 连接至 EAP-PEAP 认证方式的企业版 AP，设置身份、用户名、密码，不验证服务器证书，不加载客户端证书
AT+CWJEAP="dlink11111",1,"example@espressif.com","espressif","test11",0

错误代码:

WPA2 企业版错误码以 ERR CODE:0x<%08x> 格式打印：

AT_EAP_MALLOC_FAILED	0x8001
AT_EAP_GET_NVS_CONFIG_FAILED	0x8002
AT_EAP_CONN_FAILED	0x8003
AT_EAP_SET_WIFI_CONFIG_FAILED	0x8004
AT_EAP_SET_IDENTITY_FAILED	0x8005
AT_EAP_SET_USERNAME_FAILED	0x8006
AT_EAP_SET_PASSWORD_FAILED	0x8007
AT_EAP_GET_CA_LEN_FAILED	0x8008
AT_EAP_READ_CA_FAILED	0x8009
AT_EAP_SET_CA_FAILED	0x800A
AT_EAP_GET_CERT_LEN_FAILED	0x800B
AT_EAP_READ_CERT_FAILED	0x800C
AT_EAP_GET_KEY_LEN_FAILED	0x800D
AT_EAP_READ_KEY_FAILED	0x800E
AT_EAP_SET_CERT_KEY_FAILED	0x800F
AT_EAP_ENABLE_FAILED	0x8010
AT_EAP_ALREADY_CONNECTED	0x8011
AT_EAP_GET_SSID_FAILED	0x8012
AT_EAP_SSID_NULL	0x8013
AT_EAP_SSID_LEN_ERROR	0x8014
AT_EAP_GET_METHOD_FAILED	0x8015
AT_EAP_CONN_TIMEOUT	0x8016
AT_EAP_GET_IDENTITY_FAILED	0x8017
AT_EAP_IDENTITY_LEN_ERROR	0x8018
AT_EAP_GET_USERNAME_FAILED	0x8019
AT_EAP_USERNAME_LEN_ERROR	0x801A
AT_EAP_GET_PASSWORD_FAILED	0x801B
AT_EAP_PASSWORD_LEN_ERROR	0x801C
AT_EAP_GET_SECURITY_FAILED	0x801D
AT_EAP_SECURITY_ERROR	0x801E
AT_EAP_METHOD_SECURITY_UNMATCHED	0x801F
AT_EAP_PARAMETER_COUNTS_ERROR	0x8020
AT_EAP_GET_WIFI_MODE_ERROR	0x8021
AT_EAP_WIFI_MODE_NOT_STA	0x8022
AT_EAP_SET_CONFIG_FAILED	0x8023
AT_EAP_METHOD_ERROR	0x8024

说明¶

若 AT+SYSSTORE=1，配置更改将保存到 NVS 分区
使用本命令需开启 Station 模式
使用 TLS 认证方式需使能客户端证书

AT+CWHOSTNAME：查询/设置 ESP Station 的主机名称¶

查询命令¶

功能：

查询 ESP Station 的主机名称

命令：

AT+CWHOSTNAME?

响应：

+CWHOSTNAME:<hostname>

OK

设置命令¶

功能：

设置 ESP Station 的主机名称

命令：

AT+CWHOSTNAME=<hostname>

响应：

OK

若没开启 Station 模式，则返回：

ERROR

参数¶

<hostname>：ESP Station 的主机名称，最大长度：32 字节

说明¶

配置更改不保存到 flash

示例¶

AT+CWMODE=3
AT+CWHOSTNAME="my_test"

AT+CWCOUNTRY：查询/设置 Wi-Fi 国家代码¶

查询命令¶

功能：

查询 Wi-Fi 国家代码

命令：

AT+CWCOUNTRY?

响应：

+CWCOUNTRY:<country_policy>,<country_code>,<start_channel>,<total_channel_count>

OK

设置命令¶

功能：

设置 Wi-Fi 国家代码

命令：

AT+CWCOUNTRY=<country_policy>,<country_code>,<start_channel>,<total_channel_count>

响应：

OK

参数¶

<country_policy>：
- 0: 将国家代码改为 ESP 设备连入的 AP 的国家代码
- 1: 不改变国家代码，始终保持本命令设置的国家代码
<country_code>：国家代码，最大长度：3 个字符
<start_channel>：起始信号道，范围：[1,14]
<total_channel_count>：信道总个数

说明¶

配置更改不保存到 flash

示例¶

AT+CWMODE=3
AT+CWCOUNTRY=1,"CN",1,13

TCP/IP AT 命令¶

[English]

AT+CIPV6: 启用/禁用 IPv6 网络 (IPv6)
AT+CIPSTATE：查询 TCP/UDP/SSL 连接信息
AT+CIPSTATUS (弃用)：查询 TCP/UDP/SSL 连接状态和信息
AT+CIPDOMAIN：域名解析
AT+CIPSTART：建立 TCP 连接、UDP 传输或 SSL 连接
AT+CIPSTARTEX：建立自动分配 ID 的 TCP 连接、UDP 传输或 SSL 连接
[仅适用数据模式] +++: 退出数据模式
AT+CIPSEND：在普通传输模式或 Wi-Fi 透传模式下发送数据
AT+CIPSENDL：在普通传输模式下并行发送长数据
AT+CIPSENDLCFG：设置 AT+CIPSENDL 命令的属性
AT+CIPSENDEX：在普通传输模式下采用扩展的方式发送数据
AT+CIPCLOSE：关闭 TCP/UDP/SSL 连接
AT+CIFSR：查询本地 IP 地址和 MAC 地址
AT+CIPMUX：启用/禁用多连接模式
AT+CIPSERVER：建立/关闭 TCP 或 SSL 服务器
AT+CIPSERVERMAXCONN：查询/设置服务器允许建立的最大连接数
AT+CIPMODE：查询/设置传输模式
AT+SAVETRANSLINK：设置开机透传模式信息
AT+CIPSTO：查询/设置本地 TCP 服务器超时时间
AT+CIPSNTPCFG：查询/设置时区和 SNTP 服务器
AT+CIPSNTPTIME：查询 SNTP 时间
AT+CIPSNTPINTV：查询/设置 SNTP 时间同步的间隔
AT+CIUPDATE：通过 Wi-Fi 升级固件
AT+CIPDINFO：设置 +IPD 消息详情
AT+CIPSSLCCONF：查询/设置 SSL 客户端配置
AT+CIPSSLCCN：查询/设置 SSL 客户端的公用名 (common name)
AT+CIPSSLCSNI：查询/设置 SSL 客户端的 SNI
AT+CIPSSLCALPN：查询/设置 SSL 客户端 ALPN
AT+CIPSSLCPSK：查询/设置 SSL 客户端的 PSK
AT+CIPRECONNINTV：查询/设置 Wi-Fi 透传模式下的 TCP/UDP/SSL 重连间隔
AT+CIPRECVMODE：查询/设置 socket 接收模式
AT+CIPRECVDATA：获取被动接收模式下的 socket 数据
AT+CIPRECVLEN：查询被动接收模式下 socket 数据的长度
AT+PING：ping 对端主机
AT+CIPDNS：查询/设置 DNS 服务器信息
AT+CIPTCPOPT：查询/设置 socket 选项

AT+CIPV6: 启用/禁用 IPv6 网络 (IPv6)¶

查询命令¶

功能：

查询 IPv6 网络是否使能

命令：

AT+CIPV6?

响应：

+CIPV6:<enable>

OK

设置命令¶

功能：

启用/禁用 IPv6 网络

命令：

AT+CIPV6=<enable>

响应：

OK

参数¶

<enable>: IPv6 网络使能状态。默认值：0
- 0: 禁用 IPv6 网络
- 1: 启用 IPv6 网络

说明¶

在使用基于 IPv6 网络的上层应用前，需要先启用 IPv6 网络。（例如：基于 IPv6 网络使用 TCP/UDP/SSL/PING/DNS，也称为 TCP6/UDP6/SSL6/PING6/DNS6 或 TCPv6/UDPv6/SSLv6/PINGv6/DNSv6）

AT+CIPSTATE：查询 TCP/UDP/SSL 连接信息¶

查询命令¶

命令：

AT+CIPSTATE?

响应：

当有连接时，AT 返回：

+CIPSTATE:<link ID>,<"type">,<"remote IP">,<remote port>,<local port>,<tetype>

OK

当没有连接时，AT 返回：

OK

参数¶

<link ID>：网络连接 ID (0 ~ 4)，用于多连接的情况
<”type”>：字符串参数，表示传输类型：”TCP”、”UDP”、”SSL”、”TCPv6”、”UDPv6” 或 “SSLv6”
<”remote IP”>：字符串参数，表示远端 IPv4 地址或 IPv6 地址
<remote port>：远端端口值
<local port>：ESP 本地端口值
<tetype>:
- 0: ESP 设备作为客户端
- 1: ESP 设备作为服务器

AT+CIPSTATUS (弃用)：查询 TCP/UDP/SSL 连接状态和信息¶

执行命令¶

命令：

AT+CIPSTATUS

响应：

STATUS:<stat>
+CIPSTATUS:<link ID>,<"type">,<"remote IP">,<remote port>,<local port>,<tetype>
OK

参数¶

<stat>：ESP station 接⼝的状态
- 0: ESP station 为未初始化状态
- 1: ESP station 为已初始化状态，但还未开始 Wi-Fi 连接
- 2: ESP station 已连接 AP，获得 IP 地址
- 3: ESP station 已建立 TCP、UDP 或 SSL 传输
- 4: ESP 设备所有的 TCP、UDP 和 SSL 均断开
- 5: ESP station 开始过 Wi-Fi 连接，但尚未连接上 AP 或从 AP 断开
<link ID>：网络连接 ID (0 ~ 4)，用于多连接的情况
<”type”>：字符串参数，表示传输类型：”TCP”、”UDP”、”SSL”、”TCPv6”、”UDPv6” 或 “SSLv6”
<”remote IP”>：字符串参数，表示远端 IPv4 地址或 IPv6 地址
<remote port>：远端端口值
<local port>：ESP 本地端口值
<tetype>:
- 0: ESP 设备作为客户端
- 1: ESP 设备作为服务器

说明¶

建议您使用 AT+CWSTATE 命令查询 Wi-Fi 状态，使用 AT+CIPSTATE 命令查询 TCP/UDP/SSL 状态。

AT+CIPDOMAIN：域名解析¶

设置命令¶

命令：

AT+CIPDOMAIN=<"domain name">[,<ip network>]

响应：

+CIPDOMAIN:<"IP address">

OK

参数¶

<”domain name”>：待解析的域名
<ip network>：首选 IP 网络。默认值：1
- 1：首选解析为 IPv4 地址
- 2：只解析为 IPv4 地址
- 3：只解析为 IPv6 地址
<”IP address”>：解析出的 IP 地址

示例¶

AT+CWMODE=1                       // 设置 station 模式
AT+CWJAP="SSID","password"        // 连接网络
AT+CIPDOMAIN="iot.espressif.cn"   // 域名解析

// 域名解析，只解析为 IPv4 地址
AT+CIPDOMAIN="iot.espressif.cn",2

// 域名解析，只解析为 IPv6 地址
AT+CIPDOMAIN="ipv6.test-ipv6.com",3

// 域名解析，首选解析为 IPv4 地址
AT+CIPDOMAIN="ds.test-ipv6.com",1

AT+CIPSTART：建立 TCP 连接、UDP 传输或 SSL 连接¶

建立 TCP 连接¶

设置命令¶

命令：

// 单连接 (AT+CIPMUX=0):
AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<keep alive>][,<"local IP">]

// 多连接 (AT+CIPMUX=1):
AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<keep alive>][,<"local IP">]

响应：

单连接模式下，返回：

CONNECT

OK

多连接模式下，返回：

<link ID>,CONNECT

OK

参数¶

<link ID>：网络连接 ID (0 ~ 4)，用于多连接的情况
<”type”>：字符串参数，表示网络连接类型，”TCP” 或 “TCPv6”。默认值：”TCP”
<”remote host”>：字符串参数，表示远端 IPv4 地址、IPv6 地址，或域名
<remote port>：远端端口值
<keep alive>：TCP keep-alive 间隔，默认值：0
- 0: 禁用 TCP keep-alive 功能
- 1 ~ 7200: 检测间隔，单位：秒
<”local IP”>：连接绑定的本机 IPv4 地址或 IPv6 地址，该参数在本地多网络接口时和本地多 IP 地址时非常有用。默认为禁用，如果您想使用，需自行设置，空值也为有效值

说明¶

如果想基于 IPv6 网络建立 TCP 连接，需要先设置 AT+CIPV6=1，再通过 AT+CWJAP 获取到一个 IPv6 地址
<keep alive> 参数最终会配置到 socket 选项 TCP_KEEPIDLE，keepalive 另外的　socket 选项 TCP_KEEPINTVL 默认会使用 1，TCP_KEEPCNT 默认会使用 3

示例¶

AT+CIPSTART="TCP","iot.espressif.cn",8000
AT+CIPSTART="TCP","192.168.101.110",1000
AT+CIPSTART="TCP","192.168.101.110",2500,60
AT+CIPSTART="TCP","192.168.101.110",1000,,"192.168.101.100"
AT+CIPSTART="TCPv6","test-ipv6.com",80
AT+CIPSTART="TCPv6","fe80::860d:8eff:fe9d:cd90",1000,,"fe80::411c:1fdb:22a6:4d24"

// esp-at 已通过 AT+CWJAP 获取到 IPv6 全局地址
AT+CIPSTART="TCPv6","2404:6800:4005:80b::2004",80,,"240e:3a1:2070:11c0:32ae:a4ff:fe80:65ac"

建立 UDP 传输¶

设置命令¶

命令：

// 单连接：(AT+CIPMUX=0)
AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<local port>,<mode>,<"local IP">]

// 多连接：(AT+CIPMUX=1)
AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<local port>,<mode>,<"local IP">]

响应：

单连接模式下，返回：

CONNECT

OK

多连接模式下，返回：

<link ID>,CONNECT

OK

参数¶

<link ID>：网络连接 ID (0 ~ 4)，用于多连接的情况
<”type”>：字符串参数，表示网络连接类型，”UDP” 或 “UDPv6”。默认值：”TCP”
<”remote host”>：字符串参数，表示远端 IPv4 地址、IPv6 地址，或域名
<remote port>：远端端口值
<local port>：ESP 设备的 UDP 端口值
<mode>：在 UDP Wi-Fi 透传下，本参数的值必须设为 0
- 0: 接收到 UDP 数据后，不改变对端 UDP 地址信息（默认）
- 1: 仅第一次接收到与初始设置不同的对端 UDP 数据时，改变对端 UDP 地址信息为发送数据设备的 IP 地址和端口
- 2: 每次接收到 UDP 数据时，都改变对端 UDP 地址信息为发送数据的设备的 IP 地址和端口
<”local IP”>：连接绑定的本机 IPv4 地址或 IPv6 地址，该参数在本地多网络接口时和本地多 IP 地址时非常有用。默认为禁用，如果您想使用，需自行设置，空值也为有效值

说明¶

如果 UDP 连接中的远端 IP 地址是 IPv4 组播地址 (224.0.0.0 ~ 239.255.255.255)，ESP 设备将发送和接收 UDPv4 组播
如果 UDP 连接中的远端 IP 地址是 IPv4 广播地址 (255.255.255.255)，ESP 设备将发送和接收 UDPv4 广播
如果 UDP 连接中的远端 IP 地址是 IPv6 组播地址 (FF00:0:0:0:0:0:0:0 ~ FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF)，ESP 设备将基于 IPv6 网络，发送和接收 UDP 组播
使用参数 <mode> 前，需先设置参数 <local port>
如果想基于 IPv6 网络建立 UDP 连接，需要先设置 AT+CIPV6=1, 再通过 AT+CWJAP 获取到一个 IPv6 地址

示例¶

// UDPv4 单播
AT+CIPSTART="UDP","192.168.101.110",1000,1002,2
AT+CIPSTART="UDP","192.168.101.110",1000,,,"192.168.101.100"

// 基于 IPv6 网络的 UDP 单播
AT+CIPSTART="UDPv6","fe80::32ae:a4ff:fe80:65ac",1000,,,"fe80::5512:f37f:bb03:5d9b"

// 基于 IPv6 网络的 UDP 多播
AT+CIPSTART="UDPv6","FF02::FC",1000,1002,0

建立 SSL 连接¶

设置命令¶

命令：

// 单连接：(AT+CIPMUX=0)
AT+CIPSTART=<"type">,<"remote host">,<remote port>[,<keep alive>,<"local IP">]

// 多连接：(AT+CIPMUX=1)
AT+CIPSTART=<link ID>,<"type">,<"remote host">,<remote port>[,<keep alive>,<"local IP">]

响应：

单连接模式下，返回：

CONNECT

OK

多连接模式下，返回：

<link ID>,CONNECT

OK

参数¶

<link ID>：网络连接 ID (0 ~ 4)，用于多连接的情况
<”type”>：字符串参数，表示网络连接类型，”SSL” 或 “SSLv6”。默认值：”TCP”
<”remote host”>：字符串参数，表示远端 IPv4 地址、IPv6 地址，或域名
<remote port>：远端端口值
<keep alive>：SSL 保留配置，默认值：0
<”local IP”>：连接绑定的本机 IPv4 地址或 IPv6 地址，该参数在本地多网络接口时和本地多 IP 地址时非常有用。默认为禁用，如果您想使用，需自行设置，空值也为有效值

说明¶

SSL 连接数量取决于可用内存和最大连接数量
SSL 连接需占用大量内存，内存不足会导致系统重启
如果 AT+CIPSTART 命令是基于 SSL 连接，且每个数据包的超时时间为 10 秒，则总超时时间会变得更长，具体取决于握手数据包的个数
如果想基于 IPv6 网络建立 SSL 连接，需要先设置 AT+CIPV6=1, 再通过 AT+CWJAP 获取到一个 IPv6 地址
<keep alive> 参数最终会配置到 socket 选项 TCP_KEEPIDLE，keepalive 另外的　socket 选项 TCP_KEEPINTVL 默认会使用 1，TCP_KEEPCNT 默认会使用 3

示例¶

AT+CIPSTART="SSL","iot.espressif.cn",8443
AT+CIPSTART="SSL","192.168.101.110",1000,,"192.168.101.100"

// esp-at 已通过 AT+CWJAP 获取到 IPv6 全局地址
AT+CIPSTART="SSLv6","240e:3a1:2070:11c0:6972:6f96:9147:d66d",1000,,"240e:3a1:2070:11c0:55ce:4e19:9649:b75"

AT+CIPSTARTEX：建立自动分配 ID 的 TCP 连接、UDP 传输或 SSL 连接¶

本命令与 AT+CIPSTART 相似，不同点在于：在多连接的情况下 (AT+CIPMUX=1) 无需手动分配 ID，系统会自动为新建的连接分配 ID。

[仅适用数据模式] +++：退出数据模式 ¶

特殊执行命令¶

功能：

退出数据模式，进入命令模式

Command:

// 仅适用数据模式
+++

说明¶

此特殊执行命令包含有三个相同的 + 字符（即 ASCII 码：0x2b），同时命令结尾没有 CR-LF 字符
确保第一个 + 字符前至少有 20 ms 时间间隔内没有其他输入，第三个 + 字符后至少有 20 ms 时间间隔内没有其他输入，三个 + 字符之间至多有 20 ms 时间间隔内没有其他输入。否则，+ 字符会被当做普通数据发送出去
本条特殊执行命令没有命令回复
请至少间隔 1 秒再发下一条 AT 命令

AT+CIPSEND：在普通传输模式或 Wi-Fi 透传模式下发送数据¶

设置命令¶

功能：

普通传输模式下，指定长度发送数据。如果您要发送的数据长度大于 8192 字节，请使用 AT+CIPSENDL 命令发送。

命令：

// 单连接：(AT+CIPMUX=0)
AT+CIPSEND=<length>

// 多连接：(AT+CIPMUX=1)
AT+CIPSEND=<link ID>,<length>

// UDP 传输可指定对端主机和端口
AT+CIPSEND=[<link ID>,]<length>[,<"remote host">,<remote port>]

响应：

OK

>

上述响应表示 AT 已准备好接收串行数据，此时您可以输入数据，当 AT 接收到的数据长度达到 <length> 后，数据传输开始。

如果未建立连接或数据传输时连接被断开，返回：

ERROR

如果数据传输成功，返回：

SEND OK

执行命令¶

功能：

进入 Wi-Fi 透传模式

命令：

AT+CIPSEND

响应：

OK
>

或

ERROR

进入 Wi-Fi 透传模式，ESP 设备每次最大接收 8192 字节，最大发送 2920 字节。如果当前接收的数据长度大于最大发送字节数，AT 将立即发送；否则，接收的数据将在 20 ms 内发送。当输入单独一包 +++ 时，退出透传模式下的数据发送模式，请至少间隔 1 秒再发下一条 AT 命令。

本命令必须在开启透传模式以及单连接下使用。若为 Wi-Fi UDP 透传，AT+CIPSTART 命令的参数 <mode> 必须设置为 0。

参数¶

<link ID>：网络连接 ID (0 ~ 4)，用于多连接的情况
<length>：数据长度，最大值：8192 字节
<”remote host”>：UDP 传输可以指定对端主机：IPv4 地址、IPv6 地址，或域名
<remote port>：UDP 传输可以指定对端端口

说明¶

您可以使用 AT+CIPTCPOPT 命令来为每个 TCP 连接配置套接字选项。例如：设置 <so_sndtimeo> 为 5000，则 TCP 发送会在 5 秒内返回，无论成功还是失败。这可以节省 MCU 等待 AT 命令回复的时间。

AT+CIPSENDL：在普通传输模式下并行发送长数据¶

设置命令¶

功能：

普通传输模式下，指定长度，并行发送数据（AT 命令端口接收数据和 AT 往对端发送数据是并行的）。您可以使用 AT+CIPSENDLCFG 命令配置本条命令。如果您要发送的数据长度小于 8192 字节，您也可以使用 AT+CIPSEND 命令发送。

命令：

// 单连接：(AT+CIPMUX=0)
AT+CIPSENDL=<length>

// 多连接：(AT+CIPMUX=1)
AT+CIPSENDL=<link ID>,<length>

// UDP 传输可指定对端主机和端口
AT+CIPSENDL=[<link ID>,]<length>[,<"remote host">,<remote port>]

响应：

OK

>

上述响应表示 AT 进入数据模式并且已准备好接收 AT 命令端口的数据，此时您可以输入数据，一旦 AT 命令端口接收到数据，数据就会被发往底层协议，数据传输开始。

如果传输已开始，系统会根据 AT+CIPSENDLCFG 配置上报消息：

+CIPSENDL:<had sent len>,<port recv len>

如果传输被 +++ 命令取消，系统返回：

SEND CANCELLED

如果所有数据没有被完全发出去，系统最终返回：

SEND FAIL

如果所有数据被成功发往协议栈，系统最终返回：

SEND OK

当连接断开时，您可以发送 +++ 命令取消传输，同时 ESP 设备会从数据模式退出。否则，AT 命令端口会一直接收数据，直到收到指定的 <length> 长度数据后，才会退出数据模式。

参数¶

<link ID>：网络连接 ID (0 ~ 4)，用于多连接的情况
<length>：数据长度，最大值：2 ³¹ - 1 字节
<”remote host”>：UDP 传输可以指定对端主机：IPv4 地址、IPv6 地址，或域名
<remote port>：UDP 传输可以指定对端端口
<had sent len>：成功发到底层协议栈的数据长度
<port recv len>：AT 命令端口收到的数据总长度

说明¶

您可以使用 AT+CIPTCPOPT 命令来为每个 TCP 连接配置套接字选项。例如：设置 <so_sndtimeo> 为 5000，则 TCP 发送会在 5 秒内返回，无论成功还是失败。这可以节省 MCU 等待 AT 命令回复的时间。

AT+CIPSENDLCFG: 设置 AT+CIPSENDL 命令的属性¶

查询命令¶

功能：

查询 AT+CIPSENDL 命令的配置

命令：

AT+CIPSENDLCFG?

响应：

+CIPSENDLCFG:<report size>,<transmit size>

OK

设置命令¶

功能：

设置 AT+CIPSENDL 命令的配置

命令：

AT+CIPSENDLCFG:<report size>[,<transmit size>]

响应：

OK

参数¶

<report size>: AT+CIPSENDL 命令中的上报块大小。默认值：1024。范围：[100,2 ²⁰]。例如：设置 <report size> 值为 100，则 AT+CIPSENDL 命令回复里的 <had sent len> 上报序列为（100，200，300，400，……）。最后的 <had sent len> 上报值总是等于实际传输的数据长度。
<transmit size>: AT+CIPSENDL 命令中的传输块大小，它指定了数据发往协议栈的数据块大小。默认值：2920。范围：[100,2920]。如果收到的数据长度大于等于 <transmit size>，则数据会被立即发往底层协议栈；否则，数据会等待 20 毫秒后再发往底层协议栈。

说明¶

对于吞吐量小但对实时性要求高的设备，推荐您设置较小的 <transmit size>。也推荐您通过 AT+CIPTCPOPT 命令设置 TCP_NODELAY 属性。
对于吞吐量大的设备，推荐您设置较大的 <transmit size>。也推荐您阅读如何提高 ESP-AT 吞吐性能。

AT+CIPSENDEX：在普通传输模式下采用扩展的方式发送数据¶

设置命令¶

功能：

普通传输模式下，指定长度发送数据，或者使用字符串 \0 (0x5c, 0x30 ASCII) 触发数据发送

命令：

// 单连接：(AT+CIPMUX=0)
AT+CIPSENDEX=<length>

// 多连接：(AT+CIPMUX=1)
AT+CIPSENDEX=<link ID>,<length>

// UDP 传输可指定对端 IP 地址和端口：
AT+CIPSENDEX=[<link ID>,]<length>[,<"remote host">,<remote port>]

响应：

OK

>

上述响应表示 AT 已准备好接收串行数据，此时您可以输入指定长度的数据，当 AT 接收到的数据长度达到 <length> 后或数据中出现 \0 字符时，数据传输开始。

如果未建立连接或数据传输时连接被断开，返回：

ERROR

如果数据传输成功，返回：

SEND OK

参数¶

<link ID>：网络连接 ID (0 ~ 4)，用于多连接的情况
<length>：数据长度，最大值：8192 字节
<”remote host”>：UDP 传输可以指定对端主机：IPv4 地址、IPv6 地址，或域名
<remote port>：UDP 传输可以指定对端端口

说明¶

当数据长度满足要求时，或数据中出现 \0 字符时 (0x5c，0x30 ASCII)，数据传输开始，系统返回普通命令模式，等待下一条 AT 命令
如果数据中包含 \<any>，则会去掉反斜杠，只使用 <any> 符号
如果需要发送 \0，请转义为 \\0
您可以使用 AT+CIPTCPOPT 命令来为每个 TCP 连接配置套接字选项。例如：设置 <so_sndtimeo> 为 5000，则 TCP 发送会在 5 秒内返回，无论成功还是失败。这可以节省 MCU 等待 AT 命令回复的时间。

AT+CIPCLOSE：关闭 TCP/UDP/SSL 连接¶

设置命令¶

功能：

关闭多连接模式下的 TCP/UDP/SSL 连接

命令：

AT+CIPCLOSE=<link ID>

响应：

<link ID>,CLOSED

OK

执行命令¶

功能：

关闭单连接模式下的 TCP/UDP/SSL 连接

AT+CIPCLOSE

响应：

CLOSED

OK

参数¶

<link ID>：需关闭的网络连接 ID，如果设为 5，则表示关闭所有连接

AT+CIFSR：查询本地 IP 地址和 MAC 地址¶

执行命令¶

命令：

AT+CIFSR

响应：

+CIFSR:APIP,<"APIP">
+CIFSR:APIP6LL,<"APIP6LL">
+CIFSR:APIP6GL,<"APIP6GL">
+CIFSR:APMAC,<"APMAC">
+CIFSR:STAIP,<"STAIP">
+CIFSR:STAIP6LL,<"STAIP6LL">
+CIFSR:STAIP6GL,<"STAIP6GL">
+CIFSR:STAMAC,<"STAMAC">
+CIFSR:ETHIP,<"ETHIP">
+CIFSR:ETHIP6LL,<"ETHIP6LL">
+CIFSR:ETHIP6GL,<"ETHIP6GL">
+CIFSR:ETHMAC,<"ETHMAC">

OK

参数¶

<”APIP”>: ESP SoftAP 的 IPv4 地址
<”APIP6LL”>: ESP SoftAP 的 IPv6 本地链路地址
<”APIP6GL”>: ESP SoftAP 的 IPv6 全局地址
<”APMAC”>: ESP SoftAP 的 MAC 地址
<”STAIP”>: ESP station 的 IPv4 地址
<”STAIP6LL”>: ESP station 的 IPv6 本地链路地址
<”STAIP6GL”>: ESP station 的 IPv6 全局地址
<”STAMAC”>: ESP station 的 MAC 地址
<”ETHIP”>: ESP ethernet 的 IPv4 地址
<”ETHIP6LL”>: ESP ethernet 的 IPv6 本地链路地址
<”ETHIP6GL”>: ESP ethernet 的 IPv6 全局地址
<”ETHMAC”>: ESP ethernet 的 MAC 地址

说明¶

只有当 ESP 设备获取到有效接口信息后，才能查询到它的 IP 地址和 MAC 地址

AT+CIPMUX：启用/禁用多连接模式¶

查询命令¶

功能：

查询连接模式

命令：

AT+CIPMUX?

响应：

+CIPMUX:<mode>
OK

设置命令¶

功能：

设置连接模式

命令：

AT+CIPMUX=<mode>

响应：

OK

参数¶

<mode>：连接模式，默认值：0
- 0: 单连接
- 1: 多连接

说明¶

只有当所有连接都断开时才可更改连接模式
只有普通传输模式 (AT+CIPMODE=0)，才能设置为多连接
如果建立了 TCP/SSL 服务器，想切换为单连接，必须关闭服务器 (AT+CIPSERVER=0)

示例¶

AT+CIPMUX=1

AT+CIPSERVER：建立/关闭 TCP 或 SSL 服务器¶

查询命令¶

功能：

查询 TCP/SSL 服务器状态

命令：

AT+CIPSERVER?

响应：

+CIPSERVER:<mode>[,<port>,<"type">][,<CA enable>]

OK

设置命令¶

命令：

AT+CIPSERVER=<mode>[,<param2>][,<"type">][,<CA enable>]

响应：

OK

参数¶

<mode>：
- 0: 关闭服务器
- 1: 建立服务器
<param2>：参数 <mode> 不同，则此参数意义不同：

如果 <mode> 是 1，<param2> 代表端口号。默认值：333

如果 <mode> 是 0，<param2> 代表服务器是否关闭所有客户端。默认值：0

0：关闭服务器并保留现有客户端连接

1：关闭服务器并关闭所有连接

<”type”>：服务器类型：”TCP”，”TCPv6”，”SSL”，或 “SSLv6”. 默认值：”TCP”
<CA enable>：
- 0：不使用 CA 认证
- 1：使用 CA 认证

说明¶

多连接情况下 (AT+CIPMUX=1)，才能开启服务器
创建服务器后，自动建立服务器监听，最多只允许创建一个服务器
当有客户端接入，会自动占用一个连接 ID
如果想基于 IPv6 网络建立服务器，需要先设置 AT+CIPV6=1，再通过 AT+CWJAP 获取到一个 IPv6 地址
关闭服务器时参数 <"type"> 和 <CA enable> 必须省略

示例¶

// 建立 TCP 服务器
AT+CIPMUX=1
AT+CIPSERVER=1,80

// 建立 SSL 服务器
AT+CIPMUX=1
AT+CIPSERVER=1,443,"SSL",1

// 基于 IPv6 网络，创建 SSL 服务器
AT+CIPMUX=1
AT+CIPSERVER=1,443,"SSLv6",0

// 关闭服务器并且关闭所有连接
AT+CIPSERVER=0,1

AT+CIPSERVERMAXCONN：查询/设置服务器允许建立的最大连接数¶

查询命令¶

功能：

查询 TCP 或 SSL 服务器允许建立的最大连接数

命令：

AT+CIPSERVERMAXCONN?

响应：

+CIPSERVERMAXCONN:<num>
OK

设置命令¶

功能：

设置 TCP 或 SSL 服务器允许建立的最大连接数

命令：

AT+CIPSERVERMAXCONN=<num>

响应：

OK

参数¶

<num>：TCP 或 SSL 服务器允许建立的最大连接数

说明¶

如需设置最大连接数 (AT+CIPSERVERMAXCONN=<num>)，请在创建服务器之前设置。

示例¶

AT+CIPMUX=1
AT+CIPSERVERMAXCONN=2
AT+CIPSERVER=1,80

AT+CIPMODE：查询/设置传输模式¶

查询命令¶

功能：

查询传输模式

命令：

AT+CIPMODE?

响应：

+CIPMODE:<mode>
OK

设置命令¶

功能：

设置传输模式

命令：

AT+CIPMODE=<mode>

响应：

OK

参数¶

<mode>:
- 0: 普通传输模式
- 1: Wi-Fi 透传接收模式，仅支持 TCP 单连接、UDP 固定通信对端、SSL 单连接的情况

说明¶

配置更改不保存到 flash。

示例¶

AT+CIPMODE=1

AT+SAVETRANSLINK：设置开机透传模式信息¶

设置开机进入 TCP/SSL 透传模式信息¶

设置命令¶

命令：

AT+SAVETRANSLINK=<mode>,<"remote host">,<remote port>[,<"type">,<keep alive>]

响应：

OK

参数¶

<mode>:
- 0: 关闭 ESP 上电进入 Wi-Fi 透传模式
- 1: 开启 ESP 上电进入 Wi-Fi 透传模式
<”remote host”>：字符串参数，表示远端 IPv4 地址、IPv6 地址，或域名
<remote port>：远端端口值
<”type”>：字符串参数，表示传输类型：”TCP”，”TCPv6”，”SSL”，或 “SSLv6”。默认值：”TCP”
<keep alive>：TCP keep-alive 间隔，默认值：0
- 0: 禁用 keep-alive 功能
- 1 ~ 7200: 检测间隔，单位：秒

说明¶

本设置将 Wi-Fi 开机透传模式信息保存在 NVS 区，若参数 <mode> 为 1 ，下次上电自动进入透传模式。需重启生效。
只要远端 IP 地址（域名）、端口的值符合规范，本设置就会被保存到 flash。
如果想基于 IPv6 网络建立透传连接，需要先设置 AT+CIPV6=1，再通过 AT+CWJAP 获取到一个 IPv6 地址

示例¶

AT+SAVETRANSLINK=1,"192.168.6.110",1002,"TCP"
AT+SAVETRANSLINK=1,"www.baidu.com",443,"SSL"
AT+SAVETRANSLINK=1,"240e:3a1:2070:11c0:55ce:4e19:9649:b75",8080,"TCPv6"
AT+SAVETRANSLINK=1,"240e:3a1:2070:11c0:55ce:4e19:9649:b75",8080,"SSLv6

设置开机进入 UDP 透传模式信息¶

设置¶

命令：

AT+SAVETRANSLINK=<mode>,<"remote host">,<remote port>,[<"type">,<local port>]

响应：

OK

参数¶

<mode>:
- 0: 关闭 ESP 上电进入 Wi-Fi 透传模式
- 1: 开启 ESP 上电进入 Wi-Fi 透传模式
<”remote host”>：字符串参数，表示远端 IPv4 地址、IPv6 地址，或域名
<remote port>：远端端口值
<”type”>：字符串参数，表示传输类型：”UDP” 或 “UDPv6”。默认值：”TCP”
[<local port>]：开机进入 UDP 传输时，使用的本地端口

说明¶

本设置将 Wi-Fi 开机透传模式信息保存在 NVS 区，若参数 <mode> 为 1 ，下次上电自动进入透传模式。需重启生效
只要远端 IP 地址（域名）、端口的值符合规范，本设置就会被保存到 flash
如果想基于 IPv6 网络建立透传连接，需要先设置 AT+CIPV6=1，再通过 AT+CWJAP 获取到一个 IPv6 地址

示例¶

AT+SAVETRANSLINK=1,"192.168.6.110",1002,"UDP",1005
AT+SAVETRANSLINK=1,"240e:3a1:2070:11c0:55ce:4e19:9649:b75",8081,"UDPv6",1005

AT+CIPSTO：查询/设置本地 TCP/SSL 服务器超时时间¶

查询命令¶

功能：

查询本地 TCP/SSL 服务器超时时间

命令：

AT+CIPSTO?

响应：

+CIPSTO:<time>
OK

设置命令¶

功能：

设置本地 TCP/SSL 服务器超时时间

命令：

AT+CIPSTO=<time>

响应：

OK

参数¶

<time>：本地 TCP/SSL 服务器超时时间，单位：秒，取值范围：[0,7200]

说明¶

当 TCP/SSL 客户端在 <time> 时间内未发生数据通讯时，ESP 服务器会断开此连接。
如果设置参数 <time> 为 0，则连接永远不会超时，不建议这样设置。
在设定的时间内，当客户端发起与服务器的通信时，计时器将重新计时。超时后，客户端被关闭。在设定的时间内，如果服务器发起与客户端的通信，计时器将不会重新计时。超时后，客户端被关闭。

示例¶

AT+CIPMUX=1
AT+CIPSERVER=1,1001
AT+CIPSTO=10

AT+CIPSNTPCFG：查询/设置时区和 SNTP 服务器¶

查询命令¶

命令：

AT+CIPSNTPCFG?

响应：

+CIPSNTPCFG:<enable>,<timezone>,<SNTP server1>[,<SNTP server2>,<SNTP server3>]
OK

设置命令¶

命令：

AT+CIPSNTPCFG=<enable>,<timezone>[,<SNTP server1>,<SNTP server2>,<SNTP server3>]

响应：

OK

参数¶

<enable>：设置 SNTP 服务器：
- 1: 设置 SNTP 服务器；
- 0: 不设置 SNTP 服务器。
<timezone>：支持以下两种格式：
- 第一种格式的范围：[-12,14]，它以小时为单位，通过与协调世界时 (UTC) 的偏移来标记大多数时区（UTC−12:00 至 UTC+14:00）；
- 第二种格式为 UTC 偏移量， UTC 偏移量 指定了你需要加多少时间到 UTC 时间上才能得到本地时间，通常显示为 [+|-][hh]mm。如果当地时区在本初子午线以西，则为负数，如果在东边，则为正数。小时 (hh) 必须在 -12 到 14 之间，分钟 (mm) 必须在 0 到 59 之间。例如，如果您想把时区设置为新西兰查塔姆群岛，即 UTC+12:45，您应该把 <timezone> 参数设置为 1245，更多信息请参考 UTC 偏移量。
[<SNTP server1>]：第一个 SNTP 服务器。
[<SNTP server2>]：第二个 SNTP 服务器。
[<SNTP server3>]：第三个 SNTP 服务器。

说明¶

设置命令若未填写以上三个 SNTP 服务器参数，则默认使用 “cn.ntp.org.cn”、”ntp.sjtu.edu.cn” 和 “us.pool.ntp.org” 其中之一。
对于查询命令，查询的 <timezone> 参数可能会和设置的 <timezone> 参数不一样。因为 <timezone> 参数支持第二种 UTC 偏移量格式，例如：设置 AT+CIPSNTPCFG=1,015，那么查询时，ESP-AT 会忽略时区参数的前导 0，即设置值是 15。不属于第一种格式，所以按照第二种 UTC 偏移量格式解析，也就是 UTC+00:15，也就是查询出来的是 0 时区。

示例¶

// 使能 SNTP 服务器，设置中国时区 (UTC+08:00)
AT+CIPSNTPCFG=1,8,"cn.ntp.org.cn","ntp.sjtu.edu.cn"
或
AT+CIPSNTPCFG=1,800,"cn.ntp.org.cn","ntp.sjtu.edu.cn"

// 使能 SNTP 服务器，设置美国纽约的时区 (UTC−05:00)
AT+CIPSNTPCFG=1,-5,"0.pool.ntp.org","time.google.com"
或
AT+CIPSNTPCFG=1,-500,"0.pool.ntp.org","time.google.com"

// 使能 SNTP 服务器，设置新西兰时区查塔姆群岛的时区 (Chatham Islands, UTC+12:45)
AT+CIPSNTPCFG=1,1245,"0.pool.ntp.org","time.google.com"

AT+CIPSNTPTIME：查询 SNTP 时间¶

查询命令¶

命令：

AT+CIPSNTPTIME?

响应：

+CIPSNTPTIME:<asctime style time>
OK

说明¶

有关 asctime 时间的定义请见 asctime man page。

示例¶

AT+CWMODE=1
AT+CWJAP="1234567890","1234567890"
AT+CIPSNTPCFG=1,8,"cn.ntp.org.cn","ntp.sjtu.edu.cn"
AT+CIPSNTPTIME?
+CIPSNTPTIME:Tue Oct 19 17:47:56 2021
OK

或

AT+CWMODE=1
AT+CWJAP="1234567890","1234567890"
AT+CIPSNTPCFG=1,530
AT+CIPSNTPTIME?
+CIPSNTPTIME:Tue Oct 19 15:17:56 2021
OK

AT+CIPSNTPINTV：查询/设置 SNTP 时间同步的间隔¶

查询命令¶

命令：

AT+CIPSNTPINTV?

响应：

+CIPSNTPINTV:<interval second>

OK

设置命令¶

命令：

AT+CIPSNTPINTV=<interval second>

响应：

OK

参数¶

<interval second>：SNTP 时间同步间隔。单位：秒。范围：[15,4294967]。

示例¶

AT+CIPSNTPCFG=1,8,"cn.ntp.org.cn","ntp.sjtu.edu.cn"

OK

// 每小时同步一次时间
AT+CIPSNTPINTV=3600

OK

AT+CIUPDATE：通过 Wi-Fi 升级固件¶

ESP-AT 在运行时，通过 Wi-Fi 从指定的服务器上下载新固件到某些分区，从而升级固件。

查询命令¶

功能：

查询 ESP 设备的升级状态

命令：

AT+CIUPDATE?

响应：

+CIPUPDATE:<state>

OK

执行命令¶

功能：

在阻塞模式下通过 OTA 升级到 TCP 服务器上最新版本的固件

命令：

AT+CIUPDATE

响应：

请参考设置命令中的响应

设置命令¶

功能：

升级到服务器上指定版本的固件

命令：

AT+CIUPDATE=<ota mode>[,<version>][,<firmware name>][,<nonblocking>]

响应：

如果 OTA 在阻塞模式下成功，返回：

+CIPUPDATE:1
+CIPUPDATE:2
+CIPUPDATE:3
+CIPUPDATE:4

OK

如果 OTA 在非阻塞模式下成功，返回：

OK
+CIPUPDATE:1
+CIPUPDATE:2
+CIPUPDATE:3
+CIPUPDATE:4

如果在阻塞模式下 OTA 失败，返回：

+CIPUPDATE:<state>

ERROR

如果在非阻塞模式下 OTA 失败，返回：

OK
+CIPUPDATE:<state>
+CIPUPDATE:-1

参数¶

<ota mode>:
- 0: 通过 HTTP OTA；
- 1: 通过 HTTPS OTA，如果无效，请检查 ./build.py menuconfig > Component config > AT > OTA based upon ssl 是否使能，更多信息请见编译 ESP-AT 工程。
<version>：AT 版本，如 v1.2.0.0、v1.1.3.0 或 v1.1.2.0。
<firmware name>：升级的固件，如 ota、mqtt_ca、client_ca 或其它 at_customize.csv 中自定义的分区。
<nonblocking>:
- 0: 阻塞模式的 OTA（此模式下，直到 OTA 升级成功或失败后才可以发送 AT 命令）；
- 1: 非阻塞模式的 OTA（此模式下，升级完成后 (+CIPUPDATE:4) 需手动重启)。
<state>:
- 1: 找到服务器；
- 2: 连接至服务器；
- 3: 获得升级版本；
- 4: 完成升级；
- -1: 非阻塞模式下 OTA 失败。

说明¶

升级速度取决于网络状况。
如果网络条件不佳导致升级失败，AT 将返回 ERROR，请等待一段时间再试。
如果您直接使用乐鑫提供的 AT BIN, 本命令将从 Espressif Cloud 下载 AT 固件升级。
如果您使用的是自行编译的 AT BIN，请自行实现 AT+CIUPDATE FOTA 功能或者使用 AT+USEROTA 或者 AT+WEBSERVER 命令，可参考 ESP-AT 工程提供的示例 FOTA。
建议升级 AT 固件后，调用 AT+RESTORE 恢复出厂设置。
OTA 过程的超时时间为 3 分钟。
非阻塞模式响应中的 OK 和 +CIPUPDATE:<state> 在输出顺序上没有严格意义上的先后顺序。OK 可能在 +CIPUPDATE:<state> 之前输出，也有可能在 +CIPUPDATE:<state> 之后输出。
不建议升级到旧版本。
请参考如何实现 OTA 升级获取更多 OTA 命令。

示例¶

AT+CWMODE=1
AT+CWJAP="1234567890","1234567890"
AT+CIUPDATE
AT+CIUPDATE=1
AT+CIUPDATE=1,"v1.2.0.0"
AT+CIUPDATE=1,"v2.2.0.0","mqtt_ca"
AT+CIUPDATE=1,"v2.2.0.0","ota",1
AT+CIUPDATE=1,,,1
AT+CIUPDATE=1,,"ota",1
AT+CIUPDATE=1,"v2.2.0.0",,1

AT+CIPDINFO：设置 +IPD 消息详情¶

查询命令¶

命令：

AT+CIPDINFO?

响应：

+CIPDINFO:true
OK

或

+CIPDINFO:false
OK

设置命令¶

命令：

AT+CIPDINFO=<mode>

响应：

OK

参数¶

<mode>:
- 0: 在 “+IPD” 和 “+CIPRECVDATA” 消息中，不提示对端 IP 地址和端口信息
- 1: 在 “+IPD” 和 “+CIPRECVDATA” 消息中，提示对端 IP 地址和端口信息

示例¶

AT+CIPDINFO=1

AT+CIPSSLCCONF：查询/设置 SSL 客户端配置¶

查询命令¶

功能：

查询 ESP 作为 SSL 客户端时每个连接的配置信息

命令：

AT+CIPSSLCCONF?

响应：

+CIPSSLCCONF:<link ID>,<auth_mode>,<pki_number>,<ca_number>
OK

设置命令¶

命令：

// 单连接：(AT+CIPMUX=0)
AT+CIPSSLCCONF=<auth_mode>[,<pki_number>][,<ca_number>]

// 多连接：(AT+CIPMUX=1)
AT+CIPSSLCCONF=<link ID>,<auth_mode>[,<pki_number>][,<ca_number>]

响应：

OK

参数¶

<link ID>：网络连接 ID (0 ~ max)，在多连接的情况下，若参数值设为 max，则表示所有连接，本参数默认值为 5。
<auth_mode>:
- 0: 不认证，此时无需填写 <pki_number> 和 <ca_number> 参数；
- 1: ESP-AT 提供客户端证书供服务器端 CA 证书校验；
- 2: ESP-AT 客户端载入 CA 证书来校验服务器端的证书；
- 3: 相互认证。
<pki_number>：证书和私钥的索引，如果只有一个证书和私钥，其值应为 0。
<ca_number>：CA 的索引，如果只有一个 CA，其值应为 0。

说明¶

如果想要本配置立即生效，请在建立 SSL 连接前运行本命令。
配置更改将保存在 NVS 区，如果您使用 AT+SAVETRANSLINK 命令设置开机进入 Wi-Fi SSL 透传模式，ESP 将在下次上电时基于本配置建立 SSL 连接。

AT+CIPSSLCCN：查询/设置 SSL 客户端的公用名 (common name)¶

查询命令¶

功能：

查询每个 SSL 连接中客户端的通用名称

命令：

AT+CIPSSLCCN?

响应：

+CIPSSLCCN:<link ID>,<"common name">
OK

设置命令¶

命令：

// 单连接：(AT+CIPMUX=0)
AT+CIPSSLCCN=<"common name">

// 多连接：(AT+CIPMUX=1)
AT+CIPSSLCCN=<link ID>,<"common name">

响应：

OK

参数¶

<link ID>：网络连接 ID (0 ~ max)，在单连接的情况下，本参数值为 0；在多连接的情况下，若参数值设为 max，则表示所有连接；本参数默认值为 5。
<”common name”>：本参数用来认证服务器发送的证书中的公用名。公用名最大长度为 64 字节。

说明¶

如果想要本配置立即生效，请在建立 SSL 连接前运行本命令。

AT+CIPSSLCSNI：查询/设置 SSL 客户端的 SNI¶

查询命令¶

功能：

查询每个连接的 SNI 配置

命令：

AT+CIPSSLCSNI?

响应：

+CIPSSLCSNI:<link ID>,<"sni">
OK

设置命令¶

命令：

单连接：(AT+CIPMUX=0)
AT+CIPSSLCSNI=<"sni">

多连接：(AT+CIPMUX=1)
AT+CIPSSLCSNI=<link ID>,<"sni">

响应：

OK

参数¶

<link ID>：网络连接 ID (0 ~ max)，在单连接的情况下，本参数值为 0；在多连接的情况下，若参数值设为 max，则表示所有连接；本参数默认值为 5。
<”sni”>：ClientHello 里的 SNI。SNI 最大长度为 64 字节。

说明¶

如果想要本配置立即生效，请在建立 SSL 连接前运行本命令。

AT+CIPSSLCALPN：查询/设置 SSL 客户端 ALPN¶

查询命令¶

功能：

查询 ESP 作为 SSL 客户端时每个连接的 ALPN 配置

命令：

AT+CIPSSLCALPN?

响应：

+CIPSSLCALPN:<link ID>,<"alpn">[,<"alpn">][,<"alpn">]

OK

设置命令¶

命令：

// 单连接：(AT+CIPMUX=0)
AT+CIPSSLCALPN=<counts>[,<"alpn">][,<"alpn">][,<"alpn">]

// 多连接：(AT+CIPMUX=1)
AT+CIPSSLCALPN=<link ID>,<counts>[,<"alpn">][,<"alpn">[,<"alpn">]

响应：

OK

参数¶

<link ID>：网络连接 ID (0 ~ max)，在单连接的情况下，本参数值为 0；在多连接的情况下，若参数值设为 max，则表示所有连接；本参数默认值为 5。
<counts>：ALPN 的数量。范围：[0,5]。

0: 清除 ALPN 配置。

[1,5]: 设置 ALPN 配置。

<”alpn”>：字符串参数，表示 ClientHello 中的 ALPN。ALPN 最大长度受限于命令的最大长度。

说明¶

如果想要本配置立即生效，请在建立 SSL 连接前运行本命令。

AT+CIPSSLCPSK：查询/设置 SSL 客户端的 PSK¶

查询命令¶

功能：

查询 ESP 作为 SSL 客户端时每个连接的 PSK 配置

命令：

AT+CIPSSLCPSK?

响应：

+CIPSSLCPSK:<link ID>,<"psk">,<"hint">
OK

设置命令¶

命令：

// 单连接：(AT+CIPMUX=0)
AT+CIPSSLCPSK=<"psk">,<"hint">

// 多连接：(AT+CIPMUX=1)
AT+CIPSSLCPSK=<link ID>,<"psk">,<"hint">

响应：

OK

参数¶

<link ID>：网络连接 ID (0 ~ max)，在单连接的情况下，本参数值为 0；在多连接的情况下，若参数值设为 max，则表示所有连接；本参数默认值为 5。
<”psk”>：PSK identity，最大长度：32。
<”hint”>：PSK hint，最大长度：32。

说明¶

如果想要本配置立即生效，请在建立 SSL 连接前运行本命令。

AT+CIPRECONNINTV：查询/设置 Wi-Fi 透传模式下的 TCP/UDP/SSL 重连间隔¶

查询命令¶

功能：

查询 Wi-Fi 透传模式下的自动重连间隔

命令：

AT+CIPRECONNINTV?

响应：

+CIPRECONNINTV:<interval>
OK

设置命令¶

功能：

设置 Wi-Fi 透传模式下 TCP/UDP/SSL 传输断开后自动重连的间隔

命令：

AT+CIPRECONNINTV=<interval>

响应：

OK

参数¶

<interval>：自动重连间隔时间，单位：100 毫秒，默认值：1，范围：[1,36000]。

说明¶

若 AT+SYSSTORE=1 时，配置更改将保存在 NVS 区。

示例¶

AT+CIPRECONNINTV=10

AT+CIPRECVMODE：查询/设置 socket 接收模式¶

查询命令¶

功能：

查询 socket 接收模式

命令：

AT+CIPRECVMODE?

响应：

+CIPRECVMODE:<mode>
OK

设置命令¶

命令：

AT+CIPRECVMODE=<mode>

响应：

OK

参数¶

<mode>：socket 数据接收模式，默认值：0。
- 0: 主动模式，ESP-AT 将所有接收到的 socket 数据立即发送给主机 MCU，头为 “+IPD”。
- 1: 被动模式，ESP-AT 将所有接收到的 socket 数据保存到内部缓存区 (socket 接收窗口，默认值为 5760 字节），等待 MCU 读取。对于 TCP 和 SSL 连接，如果缓存区满了，将阻止 socket 传输；对于 UDP 传输，如果缓存区满了，则会发生数据丢失。

说明¶

该配置不能用于 Wi-Fi 透传模式。
当 ESP-AT 在被动模式下收到 socket 数据时，会根据情况的不同提示不同的信息：
- 多连接时 (AT+CIPMUX=1)，提示 +IPD,<link ID>,<len>；
- 单连接时 (AT+CIPMUX=0)，提示 +IPD,<len>。
<len> 表示缓存区中 socket 数据的总长度。
一旦有 +IPD 报出，应该运行 AT+CIPRECVDATA 来读取数据。否则，在前一个 +IPD 被读取之前，下一个 +IPD 将不会被报告给主机 MCU。
在断开连接的情况下，缓冲的 socket 数据仍然存在，MCU 仍然可以读取，直到发送 AT+CIPCLOSE （AT 作为客户端）或 AT+CIPSERVER=0,1 （AT 作为服务器）。换句话说，如果 +IPD 已经被报告，那么在你发送 AT+CIPCLOSE 或发送 AT+CIPSERVER=0,1 或通过 AT+CIPRECVDATA 命令读取所有数据之前，这个连接的 CLOSED 信息永远不会出现。

示例¶

AT+CIPRECVMODE=1

AT+CIPRECVDATA：获取被动接收模式下的 socket 数据¶

设置命令¶

命令：

// 单连接：(AT+CIPMUX=0)
AT+CIPRECVDATA=<len>

// 多连接：(AT+CIPMUX=1)
AT+CIPRECVDATA=<link_id>,<len>

响应：

+CIPRECVDATA:<actual_len>,<data>
OK

或

+CIPRECVDATA:<actual_len>,<remote IP>,<remote port>,<data>
OK

参数¶

<link_id>：多连接模式下的连接 ID。
<len>：最大值为：0x7fffffff，如果实际收到的数据长度比本参数值小，则返回实际长度的数据。
<actual_len>：实际获取的数据长度。
<data>：获取的数据。
[<remote IP>]：字符串参数，表示对端 IP 地址，通过 AT+CIPDINFO=1 命令使能。
[<remote port>]：对端端口，通过 AT+CIPDINFO=1 命令使能。

示例¶

AT+CIPRECVMODE=1

// 例如，如果主机 MCU 从 0 号连接中收到 100 字节的数据，
// 则会提示消息 "+IPD,0,100"，
// 然后，您可以通过运行以下命令读取这 100 字节的数据：
AT+CIPRECVDATA=0,100

AT+CIPRECVLEN：查询被动接收模式下 socket 数据的长度¶

查询命令¶

功能：

查询某一连接中缓存的所有的数据长度

命令：

AT+CIPRECVLEN?

响应：

+CIPRECVLEN:<data length of link0>,<data length of link1>,<data length of link2>,<data length of link3>,<data length of link4>
OK

参数¶

<data length of link>：某一连接中缓冲的所有的数据长度。

说明¶

SSL 连接中，ESP-AT 将返回加密数据的长度，所以返回的长度会大于真实数据的长度。

示例¶

AT+CIPRECVLEN?
+CIPRECVLEN:100,,,,,
OK

AT+PING：ping 对端主机¶

设置命令¶

功能：

ping 对端主机

命令：

AT+PING=<"host">

响应：

+PING:<time>

OK

或

+PING:TIMEOUT   // 只有在域名解析失败或 PING 超时情况下，才会有这个回复

ERROR

参数¶

<”host”>：字符串参数，表示对端主机的 IPv4 地址，IPv6 地址，或域名。
<time>：ping 的响应时间，单位：毫秒。

说明¶

如果想基于 IPv6 网络 ping 对端主机，需要先设置 AT+CIPV6=1，再通过 AT+CWJAP 获取到一个 IPv6 地址
如果远端主机是域名字符串，则 ping 将先通过 DNS 进行域名解析（优先解析 IPv4 地址），再 ping 对端主机 IP 地址

示例¶

AT+PING="192.168.1.1"
AT+PING="www.baidu.com"

// 下一代互联网国家工程中心
AT+PING="240c::6666"

AT+CIPDNS：查询/设置 DNS 服务器信息¶

查询命令¶

功能：

查询当前 DNS 服务器信息

命令：

AT+CIPDNS?

响应：

+CIPDNS:<enable>[,<"DNS IP1">][,<"DNS IP2">][,<"DNS IP3">]
OK

设置命令¶

功能：

设置 DNS 服务器信息

命令：

AT+CIPDNS=<enable>[,<"DNS IP1">][,<"DNS IP2">][,<"DNS IP3">]

响应：

OK

或

ERROR

参数¶

<enable>：设置 DNS 服务器
- 0: 启用自动获取 DNS 服务器设置，DNS 服务器将会恢复为 208.67.222.222 和 8.8.8.8，只有当 ESP station 完成了 DHCP 过程，DNS 服务器才有可能会更新。
- 1: 启用手动设置 DNS 服务器信息，如果不设置参数 <DNS IPx> 的值，则使用默认值 208.67.222.222 和 8.8.8.8。
<DNS IP1>：第一个 DNS 服务器 IP 地址，对于设置命令，只有当 <enable> 参数为 1 时，也就是启用手动 DNS 设置，本参数才有效；如果设置 <enable> 为 1，并为本参数设置一个值，当您运行查询命令时，ESP-AT 将把该参数作为当前的 DNS 设置返回。
<DNS IP2>：第二个 DNS 服务器 IP 地址，对于设置命令，只有当 <enable> 参数为 1 时，也就是启用手动 DNS 设置，本参数才有效；如果设置 <enable> 为 1，并为本参数设置一个值，当您运行查询命令时，ESP-AT 将把该参数作为当前的 DNS 设置返回。
<DNS IP3>：第三个 DNS 服务器 IP 地址，对于设置命令，只有当 <enable> 参数为 1 时，也就是启用手动 DNS 设置，本参数才有效；如果设置 <enable> 为 1，并为本参数设置一个值，当您运行查询命令时，ESP-AT 将把该参数作为当前的 DNS 设置返回。

说明¶

若 AT+SYSSTORE=1，配置更改将保存在 NVS 区。
这三个参数不能设置在同一个服务器上。
当 <enable> 为 0 时，DNS 服务器可能会根据 ESP 设备所连接的路由器的配置而改变。

示例¶

AT+CIPDNS=0
AT+CIPDNS=1,"208.67.222.222","114.114.114.114","8.8.8.8"

// 第一个基于 IPv6 的 DNS 服务器：下一代互联网国家工程中心
// 第二个基于 IPv6 的 DNS 服务器：google-public-dns-a.google.com
// 第三个基于 IPv6 的 DNS 服务器：江苏省主 DNS 服务器
AT+CIPDNS=1,"240c::6666","2001:4860:4860::8888","240e:5a::6666"

AT+CIPTCPOPT：查询/设置 socket 选项¶

查询命令¶

功能：

查询当前 socket 选项

命令：

AT+CIPTCPOPT?

响应：

+CIPTCPOPT:<link_id>,<so_linger>,<tcp_nodelay>,<so_sndtimeo>
OK

设置命令¶

命令：

// 单连接：(AT+CIPMUX=0):
AT+CIPTCPOPT=[<so_linger>],[<tcp_nodelay>],[<so_sndtimeo>]

// 多连接：(AT+CIPMUX=1):
AT+CIPTCPOPT=<link ID>,[<so_linger>],[<tcp_nodelay>],[<so_sndtimeo>]

响应：

OK

或

ERROR

参数¶

<link_id>：网络连接 ID (0 ~ max)，在多连接的情况下，若参数值设为 max，则表示所有连接；本参数默认值为 5。
<so_linger>：配置 socket 的 SO_LINGER 选项，单位：秒，默认值：-1。
- = -1: 关闭；
- = 0: 开启，linger time = 0；
- > 0: 开启，linger time = <so_linger>；
<tcp_nodelay>：配置 socket 的 TCP_NODELAY 选项，默认值：0。
- 0: 禁用 TCP_NODELAY
- 1: 启用 TCP_NODELAY
<so_sndtimeo>：配置 socket 的 SO_SNDTIMEO 选项，单位：毫秒，默认值：0。

Bluetooth® Low Energy AT 命令集¶

[English]

当前，ESP32 和 ESP32-C3 都支持 Bluetooth LE 命令。ESP32 系列和 ESP32-C3 系列 AT 固件支持蓝牙核心规范 4.2 版本。下一版本 ESP32-C3 AT 固件将支持蓝牙核心规范 5.0 版本。

AT+BLEINIT：Bluetooth LE 初始化
AT+BLEADDR：设置 Bluetooth LE 设备地址
AT+BLENAME：查询/设置 Bluetooth LE 设备名称
AT+BLESCANPARAM：查询/设置 Bluetooth LE 扫描参数
AT+BLESCAN：使能 Bluetooth LE 扫描
AT+BLESCANRSPDATA：设置 Bluetooth LE 扫描响应
AT+BLEADVPARAM：查询/设置 Bluetooth LE 广播参数
AT+BLEADVDATA：设置 Bluetooth LE 广播数据
AT+BLEADVDATAEX：自动设置 Bluetooth LE 广播数据
AT+BLEADVSTART：开始 Bluetooth LE 广播
AT+BLEADVSTOP：停止 Bluetooth LE 广播
AT+BLECONN：建立 Bluetooth LE 连接
AT+BLECONNPARAM：查询/更新 Bluetooth LE 连接参数
AT+BLEDISCONN：断开 Bluetooth LE 连接
AT+BLEDATALEN：设置 Bluetooth LE 数据包长度
AT+BLECFGMTU：设置 Bluetooth LE MTU 长度
AT+BLEGATTSSRVCRE：GATTS 创建服务
AT+BLEGATTSSRVSTART：GATTS 开启服务
AT+BLEGATTSSRVSTOP：GATTS 停止服务
AT+BLEGATTSSRV：GATTS 发现服务
AT+BLEGATTSCHAR：GATTS 发现服务特征
AT+BLEGATTSNTFY：服务器 notify 服务特征值给客户端
AT+BLEGATTSIND：服务器 indicate 服务特征值给客户端
AT+BLEGATTSSETATTR：GATTS 设置服务特征值
AT+BLEGATTCPRIMSRV：GATTC 发现基本服务
AT+BLEGATTCINCLSRV：GATTC 发现包含的服务
AT+BLEGATTCCHAR：GATTC 发现服务特征
AT+BLEGATTCRD：GATTC 读取服务特征值
AT+BLEGATTCWR：GATTC 写服务特征值
AT+BLESPPCFG：查询/设置 Bluetooth LE SPP 参数
AT+BLESPP：进入 Bluetooth LE SPP 模式
AT+BLESECPARAM：查询/设置 Bluetooth LE 加密参数
AT+BLEENC：发起 Bluetooth LE 加密请求
AT+BLEENCRSP：回复对端设备发起的配对请求
AT+BLEKEYREPLY：给对方设备回复密钥
AT+BLECONFREPLY：给对方设备回复确认结果（传统连接阶段）
AT+BLEENCDEV：查询绑定的 Bluetooth LE 加密设备列表
AT+BLEENCCLEAR：清除 Bluetooth LE 加密设备列表
AT+BLESETKEY：设置 Bluetooth LE 静态配对密钥
AT+BLEHIDINIT：Bluetooth LE HID 协议初始化
AT+BLEHIDKB：发送 Bluetooth LE HID 键盘信息
AT+BLEHIDMUS：发送 Bluetooth LE HID 鼠标信息
AT+BLEHIDCONSUMER：发送 Bluetooth LE HID consumer 信息
AT+BLUFI：开启或关闭 BluFi
AT+BLUFINAME：查询/设置 BluFi 设备名称

AT+BLEINIT：Bluetooth LE 初始化¶

查询命令¶

功能：

查询 Bluetooth LE 是否初始化

命令：

AT+BLEINIT?

响应：

若已初始化，AT 返回：

+BLEINIT:<role>
OK

若未初始化，AT 返回：

+BLEINIT:0
OK

设置命令¶

功能：

设置 Bluetooth LE 初始化角色

命令：

AT+BLEINIT=<init>

响应：

OK

参数¶

<init>:
- 0: 注销 Bluetooth LE
- 1: client 角色
- 2: server 角色

说明¶

使用 Bluetooth LE 功能时，如果您无需使用 SoftAP 模式，则建议您可以通过 AT+CWMODE 禁用 SoftAP 模式。
使用相关命令之前，请先下载 “at_customize.bin” 文件，详情请见如何自定义低功耗蓝牙服务。
使用其它 Bluetooth LE 命令之前，请先调用本命令，初始化 Bluetooth LE 角色。
Bluetooth LE 角色初始化后，不能直接切换。如需切换角色，需要先调用 AT+RST 命令重启系统，再重新初始化 Bluetooth LE 角色。
若使用 ESP 作为 Bluetooth LE server，需烧录 service bin 到 flash：
- 对于如何生成 service bin 文件，请参考 esp-at/tools/readme.md；
- service bin 文件的烧录地址，请见 esp-at/module_config/module_${platform}_default/at_customize.csv 文件中 “ble_data” 对应的地址。

示例¶

AT+BLEINIT=1

AT+BLEADDR：设置 Bluetooth LE 设备地址¶

查询命令¶

功能：

查询 Bluetooth LE 设备的公共地址

命令：

AT+BLEADDR?

响应：

+BLEADDR:<BLE_public_addr>
OK

设置命令¶

功能：

设置 Bluetooth LE 设备的地址类型

命令：

AT+BLEADDR=<addr_type>[,<random_addr>]

响应：

OK

参数¶

<addr_type>:
- 0: 公共地址 (Public Address)
- 1: 随机地址 (Random Address)

说明¶

静态地址 (Static Address) 应满足以下条件：
- 地址最高两位应为 1；
- 随机地址部分至少有 1 位为 0；
- 随机地址部分至少有 1 位为 1。

示例¶

AT+BLEADDR=1,"f8:7f:24:87:1c:7b"    // 设置随机设备地址的静态地址
AT+BLEADDR=1                        // 设置随机设备地址的私有地址
AT+BLEADDR=0                        // 设置公共设备地址

AT+BLENAME：查询/设置 Bluetooth LE 设备名称¶

查询命令¶

功能：

查询 Bluetooth LE 设备名称

命令：

AT+BLENAME?

响应：

+BLENAME:<device_name>
OK

设置命令¶

功能：

设置 Bluetooth LE 设备名称

命令：

AT+BLENAME=<device_name>

响应：

OK

参数¶

<device_name>：Bluetooth LE 设备名称，最大长度：32，默认名称为 “ESP_AT”。

说明¶

若 AT+SYSSTORE=1，配置更改将保存在 NVS 区。
通过该命令设置设备名称后，建议您执行 AT+BLEADVDATA 命令将设备名称放进广播数据当中。

示例¶

AT+BLENAME="esp_demo"

AT+BLESCANPARAM：查询/设置 Bluetooth LE 扫描参数¶

查询命令¶

功能：

查询 Bluetooth LE 扫描参数

命令：

AT+BLESCANPARAM?

响应：

+BLESCANPARAM:<scan_type>,<own_addr_type>,<filter_policy>,<scan_interval>,<scan_window>
OK

设置命令¶

功能：

设置 Bluetooth LE 扫描参数

命令：

AT+BLESCANPARAM=<scan_type>,<own_addr_type>,<filter_policy>,<scan_interval>,<scan_window>

响应：

OK

参数¶

<scan_type>：扫描类型
- 0: 被动扫描
- 1: 主动扫描
<own_addr_type>：地址类型
- 0: 公共地址
- 1: 随机地址
- 2: RPA 公共地址
- 3: RPA 随机地址
<filter_policy>：扫描过滤方式
- 0: BLE_SCAN_FILTER_ALLOW_ALL
- 1: BLE_SCAN_FILTER_ALLOW_ONLY_WLST
- 2: BLE_SCAN_FILTER_ALLOW_UND_RPA_DIR
- 3: BLE_SCAN_FILTER_ALLOW_WLIST_PRA_DIR
<scan_interval>：扫描间隔。本参数值应大于等于 <scan_window> 参数值。参数范围：[0x0004,0x4000]。扫描间隔是该参数乘以 0.625 毫秒，所以实际的扫描间隔范围为 [2.5,10240] 毫秒。
<scan_window>：扫描窗口。本参数值应小于等于 <scan_interval> 参数值。参数范围：[0x0004,0x4000]。扫描窗口是该参数乘以 0.625 毫秒，所以实际的扫描窗口范围为 [2.5,10240] 毫秒。

示例¶

AT+BLEINIT=1   // 角色：客户端
AT+BLESCANPARAM=0,0,0,100,50

AT+BLESCAN：使能 Bluetooth LE 扫描¶

设置命令¶

功能：

开始/停止 Bluetooth LE 扫描

命令：

AT+BLESCAN=<enable>[,<interval>][,<filter_type>,<filter_param>]

响应：

+BLESCAN:<addr>,<rssi>,<adv_data>,<scan_rsp_data>,<addr_type>
OK

参数¶

<enable>：
- 1: 开始持续扫描
- 0: 停止持续扫描
[<interval>]：扫描持续时间，单位：秒。
- 若设置停止扫描，无需设置本参数；
- 若设置开始扫描，需设置本参数：
- 本参数设为 0 时，则表示开始持续扫描；
- 本参数设为非 0 值时，例如 AT+BLESCAN=1,3，则表示扫描 3 秒后自动结束扫描，然后返回扫描结果。
[<filter_type>]：过滤选项
- 1: “MAC”
- 2: “NAME”
<filter_param>：过滤参数，表示对方设备 MAC 地址或名称
<addr>：Bluetooth LE 地址
<rssi>：信号强度
<adv_data>：广播数据
<scan_rsp_data>：扫描响应数据
<addr_type>：广播设备地址类型

说明¶

响应中的 OK 和 +BLESCAN:<addr>,<rssi>,<adv_data>,<scan_rsp_data>,<addr_type> 在输出顺序上没有严格意义上的先后顺序。OK 可能在 +BLESCAN:<addr>,<rssi>,<adv_data>,<scan_rsp_data>,<addr_type> 之前输出，也有可能在 +BLESCAN:<addr>,<rssi>,<adv_data>,<scan_rsp_data>,<addr_type> 之后输出。

示例¶

AT+BLEINIT=1    // 角色：客户端
AT+BLESCAN=1    // 开始扫描
AT+BLESCAN=0    // 停止扫描
AT+BLESCAN=1,3,1,"24:0A:C4:96:E6:88"  // 开始扫描，过滤类型为 MAC 地址
AT+BLESCAN=1,3,2,"ESP-AT"  // 开始扫描，过滤类型为设备名称

AT+BLESCANRSPDATA：设置 Bluetooth LE 扫描响应¶

设置命令¶

功能：

设置 Bluetooth LE 扫描响应

命令：

AT+BLESCANRSPDATA=<scan_rsp_data>

响应：

OK

参数¶

<scan_rsp_data>：扫描响应数据，为 HEX 字符串。例如，若想设置扫描响应数据为 “0x11 0x22 0x33 0x44 0x55”，则命令为 AT+BLESCANRSPDATA="1122334455"。

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLESCANRSPDATA="1122334455"

AT+BLEADVPARAM：查询/设置 Bluetooth LE 广播参数¶

查询命令¶

功能：

查询广播参数

命令：

AT+BLEADVPARAM?

响应：

+BLEADVPARAM:<adv_int_min>,<adv_int_max>,<adv_type>,<own_addr_type>,<channel_map>,<adv_filter_policy>,<peer_addr_type>,<peer_addr>
OK

设置命令¶

功能：

设置广播参数

命令：

AT+BLEADVPARAM=<adv_int_min>,<adv_int_max>,<adv_type>,<own_addr_type>,<channel_map>[,<adv_filter_policy>][,<peer_addr_type>][,<peer_addr>]

响应：

OK

参数¶

<adv_int_min>：最小广播间隔。参数范围：[0x0020,0x4000]。广播间隔等于该参数乘以 0.625 毫秒，所以实际的最小广播间隔范围为 [20,10240] 毫秒。本参数值应小于等于 <adv_int_max> 参数值。
<adv_int_max>：最大广播间隔。参数范围：[0x0020,0x4000]。广播间隔等于该参数乘以 0.625 毫秒，所以实际的最大广播间隔范围为 [20,10240] 毫秒。本参数值应大于等于 <adv_int_min> 参数值。
<adv_type>:
- 0: ADV_TYPE_IND
- 1: ADV_TYPE_DIRECT_IND_HIGH
- 2: ADV_TYPE_SCAN_IND
- 3: ADV_TYPE_NONCONN_IND
- 4: ADV_TYPE_DIRECT_IND_LOW
<own_addr_type>：Bluetooth LE 地址类型
- 0: BLE_ADDR_TYPE_PUBLIC
- 1: BLE_ADDR_TYPE_RANDOM
<channel_map>：广播信道
- 1: ADV_CHNL_37
- 2: ADV_CHNL_38
- 4: ADV_CHNL_39
- 7: ADV_CHNL_ALL
[<adv_filter_policy>]：广播过滤器规则
- 0: ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY
- 1: ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY
- 2: ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST
- 3: ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST
[<peer_addr_type>]：对方 Bluetooth LE 地址类型
- 0: PUBLIC
- 1: RANDOM
[<peer_addr>]：对方 Bluetooth LE 地址

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLEADVPARAM=50,50,0,0,4,0,0,"12:34:45:78:66:88"

AT+BLEADVDATA：设置 Bluetooth LE 广播数据¶

设置命令¶

功能：

设置广播数据

命令：

AT+BLEADVDATA=<adv_data>

响应：

OK

参数¶

<adv_data>：广播数据，为 HEX 字符串。例如，若想设置广播数据为 “0x11 0x22 0x33 0x44 0x55”，则命令为 AT+BLEADVDATA="1122334455"。

说明¶

如果之前已经使用命令 AT+BLEADVDATAEX=<dev_name>,<uuid>,<manufacturer_data>,<include_power> 设置了广播数据，则会被本命令设置的广播数据覆盖。
如果您想使用本命令修改设备名称，则建议在执行完该命令之后执行 AT+BLENAME 命令将设备名称设置为同样的名称。

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLEADVDATA="1122334455"

AT+BLEADVDATAEX：自动设置 Bluetooth LE 广播数据¶

查询命令¶

功能：

查询广播数据的参数

命令：

AT+BLEADVDATAEX?

响应：

+BLEADVDATAEX:<dev_name>,<uuid>,<manufacturer_data>,<include_power>

OK

设置命令¶

功能：

设置广播数据并开始广播

命令：

AT+BLEADVDATAEX=<dev_name>,<uuid>,<manufacturer_data>,<include_power>

响应：

OK

参数¶

<dev_name>：字符串参数，表示设备名称。例如，若想设置设备名称为 “just-test”，则命令为 AT+BLEADVSTARTEX="just-test",<uuid>,<manufacturer_data>,<include_power>。
<uuid>：字符串参数。例如，若想设置 UUID 为 “0xA002”，则命令为 AT+BLEADVSTARTEX=<dev_name>,"A002",<manufacturer_data>,<include_power>。
<manufacturer_data>：制造商数据，为 HEX 字符串。例如，若想设置制造商数据为 “0x11 0x22 0x33 0x44 0x55”，则命令为 AT+BLEADVSTARTEX=<dev_name>,<uuid>,"1122334455",<include_power>。
<include_power>：若广播数据需包含 TX 功率，本参数应该设为 1；否则，为 0。

说明¶

如果之前已经使用命令 AT+BLEADVDATA=<adv_data> 设置了广播数据，则会被本命令设置的广播数据覆盖。

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLEADVDATAEX="ESP-AT","A002","0102030405",1

AT+BLEADVSTART：开始 Bluetooth LE 广播¶

执行命令¶

功能：

开始广播

命令：

AT+BLEADVSTART

响应：

OK

说明¶

若未使用命令 AT+BLEADVPARAM=<adv_parameter> 设置广播参数，则使用默认广播参数。
若未使用命令 AT+BLEADVDATA=<adv_data> 设置广播数据，则发送全 0 数据包。
若之前已经使用命令 AT+BLEADVDATA=<adv_data> 设置过广播数据，则会被 AT+BLEADVDATAEX=<dev_name>,<uuid>,<manufacturer_data>,<include_power> 设置的广播数据覆盖，相反，如果先使用 AT+BLEADVDATAEX，则会被 AT+BLEADVDATA 设置的广播数据覆盖。

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLEADVSTART

AT+BLEADVSTOP：停止 Bluetooth LE 广播¶

执行命令¶

功能：

停止广播

命令：

AT+BLEADVSTOP

响应：

OK

说明¶

若开始广播后，成功建立 Bluetooth LE 连接，则会自动结束 Bluetooth LE 广播，无需调用本命令。

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLEADVSTART
AT+BLEADVSTOP

AT+BLECONN：建立 Bluetooth LE 连接¶

查询命令¶

功能：

查询 Bluetooth LE 连接

命令：

AT+BLECONN?

响应：

+BLECONN:<conn_index>,<remote_address>
OK

若未建立连接，则响应不显示 <conn_index> 和 <remote_address> 参数。

设置命令¶

功能：

建立 Bluetooth LE 连接

命令：

AT+BLECONN=<conn_index>,<remote_address>[,<addr_type>,<timeout>]

响应：

若建立连接成功，则提示：

+BLECONN:<conn_index>,<remote_address>

OK

若建立连接失败，则提示：

+BLECONN:<conn_index>,-1

ERROR

若是因为参数错误或者其它的一些原因导致连接失败，则提示：

ERROR

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<remote_address>：对方 Bluetooth LE 设备地址。
[<addr_type>]：广播设备地址类型。
[<timeout>]：连接超时时间，单位：秒。范围：[3,30]。

说明¶

建议在建立新连接之前，先运行 AT+BLESCAN 命令扫描设备，确保目标设备处于广播状态。
最大连接超时为 30 秒。
如果 Bluetooth LE server 已初始化且连接已成功建立，则可以使用此命令在对等设备 (GATTC) 中发现服务。还可以使用以下 GATTC 命令：
如果 AT+BLECONN? 在 Bluetooth LE 未初始的情况下执行 (AT+BLEINIT=0)，则系统不会输出 +BLECONN:<conn_index>,<remote_address> 。

示例¶

AT+BLEINIT=1   // 角色：客户端
AT+BLECONN=0,"24:0a:c4:09:34:23",0,10

AT+BLECONNPARAM：查询/更新 Bluetooth LE 连接参数¶

查询命令¶

功能：

查询 Bluetooth LE 连接参数

命令：

AT+BLECONNPARAM?

响应：

+BLECONNPARAM:<conn_index>,<min_interval>,<max_interval>,<cur_interval>,<latency>,<timeout>
OK

设置命令¶

功能：

更新 Bluetooth LE 连接参数

命令：

AT+BLECONNPARAM=<conn_index>,<min_interval>,<max_interval>,<latency>,<timeout>

响应：

OK

若设置失败，则提示以下信息：

+BLECONNPARAM: <conn_index>,-1

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<min_interval>：最小连接间隔。本参数值应小于等于 <max_interval> 参数值。参数范围：[0x0006,0x0C80]。连接间隔等于该参数乘以 1.25 毫秒，所以实际的最小连接间隔范围为 [7.5,4000] 毫秒。
<max_interval>：最大连接间隔。本参数值应大于等于 <min_interval> 参数值。参数范围：[0x0006,0x0C80]。连接间隔等于该参数乘以 1.25 毫秒，所以实际的最大连接间隔范围为 [7.5,4000] 毫秒。
<cur_interval>：当前连接间隔。
<latency>：延迟。参数范围：[0x0000,0x01F3]。
<timeout>：超时。参数范围：[0x000A,0x0C80]。超时等于该参数乘以 10 毫秒，所以实际的超时范围为 [100,32000] 毫秒。

说明¶

本命令要求先建立连接，并且仅支持 client 角色更新连接参数。

示例¶

AT+BLEINIT=1   // 角色：客户端
AT+BLECONN=0,"24:0a:c4:09:34:23"
AT+BLECONNPARAM=0,12,14,1,500

AT+BLEDISCONN：断开 Bluetooth LE 连接¶

执行命令¶

功能：

断开 Bluetooth LE 连接

命令：

AT+BLEDISCONN=<conn_index>

响应：

OK  // 收到 AT+BLEDISCONN 命令
+BLEDISCONN:<conn_index>,<remote_address>  // 运行命令成功

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<remote_address>：对方 Bluetooth LE 设备地址。

说明¶

仅支持客户端运行本命令断开连接。

示例¶

AT+BLEINIT=1   // 角色：客户端
AT+BLECONN=0,"24:0a:c4:09:34:23"
AT+BLEDISCONN=0

AT+BLEDATALEN：设置 Bluetooth LE 数据包长度¶

设置命令¶

功能：

设置 Bluetooth LE 数据包长度

命令：

AT+BLEDATALEN=<conn_index>,<pkt_data_len>

响应：

OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<pkt_data_len>：数据包长度，范围：[0x001B,0x00FB]。

说明¶

需要先建立 Bluetooth LE 连接，才能设置数据包长度。

示例¶

AT+BLEINIT=1   // 角色：客户端
AT+BLECONN=0,"24:0a:c4:09:34:23"
AT+BLEDATALEN=0,30

AT+BLECFGMTU：设置 Bluetooth LE MTU 长度¶

查询命令¶

功能：

查询 MTU（maximum transmission unit，最大传输单元）长度

命令：

AT+BLECFGMTU?

响应：

+BLECFGMTU:<conn_index>,<mtu_size>
OK

设置命令¶

功能：

设置 MTU 的长度

命令：

AT+BLECFGMTU=<conn_index>,<mtu_size>

响应：

OK  // 收到本命令

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<mtu_size>：MTU 长度。

说明¶

本命令要求先建立 Bluetooth LE 连接。
仅支持客户端运行本命令设置 MTU 的长度。
MTU 的实际长度需要协商，响应 OK 只表示尝试协商 MTU 长度，因此设置长度不一定生效，建议调用 AT+BLECFGMTU? 查询实际 MTU 长度。

示例¶

AT+BLEINIT=1   // 角色：客户端
AT+BLECONN=0,"24:0a:c4:09:34:23"
AT+BLECFGMTU=0,300

AT+BLEGATTSSRVCRE：GATTS 创建服务¶

执行命令¶

功能：

GATTS (Generic Attributes Server) 创建 Bluetooth LE 服务

命令：

AT+BLEGATTSSRVCRE

响应：

OK

说明¶

使用 ESP 作为 Bluetooth LE server 创建服务，需烧录 service bin 文件到 flash 中。
- 如何生成 service bin 文件，请参考 esp-at/tools/readme.md。
- service bin 文件的烧录地址为 esp-at/module_config/module_${platform}_default/at_customize.csv 文件中的 “ble_data” 地址。
Bluetooth LE server 初始化后，请及时调用本命令创建服务；如果先建立 Bluetooth LE 连接，则无法创建服务。
如果 Bluetooth LE client 已初始化成功，可以使用此命令创建服务；也可以使用其他一些相应的 GATTS 命令，例如启动和停止服务、设置服务特征值和 notification/indication，具体命令如下：
- AT+BLEGATTSSRVCRE (建议在 Bluetooth LE 连接建立之前使用)
- AT+BLEGATTSSRVSTART (建议在 Bluetooth LE 连接建立之前使用)
- AT+BLEGATTSSRV
- AT+BLEGATTSCHAR
- AT+BLEGATTSNTFY
- AT+BLEGATTSIND
- AT+BLEGATTSSETATTR

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLEGATTSSRVCRE

AT+BLEGATTSSRVSTART：GATTS 开启服务¶

执行命令¶

功能：

GATTS 开启全部服务

命令：

AT+BLEGATTSSRVSTART

设置命令¶

功能：

GATTS 开启某指定服务

命令：

AT+BLEGATTSSRVSTART=<srv_index>

响应：

OK

参数¶

<srv_index>：服务序号，从 1 开始递增。

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART

AT+BLEGATTSSRVSTOP：GATTS 停止服务¶

执行命令¶

功能：

GATTS 停止全部服务

命令：

AT+BLEGATTSSRVSTOP

设置命令¶

功能：

GATTS 停止某指定服务

命令：

AT+BLEGATTSSRVSTOP=<srv_index>

响应：

OK

参数¶

<srv_index>：服务序号，从 1 开始递增。

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART
AT+BLEGATTSSRVSTOP

AT+BLEGATTSSRV：GATTS 发现服务¶

查询命令¶

功能：

GATTS 发现服务

命令：

AT+BLEGATTSSRV?

响应：

+BLEGATTSSRV:<srv_index>,<start>,<srv_uuid>,<srv_type>
OK

参数¶

<srv_index>：服务序号，从 1 开始递增。
<start>：
- 0: 服务未开始；
- 1: 服务已开始。
<srv_uuid>：服务的 UUID。
<srv_type>：服务的类型：
- 0: 次要服务；
- 1: 首要服务。

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRV?

AT+BLEGATTSCHAR：GATTS 发现服务特征¶

查询命令¶

功能：

GATTS 发现服务特征

命令：

AT+BLEGATTSCHAR?

响应：

对于服务特征信息，响应如下：

+BLEGATTSCHAR:"char",<srv_index>,<char_index>,<char_uuid>,<char_prop>

对于描述符信息，响应如下：

+BLEGATTSCHAR:"desc",<srv_index>,<char_index>,<desc_index>
OK

参数¶

<srv_index>：服务序号，从 1 开始递增。
<char_index>：服务特征的序号，从 1 起始递增。
<char_uuid>：服务特征的 UUID。
<char_prop>：服务特征的属性。
<desc_index>：特征描述符序号。
<desc_uuid>：特征描述符的 UUID。

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART
AT+BLEGATTSCHAR?

AT+BLEGATTSNTFY：服务器 notify 服务特征值给客户端¶

设置命令¶

功能：

服务器 notify 服务特征值给客户端

命令：

AT+BLEGATTSNTFY=<conn_index>,<srv_index>,<char_index>,<length>

响应：

符号 > 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 <length> 的值时，执行 notify 操作。

若数据传输成功，则提示：

OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<srv_index>：服务序号，可运行 AT+BLEGATTSCHAR? 查询。
<char_index>：服务特征的序号，可运行 AT+BLEGATTSCHAR? 查询。
<length>：数据长度。

示例¶

AT+BLEINIT=2      // 角色：服务器
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART
AT+BLEADVSTART    // 开始广播，当 client 连接后，必须配置接收 notify
AT+BLEGATTSCHAR?  // 查询允许 notify 客户端的特征
// 例如，使用 3 号服务的 6 号特征 notify 长度为 4 字节的数据，使用如下命令：
AT+BLEGATTSNTFY=0,3,6,4
// 提示 ">" 符号后，输入 4 字节的数据，如 "1234"，然后数据自动传输

AT+BLEGATTSIND：服务器 indicate 服务特征值给客户端¶

设置命令¶

功能：

服务器 indicate 服务特征值给客户端

命令：

AT+BLEGATTSIND=<conn_index>,<srv_index>,<char_index>,<length>

响应：

符号 > 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 <length> 的值时，执行 indicate 操作。

若数据传输成功，则提示：

OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<srv_index>：服务序号，可运行 AT+BLEGATTSCHAR? 查询。
<char_index>：服务特征的序号，可运行 AT+BLEGATTSCHAR? 查询。
<length>：数据长度。

示例¶

AT+BLEINIT=2      // 角色：服务器
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART
AT+BLEADVSTART    // 开始广播，当 client 连接后，必须配置接收 indication
AT+BLEGATTSCHAR?  // 查询客户端可以接收 indication 的特征
// 例如，使用 3 号服务的 7 号特征 indicate 长度为 4 字节的数据，命令如下：
AT+BLEGATTSIND=0,3,7,4
// 提示 ">" 符号后，输入 4 字节的数据，如 "1234"，然后数据自动传输

AT+BLEGATTSSETATTR：GATTS 设置服务特征值¶

设置命令¶

功能：

GATTS 设置服务特征值或描述符值

命令：

AT+BLEGATTSSETATTR=<srv_index>,<char_index>,[<desc_index>],<length>

响应：

符号 > 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 <length> 的值时，执行设置操作。

若数据传输成功，则提示：

OK

参数¶

<srv_index>：服务序号，可运行 AT+BLEGATTSCHAR? 查询。
<char_index>：服务特征的序号，可运行 AT+BLEGATTSCHAR? 查询。
[<desc_index>]：特征描述符序号：
- 若填写，则设置描述符的值；
- 若未填写，则设置特征值。
<length>：数据长度。

说明¶

如果 <length> 参数值大于支持的最大长度，则设置会失败。关于 service table，请见 components/customized_partitions/raw_data/ble_data。

示例¶

AT+BLEINIT=2   // 角色：服务器
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART
AT+BLEGATTSCHAR?
// 例如，向 1 号服务的 1 号特征写入长度为 1 字节的数据，命令如下：
AT+BLEGATTSSETATTR=1,1,,1
// 提示 ">" 符号后，输入 1 字节的数据即可，例如 "8"，然后设置开始

AT+BLEGATTCPRIMSRV：GATTC 发现基本服务¶

查询命令¶

功能：

GATTC (Generic Attributes Client) 发现基本服务

命令：

AT+BLEGATTCPRIMSRV=<conn_index>

响应：

+BLEGATTCPRIMSRV:<conn_index>,<srv_index>,<srv_uuid>,<srv_type>
OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<srv_index>：服务序号，从 1 开始递增。
<srv_uuid>：服务的 UUID。
<srv_type>：服务的类型：
- 0: 次要服务；
- 1: 首要服务。

说明¶

使用本命令，需要先建立 Bluetooth LE 连接。

示例¶

AT+BLEINIT=1   // 角色：客户端
AT+BLECONN=0,"24:12:5f:9d:91:98"
AT+BLEGATTCPRIMSRV=0

AT+BLEGATTCINCLSRV：GATTC 发现包含的服务¶

设置命令¶

功能：

GATTC 发现包含服务

命令：

AT+BLEGATTCINCLSRV=<conn_index>,<srv_index>

响应：

+BLEGATTCINCLSRV:<conn_index>,<srv_index>,<srv_uuid>,<srv_type>,<included_srv_uuid>,<included_srv_type>
OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<srv_index>：服务序号，可运行 AT+BLEGATTCPRIMSRV=<conn_index> 查询。
<srv_uuid>：服务的 UUID。
<srv_type>：服务的类型：
- 0: 次要服务；
- 1: 首要服务。
<included_srv_uuid>：包含服务的 UUID。
<included_srv_type>：包含服务的类型：
- 0: 次要服务；
- 1: 首要服务。

说明¶

使用本命令，需要先建立 Bluetooth LE 连接。

示例¶

AT+BLEINIT=1   // 角色：客户端
AT+BLECONN=0,"24:12:5f:9d:91:98"
AT+BLEGATTCPRIMSRV=0
AT+BLEGATTCINCLSRV=0,1  // 根据前一条命令的查询结果，指定 index 查询

AT+BLEGATTCCHAR：GATTC 发现服务特征¶

设置命令¶

功能：

GATTC 发现服务特征

命令：

AT+BLEGATTCCHAR=<conn_index>,<srv_index>

响应：

对于服务特征信息，响应如下：

+BLEGATTCCHAR:"char",<conn_index>,<srv_index>,<char_index>,<char_uuid>,<char_prop>

对于描述符信息，响应如下：

+BLEGATTCCHAR:"desc",<conn_index>,<srv_index>,<char_index>,<desc_index>,<desc_uuid>
OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<srv_index>：服务序号，可运行 AT+BLEGATTCPRIMSRV=<conn_index> 查询。
<char_index>：服务特征的序号，从 1 开始递增。
<char_uuid>：服务特征的 UUID。
<char_prop>：服务特征的属性。
<desc_index>：特征描述符序号。
<desc_uuid>：特征描述符的 UUID。

说明¶

使用本命令，需要先建立 Bluetooth LE 连接。

示例¶

AT+BLEINIT=1   // 角色：客户端
AT+BLECONN=0,"24:12:5f:9d:91:98"
AT+BLEGATTCPRIMSRV=0
AT+BLEGATTCCHAR=0,1 // 根据前一条命令的查询结果，指定 index 查询

AT+BLEGATTCRD：GATTC 读取服务特征值¶

设置命令¶

功能：

GATTC 读取服务特征值或描述符值

命令：

AT+BLEGATTCRD=<conn_index>,<srv_index>,<char_index>[,<desc_index>]

响应：

+BLEGATTCRD:<conn_index>,<len>,<value>
OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<srv_index>：服务序号，可运行 AT+BLEGATTCPRIMSRV=<conn_index> 查询。
<char_index>：服务特征序号，可运行 AT+BLEGATTCCHAR=<conn_index>,<srv_index> 查询。
[<desc_index>]：特征描述符序号：
- 若设置，读取目标描述符的值；
- 若未设置，读取目标特征的值。
<len>：数据长度。
<value>：<char_value> 或者 <desc_value>。

<char_value>：服务特征值，字符串格式，运行 AT+BLEGATTCRD=<conn_index>,<srv_index>,<char_index> 读取。例如，若响应为 +BLEGATTCRD:0,1,0，则表示数据长度为 1，内容为 “0”。

<desc_value>：服务特征描述符的值，字符串格式，运行 AT+BLEGATTCRD=<conn_index>,<srv_index>,<char_index>,<desc_index> 读取。例如，若响应为 +BLEGATTCRD:0,4,0123，则表示数据长度为 4，内容为 “0123”。

说明¶

使用本命令，需要先建立 Bluetooth LE 连接。
若目标服务特征不支持读操作，则返回 “ERROR”。

示例¶

AT+BLEINIT=1   // 角色：客户端
AT+BLECONN=0,"24:12:5f:9d:91:98"
AT+BLEGATTCPRIMSRV=0
AT+BLEGATTCCHAR=0,3 // 根据前一条命令的查询结果，指定 index 查询
// 例如，读取第 3 号服务的第 2 号特征的第 1 号描述符信息，命令如下：
AT+BLEGATTCRD=0,3,2,1

AT+BLEGATTCWR：GATTC 写服务特征值¶

设置命令¶

功能：

GATTC 写服务特征值或描述符值

命令：

AT+BLEGATTCWR=<conn_index>,<srv_index>,<char_index>[,<desc_index>],<length>

Response:

符号 > 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 <length> 的值时，执行写入操作。

若数据传输成功，则提示：

OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<srv_index>：服务序号，可运行 AT+BLEGATTCPRIMSRV=<conn_index> 查询。
<char_index>：服务特征序号，可运行 AT+BLEGATTCCHAR=<conn_index>,<srv_index> 查询。
[<desc_index>]：特征描述符序号：
- 若设置，则写目标描述符的值；
- 若未设置，则写目标特征的值。
<length>：数据长度。

说明¶

使用本命令，需要先建立 Bluetooth LE 连接。
若目标服务特征不支持写操作，则返回 “ERROR”。

示例¶

AT+BLEINIT=1   // 角色：客户端
AT+BLECONN=0,"24:12:5f:9d:91:98"
AT+BLEGATTCPRIMSRV=0
AT+BLEGATTCCHAR=0,3 // 根据前一条命令的查询结果，指定 index 查询
// 例如，向第 3 号服务的第 4 号特征，写入长度为 6 字节的数据，命令如下：
AT+BLEGATTCWR=0,3,4,,6
// 提示 ">" 符号后，输入 6 字节的数据即可，如 "123456"，然后开始写入

AT+BLESPPCFG：查询/设置 Bluetooth LE SPP 参数¶

查询命令¶

功能：

查询 Bluetooth LE SPP (Serial Port Profile) 参数

命令：

AT+BLESPPCFG?

响应：

+BLESPPCFG:<tx_service_index>,<tx_char_index>,<rx_service_index>,<rx_char_index>,<auto_conn>
OK

设置命令¶

功能：

设置或重置 Bluetooth LE SPP 参数

命令：

AT+BLESPPCFG=<cfg_enable>[,<tx_service_index>,<tx_char_index>,<rx_service_index>,<rx_char_index>][,<auto_conn>]

响应：

OK

参数¶

<cfg_enable>：
- 0: 重置所有 SPP 参数，后面参数无需填写；
- 1: 后面参数需要填写。
<tx_service_index>：tx 服务序号，可运行 AT+BLEGATTCPRIMSRV=<conn_index> 和 AT+BLEGATTSSRV? 查询。
<tx_char_index>：tx 服务特征序号，可运行 AT+BLEGATTCCHAR=<conn_index>,<srv_index> 和 AT+BLEGATTSCHAR? 查询。
<rx_service_index>：rx 服务序号，可运行 AT+BLEGATTCPRIMSRV=<conn_index> 和 AT+BLEGATTSSRV? 查询。
<rx_char_index>：rx 服务特征序号，可运行 AT+BLEGATTCCHAR=<conn_index>,<srv_index> 和 AT+BLEGATTSCHAR? 查询。
<auto_conn>: 自动重连标志位，默认情况下，自动重连功能被使能。
- 0: 禁止 Bluetooth LE 透传自动重连功能。
- 1: 使能 Bluetooth LE 透传自动重连功能。

说明¶

对于 Bluetooth LE 客户端，tx 服务特征属性必须是 write with response 或 write without response，rx 服务特征属性必须是 indicate 或 notify。
对于 Bluetooth LE 服务器，tx 服务特征属性必须是 indicate 或 notify，rx 服务特征属性必须是 write with response 或 write without response。
禁用了自动重连功能后，如果连接断开，会提示有断开连接信息提示(依赖于 AT+SYSMSG)，需要重新发送连接的命令；使能的情况下，连接断开后，会自动重连， MCU 侧将感知不到连接的断开，如果对端的 MAC 发生了改变，则无法连接成功。

示例¶

AT+BLESPPCFG=0          // 重置 Bluetooth LE SPP 参数
AT+BLESPPCFG=1,3,5,3,7  // 设置 Bluetooth LE SPP 参数
AT+BLESPPCFG?           // 查询 Bluetooth LE SPP 参数

AT+BLESPP：进入 Bluetooth LE SPP 模式¶

执行命令¶

功能：

进入 Bluetooth LE SPP 模式

命令：

AT+BLESPP

响应：

OK

>

上述响应表示 AT 已经进入 Bluetooth LE SPP 模式，可以进行数据的发送和接收。

若 Bluetooth LE SPP 状态错误 ( 对端在 Bluetooth LE 连接建立后未使能 Notifications )，则返回：

ERROR

说明¶

在 SPP 传输中，若未设置 AT+SYSMSG Bit0 为 1，则 AT 不会提示任何退出 SPP 透传模式的信息。
在 SPP 传输中，若未设置 AT+SYSMSG Bit2 为 1，则 AT 不会提示任何连接状态变更的信息。
当系统收到只含有 +++ 的包时，设备返回到普通命令模式，请至少等待一秒再发送下一个 AT 命令。

示例¶

AT+BLESPP   // 进入 Bluetooth LE SPP 模式

AT+BLESECPARAM：查询/设置 Bluetooth LE 加密参数¶

查询命令¶

功能：

查询 Bluetooth LE SMP 加密参数

命令：

AT+BLESECPARAM?

响应：

+BLESECPARAM:<auth_req>,<iocap>,<enc_key_size>,<init_key>,<rsp_key>,<auth_option>
OK

设置命令¶

功能：

设置 Bluetooth LE SMP 加密参数

命令：

AT+BLESECPARAM=<auth_req>,<iocap>,<enc_key_size>,<init_key>,<rsp_key>[,<auth_option>]

响应：

OK

参数¶

<auth_req>：认证请求。
- 0: NO_BOND
- 1: BOND
- 4: MITM
- 8: SC_ONLY
- 9: SC_BOND
- 12: SC_MITM
- 13: SC_MITM_BOND
<iocap>：输入输出能力。
- 0: DisplayOnly
- 1: DisplayYesNo
- 2: KeyboardOnly
- 3: NoInputNoOutput
- 4: Keyboard display
<enc_key_size>：加密密钥长度。参数范围：[7,16]。单位：字节。
<init_key>：多个比特位组成的初始密钥。
<rsp_key>：多个比特位组成的响应密钥。
<auth_option>：安全认证选项：
- 0: 自动选择安全等级；
- 1: 如果无法满足之前设定的安全等级，则会断开连接。

说明¶

<init_key> 和 <rsp_key> 参数的比特位组合模式如下：
- Bit0: 用于交换初始密钥和响应密钥的加密密钥；
- Bit1: 用于交换初始密钥和响应密钥的 IRK 密钥；
- Bit2: 用于交换初始密钥和响应密钥的 CSRK 密钥；
- Bit3: 用于交换初始密钥和响应密钥的 link 密钥（仅用于 Bluetooth LE 和 BR/EDR 共存模式）。

示例¶

AT+BLESECPARAM=1,4,16,3,3,0

AT+BLEENC：发起 Bluetooth LE 加密请求¶

设置命令¶

功能：

发起配对请求

命令：

AT+BLEENC=<conn_index>,<sec_act>

响应：

OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<sec_act>：
- 0: SEC_NONE；
- 1: SEC_ENCRYPT；
- 2: SEC_ENCRYPT_NO_MITM；
- 3: SEC_ENCRYPT_MITM。

说明¶

使用本命令前，请先设置安全参数、建立与对方设备的连接。

示例¶

AT+RESTORE
AT+BLEINIT=2
AT+BLEGATTSSRVCRE
AT+BLEGATTSSRVSTART
AT+BLEADDR?
AT+BLESECPARAM=1,0,16,3,3
AT+BLESETKEY=123456
AT+BLEADVSTART
// 使用 Bluetooth LE 调试 app 作为 client 与 ESP 设备建立 Bluetooth LE 连接
AT+BLEENC=0,3

AT+BLEENCRSP：回复对端设备发起的配对请求¶

设置命令¶

功能：

回复对端设备发起的配对请求

命令：

AT+BLEENCRSP=<conn_index>,<accept>

响应：

OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<accept>：
- 0: 拒绝；
- 1: 接受。

说明¶

使用本命令后，AT 会在配对请求流程结束后输出配对结果。

+BLEAUTHCMPL:<conn_index>,<enc_result>

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<enc_result>:
- 0: 加密配对成功；
- 1: 加密配对失败。

示例¶

AT+BLEENCRSP=0,1

AT+BLEKEYREPLY：给对方设备回复密钥¶

设置命令¶

功能：

回复配对密钥

命令：

AT+BLEKEYREPLY=<conn_index>,<key>

响应：

OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<key>：配对密钥。

示例¶

AT+BLEKEYREPLY=0,649784

AT+BLECONFREPLY：给对方设备回复确认结果（传统连接阶段）¶

设置命令¶

功能：

回复配对结果

命令：

AT+BLECONFREPLY=<conn_index>,<confirm>

响应：

OK

参数¶

<conn_index>：Bluetooth LE 连接号，范围：[0,2]。
<confirm>：
- 0: 否
- 1: 是

示例¶

AT+BLECONFREPLY=0,1

AT+BLEENCDEV：查询绑定的 Bluetooth LE 加密设备列表¶

查询命令¶

功能：

查询绑定的 Bluetooth LE 加密设备列表

命令：

AT+BLEENCDEV?

响应：

+BLEENCDEV:<enc_dev_index>,<mac_address>
OK

参数¶

<enc_dev_index>：已绑定设备的连接号。该参数不一定等于命令 AT+BLECONN 查询出的 Bluetooth LE 连接列表中的 conn_index 参数。范围：[0,14]。
<mac_address>：MAC 地址。

说明¶

ESP-AT 最多允许绑定 15 个设备。如果绑定的设备数量超过 15 个，那么新绑定的设备信息会根据绑定顺序从 0 到 14 号依次覆盖之前的设备信息。

示例¶

AT+BLEENCDEV?

AT+BLEENCCLEAR：清除 Bluetooth LE 加密设备列表¶

设置命令¶

功能：

从安全数据库列表中删除某一连接号的设备

命令：

AT+BLEENCCLEAR=<enc_dev_index>

响应：

OK

执行命令¶

功能：

删除安全数据库所有设备

命令：

AT+BLEENCCLEAR

响应：

OK

参数¶

<enc_dev_index>：已绑定设备的连接号。

示例¶

AT+BLEENCCLEAR

AT+BLESETKEY：设置 Bluetooth LE 静态配对密钥¶

查询命令¶

功能：

查询 Bluetooth LE 静态配对密钥，若未设置，则 AT 返回 -1

命令：

AT+BLESETKEY?

响应：

+BLESETKEY:<static_key>
OK

设置命令¶

功能：

为所有 Bluetooth LE 连接设置一个 Bluetooth LE 静态配对密钥

命令：

AT+BLESETKEY=<static_key>

响应：

OK

参数¶

<static_key>：Bluetooth LE 静态配对密钥。

示例¶

AT+BLESETKEY=123456

AT+BLEHIDINIT：Bluetooth LE HID 协议初始化¶

查询命令¶

功能：

查询 Bluetooth LE HID 协议初始化情况

命令：

AT+BLEHIDINIT?

响应：

若未初始化，则 AT 返回：

+BLEHIDINIT:0
OK

若已初始化，则 AT 返回：

+BLEHIDINIT:1
OK

设置命令¶

功能：

初始化 Bluetooth LE HID 协议

命令：

AT+BLEHIDINIT=<init>

响应：

OK

参数¶

<init>：
- 0: 取消 Bluetooth LE HID 协议的初始化；
- 1: 初始化 Bluetooth LE HID 协议。

说明¶

Bluetooth LE HID 无法与通用 GATT/GAP 命令同时使用。

示例¶

AT+BLEHIDINIT=1

AT+BLEHIDKB：发送 Bluetooth LE HID 键盘信息¶

设置命令¶

功能：

发送键盘信息

命令：

AT+BLEHIDKB=<Modifier_keys>,<key_1>,<key_2>,<key_3>,<key_4>,<key_5>,<key_6>

响应：

OK

参数¶

<Modifier_keys>：组合键。
<key_1>：键代码 1。
<key_2>：键代码 2。
<key_3>：键代码 3。
<key_4>：键代码 4。
<key_5>：键代码 5。
<key_6>：键代码 6。

说明¶

更多键代码的信息，请参考 Universal Serial Bus HID Usage Tables 的 Keyboard/Keypad Page 章节。
要使此命令与 iOS 产品交互，您的设备需要先通过 MFI 认证。

示例¶

AT+BLEHIDKB=0,4,0,0,0,0,0   // 输入字符串 "a"

AT+BLEHIDMUS：发送 Bluetooth LE HID 鼠标信息¶

设置命令¶

功能：

发送鼠标信息

命令：

AT+BLEHIDMUS=<buttons>,<X_displacement>,<Y_displacement>,<wheel>

响应：

OK

参数¶

<buttons>：鼠标按键。
<X_displacement>：X 位移。
<Y_displacement>：Y 位移。
<wheel>：滚轮。

说明¶

更多 HID 鼠标信息，请参考 Universal Serial Bus HID Usage Tables 的 Generic Desktop Page 和 Application Usages 章节。
要使此命令与 iOS 产品交互，您的设备需要先通过 MFI 认证。

示例¶

AT+BLEHIDMUS=0,10,10,0

AT+BLEHIDCONSUMER：发送 Bluetooth LE HID consumer 信息¶

设置命令¶

功能：

发送 consumer 信息

命令：

AT+BLEHIDCONSUMER=<consumer_usage_id>

响应：

OK

参数¶

<consumer_usage_id>：consumer ID，如 power、reset、help、volume 等。详情请参考 HID Usage Tables for Universal Serial Bus (USB) 中的 Consumer Page (0x0C) 章节。

说明¶

要使此命令与 iOS 产品交互，您的设备需要先通过 MFI 认证。

示例¶

AT+BLEHIDCONSUMER=233   // 调高音量

AT+BLUFI：开启或关闭 BluFi¶

查询命令¶

功能：

查询 BluFi 状态

命令：

AT+BLUFI?

响应：

若 BluFi 未开启，则返回：

+BLUFI:0

OK

若 BluFi 已开启，则返回：

+BLUFI:1

OK

设置命令¶

功能：

开启或关闭 BluFi

命令：

AT+BLUFI=<option>[,<auth floor>]

响应：

OK

参数¶

<option>：
- 0: 关闭 BluFi；
- 1: 开启 BluFi。
<auth floor>：Wi-Fi 认证模式阈值，ESP-AT 不会连接到认证模式低于此阈值的 AP：
- 0: OPEN（默认）；
- 1: WEP；
- 2: WPA_PSK；
- 3: WPA2_PSK；
- 4: WPA_WPA2_PSK；
- 5: WPA2_ENTERPRISE；
- 6: WPA3_PSK；
- 7: WPA2_WPA3_PSK。

说明¶

您只能在 Bluetooth LE 未初始化情况下开启或关闭 BluFi (AT+BLEINIT=0)。

示例¶

AT+BLUFI=1

AT+BLUFINAME：查询/设置 BluFi 设备名称¶

查询命令¶

功能：

查询 BluFi 名称

命令：

AT+BLUFINAME?

响应：

+BLUFINAME:<device_name>
OK

设置命令¶

功能：

设置 BluFi 设备名称

命令：

AT+BLUFINAME=<device_name>

响应：

OK

参数¶

<device_name>：BluFi 设备名称。

说明¶

如需设置 BluFi 设备名称，请在运行 AT+BLUFI=1 命令前设置，否则将使用默认名称 BLUFI_DEVICE。
BluFi 设备名称最大长度为 29 字节。

示例¶

AT+BLUFINAME="BLUFI_DEV"
AT+BLUFINAME?

[ESP32 Only] Classic Bluetooth® AT 命令集¶

[English]

ESP32 AT 固件支持蓝牙核心规范 4.2 版本。

[ESP32 Only] AT+BTINIT：Classic Bluetooth 初始化
[ESP32 Only] AT+BTNAME：查询/设置 Classic Bluetooth 设备名称
[ESP32 Only] AT+BTSCANMODE：设置 Classic Bluetooth 扫描模式
[ESP32 Only] AT+BTSTARTDISC：开始发现周边 Classic Bluetooth 设备
[ESP32 Only] AT+BTSPPINIT：Classic Bluetooth SPP 协议初始化
[ESP32 Only] AT+BTSPPCONN：查询/建立 SPP 连接
[ESP32 Only] AT+BTSPPDISCONN：断开 SPP 连接
[ESP32 Only] AT+BTSPPSTART：开启 Classic Bluetooth SPP 协议
[ESP32 Only] AT+BTSPPSEND：发送数据到对方 Classic Bluetooth SPP 设备
[ESP32 Only] AT+BTA2DPINIT：Classic Bluetooth A2DP 协议初始化
[ESP32 Only] AT+BTA2DPCONN：查询/建立 A2DP 连接
[ESP32 Only] AT+BTA2DPDISCONN：断开 A2DP 连接
[ESP32 Only] AT+BTA2DPSRC：查询/设置音频文件 URL
[ESP32 Only] AT+BTA2DPCTRL：控制音频播放
[ESP32 Only] AT+BTSECPARAM：查询/设置 Classic Bluetooth 安全参数
[ESP32 Only] AT+BTKEYREPLY：输入简单配对密钥 (Simple Pair Key)
[ESP32 Only] AT+BTPINREPLY：输入传统配对密码 (Legacy Pair PIN Code)
[ESP32 Only] AT+BTSECCFM：给对方设备回复确认结果（传统连接阶段）
[ESP32 Only] AT+BTENCDEV：查询 Classic Bluetooth 加密设备列表
[ESP32 Only] AT+BTENCCLEAR：清除 Classic Bluetooth 加密设备列表
[ESP32 Only] AT+BTCOD：设置设备类型
[ESP32 Only] AT+BTPOWER：查询/设置 Classic Bluetooth 的 TX 功率

[ESP32 Only] AT+BTINIT：Classic Bluetooth 初始化¶

查询命令¶

功能：

查询 Classic Bluetooth 初始化状态

命令：

AT+BTINIT?

响应：

若已初始化，则返回：

+BTINIT:1
OK

若未初始化，则返回：

+BTINIT:0
OK

设置命令¶

功能：

初始化或注销 Classic Bluetooth

命令：

AT+BTINIT=<init>

响应：

OK

参数¶

<init>：
- 0: 注销 Classic Bluetooth；
- 1: 初始化 Classic Bluetooth。

示例¶

AT+BTINIT=1

[ESP32 Only] AT+BTNAME：查询/设置 Classic Bluetooth 设备名称¶

查询命令¶

功能：

查询 Classic Bluetooth 设备名称

命令：

AT+BTNAME?

响应：

+BTNAME:<device_name>
OK

设置命令¶

功能：

设置 Classic Bluetooth 设备名称

命令：

AT+BTNAME=<device_name>

响应：

OK

参数¶

<device_name>：Classic Bluetooth 设备名称，最大长度为：32。

说明¶

若 AT+SYSSTORE=1，配置更改将保存在 NVS 区。
默认 Classic Bluetooth 设备名称为 “ESP32_AT”。

示例¶

AT+BTNAME="esp_demo"

[ESP32 Only] AT+BTSCANMODE：设置 Classic Bluetooth 扫描模式¶

设置命令¶

功能：

设置 Classic Bluetooth 扫描模式

命令：

AT+BTSCANMODE=<scan_mode>

响应：

OK

参数¶

<scan_mode>：
- 0: 不可发现且不可连接；
- 1: 可连接但不可发现；
- 2: 既可发现也可连接；
- 3: 可发现但不可连接。

示例¶

AT+BTSCANMODE=2   // 既可发现也可连接

[ESP32 Only] AT+BTSTARTDISC：开始发现周边 Classic Bluetooth 设备¶

设置命令¶

功能：

开始发现 Classic Bluetooth 设备

命令：

AT+BTSTARTDISC=<inq_mode>,<inq_len>,<inq_num_rsps>

响应：

+BTSTARTDISC:<bt_addr>,<dev_name>,<major_dev_class>,<minor_dev_class>,<major_srv_class>,<rssi>

OK

参数¶

<inq_mode>：
- 0: general inquiry mode；
- 1: limited inquiry mode。
<inq_len>：inquiry 时长，范围：0x01 ~ 0x30。
<inq_num_rsps>：可以收到的 inquiry responses 的数量，若设为 0，AT 将收到无限个 response。
<bt_addr>：Classic Bluetooth 地址。
<dev_name>：设备名称。
<major_dev_class>：主要设备类型：
- 0x0: 其他；
- 0x1: 计算机；
- 0x2: 电话（手机、无绳、支付电话、调制解调器）；
- 0x3: LAN、网络接入点；
- 0x4: 音频/视频（耳机、扬声器、立体声、视频显示、VCR）；
- 0x5: 配件（鼠标、游戏杆、键盘）；
- 0x6: 成像（打印、扫描仪、相机、显示）；
- 0x7: 可穿戴；
- 0x8: 玩具；
- 0x9: 健康；
- 0x1F: 未分类。
<minor_dev_class>：请参考次要设备类型 (Minor Device Class field)。
<major_srv_class>：主要服务类型：
- 0x0: 无效值；
- 0x1: 有限可发现模式 (Limited Discoverable Mode)；
- 0x8: 定位（位置标志）；
- 0x10: 网络，如 LAN、点对点；
- 0x20: 渲染，如打印、扬声器；
- 0x40: 捕捉，如扫描仪、麦克风；
- 0x80: 对象传输，如 v-Inbox、v-Folder；
- 0x100: 音频，如扬声器、麦克风、耳机服务；
- 0x200: 电话，如无绳电话、调制解调器、耳机服务；
- 0x400: 信息，如 WEB 服务器、WAP 服务器。
<rssi>：信号强度。

示例¶

AT+BTINIT=1
AT+BTSCANMODE=2
AT+BTSTARTDISC=0,10,10

[ESP32 Only] AT+BTSPPINIT：Classic Bluetooth SPP 协议初始化¶

查询命令¶

功能：

查询 Classic Bluetooth SPP 协议初始化状态

命令：

AT+BTSPPINIT?

响应：

若已初始化，则返回：

+BTSPPINIT:1
OK

若未初始化，则返回：

+BTSPPINIT:0
OK

设置命令¶

功能：

初始化或注销 Classic Bluetooth SPP 协议

命令：

AT+BTSPPINIT=<init>

响应：

OK

参数¶

<init>：
- 0: 注销 Classic Bluetooth SPP 协议；
- 1: 初始化 Classic Bluetooth SPP 协议，角色为 master；
- 2: 初始化 Classic Bluetooth SPP 协议，角色为 slave。

示例¶

AT+BTSPPINIT=1    // master
AT+BTSPPINIT=2    // slave

[ESP32 Only] AT+BTSPPCONN：查询/建立 SPP 连接¶

查询命令¶

功能：

查询 Classic Bluetooth SPP 连接

命令：

AT+BTSPPCONN?

响应：

+BTSPPCONN:<conn_index>,<remote_address>
OK

如果未建立连接，则返回：

+BTSPPCONN:-1

设置命令¶

功能：

建立 Classic Bluetooth SPP 连接

命令：

AT+BTSPPCONN=<conn_index>,<sec_mode>,<remote_address>

响应：

OK

若建立连接成功，则 AT 返回：

+BTSPPCONN:<conn_index>,<remote_address>

若建立连接失败，则 AT 返回：

+BTSPPCONN:<conn_index>,-1

参数¶

<conn_index>：Classic Bluetooth SPP 连接号，当前只支持单连接，连接号为 0。
<sec_mode>：
- 0x0000: 无安全保障；
- 0x0001: 需要授权（仅对外连接需要）；
- 0x0036: 需要加密；
- 0x3000: 中间人保护；
- 0x4000: 最少 16 位密码。
<remote_address>：对方 Classic Bluetooth SPP 设备地址。

示例¶

AT+BTSPPCONN=0,0,"24:0a:c4:09:34:23"

[ESP32 Only] AT+BTSPPDISCONN：断开 SPP 连接¶

执行命令¶

功能：

断开 Classic Bluetooth SPP 连接

命令：

AT+BTSPPDISCONN=<conn_index>

响应：

OK

若命令运行成功，则返回：

+BTSPPDISCONN:<conn_index>,<remote_address>

若命令运行失败，则返回：

+BTSPPDISCONN:-1

参数¶

<conn_index>：Classic Bluetooth SPP 连接号，当前只支持单连接，连接号为 0。
<remote_address>：对方 Classic Bluetooth A2DP 设备地址。

示例¶

AT+BTSPPDISCONN=0

[ESP32 Only] AT+BTSPPSEND：发送数据到对方 Classic Bluetooth SPP 设备¶

执行命令¶

功能：

进入 Classic Bluetooth SPP 模式

命令：

AT+BTSPPSEND

响应：

设置命令¶

功能：

发送数据到对方 Classic Bluetooth SPP 设备

命令：

AT+BTSPPSEND=<conn_index>,<data_len>

响应：

OK

参数¶

<conn_index>：Classic Bluetooth SPP 连接号，当前只支持单连接，连接号为 0。
<data_len>：发送数据的长度。

说明¶

系统收到此命令后先换行返回 >，然后 ESP 设备进入 UART Bluetooth 透传模式，当系统收到只含有 +++ 的包时，设备返回到普通命令模式，请等待一秒再发送下一个 AT 命令。

示例¶

AT+BTSPPSEND=0,100
AT+BTSPPSEND

[ESP32 Only] AT+BTSPPSTART：开启 Classic Bluetooth SPP 协议¶

执行命令¶

功能：

开启 Classic Bluetooth SPP 协议

命令：

AT+BTSPPSTART

响应：

OK

说明¶

在 SPP 传输中，如果未设置 AT+SYSMSG 命令的 bit2 为 1，则系统不会提示任何连接状态改变的信息。

示例¶

AT+BTSPPSTART

[ESP32 Only] AT+BTA2DPINIT：Classic Bluetooth A2DP 协议初始化¶

查询命令¶

功能：

查询 Classic Bluetooth A2DP 协议的初始化状态

命令：

AT+BTA2DPINIT?

响应：

若已初始化，则返回：

+BTA2DPINIT:<role>

OK

若未初始化，则返回：

+BTA2DPINIT:0

OK

设置命令¶

功能：

初始化或注销 Classic Bluetooth A2DP 协议

命令：

AT+BTA2DPINIT=<role>

响应：

OK

参数¶

<role>：角色
- 0: 注销 Classic Bluetooth A2DP 协议；
- 1: source；
- 2: sink。

示例¶

AT+BTA2DPINIT=2

[ESP32 Only] AT+BTA2DPCONN：查询/建立 A2DP 连接¶

查询命令¶

功能：

查询 Classic Bluetooth A2DP 连接

命令：

AT+BTA2DPCONN?

响应：

+BTA2DPCONN:<conn_index>,<remote_address>
OK

若未建立连接，则 AT 不会返回 <conn_index> 和 <remote_address> 参数。

设置命令¶

功能：

建立 Classic Bluetooth A2DP 连接

命令：

AT+BTA2DPCONN=<conn_index>,<remote_address>

响应：

OK

若建立连接成功，则返回：

+BTA2DPCONN:<conn_index>,<remote_address>

若建立连接失败，则返回：

+BTA2DPCONN:<conn_index>,-1

参数¶

<conn_index>：Classic Bluetooth A2DP 连接号，当前只支持单连接，连接号为 0。
<remote_address>：对方 Classic Bluetooth A2DP 设备地址。

示例¶

AT+BTA2DPCONN=0,0,0,"24:0a:c4:09:34:23"

[ESP32 Only] AT+BTA2DPDISCONN：断开 A2DP 连接¶

执行命令¶

功能：

断开 Classic Bluetooth A2DP 连接

命令：

AT+BTA2DPDISCONN=<conn_index>

响应：

+BTA2DPDISCONN:<conn_index>,<remote_address>
OK

参数¶

<conn_index>：Classic Bluetooth A2DP 连接号，当前只支持单连接，连接号为 0。
<remote_address>：对方 Classic Bluetooth A2DP 设备地址。

示例¶

AT+BTA2DPDISCONN=0

[ESP32 Only] AT+BTA2DPSRC：查询/设置音频文件 URL¶

查询命令¶

功能：

查询音频文件 URL

命令：

AT+BTA2DPSRC?

响应：

+BTA2DPSRC:<url>,<type>
OK

执行命令¶

功能：

设置音频文件 URL

命令：

AT+BTA2DPSRC=<conn_index>,<url>

响应：

OK

参数¶

<conn_index>：Classic Bluetooth A2DP 连接号，当前只支持单连接，连接号为 0。
<url>：源文件路径，当前只支持 HTTP、HTTPS 和 FLASH。
<type>：音频文件类型，如 “mp3”。

说明¶

当前只支持 mp3 格式文件。

示例¶

AT+BTA2DPSRC=0,"https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp3"
AT+BTA2DPSRC=0,"flash://spiffs/zhifubao.mp3"

[ESP32 Only] AT+BTA2DPCTRL：控制音频播放¶

执行命令¶

功能：

控制音频播放

命令：

AT+BTA2DPCTRL=<conn_index>,<ctrl>

响应：

OK

参数¶

<conn_index>：Classic Bluetooth A2DP 连接号，当前只支持单连接，连接号为 0。
<ctrl>：控制类型：
- 0: A2DP Sink，停止播放；
- 1: A2DP Sink，开始播放；
- 2: A2DP Sink，快进；
- 3: A2DP Sink，后退；
- 4: A2DP Sink，快进启动；
- 5: A2DP Sink，快进停止；
- 0: A2DP Source，停止播放；
- 1: A2DP Source，开始播放；
- 2: A2DP Source，暂停播放。

示例¶

AT+BTA2DPCTRL=0,1  // 开始播放音频

[ESP32 Only] AT+BTSECPARAM：查询/设置 Classic Bluetooth 安全参数¶

查询命令¶

功能：

查询 Classic Bluetooth 安全参数

命令：

AT+BTSECPARAM?

响应：

+BTSECPARAM:<io_cap>,<pin_type>,<pin_code>
OK

设置命令¶

功能：

设置 Classic Bluetooth 安全参数

命令：

AT+BTSECPARAM=<io_cap>,<pin_type>,<pin_code>

响应：

OK

参数¶

<io_cap>：输入输出能力：
- 0: DisplayOnly；
- 1: DisplayYesNo；
- 2: KeyboardOnly；
- 3: NoInputNoOutput。
<pin_type>：使用可变或固定密码：
- 0: 可变密码；
- 1: 固定密码。
<pin_code>：传统配对密码，最大长度：16 字节。

说明¶

若设置 <pin_type> 为 0，则会自动忽略 <pin_code> 参数。

示例¶

AT+BTSECPARAM=3,1,"9527"

[ESP32 Only] AT+BTKEYREPLY：输入简单配对密钥 (Simple Pair Key)¶

执行命令¶

功能：

输入简单配对密钥 (Simple Pair Key)

命令：

AT+BTKEYREPLY=<conn_index>,<Key>

响应：

OK

参数¶

<conn_index>：Classic Bluetooth 连接号，当前只支持单连接，连接号为 0。
<Key>：简单配对密钥 (Simple Pair Key)。

示例¶

AT+BTKEYREPLY=0,123456

[ESP32 Only] AT+BTPINREPLY：输入传统配对密码 (Legacy Pair PIN Code)¶

执行命令¶

功能：

输入传统配对密码 (Legacy Pair PIN Code)

命令：

AT+BTPINREPLY=<conn_index>,<Pin>

响应：

OK

参数¶

<conn_index>：Classic Bluetooth 连接号，当前只支持单连接，连接号为 0。
<Pin>：传统配对密码 (Legacy Pair PIN Code)。

示例¶

AT+BTPINREPLY=0,"6688"

[ESP32 Only] AT+BTSECCFM：给对方设备回复确认结果（传统连接阶段）¶

执行命令¶

功能：

给对方设备回复确认结果（传统连接阶段）

命令：

AT+BTSECCFM=<conn_index>,<accept>

响应：

OK

参数¶

<conn_index>：Classic Bluetooth 连接，当前只支持单连接，连接号为 0。
<accept>：拒绝或接受：
- 0: 拒绝；
- 1: 接受。

示例¶

AT+BTSECCFM=0,1

[ESP32 Only] AT+BTENCDEV：查询 Classic Bluetooth 加密设备列表¶

查询命令¶

功能：

查询绑定设备

命令：

AT+BTENCDEV?

响应：

+BTENCDEV:<enc_dev_index>,<mac_address>
OK

参数¶

<enc_dev_index>：绑定设备序号。
<mac_address>：MAC 地址。

示例¶

AT+BTENCDEV?

[ESP32 Only] AT+BTENCCLEAR：清除 Classic Bluetooth 加密设备列表¶

设置命令¶

功能：

从安全数据库列表中删除某一序号的设备

命令：

AT+BTENCCLEAR=<enc_dev_index>

响应：

OK

执行命令¶

功能：

删除安全数据库所有设备

命令：

AT+BLEENCCLEAR

响应：

OK

参数¶

<enc_dev_index>：绑定设备序号。

示例¶

AT+BTENCCLEAR

[ESP32 Only] AT+BTCOD：设置设备类型¶

设置命令¶

功能：

设置 Classic Bluetooth 设备类型

命令：

AT+BTCOD=<major>,<minor>,<service>

响应：

OK

参数¶

示例¶

AT+BTCOD=6,32,32   // 打印机

[ESP32 Only] AT+BTPOWER：查询/设置 Classic Bluetooth 的 TX 功率¶

查询命令¶

功能：

查询 Classic Bluetooth 的 TX 功率

命令：

AT+BTPOWER?

响应：

+BTPOWER:<min_tx_power>,<max_tx_power>
OK

设置命令¶

功能：

设置 Classic Bluetooth 的 TX 功率

命令：

AT+BTPOWER=<min_tx_power>,<max_tx_power>

响应：

OK

参数¶

<min_tx_power>：最小功率水平，范围：[0,7]。
<max_tx_power>：最大功率水平，范围：[0,7]。

示例¶

AT+BTPOWER=5,6   // 设置 Classic Bluetooth tx 功率

MQTT AT Commands¶

[English]

AT+MQTTUSERCFG：设置 MQTT 用户属性
AT+MQTTCLIENTID：设置 MQTT 客户端 ID
AT+MQTTUSERNAME：设置 MQTT 登陆用户名
AT+MQTTPASSWORD：设置 MQTT 登陆密码
AT+MQTTCONNCFG：设置 MQTT 连接属性
AT+MQTTALPN：设置 MQTT 应用层协议协商（ALPN）
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¶

设置命令¶

功能：

设置 MQTT 客户端 ID

命令：

AT+MQTTCLIENTID=<LinkID>,<"client_id">

响应：

OK

参数¶

<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 登陆用户名¶

设置命令¶

功能：

设置 MQTT 用户名

命令：

AT+MQTTUSERNAME=<LinkID>,<"username">

响应：

OK

参数¶

<LinkID>：当前仅支持 link ID 0。
<username>：用于登陆 MQTT broker 的用户名。

说明¶

每条 AT 命令的总长度不能超过 256 字节。
AT+MQTTUSERCFG 命令也可以设置 MQTT 用户名，二者之间的差别包括：
- AT+MQTTUSERNAME 命令可以用来设置相对较长的用户名，因为 AT+MQTTUSERCFG 命令的长度受限。
- 应在设置 AT+MQTTUSERCFG 后再使用 AT+MQTTUSERNAME。

AT+MQTTPASSWORD：设置 MQTT 登陆密码¶

设置命令¶

功能：

设置 MQTT 密码

命令：

AT+MQTTPASSWORD=<LinkID>,<"password">

响应：

OK

参数¶

<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+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¶

查询命令¶

功能：

查询 ESP 设备已连接的 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 不自动重连；
- 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+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+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 设备的最大长度受到可利用内存的限制。
<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> 消息。

HTTP AT 命令集¶

[English]

AT+HTTPCLIENT：发送 HTTP 客户端请求
AT+HTTPGETSIZE：获取 HTTP 资源大小
AT+HTTPCGET：获取 HTTP 资源
AT+HTTPCPOST：Post 指定长度的 HTTP 数据
AT+HTTPURLCFG：设置/获取长的 HTTP URL
HTTP AT 错误码

AT+HTTPCLIENT：发送 HTTP 客户端请求¶

设置命令¶

命令：

AT+HTTPCLIENT=<opt>,<content-type>,<"url">,[<"host">],[<"path">],<transport_type>[,<"data">][,<"http_req_header">][,<"http_req_header">][...]

响应：

+HTTPCLIENT:<size>,<data>

OK

参数¶

<opt>：HTTP 客户端请求方法：
- 1：HEAD
- 2：GET
- 3：POST
- 4：PUT
- 5：DELETE
<content-type>：客户端请求数据类型：
- 0：application/x-www-form-urlencoded
- 1：application/json
- 2：multipart/form-data
- 3：text/xml
<”url”>：HTTP URL，当后面的 <host> 和 <path> 参数为空时，本参数会自动覆盖这两个参数。
<”host”>：域名或 IP 地址。
<”path”>：HTTP 路径。
<transport_type>：HTTP 客户端传输类型，默认值为 1：
- 1：HTTP_TRANSPORT_OVER_TCP
- 2：HTTP_TRANSPORT_OVER_SSL
<”data”>：当 <opt> 是 POST 请求时，本参数为发送给 HTTP 服务器的数据。当 <opt> 不是 POST 请求时，这个参数不存在（也就是，不需要输入逗号来表示有这个参数）。
<”http_req_header”>：可发送多个请求头给服务器。

说明¶

如果包含 URL 的整条命令的长度超过了 256 字节，请先使用 AT+HTTPURLCFG 命令预配置 URL，然后本命令里的 <”url”> 参数需要设置为 ""。
如果 url 参数不为空，HTTP 客户端将使用它并忽略 host 参数和 path 参数；如果 url 参数被省略或字符串为空，HTTP 客户端将使用 host 参数和 path 参数。
某些已发布的固件默认不支持 HTTP 客户端命令（详情请见 ESP-AT 固件差异），但是可通过以下方式使其支持该命令：./build.py menuconfig > Component config > AT > AT http command support，然后编译项目（详情请见编译 ESP-AT 工程）。

示例¶

// HEAD 请求
AT+HTTPCLIENT=1,0,"http://httpbin.org/get","httpbin.org","/get",1

// GET 请求
AT+HTTPCLIENT=2,0,"http://httpbin.org/get","httpbin.org","/get",1

// POST 请求
AT+HTTPCLIENT=3,0,"http://httpbin.org/post","httpbin.org","/post",1,"field1=value1&field2=value2"

AT+HTTPGETSIZE：获取 HTTP 资源大小¶

设置命令¶

命令：

AT+HTTPGETSIZE=<"url">

响应：

+HTTPGETSIZE:<size>

OK

参数¶

<”url”>：HTTP URL。
<size>：HTTP 资源大小。

说明¶

如果包含 URL 的整条命令的长度超过了 256 字节，请先使用 AT+HTTPURLCFG 命令预配置 URL，然后本命令里的 <”url”> 参数需要设置为 ""。
某些已发布的固件默认不支持 HTTP 客户端命令（详情请见 ESP-AT 固件差异），但是可通过以下方式使其支持该命令：./build.py menuconfig > Component config > AT > AT http command support，然后编译项目（详情请见编译 ESP-AT 工程）。

示例¶

AT+HTTPGETSIZE="http://www.baidu.com/img/bdlogo.gif"

AT+HTTPCGET：获取 HTTP 资源¶

设置命令¶

命令：

AT+HTTPCGET=<"url">[,<tx size>][,<rx size>][,<timeout>]

响应：

+HTTPCGET:<size>,<data>
OK

参数¶

<”url”>：HTTP URL。
<tx size>：HTTP 发送缓存大小。单位：字节。默认值：2048。范围：[0,10240]。
<rx size>：HTTP 接收缓存大小。单位：字节。默认值：2048。范围：[0,10240]。
<timeout>：网络超时。单位：毫秒。默认值：5000。范围：[0,180000]。

说明¶

如果包含 URL 的整条命令的长度超过了 256 字节，请先使用 AT+HTTPURLCFG 命令预配置 URL，然后本命令里的 <”url”> 参数需要设置为 ""。

AT+HTTPCPOST：Post 指定长度的 HTTP 数据¶

设置命令¶

命令：

AT+HTTPCPOST=<"url">,<length>[,<http_req_header_cnt>][,<http_req_header>..<http_req_header>]

响应：

OK

>

符号 > 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 <length> 的值时，传输开始。

若传输成功，则返回：

SEND OK

若传输失败，则返回：

SEND FAIL

参数¶

<”url”>：HTTP URL。
<length>：需 POST 的 HTTP 数据长度。最大长度等于系统可分配的堆空间大小。
<http_req_header_cnt>：<http_req_header> 参数的数量。
[<http_req_header>]：可发送多个请求头给服务器。

说明¶

如果包含 URL 的整条命令的长度超过了 256 字节，请先使用 AT+HTTPURLCFG 命令预配置 URL，然后本命令里的 <”url”> 参数需要设置为 ""。

AT+HTTPURLCFG：设置/获取长的 HTTP URL¶

查询命令¶

命令：

AT+HTTPURLCFG?

响应：

[+HTTPURLCFG:<url length>,<data>]
OK

设置命令¶

命令：

AT+HTTPURLCFG=<url length>

响应：

OK

>

符号 > 表示 AT 准备好接收串口数据，此时您可以输入 URL，当数据长度达到参数 <url length> 的值时，系统返回：

SET OK

参数¶

<url length>：HTTP URL 长度。单位：字节。
- 0：清除 HTTP URL 配置。
- [8,8192]：设置 HTTP URL 配置。
<data>： HTTP URL 数据。

HTTP AT 错误码 ¶

HTTP 客户端：

HTTP 客户端错误码	说明
0x7000	建立连接失败
0x7190	Bad Request
0x7191	Unauthorized
0x7192	Payment Required
0x7193	Forbidden
0x7194	Not Found
0x7195	Method Not Allowed
0x7196	Not Acceptable
0x7197	Proxy Authentication Required
0x7198	Request Timeout
0x7199	Conflict
0x719a	Gone
0x719b	Length Required
0x719c	Precondition Failed
0x719d	Request Entity Too Large
0x719e	Request-URI Too Long
0x719f	Unsupported Media Type
0x71a0	Requested Range Not Satisfiable
0x71a1	Expectation Failed

HTTP 服务器：

HTTP 服务器错误码	说明
0x71f4	Internal Server Error
0x71f5	Not Implemented
0x71f6	Bad Gateway
0x71f7	Service Unavailable
0x71f8	Gateway Timeout
0x71f9	HTTP Version Not Supported

HTTP AT：
- AT+HTTPCLIENT 命令的错误码为 0x7000+Standard HTTP Error Code （更多有关 Standard HTTP/1.1 Error Code 的信息，请参考 RFC 2616）。
- 例如，若 AT 在调用 AT+HTTPCLIENT 命令时收到 HTTP error 404，则会返回 0x7194 错误码 (hex(0x7000+404)=0x7194)。

[ESP32 Only] 以太网 AT 命令¶

[English]

准备工作
[ESP32 Only] AT+CIPETHMAC：查询/设置 ESP 以太网的 MAC 地址
[ESP32 Only] AT+CIPETH：查询/设置 ESP 以太网的 IP 地址

准备工作 ¶

运行以太网 AT 命令之前，请做好以下准备工作：

注意

本节内容以 ESP32-Ethernet-Kit 开发板为例介绍运行以太网 AT 命令前的准备工作。如果您使用的是其它模组或开发板，请查阅对应的技术规格书获取 RX/TX 管脚号。

修改 AT UART 管脚（因为默认的 AT UART 管脚和以太网功能管脚冲突）：
- 打开 factory_param_data.csv 表格文件；
- 将 WROVER-32 的 uart_tx_pin 从 GPIO22 改为 GPIO2， uart_rx_pin 从 GPIO19 改为 GPIO4， uart_cts_pin 从 GPIO15 改为 GPIO1，uart_rts_pin 从 GPIO14 改为 GPIO1 （硬件流控功能可选，这里未使用该功能），更多信息请见如何设置 AT 端口管脚。
使能 AT ethernet support，更多信息请见如何启用 ESP-AT 以太网功能。
编译后将该工程烧录至 ESP32-Ethernet-Kit。
连接硬件：
- 连接主机 MCU（如 PC，可使用 USB 转串口模块）至 ESP32-Ethernet-Kit 的 GPIO2 (TX) 和 GPIO4 (RX)，不使用流控功能则无需连接 CTS/RTS；
- ESP32-Ethernet-Kit 连接以太网网络。

[ESP32 Only] AT+CIPETHMAC：查询/设置 ESP 以太网的 MAC 地址¶

查询命令¶

功能：

查询 ESP 以太网的 MAC 地址

命令：

AT+CIPETHMAC?

响应：

+CIPETHMAC:<"mac">
OK

设置命令¶

功能：

设置 ESP 以太网的 MAC 地址

命令：

AT+CIPETHMAC=<"mac">

响应：

OK

参数¶

<”mac”>：字符串参数，表示以太网接口的 MAC 地址。

说明¶

固件默认不支持以太网 AT 命令 (详情请见 ESP-AT 固件差异)，但是可通过以下方式使其支持该命令：./build.py menuconfig > Component config > AT > AT ethernet support，然后编译工程（详情请见编译 ESP-AT 工程）。
若 AT+SYSSTORE=1，配置更改将保存在 NVS 区。
以太网接口的 MAC 地址不能与其他接口的相同。
ESP MAC 地址的 bit0 不能设为 1。例如，可设为 “1a:…”，但不可设为 “15:…”。
FF:FF:FF:FF:FF:FF 和 00:00:00:00:00:00 为无效 MAC 地址，不能设置。

示例¶

AT+CIPETHMAC="1a:fe:35:98:d4:7b"

[ESP32 Only] AT+CIPETH：查询/设置 ESP 以太网的 IP 地址¶

查询命令¶

功能：

查询 ESP 以太网的 IP 地址

命令：

AT+CIPETH?

响应：

+CIPETH:ip:<ip>
+CIPETH:gateway:<gateway>
+CIPETH:netmask:<netmask>
OK

设置命令¶

功能：

设置 ESP 以太网的 IP 地址

命令：

AT+CIPETH=<ip>[,<gateway>,<netmask>]

响应：

OK

参数¶

<ip>：字符串参数，表示 ESP 以太网的 IP 地址。
[<gateway>]：网关。
[<netmask>]：网络掩码。

说明¶

固件默认不支持以太网 AT 命令 (详情请见 ESP-AT 固件差异)，但是可通过以下方式使其支持该命令：./build.py menuconfig > Component config > AT > AT ethernet support，然后编译工程（详情请见编译 ESP-AT 工程）。
若 AT+SYSSTORE=1，配置更改将保存在 NVS 区。
本命令的设置命令与 DHCP 相互影响，如 AT+CWDHCP：
- 若启用静态 IP，则 DHCP 会被禁用；
- 若启用 DHCP，则静态 IP 会被禁用；
- 最后一次配置会覆盖上一次配置。

示例¶

AT+CIPETH="192.168.6.100","192.168.6.1","255.255.255.0"

信令测试 AT 命令¶

[English]

AT+FACTPLCP：发送长 PLCP 或短 PLCP

AT+FACTPLCP：发送长 PLCP 或短 PLCP¶

设置命令¶

命令：

AT+FACTPLCP=<enable>,<tx_with_long>

响应：

OK

参数¶

<enable>：启用/禁用手动配置：
- 0: 禁用手动配置，将使用 <tx_with_long> 参数的默认值；
- 1: 启用手动配置，AT 发送的 PLCP 类型取决于 <tx_with_long> 参数。
<tx_with_long>：发送长 PLCP 或短 PLCP：
- 0: 发送短 PLCP（默认）；
- 1: 发送长 PLCP。

驱动 AT 命令¶

[English]

AT+DRVADC：读取 ADC 通道值
AT+DRVPWMINIT：初始化 PWM 驱动器
AT+DRVPWMDUTY：设置 PWM 占空比
AT+DRVPWMFADE：设置 PWM 渐变
AT+DRVI2CINIT：初始化 I2C 主机驱动
AT+DRVI2CRD：读取 I2C 数据
AT+DRVI2CWRDATA：写入 I2C 数据
AT+DRVI2CWRBYTES：写入不超过 4 字节的 I2C 数据
AT+DRVSPICONFGPIO：配置 SPI GPIO
AT+DRVSPIINIT：初始化 SPI 主机驱动
AT+DRVSPIRD：读取 SPI 数据
AT+DRVSPIWR：写入 SPI 数据

AT+DRVADC：读取 ADC 通道值¶

设置命令¶

命令：

AT+DRVADC=<channel>,<atten>

响应：

+DRVADC:<raw data>

OK

参数¶

<channel>：ADC1 通道。
- ESP32 设备的取值范围为 [0,7]。
  
  通道
  
  管脚
  
  0
  
  GPIO36
  
  1
  
  GPIO37
  
  2
  
  GPIO38
  
  3
  
  GPIO39
  
  4
  
  GPIO32
  
  5
  
  GPIO33
  
  6
  
  GPIO34
  
  7
  
  GPIO35
- ESP32-C3 设备的取值范围为 [0,4]。
  
  通道
  
  管脚
  
  0
  
  GPIO0
  
  1
  
  GPIO1
  
  2
  
  GPIO2
  
  3
  
  GPIO3
  
  4
  
  GPIO4
<atten>：衰减值。
- ESP32 设备的参数值：
  - 0: 0 dB 衰减，有效测量范围为 [100, 950] mV。
  - 1: 2.5 dB 衰减，有效测量范围为 [100, 1250] mV。
  - 2: 6 dB 衰减，有效测量范围为 [150, 1750] mV。
  - 3: 11 dB 衰减，有效测量范围为 [150, 2450] mV。
- ESP32-C3 设备的参数值：
  - 0: 0 dB 衰减，有效测量范围为 [0, 750] mV。
  - 1: 2.5 dB 衰减，有效测量范围为 [0, 1050] mV。
  - 2: 6 dB 衰减，有效测量范围为 [0, 1300] mV。
  - 3: 11 dB 衰减，有效测量范围为 [0, 2500] mV。
<raw data>：ADC 通道值。

说明¶

ESP-AT 只支持 ADC1。
ESP32 和 ESP32-C3 支持 12 位宽度。
对于如何将通道值转换为电压，ESP32 设备可以参考 ADC 转换，ESP32-C3 设备可以参考 ADC 转换。

示例¶

// ESP32 设备设置为 0 dB 衰减，有效测量范围为 [100, 950] mV
// 电压为 2048 / 4095 * 950 = 475.12 mV
AT+DRVADC=0,0
+DRVADC:2048

OK

// ESP32-C3 设备设置为 0 dB 衰减，有效测量范围为 [0, 750] mV
// 电压为 2048 / 4095 * 750 = 375.09 mV
AT+DRVADC=0,0
+DRVADC:2048

OK

AT+DRVPWMINIT：初始化 PWM 驱动器¶

设置命令¶

命令：

AT+DRVPWMINIT=<freq>,<duty_res>,<ch0_gpio>[,...,<ch3_gpio>]

响应：

OK

参数¶

<freq>：LEDC 定时器频率，单位：Hz，范围：1 Hz ~ 8 MHz。
<duty_res>：LEDC 通道占空比分辨率，范围：0 ~ 20 位。
<chx_gpio>：LEDC 通道 x 的输出 GPIO。例如，如果您想将 GPIO16 作为通道 0，需设置 <ch0_gpio> 为 16。

说明¶

ESP-AT 最多能支持 4 个通道。
使用本命令初始化的通道数量直接决定了其它 PWM 命令（如 AT+DRVPWMDUTY 和 AT+DRVPWMFADE）能够设置的通道。例如，如果您只初始化了两个通道，那么 AT+DRVPWMDUTY 命令只能用来更改这两个通道的 PWM 占空比。
频率和占空比分辨率相互影响。更多信息请见频率和占空比分辨率支持范围。

示例¶

AT+DRVPWMINIT=5000,13,17,16,18,19  // 设置 4 个通道，频率为 5 kHz，占空比分辨率为 13 位
AT+DRVPWMINIT=10000,10,17          // 只初始化通道 0，频率为 10 kHz，占空比分辨率为 10 位，其它 PWM 相关命令只能设置一个通道

AT+DRVPWMDUTY：设置 PWM 占空比¶

设置命令¶

命令：

AT+DRVPWMDUTY=<ch0_duty>[,...,<ch3_duty>]

响应：

OK

参数¶

<duty>：LEDC 通道占空比，范围：[0,2 ^{占空比分辨率}]。

说明¶

ESP-AT 最多能支持 4 个通道。
若某个通道无需设置占空比，直接省略该参数。

示例¶

AT+DRVPWMDUTY=255,512   // 设置通道 0 的占空比为 255，设置通道 1 的占空比为 512
AT+DRVPWMDUTY=,,0       // 只设置通道 2 的占空比为 0

AT+DRVPWMFADE：设置 PWM 渐变¶

设置命令¶

命令：

AT+DRVPWMFADE=<ch0_target_duty>,<ch0_fade_time>[,...,<ch3_target_duty>,<ch3_fade_time>]

响应：

OK

参数¶

<target_duty>：目标渐变占空比，范围：[0,2 ^{duty_resolution}–1]。
<fade_time>：渐变的最长时间，单位：毫秒。

说明¶

ESP-AT 最多能支持 4 个通道。
若某个通道无需设置 <target_duty> 和 <fade_time>，直接省略即可。

示例¶

AT+DRVPWMFADE=,,0,1000           // 使用一秒的时间将通道 1 的占空比设置为 0
AT+DRVPWMFADE=1024,1000,0,2000,  // 使用一秒的时间将通道 0 的占空比设置为 1024、两秒的时间将通道 1 的占空比设为 0

AT+DRVI2CINIT：初始化 I2C 主机驱动¶

设置命令¶

命令：

AT+DRVI2CINIT=<num>,<scl_io>,<sda_io>,<clock>

响应：

OK

参数¶

<num>：I2C 端口号，范围：0 ~ 1。如果未设置后面的参数，AT 将不初始化该 I2C 端口。
<scl_io>：I2C SCL 信号的 GPIO 号。
<sda_io>：I2C SDA 信号的 GPIO 号。
<clock>：主机模式下的 I2C 时钟频率，单位：Hz，最大值：1 MHz。

说明¶

本指令只支持 I2C 主机。

示例¶

AT+DRVI2CINIT=0,25,26,1000  // 初始化 I2C0，SCL：GPIO25，SDA：GPIO26，I2C 时钟频率：1 kHz
AT+DRVI2CINIT=0             // 取消 I2C0 初始化

AT+DRVI2CRD：读取 I2C 数据¶

设置命令¶

命令：

AT+DRVI2CRD=<num>,<address>,<length>

响应：

+DRVI2CRD:<read data>
OK

参数¶

<num>：I2C 端口号，范围：0 ~ 1。
<address>：I2C 从机设备地址：
- 7 位地址：0 ~ 0x7F；
- 10 位地址：第一个字节的前七个位是 1111 0XX，其中最后两位 XX 是 10 位地址的最高两位。例如，如果 10 位地址为 0x2FF (b’1011111111)，那么输入的地址为 0x7AFF (b’111101011111111)。
<length>：I2C 数据长度，范围：1 ~ 2048。
<read data>：I2C 数据。

说明¶

I2C 传输超时时间为一秒。

示例¶

AT+DRVI2CRD=0,0x34,1     // I2C0 从地址 0x34 处读取 1 字节的数据
AT+DRVI2CRD=0,0x7AFF,1   // I2C0 从 10 位地址 0x2FF 处读取 1 字节的数据

// I2C0 读地址 0x34，寄存器地址 0x27，读 2 字节
AT+DRVI2CWRBYTES=0,0x34,1,0x27     // I2C0 先写设备地址 0x34、寄存器地址 0x27
AT+DRVI2CRD=0,0x34,2               // I2C0 读地址 2 字节

AT+DRVI2CWRDATA：写入 I2C 数据¶

设置命令¶

命令：

AT+DRVI2CWRDATA=<num>,<address>,<length>

响应：

OK
>

收到上述响应后，请输入您想写入的数据，当数据达到参数指定长度后，数据传输开始。

若数据传输成功，则返回：

OK

若数据传输失败，则返回：

ERROR

参数¶

<num>：I2C 端口号，范围：0 ~ 1。
<address>：I2C 从机设备地址：
- 7 位地址：0 ~ 0x7F；
- 10 位地址：第一个字节的前七个位是 1111 0XX，其中最后两位 XX 是 10 位地址的最高两位。例如，如果 10 位地址为 0x2FF (b’1011111111)，那么输入的地址为 0x7AFF (b’111101011111111)。
<length>：I2C 数据长度，范围：1 ~ 2048。

说明¶

I2C 传输超时时间为一秒。

示例¶

AT+DRVI2CWRDATA=0,0x34,10   // I2C0 写入 10 字节数据至地址 0x34

AT+DRVI2CWRBYTES：写入不超过 4 字节的 I2C 数据¶

设置命令¶

命令：

AT+DRVI2CWRBYTES=<num>,<address>,<length>,<data>

响应：

OK

参数¶

<num>：I2C 端口号，范围：0 ~ 1。
<address>：I2C 从机设备地址。
- 7 位地址：0 ~ 0x7F。
- 10 位地址：第一个字节的前七个位是 1111 0XX，其中最后两位 XX 是 10 位地址的最高两位。例如，如果 10 位地址为 0x2FF (b’1011111111)，那么输入的地址为 0x7AFF (b’111101011111111)。
<length>：待写入的 I2C 数据长度，范围：1 ~ 4 字节。
<data>：参数 <length> 指定长度的数据，范围：0 ~ 0xFFFFFFFF。

说明¶

I2C 传输超时时间为一秒。

示例¶

AT+DRVI2CWRBYTES=0,0x34,2,0x1234     // I2C0 写入 2 字节数据 0x1234 至地址 0x34
AT+DRVI2CWRBYTES=0,0x7AFF,2,0x1234   // I2C0 写入 2 字节数据 0x1234 至 10 位地址 0x2FF

// I2C0 写地址 0x34、寄存器地址 0x27，数据为 c0xFF
AT+DRVI2CWRBYTES=0,0x34,2,0x27FF

AT+DRVSPICONFGPIO：配置 SPI GPIO¶

设置命令¶

命令：

AT+DRVSPICONFGPIO=<mosi>,<miso>,<sclk>,<cs>

响应：

OK

参数¶

<mosi>：主出从入信号对应的 GPIO 管脚。
<miso>：主入从出信号对应 GPIO 管脚，若不使用，置位 -1。
<sclk>：SPI 时钟信号对应的 GPIO 管脚。
<cs>：选择从机的信号对应 GPIO 管脚，若不使用，置位 -1。

AT+DRVSPIINIT：初始化 SPI 主机驱动¶

设置命令¶

命令：

AT+DRVSPIINIT=<clock>,<mode>,<cmd_bit>,<addr_bit>,<dma_chan>[,bits_msb]

响应：

OK

参数¶

<clock>：时钟速度，分频数为 80 MHz，单位：Hz，最大值：40 MHz。
<mode>：SPI 模式，范围：0 ~ 3。
<cmd_bit>：命令阶段的默认位数，范围：0 ~ 16。
<addr_bit>：地址阶段的默认位数，范围：0 ~ 64。
<dma_chan>：通道 1 或 2，不需要 DMA 时也可为 0。
<bits_msb>：SPI 数据格式：
- bit0:
  - 0: 先传输 MSB（默认）；
  - 1: 先传输 LSB。
- bit1:
  - 0: 先接收 MSB（默认）；
  - 1: 先接收 LSB。

说明¶

请在 SPI 初始化前配置 SPI GPIO。

示例¶

AT+DRVSPIINIT=102400,0,0,0,0,3 // SPI 时钟：100 kHz；模式：0；命令阶段和地址阶段默认位数均为 0；不使用 DMA；先传输和接收 LSB
OK
AT+DRVSPIINIT=0   // 删除 SPI 驱动
OK

AT+DRVSPIRD：读取 SPI 数据¶

设置命令¶

命令：

AT+DRVSPIRD=<data_len>[,<cmd>,<cmd_len>][,<addr>,<addr_len>]

响应：

+DRVSPIRD:<read data>
OK

参数¶

<data_len>：待读取的 SPI 数据长度，范围：1 ~ 4092 字节。
<cmd>：命令数据，数据长度由 <cmd_len> 参数设定。
<cmd_len>：本次传输中的命令长度，范围：0 ~ 2 字节。
<addr>：命令地址，地址长度由 <addr_len> 参数设定。
<addr_len>：本次传输中地址长度，范围：0 ~ 4 字节。

说明¶

若不使用 DMA，<data_len> 参数每次能够设定的最大值为 64 字节。

示例¶

AT+DRVSPIRD=2  // 读取 2 字节数据
+DRVI2CREAD:ffff
OK

AT+DRVSPIRD=2,0x03,1,0x001000,3  // 读取 2 字节数据，<cmd> 为 0x03，<cmd_len> 为 1 字节，<addr> 为 0x1000，<addr_len> 为 3 字节
+DRVI2CREAD:ffff
OK

AT+DRVSPIWR：写入 SPI 数据¶

设置命令¶

命令：

AT+DRVSPIWR=<data_len>[,<cmd>,<cmd_len>][,<addr>,<addr_len>]

响应：

当 <data_len> 参数值大于 0，AT 返回：

OK
>

收到上述响应后，请输入您想写入的数据，当数据达到参数指定长度后，数据传输开始。

若数据传输成功，AT 返回：

OK

当 <data_len> 参数值为 0 时，也即 AT 只传输命令和地址，不传输 SPI 数据，此时 AT 返回：

OK

参数¶

<data_len>：SPI 数据长度，范围：0 ~ 4092。
<cmd>：命令数据，数据长度由 <cmd_len> 参数设定。
<cmd_len>：本次传输中的命令长度，范围：0 ~ 2 字节。
<addr>：命令地址，地址长度由 <addr_len> 参数设定。
<addr_len>：本次传输中地址长度，范围：0 ~ 4 字节。

说明¶

若不使用 DMA，<data_len> 参数每次能够设定的最大值为 64 字节。

示例¶

AT+DRVSPIWR=2  // 写入 2 字节数据
OK
>              // 开始接收串行数据
OK

AT+DRVSPIWR=0,0x03,1,0x001000,3  // 写入 0 字节数据，<cmd> 为 0x03，<cmd_len> 为 1 字节，<addr> 为 0x1000，<addr_len> 为 3 字节
OK

Web 服务器 AT 命令¶

[English]

AT+WEBSERVER: 启用/禁用通过 Web 服务器配置 Wi-Fi 连接

AT+WEBSERVER: 启用/禁用通过 Web 服务器配置 Wi-Fi 连接¶

设置命令¶

命令：

AT+WEBSERVER=<enable>,<server_port>,<connection_timeout>

响应：

OK

参数¶

<enable>: 启用/禁用 Web 服务器。
- 0: 禁用 Web 服务器并释放相关资源。
- 1: 启用 Web 服务器，您可以通过微信或者浏览器配置 Wi-Fi 连接信息。
<server_port>: Web 服务器端口号。
<connection_timeout>: 每个连接的超时时间。单位：秒。范围：[21,60]。

说明¶

有两种方法可以提供 Web 服务器所需的 HTML 文件。一种是使用 FAT 文件系统，此时需要启用 AT FS 命令。另一种是使用嵌入文件来存储 HTML 文件（默认设置）。
请确保开放的 socket 的最大数目不能小于 12，您可以在 menuconfig 中设置此项 ./build.py menuconfig > Component config > LWIP > Max number of open sockets，然后重新编译工程（参考文档编译 ESP-AT 工程）。
AT 固件默认不支持 Web 服务器 AT 命令（参考文档 see ESP-AT 固件差异），但您可以在 menuconfig 中设置支持 Web 服务器 AT 命令 ./build.py menuconfig > Component config > AT > AT WEB Server command support，然后重新编译工程（参考文档编译 ESP-AT 工程）。
ESP-AT 在 ESP32 和 ESP32-C 系列设备中支持强制门户 (captive portal)，可参考示例。
更多示例可参考文档 Web Server AT 示例。
该命令的实现开源，源码请参考 at/src/at_web_server_cmd.c。
请参考如何实现 OTA 升级获取更多 OTA 命令。

示例¶

// 启用 Web 服务器，端口 80，每个连接的超时时间 50 秒
AT+WEBSERVER=1,80,50

// 禁用 Web 服务器
AT+WEBSERVER=0

用户 AT 命令¶

[English]

AT+USERRAM：操作用户的空闲 RAM
AT+USEROTA：根据指定 URL 升级固件

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+USEROTA：根据指定 URL 升级固件¶

ESP-AT 在运行时，升级到指定 URL 上的新固件。

设置命令¶

功能：

升级到 URL 指定版本的固件

命令：

AT+USEROTA=<url len>

响应：

OK

>

上述响应表示 AT 已准备好接收 URL，此时您可以输入 URL，当 AT 接收到的 URL 长度达到 <url len> 后，返回：

Recv <url len> bytes

AT 输出上述信息之后，升级过程开始。如果升级完成，返回：

OK

如果参数错误或者固件升级失败，返回：

ERROR

参数¶

<url len>：URL 长度。最大值：8192 字节

说明¶

升级速度取决于网络状况。
如果网络条件不佳导致升级失败，AT 将返回 ERROR，请等待一段时间再试。
建议升级 AT 固件后，调用 AT+RESTORE 恢复出厂设置。
AT+USEROTA 支持 HTTP 和 HTTPS。
AT 输出 > 字符后，数据中的特殊字符不需要转义字符进行转义，也不需要以新行结尾（CR-LF）。
当 URL 为 HTTPS 时，不建议 SSL 认证。如果要求 SSL 认证，您必须自行生成 PKI 文件然后将它们下载到对应的分区中，之后在 AT+USEROTA 命令的实现代码中加载证书。对于 PKI 文件请参考如何生成 PKI 文件。对于 AT+USEROTA 命令，可参考 ESP-AT 工程提供的示例 USEROTA。
请参考如何实现 OTA 升级获取更多 OTA 命令。

示例¶

AT+USEROTA=36

OK

>
Recv 36 bytes

OK

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

AT 命令分类
参数信息保存在 flash 中的 AT 命令
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 区域中，因此重启后，会直接使用。

AT+UART_DEF: AT+UART_DEF=115200,8,1,0,3
AT+SAVETRANSLINK: AT+SAVETRANSLINK=1,"192.168.6.10",1001
AT+CWAUTOCONN: AT+CWAUTOCONN=1

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

AT 消息 ¶

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

ESP-AT 响应（被动）

每个输入的 ESP-AT 命令都会返回响应，告诉发送者 ESP-AT 命令的执行结果。响应的最后一条消息必然是 OK 或者 ERROR。

ESP-AT 响应¶
AT 响应	说明
OK	AT 命令处理完毕，返回 OK
ERROR	AT 命令错误或执行过程中发生错误
SEND OK	数据已发送到协议栈（针对于 AT+CIPSEND 和 AT+CIPSENDEX 命令），但不代表数据已经发到对端
SEND FAIL	向协议栈发送数据时发生错误（针对于 AT+CIPSEND 和 AT+CIPSENDEX 命令）
SET OK	URL 已经成功设置（针对于 AT+HTTPURLCFG 命令）
+<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 配对完成

AT 命令示例¶

[English]

TCP-IP AT 示例¶

[English]

本文档主要介绍在 ESP 设备上运行 TCP/IP AT 命令命令的详细示例。

ESP 设备作为 TCP 客户端建立单连接
ESP 设备作为 TCP 服务器建立多连接
远端 IP 地址和端口固定的 UDP 通信
远端 IP 地址和端口可变的 UDP 通信
ESP 设备作为 SSL 客户端建立单连接
ESP 设备作为 SSL 服务器建立多连接
ESP 设备作为 SSL 客户端建立双向认证单连接
ESP 设备作为 SSL 服务器建立双向认证多连接
ESP 设备作为 TCP 客户端，建立单连接，实现 UART Wi-Fi 透传
ESP 设备作为 softAP 在 UDP 传输中实现 UART Wi-Fi 透传

ESP 设备作为 TCP 客户端建立单连接 ¶

设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接到路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。
查询 ESP 设备 IP 地址。

命令：
```
AT+CIPSTA?
```
响应：
```
+CIPSTA:ip:"192.168.3.112"
+CIPSTA:gateway:"192.168.3.1"
+CIPSTA:netmask:"255.255.255.0"

OK
```
说明：
- 您的查询结果可能与上述响应中的不同。
PC 与 ESP 设备连接同一个路由。

在 PC 上使用网络调试工具，创建一个 TCP 服务器。例如 TCP 服务器的 IP 地址为 192.168.3.102，端口为 8080。
ESP 设备作为客户端通过 TCP 连接到 TCP 服务器，服务器 IP 地址为 192.168.3.102，端口为 8080。

命令：
```
AT+CIPSTART="TCP","192.168.3.102",8080
```
响应：
```
CONNECT

OK
```
发送 4 字节数据。

命令：
```
AT+CIPSEND=4
```
响应：
```
OK

>
```
输入 4 字节数据，例如输入数据是 test，之后 AT 将会输出以下信息。
```
Recv 4 bytes

SEND OK
```
说明：
- 若输入的字节数目超过 AT+CIPSEND 命令设定的长度 (n)，则系统会响应 busy p...，并发送数据的前 n 个字节，发送完成后响应 SEND OK。
接收 4 字节数据。

假设 TCP 服务器发送 4 字节的数据（数据为 test），则系统会提示：
```
+IPD,4:test
```

ESP 设备作为 TCP 服务器建立多连接 ¶

当 ESP 设备作为 TCP 服务器时，必须通过 AT+CIPMUX=1 命令使能多连接，因为可能有多个 TCP 客户端连接到 ESP 设备。

以下是 ESP 设备作为 softAP 建立 TCP 服务器的示例；如果是 ESP 设备作为 station，可在连接路由器后按照同样方法建立服务器。

设置 Wi-Fi 模式为 softAP。

命令：
```
AT+CWMODE=2
```
响应：
```
OK
```
使能多连接。

命令：
```
AT+CIPMUX=1
```
响应：
```
OK
```

设置 softAP。

命令：

AT+CWSAP="ESP32_softAP","1234567890",5,3

响应：

OK

查询 softAP 信息。

命令：

AT+CIPAP?

响应：

AT+CIPAP?
+CIPAP:ip:"192.168.4.1"
+CIPAP:gateway:"192.168.4.1"
+CIPAP:netmask:"255.255.255.0"

OK

说明：

您查询到的地址可能与上述响应中的不同。

建立 TCP 服务器，默认端口为 333。

命令：
```
AT+CIPSERVER=1
```
响应：
```
OK
```
PC 连接到 ESP 设备的 softAP。
在 PC 上使用网络调试工具创建一个 TCP 客户端，连接到 ESP 设备创建的 TCP 服务器。
发送 4 字节数据到网络连接 ID 为 0 的链路上。

命令：
```
AT+CIPSEND=0,4
```
响应：
```
OK

>
```
输入 4 字节数据，例如输入数据是 test，之后 AT 将会输出以下信息。
```
Recv 4 bytes

SEND OK
```
说明：
- 若输入的字节数目超过 AT+CIPSEND 命令设定的长度 (n)，则系统会响应 busy p...，并发送数据的前 n 个字节，发送完成后响应 SEND OK。
从网络连接 ID 为 0 的链路上接收 4 字节数据。

假设 TCP 服务器发送 4 字节的数据（数据为 test），则系统会提示：
```
+IPD,0,4:test
```
关闭 TCP 连接。

命令：
```
AT+CIPCLOSE=0
```
响应：
```
0,CLOSED

OK
```

远端 IP 地址和端口固定的 UDP 通信 ¶

设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接到路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。
查询 ESP 设备 IP 地址。

命令：
```
AT+CIPSTA?
```
响应：
```
+CIPSTA:ip:"192.168.3.112"
+CIPSTA:gateway:"192.168.3.1"
+CIPSTA:netmask:"255.255.255.0"

OK
```
说明：
- 您的查询结果可能与上述响应中的不同。
PC 与 ESP 设备连接到同一个路由。

在 PC 上使用网络调试工具，创建一个 UDP 传输。例如 PC 的 IP 地址为 192.168.3.102，端口为 8080。
使能多连接。

命令：
```
AT+CIPMUX=1
```
响应：
```
OK
```
创建 UDP 传输。分配网络连接 ID 为 4，远程 IP 地址为 192.168.3.102，远端端口为 8080，本地端口为 1112，模式为 0。

重要

AT+CIPSTART 命令的参数 mode 决定了 UDP 通信的远端 IP 地址和端口是否固定。若参数为 0，则代表系统会分配一个特定网络连接 ID，以确保通信过程中远端的 IP 地址和端口不会被改变，且数据发送端和数据接收端不会被其它设备代替。

命令：
```
AT+CIPSTART=4,"UDP","192.168.3.102",8080,1112,0
```
响应：
```
4,CONNECT

OK
```
说明：
- "192.168.3.102" 和 8080 为 UDP 传输的远端 IP 地址和远端端口，也就是 PC 建立的 UDP 配置。
- 1112 为 ESP 设备的 UDP 本地端口，您可自行设置，如不设置则为随机值。
- 0 表示 UDP 远端 IP 地址和端口是固定的，不能更改。比如有另外一台 PC 创建了 UDP 端并且向 ESP 设备端口 1112 发送数据，ESP 设备仍然会接收来自 UDP 端口 1112 的数据，如果使用 AT 命令 AT+CIPSEND=4,X，那么数据仍然只会发送到第一台 PC 端。但是如果这个参数未设置为 0，那么数据将会被发送到新的 PC 端。
发送 7 字节数据到网络连接 ID 为 4 的链路上。

命令：
```
AT+CIPSEND=4,7
```
响应：
```
OK

>
```
输入 7 字节数据，例如输入数据是 abcdefg，之后 AT 将会输出以下信息。
```
Recv 7 bytes

SEND OK
```
说明：
- 若输入的字节数目超过 AT+CIPSEND 命令设定的长度 (n)，则系统会响应 busy p...，并发送数据的前 n 个字节，发送完成后响应 SEND OK。
从网络连接 ID 为 4 的链路上接收 4 字节数据。

假设 PC 发送 4 字节的数据（数据为 test），则系统会提示：
```
+IPD,4,4:test
```
关闭网络连接 ID 为 4 的 UDP 连接。

命令：
```
AT+CIPCLOSE=4
```
响应：
```
4,CLOSED

OK
```

远端 IP 地址和端口可变的 UDP 通信 ¶

设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接到路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。
查询 ESP 设备 IP 地址。

命令：
```
AT+CIPSTA?
```
响应：
```
+CIPSTA:ip:"192.168.3.112"
+CIPSTA:gateway:"192.168.3.1"
+CIPSTA:netmask:"255.255.255.0"

OK
```
说明：
- 您的查询结果可能与上述响应中的不同。
PC 与 ESP 设备连接到同一个路由。

在 PC 上使用网络调试工具，创建一个 UDP 传输。例如 IP 地址为 192.168.3.102，端口为 8080。
使能单连接。

命令：
```
AT+CIPMUX=0
```
响应：
```
OK
```
创建 UDP 传输。远程 IP 地址为 192.168.3.102，远端端口为 8080，本地端口为 1112，模式为 2。

命令：
```
AT+CIPSTART="UDP","192.168.3.102",8080,1112,2
```
响应：
```
CONNECT

OK
```
说明：
- "192.168.3.102" 和 8080 为 UDP 传输的远端 IP 地址和远端端口，也就是 PC 建立的 UDP 配置。
- 1112 为 ESP 设备的 UDP 本地端口，您可自行设置，如不设置则为随机值。
- 2 表示当前 UDP 传输建立后，UDP 传输远端信息仍然会更改；UDP 传输的远端信息会自动更改为最近一次与 ESP 设备 UDP 通信的远端 IP 地址和端口。
发送 4 字节数据。

命令：
```
AT+CIPSEND=4
```
响应：
```
OK

>
```
输入 4 字节数据，例如输入数据是 test，之后 AT 将会输出以下信息。
```
Recv 4 bytes

SEND OK
```
说明：
- 若输入的字节数目超过 AT+CIPSEND 命令设定的长度 (n)，则系统会响应 busy p...，并发送数据的前 n 个字节，发送完成后响应 SEND OK。
发送 UDP 包给其它 UDP 远端。例如发送 4 字节数据，远端主机的 IP 地址为 192.168.3.103，远端端口为 1000。

若需要发 UDP 包给其它 UDP 远端，只需指定对方 IP 地址和端口即可。

命令：
```
AT+CIPSEND=4,"192.168.3.103",1000
```
响应：
```
OK

>
```
输入 4 字节数据，例如输入数据是 test，之后 AT 将会输出以下信息。
```
Recv 4 bytes

SEND OK
```
接收 4 字节数据。

假设 PC 发送 4 字节的数据（数据为 test），则系统会提示：
```
+IPD,4:test
```
关闭 UDP 连接。

命令：
```
AT+CIPCLOSE
```
响应：
```
CLOSED

OK
```

ESP 设备作为 SSL 客户端建立单连接 ¶

设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接到路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。
查询 ESP 设备 IP 地址。

命令：
```
AT+CIPSTA?
```
响应：
```
+CIPSTA:ip:"192.168.3.112"
+CIPSTA:gateway:"192.168.3.1"
+CIPSTA:netmask:"255.255.255.0"

OK
```
说明：
- 您的查询结果可能与上述响应中的不同。
PC 与 ESP 设备连接同一个路由。

在 PC 上使用 OpenSSL 命令，创建一个 SSL 服务器。例如 SSL 服务器的 IP 地址为 192.168.3.102，端口为 8070。

命令：

openssl s_server -cert /home/esp-at/components/customized_partitions/raw_data/server_cert/server_cert.crt -key /home/esp-at/components/customized_partitions/raw_data/server_key/server.key -port 8070

响应：

ACCEPT

ESP 设备作为客户端通过 SSL 连接到 SSL 服务器，服务器 IP 地址为 192.168.3.102，端口为 8070。

命令：
```
AT+CIPSTART="SSL","192.168.3.102",8070
```
响应：
```
CONNECT

OK
```
发送 4 字节数据。

命令：
```
AT+CIPSEND=4
```
响应：
```
OK

>
```
输入 4 字节数据，例如输入数据是 test，之后 AT 将会输出以下信息。
```
Recv 4 bytes

SEND OK
```
说明：
- 若输入的字节数目超过 AT+CIPSEND 命令设定的长度 (n)，则系统会响应 busy p...，并发送数据的前 n 个字节，发送完成后响应 SEND OK。
接收 4 字节数据。

假设 TCP 服务器发送 4 字节的数据（数据为 test），则系统会提示：
```
+IPD,4:test
```

ESP 设备作为 SSL 服务器建立多连接 ¶

当 ESP 设备作为 SSL 服务器时，必须通过 AT+CIPMUX=1 命令使能多连接，因为可能有多个客户端连接到 ESP 设备。

以下是 ESP 设备作为 softAP 建立 SSL 服务器的示例；如果是 ESP 设备作为 station，可在连接路由器后，参照本示例中的建立连接 SSL 服务器的相关步骤。

设置 Wi-Fi 模式为 softAP。

命令：
```
AT+CWMODE=2
```
响应：
```
OK
```
使能多连接。

命令：
```
AT+CIPMUX=1
```
响应：
```
OK
```

配置 ESP softAP。

命令：

AT+CWSAP="ESP32_softAP","1234567890",5,3

响应：

OK

查询 softAP 信息。

命令：

AT+CIPAP?

响应：

AT+CIPAP?
+CIPAP:ip:"192.168.4.1"
+CIPAP:gateway:"192.168.4.1"
+CIPAP:netmask:"255.255.255.0"

OK

说明：

您查询到的地址可能与上述响应中的不同。

建立 SSL 服务器，端口为 8070。

命令：
```
AT+CIPSERVER=1,8070,"SSL"
```
响应：
```
OK
```
PC 连接到 ESP 设备的 softAP。
在 PC 上使用 OpenSSL 命令，创建一个 SSL 客户端，连接到 ESP 设备创建的 SSL 服务器。

命令：
```
openssl s_client -host 192.168.4.1 -port 8070
```
ESP 设备上的响应：
```
CONNECT
```
发送 4 字节数据到网络连接 ID 为 0 的链路上。

命令：
```
AT+CIPSEND=0,4
```
响应：
```
OK

>
```
输入 4 字节数据，例如输入数据是 test，之后 AT 将会输出以下信息。
```
Recv 4 bytes

SEND OK
```
说明：
- 若输入的字节数目超过 AT+CIPSEND 命令设定的长度 (n)，则系统会响应 busy p...，并发送数据的前 n 个字节，发送完成后响应 SEND OK。
从网络连接 ID 为 0 的链路上接收 4 字节数据。

假设 SSL 服务器发送 4 字节的数据（数据为 test），则系统会提示：
```
+IPD,0,4:test
```
关闭 SSL 连接。

命令：
```
AT+CIPCLOSE=0
```
响应：
```
0,CLOSED

OK
```

ESP 设备作为 SSL 客户端建立双向认证单连接 ¶

本示例中使用的证书是 esp-at 中默认的证书，您也可以自己生成证书，并烧录，然后您需要将下面的 SSL 服务器证书路径替换为您的证书路径。获取 SSL 证书，请参考 esp-at/tools/README.md 了解如何生成证书 bin 和烧录地址请参考 esp-at/module_config/module_name/at_customize.csv。

设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接到路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。
设置 SNTP 服务器。

命令：
```
AT+CIPSNTPCFG=1,8,"cn.ntp.org.cn","ntp.sjtu.edu.cn"
```
响应：
```
OK
```
说明：
- 您可以根据自己国家的时区设置 SNTP 服务器。
查询 SNTP 时间。

命令：
```
AT+CIPSNTPTIME?
```
响应：
```
+CIPSNTPTIME:Mon Oct 18 20:12:27 2021
OK
```
说明：
- 您可以查询 SNTP 时间与实时时间是否相符来判断您设置的 SNTP 服务器是否生效。
查询 ESP 设备 IP 地址。

命令：
```
AT+CIPSTA?
```
响应：
```
+CIPSTA:ip:"192.168.3.112"
+CIPSTA:gateway:"192.168.3.1"
+CIPSTA:netmask:"255.255.255.0"

OK
```
说明：
- 您的查询结果可能与上述响应中的不同。
PC 与 ESP 设备连接同一个路由。

在 PC 上使用 OpenSSL 命令，创建一个 SSL 服务器。例如 SSL 服务器的 IP 地址为 192.168.3.102，端口为 8070。

命令：

openssl s_server -CAfile /home/esp-at/components/customized_partitions/raw_data/server_ca/server_ca.crt -cert /home/esp-at/components/customized_partitions/raw_data/server_cert/server_cert.crt -key /home/esp-at/components/customized_partitions/raw_data/server_key/server.key -port 8070 -verify_return_error -verify_depth 1 -Verify 1

ESP 设备上的响应：

ACCEPT

说明：

命令中的证书路径可以根据你的证书位置进行调整。

ESP 设备设置 SSL 客户端双向认证配置。

命令：
```
AT+CIPSSLCCONF=3,0,0
```
响应：
```
OK
```
ESP 设备作为客户端通过 SSL 连接到 SSL 服务器，服务器 IP 地址为 192.168.3.102，端口为 8070。

命令：
```
AT+CIPSTART="SSL","192.168.3.102",8070
```
响应：
```
CONNECT

OK
```
发送 4 字节数据。

命令：
```
AT+CIPSEND=4
```
响应：
```
OK

>
```
输入 4 字节数据，例如输入数据是 test，之后 AT 将会输出以下信息。
```
Recv 4 bytes

SEND OK
```
说明：
- 若输入的字节数目超过 AT+CIPSEND 命令设定的长度 (n)，则系统会响应 busy p...，并发送数据的前 n 个字节，发送完成后响应 SEND OK。
接收 4 字节数据。

假设 TCP 服务器发送 4 字节的数据（数据为 test），则系统会提示：
```
+IPD,4:test
```

ESP 设备作为 SSL 服务器建立双向认证多连接 ¶

当 ESP 设备作为 SSL 服务器时，必须通过 AT+CIPMUX=1 命令使能多连接，因为可能有多个客户端连接到 ESP 设备。

以下是 ESP 设备作为 station 建立 SSL 服务器的示例；如果是 ESP 设备作为 softAP，可参考 ESP 设备作为 SSL 服务器建立多连接 示例。

设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接到路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。
查询 ESP 设备 IP 地址。

命令：
```
AT+CIPSTA?
```
响应：
```
+CIPSTA:ip:"192.168.3.112"
+CIPSTA:gateway:"192.168.3.1"
+CIPSTA:netmask:"255.255.255.0"

OK
```
说明：
- 您的查询结果可能与上述响应中的不同。
使能多连接。

命令：
```
AT+CIPMUX=1
```
响应：
```
OK
```
建立 SSL 服务器，端口为 8070。

命令：
```
AT+CIPSERVER=1,8070,"SSL",1
```
响应：
```
OK
```
PC 与 ESP 设备连接同一个路由。

在 PC 上使用 OpenSSL 命令，创建一个 SSL 客户端，连接到 ESP 设备创建的 SSL 服务器。

命令：

openssl s_client -CAfile /home/esp-at/components/customized_partitions/raw_data/client_ca/client_ca_00.crt -cert /home/esp-at/components/customized_partitions/raw_data/client_cert/client_cert_00.crt -key /home/esp-at/components/customized_partitions/raw_data/client_key/client_key_00.key -host 192.168.3.112 -port 8070

ESP 设备上的响应：

0,CONNECT

发送 4 字节数据到网络连接 ID 为 0 的链路上。

命令：
```
AT+CIPSEND=0,4
```
响应：
```
OK

>
```
输入 4 字节数据，例如输入数据是 test，之后 AT 将会输出以下信息。
```
Recv 4 bytes

SEND OK
```
说明：
- 若输入的字节数目超过 AT+CIPSEND 命令设定的长度 (n)，则系统会响应 busy p...，并发送数据的前 n 个字节，发送完成后响应 SEND OK。
从网络连接 ID 为 0 的链路上接收 4 字节数据。

假设 SSL 服务器发送 4 字节的数据（数据为 test），则系统会提示：
```
+IPD,0,4:test
```
关闭 SSL 连接。

命令：
```
AT+CIPCLOSE=0
```
响应：
```
0,CLOSED

OK
```
关闭 SSL 服务端。

命令：
```
AT+CIPSERVER=0
```
响应：
```
OK
```

ESP 设备作为 TCP 客户端，建立单连接，实现 UART Wi-Fi 透传 ¶

设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接到路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。
查询 ESP 设备 IP 地址。

命令：
```
AT+CIPSTA?
```
响应：
```
+CIPSTA:ip:"192.168.3.112"
+CIPSTA:gateway:"192.168.3.1"
+CIPSTA:netmask:"255.255.255.0"

OK
```
说明：
- 您的查询结果可能与上述响应中的不同。
PC 与 ESP 设备连接到同一个路由。

在 PC 上使用网络调试工具，创建一个 TCP 服务器。例如 IP 地址为 192.168.3.102，端口为 8080。
ESP 设备作为客户端通过 TCP 连接到 TCP 服务器，服务器 IP 地址为 192.168.3.102，端口为 8080。

命令：
```
AT+CIPSTART="TCP","192.168.3.102",8080
```
响应：
```
CONNECT

OK
```
使能 UART Wi-Fi 透传模式。

命令：
```
AT+CIPMODE=1
```
响应：
```
OK
```
在透传模式下发送数据。

命令：
```
AT+CIPSEND
```
响应：
```
OK

>
```
停止发送数据

在透传发送数据过程中，若识别到单独的一包数据 +++，则系统会退出透传发送。此时请至少等待 1 秒，再发下一条 AT 命令。请注意，如果直接用键盘打字输入 +++，有可能因时间太慢而不能被识别为连续的三个 +。更多介绍请参考 [仅适用透传模式] +++。

重要

使用 +++ 可退出透传发送数据，回到正常 AT 命令模式，此时 TCP 连接仍然有效。您也可以使用 AT+CIPSEND 命令恢复透传。
退出 UART Wi-Fi 透传模式。

命令：
```
AT+CIPMODE=0
```
响应：
```
OK
```
关闭 TCP 连接。

命令：
```
AT+CIPCLOSE
```
响应：
```
CLOSED

OK
```

ESP 设备作为 softAP 在 UDP 传输中实现 UART Wi-Fi 透传 ¶

设置 Wi-Fi 模式为 softAP。

命令：
```
AT+CWMODE=2
```
响应：
```
OK
```

设置 softAP。

命令：

AT+CWSAP="ESP32_softAP","1234567890",5,3

响应：

OK

PC 连接到 ESP 设备的 softAP。
创建一个 UDP 端点。

在 PC 上使用网络调试助手，创建一个 UDP 传输。例如 PC 端 IP 地址为 192.168.4.2，端口为 8080。
ESP 设备与 PC 对应端口建立固定对端 IP 地址和端口的 UDP 传输。远程 IP 地址为 192.168.4.2，远端端口为 8080，本地端口为 2233，模式为 0。

命令：
```
AT+CIPSTART="UDP","192.168.4.2",8080,2233,0
```
响应：
```
CONNECT

OK
```
使能 UART Wi-Fi 透传模式。

命令：
```
AT+CIPMODE=1
```
响应：
```
OK
```
在透传模式下发送数据。

命令：
```
AT+CIPSEND
```
响应：
```
OK

>
```
停止发送数据

在透传发送数据过程中，若识别到单独的一包数据 +++，则系统会退出透传发送。此时请至少等待 1 秒，再发下一条 AT 命令。请注意，如果直接用键盘打字输入 +++，有可能因时间太慢而不能被识别为连续的三个 +。更多介绍请参考 [仅适用透传模式] +++。

重要

使用 +++ 可退出透传发送数据，回到正常 AT 命令模式，此时 TCP 连接仍然有效。您也可以使用 AT+CIPSEND 命令恢复透传。
退出 UART Wi-Fi 透传模式。

命令：
```
AT+CIPMODE=0
```
响应：
```
OK
```
关闭 TCP 连接。

命令：
```
AT+CIPCLOSE
```
响应：
```
CLOSED

OK
```

Bluetooth LE AT 示例¶

[English]

本文档主要介绍 Bluetooth® Low Energy AT 命令集的使用方法，并提供在 ESP 设备上运行这些命令的详细示例。

简介
Bluetooth LE 客户端读写服务特征值
Bluetooth LE 服务端读写服务特征值
Bluetooth LE 连接加密
两个 ESP32 开发板之间建立 SPP 连接，以及在 UART-Bluetooth LE 透传模式下传输数据
ESP32 与手机建立 SPP 连接，以及在 UART-Bluetooth LE 透传模式下传输数据

简介 ¶

ESP-AT 当前仅支持 Bluetooth LE 4.2 协议规范，本文档中的描述仅适用于 Bluetooth LE protocol 4.2 协议规范。请参考核心规范 4.2 获取更多信息。

Bluetooth LE 协议架构¶

Bluetooth LE 协议栈从下至上分为几个层级：Physical Layer (PHY)、Link Layer (LL)、Host Controller Interface (HCI)、Logical Link Control and Adaptation Protocol Layer (L2CAP)、Attribute Protocol (ATT)、Security Manager Protocol (SMP)、Generic Attribute Profile (GATT)、Generic Access Profile (GAP)。

PHY：PHY 层主要负责在物理信道上发送和接收信息包。Bluetooth LE 使用 40 个射频信道。频率范围：2402 MHz 到 2480 MHz。
LL：LL 层主要负责创建、修改和释放逻辑链路（以及，如果需要，它们相关的逻辑传输），以及与设备之间的物理链路相关的参数的更新。它控制链路层状态机处于 准备、广播、监听/扫描、发起连接、已连接 五种状态之一。
HCI：HCI 层向主机和控制器提供一个标准化的接口。该层可以由软件 API 实现或者使用硬件接口 UART、SPI、USB 来控制。
L2CAP：L2CAP 层负责对主机和协议栈之间交换的数据进行协议复用能力、分段和重组操作。
ATT：ATT 层实现了属性服务器和属性客户端之间的点对点协议。ATT 客户端向 ATT 服务端发送命令、请求和确认。ATT 服务端向客户端发送响应、通知和指示。
SMP：SMP 层用于生成加密密钥和身份密钥。SMP 还管理加密密钥和身份密钥的存储，并负责生成随机地址并将随机地址解析为已知设备身份。
GATT：GATT 层表示属性服务器和可选的属性客户端的功能。该配置文件描述了属性服务器中使用的服务、特征和属性的层次结构。该层提供用于发现、读取、写入和指示服务特性和属性的接口。
GAP：GAP 层代表所有蓝牙设备通用的基本功能，例如传输、协议和应用程序配置文件使用的模式和访问程序。GAP 服务包括设备发现、连接模式、安全、身份验证、关联模型和服务发现。

Bluetooth LE 角色划分¶

在 Bluetooth LE 协议栈中不同的层级有不同的角色划分。这些角色划分互不影响。

LL：设备可以划分为 主机 和 从机，从机广播，主机可以发起连接。
GAP：定义了 4 种特定角色：广播者、观察者、外围设备 和 中心设备。
GATT：设备可以分为 服务端 和 客户端。

重要

本文档中描述的 Bluetooth LE 服务端 和 Bluetooth LE 客户端 都是 GATT 层角色。
当前，ESP-AT 支持 Bluetooth LE 服务端 和 Bluetooth LE 客户端 同时存在。
不论 ESP-AT 初始化为 Bluetooth LE 服务端还是 Bluetooth LE 客户端，同时连接的最大设备数量为 3。

GATT 其实是一种属性传输协议，简单的讲可以认为是一种属性传输的应用层协议。这个属性的结构非常简单。它由 服务 组成，每个服务由不同数量的 特征 组成，每个 特征 又由很多其它的元素组成。

GATT 服务端 和 GATT 客户端 这两种角色存在于 Bluetooth LE 连接建立之后。GATT 服务器存储通过属性协议传输的数据，并接受来自 GATT 客户端的属性协议请求、命令和确认。简而言之，提供数据的一端称为 GATT 服务端，访问数据的一端称为 GATT 客户端。

重要

ESP32 Bluetooth LE 服户端需烧录 ble_data.bin 文件到 flash 中，用以提供 Bluetooth LE 服务。
- 如何生成 ble_data.bin 文件，请参考文档自定义 Bluetooth LE Services 工具。
- ble_data.bin 文件的烧录地址，见 at_customize.csv 中 ble_data 对应的地址，或者在文件 build/download.config 中记录的地址。

Bluetooth LE 客户端读写服务特征值 ¶

以下示例同时使用两块 ESP32 开发板，其中一块作为 Bluetooth LE 服务端（只作为 Bluetooth LE 服务端角色），另一块作为 Bluetooth LE 客户端（只作为 Bluetooth LE 客户端角色）。这个例子展示了应如何使用 AT 命令建立 Bluetooth LE 连接，完成数据通信。

重要

在以下步骤中以 ESP32 Bluetooth LE 服务端 开头的操作只需要在 ESP32 Bluetooth LE 服务端执行即可，以 ESP32 Bluetooth LE 客户端 开头的操作只需要在 ESP32 Bluetooth LE 客户端执行即可。

初始化 Bluetooth LE 功能。

ESP32 Bluetooth LE 服务端：

命令：
```
AT+BLEINIT=2
```
响应：
```
OK
```
ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLEINIT=1
```
响应：
```
OK
```
ESP32 蓝牙 LE 服务器获取其 MAC 地址。

命令：
```
AT+BLEADDR?
```
响应：
```
+BLEADDR:"24:0a:c4:d6:e4:46"
OK
```
说明：
- 您查询到的地址可能与上述响应中的不同，请记住您的地址，下面的步骤中会用到。
ESP32 Bluetooth LE 服务端创建服务。

命令：
```
AT+BLEGATTSSRVCRE
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端开启服务。

命令：
```
AT+BLEGATTSSRVSTART
```
响应：
```
OK
```

ESP32 Bluetooth LE 服务端发现服务特征。

命令：

AT+BLEGATTSCHAR?

响应：

+BLEGATTSCHAR:"char",1,1,0xC300,0x02
+BLEGATTSCHAR:"desc",1,1,1,0x2901
+BLEGATTSCHAR:"char",1,2,0xC301,0x02
+BLEGATTSCHAR:"desc",1,2,1,0x2901
+BLEGATTSCHAR:"char",1,3,0xC302,0x08
+BLEGATTSCHAR:"desc",1,3,1,0x2901
+BLEGATTSCHAR:"char",1,4,0xC303,0x04
+BLEGATTSCHAR:"desc",1,4,1,0x2901
+BLEGATTSCHAR:"char",1,5,0xC304,0x08
+BLEGATTSCHAR:"char",1,6,0xC305,0x10
+BLEGATTSCHAR:"desc",1,6,1,0x2902
+BLEGATTSCHAR:"char",1,7,0xC306,0x20
+BLEGATTSCHAR:"desc",1,7,1,0x2902
+BLEGATTSCHAR:"char",1,8,0xC307,0x02
+BLEGATTSCHAR:"desc",1,8,1,0x2901
+BLEGATTSCHAR:"char",2,1,0xC400,0x02
+BLEGATTSCHAR:"desc",2,1,1,0x2901
+BLEGATTSCHAR:"char",2,2,0xC401,0x02
+BLEGATTSCHAR:"desc",2,2,1,0x2901

OK

ESP32 Bluetooth LE 服务端开始广播，之后 ESP32 Bluetooth LE 客户端开始扫描并且持续 3 秒钟。

ESP32 Bluetooth LE 服务端：

命令：
```
AT+BLEADVSTART
```
响应：
```
OK
```
ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLESCAN=1,3
```
响应：
```
OK
+BLESCAN:"5b:3b:6c:51:90:49",-87,02011a020a0c0aff4c001005071c3024dc,,1
+BLESCAN:"c4:5b:be:93:ec:66",-84,0201060303111809095647543147572d58020a03,,0
+BLESCAN:"24:0a:c4:d6:e4:46",-29,,,0
```
说明：
- 您的扫描结果可能与上述响应中的不同。
建立 Bluetooth LE 连接。

ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLECONN=0,"24:0a:c4:d6:e4:46"
```
响应：
```
+BLECONN:0,"24:0a:c4:d6:e4:46"

OK
```
说明：
- 输入上述命令时，请使用您的 ESP Bluetooth LE 服务端地址。
- 如果 Bluetooth LE 连接成功，则会提示 +BLECONN:0,"24:0a:c4:d6:e4:46。
- 如果 Bluetooth LE 连接失败，则会提示 +BLECONN:0,-1。
ESP32 Bluetooth LE 客户端发现服务。

命令：
```
AT+BLEGATTCPRIMSRV=0
```
响应：
```
 +BLEGATTCPRIMSRV:0,1,0x1801,1
 +BLEGATTCPRIMSRV:0,2,0x1800,1
 +BLEGATTCPRIMSRV:0,3,0xA002,1
 +BLEGATTCPRIMSRV:0,4,0xA003,1

OK
```
说明：
- ESP32 Bluetooth LE 客户端查询服务的结果，比 ESP32 Bluetooth LE 服户端查询服务的结果多两个默认服务（UUID: 0x1800 和 0x1801），这是正常现象。正因如此，对于同一服务，ESP32 Bluetooth LE 客户端查询的 <srv_index> 值等于 ESP32 Bluetooth LE 服户端查询的 <srv_index> 值 + 2。例如上述示例中的服务 0xA002，当前在 ESP32 Bluetooth LE 客户端查询到的 <srv_index> 为 3，如果在 ESP32 Bluetooth LE 服户端通过 AT+BLEGATTSSRV? 命令查询，则 <srv_index> 为 1。

ESP32 Bluetooth LE 客户端发现特征值。

命令：

AT+BLEGATTCCHAR=0,3

响应：

+BLEGATTCCHAR:"char",0,3,1,0xC300,0x02
+BLEGATTCCHAR:"desc",0,3,1,1,0x2901
+BLEGATTCCHAR:"char",0,3,2,0xC301,0x02
+BLEGATTCCHAR:"desc",0,3,2,1,0x2901
+BLEGATTCCHAR:"char",0,3,3,0xC302,0x08
+BLEGATTCCHAR:"desc",0,3,3,1,0x2901
+BLEGATTCCHAR:"char",0,3,4,0xC303,0x04
+BLEGATTCCHAR:"desc",0,3,4,1,0x2901
+BLEGATTCCHAR:"char",0,3,5,0xC304,0x08
+BLEGATTCCHAR:"char",0,3,6,0xC305,0x10
+BLEGATTCCHAR:"desc",0,3,6,1,0x2902
+BLEGATTCCHAR:"char",0,3,7,0xC306,0x20
+BLEGATTCCHAR:"desc",0,3,7,1,0x2902
+BLEGATTCCHAR:"char",0,3,8,0xC307,0x02
+BLEGATTCCHAR:"desc",0,3,8,1,0x2901

OK

ESP32 Bluetooth LE 客户端读取一个特征值。

命令：
```
AT+BLEGATTCRD=0,3,1
```
响应：
```
+BLEGATTCRD:0,1,0

OK
```
说明：
- 请注意目标特征值必须要有读权限。
- 如果 ESP32 Bluetooth LE 客户端读取特征成功，ESP32 Bluetooth LE 服务端则会提示 +READ:0,"7c:df:a1:b3:8d:de"。
ESP32 Bluetooth LE 客户端写一个特征值。

命令：
```
AT+BLEGATTCWR=0,3,3,,2
```
响应：
```
>
```
符号 > 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 <length> 的值时，执行写入操作。
```
OK
```
说明：
- 如果 ESP32 Bluetooth LE 客户端写特征描述符成功，ESP32 Bluetooth LE 服务端则会提示 +WRITE:<conn_index>,<srv_index>,<char_index>,[<desc_index>],<len>,<value>。
Indicate 一个特征值。

ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLEGATTCWR=0,3,7,1,2
```
响应：
```
>
```
符号 > 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 <length> 的值时，执行写入操作。

为了接收 ESP32 Bluetooth LE 服务端发送过来的数据（通过 notify 方式或者 indicate 方式），ESP32 Bluetooth LE 客户端需要提前向服务端注册。对于 notify 方式，需要写入值 0x0001，对于 indicate 方式，需要写入值 0x0002。在本例中写入 0x0002 来使用 indicate 方式。
```
OK
```
说明：
- 如果 ESP32 Bluetooth LE 客户端写特征描述符成功，ESP32 Bluetooth LE 服务端则会提示 +WRITE:<conn_index>,<srv_index>,<char_index>,<desc_index>,<len>,<value>。
ESP32 Bluetooth LE 服务端：

命令：
```
AT+BLEGATTSIND=0,1,7,3
```
响应：
```
>
```
符号 > 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 <length> 的值时，执行 indicate 操作。
```
OK
```
说明：
- 如果 ESP32 Bluetooth LE 客户端接收到 indication, 则会提示 +INDICATE:<conn_index>,<srv_index>,<char_index>,<len>,<value>。
- 对于同一服务，ESP32 Bluetooth LE 客户端的 <srv_index> 值等于 ESP32 Bluetooth LE 服户端的 <srv_index> 值 + 2，这是正常现象。
- 对于服务中特征的权限，您可参考文档如何自定义低功耗蓝牙服务。

Bluetooth LE 服务端读写服务特征值 ¶

以下示例同时使用两块 ESP32 开发板，其中一块作为 Bluetooth LE 服务端（只作为 Bluetooth LE 服务端角色），另一块作为 Bluetooth LE 客户端（只作为 Bluetooth LE 客户端角色）。这个例子展示了应如何建立 Bluetooth LE 连接，以及服务端读写服务特征值和客户端设置，notify 服务特征值。

重要

步骤中以 ESP32 Bluetooth LE 服务端 开头的操作只需要在 ESP32 Bluetooth LE 服务端执行即可，以 ESP32 Bluetooth LE 客户端 开头的操作只需要在 ESP32 Bluetooth LE 客户端执行即可。

初始化 Bluetooth LE 功能。

ESP32 Bluetooth LE 服务端：

命令：
```
AT+BLEINIT=2
```
响应：
```
OK
```
ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLEINIT=1
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端创建服务。

命令：
```
AT+BLEGATTSSRVCRE
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端开启服务。

命令：
```
AT+BLEGATTSSRVSTART
```
响应：
```
OK
```
ESP32 蓝牙 LE 服务器获取其 MAC 地址。

命令：
```
AT+BLEADDR?
```
响应：
```
+BLEADDR:"24:0a:c4:d6:e4:46"
OK
```
说明：
- 您查询到的地址可能与上述响应中的不同，请记住您的地址，下面的步骤中会用到。

设置 Bluetooth LE 广播数据。

命令：

AT+BLEADVDATA="0201060A09457370726573736966030302A0"

响应：

OK

ESP32 Bluetooth LE 服务端开始广播。

命令：
```
AT+BLEADVSTART
```
响应：
```
OK
```
ESP32 Bluetooth LE 客户端创建服务。

命令：
```
AT+BLEGATTSSRVCRE
```
响应：
```
OK
```
ESP32 Bluetooth LE 客户端开启服务。

命令：
```
AT+BLEGATTSSRVSTART
```
响应：
```
OK
```
ESP32 Bluetooth LE 客户端获取 Bluetooth LE 地址。

命令：
```
AT+BLEADDR?
```
响应：
```
+BLEADDR:"24:0a:c4:03:a7:4e"
OK
```
说明：
- 您查询到的地址可能与上述响应中的不同，请记住您的地址，下面的步骤中会用到。

ESP32 Bluetooth LE 客户端开始扫描，持续 3 秒。

命令：

AT+BLESCAN=1,3

响应：

OK
+BLESCAN:"24:0a:c4:d6:e4:46",-78,0201060a09457370726573736966030302a0,,0
+BLESCAN:"45:03:cb:ac:aa:a0",-62,0201060aff4c001005441c61df7d,,1
+BLESCAN:"24:0a:c4:d6:e4:46",-26,0201060a09457370726573736966030302a0,,0

说明：

您的扫描结果可能与上述响应中的不同。

建立 the Bluetooth LE 连接。

ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLECONN=0,"24:0a:c4:d6:e4:46"
```
响应：
```
+BLECONN:0,"24:0a:c4:d6:e4:46"

OK
```
说明：
- 输入上述命令时，请使用您的 ESP Bluetooth LE 服务端地址。
- 如果 Bluetooth LE 连接成功，则会提示 +BLECONN:0,"24:0a:c4:d6:e4:46。
- 如果 Bluetooth LE 连接失败，则会提示 +BLECONN:0,-1。

ESP32 Bluetooth LE 服务端：
命令：
AT+BLECONN=0,"24:0a:c4:03:a7:4e"
响应：
+BLECONN:0,"24:0a:c4:03:a7:4e"

OK
说明：

输入上述命令时，请使用您的 ESP Bluetooth LE 客户端地址。

如果 Bluetooth LE 连接成功，则会提示 OK，不会提示 +BLECONN:0,"24:0a:c4:03:a7:4e。

如果 Bluetooth LE 连接失败，则会提示 ERROR，不会提示 +BLECONN:0,-1。

ESP32 Bluetooth LE 客户端查询本地服务。

命令：

AT+BLEGATTSSRV?

响应：

+BLEGATTSSRV:1,1,0xA002,1
+BLEGATTSSRV:2,1,0xA003,1

OK

ESP32 Bluetooth LE 客户端发现本地特征。

命令：

AT+BLEGATTSCHAR?

响应：

+BLEGATTSCHAR:"char",1,1,0xC300,0x02
+BLEGATTSCHAR:"desc",1,1,1,0x2901
+BLEGATTSCHAR:"char",1,2,0xC301,0x02
+BLEGATTSCHAR:"desc",1,2,1,0x2901
+BLEGATTSCHAR:"char",1,3,0xC302,0x08
+BLEGATTSCHAR:"desc",1,3,1,0x2901
+BLEGATTSCHAR:"char",1,4,0xC303,0x04
+BLEGATTSCHAR:"desc",1,4,1,0x2901
+BLEGATTSCHAR:"char",1,5,0xC304,0x08
+BLEGATTSCHAR:"char",1,6,0xC305,0x10
+BLEGATTSCHAR:"desc",1,6,1,0x2902
+BLEGATTSCHAR:"char",1,7,0xC306,0x20
+BLEGATTSCHAR:"desc",1,7,1,0x2902
+BLEGATTSCHAR:"char",1,8,0xC307,0x02
+BLEGATTSCHAR:"desc",1,8,1,0x2901
+BLEGATTSCHAR:"char",2,1,0xC400,0x02
+BLEGATTSCHAR:"desc",2,1,1,0x2901
+BLEGATTSCHAR:"char",2,2,0xC401,0x02
+BLEGATTSCHAR:"desc",2,2,1,0x2901

OK

ESP32 Bluetooth LE 服务端发现对端服务。

命令：
```
AT+BLEGATTCPRIMSRV=0
```
响应：
```
 +BLEGATTCPRIMSRV:0,1,0x1801,1
 +BLEGATTCPRIMSRV:0,2,0x1800,1
 +BLEGATTCPRIMSRV:0,3,0xA002,1
 +BLEGATTCPRIMSRV:0,4,0xA003,1

OK
```
说明：
- ESP32 Bluetooth LE 服务端查询服务的结果，比 ESP32 Bluetooth LE 客户端查询服务的结果多两个默认服务（UUID: 0x1800 和 0x1801）。正因如此，对于同一服务，ESP32 Bluetooth LE 服务端查询的 <srv_index> 值等于 ESP32 Bluetooth LE 客户端查询的 <srv_index> 值 + 2。例如，上述示例中的服务 0xA002，当前在 ESP32 Bluetooth LE 服务端查询到的 <srv_index> 为 3，如果在 ESP32 Bluetooth LE 服务端通过 AT+BLEGATTSSRV? 命令查询，则 <srv_index> 为 1。

ESP32 Bluetooth LE 服务端发现对端特征。

命令：

AT+BLEGATTCCHAR=0,3

响应：

+BLEGATTCCHAR:"char",0,3,1,0xC300,0x02
+BLEGATTCCHAR:"desc",0,3,1,1,0x2901
+BLEGATTCCHAR:"char",0,3,2,0xC301,0x02
+BLEGATTCCHAR:"desc",0,3,2,1,0x2901
+BLEGATTCCHAR:"char",0,3,3,0xC302,0x08
+BLEGATTCCHAR:"desc",0,3,3,1,0x2901
+BLEGATTCCHAR:"char",0,3,4,0xC303,0x04
+BLEGATTCCHAR:"desc",0,3,4,1,0x2901
+BLEGATTCCHAR:"char",0,3,5,0xC304,0x08
+BLEGATTCCHAR:"char",0,3,6,0xC305,0x10
+BLEGATTCCHAR:"desc",0,3,6,1,0x2902
+BLEGATTCCHAR:"char",0,3,7,0xC306,0x20
+BLEGATTCCHAR:"desc",0,3,7,1,0x2902
+BLEGATTCCHAR:"char",0,3,8,0xC307,0x02
+BLEGATTCCHAR:"desc",0,3,8,1,0x2901

OK

ESP32 Bluetooth LE 客户端设置服务特征值。

选择支持写操作的服务特征（characteristic）去设置服务特征值。

命令：
```
AT+BLEGATTSSETATTR=1,8,,1
```
响应：
```
>
```
命令：
```
写入一个字节 ``9``
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端读服务特征值。

命令：
```
AT+BLEGATTCRD=0,3,8,
```
响应：
```
+BLEGATTCRD:0,1,9

OK
```
ESP32 Bluetooth LE 服务端写服务特征值。

选择支持写操作的服务特性写入特性。

命令：
```
AT+BLEGATTCWR=0,3,6,1,2
```
响应：
```
>
```
命令：
```
写入2个字节 ``12``
```
响应：
```
OK
```
说明：
- 如果 Bluetooth LE 服务端写服务特征值成功后，Bluetooth LE 客户端则会提示 +WRITE:0,1,6,1,2,12。
ESP32 Bluetooth LE 客户端 notify 服务特征值

命令：
```
AT+BLEGATTSNTFY=0,1,6,10
```
响应：
```
>
```
命令：
```
写入 ``1234567890`` 10个字节
```
响应：
```
OK
```
说明：
- 如果 ESP32 Bluetooth LE 客户端 notify 服务特征值给服务端成功，Bluetooth LE 服务端则会提示 +NOTIFY:0,3,6,10,1234567890。

Bluetooth LE 连接加密 ¶

以下示例同时使用两块 ESP32 开发板，其中一块作为 Bluetooth LE 服务端（只作为 Bluetooth LE 服务端角色），另一块作为 Bluetooth LE 客户端（只作为 Bluetooth LE 客户端角色）。这个例子展示了怎样加密 Bluetooth LE 连接。

重要

在以下步骤中以 ESP32 Bluetooth LE 服务端 开头的操作只需要在 ESP32 Bluetooth LE 服务端执行即可，以 ESP32 Bluetooth LE 客户端 开头的操作只需要在 ESP32 Bluetooth LE 客户端执行即可。
加密 和 绑定 是两个不同的概念。绑定 只是加密成功后在本地存储了一个长期的密钥。
ESP-AT 最多允许绑定 10 个设备。

初始化 Bluetooth LE 功能。

ESP32 Bluetooth LE 服务端：

命令：
```
AT+BLEINIT=2
```
响应：
```
OK
```
ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLEINIT=1
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端获取 Bluetooth LE 地址。

命令：
```
AT+BLEADDR?
```
响应：
```
+BLEADDR:"24:0a:c4:d6:e4:46"
OK
```
说明：
- 您查询到的地址可能与上述响应中的不同，请记住您的地址，下面的步骤中会用到。
ESP32 Bluetooth LE 服务端创建服务。

命令：
```
AT+BLEGATTSSRVCRE
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端开启服务。

命令：
```
AT+BLEGATTSSRVSTART
```
响应：
```
OK
```

ESP32 Bluetooth LE 服务端发现服务特征。

命令：

AT+BLEGATTSCHAR?

响应：

+BLEGATTSCHAR:"char",1,1,0xC300,0x02
+BLEGATTSCHAR:"desc",1,1,1,0x2901
+BLEGATTSCHAR:"char",1,2,0xC301,0x02
+BLEGATTSCHAR:"desc",1,2,1,0x2901
+BLEGATTSCHAR:"char",1,3,0xC302,0x08
+BLEGATTSCHAR:"desc",1,3,1,0x2901
+BLEGATTSCHAR:"char",1,4,0xC303,0x04
+BLEGATTSCHAR:"desc",1,4,1,0x2901
+BLEGATTSCHAR:"char",1,5,0xC304,0x08
+BLEGATTSCHAR:"char",1,6,0xC305,0x10
+BLEGATTSCHAR:"desc",1,6,1,0x2902
+BLEGATTSCHAR:"char",1,7,0xC306,0x20
+BLEGATTSCHAR:"desc",1,7,1,0x2902
+BLEGATTSCHAR:"char",1,8,0xC307,0x02
+BLEGATTSCHAR:"desc",1,8,1,0x2901
+BLEGATTSCHAR:"char",2,1,0xC400,0x02
+BLEGATTSCHAR:"desc",2,1,1,0x2901
+BLEGATTSCHAR:"char",2,2,0xC401,0x02
+BLEGATTSCHAR:"desc",2,2,1,0x2901

OK

ESP32 Bluetooth LE 服务端开始广播，之后 ESP32 Bluetooth LE 客户端开始扫描并且持续 3 秒钟。

ESP32 Bluetooth LE 服务端：

命令：
```
AT+BLEADVSTART
```
响应：
```
OK
```
ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLESCAN=1,3
```
响应：
```
OK
+BLESCAN:"5b:3b:6c:51:90:49",-87,02011a020a0c0aff4c001005071c3024dc,,1
+BLESCAN:"c4:5b:be:93:ec:66",-84,0201060303111809095647543147572d58020a03,,0
+BLESCAN:"24:0a:c4:d6:e4:46",-29,,,0
```
说明：
- 您的扫描结果可能与上述响应中的不同。
建立 Bluetooth LE 连接。

ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLECONN=0,"24:0a:c4:d6:e4:46"
```
响应：
```
+BLECONN:0,"24:0a:c4:d6:e4:46"

OK
```
说明：
- 输入上述命令时，请使用您的 ESP Bluetooth LE 服务端地址。
- 如果 Bluetooth LE 连接成功，则会提示 +BLECONN:0,"24:0a:c4:d6:e4:46。
- 如果 Bluetooth LE 连接失败，则会提示 +BLECONN:0,-1。
ESP32 Bluetooth LE 客户端发现服务。

命令：
```
AT+BLEGATTCPRIMSRV=0
```
响应：
```
 +BLEGATTCPRIMSRV:0,1,0x1801,1
 +BLEGATTCPRIMSRV:0,2,0x1800,1
 +BLEGATTCPRIMSRV:0,3,0xA002,1
 +BLEGATTCPRIMSRV:0,4,0xA003,1

OK
```
说明：
- ESP32 Bluetooth LE 客户端查询服务的结果，比 ESP32 Bluetooth LE 服户端查询服务的结果多两个默认服务（UUID: 0x1800 和 0x1801），这是正常现象。正因如此，对于同一服务，ESP32 Bluetooth LE 客户端查询的 <srv_index> 值等于 ESP32 Bluetooth LE 服户端查询的 <srv_index> 值 + 2。例如上述示例中的服务 0xA002，当前在 ESP32 Bluetooth LE 客户端查询到的 <srv_index> 为 3，如果在 ESP32 Bluetooth LE 服户端通过 AT+BLEGATTSSRV? 命令查询，则 <srv_index> 为 1。

ESP32 Bluetooth LE 客户端发现特征值。

命令：

AT+BLEGATTCCHAR=0,3

响应：

+BLEGATTCCHAR:"char",0,3,1,0xC300,0x02
+BLEGATTCCHAR:"desc",0,3,1,1,0x2901
+BLEGATTCCHAR:"char",0,3,2,0xC301,0x02
+BLEGATTCCHAR:"desc",0,3,2,1,0x2901
+BLEGATTCCHAR:"char",0,3,3,0xC302,0x08
+BLEGATTCCHAR:"desc",0,3,3,1,0x2901
+BLEGATTCCHAR:"char",0,3,4,0xC303,0x04
+BLEGATTCCHAR:"desc",0,3,4,1,0x2901
+BLEGATTCCHAR:"char",0,3,5,0xC304,0x08
+BLEGATTCCHAR:"char",0,3,6,0xC305,0x10
+BLEGATTCCHAR:"desc",0,3,6,1,0x2902
+BLEGATTCCHAR:"char",0,3,7,0xC306,0x20
+BLEGATTCCHAR:"desc",0,3,7,1,0x2902
+BLEGATTCCHAR:"char",0,3,8,0xC307,0x02
+BLEGATTCCHAR:"desc",0,3,8,1,0x2901

OK

设置加密参数。设置 auth_req 为 SC_MITM_BOND，服务端的 iocap 为 KeyboardOnly，客户端的 iocap 为 KeyboardDisplay，key_size 为 16，init_key 为 3, rsp_key 为 3。

ESP32 Bluetooth LE 服务端：

命令：
```
AT+BLESECPARAM=13,2,16,3,3
```
响应：
```
OK
```
ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLESECPARAM=13,4,16,3,3
```
响应：
```
OK
```
说明：
- 在本例中，ESP32 Bluetooth LE 服务端输入配对码，ESP32 Bluetooth LE 客户端显示配对码。
- ESP-AT 支持 Legacy Pairing 和 Secure Connections 两种加密方式，但后者有更高级别的优先级。如果对端也支持 Secure Connections，则会采用 Secure Connections 方式加密。
ESP32 Bluetooth LE 客户端发起加密请求。

命令：
```
AT+BLEENC=0,3
```
响应：
```
OK
```
说明：

如果 ESP32 Bluetooth LE 服务端成功接收到加密请求，ESP32 Bluetooth LE 服务端则会提示 +BLESECREQ:0。
ESP32 Bluetooth LE 服务端响应配对请求。

命令：
```
AT+BLEENCRSP=0,1
```
响应：
```
OK
```
说明：
- 如果 ESP32 Bluetooth LE 客户端成功收到配对响应，则 ESP32 Bluetooth LE 客户端将会产生一个 6 位的配对码。
- 在本例中，ESP32 Bluetooth LE 客户端则会提示 +BLESECNTFYKEY:0,793718。配对码为 793718。
ESP32 Bluetooth LE 客户端回复配对码。

命令：
```
AT+BLEKEYREPLY=0,793718
```
响应：
```
OK
```
执行这个命令之后，在 ESP32 Bluetooth LE 服务端和 ESP32 Bluetooth LE 客户端会有一些对应信息提示。

ESP32 Bluetooth LE 服务端：
```
+BLESECKEYTYPE:0,16
+BLESECKEYTYPE:0,1
+BLESECKEYTYPE:0,32
+BLESECKEYTYPE:0,2
+BLEAUTHCMPL:0,0
```
ESP32 Bluetooth LE 客户端：
```
+BLESECNTFYKEY:0,793718
+BLESECKEYTYPE:0,2
+BLESECKEYTYPE:0,16
+BLESECKEYTYPE:0,1
+BLESECKEYTYPE:0,32
+BLEAUTHCMPL:0,0
```
您可以忽略以 +BLESECKEYTYPE 开头的信息。信息 +BLEAUTHCMPL:0,0 中的第二个参数为 0 表示加密成功，为 1 表示加密失败。

两个 ESP32 开发板之间建立 SPP 连接，以及在 UART-Bluetooth LE 透传模式下传输数据 ¶

以下示例同时使用两块 ESP32 开发板，其中一块作为 Bluetooth LE 服务端（只作为 Bluetooth LE 服务端角色），另一块作为 Bluetooth LE 客户端（只作为 Bluetooth LE 客户端角色）。这个例子展示了应如何建立 Bluetooth LE 连接，以及建立透传通信 Bluetooth LE SPP (Serial Port Profile, UART-Bluetooth LE 透传模式)。

重要

在以下步骤中以 ESP32 Bluetooth LE 服务端 开头的操作只需要在 ESP32 Bluetooth LE 服务端执行即可，以 ESP32 Bluetooth LE 客户端 开头的操作只需要在 ESP32 Bluetooth LE 客户端执行即可。

初始化 Bluetooth LE 功能。

ESP32 Bluetooth LE 服务端：

命令：
```
AT+BLEINIT=2
```
响应：
```
OK
```
ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLEINIT=1
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端创建服务。

命令：
```
AT+BLEGATTSSRVCRE
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端开启服务。

命令：
```
AT+BLEGATTSSRVSTART
```
响应：
```
OK
```
ESP32 蓝牙 LE 服务器获取其 MAC 地址。

命令：
```
AT+BLEADDR?
```
响应：
```
+BLEADDR:"24:0a:c4:d6:e4:46"
OK
```
说明：
- 您查询到的地址可能与上述响应中的不同，请记住您的地址，下面的步骤中会用到。

设置 Bluetooth LE 广播数据。

命令：

AT+BLEADVDATA="0201060A09457370726573736966030302A0"

响应：

OK

ESP32 Bluetooth LE 服务端开始广播。

命令：
```
AT+BLEADVSTART
```
响应：
```
OK
```

ESP32 Bluetooth LE 客户端开始扫描，持续 3 秒。

命令：

AT+BLESCAN=1,3

响应：

OK
+BLESCAN:"24:0a:c4:d6:e4:46",-78,0201060a09457370726573736966030302a0,,0
+BLESCAN:"45:03:cb:ac:aa:a0",-62,0201060aff4c001005441c61df7d,,1
+BLESCAN:"24:0a:c4:d6:e4:46",-26,0201060a09457370726573736966030302a0,,0

说明：

您的扫描结果可能与上述响应中的不同。

建立 the Bluetooth LE 连接。

ESP32 Bluetooth LE 客户端：

命令：
```
AT+BLECONN=0,"24:0a:c4:d6:e4:46"
```
响应：
```
+BLECONN:0,"24:0a:c4:d6:e4:46"

OK
```
说明：
- 输入上述命令时，请使用您的 ESP Bluetooth LE 服务端地址。
- 如果 Bluetooth LE 连接成功，则会提示 +BLECONN:0,"24:0a:c4:d6:e4:46。
- 如果 Bluetooth LE 连接失败，则会提示 +BLECONN:0,-1。

ESP32 Bluetooth LE 服务端查询服务。

命令：

AT+BLEGATTSSRV?

响应：

+BLEGATTSSRV:1,1,0xA002,1
+BLEGATTSSRV:2,1,0xA003,1

OK

ESP32 Bluetooth LE 服务端发现特征。

命令：

AT+BLEGATTSCHAR?

响应：

+BLEGATTSCHAR:"char",1,1,0xC300,0x02
+BLEGATTSCHAR:"desc",1,1,1,0x2901
+BLEGATTSCHAR:"char",1,2,0xC301,0x02
+BLEGATTSCHAR:"desc",1,2,1,0x2901
+BLEGATTSCHAR:"char",1,3,0xC302,0x08
+BLEGATTSCHAR:"desc",1,3,1,0x2901
+BLEGATTSCHAR:"char",1,4,0xC303,0x04
+BLEGATTSCHAR:"desc",1,4,1,0x2901
+BLEGATTSCHAR:"char",1,5,0xC304,0x08
+BLEGATTSCHAR:"char",1,6,0xC305,0x10
+BLEGATTSCHAR:"desc",1,6,1,0x2902
+BLEGATTSCHAR:"char",1,7,0xC306,0x20
+BLEGATTSCHAR:"desc",1,7,1,0x2902
+BLEGATTSCHAR:"char",1,8,0xC307,0x02
+BLEGATTSCHAR:"desc",1,8,1,0x2901
+BLEGATTSCHAR:"char",2,1,0xC400,0x02
+BLEGATTSCHAR:"desc",2,1,1,0x2901
+BLEGATTSCHAR:"char",2,2,0xC401,0x02
+BLEGATTSCHAR:"desc",2,2,1,0x2901

OK

ESP32 Bluetooth LE 客户端发现服务。

命令：
```
AT+BLEGATTCPRIMSRV=0
```
响应：
```
 +BLEGATTCPRIMSRV:0,1,0x1801,1
 +BLEGATTCPRIMSRV:0,2,0x1800,1
 +BLEGATTCPRIMSRV:0,3,0xA002,1
 +BLEGATTCPRIMSRV:0,4,0xA003,1

OK
```
说明：
- ESP32 Bluetooth LE 客户端查询服务的结果，比 ESP32 Bluetooth LE 服户端查询服务的结果多两个默认服务（UUID: 0x1800 和 0x1801），这是正常现象。正因如此，对于同一服务，ESP32 Bluetooth LE 客户端查询的 <srv_index> 值等于 ESP32 Bluetooth LE 服户端查询的 <srv_index> 值 + 2。例如，上述示例中的服务 0xA002，当前在 ESP32 Bluetooth LE 客户端查询到的 <srv_index> 为 3，如果在 ESP32 Bluetooth LE 服户端通过 AT+BLEGATTSSRV? 命令查询，则 <srv_index> 为 1。

ESP32 Bluetooth LE 客户端发现特征。

命令：

AT+BLEGATTCCHAR=0,3

响应：

+BLEGATTCCHAR:"char",0,3,1,0xC300,0x02
+BLEGATTCCHAR:"desc",0,3,1,1,0x2901
+BLEGATTCCHAR:"char",0,3,2,0xC301,0x02
+BLEGATTCCHAR:"desc",0,3,2,1,0x2901
+BLEGATTCCHAR:"char",0,3,3,0xC302,0x08
+BLEGATTCCHAR:"desc",0,3,3,1,0x2901
+BLEGATTCCHAR:"char",0,3,4,0xC303,0x04
+BLEGATTCCHAR:"desc",0,3,4,1,0x2901
+BLEGATTCCHAR:"char",0,3,5,0xC304,0x08
+BLEGATTCCHAR:"char",0,3,6,0xC305,0x10
+BLEGATTCCHAR:"desc",0,3,6,1,0x2902
+BLEGATTCCHAR:"char",0,3,7,0xC306,0x20
+BLEGATTCCHAR:"desc",0,3,7,1,0x2902
+BLEGATTCCHAR:"char",0,3,8,0xC307,0x02
+BLEGATTCCHAR:"desc",0,3,8,1,0x2901

OK

ESP32 Bluetooth LE 客户端配置 Bluetooth LE SPP。

选择支持写操作的服务特征（characteristic）作为写通道发送数据，选择支持 notify 或者 indicate 的 characteristic 作为读通道接收数据。

命令：
```
AT+BLESPPCFG=1,3,5,3,7
```
响应：
```
OK
```
ESP32 Bluetooth LE 客户端使能 Bluetooth LE SPP。

命令：
```
AT+BLESPP
```
响应：
```
OK

>
```
上述响应表示 AT 已经进入 Bluetooth LE SPP 模式，可以进行数据的发送和接收。

说明：
- ESP32 Bluetooth LE 客户端开启 Bluetooth LE SPP 透传模式后，串口收到的数据会通过 Bluetooth LE 传输到 ESP32 Bluetooth LE 服务端。
ESP32 Bluetooth LE 服务端配置 Bluetooth LE SPP。

选择支持 notify 或者 indicate 的 characteristic 作为写通道发送数据，选择支持写操作的 characteristic 作为读通道接收数据。

命令：
```
AT+BLESPPCFG=1,1,7,1,5
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端使能 Bluetooth LE SPP。

命令：
```
AT+BLESPP
```
响应：
```
OK

>
```
上述响应表示 AT 已经进入 Bluetooth LE SPP 模式，可以进行数据的发送和接收。

说明：
- ESP32 Bluetooth LE 服户端开启 Bluetooth LE SPP 透传模式后，串口收到的数据会通过 Bluetooth LE 传输到 ESP32 Bluetooth LE 客户端。
- 如果 ESP32 Bluetooth LE 客户端端没有先开启 Bluetooth LE SPP 透传，或者使用其他设备作为 Bluetooth LE 客户端，则 ESP32 Bluetooth LE 客户端需要先开启侦听 Notify 或者 Indicate。例如，ESP32 Bluetooth LE 客户端如果未开启透传，则应先调用 AT+BLEGATTCWR=0,3,7,1,1 开启侦听，ESP32 Bluetooth LE 服务端才能成功实现透传。
- 对于同一服务，ESP32 Bluetooth LE 客户端的 <srv_index> 值等于 ESP32 Bluetooth LE 服务端的 <srv_index> 值 + 2，这是正常现象。

ESP32 与手机建立 SPP 连接，以及在 UART-Bluetooth LE 透传模式下传输数据 ¶

该示例展示了如何在 ESP32 开发板（仅作为低功耗蓝牙服务器角色）和手机（仅作为低功耗蓝牙客户端角色）之间建立 SPP 连接，以及如何在 UART-Bluetooth LE 透传模式下传输数据。

重要

步骤中以 ESP32 Bluetooth LE 服务端 开头的操作只需要在 ESP32 Bluetooth LE 服务端执行即可，而以 Bluetooth LE 客户端 开头的操作只需要在手机的蓝牙调试助手中执行即可。

在手机端下载 Bluetooth LE 调试助手，例如 nRF Connect (Android) 和 LightBlue (iOS)。
初始化 Bluetooth LE 功能。

ESP32 Bluetooth LE 服务端：

命令：
```
AT+BLEINIT=2
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端创建服务。

命令：
```
AT+BLEGATTSSRVCRE
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端开启服务。

命令：
```
AT+BLEGATTSSRVSTART
```
响应：
```
OK
```
ESP32 蓝牙 LE 服务器获取其 MAC 地址。

命令：
```
AT+BLEADDR?
```
响应：
```
+BLEADDR:"24:0a:c4:d6:e4:46"
OK
```
说明：
- 您查询到的地址可能与上述响应中的不同，请记住您的地址，下面的步骤中会用到。

设置 Bluetooth LE 广播数据。

命令：

AT+BLEADVDATA="0201060A09457370726573736966030302A0"

响应：

OK

ESP32 Bluetooth LE 服务端开始广播。

命令：
```
AT+BLEADVSTART
```
响应：
```
OK
```
创建 Bluetooth LE 连接。

手机打开 nRF 调试助手，并打开 SCAN 开始扫描，找到 ESP32 Bluetooth LE 服务端的 MAC 地址，点击 CONNECT 进行连接。此时 ESP32 端应该会打印类似于 +BLECONN:0,"60:51:42:fe:98:aa" 的 log，这表示已经建立了 Bluetooth LE 连接。

ESP32 Bluetooth LE 服务端查询服务。

命令：

AT+BLEGATTSSRV?

响应：

+BLEGATTSSRV:1,1,0xA002,1
+BLEGATTSSRV:2,1,0xA003,1

OK

ESP32 Bluetooth LE 服务端发现特征。

命令：

AT+BLEGATTSCHAR?

响应：

+BLEGATTSCHAR:"char",1,1,0xC300,0x02
+BLEGATTSCHAR:"desc",1,1,1,0x2901
+BLEGATTSCHAR:"char",1,2,0xC301,0x02
+BLEGATTSCHAR:"desc",1,2,1,0x2901
+BLEGATTSCHAR:"char",1,3,0xC302,0x08
+BLEGATTSCHAR:"desc",1,3,1,0x2901
+BLEGATTSCHAR:"char",1,4,0xC303,0x04
+BLEGATTSCHAR:"desc",1,4,1,0x2901
+BLEGATTSCHAR:"char",1,5,0xC304,0x08
+BLEGATTSCHAR:"char",1,6,0xC305,0x10
+BLEGATTSCHAR:"desc",1,6,1,0x2902
+BLEGATTSCHAR:"char",1,7,0xC306,0x20
+BLEGATTSCHAR:"desc",1,7,1,0x2902
+BLEGATTSCHAR:"char",1,8,0xC307,0x02
+BLEGATTSCHAR:"desc",1,8,1,0x2901
+BLEGATTSCHAR:"char",2,1,0xC400,0x02
+BLEGATTSCHAR:"desc",2,1,1,0x2901
+BLEGATTSCHAR:"char",2,2,0xC401,0x02
+BLEGATTSCHAR:"desc",2,2,1,0x2901

OK

Bluetooth LE 客户端发现服务。

此时在手机 nRF 调试助手客户端点击 UUID:0xA002 的 UnKnown Service。
手机 nRF 调试助手客户端发现特征。

此时在手机 nRF 调试助手客户端的 UUID:0xA002 的 UnKnown Service 服务下一级选项中选择点击 Properties 为 NOTIFY 或者 INDICATE 的服务特征的右侧按钮（这里 ESP-AT 默认 Properties 为 NOTIFY 或者 INDICATE 的服务特征是 0xC305 和 0xC306），开始侦听 Properties 为 NOTIFY 或者 INDICATE 的服务特征。
ESP32 Bluetooth LE 服务端配置 Bluetooth LE SPP。

选择支持 notify 或者 indicate 的 characteristic 作为写通道发送数据，选择支持写操作的 characteristic 作为读通道接收数据。

命令：
```
AT+BLESPPCFG=1,1,7,1,5
```
响应：
```
OK
```
ESP32 Bluetooth LE 服务端使能 Bluetooth LE SPP。

命令：
```
AT+BLESPP
```
响应：
```
OK

>
```
上述响应表示 AT 已经进入 Bluetooth LE SPP 模式，可以进行数据的发送和接收。
Bluetooth LE 客户端发送数据。

在 nRF 调试助手客户端选择 0xC304 服务特征值发送数据 test 给 ESP32 Bluetooth LE 服务端，此时 ESP32 Bluetooth LE 服务端可以收到 test。
ESP32 Bluetooth LE 服务端发送数据。

在 ESP32 Bluetooth LE 服务端直接发送 test，此时 nRF 调试助手客户端可以收到 test。

MQTT AT 示例¶

[English]

本文档主要提供在 ESP 设备上运行 MQTT AT Commands 命令的详细示例。

基于 TCP 的 MQTT 连接（需要本地创建 MQTT 代理）（适用于数据量少）
基于 TCP 的 MQTT 连接（需要本地创建 MQTT 代理）（适用于数据量多）
基于 TLS 的 MQTT 连接（需要本地创建 MQTT 代理）
基于 WSS 的 MQTT 连接

重要

文档中所描述的例子均基于设备已连接 Wi-Fi 的前提。

基于 TCP 的 MQTT 连接（需要本地创建 MQTT 代理）（适用于数据量少）¶

以下示例同时使用两块 ESP32 开发板，其中一块作为 MQTT 发布者（只作为 MQTT 发布者角色），另一块作为 MQTT 订阅者（只作为 MQTT 订阅者角色）。

示例介绍了如何基于 TCP 创建 MQTT 连接。首先您需要创建一个本地 MQTT 代理，假设 MQTT 代理的 IP 地址为 192.168.3.102，端口为 8883。

重要

步骤中以 ESP32 MQTT 发布者 开头的操作只需要在 ESP32 MQTT 发布者端执行即可，以 ESP32 MQTT 订阅者 开头的操作只需要在 ESP32 MQTT 订阅者端执行即可。如果操作没有特别指明在哪端操作，则需要在发布者端和订阅者端都执行。

设置 MQTT 用户属性。

ESP32 MQTT 发布者：

命令：

AT+MQTTUSERCFG=0,1,"publisher","espressif","123456789",0,0,""

响应：

OK

ESP32 MQTT 订阅者：

命令：

AT+MQTTUSERCFG=0,1,"subscriber","espressif","123456789",0,0,""

响应：

OK

连接 MQTT 代理。

命令：
```
AT+MQTTCONN=0,"192.168.3.102",8883,1
```
响应：
```
+MQTTCONNECTED:0,1,"192.168.3.102","8883","",1

OK
```
说明：
- 您输入的 MQTT 代理域名或 MQTT 代理 IP 地址可能与上述命令中的不同。
订阅 MQTT 主题。

ESP32 MQTT 订阅者：

命令：
```
AT+MQTTSUB=0,"topic",1
```
响应：
```
OK
```
发布 MQTT 消息（字符串）。

ESP32 MQTT 发布者：

命令：
```
AT+MQTTPUB=0,"topic","test",1,0
```
响应：
```
OK
```
说明：
- 如果 ESP32 MQTT 发布者成功发布消息，以下信息将会在 ESP32 MQTT 订阅者端提示。
```
+MQTTSUBRECV:0,"topic",4,test
```
关闭 MQTT 连接。

命令：
```
AT+MQTTCLEAN=0
```
响应：
```
OK
```

基于 TCP 的 MQTT 连接（需要本地创建 MQTT 代理）（适用于数据量多）¶

以下示例同时使用两块 ESP32 开发板，其中一块作为 MQTT 发布者（只作为 MQTT 发布者角色），另一块作为 MQTT 订阅者（只作为 MQTT 订阅者角色）。

示例介绍了如何基于 TCP 创建 MQTT 连接。首先您需要创建一个本地 MQTT 代理，假设 MQTT 代理的 IP 地址为 192.168.3.102，端口为 8883。

如果您发布消息的数据量相对较多，已经超过了单条 AT 指令的长度阈值 256，则建议您可以使用 AT+MQTTPUBRAW 命令。

重要

步骤中以 ESP32 MQTT 发布者 开头的操作只需要在 ESP32 MQTT 发布者端执行即可，以 ESP32 MQTT 订阅者 开头的操作只需要在 ESP32 MQTT 订阅者端执行即可。如果操作没有特别指明在哪端操作，则需要在发布者端和订阅者端都执行。

设置 MQTT 用户属性。

ESP32 MQTT 发布者：

命令：

AT+MQTTUSERCFG=0,1,"publisher","espressif","123456789",0,0,""

响应：

OK

ESP32 MQTT 订阅者：

命令：

AT+MQTTUSERCFG=0,1,"subscriber","espressif","123456789",0,0,""

响应：

OK

连接 MQTT 代理。

命令：
```
AT+MQTTCONN=0,"192.168.3.102",8883,1
```
响应：
```
+MQTTCONNECTED:0,1,"192.168.3.102","8883","",1

OK
```
说明：
- 您输入的 MQTT 代理域名或 MQTT 代理 IP 地址可能与上述命令中的不同。
订阅 MQTT 主题。

ESP32 MQTT 订阅者：

命令：
```
AT+MQTTSUB=0,"topic",1
```
响应：
```
OK
```

发布 MQTT 消息（字符串）。

假设你想要发布消息的数据如下，长度为 427 字节。

{"headers": {"Accept": "application/json","Accept-Encoding": "gzip, deflate","Accept-Language": "en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7","Content-Length": "0","Host": "httpbin.org","Origin": "http://httpbin.org","Referer": "http://httpbin.org/","User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36","X-Amzn-Trace-Id": "Root=1-6150581e-1ad4bd5254b4bf5218070413"}}

ESP32 MQTT 发布者：

命令：

AT+MQTTPUBRAW=0,"topic",427,0,0

响应：

OK

>

上述响应表示 AT 已准备好接收串行数据，此时您可以输入数据，当 AT 接收到的数据长度达到 <length> 后，数据传输开始。

+MQTTPUB:OK

说明：

AT 输出 > 字符后，数据中的特殊字符不需要转义字符进行转义，也不需要以新行结尾（CR-LF）。

如果 ESP32 MQTT 发布者成功发布消息，以下信息将会在 ESP32 MQTT 订阅者端提示。

+MQTTSUBRECV:0,"topic",427,{"headers": {"Accept": "application/json","Accept-Encoding": "gzip, deflate","Accept-Language": "en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7","Content-Length": "0","Host": "httpbin.org","Origin": "http://httpbin.org","Referer": "http://httpbin.org/","User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36","X-Amzn-Trace-Id": "Root=1-6150581e-1ad4bd5254b4bf5218070413"}}

关闭 MQTT 连接。

命令：
```
AT+MQTTCLEAN=0
```
响应：
```
OK
```

基于 TLS 的 MQTT 连接（需要本地创建 MQTT 代理）¶

以下示例同时使用两块 ESP32 开发板，其中一块作为 MQTT 发布者（只作为 MQTT 发布者角色），另一块作为 MQTT 订阅者（只作为 MQTT 订阅者角色）。

示例介绍了如何基于 TLS 创建 MQTT 连接。首先您需要创建一个本地 MQTT 代理，假设 MQTT 代理的 IP 地址为 192.168.3.102，端口为 8883。

重要

步骤中以 ESP32 MQTT 发布者 开头的操作只需要在 ESP32 MQTT 发布者端执行即可，以 ESP32 MQTT 订阅者 开头的操作只需要在 ESP32 MQTT 订阅者端执行即可。如果操作没有特别指明在哪端操作，则需要在发布者端和订阅者端都执行。

设置时区和 SNTP 服务器。

命令：
```
AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com"
```
响应：
```
OK
```
查询 SNTP 时间。

命令：
```
AT+CIPSNTPTIME?
```
响应：
```
+CIPSNTPTIME:Thu Sep  2 18:57:03 2021
OK
```
说明：
- 您的查询 SNTP 结果可能与上述响应中的不同。
- 请确保 SNTP 时间一定是真实有效的时间，不能是 1970 年及之前的时间。
- 设置时间是为了在 TLS 认证时校验证书的有效期。

设置 MQTT 用户属性。

ESP32 MQTT 发布者：

命令：

AT+MQTTUSERCFG=0,4,"publisher","espressif","123456789",0,0,""

响应：

OK

ESP32 MQTT 订阅者：

命令：

AT+MQTTUSERCFG=0,4,"subscriber","espressif","123456789",0,0,""

响应：

OK

设置 MQTT 连接属性。

命令：
```
AT+MQTTCONNCFG=0,0,0,"lwtt","lwtm",0,0
```
响应：
```
OK
```
连接 MQTT 代理。

命令：
```
AT+MQTTCONN=0,"192.168.3.102",8883,1
```
响应：
```
+MQTTCONNECTED:0,4,"192.168.3.102","8883","",1

OK
```
说明：
- 您输入的 MQTT 代理域名或 MQTT 代理 IP 地址可能与上述命令中的不同。
订阅 MQTT 主题。

ESP32 MQTT 订阅者：

命令：
```
AT+MQTTSUB=0,"topic",1
```
响应：
```
OK
```
发布 MQTT 消息（字符串）。

ESP32 MQTT 发布者：

命令：
```
AT+MQTTPUB=0,"topic","test",1,0
```
响应：
```
OK
```
说明：
- 如果 ESP32 MQTT 发布者成功发布消息，以下信息将会在 ESP32 MQTT 订阅者端提示。
```
+MQTTSUBRECV:0,"topic",4,test
```
关闭 MQTT 连接。

命令：
```
AT+MQTTCLEAN=0
```
响应：
```
OK
```

基于 WSS 的 MQTT 连接 ¶

以下示例同时使用两块 ESP32 开发板，其中一块作为 MQTT 发布者（只作为 MQTT 发布者角色），另一块作为 MQTT 订阅者（只作为 MQTT 订阅者角色）。

示例介绍了如何基于 WSS 创建 MQTT 连接。MQTT 代理域名为 test.mosquitto.org，端口为 8081 。

重要

步骤中以 ESP32 MQTT 发布者 开头的操作只需要在 ESP32 MQTT 发布者端执行即可，以 ESP32 MQTT 订阅者 开头的操作只需要在 ESP32 MQTT 订阅者端执行即可。如果操作没有特别指明在哪端操作，则需要在发布者端和订阅者端都执行。

设置时区和 SNTP 服务器。

命令：
```
AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com"
```
响应：
```
OK
```
查询 SNTP 时间。

命令：
```
AT+CIPSNTPTIME?
```
响应：
```
+CIPSNTPTIME:Thu Sep  2 18:57:03 2021
OK
```
说明：
- 您的查询 SNTP 结果可能与上述响应中的不同。
- 请确保 SNTP 时间一定是真实有效的时间，不能是 1970 年及之前的时间。
- 设置时间是为了在 TLS 认证时校验证书的有效期。

设置 MQTT 用户属性。

ESP32 MQTT 发布者：

命令：

AT+MQTTUSERCFG=0,7,"publisher","espressif","1234567890",0,0,""

响应：

OK

ESP32 MQTT 订阅者：

命令：

AT+MQTTUSERCFG=0,7,"subscriber","espressif","1234567890",0,0,""

响应：

OK

连接 MQTT 代理。

命令：
```
AT+MQTTCONN=0,"test.mosquitto.org",8081,1
```
响应：
```
+MQTTCONNECTED:0,7,"test.mosquitto.org","8081","/",1

OK
```
说明：
- 您输入的 MQTT 代理域名或 MQTT 代理 IP 地址可能与上述命令中的不同。
订阅 MQTT 主题。

ESP32 MQTT 订阅者：

命令：
```
AT+MQTTSUB=0,"topic",1
```
响应：
```
OK
```
发布 MQTT 消息（字符串）。

ESP32 MQTT 发布者：

命令：
```
AT+MQTTPUB=0,"topic","test",1,0
```
响应：
```
OK
```
说明：
- 如果 ESP32 MQTT 发布者成功发布消息，以下信息将会在 ESP32 MQTT 订阅者端提示。
```
+MQTTSUBRECV:0,"topic",4,test
```
关闭 MQTT 连接。

命令：
```
AT+MQTTCLEAN=0
```
响应：
```
OK
```

[ESP32 Only] Ethernet AT 示例¶

[English]

本文档主要介绍 [ESP32 Only] 以太网 AT 命令的使用方法，并提供在 ESP 设备上运行这些命令的详细示例。

基于以太网创建 TCP 连接

重要

在使用 Ethernet AT 指令之前，请先阅读准备工作。
文档中所描述的例子均是基于网线已经插入的情况下。

基于以太网创建 TCP 连接 ¶

使能多连接。

命令：
```
AT+CIPMUX=1
```
响应：
```
OK
```
建立 TCP 服务器。

命令：
```
AT+CIPSERVER=1,8081
```
响应：
```
OK
```
获取 TCP 服务器的 IP 地址。

命令：
```
AT+CIPETH?
```
响应：
```
+CIPETH:ip:192.168.105.24
+CIPETH:gateway:192.168.105.1
+CIPETH:netmask:255.255.255.0
OK
```
说明：
- 您获取到的地址可能与上述响应中的不同。
在 PC 端使用网络调试工具创建一个 TCP 客户端，并连接到步骤 2 中创建的 TCP 服务端，IP 地址是 192.168.105.24，端口为 8081。
采用普通传输模式发送 4 字节数据到网络连接 ID 为 0 的链路上。

命令：
```
AT+CIPSEND=0,4
```
响应：
```
OK

>
```
输入 4 字节数据，例如输入数据是 test，之后 AT 将会输出以下信息。
```
Recv 4 bytes

SEND OK
```
说明：
- 若输入的字节数目超过了 AT+CIPSEND 指令设定的长度 (n)，则会响应 busy p...，并发送数据的前 n 个字节，发送完成后响应 SEND OK。
采用普通传输模式从网络连接 ID 为 0 的链路上接收 4 字节数据。

假设 TCP server 接收到 4 字节的数据（数据为 test），则系统会提示：
```
+IPD,0,4:test
```
关闭 TCP 连接。

命令：
```
AT+CIPCLOSE=0
```
响应：
```
0,CLOSED

OK
```
删除 TCP 服务端。

命令：
```
AT+CIPSERVER=0
```
响应：
```
OK
```
说明：
- 指令 AT+CIPSERVER=0 只会关闭服务器，但会保留现有客户端连接。如果您想同时关闭所有的客户端连接，请执行指令 AT+CIPSERVER=0,1。

Web Server AT 示例¶

[English]

本文档主要介绍 AT web server 的使用，主要涉及以下几个方面的应用：

使用浏览器进行 Wi-Fi 配网
使用浏览器进行 OTA 固件升级
使用微信小程序进行 Wi-Fi 配网
使用微信小程序进行 OTA 固件升级
[ESP32][ESP32-C 系列] 使用 Captive Portal 功能

注解

默认的 AT 固件并不支持 AT web server 的功能，请参考 Web 服务器 AT 命令启用该功能。

使用浏览器进行 Wi-Fi 配网 ¶

简介¶

通过 web server，手机或 PC 可以设置 ESP 设备的 Wi-Fi 连接信息。您可以使用手机或电脑连接到 ESP 设备的 AP，通过浏览器打开配网网页，并将 Wi-Fi 配置信息发送给 ESP 设备，然后 ESP 设备将根据该配置信息连接到指定的路由器。

流程¶

整个配网流程可以分为以下三步：

配网设备连接 ESP 设备
使用浏览器发送配网信息
通知配网结果

配网设备连接 ESP 设备 ¶

首先，为了让配网设备连接 ESP 设备，ESP 设备需要配置成 AP + STA 模式，并创建一个 WEB 服务器等待配网信息，对应的 AT 命令如下：

清除之前的配网信息，如果不清除配网信息，可能因为依然保留之前的配置信息从而导致 WEB 服务器无法创建。
- Command
```
AT+RESTORE
```
配置 ESP 设备为 Station + SoftAP 模式。
- Command
```
AT+CWMODE=3
```
设置 SoftAP 的 ssid 和 password（如设置默认连接 ssid 为 pos_softap，无密码的 Wi-Fi）。
- Command
```
AT+CWSAP="pos_softap","",11,0,3
```
使能多连接。
- Command
```
AT+CIPMUX=1
```
创建 web server，端口：80，最大连接时间：25 s（默认最大为 60 s）。
- Command
```
AT+WEBSERVER=1,80,25
```

然后，使用上述命令启动 web server 后，打开配网设备的 Wi-Fi 连接功能，连接 ESP 设备的 AP：

使用浏览器发送配网信息 ¶

在配网设备连接到 ESP 设备后，即可发送 HTTP 请求，配置待接入的路由器的信息：（注意，浏览器配网不支持配网设备作为待接入 AP，例如，如果使用手机连接到 ESP 的 AP，则该手机不建议作为 ESP 设备待接入的热点。）在浏览器中输入 web server 默认的 IP 地址（如果未设置 ESP 设备的 SoftAP IP 地址，默认为 192.168.4.1，您可以通过 AT+CIPAP? 命令查询当前的 SoftAP IP 地址)，打开配网界面，输入拟连接的路由器的 ssid、password，点击“开始配网”即可开始配网：

用户也可以点击配网页面中 SSID 输入框右方的下拉框，查看 ESP 模块附近的 AP 列表，选择目标 AP 并输入 password 后，点击“开始配网”即可启动配网：

通知配网结果 ¶

配网成功后网页显示如下：

说明 1：配网成功后，网页将自动关闭，若想继续访问网页，请重新输入 ESP 设备的 IP 地址，重新打开网页。

同时，在串口端将收到如下信息：

+WEBSERVERRSP:1      // 代表启动配网
WIFI CONNECTED       // 代表正在连接
WIFI GOT IP          // 连接成功并获取到 IP
+WEBSERVERRSP:2      // 代表网页端收到配网成功结果，此时可以释放 WEB 资源

如果配网失败，网页将显示：

同时，在串口端将收到如下信息：

+WEBSERVERRSP:1      // 代表启动配网，没有后续发起连接以及获取 IP 的信息，MCU 可以在收到该条消息后建立计时，若计时超时，则配网失败。

常见故障排除¶

说明 1：配网页面收到提示“数据发送失败”。请检查 ESP 模块的 Wi-Fi AP 是否正确开启，以及 AP 的相关配置，并确认已经输入正确的 AT 命令成功启用 web server。

使用浏览器进行 OTA 固件升级 ¶

简介¶

浏览器打开 web server 的网页后，可以选择进入 OTA 升级页面，通过网页对 ESP 模块进行固件升级。

打开 OTA 配置页面 ¶

如图，点击网页右下角“OTA 升级”选项，打开 OTA 配置页面后，可以查看当前固件版本、AT Core 版本：

说明 1：仅当浏览器连接 ESP 模块的AP，或者访问 OTA 配置页面的设备与 ESP 模块连接在同一个子网中时，才可以打开该配置界面。

说明 2：网页上显示的“当前固件版本”为当前用户编译的应用程序版本号，用户可通过 ./build.py menuconfig –> Component config –> AT –> AT firmware version (参考编译 ESP-AT 工程)更改该版本号，建立固件版本与应用程序的同步关系，以便于管理应用程序固件版本。

选择并发送新版固件 ¶

如图，点击页面中的“浏览”按钮，选择待发送的新版固件：

说明 1：在发送新版固件之前，系统会对选择的固件进行检查。固件命名的后缀必须为.bin，且其大小不超过 2M。

通知固件发送结果 ¶

如图，固件发送成功，将提示“升级成功”：

同时，在串口端将收到如下信息：

+WEBSERVERRSP:3      // 代表开始接收 OTA 固件数据
+WEBSERVERRSP:4      // 代表成功接收 OTA 固件数据并且对数据的校验正确，此时 MCU 可以选择重启 ESP 设备，以应用新版本的固件

若接收的 OTA 固件数据校验失败，在串口端将收到如下信息：

+WEBSERVERRSP:3      // 代表开始接收 OTA 固件数据
+WEBSERVERRSP:5      // 代表接收的 OTA 固件数据校验失败，用户可以选择重新打开 OTA 配置界面，按照上述步骤进行 OTA 固件升级

使用微信小程序进行 Wi-Fi 配网 ¶

简介¶

微信小程序配网是通过微信小程序连接 ESP 设备创建的 AP，并通过微信小程序将需要连接的 AP 信息传输给 ESP 设备，ESP 设备通过这些信息连接到对应的 AP，并通知微信小程序配网结果的解决方案。

流程¶

整个配网流程可以分为以下四步：

配置 ESP 设备参数
加载微信小程序
目标 AP 选择
执行配网

配置 ESP 设备参数 ¶

为了让小程序连接 ESP 设备，ESP 设备需要配置成 AP + STA 模式，并创建一个 WEB 服务器等待小程序连接，对应的 AT 命令如下：

清除之前的配网信息，如果不清除配网信息，可能因为依然保留之前的配置信息从而导致 WEB 服务器无法创建。
- Command
```
AT+RESTORE
```
配置 ESP 设备为 Station + SoftAP 模式。
- Command
```
AT+CWMODE=3
```
设置 SoftAP 的 ssid 和 password（如设置默认连接 ssid 为 pos_softap，password 为 espressif）。
- Command
```
AT+CWSAP="pos_softap","espressif",11,3,3
```

注解

微信小程序默认向 ssid 为 pos_softap，password 为 espressif 的 SoftAP 发起连接，请确保将 ESP 设备的参数按照上述配置进行设置。

使能多连接。
- Command
```
AT+CIPMUX=1
```
创建 web server，端口：80，最大连接时间：40 s（默认最大为 60 s）。
- Command
```
AT+WEBSERVER=1,80,40
```

加载微信小程序 ¶

打开手机微信，扫描下面的二维码：

打开微信小程序，进入配网界面：

目标 AP 选择 ¶

加载微信小程序后，根据待连接的目标 AP，可将配网情况分为两种情况：

1.待接入的目标 AP 为本机配网手机提供的热点。此时请选中微信小程序页面的“本机手机热点”选项框。

2.待接入的目标 AP 不是本机配网手机提供的热点，如路由器等 AP。此时请确保“本机手机热点”选项框未被选中。

执行配网 ¶

待接入的目标 AP 不是本机配网手机¶

这里以待接入的热点为路由器为例，介绍配网的过程：

1.打开手机 Wi-Fi，连接路由器：

2.打开微信小程序，可以看到小程序页面已经自动显示当前路由器的 ssid 为”FAST_FWR310_02”。

注意：如果当前页面未显示已经连接的路由器的 ssid，请点击下图中的“重新进入小程序”，刷新当前页面：

3.输入路由器的 password 后，点击“开始配网”。

4.配网成功，小程序页面显示：

同时，在串口端将收到如下信息：

+WEBSERVERRSP:1      // 代表启动配网
WIFI CONNECTED       // 代表正在连接
WIFI GOT IP          // 连接成功并获取到 IP
+WEBSERVERRSP:2      // 代表小程序收到配网成功结果，此时可以释放 WEB 资源

5.若配网失败，则小程序页面显示：

同时，在串口端将收到如下信息：

+WEBSERVERRSP:1      // 代表启动配网，没有后续发起连接以及获取 IP 的信息，MCU 可以在收到该条消息后建立计时，若计时超时，则配网失败。

待接入的目标 AP 为本机配网手机¶

如果正在配网的手机作为待接入 AP，则用户不需要输入 ssid，只需要输入本机的 AP 的 password，并根据提示及时打开手机 AP 即可（如果手机支持同时打开 Wi-Fi 和分享热点，也可提前打开手机 AP）。

1.选中微信小程序页面的“本机手机热点”选项框，输入本机热点的 password 后，点击“开始配网”。

2.启动配网后，在收到提示“连接手机热点中”的提示后，请检查本机手机热点已经开启，此时 ESP 设备将自动扫描周围热点并发起连接。

3.配网结果在小程序页面的显示以及串口端输出的数据与上述“待接入的目标 AP 不是本机配网手机”时的情况一样，请参考上文。

常见故障排除¶

说明 1：配网页面收到提示“数据发送失败”。请检查 ESP 模块的 Wi-Fi AP 是否正确开启，以及 AP 的相关配置，并确认已经输入正确的 AT 命令成功启用 web server。

说明 2：配网页面收到提示“连接 AP 失败”。请检查配网设备的 Wi-Fi 连接功能是否打开，检查 ESP 模块的 Wi-Fi AP 是否正确开启，以及 AP 的 ssid、password 是否按上述步骤进行配置。

说明 3：配网页面收到提示“系统保存的 Wi-Fi 配置过期”。请手动使用手机连接 ESP 模块 AP，确认 ESP 模块的 ssid、password 已经按照上述步骤进行配置。

使用微信小程序进行 OTA 固件升级 ¶

微信小程序支持在线完成 ESP 设备的固件升级，请参考上述配置 ESP 设备参数的具体步骤完成 ESP 模块的配置（如果已经在配网时完成配置，不用重复配置）。完成配置后，设备执行 OTA 固件升级的流程与使用浏览器进行 OTA 固件升级类似，请参考使用浏览器进行 OTA 固件升级。

[ESP32][ESP32-C 系列] 使用 Captive Portal 功能 ¶

简介¶

Captive Portal，是一种“强制认证主页”技术，当使用支持 Captive Portal 的 station 设备连接到提供 Captive Portal 服务的 AP 设备时，将触发 station 设备的浏览器跳转到指定的网页。更多关于 Captive Portal 的介绍，请参考 Captive Portal Wiki。

注解

默认情况下 AT web 并未启用该功能，可以通过 ./build.py menuconfig > Component config > AT > AT WEB Server command support > AT WEB captive portal support 启用该功能，然后编译工程（请参考编译 ESP-AT 工程）。此外，启用该功能，可能导致使用微信小程序进行配网或 OTA 固件升级时发生页面跳转，建议仅在使用浏览器访问 AT web 时启用该功能。

流程¶

启用 Captive Portal 功能后，请参考上述配网设备连接 ESP 设备的具体步骤完成 ESP 模块的配置，然后连接 ESP 设备的 AP：

如上图，station 设备连接打开 Captive Portal 功能的 ESP 设备的 AP 后，提示“需登录/认证”，然后将自动打开浏览器，并跳转到 AT web 的主界面。若不能自动跳转，请根据 station 设备的提示，点击“认证”或点击上图中的“pos_softap”热点的名称，手动触发 Captive Portal 自动打开浏览器，进入到 AT web 的主界面。

常见故障排除¶

说明 1：通信双方（station 设备、AP 设备）都支持 Captive Portal 功能才能保证该功能正常使用，因此，若设备连接 ESP 设备的 AP 后未提示“需登录/认证”，并且没有自动进入到 AT web 的主界面，可能是 station 设备不支持该功能，此时，请参考上述使用浏览器发送配网信息的具体步骤手动打开 AT web 的主界面。

HTTP AT 示例¶

[English]

本文档主要提供在 ESP 设备上运行 HTTP AT 命令集命令的详细示例。

HTTP 客户端 HEAD 请求方法
HTTP 客户端 GET 请求方法
HTTP 客户端 POST 请求方法（适用于 POST 少量数据）
HTTP 客户端 POST 请求方法（推荐方式）
HTTP 客户端 PUT 请求方法
HTTP 客户端 DELETE 请求方法

重要

当前 ESP-AT 仅支持部分 HTTP 客户端的功能。

HTTP 客户端 HEAD 请求方法 ¶

该示例以 http://httpbin.org 作为 HTTP 服务器。

恢复出厂设置。

命令：
```
AT+RESTORE
```
响应：
```
OK
```
设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。

发送一个 HTTP HEAD 请求。设置 opt 为 1 （HEAD 方法），url 为 http://httpbin.org/get，transport_type 为 1 （HTTP_TRANSPORT_OVER_TCP）。

命令：

AT+HTTPCLIENT=1,0,"http://httpbin.org/get",,,1

响应：

+HTTPCLIENT:35, Date: Sun, 26 Sep 2021 06:59:13 GMT
+HTTPCLIENT:30, Content-Type: application/json
+HTTPCLIENT:19, Content-Length: 329
+HTTPCLIENT:22, Connection: keep-alive
+HTTPCLIENT:23, Server: gunicorn/19.9.0
+HTTPCLIENT:30, Access-Control-Allow-Origin: *
+HTTPCLIENT:38, Access-Control-Allow-Credentials: true

OK

说明：

您获取到的 HTTP 头部信息可能与上述响应中的不同。

HTTP 客户端 GET 请求方法 ¶

本例以下载一个 JPG 格式的图片文件为例。图片链接为 https://www.espressif.com/sites/all/themes/espressif/images/about-us/solution-platform.jpg。

恢复出厂设置。

命令：
```
AT+RESTORE
```
响应：
```
OK
```
设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。

发送一个 HTTP GET 请求。设置 opt 为 2 （GET 方法），url 为 https://www.espressif.com/sites/all/themes/espressif/images/about-us/solution-platform.jpg，transport_type 为 2 （HTTP_TRANSPORT_OVER_SSL）。

命令：

AT+HTTPCLIENT=2,0,"https://www.espressif.com/sites/all/themes/espressif/images/about-us/solution-platform.jpg",,,2

响应：

+HTTPCLIENT:512,<0xff><0xd8><0xff><0xe2><0x0c>XICC_PROFILE<break>
<0x01><0x01><break>
<break>
<0x0c>HLino<0x02><0x10><break>
<break>
mntrRGB XYZ <0x07><0xce><break>
<0x02><break>
...
+HTTPCLIENT:512,<0xeb><0xe2>v<0xcb><0x98>-<0xf8><0x8a><0xae><0xf3><0xc8><0xb6><0xa8><0x86><0x02>j<0x06><0xe2>
"<0xaa>*p<0x7f>2",h<0x12>N<0xa5><0x1e><0xd2>bp<0xea><0x1e><0xf5><0xa3>x<0xa6>J<0x14>Ti<0xc3>m<0x1a>m<0x94>T<0xe1>I<0xb6><0x90><0xdc>_<0x11>QU;<0x94><0x97><0xcb><0xdd><0xc7><0xc6><0x85><0xd7>U<0x02><0xc9>W<0xa4><0xaa><0xa1><0xa1><0x08>hB<0x1a><0x10><0x86><0x84>!<0xa1><0x08>hB<0x1a><0x10><0x9b><0xb9>K<0xf5>5<0x95>5-=<0x8a><0xcb><0xce><0xe0><0x91><0xf0>m<0xa9><0x04>C<0xde>k<0xe7><0xc2>v<H|<0xaf><0xb8>L<0x91>=<0xda>_<0x94><0xde><0xd0><0xa9><0xc0><0xdd>8<0x9a>B<0xaa><0x1a><0x10><0x86><0x84>$<0xf4><0xd6><0xf2><0xa3><0x92><0xe7><0xa8>I<0xa3>b<0x1f>)<0xe1>z<0xc4>y<0xae><0xca><0xed><0xec><0x1e>|^<0xd7>E<0xa2>_<0x13><0x9e>;{|<0xb5>Q<0x97><0xa5>P<0xdf><0xa1>#3vn<0x1b><0xc3>-<0x92><0xe2>dIn<0x9c><0xb8>
<0xc7><0xa9><0xc6>(<0xe0><0xd3>i-<0x9e>@<0xbb><0xcc><0x88><0xd5>K<0xe3><0xf0>O<0x9f>Km<0xb3>h<0xa8>omR<0xfe><0x8b><0xf9><0xa4><0xa6><0xff><break>
aU<0xdf><0xf3><0xa3>:A<0xe2>UG<0x04>k<0xaa>*<0xa1><0xa1><0x0b><0xca><0xec><0xd8>Q<0xfb><0xbc>yqY<0xec><0xfb>?<0x16>CM<0xf6>|}<0xae><0xf3><0x1e><0xdf>%<0xf8><0xe8><0xb1>B<0x8f>[<0xb3>><0x04><0xec><0xeb>f<0x06><0x1c><0xe8><0x92><0xc9><0x8c><0xb0>I<0xd1><0x8b>%<0x99><0x04><0xd0><0xbb>s<0x8b>xj<0xe2>4f<0xa0><0x8e>+E<0xda><0xab><0xc7>=<0xab><0xc7><0xb9>xz1f<0xba><0xfd>_e6<0xff><break>
(w<0xa7>b<0xe3>m<0xf0>|<0x82><0xc9><0xfb><0x8b><0xac>r<0x95><0x94><0x96><0xd9>i<0xe9>RVA<0x91><0x83><0x8b>M'<0x86><0x8f><0xa3>A<0xd8><0xd8>"r"<0x8a><0xa8><0x9e>zl=<0xcd><0x16><0x07>D<0xa2><0xd0>u(<0xc2><0x8b><0x0b><0xc4><0xf1><0x87><0x9c><0x93><0x8f><0xe3><0xd5>U<0x12>]<0x8e><0x91>]<0x91><0x06>#l<0xbe><0xf4>t0?<0xd7><0x85><GEM<0xb1>%<0xee>UUT<0xe7><0xdf><0xa0><0xb9><0xce><0xe2>U@<0x03><0x82>S<0xe9>*<0xa8>hB<0x1a><0x10><0xa1><0xaf>V<0x19>U<0x9d><0xb3>x<0xa6><0xc7><0xe2><0x86><0x8e>d[<0x89>e<0x05>l<0x80>H<0x91>#<0xd2><0x8c><0xe1>j<0x1b>rH<0x04><0x89><0x98><0xd3>lZW]q><0xc2><';<0x93><0xb4><0xf5>&<0x9d><0xa0>^Wp<0xa9>6`<0xe2>T<0xa2><0xc2><0xb1>*<0xbc><0x13><0x13><0xa0><0xc4>)<0x83><0xb6><0xbe><0x86><0xb9><0x88>-<0x1a>

OK

HTTP 客户端 POST 请求方法（适用于 POST 少量数据）¶

该示例以 http://httpbin.org 作为 HTTP 服务器，数据类型为 application/json。

恢复出厂设置。

命令：
```
AT+RESTORE
```
响应：
```
OK
```
设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。

发送一个 HTTP POST 请求。设置 opt 为 3 （POST 方法），url 为 http://httpbin.org/post，content-type 为 1 （application/json），transport_type 为 1 （HTTP_TRANSPORT_OVER_TCP）。

命令：

AT+HTTPCLIENT=3,1,"http://httpbin.org/post",,,1,"{\"form\":{\"purpose\":\"test\"}}"

响应：

+HTTPCLIENT:282,{
  "args": {},
  "data": "{\"form\":{\"purpose\":\"test\"}}",
  "files": {},
  "form": {},
  "headers": {
    "Content-Length": "27",
    "Content-Type": "application/json",
    "Host": "httpbin.org",
    "User-Agent": "ESP32 HTTP Client/1.0",
    "X-Amzn-Trace-Id": "Root=
+HTTPCLIENT:173,1-61503a3f-4b16b71918855b97614c5dfb"
  },
  "json": {
    "form": {
      "purpose": "test"
    }
  },
  "origin": "20.187.154.207",
  "url": "http://httpbin.org/post"
}


OK

说明：

您获取到的结果可能与上述响应中的不同。

HTTP 客户端 POST 请求方法（推荐方式）¶

如果您 POST 的数据量相对较多，已经超过了单条 AT 指令的长度阈值 256，则建议您可以使用 AT+HTTPCPOST 命令。

该示例以 http://httpbin.org 作为 HTTP 服务器，数据类型为 application/json。

恢复出厂设置。

命令：
```
AT+RESTORE
```
响应：
```
OK
```
设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。

Post 指定长度数据。该命令设置 HTTP 头部字段数量为 2，分别是 connection 字段和 content-type 字段，connection 字段值为 keep-alive，connection 字段值为 application/json。

假设你想要 post 的 JSON 数据如下，长度为 472 字节。

{"headers": {"Accept": "application/json","Accept-Encoding": "gzip, deflate","Accept-Language": "en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7","Content-Length": "0","Host": "httpbin.org","Origin": "http://httpbin.org","Referer": "http://httpbin.org/","User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36","X-Amzn-Trace-Id": "Root=1-6150581e-1ad4bd5254b4bf5218070413"}}

命令：

AT+HTTPCPOST="http://httpbin.org/post",427,2,"connection: keep-alive","content-type: application/json"

响应：

OK

>

上述响应表示 AT 已准备好接收串行数据，此时您可以输入数据，当 AT 接收到的数据长度达到 <length> 后，数据传输开始。

+HTTPCPOST:281,{
  "args": {},
  "data": "{\"headers\": {\"Accept\": \"application/json\",\"Accept-Encoding\": \"gzip, deflate\",\"Accept-Language\": \"en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7\",\"Content-Length\": \"0\",\"Host\": \"httpbin.org\",\"Origin\": \"http://httpbin.org\",\"Referer\": \"htt
+HTTPCPOST:512,p://httpbin.org/\",\"User-Agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36\",\"X-Amzn-Trace-Id\": \"Root=1-6150581e-1ad4bd5254b4bf5218070413\"}}",
  "files": {},
  "form": {},
  "headers": {
    "Content-Length": "427",
    "Content-Type": "application/json",
    "Host": "httpbin.org",
    "User-Agent": "ESP32 HTTP Client/1.0",
    "X-Amzn-Trace-Id": "Root=1-61505e76-278b5c267aaf55842bd58b32"
  },
  "json": {
    "headers": {

+HTTPCPOST:512,"Accept": "application/json",
      "Accept-Encoding": "gzip, deflate",
      "Accept-Language": "en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7",
      "Content-Length": "0",
      "Host": "httpbin.org",
      "Origin": "http://httpbin.org",
      "Referer": "http://httpbin.org/",
      "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36",
      "X-Amzn-Trace-Id": "Root=1-6150581e-1ad4bd5254b4bf5218070413"
    }
  },
  "origin": "20.187.154
+HTTPCPOST:45,.207",
  "url": "http://httpbin.org/post"
}


SEND OK

说明：

AT 输出 > 字符后，HTTP body 中的特殊字符不需要转义字符进行转义，也不需要以新行结尾（CR-LF）。

HTTP 客户端 PUT 请求方法 ¶

该示例以 http://httpbin.org 作为 HTTP 服务器。PUT 请求支持查询字符串参数模式。

恢复出厂设置。

命令：
```
AT+RESTORE
```
响应：
```
OK
```
设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。

发送一个 HTTP PUT 请求。设置 opt 为 4 （PUT 方法），url 为 http://httpbin.org/put，transport_type 为 1 （HTTP_TRANSPORT_OVER_TCP）。

命令：

AT+HTTPCLIENT=4,0,"http://httpbin.org/put?user=foo",,,1

响应：

+HTTPCLIENT:282,{
  "args": {
    "user": "foo"
  },
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Content-Length": "0",
    "Content-Type": "application/x-www-form-urlencoded",
    "Host": "httpbin.org",
    "User-Agent": "ESP32 HTTP Client/1.0",
    "X-Amzn-Trace-Id": "R
+HTTPCLIENT:140,oot=1-61503d41-1dd8cbe0056190f721ab1912"
  },
  "json": null,
  "origin": "20.187.154.207",
  "url": "http://httpbin.org/put?user=foo"
}


OK

说明：

您获取到的结果可能与上述响应中的不同。

HTTP 客户端 DELETE 请求方法 ¶

该示例以 http://httpbin.org 作为 HTTP 服务器。DELETE 方法用于删除服务器上的资源。DELETE 请求的实现依赖服务器。

恢复出厂设置。

命令：
```
AT+RESTORE
```
响应：
```
OK
```
设置 Wi-Fi 模式为 station。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。

发送一个 HTTP DELETE 请求。设置 opt to 5 （DELETE 方法），url 为 http://httpbin.org/delete，transport_type to 1 （HTTP_TRANSPORT_OVER_TCP）。

命令：

AT+HTTPCLIENT=5,0,"https://httpbin.org/delete",,,1

响应：

+HTTPCLIENT:282,{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Content-Length": "0",
    "Content-Type": "application/x-www-form-urlencoded",
    "Host": "httpbin.org",
    "User-Agent": "ESP32 HTTP Client/1.0",
    "X-Amzn-Trace-Id": "Root=1-61504289-468a41
+HTTPCLIENT:114,737b0d251672acec9d"
  },
  "json": null,
  "origin": "20.187.154.207",
  "url": "https://httpbin.org/delete"
}


OK

说明：

您获取到的结果可能与上述响应中的不同。

[ESP32 Only] Classic Bluetooth AT 示例¶

[English]

本文档主要提供在 ESP 设备上运行 [ESP32 Only] Classic Bluetooth® AT 命令集命令的详细示例。

以普通传输模式在移动电话或者 PC 和 ESP32 之间建立 SPP 连接并且设置 IO 能力为 NoInputNoOutput
以透传模式在移动电话或者 PC 和 ESP32 之间建立 SPP 连接并且设置 IO 能力为 NoInputNoOutput
在移动电话或者 PC 和 ESP32 之间建立 SPP 连接并且设置 IO 能力为 KeyboardOnly
在两个 ESP32 开发板之间建立 SPP 连接
建立 A2DP 连接并启用 A2DP Sink 播放音乐
查询和清除 Classic Bluetooth 加密设备列表

重要

固件默认不支持 Classic Bluetooth 命令，请参考文档如何启用 ESP-AT 经典蓝牙使能 Classic Bluetooth 命令。

以普通传输模式在移动电话或者 PC 和 ESP32 之间建立 SPP 连接并且设置 IO 能力为 NoInputNoOutput ¶

在本例中，移动电话或 PC 为主机，ESP32 为从机。该示例展示了如何建立 SPP 连接。

Classic Bluetooth 初始化。

命令：
```
AT+BTINIT=1
```
响应：
```
OK
```
Classic Bluetooth SPP 协议初始化并且设置角色为 slave。

命令：
```
AT+BTSPPINIT=2
```
响应：
```
OK
```
设置 Classic Bluetooth 设备名称。

命令：
```
AT+BTNAME="EXAMPLE"
```
响应：
```
OK
```
设置 Classic Bluetooth 扫描模式为可发现可连接。

命令：
```
AT+BTSCANMODE=2
```
响应：
```
OK
```
设置 Classic Bluetooth 安全参数。设置 io_cap 为 NoInputNoOutput，pin_type 为 fixed，pin_code to 9527。

命令：
```
AT+BTSECPARAM=3,1,"9527"
```
响应：
```
OK
```
开启 Classic Bluetooth SPP 协议。

命令：
```
AT+BTSPPSTART
```
响应：
```
OK
```
移动电话或者 PC 发起连接。

移动电话或 PC 应能找到名为 “EXAMPLE” 的蓝牙设备。如果移动电话或 PC 发起连接并成功建立连接，ESP32 将提示：
```
+BTSPPCONN:0,"e0:24:81:47:90:bc"
```
说明：
- 您获取到的地址可能与上述响应中的不同。
发送 4 字节数据。

命令：
```
AT+BTSPPSEND=0,4
```
响应：
```
>
```
符号 > 表示 AT 准备好接收串口数据，此时您可以输入数据，当数据长度达到参数 <data_len> 的值时，执行写入操作。

输入 4 字节数据，例如输入数据是 test，之后 AT 将会输出以下信息。
```
OK
```
说明：
- 若输入的字节数目超过 AT+BTSPPSEND 命令设定的长度 (n)，则系统会响应 busy p...，并发送数据的前 n 个字节，发送完成后响应 OK。
- AT 输出 > 字符后，数据中的特殊字符不需要转义字符进行转义，也不需要以新行结尾（CR-LF）。
接收 4 字节数据。

假设移动电话或者 PC 发送 4 字节的数据（数据为 test），则系统会提示：
```
+BTDATA:4,test
```
断开 Classic Bluetooth SPP 连接。

命令：
```
AT+BTSPPDISCONN=0
```
响应：
```
+BTSPPDISCONN:0,"e0:24:81:47:90:bc"

OK
```
说明：
- 您获取到的地址可能与上述响应中的不同。

以透传模式在移动电话或者 PC 和 ESP32 之间建立 SPP 连接并且设置 IO 能力为 NoInputNoOutput ¶

在本例中，移动电话或 PC 为主机，ESP32 为从机。该示例展示了如何建立 SPP 连接。

Classic Bluetooth 初始化。

命令：
```
AT+BTINIT=1
```
响应：
```
OK
```
Classic Bluetooth SPP 协议初始化并且设置角色为 slave。

命令：
```
AT+BTSPPINIT=2
```
响应：
```
OK
```
设置 Classic Bluetooth 设备名称。

命令：
```
AT+BTNAME="EXAMPLE"
```
响应：
```
OK
```
设置 Classic Bluetooth 扫描模式为可发现可连接。

命令：
```
AT+BTSCANMODE=2
```
响应：
```
OK
```
设置 Classic Bluetooth 安全参数。设置 io_cap 为 NoInputNoOutput，pin_type 为 fixed，pin_code 为 9527。

命令：
```
AT+BTSECPARAM=3,1,"9527"
```
响应：
```
OK
```
开启 Classic Bluetooth SPP 协议。

命令：
```
AT+BTSPPSTART
```
响应：
```
OK
```
移动电话或者 PC 发起连接。

移动电话或 PC 应能找到名为 “EXAMPLE” 的蓝牙设备。如果移动电话或 PC 发起连接并成功建立连接，ESP32 将提示：
```
+BTSPPCONN:0,"e0:24:81:47:90:bc"
```
说明：
- 您获取到的地址可能与上述响应中的不同。
在透传模式下发送数据。

命令：
```
AT+BTSPPSEND
```
响应：
```
OK

>
```
上述响应表示 AT 已经进入透传模式。

说明：
- AT 进入透传模式后，串口收到的数据会传输到移动电话或者 PC 端。
停止发送数据。

在透传发送数据过程中，若识别到单独的一包数据 +++，则系统会退出透传发送。此时请至少等待 1 秒，再发下一条 AT 命令。请注意，如果直接用键盘打字输入 +++，有可能因时间太慢而不能被识别为连续的三个 +。更多介绍请参考 AT+BTSPPSEND。

重要

使用 +++ 可退出透传发送数据，回到正常 AT 命令模式。您也可以使用 AT+BTSPPSEND 命令恢复透传。
断开 Classic Bluetooth SPP 连接。

命令：
```
AT+BTSPPDISCONN=0
```
响应：
```
+BTSPPDISCONN:0,"e0:24:81:47:90:bc"

OK
```
说明：
- 您获取到的地址可能与上述响应中的不同。

在移动电话或者 PC 和 ESP32 之间建立 SPP 连接并且设置 IO 能力为 KeyboardOnly ¶

该过程基本和以普通传输模式在移动电话或者 PC 和 ESP32 之间建立 SPP 连接并且设置 IO 能力为 NoInputNoOutput 描述的一样。唯一的区别在于安全参数设置。

Classic Bluetooth 初始化。

命令：
```
AT+BTINIT=1
```
响应：
```
OK
```
Classic Bluetooth SPP 协议初始化并且设置角色为 slave。

命令：
```
AT+BTSPPINIT=2
```
响应：
```
OK
```
设置 Classic Bluetooth 设备名称。

命令：
```
AT+BTNAME="EXAMPLE"
```
响应：
```
OK
```
设置 Classic Bluetooth 扫描模式为可发现可连接。

命令：
```
AT+BTSCANMODE=2
```
响应：
```
OK
```
设置 Classic Bluetooth 安全参数。设置 io_cap 为 KeyboardOnly，pin_type 为 variable，pin_code 为 9527。

命令：
```
AT+BTSECPARAM=2,0,"9527"
```
响应：
```
OK
```
开启 Classic Bluetooth SPP 协议。

命令：
```
AT+BTSPPSTART
```
响应：
```
OK
```
移动电话或者 PC 发起连接。

移动电话或者 PC 可以发起连接并且产生 PIN 码，您可以在 ESP32 端输入 PIN 码。
```
AT+BTKEYREPLY=0,676572
```
如果连接建立成功，系统则会提示：
```
+BTSPPCONN:0,"e0:24:81:47:90:bc"
```
说明：
- 您输入的 PIN 码可能与上述命令中的不同。请使用真实的 PIN 码代替。
- 您获取到的地址可能与上述响应中的不同。
断开 Classic Bluetooth SPP 连接。

命令：
```
AT+BTSPPDISCONN=0
```
响应：
```
+BTSPPDISCONN:0,"e0:24:81:47:90:bc"

OK
```
说明：
- 您获取到的地址可能与上述响应中的不同。

在两个 ESP32 开发板之间建立 SPP 连接 ¶

下面是使用两块 ESP32 开发板的示例，一块作为主机，另一块作为从机。

重要

在以下步骤中以 主机 开头的操作只需要在主机端执行即可，以 从机 开头的操作只需要在从机端执行即可。如果操作没有特别指明在哪端操作，则需要在主机端和从机端都执行。

Classic Bluetooth 初始化。

命令：
```
AT+BTINIT=1
```
响应：
```
OK
```
Classic Bluetooth SPP 协议初始化。

主机：

命令：
```
AT+BTSPPINIT=1
```
响应：
```
OK
```
从机：

命令：
```
AT+BTSPPINIT=2
```
响应：
```
OK
```
设置 Classic Bluetooth 设备名称。

从机：

命令：
```
AT+BTNAME="EXAMPLE"
```
响应：
```
OK
```
设置 Classic Bluetooth 扫描模式为可发现可连接。

从机：

命令：
```
AT+BTSCANMODE=2
```
响应：
```
OK
```
设置 Classic Bluetooth 安全参数。设置 io_cap 为 NoInputNoOutput，pin_type 为 fixed，pin_code 为 9527。

从机：

命令：
```
AT+BTSECPARAM=3,1,"9527"
```
响应：
```
OK
```
开启 Classic Bluetooth SPP 协议。

从机：

命令：
```
AT+BTSPPSTART
```
响应：
```
OK
```

开启发现 Classic Bluetooth 周围设备。设置持续时间为 10 秒，可以收到的回应的数量为 10。

主机：

命令：

AT+BTSTARTDISC=0,10,10

响应：

+BTSTARTDISC:"10:f6:05:f9:bc:4f",realme V11 5G,0x2,0x3,0x2d0,-34
+BTSTARTDISC:"24:0a:c4:d6:e4:46",EXAMPLE,,,,-27
+BTSTARTDISC:"10:f6:05:f9:bc:4f",realme V11 5G,0x2,0x3,0x2d0,-33
+BTSTARTDISC:"24:0a:c4:d6:e4:46",EXAMPLE,,,,-25
+BTSTARTDISC:"ac:d6:18:47:0c:ae",,0x2,0x3,0x2d0,-72
+BTSTARTDISC:"24:0a:c4:d6:e4:46",EXAMPLE,,,,-26
+BTSTARTDISC:"10:f6:05:f9:bc:4f",,0x2,0x3,0x2d0,-41
+BTSTARTDISC:"24:0a:c4:2c:a8:a2",,,,,-50
+BTSTARTDISC:"24:0a:c4:d6:e4:46",EXAMPLE,,,,-26
+BTSTARTDISC:"10:f6:05:f9:bc:4f",realme V11 5G,0x2,0x3,0x2d0,-39
+BTSTARTDISC:"24:0a:c4:d6:e4:46",EXAMPLE,,,,-23
+BTSTARTDISC:"10:f6:05:f9:bc:4f",realme V11 5G,0x2,0x3,0x2d0,-36
+BTSTARTDISC:"10:f6:05:f9:bc:4f",realme V11 5G,0x2,0x3,0x2d0,-41
+BTSTARTDISC:"b4:a5:ac:16:14:8c",,0x2,0x3,0x2d0,-57
+BTSTARTDISC:"24:0a:c4:2c:a8:a2"
+BTSTARTDISC:"b4:a5:ac:16:14:8c"

OK

说明：

您的发现结果可能与上述响应中的不同。

建立 SPP 连接。

主机：

命令：
```
AT+BTSPPCONN=0,0,"24:0a:c4:d6:e4:46"
```
响应：
```
+BTSPPCONN:0,"24:0a:c4:d6:e4:46"

OK
```
说明：
- 输入上述命令时，请使用您的从机地址。
- 如果连接建立成功，从机端则会提示 +BTSPPCONN:0,"30:ae:a4:80:06:8e"。
断开 Classic Bluetooth SPP 连接。

从机：

命令：
```
AT+BTSPPDISCONN=0
```
响应：
```
+BTSPPDISCONN:0,"30:ae:a4:80:06:8e"

OK
```
说明：
- 主机和从机都可以主动断开连接。
- 如果连接被成功断开，主机端则会提示 +BTSPPDISCONN:0,"24:0a:c4:d6:e4:46"。

建立 A2DP 连接并启用 A2DP Sink 播放音乐 ¶

重要

使用 A2DP Sink 需要客户自己添加 I2S 部分的代码。初始化 I2S 部分的代码请参考 a2dp sink 例程。
decoder 芯片部分的驱动代码也需要客户自行添加或使用现成的开发板。

Classic Bluetooth 初始化。

命令：
```
AT+BTINIT=1
```
响应：
```
OK
```
Classic Bluetooth A2DP 协议初始化并且设置角色为 sink。

命令：
```
AT+BTA2DPINIT=2
```
响应：
```
OK
```
设置 Classic Bluetooth 设备名称。

命令：
```
AT+BTNAME="EXAMPLE"
```
响应：
```
OK
```
设置 Classic Bluetooth 扫描模式为可发现可连接。

命令：
```
AT+BTSCANMODE=2
```
响应：
```
OK
```
建立连接。

source 角色应能找到名为 “EXAMPLE” 的蓝牙设备。在本例中您可以使用您的移动电话发起连接。如果连接成功建立，ESP32 将提示：
```
+BTA2DPCONN:0,"e0:24:81:47:90:bc"
```
说明：
- 您获取到的地址可能与上述响应中的不同。
开始播放音乐。

命令：
```
AT+BTA2DPCTRL=0,1
```
响应：
```
OK
```
说明：
- 更多类型控制请参考 AT+BTA2DPCTRL。
停止播放音乐。

命令：
```
AT+BTA2DPCTRL=0,0
```
响应：
```
OK
```
说明：
- 更多类型控制请参考 AT+BTA2DPCTRL。

断开 A2DP 连接。

命令：

AT+BTA2DPDISCONN=0

响应：

OK
+BTA2DPDISCONN:0,"e0:24:81:47:90:bc"

查询和清除 Classic Bluetooth 加密设备列表 ¶

获取加密设备列表

命令：
```
AT+BTENCDEV?
```
响应：
```
+BTA2DPDISCONN:0,"e0:24:81:47:90:bc"
OK
```
说明：
- 如果之前没有设备成功绑定过，AT 只会提示 OK。
清除 Classic Bluetooth 加密设备列表。

有两种方式可以清除加密设备列表。
1. 通过索引值删除加密列表中的指定设备。
  
  命令：
```
AT+BTENCCLEAR=0
```
  响应：
```
OK
```
2. 删除加密列表中的全部设备。
  
  命令：
```
AT+BTENCCLEAR
```
  响应：
```
OK
```

Sleep AT 示例¶

[English]

本文档简要介绍并举例说明如何在 ESP32 和 ESP32-C3 系列产品上使用 AT 命令设置睡眠模式。

简介
在 Wi-Fi 模式下设置为 Modem-sleep 模式
在 Wi-Fi 模式下设置为 Light-sleep 模式
在蓝牙广播态下设置为 Modem-sleep 模式
在蓝牙连接态下设置为 Modem-sleep 模式
在蓝牙广播态下设置为 Light-sleep 模式
在蓝牙连接态下设置为 Light-sleep 模式
设置为 Deep-sleep 模式

简介 ¶

ESP32 和 ESP32-C3 系列采用先进的电源管理技术，可以在不同的电源模式之间切换。当前，ESP-AT 支持以下四种功耗模式（更多休眠模式请参考技术规格书）：

Active 模式：芯片射频处于工作状态。芯片可以接收、发射和侦听信号。
Modem-sleep 模式：CPU 可运行，时钟可被配置。Wi-Fi 基带、蓝牙基带和射频关闭。
Light-sleep 模式：CPU 暂停运行。RTC 存储器和外设以及 ULP 协处理器运行。任何唤醒事件（MAC、主机、RTC 定时器或外部中断）都会唤醒芯片。
Deep-sleep 模式：CPU 和大部分外设都会掉电，只有 RTC 存储器和 RTC 外设处于工作状态。

默认情况下，ESP32 和 ESP32-C3 会在系统复位后进入 Active 模式。当 CPU 不需要一直工作时，例如等待外部活动唤醒时，系统可以进入低功耗模式。

对于 ESP32 和 ESP32-C3 的功耗，请参考 ESP32 系列芯片技术规格书和 ESP32-C3 系列芯片技术规格书。

注解

将分别描述在 Wi-Fi 模式和蓝牙模式下将 ESP32 和 ESP32-C3 设置为睡眠模式。
在单 Wi-Fi 模式下，只有 station 模式支持 Modem-sleep 模式和 Light-sleep 模式。
对于蓝牙模式下的 Light-sleep 模式，请确保外部存在 32 KHz 晶振。如果外部不存在 32 KHz 晶振，ESP-AT 将工作在 Modem-sleep 模式。

测量方法¶

为避免功耗测试过程中出现一些不必要的干扰，建议使用集成芯片的乐鑫模组进行测试。

硬件连接可参考如下。

ESP32 系列

ESP32-C3 系列

在 Wi-Fi 模式下设置为 Modem-sleep 模式 ¶

设置 Wi-Fi 为 station 模式。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接路由器。

命令：
```
AT+CWJAP="espressif","1234567890"
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。
设置休眠模式为 Modem-sleep 模式。

命令：
```
AT+SLEEP=1
```
响应：
```
OK
```

注解

RF 将根据 AP 的 DTIM 定期关闭（路由器一般设置 DTIM 为 1）。
当 ESP32 模组的 CPU 频率为 80 MHz 并且模组处于单 Wi-Fi 模式下时，Modem-sleep 模式下的平均电流约为 21 mA。
当 ESP32-C3 模组的 CPU 频率为 160 MHz 并且模组处于单 Wi-Fi 模式下时，Modem-sleep 模式下的平均电流约为 20 mA。

在 Wi-Fi 模式下设置为 Light-sleep 模式 ¶

设置 Wi-Fi 为 station 模式。

命令：
```
AT+CWMODE=1
```
响应：
```
OK
```
连接路由器。设置监听间隔为 3。

命令：
```
AT+CWJAP="espressif","1234567890",,,,3
```
响应：
```
WIFI CONNECTED
WIFI GOT IP

OK
```
说明：
- 您输入的 SSID 和密码可能跟上述命令中的不同。请使用您的路由器的 SSID 和密码。
设置休眠模式为 Light-sleep 模式。

命令：
```
AT+SLEEP=2
```
响应：
```
OK
```

注解

CPU 将会自动休眠，RF 则会根据 AT+CWJAP 设置的监听间隔定期关闭。
当 ESP32 模组处于单 Wi-Fi 模式下时，Light-sleep 模式下平均电流约为 0.8 mA。
当 ESP32-C3 模组处于单 Wi-Fi 模式下时，Light-sleep 模式下平均电流约为 130 uA。

在蓝牙广播态下设置为 Modem-sleep 模式 ¶

初始化为角色为蓝牙服务端。

命令：
```
AT+BLEINIT=2
```
响应：
```
OK
```
设置蓝牙广播参数。设置蓝牙广播间隔为 1 s。

命令：
```
AT+BLEADVPARAM=1600,1600,0,0,7,0,0,"00:00:00:00:00:00"
```
响应：
```
OK
```
开始广播

命令：
```
AT+BLEADVSTART
```
响应：
```
OK
```
禁用 Wi-Fi。

命令：
```
AT+CWMODE=0
```
响应：
```
OK
```
设置休眠模式为 Modem-sleep 模式。

命令：
```
AT+SLEEP=1
```
响应：
```
OK
```

注解

当 ESP32 模组的 CPU 频率为 80 MHz 时并且模组处于单蓝牙广播态模式时，Modem-sleep 模式下的平均电流约为 23 mA。
当 ESP32-C3 模组的 CPU 频率为 160 MHz 时并且模组处于单蓝牙广播态模式时，Modem-sleep 模式下的平均电流约为 20 mA。

在蓝牙连接态下设置为 Modem-sleep 模式 ¶

初始化为角色为蓝牙服务端。

命令：
```
AT+BLEINIT=2
```
响应：
```
OK
```
开启蓝牙广播。

命令：
```
AT+BLEADVSTART
```
响应：
```
OK
```
等待连接。

如果连接建立成功，则 AT 将会提示：
```
+BLECONN:0,"47:3f:86:dc:e4:7d"
+BLECONNPARAM:0,0,0,6,0,500
+BLECONNPARAM:0,0,0,24,0,500

OK
```
说明：
- 在这个示例中，蓝牙客户端的地址为 47:3f:86:dc:e4:7d。
- 对于提示信息（+BLECONN and +BLECONNPARAM），请参考 AT+BLECONN 和 AT+BLECONNPARAM 获取更多信息。
更新蓝牙连接参数。设置蓝牙连接间隔为 1 s。

命令：
```
AT+BLECONNPARAM=0,800,800,0,500
```
响应：
```
OK
```
如果连接参数更新成功，则 AT 将会提示：
```
+BLECONNPARAM:0,800,800,800,0,500
```
说明：
- 对于提示信息（+BLECONNPARAM），请参考 AT+BLECONNPARAM 获取更多信息。
禁用 Wi-Fi。

命令：
```
AT+CWMODE=0
```
响应：
```
OK
```
设置休眠模式为 Modem-sleep 模式。

命令：
```
AT+SLEEP=1
```
响应：
```
OK
```

注解

当 ESP32 的 CPU 频率为 80 MHz 时并且处于蓝牙连接态模式时，Modem-sleep 模式下的平均电流约为 23 mA。
当 ESP32-C3 的 CPU 频率为 160 MHz 时并且处于蓝牙连接态模式时，Modem-sleep 模式下的平均电流约为 20 mA。

在蓝牙广播态下设置为 Light-sleep 模式 ¶

初始化为角色为蓝牙服务端。

命令：
```
AT+BLEINIT=2
```
响应：
```
OK
```
设置蓝牙广播参数。设置蓝牙广播间隔为 1 s。

命令：
```
AT+BLEADVPARAM=1600,1600,0,0,7,0,0,"00:00:00:00:00:00"
```
响应：
```
OK
```
开始广播。

命令：
```
AT+BLEADVSTART
```
响应：
```
OK
```
禁用 Wi-Fi。

命令：
```
AT+CWMODE=0
```
响应：
```
OK
```
设置休眠模式为 Light-sleep 模式。

命令：
```
AT+SLEEP=2
```
响应：
```
OK
```

注解

当 ESP32 模组处于蓝牙广播态模式时，Light-sleep 模式下的平均电流约为 0.8 mA。
当 ESP32-C3 模组处于蓝牙广播态模式时，Light-sleep 模式下的平均电流约为 130 uA。

在蓝牙连接态下设置为 Light-sleep 模式 ¶

初始化为角色为蓝牙服务端。

命令：
```
AT+BLEINIT=2
```
响应：
```
OK
```
开始广播。

命令：
```
AT+BLEADVSTART
```
响应：
```
OK
```
等待连接。

如果连接建立成功，则 AT 将会提示：
```
+BLECONN:0,"47:3f:86:dc:e4:7d"
+BLECONNPARAM:0,0,0,6,0,500
+BLECONNPARAM:0,0,0,24,0,500

OK
```
说明：
- 在这个示例中，蓝牙客户端的地址为 47:3f:86:dc:e4:7d。
- 对于提示信息（+BLECONN and +BLECONNPARAM），请参考 AT+BLECONN 和 AT+BLECONNPARAM 获取更多信息。
更新蓝牙连接参数。设置蓝牙连接间隔为 1 s。

命令：
```
AT+BLECONNPARAM=0,800,800,0,500
```
响应：
```
OK
```
如果连接参数更新成功，则 AT 将会提示：
```
+BLECONNPARAM:0,800,800,800,0,500
```
说明：
- 对于提示信息（+BLECONNPARAM），请参考 AT+BLECONNPARAM 获取更多信息。
禁用 Wi-Fi。

命令：
```
AT+CWMODE=0
```
响应：
```
OK
```
设置休眠模式为 Light-sleep 模式。

命令：
```
AT+SLEEP=2
```
响应：
```
OK
```

注解

当 ESP32 模组处于蓝牙连接态模式时，Light-sleep 模式下的平均电流约为 0.8 mA。
当 ESP32-C3 模组处于蓝牙连接态模式时，Light-sleep 模式下的平均电流约为 130 uA。

设置为 Deep-sleep 模式 ¶

设置休眠模式为 Deep-sleep 模式。设置 deep-sleep 时间为 3600000 ms。

命令：
```
AT+GSLP=3600000
```
响应：
```
OK
```
说明：
- 设定时间到后，设备自动唤醒，调用深度睡眠唤醒桩，然后加载应用程序。
- 对于 Deep-sleep 模式，唯一的唤醒方法是定时唤醒。

注解

当 ESP32 模组处于 Deep-sleep 模式时，Deep-sleep 模式下的平均电流约为 10 uA。
当 ESP32-C3 模组处于 Deep-sleep 模式时，Deep-sleep 模式下的平均电流约为 5 uA。

如何编译和开发自己的 AT 工程¶

[English]

编译 ESP-AT 工程¶

[English]

本文档详细介绍了如何编译 ESP-AT 工程，并将生成的固件烧录到 ESP 设备中，包括 ESP32 和 ESP32-C3。当默认的官方发布的固件无法满足需求时，如您需要自定义 AT 端口管脚、低功耗蓝牙服务以及分区等，那么就需要编译 ESP-AT 工程。

文档结构如下所示。

概述：ESP-AT 工程编译步骤概述。
ESP32 和 ESP32-C3 系列：ESP32、ESP32-C3 系列 AT 工程编译的详细步骤。

概述¶

在编译 ESP-AT 工程之前，首先需要学习使用 ESP-IDF，并创建 ESP-IDF 的编译环境，这是因为 ESP-AT 是基于 ESP-IDF 的工程。

环境创建完成后，安装工具和 ESP-AT SDK。然后，将 ESP 设备连接至 PC，使用 ./build.py menuconfig 配置工程。最后，编译工程，并将生成的 bin 文件烧录到 ESP 设备上。

注解

请注意可能出现管脚冲突，如果选择 AT through HSPI，那么可通过 ./build.py menuconfig –> Component config –> AT –> AT hspi settings 获取 HSPI 管脚信息。

ESP32 和 ESP32-C3 系列¶

本节介绍了如何为 ESP32 和 ESP32-C3 系列编译 ESP-AT 工程。

ESP-IDF 快速入门¶

在编译 ESP-AT 工程之前，请先学习使用 ESP-IDF，因为 ESP-AT 是基于 ESP-IDF 开发的，不同系列的 AT 工程支持的 ESP-IDF 版本也不尽相同：

不同系列支持的 ESP-IDF 版本¶
工程	IDF 版本	IDF 文档版本
ESP32 ESP-AT	release/v4.2	ESP-IDF 快速入门文档 v4.2
ESP32-C3 ESP-AT	release/v4.3	ESP-IDF 快速入门文档 v4.3

首先，按照 ESP-IDF 快速入门 文档中的第 1 至 4 步，为 ESP-IDF 创建开发环境（点击上表中的相应链接跳转至文档）。

然后，根据 ESP-IDF 快速入门 文档中的第 5 至 10 步，创建一个简单的 hello_world 工程，确保环境能够正常工作，并熟悉如何基于 ESP-IDF 创建新工程。这一步并非必要，但是强烈建议您进行这一步。

在完成所有 10 个步骤后（如果没有，至少完成前 4 步），可以进行下面专门针对 ESP-AT 工程的步骤。

注解

在上述过程中，请不要设置 IDF_PATH，否则以后编译 ESP-AT 项目时会遇到一些问题。

获取 ESP-AT¶

编译 ESP-AT 工程需下载乐鑫提供的软件库文件 ESP-AT 仓库。

打开终端，切换到您要保存 ESP-AT 的工作目录，使用 git clone 命令克隆远程仓库，获取 ESP-AT 的本地副本。以下是不同操作系统的获取方式。

Linux 或 macOS

cd ~/esp
git clone --recursive https://github.com/espressif/esp-at.git

Windows
- 对于 ESP32 系列模组，推荐您以管理员权限运行 ESP-IDF 4.2 CMD。
- 对于 ESP32-C3 系列模组，推荐您以管理员权限运行 ESP-IDF 4.3 CMD。
```
cd %userprofile%\esp
git clone --recursive https://github.com/espressif/esp-at.git
```

如果您位于中国或访问 GitHub 有困难，也可以使用 git clone https://gitee.com/EspressifSystems/esp-at.git 来获取 ESP-AT，可能会更快。

ESP-AT 将下载至 Linux 和 macOS 的 ~/esp/esp-at、Windows 的 %userprofile%\esp\esp-at。

注解

在本文档中，Linux 和 macOS 操作系统中 ESP-AT 的默认安装路径为 ~/esp；Windows 操作系统的默认路径为 %userprofile%\esp。您也可以将 ESP-AT 安装在任何其它路径下，但请注意在使用命令行时进行相应替换。注意，ESP-AT 不支持带有空格的路径。

连接设备¶

使用 USB 线将您的设备连接到 PC 上，以下载固件和输出日志，详情请见硬件连接。注意，如果您在编译过程中不发送 AT 命令和接收 AT 响应，则不需要建立 “AT 命令/响应” 连接。关于更改默认端口管脚的信息请参考如何设置 AT 端口管脚。

配置¶

此步骤中，您将在 esp-at 文件夹下克隆 esp-idf 文件夹，在这个新克隆的文件夹中设置开发环境，最后配置工程。

前往 ~/esp/esp-at 目录。
运行项目配置工具 menuconfig 来配置。

./build.py menuconfig

如果是第一次编译工程，请为 ESP 设备选择以下配置选项。

选择 Platform name，例如 ESP32 系列设备选择 PLATFORM_ESP32，ESP32-C3 系列设备选择 PLATFORM_ESP32C3。Platform name 由 factory_param_data.csv 定义。

选择 Module name，例如 ESP32-WROOM-32D 模组选择 WROOM-32。Module name 由 factory_param_data.csv 定义。

启用或禁用 silence mode，启用时将删除一些日志并减少固件的大小。一般情况下请禁用。

如果 build/module_info.json 文件存在，上述三个配置选项将不会出现。因此，如果您想重新配置模组信息，请删除该文件。

现在，esp-idf 文件夹已经被创建在 esp-at 文件夹中。这个 esp-idf 与 ESP-IDF 快速入门中的不同。

如果您遇到以下任意一种情况，可以继续进行进行下一步，在 esp-at/esp-idf 中设置开发环境。
终端提示如下错误信息。
The following Python requirements are not satisfied:
...
Please follow the instructions found in the "Set up the tools" section of ESP-IDF Get Started Guide.
如果您曾经编译过某个 ESP 系列的 AT 工程，而现在想切换到另一个系列进行编译，则必须运行 rm -rf esp-idf 来删除旧的 esp-idf，然后再进行下一步操作。

您的 esp-idf 已经升级。

在 esp-at/esp-idf 文件夹中设置开发环境。

如果是第一次编译 ESP-AT 工程，按照 ESP-IDF 快速入门 文档中的第 3 步在该文件夹下设置工具链。

每次编译 ESP-AT 工程时，请按照 ESP-IDF 快速入门 文档中的第 4 步在该文件夹下设置环境变量。
如果未安装 ``pyyaml`` 和 ``xlrd`` 包，请使用 pip 在该文件夹下安装 ``pyyaml`` 和 ``xlrd``。
python -m pip install pyyaml xlrd

如果以上所有步骤都正确，再次运行 ./build.py menuconfig 时则会显示下面的菜单：

此菜单可以用来配置每个工程，如更改 AT 端口管脚、启用经典蓝牙功能等，如果不修改配置，那么就会按照默认配置编译工程。

编译工程¶

运行以下命令编译工程。

./build.py build

如果启用了蓝牙功能，固件尺寸会大大增加。请确保它不超过 ota 分区的大小。
编译完成后会在 build/factory 路径下生成打包好的量产固件。更多信息请参见 ESP-AT 固件差异。

烧录到设备¶

运行以下命令将生成的固件烧录到 ESP 设备上。

./build.py -p (PORT) flash

注意，请用 ESP 设备的串口名称替换 PORT。
或者按照提示信息将固件烧录到 flash 中。注意，仍然需要替换 PORT。
如果 ESP-AT bin 不能启动，并且打印出 “ota data partition invalid”，请运行 ./build.py erase_flash 来擦除整个 flash，然后重新烧录 AT 固件。

如何设置 AT 端口管脚¶

[English]

本文档介绍了如何修改 ESP32 和 ESP32-C3 系列固件中的 AT port 管脚。默认情况下，ESP-AT 使用两个 UART 接口作为 AT 端口：一个用于输出日志（以下称为日志端口），另一个用于发送 AT 命令和接收响应（以下称为命令端口）。

要修改 ESP 设备的 AT 端口管脚，应该：

克隆 ESP-AT 工程。
在 menuconfig 配置工具或 factory_param_data.csv 表格中修改对应管脚。
编译工程，在 build/customized_partitions/factory_param.bin 生成新的 bin 文件。
将新的 bin 文件烧录进设备。

本文档重点介绍如何修改管脚，点击上面的链接了解其它步骤的详细信息。以下是本文档的结构。

ESP32 系列
ESP32-C3 系列

注解

使用其它接口作为 AT 命令接口请参考使用 AT SPI 接口 , AT through SPI 和使用 AT 套接字接口。

ESP32 系列¶

ESP32 AT 固件的日志端口和命令端口管脚可以自定义为其它管脚，请参阅《ESP32 技术参考手册》查看可使用的管脚。

修改日志端口管脚¶

默认情况下，乐鑫提供的 ESP32 AT 固件使用以下 UART0 管脚输出日志：

TX：GPIO1
RX：GPIO3

在编译 ESP-AT 工程时，可使用 menuconfig 配置工具将其修改为其它管脚：

./build.py menuconfig –> Component config –> Common ESP-related –> UART for console output
./build.py menuconfig –> Component config –> Common ESP-related –> UART TX on GPIO#
./build.py menuconfig –> Component config –> Common ESP-related –> UART RX on GPIO#

修改命令端口管脚¶

默认情况下，UART1 用于发送 AT 命令和接收 AT 响应，其管脚定义在 factory_param_data.csv 表格中的 uart_port、uart_tx_pin、uart_rx_pin、uart_cts_pin 和 uart_rts_pin 列。

您可以直接在 factory_param_data.csv 表中修改端口管脚：

打开您本地的 factory_param_data.csv。
找到模组所在的行。
根据需要设置 uart_port。
根据需要设置 uart_tx_pin 和 uart_rx_pin。
若不需要使用硬件流控功能，请将 uart_cts_pin 和 uart_rts_pin 设置为 -1。
保存表格。

ESP32-C3 系列¶

ESP32-C3 AT 固件的日志端口和命令端口管脚可以自定义为其它管脚，请参阅《ESP32-C3 技术参考手册》查看可使用的管脚。

修改日志端口管脚¶

默认情况下，乐鑫提供的 ESP32-C3 AT 固件使用以下 UART0 管脚输出日志：

TX：GPIO21
RX：GPIO20

在编译 ESP-AT 工程时，可使用 menuconfig 配置工具将其修改为其它管脚：

./build.py menuconfig –> Component config –> Common ESP-related –> UART for console output
./build.py menuconfig –> Component config –> Common ESP-related –> UART TX on GPIO#
./build.py menuconfig –> Component config –> Common ESP-related –> UART RX on GPIO#

修改命令端口管脚¶

默认情况下，UART1 用于发送 AT 命令和接收 AT 响应，其管脚定义在 factory_param_data.csv 表格中的 uart_port、uart_tx_pin、uart_rx_pin、uart_cts_pin 和 uart_rts_pin 列。

您可以直接在 factory_param_data.csv 表中修改端口管脚：

打开您本地的 factory_param_data.csv。
找到模组所在的行。
根据需要设置 uart_port。
根据需要设置 uart_tx_pin 和 uart_rx_pin。
若不需要使用硬件流控功能，请将 uart_cts_pin 和 uart_rts_pin 设置为 -1。
保存表格。

添加自定义 AT 命令¶

[English]

本文档详细介绍了如何在 ESP-AT 工程中添加用户定义的 AT 命令，以 AT+TEST 命令为例展示每个步骤的示例代码。

自定义一个基本的、功能良好的命令至少需要以下两个步骤。

定义 AT 命令
注册 AT 命令

这一步介绍新命令的运行及响应情况。

尝试一下吧

其余的步骤适用于定义相对复杂的命令，可根据您的需要进行选择。

定义返回消息
获取命令参数
省略命令参数
阻塞命令的执行
从 AT 命令端口获取输入的数据

AT 命令集的源代码不开源，以库文件的形式呈现，它也是解析自定义的 AT 命令的基础。

定义 AT 命令¶

在定义 AT 命令之前，请先决定 AT 命令的名称和类型。

命令命名规则：

命令应以 + 符号开头。
支持字母 (A~Z, a~z)、数字 (0~9) 及其它一些字符 (!、 %、-、.、/、:、_)，详情请见 AT 命令分类。

命令类型：

每条 AT 命令最多可以有四种类型：测试命令、查询命令、设置命令和执行命令，更多信息参见 AT 命令分类。

然后，定义所需类型的命令。假设 AT+TEST 支持所有的四种类型，下面是定义每种类型的示例代码。

测试命令：

uint8_t at_test_cmd_test(uint8_t *cmd_name)
{
    uint8_t buffer[64] = {0};

    snprintf((char *)buffer, 64, "this cmd is test cmd: %s\r\n", cmd_name);

    esp_at_port_write_data(buffer, strlen((char *)buffer));

    return ESP_AT_RESULT_CODE_OK;
}

查询命令：

uint8_t at_query_cmd_test(uint8_t *cmd_name)
{
    uint8_t buffer[64] = {0};

    snprintf((char *)buffer, 64, "this cmd is query cmd: %s\r\n", cmd_name);

    esp_at_port_write_data(buffer, strlen((char *)buffer));

    return ESP_AT_RESULT_CODE_OK;
}

设置命令：

uint8_t at_setup_cmd_test(uint8_t para_num)
{
    int32_t para_int_1 = 0;
    uint8_t *para_str_2 = NULL;
    uint8_t num_index = 0;
    uint8_t buffer[64] = {0};

    if (esp_at_get_para_as_digit(num_index++, &para_int_1) != ESP_AT_PARA_PARSE_RESULT_OK) {
        return ESP_AT_RESULT_CODE_ERROR;
    }

    if (esp_at_get_para_as_str(num_index++, &para_str_2) != ESP_AT_PARA_PARSE_RESULT_OK) {
        return ESP_AT_RESULT_CODE_ERROR;
    }

    snprintf((char *)buffer, 64, "this cmd is setup cmd and cmd num is: %u\r\n", para_num);
    esp_at_port_write_data(buffer, strlen((char *)buffer));

    memset(buffer, 0, 64);
    snprintf((char *)buffer, 64, "first parameter is: %d\r\n", para_int_1);
    esp_at_port_write_data(buffer, strlen((char *)buffer));

    memset(buffer, 0, 64);
    snprintf((char *)buffer, 64, "second parameter is: %s\r\n", para_str_2);
    esp_at_port_write_data(buffer, strlen((char *)buffer));

    return ESP_AT_RESULT_CODE_OK;
}

执行命令：

uint8_t at_exe_cmd_test(uint8_t *cmd_name)
{
    uint8_t buffer[64] = {0};

    snprintf((char *)buffer, 64, "this cmd is execute cmd: %s\r\n", cmd_name);

    esp_at_port_write_data(buffer, strlen((char *)buffer));

    return ESP_AT_RESULT_CODE_OK;
}

最后，调用 esp_at_cmd_struct 来定义 AT 命令的名称和支持的类型，下面的示例代码定义了名称为 +TEST``（省略了 ``AT）并支持所有四种类型的命令。

static esp_at_cmd_struct at_custom_cmd[] = {
    {"+TEST", at_test_cmd_test, at_query_cmd_test, at_setup_cmd_test, at_exe_cmd_test},
};

如果不定义某个类型，将其设置为 NULL。

注册 AT 命令¶

调用 API esp_at_custom_cmd_array_regist() 来注册 AT 命令，以下是注册 AT+TEST 的示例代码。

esp_at_custom_cmd_array_regist(at_custom_cmd, sizeof(at_custom_cmd) / sizeof(at_custom_cmd[0]));

注解

建议把 esp_at_custom_cmd_array_regist 加入 app_main() 中的 at_custom_init()。

尝试一下吧¶

如果你已经完成了上述两个步骤，请编译 ESP-AT 工程并烧录固件，该命令即可在您的设备上正常运行。尝试运行一下吧！

下面是 AT+TEST 的运行情况。

测试命令：

AT+TEST=?

响应：

AT+TEST=?
this cmd is test cmd: +TEST

OK

查询命令：

AT+TEST?

响应：

AT+TEST?
this cmd is query cmd: +TEST

OK

设置命令：

AT+TEST=1,"espressif"

响应：

AT+TEST=1,"espressif"
this cmd is setup cmd and cmd num is: 2
first parameter is: 1
second parameter is: espressif

OK

执行命令：

AT+TEST

响应：

AT+TEST
this cmd is execute cmd: +TEST

OK

定义返回消息¶

ESP-AT 已经在 esp_at_result_code_string_index 定义了一些返回消息，更多返回消息请参见 AT 消息。

除了通过 return 模式返回消息，也可调用 API esp_at_response_result() 来返回命令执行结果。可在代码中同时使用 API 和 ESP_AT_RESULT_CODE_SEND_OK 及 ESP_AT_RESULT_CODE_SEND_FAIL。

例如，当使用 AT+TEST 的执行命令向服务器或 MCU 发送数据时，用 esp_at_response_result() 来返回发送结果，用 return 模式来返回命令执行结果，示例代码如下。

uint8_t at_exe_cmd_test(uint8_t *cmd_name)
{
    uint8_t buffer[64] = {0};

    snprintf((char *)buffer, 64, "this cmd is execute cmd: %s\r\n", cmd_name);

    esp_at_port_write_data(buffer, strlen((char *)buffer));

    // 向服务器或 MCU 发送数据的自定义操作
    send_data_to_server();

    // 返回 SEND OK
    esp_at_response_result(ESP_AT_RESULT_CODE_SEND_OK);

    return ESP_AT_RESULT_CODE_OK;
}

运行命令及返回的响应：

AT+TEST
this cmd is execute cmd: +TEST

SEND OK

OK

获取命令参数¶

ESP-AT 提供以下两个 API 获取命令参数。

esp_at_get_para_as_digit() 可获取数字参数。
esp_at_get_para_as_str() 可获取字符串参数。

示例请见执行命令。

省略命令参数¶

本节介绍如何设置某些命令参数为可选参数。

省略首位或中间参数
省略最后一位参数

省略首位或中间参数¶

假设您想将 AT+TEST 命令的 <param_2> 和 <param_3> 参数设置为可选参数，其中 <param_2> 为数字参数，<param_3> 为字符串参数。

AT+TEST=<param_1>[,<param_2>][,<param_3>],<param_4>

实现代码如下。

uint8_t at_setup_cmd_test(uint8_t para_num)
{
    int32_t para_int_1 = 0;
    int32_t para_int_2 = 0;
    uint8_t *para_str_3 = NULL;
    uint8_t *para_str_4 = NULL;
    uint8_t num_index = 0;
    uint8_t buffer[64] = {0};
    esp_at_para_parse_result_type parse_result = ESP_AT_PARA_PARSE_RESULT_OK;

    snprintf((char *)buffer, 64, "this cmd is setup cmd and cmd num is: %u\r\n", para_num);
    esp_at_port_write_data(buffer, strlen((char *)buffer));

    parse_result = esp_at_get_para_as_digit(num_index++, &para_int_1);
    if (parse_result != ESP_AT_PARA_PARSE_RESULT_OK) {
        return ESP_AT_RESULT_CODE_ERROR;
    } else {
        memset(buffer, 0, 64);
        snprintf((char *)buffer, 64, "first parameter is: %d\r\n", para_int_1);
        esp_at_port_write_data(buffer, strlen((char *)buffer));
    }

    parse_result = esp_at_get_para_as_digit(num_index++, &para_int_2);
    if (parse_result != ESP_AT_PARA_PARSE_RESULT_OMITTED) {
        if (parse_result != ESP_AT_PARA_PARSE_RESULT_OK) {
            return ESP_AT_RESULT_CODE_ERROR;
        } else {
            // 示例代码
            // 需要自定义操作
            memset(buffer, 0, 64);
            snprintf((char *)buffer, 64, "second parameter is: %d\r\n", para_int_2);
            esp_at_port_write_data(buffer, strlen((char *)buffer));
        }
    } else {
        // 示例代码
        // 省略第二个参数
        // 需要自定义操作
        memset(buffer, 0, 64);
        snprintf((char *)buffer, 64, "second parameter is omitted\r\n");
        esp_at_port_write_data(buffer, strlen((char *)buffer));
    }

    parse_result = esp_at_get_para_as_str(num_index++, &para_str_3);
    if (parse_result != ESP_AT_PARA_PARSE_RESULT_OMITTED) {
        if (parse_result != ESP_AT_PARA_PARSE_RESULT_OK) {
            return ESP_AT_RESULT_CODE_ERROR;
        } else {
            // 示例代码
            // 需自定义操作
            memset(buffer, 0, 64);
            snprintf((char *)buffer, 64, "third parameter is: %s\r\n", para_str_3);
            esp_at_port_write_data(buffer, strlen((char *)buffer));
        }
    } else {
        // 示例代码
        // 省略第三个参数
        // 需自定义操作
        memset(buffer, 0, 64);
        snprintf((char *)buffer, 64, "third parameter is omitted\r\n");
        esp_at_port_write_data(buffer, strlen((char *)buffer));
    }

    parse_result = esp_at_get_para_as_str(num_index++, &para_str_4);
    if (parse_result != ESP_AT_PARA_PARSE_RESULT_OK) {
        return ESP_AT_RESULT_CODE_ERROR;
    } else {
        memset(buffer, 0, 64);
        snprintf((char *)buffer, 64, "fourth parameter is: %s\r\n", para_str_4);
        esp_at_port_write_data(buffer, strlen((char *)buffer));
    }

    return ESP_AT_RESULT_CODE_OK;
}

注解

如果输入的字符串参数为 ""，则该参数没有被省略。

省略最后一位参数¶

假设 AT+TEST 命令的 <param_3> 参数为字符串参数，且为最后一位参数，您想将它设置为可选参数。

AT+TEST=<param_1>,<param_2>[,<param_3>]

则有以下两种省略情况。

AT+TEST=<param_1>,<param_2>
AT+TEST=<param_1>,<param_2>,

实现代码如下。

uint8_t at_setup_cmd_test(uint8_t para_num)
{
    int32_t para_int_1 = 0;
    uint8_t *para_str_2 = NULL;
    uint8_t *para_str_3 = NULL;
    uint8_t num_index = 0;
    uint8_t buffer[64] = {0};
    esp_at_para_parse_result_type parse_result = ESP_AT_PARA_PARSE_RESULT_OK;

    snprintf((char *)buffer, 64, "this cmd is setup cmd and cmd num is: %u\r\n", para_num);
    esp_at_port_write_data(buffer, strlen((char *)buffer));

    parse_result = esp_at_get_para_as_digit(num_index++, &para_int_1);
    if (parse_result != ESP_AT_PARA_PARSE_RESULT_OK) {
        return ESP_AT_RESULT_CODE_ERROR;
    } else {
        memset(buffer, 0, 64);
        snprintf((char *)buffer, 64, "first parameter is: %d\r\n", para_int_1);
        esp_at_port_write_data(buffer, strlen((char *)buffer));
    }

    parse_result = esp_at_get_para_as_str(num_index++, &para_str_2);
    if (parse_result != ESP_AT_PARA_PARSE_RESULT_OK) {
        return ESP_AT_RESULT_CODE_ERROR;
    } else {
        memset(buffer, 0, 64);
        snprintf((char *)buffer, 64, "second parameter is: %s\r\n", para_str_2);
        esp_at_port_write_data(buffer, strlen((char *)buffer));
    }

    if (num_index == para_num) {
        memset(buffer, 0, 64);
        snprintf((char *)buffer, 64, "third parameter is omitted\r\n");
        esp_at_port_write_data(buffer, strlen((char *)buffer));
    } else {
        parse_result = esp_at_get_para_as_str(num_index++, &para_str_3);
        if (parse_result != ESP_AT_PARA_PARSE_RESULT_OMITTED) {
            if (parse_result != ESP_AT_PARA_PARSE_RESULT_OK) {
                return ESP_AT_RESULT_CODE_ERROR;
            } else {
                // 示例代码
                // 需自定义操作
                memset(buffer, 0, 64);
                snprintf((char *)buffer, 64, "third parameter is: %s\r\n", para_str_3);
                esp_at_port_write_data(buffer, strlen((char *)buffer));
            }
        } else {
            // 示例代码
            // 省略第三个参数
            // 需自定义操作
            memset(buffer, 0, 64);
            snprintf((char *)buffer, 64, "third parameter is omitted\r\n");
            esp_at_port_write_data(buffer, strlen((char *)buffer));
        }
    }

    return ESP_AT_RESULT_CODE_OK;
}

注解

如果输入的字符串参数为 ""，则该参数没有被省略。

阻塞命令的执行¶

有时您想阻塞某个命令的执行，等待另一个执行结果，然后系统基于这个结果可能会返回不同的值。

一般来说，这类命令需要与其它任务的结果进行同步。

推荐使用 semaphore 来同步。

示例代码如下。

xSemaphoreHandle at_operation_sema = NULL;

uint8_t at_exe_cmd_test(uint8_t *cmd_name)
{
    uint8_t buffer[64] = {0};

    snprintf((char *)buffer, 64, "this cmd is execute cmd: %s\r\n", cmd_name);

    esp_at_port_write_data(buffer, strlen((char *)buffer));

    // 示例代码
    // 不必在此处创建 semaphores
    at_operation_sema = xSemaphoreCreateBinary();
    assert(at_operation_sema != NULL);

    // 阻塞命令的执行
    // 等待另一个执行的结果
    // 其它任务可调用 xSemaphoreGive 来释放 semaphore
    xSemaphoreTake(at_operation_sema, portMAX_DELAY);

    return ESP_AT_RESULT_CODE_OK;
}

从 AT 命令端口获取输入的数据¶

ESP-AT 支持从 AT 命令端口访问输入的数据，为此提供以下两个 API。

esp_at_port_enter_specific() 设置回调函数，AT 端口接收到输入的数据后，将调用该函数。
esp_at_port_exit_specific() 删除由 esp_at_port_enter_specific 设置的回调函数。

获取数据的方法会根据数据长度是否被指定而有所不同。

指定长度的输入数据¶

假设您已经使用 <param_1> 指定了数据长度，如下所示。

AT+TEST=<param_1>

以下示例代码介绍如何从 AT 命令端口获取长度为 <param_1> 的输入数据。

static xSemaphoreHandle at_sync_sema = NULL;

void wait_data_callback(void)
{
    xSemaphoreGive(at_sync_sema);
}

uint8_t at_setup_cmd_test(uint8_t para_num)
{
    int32_t specified_len = 0;
    int32_t received_len = 0;
    int32_t remain_len = 0;
    uint8_t *buf = NULL;
    uint8_t buffer[64] = {0};

    if (esp_at_get_para_as_digit(0, &specified_len) != ESP_AT_PARA_PARSE_RESULT_OK) {
        return ESP_AT_RESULT_CODE_ERROR;
    }

    buf = (uint8_t *)malloc(specified_len);
    if (buf == NULL) {
        memset(buffer, 0, 64);
        snprintf((char *)buffer, 64, "malloc failed\r\n");
        esp_at_port_write_data(buffer, strlen((char *)buffer));
    }

    // 示例代码
    // 不必在此处创建 semaphores
    if (!at_sync_sema) {
        at_sync_sema = xSemaphoreCreateBinary();
        assert(at_sync_sema != NULL);
    }

    // 返回输入数据提示符 ">"
    esp_at_port_write_data((uint8_t *)">", strlen(">"));

    // 设置回调函数，在接收到输入数据后由 AT 端口调用
    esp_at_port_enter_specific(wait_data_callback);

    // 接收输入的数据
    while(xSemaphoreTake(at_sync_sema, portMAX_DELAY)) {
        received_len += esp_at_port_read_data(buf + received_len, specified_len - received_len);

        if (specified_len == received_len) {
            esp_at_port_exit_specific();

            // 获取剩余输入数据的长度
            remain_len = esp_at_port_get_data_length();
            if (remain_len > 0) {
                // 示例代码
                // 如果剩余数据长度 > 0，则实际输入数据长度大于指定的接收数据长度
                // 可自定义如何处理这些剩余数据
                // 此处只是简单打印出剩余数据
                esp_at_port_recv_data_notify(remain_len, portMAX_DELAY);
            }

            // 示例代码
            // 输出接收到的数据
            memset(buffer, 0, 64);
            snprintf((char *)buffer, 64, "\r\nreceived data is: ");
            esp_at_port_write_data(buffer, strlen((char *)buffer));

            esp_at_port_write_data(buf, specified_len);

            break;
        }
    }

    free(buf);

    return ESP_AT_RESULT_CODE_OK;
}

因此，如果您设置 AT+TEST=5，输入的数据为 1234567890，那么 ESP-AT 返回的结果如下所示。

AT+TEST=5
>67890
received data is: 12345
OK

未指定长度的输入数据¶

这种情况类似 Wi-Fi 透传模式，不指定数据长度。

AT+TEST

假设 ESP-AT 结束命令的执行并返回执行结果，示例代码如下。

#define BUFFER_LEN (2048)
static xSemaphoreHandle at_sync_sema = NULL;

void wait_data_callback(void)
{
    xSemaphoreGive(at_sync_sema);
}

uint8_t at_exe_cmd_test(uint8_t *cmd_name)
{
    int32_t received_len = 0;
    int32_t remain_len = 0;
    uint8_t *buf = NULL;
    uint8_t buffer[64] = {0};


    buf = (uint8_t *)malloc(BUFFER_LEN);
    if (buf == NULL) {
        memset(buffer, 0, 64);
        snprintf((char *)buffer, 64, "malloc failed\r\n");
        esp_at_port_write_data(buffer, strlen((char *)buffer));
    }

    // 示例代码
    // 不必在此处创建 semaphores
    if (!at_sync_sema) {
        at_sync_sema = xSemaphoreCreateBinary();
        assert(at_sync_sema != NULL);
    }

    // 返回输入数据提示符 ">"
    esp_at_port_write_data((uint8_t *)">", strlen(">"));

    // 设置回调函数，在接收到输入数据后由 AT 端口调用
    esp_at_port_enter_specific(wait_data_callback);

    // 接收输入的数据
    while(xSemaphoreTake(at_sync_sema, portMAX_DELAY)) {
        memset(buf, 0, BUFFER_LEN);

        received_len = esp_at_port_read_data(buf, BUFFER_LEN);
        // 检查是否退出该模式
        // 退出条件是接收到 "+++" 字符串
        if ((received_len == 3) && (strncmp((const char *)buf, "+++", 3)) == 0) {
            esp_at_port_exit_specific();

            // 示例代码
            // 如果剩余数据长度 > 0，说明缓冲区内仍有数据需要处理
            // 可自定义如何处理剩余数据
            // 此处只是简单打印出剩余数据
            remain_len = esp_at_port_get_data_length();
            if (remain_len > 0) {
                esp_at_port_recv_data_notify(remain_len, portMAX_DELAY);
            }

            break;
        } else if (received_len > 0) {
            // 示例代码
            // 可自定义如何处理接收到的数据
            // 此处只是简单打印出接收到的数据
            memset(buffer, 0, 64);
            snprintf((char *)buffer, 64, "\r\nreceived data is: ");
            esp_at_port_write_data(buffer, strlen((char *)buffer));

            esp_at_port_write_data(buf, strlen((char *)buf));
        }
    }

    free(buf);

    return ESP_AT_RESULT_CODE_OK;
}

因此，如果第一个输入数据是 1234567890，第二个输入数据是 +++，那么 ESP-AT 返回结果如下所示。

AT+TEST
>
received data is: 1234567890
OK

如何提高 ESP-AT 吞吐性能¶

[English]

默认情况下，ESP-AT 和主机之间使用 UART 进行通信，因此最高吞吐速率不会超过其默认配置，即不会超过 115200 bps。用户如要 ESP-AT 实现较高的吞吐量，需了解本文，并做出有针对性的配置。本文以 ESP32 为例，介绍如何提高 ESP-AT 吞吐性能。

注解

本文基于 ESP-AT 处于透传模式下，描述提高 TCP/UDP/SSL 吞吐性能的一般性方法。

用户可以选择下面其中一种方法，提高吞吐性能：

[简单] 快速配置
[推荐] 熟悉数据流、针对性地配置

[简单] 快速配置¶

1. 配置系统、LWIP、Wi-Fi 适用于高吞吐的参数

将下面代码段拷贝并追加至 module_config/module_esp32_default/sdkconfig.defaults 文件最后，其它 ESP 系列设备请修改对应文件夹下的 sdkconfig.defaults 文件。

# System
CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=4096
CONFIG_FREERTOS_UNICORE=n
CONFIG_FREERTOS_HZ=1000
CONFIG_ESP32_DEFAULT_CPU_FREQ_240=y
CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ=240
CONFIG_ESPTOOLPY_FLASHMODE_QIO=y
CONFIG_ESPTOOLPY_FLASHFREQ_80M=y

# LWIP
CONFIG_LWIP_TCP_SND_BUF_DEFAULT=65534
CONFIG_LWIP_TCP_WND_DEFAULT=65534
CONFIG_LWIP_TCP_RECVMBOX_SIZE=12
CONFIG_LWIP_UDP_RECVMBOX_SIZE=12
CONFIG_LWIP_TCPIP_RECVMBOX_SIZE=64

# Wi-Fi
CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM=16
CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM=64
CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM=64
CONFIG_ESP32_WIFI_TX_BA_WIN=32
CONFIG_ESP32_WIFI_RX_BA_WIN=32
CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED=y
CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED=y

2. 提高 UART 缓冲区大小

将下面代码段拷贝并替换 at_uart_task.c 文件中 uart_driver_install() 行。
uart_driver_install(esp_at_uart_port, 1024 * 16, 1024 * 16, 100, &esp_at_uart_queue, 0);

3. 删除默认配置、重新编译固件、烧录运行

rm -rf build sdkconfig
./build.py build
./build.py flash monitor

4. 透传前提高 UART 波特率

典型 AT 命令序列如下：

AT+CWMODE=1
AT+CWJAP="ssid","password"
AT+UART_CUR=3000000,8,1,0,3
AT+CIPSTART="TCP","192.168.105.13",3344
AT+CIPSEND
// 传输数据

此快速配置的方法在一定程度上可以提高吞吐，但有时可能不能达到用户的预期。另外有些配置可能不是吞吐的瓶颈，配置较高可能会牺牲内存资源或功耗等。因此，用户也可以熟悉下面推荐的方法，进行有针对性地配置。

[推荐] 熟悉数据流、针对性地配置¶

影响 ESP-AT 吞吐的因素大体描述如下图：

如图中箭头所示：

ESP-AT 发送 (TX) 的数据流为 S1 -> S2 -> S3 -> S4 -> S5 -> S6 -> S7 -> S8
ESP-AT 接收 (RX) 的数据流为 R8 -> R7 -> R6 -> R5 -> R4 -> R3 -> R2 -> R1

吞吐的数据流类似于水流，要想提高吞吐，需要考虑在数据流速较低的节点之间进行优化，而不需要在数据流速本就达到预期的节点之间进行额外的配置，以免造成不必要的资源浪费。在实际产品中，往往只需要提高其中一条数据流吞吐即可，用户需要根据下面指导进行对应的配置即可。

注解

下面的配置均以可用内存充足为前提的，用户可以通过 AT+SYSRAM 命令来查询可用内存。

1. G0 吞吐优化

G0 是系统可以优化的部分，建议参考配置如下：

CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=4096
CONFIG_FREERTOS_UNICORE=n
CONFIG_FREERTOS_HZ=1000
CONFIG_ESP32_DEFAULT_CPU_FREQ_240=y
CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ=240
CONFIG_ESPTOOLPY_FLASHMODE_QIO=y
CONFIG_ESPTOOLPY_FLASHFREQ_80M=y

2. S1、R1 吞吐优化

通常情况下，S1 和 R1 是 ESP-AT 吞吐高低的关键。因为默认情况下，ESP-AT 和主机之间使用 UART 进行通信，波特率为 115200，而 UART 硬件上，速率上限为 5 Mbps。因此，用户使用场景吞吐低于 5 Mbps，可以使用默认的 UART 作为和主机之间的通信介质，同时可以进行下面优化。

2.1 提高 UART 缓冲区大小

将下面代码段拷贝并替换 at_uart_task.c 文件中 uart_driver_install() 行。
提高 UART TX 吞吐
uart_driver_install(esp_at_uart_port, 1024 * 16, 8192, 100, &esp_at_uart_queue, 0);
提高 UART RX 吞吐
uart_driver_install(esp_at_uart_port, 2048, 1024 * 16, 100, &esp_at_uart_queue, 0);
提高 UART TX 和 RX 吞吐
uart_driver_install(esp_at_uart_port, 1024 * 16, 1024 * 16, 100, &esp_at_uart_queue, 0);

2.2 透传前提高 UART 波特率

典型 AT 命令序列如下：

AT+CWMODE=1
AT+CWJAP="ssid","password"
AT+UART_CUR=3000000,8,1,0,3
AT+CIPSTART="TCP","192.168.105.13",3344
AT+CIPSEND
// 传输数据

注解

用户需要确保主机的 UART 可以支持到这么高的速率，并且主机和 ESP-AT 之间的 UART 连线尽可能地短。

注解

如果用户期望吞吐速率大于或接近于 5 Mbps，可以考虑使用 SPI、SDIO、Socket 等方式。具体请参考：

SPI： SPI AT 指南
SDIO： SDIO AT 指南
Socket： Socket AT 指南

3. S2、R2、R3、S3 吞吐优化

通常情况下，S2、R2、R3、S3 不是 ESP-AT 吞吐高低的瓶颈。因为 AT core 在 UART 缓冲区和通信协议的传输层之间传递数据，仅有极少的且不耗时的应用逻辑，无需优化。

4. S4、R4、S5、R5、S6、R6 吞吐优化

ESP-AT 和主机之间使用 UART 进行通信，S4、R4、S5、R5、S6、R6 无需优化。ESP-AT 和主机之间使用其他传输介质进行通信时，S4、R4、S5、R5、S6、R6 是影响吞吐的一个因素。

S4、R4、S5、R5、S6、R6 是通信协议的传输层、网络层、和数据链路层之间的数据流。用户需要阅读 ESP-IDF 中如何提高 Wi-Fi 性能文档，了解原理，进行合理配置。这些配置均可以在 ./build.py menuconfig 里进行配置。

优化 S4 -> S5 -> S6：发送数据方向配置

优化 R6 -> R5 -> R4：接收数据方向配置

5. S6、R6 吞吐优化

S6 和 R6 是通信协议的数据链路层，ESP32 可以使用 Wi-Fi 或者以太网作为传输介质。Wi-Fi 除了上述介绍的优化方法之外，可能还需要用户关心：

提高 RF 发射功率

默认发射功率通常不是吞吐高低的瓶颈，用户也可以通过 AT+RFPOWER 命令查询和设置 RF 发射功率。

设置 802.11 b/g/n 协议

默认 Wi-Fi 模式即为 802.11 b/g/n 协议，用户可通过 AT+CWSTAPROTO 命令查询和设置 802.11 b/g/n 协议。配置是双向的，因此建议 AP 端 Wi-Fi 模式配置为 802.11 b/g/n 协议，频宽配置为 HT20/HT40 (20/40 MHz) 模式。

6. S7、R7、S8、R8 吞吐优化

通常情况下，S7、R7、S8、R8 不是 ESP-AT 吞吐优化的范围。因为这和实际网络带宽、网络路由、物理距离等有关。

如何生成出厂参数二进制文件¶

[English]

本文介绍了如何为模组生成一个自定义的 ESP-AT 出厂参数二进制文件 (factory_MODULE_NAME.bin)。例如，您可能想在 ESP-AT 固件中自定义国家代码、射频限制或 UART 管脚，则可以通过下面的两个表格定义此类参数。

factory_param_type.csv
factory_param_data.csv

下面介绍如何通过修改这两个表格来生成自定义的出厂参数二进制文件。

新增一个自定义模组
新增一个自定义参数
修改现有模组的出厂参数数据

factory_param_type.csv¶

factory_param_type.csv 表列出了您可以定义的所有参数，以及每个参数的偏移量、类型和大小，它储存在 customized_partitions/raw_data/factory_param/factory_param_type.csv。

下表提供了每个参数的信息。

param_name	说明
description	在编译 ESP-AT 工程时提示的模组附加信息。
magic_flag	该值必须是 `0xfcfc`。
version	供内部使用的出厂参数管理版本，当前版本为 `3`，不建议修改。
reserved1	保留。
tx_max_power	ESP32 和 ESP32-C3 的 Wi-Fi 最大发射功率：[40,84]，详情请见 ESP32 和 ESP32-C3 发射功率设置范围。
uart_port	用于发送 AT 命令和接收 AT 响应的 UART 端口。
start_channel	起始 Wi-Fi 信道。
channel_num	Wi-Fi 的总信道数。
country_code	国家代码。
uart_baudrate	UART 的波特率。
uart_tx_pin	UART tx 管脚。
uart_rx_pin	UART rx 管脚。
uart_cts_pin	UART cts 管脚，不使用时请置为 -1。
uart_rts_pin	UART rts 管脚，不使用时请置为 -1。
tx_control_pin	某些开发板上电时，该 tx 管脚需要与 MCU 分开。不使用时请置为 -1。
rx_control_pin	某些开发板上电时，该 rx 管脚需要与 MCU 分开。不使用时请置为 -1。
reserved2	保留。
platform	运行当前固件的平台（也称为芯片系列）。
module_name	运行当前固件的模组。

factory_param_data.csv¶

factory_param_data.csv 表格保存了 factory_param_type.csv 中定义的所有参数的值，支持 ESP32 和 ESP32-C3 系列的模组。您可通过修改表中的值来自定义出厂参数二进制文件。该表储存在 customized_partitions/raw_data/factory_param/factory_param_data.csv 中。

新增一个自定义模组¶

本节通过一个示例介绍如何在 factory_param_data.csv 中添加一个自定义模组，并为其生成出厂参数二进制文件。假设您想为一个名为 MY_MODULE 的 ESP32 模组生成出厂参数二进制文件，其国家代码为 JP，Wi-Fi 信道为 1 至 14，其它参数与 PLATFORM_ESP32 的 WROOM-32 模组相同，可按照以下步骤进行操作。

修改 factory_param_data.csv
修改 esp_at_module_info 结构体
重新编译工程并选择自定义模组

修改 factory_param_data.csv ¶

在 factory_param_data.csv 表中设置 MY_MODULE 的所有参数值。

首先，在表格底部插入一行，然后输入以下参数值。

param_name: value
platform: PLATFORM_ESP32
module_name: MY_MODULE
description: MY_DESCRIPTION
magic_flag: 0xfcfc
version: 3
reserved1: 0
tx_max_power: 78
uart_port: 1
start_channel: 1
channel_num: 14
country_code: JP
uart_baudrate: 115200
uart_tx_pin: 17
uart_rx_pin: 16
uart_cts_pin: 15
uart_rts_pin: 14
tx_control_pin: -1
rx_control_pin: -1

修改后的 factory_param_data.csv 表格如下所示。

platform,module_name,description,magic_flag,version,reserved1,tx_max_power,uart_port,start_channel,channel_num,country_code,uart_baudrate,uart_tx_pin,uart_rx_pin,uart_cts_pin,uart_rts_pin,tx_control_pin,rx_control_pin
PLATFORM_ESP32,WROOM-32,,0xfcfc,3,0,78,1,1,13,CN,115200,17,16,15,14,-1,-1
...
PLATFORM_ESP32,MY_MODULE,MY_DESCRIPTION,0xfcfc,3,0,78,1,1,14,JP,115200,17,16,15,14,-1,-1

修改 `esp_at_module_info` 结构体 ¶

在 at/src/at_default_config.c 中的 esp_at_module_info 结构体中添加自定义模组的信息。

esp_at_module_info 结构体提供 OTA 升级验证 token：

typedef struct {
    char* module_name;
    char* ota_token;
    char* ota_ssl_token;
} esp_at_module_info_t;

若不想使用 OTA 功能，那么第二个参数 ota_token 和第三个参数 ota_ssl_token 应该设置为 NULL，第一个参数 module_name 必须与 factory_param_data.csv 文件中的 module_name 一致。

下面是修改后的 esp_at_module_info 结构体。

static const esp_at_module_info_t esp_at_module_info[] = {
#if defined(CONFIG_IDF_TARGET_ESP32)
    {"WROOM-32",        CONFIG_ESP_AT_OTA_TOKEN_WROOM32,       CONFIG_ESP_AT_OTA_SSL_TOKEN_WROOM32 },        // 默认：ESP32-WROOM-32
    {"WROOM-32",        CONFIG_ESP_AT_OTA_TOKEN_WROOM32,       CONFIG_ESP_AT_OTA_SSL_TOKEN_WROOM32 },        // ESP32-WROOM-32
    {"WROVER-32",       CONFIG_ESP_AT_OTA_TOKEN_WROVER32,      CONFIG_ESP_AT_OTA_SSL_TOKEN_WROVER32 },       // ESP32-WROVER
    {"PICO-D4",         CONFIG_ESP_AT_OTA_TOKEN_ESP32_PICO_D4, CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32_PICO_D4},   // ESP32-PICO-D4
    {"SOLO-1",          CONFIG_ESP_AT_OTA_TOKEN_ESP32_SOLO_1,  CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32_SOLO_1 },   // ESP32-SOLO-1
    {"MINI-1",          CONFIG_ESP_AT_OTA_TOKEN_ESP32_MINI_1,  CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32_MINI_1 },   // ESP32-MINI-1
    {"ESP32-D2WD",      NULL,  NULL },   // ESP32-D2WD
    {"ESP32_QCLOUD",    CONFIG_ESP_AT_OTA_TOKEN_ESP32_QCLOUD,   CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32_QCLOUD },  // ESP32-QCLOUD
    {"MY_MODULE",       CONFIG_ESP_AT_OTA_TOKEN_MY_MODULE,      CONFIG_ESP_AT_OTA_SSL_TOKEN_MY_MODULE },     // MY_MODULE
#endif

#if defined(CONFIG_IDF_TARGET_ESP32C3)
    {"MINI-1",         CONFIG_ESP_AT_OTA_TOKEN_ESP32C3_MINI,        CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32C3_MINI },
    {"ESP32C3_QCLOUD", CONFIG_ESP_AT_OTA_TOKEN_ESP32C3_MINI_QCLOUD, CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32C3_MINI_QCLOUD },
#endif
};

宏 CONFIG_ESP_AT_OTA_TOKEN_MY_MODULE 和宏 CONFIG_ESP_AT_OTA_SSL_TOKEN_MY_MODULE 定义在头文件 at/private_include/at_ota_token.h 中。

#if defined(CONFIG_IDF_TARGET_ESP32)
...
#define CONFIG_ESP_AT_OTA_TOKEN_MY_MODULE       CONFIG_ESP_AT_OTA_TOKEN_DEFAULT

...
#define CONFIG_ESP_AT_OTA_SSL_TOKEN_MY_MODULE       CONFIG_ESP_AT_OTA_SSL_TOKEN_DEFAULT

重新编译工程并选择自定义模组 ¶

在添加自定义模组信息后，根据编译 ESP-AT 工程重新编译整个工程，在配置工程时选择自定义模组。

Platform name:
PLATFORM_ESP32
PLATFORM_ESP32C3
choose(range[1,2]):1

Module name:
WROOM-32
WROVER-32
PICO-D4
SOLO-1
MINI-1 (description: ESP32-U4WDH chip inside)
ESP32-D2WD (description: 2MB flash, No OTA)
ESP32_QCLOUD (description: QCLOUD TX:17 RX:16)
MY_MODULE (description: MY_DESCRIPTION)
choose(range[1,8]):8

编译完成后可在 esp-at/build/customized_partitions 文件夹下找到生成的出厂参数二进制文件。

新增一个自定义参数¶

本节通过一个示例介绍如何新增一个自定义参数。假设您想为 MY_MODULE 添加参数 date，并将其设置为 20210603，可按照以下步骤进行操作。

修改 factory_param_type.csv
修改 factory_param_data.csv
处理自定义参数
重新编译工程

修改 factory_param_type.csv ¶

在 factory_param_type.csv 中定义参数 date。

首先，在表格的底部插入一行，然后设置参数的名称 (param_name)、偏移量 (offset)、类型 (type) 和大小 (size)。

param_name	offset	type	size
description	-1	String	0
…	…	…	…
`date`	`88`	`String`	`9`

修改 factory_param_data.csv ¶

在 factory_param_data.csv 最后一列的后面插入一列，并命名为 date，然后将 MY_MODULE 对应的值设置为 20210603。

以下是修改后的 CSV 表格。

platform,module_name,description,magic_flag,version,reserved1,tx_max_power,uart_port,start_channel,channel_num,country_code,uart_baudrate,uart_tx_pin,uart_rx_pin,uart_cts_pin,uart_rts_pin,tx_control_pin,rx_control_pin,date
PLATFORM_ESP32,WROOM-32,,0xfcfc,3,0,78,1,1,13,CN,115200,17,16,15,14,-1,-1
...
PLATFORM_ESP32,MY_MODULE,MY_DESCRIPTION,0xfcfc,3,0,78,1,1,14,JP,115200,17,16,15,14,-1,-1,20210603

处理自定义参数 ¶

您可以自定义函数来处理自定义的参数 date，以下只是简单输出参数值。

static void esp_at_factory_parameter_date_init(void)
{
    const esp_partition_t * partition = esp_at_custom_partition_find(0x40, 0xff, "factory_param");
    char* data = NULL;
    char* str_date = NULL;

    if (!partition) {
        printf("factory_parameter partition missed\r\n");
        return;
    }

    data = (char*)malloc(ESP_AT_FACTORY_PARAMETER_SIZE); // 说明
    assert(data != NULL);
    if(esp_partition_read(partition, 0, data, ESP_AT_FACTORY_PARAMETER_SIZE) != ESP_OK){
        free(data);
        return;
    }

    if ((data[0] != 0xFC) || (data[1] != 0xFC)) { // 检查 magic flag 是否为 0xfc 0xfc
        return;
    }

    // 示例代码
    // 可自定义如何处理参数 date
    // 此处仅简单打印 date 参数值
    str_date = &data[88];   // date 字段偏移地址
    printf("date is %s\r\n", str_date);

    free(data);

    return;
}

重新编译工程 ¶

参考编译 ESP-AT 工程来编译整个工程。

编译完成后可在 esp-at/build/customized_partitions 文件夹下找到生成的出厂参数二进制文件。

修改现有模组的出厂参数数据¶

假设您需要修改 factory_param_data.csv 中现有的某个模组的出厂参数数据，可采用下面任意一种方法。

重新编译整个工程
只编译出厂参数二进制文件
直接修改出厂参数二进制文件

重新编译整个工程 ¶

打开 factory_param_data.csv 并根据需要修改参数。

重新编译 ESP-AT 工程（参考编译 ESP-AT 工程），出厂参数二进制文件会在 esp-at/build/customized_partitions 文件夹生成。

只编译出厂参数二进制文件 ¶

首先，克隆整个 ESP-AT 工程。

然后，前往 ESP-AT 工程的根目录，输入以下命令，并替换一些参数。

python tools/factory_param_generate.py --platform PLATFORM --module MODULE --define_file DEFINE_FILE --module_file MODULE_FILE --bin_name BIN_NAME --log_file LOG_FILE

PLATFORM 替换为模组的平台，必须与 factory_param_data.csv 中 platform 的值一致。
MODULE 替换为模组的名称，必须与 factory_param_data.csv 中 module_name 的值一致。
DEFINE_FILE 替换为 factory_param_type.csv 的相对路径。
MODULE_FILE 替换为 factory_param_data.csv 的相对路径。
BIN_NAME 替换为出厂参数二进制文件名。
LOG_FILE 储存模组名称的文件名。

以下为 MY_MODULE 的示例代码。

python tools/factory_param_generate.py --platform PLATFORM_ESP32 --module MY_MODULE --define_file components/customized_partitions/raw_data/factory_param/factory_param_type.csv --module_file components/customized_partitions/raw_data/factory_param/factory_param_data.csv --bin_name ./factory_param.bin --log_file ./factory_parameter.log

执行上述命令后，将在当前目录下生成以下三个文件。

factory_param.bin
factory_parameter.log
factory_param_MY_MODULE.bin

将新生成的 factory_param_MY_MODULE.bin 下载到 flash 中，可使用 ESP-AT 提供的 esptool.py 进行下载，在 ESP-AT 项目的根目录下执行以下命令，并替换一些参数。

python esp-idf/components/esptool_py/esptool/esptool.py -p PORT -b BAUD --before default_reset --after hard_reset --chip auto  write_flash --flash_mode dio --flash_size detect --flash_freq 40m ADDRESS FILEDIRECTORY

PORT 替换为端口名称。
BAUD 替换为波特率。
ADDRESS 替换为 flash 中开始的地址。ESP-AT 对 ADDRESS 参数有严格的要求，不同固件的出厂参数二进制文件的地址不同，请参考下面的表格。

出厂参数二进制文件下载地址¶

平台

固件

地址

PLATFORM_ESP32

所有固件

0x30000

PLATFORM_ESP32C3

MINI-1 固件

0x31000

PLATFORM_ESP32C3

QCLOUD 固件

0x30000
FILEDIRECTORY 替换为出厂参数二进制文件的相对路径。

下面是将生成的出厂参数二进制文件烧录到 MY_MODULE 的命令示例。

python esp-idf/components/esptool_py/esptool/esptool.py -p /dev/ttyUSB0 -b 921600 --before default_reset --after hard_reset --chip auto  write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x30000 ./factory_param_MY_MODULE.bin

直接修改出厂参数二进制文件 ¶

用二进制工具打开出厂参数二进制文件，根据 factory_param_type.csv 中的参数偏移量，直接在相应位置进行修改。

将修改后的 factory_param.bin 烧录至 flash（详情请见下载指导）。

如何自定义低功耗蓝牙服务¶

[English]

本文档介绍了如何利用 ESP-AT 提供的低功耗蓝牙服务源文件在 ESP 设备上自定义低功耗蓝牙服务。

低功耗蓝牙服务源文件
自定义低功耗蓝牙服务

低功耗蓝牙服务被定义为 GATT 结构的多元数组，该数组至少包含一个属性类型 (attribute type) 为 0x2800 的首要服务 (primary service)。每个服务总是由一个服务定义和几个特征组成。每个特征总是由一个值和可选的描述符组成。更多相关信息请参阅《蓝牙核心规范》中的 Generic Attribute Profile (GATT) 一节。

低功耗蓝牙服务源文件 ¶

低功耗蓝牙服务源文件是 ESP-AT 工程创建低功耗蓝牙服务所依据的文件，文件位于 components/customized_partitions/raw_data/ble_data/example.csv，内容如下表所示。

index	uuid_len	uuid	perm	val_max_len	val_cur_len	value
0	16	0x2800	0x01	2	2	A002
1	16	0x2803	0x01	1	1	2
2	16	0xC300	0x01	1	1	30
3	16	0x2901	0x11	1	1	30
…	…	…	…	…	…	…

以下内容是对上表的说明。

perm 字段描述权限，它在 ESP-AT 工程中的定义如下所示。

/* relate to BTA_GATT_PERM_xxx in bta/bta_gatt_api.h */
/**
* @brief Attribute permissions
*/
#define    ESP_GATT_PERM_READ                  (1 << 0)   /* bit 0 -  0x0001 */    /* relate to BTA_GATT_PERM_READ in bta/bta_gatt_api.h */
#define    ESP_GATT_PERM_READ_ENCRYPTED        (1 << 1)   /* bit 1 -  0x0002 */    /* relate to BTA_GATT_PERM_READ_ENCRYPTED in bta/bta_gatt_api.h */
#define    ESP_GATT_PERM_READ_ENC_MITM         (1 << 2)   /* bit 2 -  0x0004 */    /* relate to BTA_GATT_PERM_READ_ENC_MITM in bta/bta_gatt_api.h */
#define    ESP_GATT_PERM_WRITE                 (1 << 4)   /* bit 4 -  0x0010 */    /* relate to BTA_GATT_PERM_WRITE in bta/bta_gatt_api.h */
#define    ESP_GATT_PERM_WRITE_ENCRYPTED       (1 << 5)   /* bit 5 -  0x0020 */    /* relate to BTA_GATT_PERM_WRITE_ENCRYPTED in bta/bta_gatt_api.h */
#define    ESP_GATT_PERM_WRITE_ENC_MITM        (1 << 6)   /* bit 6 -  0x0040 */    /* relate to BTA_GATT_PERM_WRITE_ENC_MITM in bta/bta_gatt_api.h */
#define    ESP_GATT_PERM_WRITE_SIGNED          (1 << 7)   /* bit 7 -  0x0080 */    /* relate to BTA_GATT_PERM_WRITE_SIGNED in bta/bta_gatt_api.h */
#define    ESP_GATT_PERM_WRITE_SIGNED_MITM     (1 << 8)   /* bit 8 -  0x0100 */    /* relate to BTA_GATT_PERM_WRITE_SIGNED_MITM in bta/bta_gatt_api.h */
#define    ESP_GATT_PERM_READ_AUTHORIZATION    (1 << 9)   /* bit 9 -  0x0200 */
#define    ESP_GATT_PERM_WRITE_AUTHORIZATION   (1 << 10)  /* bit 10 - 0x0400 */

上表第一行是 UUID 为 0xA002 的服务定义。
第二行是特征的声明。UUID 0x2803 表示特征声明，数值 (value) 2 设置权限，权限长度为 8 位，每一位代表一个操作的权限，1 表示支持该操作，0 表示不支持。

位

权限

0

BROADCAST

1

READ

2

WRITE WITHOUT RESPONSE

3

WRITE

4

NOTIFY

5

INDICATE

6

AUTHENTICATION SIGNED WRITES

7

EXTENDED PROPERTIES
第三行定义了服务的特征。该行的 UUID 是特征的 UUID，数值是特征的数值。
第四行定义了特征的描述符（可选）。

有关 UUID 的更多信息请参考蓝牙技术联盟分配符。

如果直接在 ESP 设备上使用默认源文件，不做任何修改，并建立低功耗蓝牙连接，那么在客户端查询服务器服务后，会得到如下结果。

自定义低功耗蓝牙服务 ¶

请根据以下步骤自定义低功耗蓝牙服务。

修改低功耗蓝牙服务源文件
生成 ble_data.bin 文件
下载 ble_data.bin 文件

修改低功耗蓝牙服务源文件 ¶

可定义多个服务，例如，若要定义三个服务（Server_A、Server_B 和 Server_C），则需要将这三个服务按顺序排列。由于定义每个服务的操作大同小异，这里我们以定义一个服务为例，其他服务您可以按照此例进行定义。

添加服务定义。

本例定义了一个值为 0xFF01 的主要服务。

index

uuid_len

uuid

perm

val_max_len

val_cur_len

value

31

16

0x2800

0x01

2

2

FF01
添加特征说明和特征值。

本例定义了一个 UUID 为 0xC300 的可读可写特征，并将其值设置为 0x30。

index

uuid_len

uuid

perm

val_max_len

val_cur_len

value

32

16

0x2803

0x11

1

1

0A

33

16

0xC300

0x11

1

1

30
添加特征描述符（可选）。

本例添加了客户端特征配置，数字 0x0000 表示通知 (notification) 和指示 (indication) 被禁用。

index

uuid_len

uuid

perm

val_max_len

val_cur_len

value

34

16

0x2902

0x11

2

2

0000

完成以上步骤后，自定义的低功耗蓝牙服务定义如下。

index	uuid_len	uuid	perm	val_max_len	val_cur_len	value
31	16	0x2800	0x01	2	2	FF01
32	16	0x2803	0x11	1	1	0A
33	16	0xC300	0x11	1	1	30
34	16	0x2902	0x11	2	2	0000

生成 ble_data.bin 文件 ¶

可采用以下任意一种方式生成 ble_data.bin 文件。

重新编译 ESP-AT 工程，生成 ble_data.bin，详情请见编译工程。
执行 BLEService.py 脚本，生成 ble_data.bin 文件。

BLEService.py 的路径为 tools/BLEService.py，您可以在 ESP-AT 的根目录执行以下命令生成 ble_data.bin 文件。
```
python ./tools/BLEService.py components/customized_partitions/raw_data/ble_data/example.csv
```

下载 ble_data.bin 文件 ¶

可采用以下任意一种方式下载 ble_data.bin 文件，分别对应生成 ble_data.bin 文件这一小节中提到的生成 ble_data.bin 文件的方法。

下载重新编译过的 ESP-AT 固件，详情请见烧录到设备。
仅下载 ble_data.bin，这种方法只更新设备中的 ble_data 区域。

您可以在 ESP-AT 根目录执行以下命令下载 ble_data.bin 文件。
```
esptool.py --chip auto --port PORTNAME --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size 4MB ADDRESS ble_data.bin
```
将 PORTNAME 替换为您的串口名称，ADDRESS 替换为下载 ble_data.bin 文件的地址，不同的模组有不同的下载地址。
- ESP32：0x21000
- ESP32-C3：0x1F000
- ESP32-C3 QCLOUD：0x21000

下载完成后，重新建立低功耗蓝牙连接，在客户端查询的服务器服务如下所示。

如何自定义分区¶

[English]

本文档介绍了如何通过修改 ESP-AT 提供的 at_customize.csv 表来自定义 ESP 设备中的分区。共有两个分区表：一级分区表和二级分区表。

一级分区表 partitions_at.csv 供系统使用，在此基础上生成 partitions_at.bin 文件。如果一级分区表出错，系统将无法启动。因此，不建议修改 partitions_at.csv。

ESP-AT 提供了二级分区表 at_customize.csv 供您存储自定义数据块。它基于一级分区表。

要修改 ESP 设备中的分区，请按照前三个步骤操作。第四部分举例说明了前三个步骤。

修改 at_customize.csv
生成 at_customize.bin
烧录 at_customize.bin 至 ESP 设备
示例

修改 at_customize.csv¶

请参考下表找到模组的 at_customize.csv。

at_customize.csv 路径¶
平台	模组	路径
ESP32	WROOM-32 PICO-D4 SOLO-1 MINI-1	module_esp32_default/at_customize.csv
ESP32	WROVER-32	module_wrover-32/at_customize.csv
ESP32	ESP32-D2WD	module_esp32-d2wd/at_customize.csv
ESP32	ESP32_QCLOUD	module_esp32_qcloud/at_customize.csv
ESP32-C3	MINI-1	module_esp32c3_default/at_customize.csv
ESP32-C3	ESP32C3_QCLOUD	module_esp32c3_qcloud/at_customize.csv

然后，在修改 at_customize.csv 时遵循以下规则。

已定义的用户分区的 Name 和 Type 不可更改，但 SubType、Offset 和 Size 可以更改。
如果您需要添加一个新的用户分区，请先检查它是否已经在 ESP-IDF (esp_partition.h) 中定义。
- 如果已定义，请保持 Type 值与 ESP-IDF 的相同。
- 如果未定义，请将 Type 设置为 0x40。
用户分区的 Name 不应超过 16 字节。
at_customize 分区的默认大小定义在 partitions_at.csv 表中，添加新用户分区时请不要超出范围。

生成 at_customize.bin¶

修改 at_customize.csv 后，您可以重新编译 ESP-AT 工程或使用 python 脚本 gen_esp32part.py 来生成 at_customize.bin 文件。

如果使用脚本，在 ESP-AT 工程根目录下执行以下命令，并替换 INPUT 和 OUTPUT。

python esp-idf/components/partition_table/gen_esp32part.py <INPUT> [OUTPUT]

INPUT 替换为待解析的 at_customize.csv 或二进制文件的路径。
OUTPUT 替换为生成的二进制或 CSV 文件的路径，如果省略，将使用标准输出。

烧录 at_customize.bin 至 ESP 设备¶

将 at_customize.bin 下载到 flash 中。关于如何将二进制文件烧录至 ESP 设备，请参考烧录 AT 固件至设备。下表为不同模组 at_customize.bin 文件的下载地址。

不同模组 at_customize.bin 的下载地址¶
平台	模组	地址	大小
ESP32	WROOM-32 WROVER-32 PICO-D4 SOLO-1 MINI-1 ESP32-D2WD ESP32_QCLOUD	0x20000	0xE0000
ESP32-C3	MINI-1	0x1E000	0x42000
ESP32-C3	ESP32C3_QCLOUD	0x20000	0xE0000

在某些情况下，必须将 at_customize.bin 下载到 flash 后才能使用一些 AT 命令：

AT+SYSFLASH：查询或读写 flash 用户分区
AT+FS：文件系统操作
SSL 服务器相关命令
BLE 服务器相关命令

示例¶

本节介绍如何将名为 test 的 4 KB 分区添加到 ESP32-WROOM-32 模组中。

首先找到 ESP32-WROOM-32 的 at_customize.csv 表，设置新分区的 Name、Type、SubType、Offset 和 Size。

# Name,Type,SubType,Offset,Size
... ...
test,0x40,15,0x3D000,4K
fatfs,data,fat,0x70000,576K

第二步，重新编译 ESP-AT 工程，或者在 ESP-AT 根目录下执行 python 脚本生成 at_customize.bin。

python esp-idf/components/partition_table/gen_esp32part.py -q ./module_config/module_esp32_default/at_customize.csv at_customize.bin

然后，ESP-AT 根目录中会生成 at_customize.bin。

第三步，下载 at_customize.bin 至 flash。

在 ESP-AT 工程根目录下执行以下命令，并替换 PORT 和 BAUD。

python esp-idf/components/esptool_py/esptool/esptool.py -p PORT -b BAUD --before default_reset --after hard_reset --chip auto  write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x20000 ./at_customize.bin

PORT 替换为端口名称。
BAUD 替换为波特率。

如何启用 ESP-AT 经典蓝牙¶

[English]

默认情况下，ESP32 系列 AT 固件禁用经典蓝牙 AT 命令，若需在 ESP32 设备上使用，请按照以下步骤操作。当前 AT 支持的经典蓝牙命令分为三类，通用蓝牙命令、SPP 命令和 A2DP 命令，每类命令可以单独启用和禁用。

克隆 ESP-AT 工程。
执行 ./build.py menuconfig （Linux 或者 macOS）或者 build.py menuconfig (Windows) 来运行配置工具。
启用您需要的命令。

启用通用蓝牙命令。

Component config -> AT -> AT bt command support

启用 SPP 命令。

Component config -> AT -> AT bt command support -> AT bt spp command support

启用 A2DP 命令。

Component config -> AT -> AT bt command support -> AT bt a2dp command support

编译工程，在 build/esp-at.bin 中生成新的固件。
将新固件烧录进您的设备。

如何启用 ESP-AT 以太网功能¶

[English]

概述¶

本文档旨在指导用户启用 ESP-AT Ethernet，并通过简单的测试，展示如何确认是否启用成功。

第一步：配置并烧录¶

./build.py menuconfig -> Component config -> AT -> AT ethernet support 启用以太网功能。
./build.py menuconfig -> Component config -> AT -> Ethernet PHY 选择以太网 PHY。选择以太网 PHY 的说明请参考 PHY 配置。
重新编译 esp-at 工程 (参考编译 ESP-AT 工程)，将生成的固件烧录到开发板中运行。

PHY 配置¶

使用 ./build.py menuconfig 配置以太网接口要使用的 PHY 模块，配置选项将根据你使用不同的硬件而有所不同。

Espressif 的官方硬件以太网开发板默认的配置是使用 IP101 PHY 模块。ESP32 AT 最多支持四种以太网 PHY：LAN8720，IP101，DP83848 和 RTL8201。由于 TI 停止生产，TLK110 PHY 已经不再支持。如果你想使用其他 PHY，请参考 ESP32-Ethernet-Kit V1.2 入门指南进行设计。

第二步：连接开发板并测试¶

将开发板通过网线连接到路由器，开发板将自动发送 DHCP 请求并尝试获取 IP 地址。如果设备获取 IP 地址成功，那么你可以使用连接到该路由器的 PC ping 通开发板。

如何增加一个新的模组支持¶

[English]

ESP-AT 工程支持多个模组，并提供了模组的配置文件：factory_param_data.csv 和 module_config。下表列出了 ESP-AT 工程支持的平台（即芯片系列）、模组以及模组配置文件的位置。

平台	模组	默认配置文件
ESP32	WROOM-32 PICO-D4 SOLO-1 MINI-1	module_config/module_esp32_default/sdkconfig.defaults module_config/module_esp32_default/sdkconfig_silence.defaults
ESP32	WROVER-32	module_config/module_wrover-32/sdkconfig.defaults module_config/module_wrover-32/sdkconfig_silence.defaults
ESP32	ESP32-D2WD	module_config/module_esp32-d2wd/sdkconfig.defaults module_config/module_esp32-d2wd/sdkconfig_silence.defaults
ESP32	ESP32_QCLOUD	module_config/module_esp32_qcloud/sdkconfig.defaults module_config/module_esp32_qcloud/sdkconfig_silence.defaults
ESP32-C3	MINI-1	module_config/module_esp32c3_default/sdkconfig.defaults module_config/module_esp32c3_default/sdkconfig_silence.defaults
ESP32-C3	ESP32C3_QCLOUD	module_config/module_esp32c3_qcloud/sdkconfig.defaults module_config/module_esp32c3_qcloud/sdkconfig_silence.defaults

注意

当 ./build.py menuconfig 中的 silence mode 为 0 时，对应模块的配置文件为 sdkconfig.defaults。
当 ./build.py menuconfig 中的 silence mode 为 1 时，对应模块的配置文件为 sdkconfig_silence.defaults。

如果要在 ESP-AT 工程中添加对某个 ESP 模组的支持，则需要修改这些配置文件。此处的“ESP 模组”指的是：

ESP-AT 工程暂未适配支持的模组，包括 ESP-AT 已适配相应芯片的模组，和未适配相应芯片的模组。但不建议添加后者，因为工作量巨大，此文档也不做阐述。
ESP-AT 工程已适配支持的模组，但用户需要对其修改默认配置的。

本文档将说明如何在 ESP-AT 工程中为 ESP-AT 已支持的某款 ESP 芯片添加新的模组支持，下文中以添加对 ESP32-WROOM-32 支持为例，该模组使用 SDIO 而不是默认的 UART 接口。

在 factory_param_data.csv 添加模组信息¶

打开本地的 factory_param_data.csv ，在表格最后插入一行，根据实际需要设置相关参数。本例中，我们将 platform 设置为 PLATFORM_ESP32、module_name 设置为 WROOM32-SDIO，其他参数设置值见下表（参数含义请参考 factory_param_type.csv）。

platform: PLATFORM_ESP32
module_name: WROOM32-SDIO
description:
magic_flag: 0xfcfc
version: 3
reserved1: 0
tx_max_power: 78
uart_port: 1
start_channel: 1
channel_num: 13
country_code: CN
uart_baudrate: -1
uart_tx_pin: -1
uart_rx_pin: -1
uart_cts_pin: -1
uart_rts_pin: -1
tx_control_pin: -1
rx_control_pin: -1

修改 esp_at_module_info 结构体¶

详情请参考修改 esp_at_module_info 结构体。

配置模组文件¶

首先，进入 module_config 文件夹，创建一个子文件夹来存放模组的配置文件（文件夹名称为小写），然后在其中加入配置文件 IDF_VERSION、at_customize.csv、partitions_at.csv、sdkconfig.defaults 以及 sdkconfig_silence.defaults。

本例中，我们复制粘贴 module_esp32_default 文件夹及其中的配置文件，并重命名为 module_wroom32-sdio。在本例中，配置文件 IDF_VERSION、at_customize.csv 和 partitions_at.csv 无需修改，我们只需修改 sdkconfig.defaults 和 sdkconfig_silence.defaults：

使用 module_wroom32-sdio 文件夹下的分区表，需要修改如下配置

CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="module_config/module_wroom32-sdio/partitions_at.csv"
CONFIG_PARTITION_TABLE_FILENAME="module_config/module_wroom32-sdio/partitions_at.csv"
CONFIG_AT_CUSTOMIZED_PARTITION_TABLE_FILE="module_config/module_wroom32-sdio/at_customize.csv"

使用 SDIO 配置，移除 UART 配置
- 移除 UART 配置
```
CONFIG_AT_BASE_ON_UART=n
```
- 新增 SDIO 配置
```
CONFIG_AT_BASE_ON_SDIO=y
```

完成上述步骤后，可重新编译 ESP-AT 工程生成模组固件。本例中，我们在配置工程时，应选择 PLATFORM_ESP32 和 WROOM32-SDIO 来生成模组固件。

ESP32 SDIO AT 指南¶

[English]

简介¶

ESP32 SDIO AT 使用 SDIO 协议进行通讯，其中 ESP32 作为 SDIO slave 与 MCU 进行通信。

SDIO 可使用一线或四线模式。至少需要 4 根线：CMD、CLK、DAT0 和 DAT1。

对于一线模式，至少需要 4 根线：CMD、CLK、DAT0 和 DAT1，其中 DAT1 作为中断线；
对于四线模式，需要增加 DAT2 和 DAT3。

SDIO slave 管脚如下所示：

CLK：GPIO14
CMD：GPIO15
DAT0：GPIO2
DAT1：GPIO4
DAT2：GPIO12（四线）
DAT3：GPIO13（四线）

如何使用 SDIO AT¶

在测试 SDIO AT 通信之前，首先请参照 SD Pull-up Requirements 的介绍对 ESP32 硬件进行处理，否则 SDIO 通信将会异常。

Slave 侧¶

AT 项目默认使用 UART 作为传输介质，你可以通过 ./build.py menuconfig -> Component config -> AT -> communicate method for AT command -> AT throughSDIO 切换为用 SDIO 作为传输介质。之后重新编译 esp-at 工程，烧录新的固件并运行。

Host 侧¶

ESP-AT 提供了 ESP32 和 STM32 作为 SDIO host 的 at_sdio_host 参考示例。对于 ESP32 的参考示例，可以使用 AT 工程的 esp-idf 版本进行编译烧录；对于 STM32，我们提供的方案基于 STM32F103ZET，请使用 Keil5 进行编译烧录。

对于其他平台，可以参照这两个示例进行适配。

SDIO 交互流程¶

Host 侧¶

初始化 SDIO host
- SDIO host 初始化主要是 SDIO 协议的初始化，包括设置 1 线或者 4 线、SDIO 频率、初始化 SD mode。
协商 SDIO 通讯
- 这部分主要按照 SDIO spec 协议标准的要求，跟 SDIO slave 协商参数。
- 特别需要注意的是，如果 SDIO host 和 slave 同时重启，那么，协商需要等待 slave 初始化完成后再开始。一般 host 会在启动时添加延时，等待 slave 启动完成，再开始协商 SDIO 通信。
接收数据
- 接收数据主要依靠监测 DAT1 的中断信号。当接收到中断信号后，host 读取中断源并判断中断信号，如果中断是 slave 有数据要发送，host 会调用 CMD53 读取 slave 的数据。
发送数据
- SDIO AT DEMO 中，发送数据通过串口输入，然后 host 调用 CMD53 将数据发送过去。
- 需要注意的是，如果发送超时，那么有可能 slave 侧出现异常，此时 host 和 slave 需要重新初始化 SDIO。
- 在调用 AT+RST 或者 AT+RESTORE 命令后，host 和 slave 也同样需要重新初始化 SDIO。

Slave 侧¶

SDIO slave 的处理与 SDIO host 类似，slave 在接收到 SDIO host 发送的数据后，通知 AT core 并将数据发送给 AT core 进行处理，在 AT core 处理完成后，再发送数据给 SDIO host。

初始化 SDIO slave
- 调用 sdio_slave_initialize 初始化 SDIO slave driver。
- 调用 sdio_slave_recv_register_buf 注册接收用的 buffer，为了加快接收速度，此处注册了多个接收 buffer。
- 调用 sdio_slave_recv_load_buf 加载刚刚注册的 buffer，准备接收数据。
- sdio_slave_set_host_intena 用于设置 host 可用中断，主要用到的是新数据包发送中断 SDIO_SLAVE_HOSTINT_SEND_NEW_PACKET。
- 调用 sdio_slave_start 在硬件上开始接收和发送。
发送数据
- 因为 SDIO slave 发送的数据需要保证能被 DMA 访问，所以需要先把 AT 中的数据拷贝到可被 DMA 访问的内存中，然后调用 sdio_slave_transmit 进行发送。
接收数据
- 为了优化接收 SDIO 数据传输给 AT core 的速率，在调用 sdio_slave_recv 接收 SDIO 数据后，使用了循环链表将接收到的数据传输到 AT core。

SPI AT 指南¶

本文档主要介绍 SPI AT 的实现与使用，主要涉及以下几个方面：

简介
使用 SPI AT
SPI AT 速率

注解

本文档仅介绍 ESP32-C、ESP32-S 系列的 ESP 设备的 SPI AT 的实现与应用。由于硬件限制，ESP32 系列不建议使用 SPI AT，可使用 SDIO SPI AT 作为替代。

简介 ¶

SPI AT 基于 AT 工程，使用 SPI 协议进行数据通信。在使用 SPI AT 时，MCU 设备作为 SPI master，ESP 设备作为 SPI slave，通信双方通过 SPI 协议实现基于 AT 命令的数据交互。

使用 SPI AT 的优势¶

AT 工程默认使用 UART 协议进行数据通信，但是 UART 协议在一些需要高速传输数据的应用场景并不适用，因此，使用支持更高传输速率的 SPI 协议传输数据成为一种较好的选择。

如何启用 SPI AT？¶

您可以通过下述步骤配置并启用 SPI AT：

通过 ./build.py menuconfig -> Component config -> AT -> communicate method for AT command -> AT through HSPI 使能 SPI AT。
通过 ./build.py menuconfig -> Component config -> AT -> communicate method for AT command -> AT SPI Data Transmission Mode 选择 SPI 数据传输模式。
通过 ./build.py menuconfig -> Component config -> AT -> communicate method for AT command -> AT SPI GPIO settings 配置 SPI 使用的 GPIO 管脚。
通过 ./build.py menuconfig -> Component config -> AT -> communicate method for AT command -> AT SPI driver settings 选择 SPI 从机的工作模式，并配置相关缓存区的大小。
重新编译 esp-at 工程（参考编译 ESP-AT 工程），烧录新的固件并运行。

SPI AT 默认管脚¶

下表给出了不同系列的 ESP 设备使用 SPI AT 时默认的硬件管脚：

SPI AT 默认管脚¶
信号	GPIO 编号 (ESP32-C3)
SCLK	6
MISO	2
MOSI	7
CS	10
HANDSHAKE	3
GND	GND
QUADWP (qio/qout):sup:1	8
QUADHD (qio/qout):sup:1	9

说明 1：QUADWP 引脚和 QUADHD 引脚仅在使用 4 线 SPI 工作时使用。

您可以通过 ./build.py menuconfig > Component config > AT > communicate method for AT command > AT through HSPI > AT SPI GPIO settings，然后编译工程来配置 SPI AT 对应的管脚（参考编译 ESP-AT 工程）。

使用 SPI AT ¶

在使用 SPI AT 时，ESP 设备上运行的 SPI slave 工作在半双工通信模式下。通常，在使用 SPI 协议进行半双工通信时，由 SPI master 启动对 SPI slave 的读/写操作，但是，使用 AT 命令进行数据交互时，需要 ESP 设备主动能够主动上报一些信息。因此，我们在 SPI master 和 slave 之间添加了一个握手线，来实现 slave 主动向 master 上报信息的功能。使用握手线的具体方法为：

Master 向 slave 发送 AT 数据时，使用握手线的方法为：
1. master 向 slave 发送请求传输数据的请求，然后等待 slave 向握手线发出的允许发送数据的信号。
2. master 检测到握手线上的 slave 发出的允许发送的信号后，开始发送数据。
3. master 发送数据后，通知 slave 数据发送结束。
Master 接收 slave 发送的 AT 数据时，使用握手线的方法为：
1. slave 通过握手线通知 master 开始接收数据。
2. master 接收数据，并在接收所有数据后，通知 slave 数据已经全部接收。

通信格式¶

SPI AT 的通信格式为 CMD+ADDR+DUMMY+DATA（读/写）。在使用 SPI AT 时，SPI master 使用到的一些通信报文介绍如下：

Master 向 slave 发送数据时的通信报文：

主机向从机发送数据¶
CMD（1 字节）	ADDR（1 字节）	DUMMY（1 字节）	DATA（高达 4092 字节）
0x3	0x0	0x0	data_buffer

Master 向 slave 发送数据结束后，需要发送一条通知消息来结束本次传输，具体的通信报文为：

主机通知从机，主机发送数据已经结束¶
CMD（1 字节）	ADDR（1 字节）	DUMMY（1 字节）	DATA
0x7	0x0	0x0	null

Master 接收 slave 发送的数据时的通信报文：

主机读取从机发送的数据¶
CMD（1 字节）	ADDR（1 字节）	DUMMY（1 字节）	DATA（高达 4092 字节）
0x4	0x0	0x0	data_buffer

Master 接收 slave 发送的数据后，需要发送一条通知消息来结束本次传输，具体的通信报文为：

主机通知从机，主机读取数据已经结束¶
CMD（1 字节）	ADDR（1 字节）	DUMMY（1 字节）	DATA
0x8	0x0	0x0	null

Master 向 slave 发送请求传输指定大小数据的通信报文：

主机向从机发送写数据请求¶
CMD（1 字节）	ADDR（1 字节）	DUMMY（1 字节）	DATA（4 字节）
0x1	0x0	0x0	data_info

其中 4 字节的 data_info 中包含了本次请求传输数据的数据包信息，具体格式如下：

Master 向 slave 发送的数据的字节数，长度 0～15 bit。
Master 向 slave 发送的数据包的序列号，该序列号在 master 每次发送时递增，长度 16～23 bit。
Magic 值，长度 24～31 bit，固定为 0xFE。

Master 检测到握手线上有 slave 发出的信号后，需要发送一条消息查询 slave 进入接收数据的工作模式，还是进入到发送数据的工作模式，具体的通信报文为：

主机发送请求，查询从机的可读/可写状态¶
CMD（1 字节）	ADDR（1 字节）	DUMMY（1 字节）	DATA（4 字节）
0x2	0x4	0x0	slave_status

发送查询请求后，slave 返回的状态信息将存储在 4 字节的 slave_status 中，其具体的格式如下：

slave 需要向 master 发送的数据的字节数，长度 0～15 bit；仅当 slave 处于可读状态时，该字段数字有效。
数据包序列号，长度 16～23 bit，当序列号达到最大值 0xFF 时，下一个数据包的序列号重新设置为 0x0。当 slave 处于可写状态时，该字段为 master 需向 slave 发送的下一下数据包的序列号；当 slave 处于可读状态时，该字段为 slave 向 master 发送的下一个数据包的序列号。
slave 的可读/可写状态，长度 24～31 bit。

SPI AT 数据交互流程¶

SPI AT 数据交互流程主要分为两个方面：

SPI master 向 slave 发送 AT 指令：

| SPI master |                            | SPI slave |
       |                                        |
       |   -------step 1: request to send---->  |
       |                                        |
       |   <------step 2: GPIO interrupt------  |
       |                                        |
       |   -------step 3: read slave status-->  |
       |                                        |
       |   -------step 4: send data---------->  |
       |                                        |
       |   -------step 5: send done---------->  |

每个步骤具体的说明如下：

master 向 slave 发送请求向 slave 写数据的请求。
slave 接收 master 的发送请求，若此时 slave 允许接收数据，则向 slave_status 寄存器写入允许 master 写入的标志位，然后通过握手线触发 master 上的 GPIO 中断。
master 接收到中断后，读取 slave 的 slave_status 寄存器，检测到 slave 进入接收数据的状态。
master 开始向 slave 发送数据。
发送数据结束后，master 向 slave 发送一条代表发送结束的消息。

SPI slave 向 master 发送 AT 响应：

| SPI master |                            | SPI slave |
       |                                        |
       |   <------step 1: GPIO interrupt------  |
       |                                        |
       |   -------step 2: read slave status-->  |
       |                                        |
       |   <------step 3: send data-----------  |
       |                                        |
       |   -------step 4: receive done------->  |

每个步骤具体的说明如下：

slave 向 slave_status 寄存器写入允许 master 读取来自 slave 的数据的标志位,然后通过握手线触发 master 上的 GPIO 中断。
master 接收到中断后，读取 slave 的 slave_status 寄存器，检测到 slave 进入发送数据的状态。
master 开始接收来自 slave 的数据。
数据接收完毕后，master 向 slave 发送一条代表接收数据结束的消息。

SPI AT Master 示例代码¶

使用 SPI master 与 ESP 设备运行的 SPI slave 进行通信的示例代码请参考 :example:` AT ESP32 SPI Master 例程 <at_spi_master/spi/esp32_c_series>`。

SPI AT 速率 ¶

测试说明¶

使用 ESP32-DevKitC 开发板作为 SPI master，运行 ESP-AT 中的 at_spi_master/spi/esp32_c_series 目录的代码。其软硬件配置如下：

硬件：CPU 工作频率设置为 240 MHz，flash SPI mode 配置为 QIO 模式，flash 频率设置为 40 MHz。
软件：基于 ESP-IDF v4.3 的编译环境，并将示例代码中的 streambuffer 的大小调整为 8192 字节。

使用 ESP32-C3 作为 SPI slave，编译并烧录 SPI AT 固件（参考编译 ESP-AT 工程），并将 ESP32-C3 配置工作在 TCP 透传模式。其软硬件配置如下：

硬件：CPU 工作频率设置为 160 MHz。
软件：SPI-AT 的实现代码中，将 streambuffer 的大小设置为 8192 字节，并使用 ESP-IDF 下的 example/wifi/iperf 中的 sdkconfig.defaults.esp32c3 中的相关配置参数。

测试结果¶

下表显示了我们在屏蔽箱中得到的通信速率结果：

SPI AT Wi-Fi TCP 通信速率¶
Clock	SPI mode	master->slave	slave->master
10 M	Standard	0.95 MByte/s	1.00 MByte/s
10 M	Dual	1.37 MByte/s	1.29 MByte/s
10 M	Quad	1.43 MByte/s	1.31 MByte/s
20 M	Standard	1.41 MByte/s	1.30 MByte/s
20 M	Dual	1.39 MByte/s	1.30 MByte/s
20 M	Quad	1.39 MByte/s	1.30 MByte/s
40 M	Standard	1.37 MByte/s	1.30 MByte/s
40 M	Dual	1.40 MByte/s	1.31 MByte/s
40 M	Quad	1.48 MByte/s	1.31 MByte/s

说明 1：当 SPI 的时钟频率较高时，受限于上层网络组件的限制，使用 Dual 或者 Quad 工作模式的通信速率想比较于 Standard 模式并未显著改善。

说明 2：更多关于 SPI 通信的介绍请参考对应模组的技术参考手册。

如何实现 OTA 升级¶

[English]

本文档指导如何为 ESP32 和 ESP32-C3 系列模块实现 OTA 升级。目前，ESP-AT 针对不同场景提供了以下三种 OTA 命令。您可以根据自己的需求选择适合的 OTA 命令。

AT+USEROTA

AT+CIUPDATE

AT+WEBSERVER

文档结构如下所示：

OTA 命令对比及应用场景
使用 ESP-AT OTA 命令执行 OTA 升级

OTA 命令对比及应用场景¶

AT+USEROTA ¶

此命令通过 URL 实现 OTA 升级。您可以升级到放置在 HTTP 服务器上的固件。目前该命令仅支持应用分区升级。请参考 AT+USEROTA 获取更多信息。

由于此命令属于用户自定义命令，您可以通过修改 at/src/at_user_cmd.c 源代码来实现该命令。

此命令的应用场景如下：

您有属于自己的 HTTP 服务器。

您必须指定 URL。

重要

如果您升级的固件为非乐鑫正式发布的固件，在升级完成后，您可能无法使用 AT+CIUPDATE 命令升级，除非您按照使用 AT+CIUPDATE 进行 OTA 升级创建了自己的设备。

AT+CIUPDATE ¶

此命令使用 iot.espressif.cn 作为默认 HTTP 服务器。该命令不仅可以升级应用程序分区，还可以升级 at_customize.csv 中定义的用户自定义分区。如果您使用的是乐鑫发布的版本，该命令将只会升级到乐鑫发布的版本。请参考 AT+CIUPDATE 获取更多信息。

使用该命令升级自定义 bin 文件，请选择以下方式之一。

将 iot.espressif.cn 替换为您自己的 HTTP 服务器，并实现交互流程。 如何实现自己的 AT+CIUPDATE 命令，请参考 at/src/at_ota_cmd.c。

在 iot.espressif.cn 上创建一个设备，并在其上上传 bin 文件。（前提是模组中运行的固件已经对应您在乐鑫服务器上创建的设备。） 请参考使用 AT+CIUPDATE 进行 OTA 升级获取更多信息。

此命令的应用场景如下：

您只使用乐鑫发布的固件，只想升级到乐鑫发布的固件。

您希望升级自定义的 bin 文件，但没有自己的 HTTP 服务器。

您有自己的 HTTP 服务器。除了升级应用程序分区外，还希望升级在 at_customize.csv 文件中定义的用户自定义分区。

AT+WEBSERVER ¶

此命令通过浏览器或微信小程序升级 AT 固件。目前，该命令仅提供升级应用程序分区的功能。在开始升级之前，请启用 web 服务器命令并提前将 AT 固件复制到电脑或者手机上。您可以参考 AT+WEBSERVER 或者 Web Server AT 示例获取更多信息。

为了实现您自己的 HTML 页面，请参考示例 fs_image/index.html。为了实现您自己的 AT+WEBSERVER 命令，请参考示例 at/src/at_web_server_cmd.c。

此命令的应用场景如下：

您需要更方便快捷的 OTA 升级，不依赖于网络状态。

重要

如果您升级的固件为非乐鑫正式发布的固件，在升级完成后，您可能无法使用 AT+CIUPDATE 命令升级，除非您按照使用 AT+CIUPDATE 进行 OTA 升级创建了自己的设备。

使用 ESP-AT OTA 命令执行 OTA 升级¶

使用 AT+USEROTA 进行 OTA 升级¶

请参考 AT+USEROTA 获取更多信息。

使用 AT+CIUPDATE 进行 OTA 升级¶

通过 AT+CIUPDATE 命令升级自定义的 bin 文件，首先要做的就是将 bin 文件上传到 iot.espressif.cn 并且获取到 token 值。以下步骤描述了如何在 iot.espressif.cn 上创建设备并上传 bin 文件。

打开网站 http://iot.espressif.cn 或者 https://iot.espressif.cn。

打开 iot.espressif.cn 网站¶
点击网页右上角的 “Join”，输入您的名字，邮箱地址和密码。

加入 iot.espressif.cn¶

注解

当前 Join 功能暂不对新用户开放。如果您想使用该功能，请联系乐鑫。

点击网页左上角的 “Device”，然后点击 “Create” 来创建一个设备。

点击 “Device”¶

点击 “Create”¶
当设备创建成功后会生成一个密钥，如下图所示：

生成一个密钥¶
使用该密钥来编译您的 OTA bin 文件。配置 AT OTA token 密钥的过程如下如所示：

配置 AT OTA token 密钥 - 步骤 1¶

配置 AT OTA token 密钥 - 步骤 2 和 3¶

注解

如果使用 SSL OTA，选项 “The SSL token for AT OTA” 也需要配置。
点击 “Product” 进入网页，如下如所示。单击创建的设备，在 “ROM Deploy” 下输入版本和 corename。将步骤 5 中的 bin 文件重命令为 “ota.bin” 并保存。

输入版本和 corename¶
注解
- 如果您想要升级 at_customize.csv 中定义的用户自定义分区，只需将 ota.bin 替换为用户自定义分区的 bin 文件即可。
- 对于 corename 字段，此字段仅仅用于帮助您区分 bin 文件。
单击 ota.bin 将其保存为当前版本。

保存当前版本的 ota.bin¶
在设备上运行 AT+USEROTA 命令。如果网络已连接，将开始 OTA 升级。

重要

设置上传到 iot.espressif.cn 的 bin 文件名称时，请遵循以下规则：
- 如果升级 app 分区，请将 bin 文件名设置为 ota.bin。
- 如果升级用户自定义的分区，请将 bin 文件名设置为 at_customize.csv 中的 Name 字段。例如，如果升级 factory_Param 分区，请将其设置为 factory_ param.bin。
ESP-AT 将新固件存储在备用 OTA 分区中。这样，即使 OTA 由于意外原因失败，原始 ESP-AT 固件也能正常运行。但对于自定义分区，由于 ESP-AT 没有备份措施，请小心升级。
如果您打算从一开始只升级自定制的 bin 文件，那么在发布初始版本时，就应该将 OTA token 设置为自己的 token 值。

使用 AT+WEBSERVER 进行 OTA 升级¶

请参考 AT+WEBSERVER 和 Web Server AT 示例获取更多信息。

如何更新 ESP-IDF 版本¶

[English]

ESP-AT 固件基于乐鑫物联网开发框架（ESP-IDF），每个版本的 ESP-AT 固件对应某个特定的 ESP-IDF 版本。强烈建议使用 ESP-AT 工程默认的 ESP-IDF 版本，不建议 更新 ESP-IDF 版本，因为 libesp_*_at_core.a 底层的 ESP-IDF 版本与 ESP-AT 工程的 IDF 版本不一致可能会导致固件的错误操作。

但是，在某些特殊情况下，ESP-IDF 的小版本更新也可能适用于 ESP-AT 工程。如果您需要更新，本文档可作为参考。

ESP-AT 固件对应的 ESP-IDF 版本记录在 IDF_VERSION 文件中，这些文件分布在 module_config 文件夹下的不同模组文件夹中。该文件描述了模组固件所基于的 ESP-IDF 的分支、提交 ID 和仓库地址。例如，PLATFORM_ESP32 平台的 WROOM-32 模组的 IDF_VERSION 位于 module_config/module_esp32_default/IDF_VERSION。

如果您想为 ESP-AT 固件更新 ESP-IDF 版本，请按照以下步骤操作。

找到模组的 IDF_VERSION 文件。
根据需要更新其中的分支、提交 ID 和仓库地址。
删除 esp-at 根目录下原有的 esp-idf，以便下次编译时首先克隆 IDF_VERSION 中指定的 ESP-IDF 版本。
重新编译 ESP-AT 工程。

注意，当 ESP-AT 版本和 ESP-IDF 版本不匹配，编译时会报如下错误。

Please wait for the update to complete, which will take some time

ESP-AT 固件差异¶

[English]

本文档比较了同一 ESP 系列的 AT 固件在支持的命令集、硬件、模组方面的差异。

ESP32 系列¶

本节介绍以下 ESP32 系列 AT 固件的区别：

ESP32-WROOM-32_AT_Bin（本节简称为 WROOM Bin）
ESP32-WROVER-32_AT_Bin（本节简称为 WROVER Bin）
ESP32-PICO-D4_AT_Bin（本节简称为 PICO-D4 Bin）
ESP32-SOLO-1_AT_Bin（本节简称为 SOLO-1 Bin
ESP32-MINI-1_AT_Bin（本节简称为 MINI-1 Bin）
ESP32-D2WD_AT_Bin（本节简称为 D2WD Bin）
ESP32-QLOUD_AT_Bin（本节简称为 QCLOUD Bin）

支持的命令集¶

下表列出了官方适配的 ESP32 系列 AT 固件默认支持哪些命令集（用表示）、默认不支持但可以在配置和编译 ESP-AT 工程后支持的命令集（用表示）、完全不支持的命令集（用表示），下表没有列出的命令集也为完全不支持的命令集。正式发布的固件见 AT 固件，已适配但未发布的模组固件，需要自行编译。自行编译的固件无法从乐鑫官方服务器进行 OTA 升级。

命令集	WROOM Bin	WROVER Bin	PICO-D4 Bin	SOLO-1 Bin	MINI-1 Bin	D2WD Bin	QCLOUD Bin
base
user
wifi
net
MDNS
WPS
smartconfig
ping
MQTT
http
ble
ble hid
blufi
bt spp
bt a2dp
ethernet
FS
driver
WPA2
WEB
OTA
qcloud IoT

硬件差异¶

硬件	WROOM Bin	WROVER Bin	PICO-D4 Bin	SOLO-1 Bin	MINI-1 Bin	D2WD Bin	QCLOUD Bin
Flash	4 MB	4 MB	4 MB	4 MB	4 MB	2 MB	4 MB
PSRAM		8 MB
UART 管脚 1	TX: 17 RX: 16 CTS: 15 RTS: 14	TX: 22 RX: 19 CTS: 15 RTS: 14	TX: 22 RX: 19 CTS: 15 RTS: 14	TX: 17 RX: 16 CTS: 15 RTS: 14	TX: 22 RX: 19 CTS: 15 RTS: 14	TX: 22 RX: 19 CTS: 15 RTS: 14	TX: 17 RX: 16 CTS: 15 RTS: 14

1: UART 管脚可自定义，详情请参考如何设置 AT 端口管脚。

支持的模组¶

下表列出了 ESP32 系列 AT 固件支持的模组或芯片。

模组/芯片	WROOM Bin	WROVER Bin	PICO-D4 Bin	SOLO-1 Bin	MINI-1 Bin	D2WD Bin	QCLOUD Bin
ESP32-WROOM-32E
ESP32-WROOM-32UE
ESP32-WROOM-32D
ESP32-WROOM-32U
ESP32-WROOM-32
ESP32-WROOM-32SE
ESP32-WROVER-E
ESP32-WROVER-IE
ESP32-WROVER-B
ESP32-WROVER-IB
ESP32-WROVER
ESP32-WROVER-I
ESP32-SOLO-1
ESP32-D2WD
ESP32-MINI-1
ESP32-PICO-D4

ESP32-C3 系列¶

本节介绍以下 ESP32-C3 系列 AT 固件的区别：

ESP32-C3-MINI-1_AT_Bin（本节简称为 MINI-1 Bin）
ESP32-C3-QCLOUD_AT_BIN（本节简称为 QCLOUD Bin）

支持的命令集¶

下表列出了官方适配的 ESP32-C3 系列 AT 固件默认支持哪些命令集（用表示）、默认不支持但可以在配置和编译 ESP-AT 工程后支持的命令集（用表示）、完全不支持的命令集（用表示），下表没有列出的命令集也为完全不支持的命令集。正式发布的固件见 AT 固件，已适配但未发布的模组固件，需要自行编译。自行编译的固件无法从乐鑫官方服务器进行 OTA 升级。

命令集	MINI-1 Bin	QCLOUD Bin
base
user
wifi
net
MDNS
WPS
smartconfig
ping
MQTT
http
FS
driver
WPA2
WEB
OTA
qcloud IoT

硬件差异¶

硬件	MINI-1	QCLOUD
Flash	4 MB	4 MB
PSRAM
UART 管脚 2	TX: 7 RX: 6 CTS: 5 RTS: 4	TX: 7 RX: 6 CTS: 5 RTS: 4

2: UART 管脚可自定义，详情请参考如何设置 AT 端口管脚。

支持的模组¶

下表列出了 ESP32-C3 系列 AT 固件支持的模组或芯片。

模组/芯片	MINI-1 Bin	QCLOUD Bin
ESP32-C3-MINI-1

如何从 GitHub 下载最新临时版本 AT 固件¶

[English]

由于 ESP-AT 在 GitHub 上启用 CI（持续集成），因此每次代码被推送到 GitHub 都会生成 ESP-AT 固件的临时版本。

注解

AT 固件的临时版本仅用于测试，乐鑫不对其负责。您需要自行测试和保存固件。

以下步骤指导您如何从 GitHub 下载最新临时版本 AT 固件。在开始之前，请先登录您的 GitHub 账号，因为下载固件需要登录权限。

打开网页 https://github.com/espressif/esp-at。

ESP-AT GitHub 官方页面¶
点击 “Actions” 进入 “Actions” 页面。

点击 Actions¶

Actions 页面¶
点击最新的 workflow 进入 workflow 页面。

点击最新的 Workflow¶

最新的 Workflow 页面¶

如果您想下载指定分支的临时固件，点击 “Branch” 进入指定分支的 workflow 页面。

点击 Branch¶
将页面滚动到最后，在 Artifacts 页面中选择相对应的模组。

Artifacts 页面¶
点击下载模组的最新临时版本 AT 固件。

注解

如果您在 Artifacts 页面中没有找到对应的模组，请参考 ESP-AT 固件差异选择类似固件进行下载。

自定义 Bluetooth LE Services 工具¶

[English]

ESP-AT 提供 python 脚本 BLEService.py 将自定义 Bluetooth LE 服务转换为 ble_data.bin。关于自定义 Bluetooth LE 服务，请参考文档如何自定义低功耗蓝牙服务。

生成二进制文件
下载或者更新二进制文件

生成二进制文件 ¶

请选择以下方式之一生成 ble_data.bin。

脚本生成
编译期间生成

脚本生成 ¶

脚本 BLEService.py 的路径是 tools/BLEService.py。您可以通过 -h 选项获取脚本的帮助信息。您也可以直接通过以下命令生成 ble_data.bin 二进制文件。

python <SCRIPT_PATH> [-t TARGET_FILE_NAME] <source_file>

SCRIPT_PATH：脚本路径。如果您正处于 “tools” 目录下，则 SCRIPT_PATH 为 BLEService.py。
TARGET_FILE_NAME：要保存生成的目标文件名（目标文件名的绝对地址或者相对地址）；如果没有指定，则会在 source_file 所在目录下生成 ATBleService.bin 二进制文件。
source_file：您想转换的 Bluetooth LE GATT 服务源文件（源文件的绝对地址或者相对地址）。

例如，您可以执行以下命令在 tools 目录下生成 ble_data.bin 二进制文件。

python BLEService.py -t ble_data.bin ../components/customized_partitions/raw_data/ble_data/example.csv

编译期间生成 ¶

ESP-AT 中 Bluetooth LE GATT service 文件的存储路径为 components/customized_partitions/raw_data。

对于怎样自定义 Bluetooth LE 服务，请参考文档如何自定义低功耗蓝牙服务。

对于怎样编译 ESP-AT 工程，请参考文档编译 ESP-AT 工程。

下载或者更新二进制文件 ¶

脚本 BLEService.py 仅仅负责将证书文件转换为二进制文件。您可以通过以下方式将二进制文件烧录到 flash 中：

通过烧录工具烧录二进制文件

Windows

请下载 Windows Flash 下载工具。

请参考 zip 文件夹中 readme.pdf 或者 doc 目录获取更多有关该工具的信息。
Linux or macOS

请使用 esptool.py。

您可以参考如何自定义低功耗蓝牙服务获取更多信息。
esptool.py --chip auto --port PORTNAME --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size 4MB ADDRESS FILEDIRECTORY
将 PORTNAME 替换为您的串口。将 ADDRESS 替换为烧录地址。将 FILEDIRECTORY 替换为二进制文件所在的目录。

通过命令更新证书二进制文件

AT+SYSFLASH 命令

以 ESP32 模组为例，您可以执行以下命令来更新 ble_data 分区。请参考 AT+SYSFLASH 获取更多信息。
查询 flash 用户分区

命令：
AT+SYSFLASH?
响应：
+SYSFLASH:"ble_data",64,1,0x21000,0x3000
+SYSFLASH:"server_cert",64,2,0x24000,0x2000
+SYSFLASH:"server_key",64,3,0x26000,0x2000
+SYSFLASH:"server_ca",64,4,0x28000,0x2000
+SYSFLASH:"client_cert",64,5,0x2a000,0x2000
+SYSFLASH:"client_key",64,6,0x2c000,0x2000
+SYSFLASH:"client_ca",64,7,0x2e000,0x2000
+SYSFLASH:"factory_param",64,8,0x30000,0x1000
+SYSFLASH:"wpa2_cert",64,9,0x31000,0x2000
+SYSFLASH:"wpa2_key",64,10,0x33000,0x2000
+SYSFLASH:"wpa2_ca",64,11,0x35000,0x2000
+SYSFLASH:"mqtt_cert",64,12,0x37000,0x2000
+SYSFLASH:"mqtt_key",64,13,0x39000,0x2000
+SYSFLASH:"mqtt_ca",64,14,0x3b000,0x2000
+SYSFLASH:"fatfs",1,129,0x70000,0x90000

OK
擦除 ble_data 分区

命令：
AT+SYSFLASH=0,"ble_data"
响应：
OK
更新 ble_data 分区

命令：
AT+SYSFLASH=1,"ble_data",0,2344
响应：
>
当 <operator> 为 write 时，系统收到此命令后先换行返回 >，此时您可以输入要写的数据，数据长度应与 <length> 一致。当写入操作完成之后，系统会提示以下信息。
OK
AT+CIUPDATE

例如，您可以执行以下命令来更新 ble_data 分区（前提是您必须使用 Wi-Fi 功能）。请参考 AT+CIUPDATE 获取更多信息。

重要

如果您想通过这种方式更新 ble_data 分区，您必须实现自己的 OTA 设备，请参考文档如何实现 OTA 升级。
AT+CIUPDATE=1,"v2.2.0.0","ble_data"

注解

您必须确保烧录的地址是正确的，否则 ESP-AT 固件可能不能工作。查看烧录地址的最简单方法是执行命令 AT+SYSFLASH?。

如何生成 PKI 文件¶

[English]

ESP-AT 提供 python 脚本 AtPKI.py 将 SSL 服务器证书文件，SSL 客户端证书文件，MQTT 证书文件和 WPA2 证书文件（包括 CA 证书， cert 证书和私钥）转换为二进制文件。

证书二进制文件格式
生成证书二进制文件
下载或者更新证书二进制文件

证书二进制文件格式 ¶

除了将证书文件转换为二进制文件外，脚本 AtPKI.py 还会向二进制文件中添加一些额外信息。

转换单个证书文件时，将会在文件头中以小端模式添加 12 字节数据，并在文件末尾进行 4 字节对齐。

字段

描述

magic code（2 字节）

0xF1 0xF1

列表大小（2 字节）

证书文件的数量

长度（4 字节）

剩余文件长度 = 总的文件大小 - magic code 大小 - 列表大小 - 长度大小

类型（1 字节）

ca: 0x01

certificate: 0x02

key: 0x03

ID（1 字节）

用于匹配证书文件

内容长度（2 字节）

转换为二进制文件的证书文件的大小

以生成证书二进制文件小节中生成的 client_cert.bin 文件为例，二进制文件开头的小端模式 12 字节数据如下所示：

字段

描述

magic code（2 字节）

0xF1 0xF1

列表大小（2 字节）

0x02 0x00

长度（4 字节）

0x20 0x09 0x00 0x00

类型（1 字节）

0x02

ID（1 字节）

0x00

内容长度（2 字节）

0x8C 0x04

转换多个证书文件时，脚本 AtPKI.py 还会在除第一个证书文件外的每个证书文件的开头插入 4 字节数据。文件开头的小端模式 4 字节数据如下：

字段

描述

类型（1 字节）

ca: 0x01

certificate: 0x02

key: 0x03

ID（1 字节）

用于匹配证书文件

内容长度（2 字节）

转换为二进制文件的证书文件的大小

以生成证书二进制文件小节中生成的 client_cert.bin 文件为例，文件开头的小端模式 4 字节数据如下所示：

字段

描述

类型（1 字节）

certificate: 0x02

ID（1 字节）

0x01

内容长度（2 字节）

0x8C 0x04

生成证书二进制文件 ¶

请选择以下方式之一生成证书二进制文件。

脚本生成
编译期间生成

脚本生成 ¶

脚本 AtPKI.py 的路径是 tools/AtPKI.py。您可以通过 -h 选项获取脚本的帮助信息。您也可以直接通过以下命令生成二进制文件。

python <SCRIPT_PATH> generate_bin [-b OUTPUT_BIN_NAME] <PKI_LIST> <source_file>

SCRIPT_PATH：脚本路径。如果您正处于 “tools” 目录下，则 SCRIPT_PATH 为 AtPKI.py。
OUTPUT_BIN_NAME：要保存生成的目标文件名（目标文件名的绝对地址或者相对地址）；如果 -b OUTPUT_BIN_NAME 被省略，则脚本将会在当前目录下生成 PKI.bin 文件。
PKI_LIST：必须等于 ca、cert、key 中的一个。
source_file：您想转换的证书源文件（证书源文件的绝对地址或者相对地址）。

以 ESP-AT 的 SSL 客户端证书文件为例，您可以执行下面的命令在 tools 目录下生成 client_cert.bin 二进制文件。

python AtPKI.py generate_bin -b ./client_cert.bin  cert ../components/customized_partitions/raw_data/client_cert/client_cert_00.crt cert ../components/customized_partitions/raw_data/client_cert/client_cert_01.crt

编译期间生成 ¶

ESP-AT 中证书文件的存储路径为 components/customized_partitions/raw_data。

以 ESP-AT 的 SSL 客户端证书文件为例。如果您想生成自己的 SSL 客户端证书二进制文件，您必须将目录 client_ca 下的 CA 证书替换为自己的 CA 证书，将目录 client_cert 目录下的 cert 证书替换为自己的 cert 证书，将 client_ key 目录下的私钥替换为自己的私钥。

如果您有多套证书文件，请按照您的证书链依次放置于对应的目录下。建议您可以将文件名以数字结尾以确保证书文件的解析顺序。

替换完成之后，您可以参考编译 ESP-AT 工程来编译 ESP-AT 工程。

下载或者更新证书二进制文件 ¶

脚本 AtPKI.py 仅仅负责将证书文件转换为二进制文件。您可以通过以下方式将二进制文件烧录到 flash 中：

通过烧录工具烧录¶

Windows

请下载 Windows Flash 下载工具。

请参考 zip 文件夹中 readme.pdf 或者 doc 目录获取更多有关该工具的信息。
Linux or macOS

请使用 esptool.py。

您可以在 ESP-AT 根目录下执行下面的命令烧录二进制文件。
```
esptool.py --chip auto --port PORTNAME --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size 4MB ADDRESS FILEDIRECTORY
```
将 PORTNAME 替换为您的串口。将 ADDRESS 替换为烧录地址。将 FILEDIRECTORY 替换为二进制文件所在的目录。

通过命令更新¶

AT+SYSFLASH 命令

以 ESP32 模组为例，您可以执行以下命令来更新 client_cert 分区。请参考 AT+SYSFLASH 获取更多信息。

查询 flash 用户分区

命令：

AT+SYSFLASH?

响应：

+SYSFLASH:"ble_data",64,1,0x21000,0x3000
+SYSFLASH:"server_cert",64,2,0x24000,0x2000
+SYSFLASH:"server_key",64,3,0x26000,0x2000
+SYSFLASH:"server_ca",64,4,0x28000,0x2000
+SYSFLASH:"client_cert",64,5,0x2a000,0x2000
+SYSFLASH:"client_key",64,6,0x2c000,0x2000
+SYSFLASH:"client_ca",64,7,0x2e000,0x2000
+SYSFLASH:"factory_param",64,8,0x30000,0x1000
+SYSFLASH:"wpa2_cert",64,9,0x31000,0x2000
+SYSFLASH:"wpa2_key",64,10,0x33000,0x2000
+SYSFLASH:"wpa2_ca",64,11,0x35000,0x2000
+SYSFLASH:"mqtt_cert",64,12,0x37000,0x2000
+SYSFLASH:"mqtt_key",64,13,0x39000,0x2000
+SYSFLASH:"mqtt_ca",64,14,0x3b000,0x2000
+SYSFLASH:"fatfs",1,129,0x70000,0x90000

OK

擦除 client_cert 分区

命令：
AT+SYSFLASH=0,"client_cert"
响应：
OK

更新 client_cert 分区

命令：
AT+SYSFLASH=1,"client_cert",0,2344
响应：
>
当 <operator> 为 write 时，系统收到此命令后先换行返回 >，此时您可以输入要写的数据，数据长度应与 <length> 一致。当写入操作完成之后，系统会提示以下信息。
OK

AT+CIUPDATE 命令

例如，您可以执行以下命令来更新 client_ca 分区。请参考 AT+CIUPDATE 获取更多信息。

重要

如果您想通过这种方式更新 client_ca 分区，您必须实现自己的 OTA 设备，请参考文档如何实现 OTA 升级。
```
AT+CIUPDATE=1,"v2.2.0.0","client_ca"
```

注解

您必须确保烧录的地址是正确的，否则 ESP-AT 固件可能不能工作。查看烧录地址的最简单方法是执行命令 AT+SYSFLASH?。

AT API Reference¶

Header File¶

at/include/esp_at_core.h

Functions¶

void esp_at_module_init(uint32_t netconn_max, const uint8_t *custom_version)¶

This function should be called only once, before any other AT functions are called.

Parameters

netconn_max: the maximum number of the link in the at module
custom_version: version information by custom

esp_at_para_parse_result_type esp_at_get_para_as_digit(int32_t para_index, int32_t *value)¶

Parse digit parameter from command string.

Return

ESP_AT_PARA_PARSE_RESULT_OK : succeed
ESP_AT_PARA_PARSE_RESULT_FAIL : fail
ESP_AT_PARA_PARSE_RESULT_OMITTED : this parameter is OMITTED

Parameters

para_index: the index of parameter
value: the value parsed

esp_at_para_parse_result_type esp_at_get_para_as_str(int32_t para_index, uint8_t **result)¶

Parse string parameter from command string.

Return

ESP_AT_PARA_PARSE_RESULT_OK : succeed
ESP_AT_PARA_PARSE_RESULT_FAIL : fail
ESP_AT_PARA_PARSE_RESULT_OMITTED : this parameter is OMITTED

Parameters

para_index: the index of parameter
result: the pointer that point to the result.

void esp_at_port_recv_data_notify_from_isr(int32_t len)¶

Calling the esp_at_port_recv_data_notify_from_isr to notify at module that at port received data. When received this notice,at task will get data by calling get_data_length and read_data in esp_at_device_ops. This function MUST be used in isr.

Parameters

len: data length

bool esp_at_port_recv_data_notify(int32_t len, uint32_t msec)¶

Calling the esp_at_port_recv_data_notify to notify at module that at port received data. When received this notice,at task will get data by calling get_data_length and read_data in esp_at_device_ops. This function MUST NOT be used in isr.

Return

true : succeed
false : fail

Parameters

len: data length
msec: timeout time,The unit is millisecond. It waits forever,if msec is portMAX_DELAY.

void esp_at_transmit_terminal_from_isr(void)¶: terminal transparent transmit mode,This function MUST be used in isr.

void esp_at_transmit_terminal(void)¶: terminal transparent transmit mode,This function MUST NOT be used in isr.

bool esp_at_custom_cmd_array_regist(const esp_at_cmd_struct *custom_at_cmd_array, uint32_t cmd_num)¶

regist at command set, which defined by custom,

Parameters

custom_at_cmd_array: at command set
cmd_num: command number

void esp_at_device_ops_regist(esp_at_device_ops_struct *ops)¶

regist device operate functions set,

Parameters

ops: device operate functions set

bool esp_at_custom_net_ops_regist(int32_t link_id, esp_at_custom_net_ops_struct *ops)¶

bool esp_at_custom_ble_ops_regist(int32_t conn_index, esp_at_custom_ble_ops_struct *ops)¶

void esp_at_custom_ops_regist(esp_at_custom_ops_struct *ops)¶

regist custom operate functions set interacting with AT,

Parameters

ops: custom operate functions set

uint32_t esp_at_get_version(void)¶

get at module version number,

Return: at version bit31~bit24: at main version bit23~bit16: at sub version bit15~bit8 : at test version bit7~bit0 : at custom version

void esp_at_response_result(uint8_t result_code)¶

response AT process result,

Parameters

result_code: see esp_at_result_code_string_index

int32_t esp_at_port_write_data(uint8_t *data, int32_t len)¶

write data into device,

Return

>= 0 : the real length of the data written
others : fail.

Parameters

data: data buffer to be written
len: data length

int32_t esp_at_port_read_data(uint8_t *data, int32_t len)¶

read data from device,

Return

>= 0 : the real length of the data read from device
others : fail

Parameters

data: data buffer
len: data length

bool esp_at_port_wait_write_complete(int32_t timeout_msec)¶

wait for transmitting data completely to peer device,

Return

true : succeed,transmit data completely
false : fail

Parameters

timeout_msec: timeout time,The unit is millisecond.

int32_t esp_at_port_get_data_length(void)¶

get the length of the data received,

Return

>= 0 : the length of the data received
others : fail

bool esp_at_base_cmd_regist(void)¶: regist at base command set. If not,you can not use AT base command

bool esp_at_user_cmd_regist(void)¶: regist at user command set. If not,you can not use AT user command

bool esp_at_wifi_cmd_regist(void)¶: regist at wifi command set. If not,you can not use AT wifi command

bool esp_at_net_cmd_regist(void)¶: regist at net command set. If not,you can not use AT net command

bool esp_at_mdns_cmd_regist(void)¶: regist at mdns command set. If not,you can not use AT mdns command

bool esp_at_driver_cmd_regist(void)¶: regist at driver command set. If not,you can not use AT driver command

bool esp_at_wps_cmd_regist(void)¶: regist at wps command set. If not,you can not use AT wps command

bool esp_at_smartconfig_cmd_regist(void)¶: regist at smartconfig command set. If not,you can not use AT smartconfig command

bool esp_at_ping_cmd_regist(void)¶: regist at ping command set. If not,you can not use AT ping command

bool esp_at_http_cmd_regist(void)¶: regist at http command set. If not,you can not use AT http command

bool esp_at_mqtt_cmd_regist(void)¶: regist at mqtt command set. If not,you can not use AT mqtt command

bool esp_at_ble_cmd_regist(void)¶: regist at ble command set. If not,you can not use AT ble command

bool esp_at_ble_hid_cmd_regist(void)¶: regist at ble hid command set. If not,you can not use AT ble hid command

bool esp_at_blufi_cmd_regist(void)¶: regist at blufi command set. If not,you can not use AT blufi command

bool esp_at_bt_cmd_regist(void)¶: regist at bt command set. If not,you can not use AT bt command

bool esp_at_bt_spp_cmd_regist(void)¶: regist at bt spp command set. If not,you can not use AT bt spp command

bool esp_at_bt_a2dp_cmd_regist(void)¶: regist at bt a2dp command set. If not,you can not use AT bt a2dp command

bool esp_at_fs_cmd_regist(void)¶: regist at fs command set. If not,you can not use AT fs command

bool esp_at_eap_cmd_regist(void)¶: regist at WPA2 Enterprise AP command set. If not,you can not use AT EAP command

bool esp_at_eth_cmd_regist(void)¶: regist at ethernet command set. If not,you can not use AT ethernet command

bool esp_at_custom_cmd_line_terminator_set(uint8_t *terminator)¶

Set AT command terminator, by default, the terminator is “\r\n” You can change it by calling this function, but it just supports one character now.

Return

true : succeed,transmit data completely
false : fail

Parameters

terminator: the line terminator

uint8_t *esp_at_custom_cmd_line_terminator_get(void)¶

Get AT command line terminator,by default, the return string is “\r\n”.

Return: the command line terminator

const esp_partition_t *esp_at_custom_partition_find(esp_partition_type_t type, esp_partition_subtype_t subtype, const char *label)¶

Find the partition which is defined in at_customize.csv.

Return

pointer to esp_partition_t structure, or NULL if no partition is found. This pointer is valid for the lifetime of the application

Parameters

type: the type of the partition
subtype: the subtype of the partition
label: Partition label

void esp_at_port_enter_specific(esp_at_port_specific_callback_t callback)¶

Set AT core as specific status, it will call callback if receiving data. for example:

static void wait_data_callback (void)
{
    xSemaphoreGive(sync_sema);
}

void process_task(void* para)
{
    vSemaphoreCreateBinary(sync_sema);
    xSemaphoreTake(sync_sema,portMAX_DELAY);
    esp_at_port_write_data((uint8_t *)">",strlen(">"));
    esp_at_port_enter_specific(wait_data_callback);
    while(xSemaphoreTake(sync_sema,portMAX_DELAY)) {
        len = esp_at_port_read_data(data, data_len);
        // TODO:
    }
}

Parameters

callback: which will be called when received data from AT port

void esp_at_port_exit_specific(void)¶: Exit AT core as specific status.

const uint8_t *esp_at_get_current_cmd_name(void)¶: Get current AT command name.

Structures¶

struct esp_at_cmd_struct¶

esp_at_cmd_struct used for define at command

Public Members

char *at_cmdName¶: at command name

uint8_t (*at_testCmd)(uint8_t *cmd_name)¶: Test Command function pointer

uint8_t (*at_queryCmd)(uint8_t *cmd_name)¶: Query Command function pointer

uint8_t (*at_setupCmd)(uint8_t para_num)¶: Setup Command function pointer

uint8_t (*at_exeCmd)(uint8_t *cmd_name)¶: Execute Command function pointer

struct esp_at_device_ops_struct¶

esp_at_device_ops_struct device operate functions struct for AT

Public Members

int32_t (*read_data)(uint8_t *data, int32_t len)¶: read data from device

int32_t (*write_data)(uint8_t *data, int32_t len)¶: write data into device

int32_t (*get_data_length)(void)¶: get the length of data received

bool (*wait_write_complete)(int32_t timeout_msec)¶: wait write finish

struct esp_at_custom_net_ops_struct¶

esp_at_custom_net_ops_struct custom socket callback for AT

Public Members

int32_t (*recv_data)(uint8_t *data, int32_t len)¶: callback when socket received data

void (*connect_cb)(void)¶: callback when socket connection is built

void (*disconnect_cb)(void)¶: callback when socket connection is disconnected

struct esp_at_custom_ble_ops_struct¶

esp_at_custom_ble_ops_struct custom ble callback for AT

Public Members

int32_t (*recv_data)(uint8_t *data, int32_t len)¶: callback when ble received data

void (*connect_cb)(void)¶: callback when ble connection is built

void (*disconnect_cb)(void)¶: callback when ble connection is disconnected

struct esp_at_custom_ops_struct¶

esp_at_ops_struct some custom function interacting with AT

Public Members

void (*status_callback)(esp_at_status_type status)¶: callback when AT status changes

void (*pre_deepsleep_callback)(void)¶: callback before enter deep sleep

void (*pre_restart_callback)(void)¶: callback before restart

Macros¶

at_min(x, y)¶

at_max(x, y)¶

ESP_AT_ERROR_NO(subcategory, extension)¶

ESP_AT_CMD_ERROR_OK¶: No Error

ESP_AT_CMD_ERROR_NON_FINISH¶: terminator character not found (“\r\n” expected)

ESP_AT_CMD_ERROR_NOT_FOUND_AT¶: Starting “AT” not found (or at, At or aT entered)

ESP_AT_CMD_ERROR_PARA_LENGTH(which_para)¶: parameter length mismatch

ESP_AT_CMD_ERROR_PARA_TYPE(which_para)¶: parameter type mismatch

ESP_AT_CMD_ERROR_PARA_NUM(need, given)¶: parameter number mismatch

ESP_AT_CMD_ERROR_PARA_INVALID(which_para)¶: the parameter is invalid

ESP_AT_CMD_ERROR_PARA_PARSE_FAIL(which_para)¶: parse parameter fail

ESP_AT_CMD_ERROR_CMD_UNSUPPORT¶: the command is not supported

ESP_AT_CMD_ERROR_CMD_EXEC_FAIL(result)¶: the command execution failed

ESP_AT_CMD_ERROR_CMD_PROCESSING¶: processing of previous command is in progress

ESP_AT_CMD_ERROR_CMD_OP_ERROR¶: the command operation type is error

Type Definitions¶

typedef void (*esp_at_port_specific_callback_t)(void)¶: AT specific callback type.

Enumerations¶

enum esp_at_status_type¶

esp_at_status some custom function interacting with AT

Values:

ESP_AT_STATUS_NORMAL = 0x0¶: Normal mode.Now mcu can send AT command

ESP_AT_STATUS_TRANSMIT¶: Transparent Transmition mode

enum esp_at_module¶

module number,Now just AT module

Values:

ESP_AT_MODULE_NUM = 0x01¶: AT module

enum esp_at_error_code¶

subcategory number

Values:

ESP_AT_SUB_OK = 0x00¶: OK

ESP_AT_SUB_COMMON_ERROR = 0x01¶: reserved

ESP_AT_SUB_NO_TERMINATOR = 0x02¶: terminator character not found (“\r\n” expected)

ESP_AT_SUB_NO_AT = 0x03¶: Starting “AT” not found (or at, At or aT entered)

ESP_AT_SUB_PARA_LENGTH_MISMATCH = 0x04¶: parameter length mismatch

ESP_AT_SUB_PARA_TYPE_MISMATCH = 0x05¶: parameter type mismatch

ESP_AT_SUB_PARA_NUM_MISMATCH = 0x06¶: parameter number mismatch

ESP_AT_SUB_PARA_INVALID = 0x07¶: the parameter is invalid

ESP_AT_SUB_PARA_PARSE_FAIL = 0x08¶: parse parameter fail

ESP_AT_SUB_UNSUPPORT_CMD = 0x09¶: the command is not supported

ESP_AT_SUB_CMD_EXEC_FAIL = 0x0A¶: the command execution failed

ESP_AT_SUB_CMD_PROCESSING = 0x0B¶: processing of previous command is in progress

ESP_AT_SUB_CMD_OP_ERROR = 0x0C¶: the command operation type is error

enum esp_at_para_parse_result_type¶

the result of AT parse

Values:

ESP_AT_PARA_PARSE_RESULT_FAIL = -1¶: parse fail,Maybe the type of parameter is mismatched,or out of range

ESP_AT_PARA_PARSE_RESULT_OK = 0¶: Successful

ESP_AT_PARA_PARSE_RESULT_OMITTED¶: the parameter is OMITTED.

enum esp_at_result_code_string_index¶

the result code of AT command processing

Values:

ESP_AT_RESULT_CODE_OK = 0x00¶: “OK”

ESP_AT_RESULT_CODE_ERROR = 0x01¶: “ERROR”

ESP_AT_RESULT_CODE_FAIL = 0x02¶: “ERROR”

ESP_AT_RESULT_CODE_SEND_OK = 0x03¶: “SEND OK”

ESP_AT_RESULT_CODE_SEND_FAIL = 0x04¶: “SEND FAIL”

ESP_AT_RESULT_CODE_IGNORE = 0x05¶: response nothing, just change internal status

ESP_AT_RESULT_CODE_PROCESS_DONE = 0x06¶: response nothing, just change internal status

ESP_AT_RESULT_CODE_OK_AND_INPUT_PROMPT = 0x07¶

ESP_AT_RESULT_CODE_MAX¶

Header File¶

at/include/esp_at.h

Functions¶

const char *esp_at_get_current_module_name(void)¶: get current module name

const char *esp_at_get_module_name_by_id(uint32_t id)¶: get module name by index

uint32_t esp_at_get_module_id(void)¶: get current module id

void esp_at_board_init(void)¶: init peripheral and default parameters in factory_param.bin

bool esp_at_web_server_cmd_regist(void)¶: regist WiFi config via web command. If not,you can not use web server to config wifi connect

Macros¶

ESP_AT_PORT_TX_WAIT_MS_MAX¶

ESP_AT_FACTORY_PARAMETER_SIZE¶

第三方定制化 AT 命令和固件¶

腾讯云 IoT AT 命令和固件¶

腾讯云 IoT AT 命令集¶

本文档主要介绍腾讯云 IoT AT 命令、错误码及应用说明，针对 ESP32 & ESP32-C3 设备，下表为本文档的目录。

说明
TC 设备信息设置命令
TC MQTT 命令
TC OTA 命令
URC 模组主动上报 MCU 消息
Wi-Fi 配网及 AT 辅助命令
TC 网关子设备命令
错误码
应用说明

说明 ¶

术语解释 ¶

术语	含义
MQTT	一种基于轻量级代理的 Pub/Sub 模型的消息传输协议
MCU	微控制单元，一般为通讯模组的上位机
Topic	主题，Pub/Sub 模型中消息的通信媒介，Pub/Sub 必须要有主题，只有当订阅了某个主题后，才能收到相应主题数据信息，才能进行通信
Pub	设备端的发布协议，意思是往 Topic 中发布消息
Sub	设备端的订阅协议，意思是从 Topic 中订阅消息
URC	全称 Unsolicited Result Code，非请求结果码，一般为模组给 MCU 的串口返回

更多信息请参考腾讯物联网通信词汇表及其它相关文档。

符号说明 ¶

本文档所有语法声明中（包括测试命令、读取命令、设置命令），所有形如 "xxx" 的双引号引注信息，都是确定内容的信息，例：

命令
```
AT+TCDEVINFOSET=?
```
响应
```
+TCDEVINFOSET: "TLSMODE (0/1/2)","PRODUCTID","DEVICENAME"[,"DEVICESECRET"]

OK
```
"ProductId"、"DeviceName" 等指确定的字符串 “ProductId”、”DeviceName”

本文档所有语法声明中（包括测试命令、读取命令、设置命令），所有形如 <xxx> 的尖角括号引注信息，都是指变量信息，例：

命令
```
AT+TCDEVINFOSET?
```
响应
```
+TCDEVINFOSET: <tlsmode>,<productId>,<devicename>,[,<devicesecret>]

OK
```
<productId>、<devicename> 等参数指实际的产品 ID 和设备名称，如 CTQS08Y5LG、"Dev01"

在表示具体的数据时，字符串类型和枚举类型的数据需要由双引号 "xx" 引注，数值型数据直接以数据表示。例：

命令
```
AT+TCCERTADD="cdev_cert.crt",1428
```
响应
```
OK
>
+TCCERTADD: OK
```
1428 表示数值型数据，"cdev_cert.crt" 表示字符串型，建议用户参照示例编写程序。

关于空格，只有回码的冒号和信息之间有一个空格，其他都没有空格。

校验和 (BCC) 生成方法，返回十进制校验和：

int CalcCheck(BYTE* Bytes, int len){
      int i, result;
      for (result = Bytes[0], i = 1; i < len ; i++){
              result ^= Bytes[i];
      }
      return result;
}

ESP-AT 命令说明 ¶

ESP-AT 命令集及使用说明请参考乐鑫官方 ESP-AT 用户指南及 GitHub ESP-AT 项目。

对于 ESP-AT 机制，有如下注意事项：

每条 AT 命令总字符长度不可超过 256 字节，否则会报错。
每条 AT 命令都应以 /r/n 为结束符。
如果AT命令的参数内容包含了特殊字符如双引号 " 、逗号 , 等，需要加 \ 进行转义，比如 PUB 消息的 payload 采用的 JSON 数据格式为 {"action": "publish_test", "count":"0"}，则应该转义为 {\"action\":\"publish_test\"\,\"count\":\"0\"} 再传入，否则会报错。
如果上一个 AT 命令还没处理完成，再发送新的命令会返回如下错误：
```
ERR CODE:0x010b0000

busy p...
```

TC 设备信息设置命令 ¶

AT+TCDEVINFOSET：平台设备信息设置 ¶

功能¶

设置腾讯云物联网平台创建的产品及设备信息

测试命令¶

命令：

AT+TCDEVINFOSET=?

响应：

+TCDEVINFO:"TLS_MODE (1)","PRODUCT_ID","DEVICE_NAME","DEVICE_SECRET_BCC","PRODUCT_REGION"

OK

读取命令¶

命令：

AT+TCDEVINFOSET?

响应：

+TCDEVINFOSET:<tls_mode>,<product_id>,<device_name>,<devicesecret_checksum>,<product_region>

OK

或

+CME ERROR: <err>

说明：

ESP32 & ESP32-C3 模组返回 <tls_mode> 为 1，且不返回 devicesecret 的字符串内容，只返回 devicesecret 字符串的校验和 (BCC)

设置命令¶

命令：

AT+TCDEVINFOSET=<tls_mode>,<product_id>,<device_name>,<device_secret>[,<product_region>]

响应：

OK

或

+CME ERROR: <err>

说明：

如果模组已经连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送断开连接命令 (AT+TCMQTTDISCONN) 才能执行该命令
如果输入合法，首先返回OK，接下来返回设备信息设置成功与否:
- +TCDEVINFOSET:OK：设置成功
- TCDEVINFOSET:FAIL<err_code>：设置失败

参数¶

<tls_mode>：接入方式，必填项，仅支持模式 1
- 0：直连模式
- 1：TLS 密钥方式
- 2：TLS 证书方式，数值类型
<product_id>：产品 id，必填项，字符串类型，最大长度 10 字节
<device_name>：设备名称，必填项，字符串类型，最大长度 48 字节
<device_secret>：设备密钥，必填项，字符串类型，最大长度 44 字节
<product_region>：产品区域，选填项，字符串类型，最大长度 24 字节，如果不提供，默认为中国大陆公有云 “ap-guangzhou”

示例¶

// 设置成功
AT+TCDEVINFOSET=1,"CTQS08Y5LG","Dev01","ZHNkIGRzZCA="
OK
+TCDEVINFOSET:OK

AT+TCPRDINFOSET：平台产品信息设置 ¶

功能¶

设置腾讯云物联网平台创建的产品信息，适用于产品级密钥场景

测试命令¶

命令：

AT+TCPRDINFOSET=?

响应：

+TCPRDINFOSET:"TLS_MODE(1)","PRODUCT_ID","PRODUCT_SECRET_BCC","DEVICE_NAME","PRODUCT_REGION"

OK

读取命令¶

命令：

AT+TCPRDINFOSET?

响应：

+TCPRDINFOSET:<tls_mode>,<product_ID>,<product_secret_checksum>,<device_name>,<product_region>

OK

设置命令¶

命令：

AT+TCPRDINFOSET=<tls_mode>,<product_ID>,<product_secret>,<device_name>,<product_region>

响应：

OK

或

+CME ERROR: <err>

说明：

如果模组已经连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送断开连接命令 (AT+TCMQTTDISCONN) 才能执行该命令
如果输入合法，首先返回 OK，接下来返回设备信息设置成功与否
- +TCPRDINFOSET:OK：设置成功，产品数据会保存到 flash，掉电不丢失
- +TCPRDINFOSET:FAIL,<err_code>：设置失败

参数¶

<tls_mode>：接入方式，必填项
- 0：直连模式，
- 1：TLS 密钥方式
- 2：TLS 证书方式，数值类型
<product_ID>：产品 ID，必填项，字符串类型，最大长度 10
<product_secret>：产品密钥，必填项，字符串类型，最大长度 32
<device_name>：设备名称，必填项，字符串类型，最大长度 48
<product_region>：产品区域，选填项，字符串类型，最大长度 24 字节，如果不提供，默认为中国大陆公有云 “ap-guangzhou”

示例¶

AT+TCPRDINFOSET=1,"CTQS08Y5LG","ZHNkIGRzZCA=","Dev01"

OK
+TCPRDINFOSET:OK

AT+TCDEVREG：执行设备动态注册 ¶

功能¶

采用产品级密钥场景下，执行设备动态注册并获取设备信息

测试命令¶

命令：

AT+TCDEVREG=?

响应：

OK

执行命令¶

命令：

AT+TCDEVREG

响应：

OK

或

+CME ERROR: <err>

说明¶

使用产品级密钥场景下执行动态注册的逻辑说明：

如果模组上面没有完整的设备信息，即设备未注册未激活，则正常注册，返回成功/失败。
模组上已存在一个设备 A，且是已注册未激活状态，如果用户使用 AT+TCPRDINFOSET 提供的设备信息也是 A，则正常注册，云端会重新分配 PSK 或证书，返回成功/失败。
模组上已存在一个设备 A，且是已注册已激活状态，如果用户使用 AT+TCPRDINFOSET 提供的设备信息也是 A，则会注册失败，AT 命令返回错误，用户需要更换设备信息或在云端将设备重置。
模组已存在一个设备 A 的信息，如果用户使用 AT+TCPRDINFOSET 提供了一个新的设备 B 的信息，则会使用新的设备 B 的信息去注册，注册成功则覆盖原来设备 A 的信息，注册失败则原有的设备 A 信息不变。
正常情况下，设备动态注册仅需执行一次，执行成功后，设备密钥信息已经保存在模组 flash 中，后续上电初始化时可通过命令 AT+TCDEVINFOSET?? 查询是否存在正确的设备信息并正常连接腾讯云 MQTT 服务。

示例¶

AT+TCDEVREG

OK
+TCDEVREG:OK

AT+TCMODULE：模组信息读取 ¶

功能¶

获取模组相关的硬件及软件信息

执行命令¶

命令：

AT+TCMODULE

响应：

Module HW name: 模组硬件信息
Module FW version: 模组固件信息
Module Mac addr: Wi-Fi 模组 mac 地址
Module FW compiled time: 模组固件编译生成时间
Module Flash size: 模组 flash 大小
OK

示例¶

AT+TCMODULE
Module HW name: ESP-WROOM-32D
Module FW version: QCloud_AT_ESP32_v2.0.0
Module Mac addr: 3c:71:bf:33:b0:2e
Module FW compiled time: Jun 17 2020 16:25:27
Module Flash size: 2MB
OK

AT+TCRESTORE：清除模组设备信息 ¶

功能¶

清除模组 flash 上保存的腾讯云设备信息

测试命令¶

命令：

AT+TCRESTORE=?

响应：

OK

执行命令¶

命令：

AT+TCRESTORE

响应：

OK

或

+CME ERROR: <err>

说明：

如果模组已经连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送断开连接命令 (AT+TCMQTTDISCONN) 才能执行该命令。
如果状态允许，则返回 OK，然后清除模组上面存储的腾讯云相关设备及产品信息，以及缓存的 OTA 固件信息，并重启模组。
该命令不会清除模组信息（即通过 AT+TCMODULE 可以读取的信息）以及 ESP 设备的 NVS 数据包括 Wi-Fi 配置，如果需要清除 Wi-Fi 配置信息需要执行 AT+RESTORE。

示例¶

AT+TCRESTORE

OK

TC MQTT 命令 ¶

AT+TCMQTTCONN：配置 MQTT 连接参数 ¶

功能¶

配置 MQTT 连接参数，包括客户端和服务器的心跳间隔、会话控制、并连接腾讯云端服务器

测试命令¶

命令：

AT+TCMQTTCONN=?

响应：

+TCMQTTCONN:<TLSMODE_SELECTED>,<CMDTIMEOUT_VALUE>,<KEEPALIVE>(max 690s),<CLEAN_SESSION>(0/1),<RECONNECT>(0/1)

OK

读取命令¶

命令：

AT+TCMQTTCONN?

响应：

+TCMQTTCONN:<tlsmode>,<cmdtimeout>,<keepalive>,<clean_session>,<reconnect>

OK

说明：

KEEPALIVE 的默认值为 240，CLEAN_SESSION 的默认值为 1

设置命令¶

命令：

AT+TCMQTTCONN=<tlsmode>,<cmdtimeout>,<keepalive>,<clean_session>,<reconnect>

响应：

OK

或

+CME ERR: <err>

参数¶

<tlsmode>：接入方式，必填项，仅支持 <tlsmode> 为 1 的模式
- 0：直连模式
- 1：TLS密钥方式
- 2：TLS证书方式，整型
<cmdtimeout>：命令超时时间，必填项，整型，MQTT 连接、发布、订阅的超时时间，单位毫秒，建议设置为 5000，可以根据网络环境调整该值。范围为 1000 ~ 10000 毫秒
<keepalive>：心跳间隔，必填项，整型，范围 60 ~ 690 秒，默认值为 240
<clean_session>：是否清除会话，必填项，整型
- 0：不清除
- 1：清除（默认）
<reconnect>：MQTT 断连后是否重连，必填项，整型
- 0：不自动重连
- 1：自动重连
该命令前置依赖 AT+TCDEVINFOSET 命令

示例¶

AT+TCMQTTCONN=1,5000,240,1,1

OK
+TCMQTTCONN:OK

AT+TCMQTTDISCONN：断开 MQTT 连接 ¶

功能¶

断开与腾讯云的 MQTT 连接

测试命令¶

命令：

AT+TCMQTTDISCONN=?

响应：

OK

执行命令¶

命令：

AT+TCMQTTDISCONN

响应：

OK

或

+CME ERROR: <err>

说明：

如果模组处于 OTA 状态中，执行该命令会先取消 OTA 后台任务再断开 MQTT 连接
未连接状态下返回 +CME ERROR: <err>

示例¶

AT+TCMQTTDISCONN

OK

AT+TCMQTTPUB：向某个 Topic 发布消息 ¶

功能¶

向某个 Topic 发布消息

测试命令¶

命令：

AT+TCMQTTPUB=?

响应：

+TCMQTTPUB: "TOPIC_NAME(maxlen 128)", "QOS(0/1)","PAYLOAD"

OK

设置命令¶

命令：

AT+TCMQTTPUB=<topic>,<qos>,<message>

响应：

OK

或

+CME ERR: <err>

说明：

如果模组尚未连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送连接命令 (AT+TCMQTTCONN) 才能发布消息。
如果输入合法，首先返回 OK，接下来返回消息发布成功与否。如果是 QoS1 消息，会等到收到 PUBACK 或超时失败再返回。
- +TCMQTTPUB: OK：发布成功
- +TCMQTTPUB: FAIL,<err_code>：发布失败

参数¶

<topic>：发布消息的 Topic name，字符串最大长度 128
<qos>：QoS 值，暂只支持 0 和 1
<message>：发布的消息体的内容

说明¶

注意每条 AT 命令总字符长度不可超过 256 字节，否则会报错，关于消息体内容格式及长度请参考 ESP-AT 命令说明章节。

示例¶

// 消息发布成功
AT+TCMQTTPUB="iot-ee54phlu/device1/get",1,"hello world"

OK
+TCMQTTPUB: OK

AT+TCMQTTPUBL：向某个 Topic 发布长消息 ¶

功能¶

向某 Topic 发布长消息，用于 AT+TCMQTTPUB 消息体长度较大场景

测试命令¶

命令：

AT+TCMQTTPUBL=?

响应：

+TCMQTTPUBL: "TOPIC_NAME(maxlen 128)", "QOS(0/1)","LEN(1-2048)"

OK

设置命令¶

命令：

AT+TCMQTTPUBL=<topic>,<qos>,<msg_length>

响应：

OK
>

或

+CME ERR:<err>

说明：

如果模组尚未连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送连接命令 (AT+TCMQTTCONN) 才能发布消息。
如果模组处于 OTA 下载状态中，由于内存资源限制，不支持该发布消息命令，会返回错误。
如果输入合法，首先返回 OK，接下来返回 >，进入接收消息 payload 状态，读到 <msg_length>长度的数据后，结束接收并返回发送 MQTT 消息结果：
- +TCMQTTPUBL:OK：发布成功
- +TCMQTTPUBL:FAIL,<err_code>：发布失败
进入接收消息 payload 状态后，有 20 秒钟左右的超时时间，如果超时后收到的数据长度小于 <msg_length>，或者收到 +++\r\n，则退出接收消息 payload 状态，返回错误 +CME ERR:<err>，并且不会发送该 MQTT 消息。
消息 payload 不会回显。

参数¶

<topic>：发布消息的 Topic name，最大字符串长度 128
<qos>：QoS 值，暂只支持 0 和 1
<msg_length>：发布的消息体的长度，最大长度 2048。该长度不包括结尾的 /r/n，关于消息体内容格式请参考本文档 ESP-AT 命令说明章节

示例¶

// 消息发布成功
AT+TCMQTTPUBL="iot-ee54phlu/device1/get",1,11
>

Hello,world
OK

+TCMQTTPUBL: OK

AT+TCMQTTPUBRAW：向某个 Topic 发布二进制数据消息 ¶

功能¶

向某 Topic 发布二进制数据消息，可以发布自定义的任意数据而非文本或者 JSON 数据，模组透传不做任何转义处理。

测试命令¶

命令：

AT+TCMQTTPUBRAW=?

响应：

+TCMQTTPUBRAW: "TOPIC_NAME(maxlen128)", "QOS(0/1)","LEN(1-2048)"

OK

设置命令¶

命令：

AT+TCMQTTPUBRAW=<topic>,<qos>,<msg_length>

响应：

OK
>

或

+CME ERR:<err>

说明：

如果模组尚未连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送连接命令 (AT+TCMQTTCONN) 才能发布消息。
如果模组处于 OTA 下载状态中，由于内存资源限制，不支持该发布消息命令，会返回错误。
如果输入合法，首先返回 OK，接下来返回 >，进入接收消息 payload 状态，读到 <msg_length> 长度的数据后，结束接收并返回发送 MQTT 消息结果：
- +TCMQTTPUBRAW:OK：发布成功
- +TCMQTTPUBRAW:FAIL,<err_code>：发布失败
进入接收消息 payload 状态后，有 20 秒钟左右的超时时间，如果超时后收到的数据长度小于 <msg_length>，或者收到 +++\r\n，则退出接收消息 payload 状态，返回错误 +CME ERR:<err>，并且不会发送该 MQTT 消息。
消息 payload 不会回显。

参数¶

<topic>：发布消息的 Topic name，最大字符串长度 128
<qos>：QoS 值，暂只支持 0 和 1
<msg_length>：发布的消息体的长度，最大长度 2048，该长度不包括结尾的 /r/n

示例¶

// 消息发布成功
AT+TCMQTTPUBRAW="$thing/up/raw/iot-ee54phlu/device1",1,10
>

 0x0102030405060708090A
 OK

 +TCMQTTPUBRAW: OK

AT+TCMQTTSUB：订阅 MQTT 某个 Topic ¶

功能¶

订阅 MQTT 某个 Topic，Wi-Fi 模组最多支持订阅 10 个 Topic

测试命令¶

命令：

AT+TCMQTTSUB=?

响应：

+TCMQTTSUB:"TOPIC_NAME(maxlen 128)","QOS(0/1)"

OK

读取命令¶

命令：

AT+TCMQTTSUB?

响应：

OK

或

+TCMQTTSUB: <topic>,<qos>
:
:list of sub topic
+TCMQTTSUB: <topic_n>,<qos>

OK

说明：

如果有已经订阅的消息，返回已订阅的 Topic 列表

设置命令¶

命令：

AT+TCMQTTSUB=<topic>,<qos>

响应：

OK

或

+CME ERROR:<err>

说明：

如果模组尚未连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送连接命令 (AT+TCMQTTCONN) 才能订阅消息。
如果模组处于 OTA 下载状态中，不支持该命令，会返回错误。
如果模组尚未连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送连接命令 (AT+TCMQTTCONN) 才能订阅消息。
如果模组处于 OTA 下载状态中，不支持该命令，会返回错误。
如果输入合法，首先返回 OK，然后返回订阅成功与否，该命令会等到收到 SUBACK 或超时失败再返回。
- +TCMQTTSUB:OK：订阅成功
- +TCMQTTSUB:FAIL,<err_code>：订阅失败

参数¶

<topic>：订阅的 Topic name，最大长度 128
<qos>：QoS 值，暂只支持 0 和 1

示例¶

AT+TCMQTTSUB="iot-ee54phlu/device1/control",0

OK
+TCMQTTSUB: OK

AT+TCMQTTUNSUB：取消已经订阅的 Topic ¶

功能¶

取消已订阅的 Topic

测试命令¶

命令：

AT+TCMQTTUNSUB=?

响应：

+TCMQTTUNSUB: "TOPIC_NAME"

OK

读取命令¶

命令：

AT+TCMQTTUNSUB?

响应：

OK

设置命令¶

命令：

AT+TCMQTTUNSUB=<topic>

响应：

OK

或

+CME ERROR:<err>

说明：

如果模组尚未连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送连接命令 (AT+TCMQTTCONN) 才能订阅消息。
如果模组处于 OTA 下载状态中，不支持该命令，会返回错误。
如果输入合法，首先返回 OK，然后返回取消订阅成功与否：
- +TCMQTTUNSUB:OK：取消订阅成功；
- +TCMQTTUNSUB:FAIL,<err_code>：取消订阅失败。

参数¶

<topic>：取消订阅的 Topic

AT+TCMQTTSTATE：查询 MQTT 连接状态 ¶

功能¶

查询 MQTT 连接状态

测试命令¶

命令：

AT+TCMQTTSTATE=?

响应：

OK

读取命令¶

命令：

AT+TCMQTTSTATE？

响应：

+TCMQTTSTATE: <state>

OK

参数¶

<state>：MQTT 连接状态
- 0：MQTT 已断开
- 1：MQTT 已连接

示例¶

AT+TCMQTTSTATE?

+TCMQTTSTATE: 1
OK

TC OTA 命令 ¶

AT+TCOTASET：OTA 功能使能控制及版本设置 ¶

功能¶

OTA 功能使能控制及版本设置

测试命令¶

命令：

AT+TCOTASET=?

响应：

+TCOTASET: 1(ENABLE)/0(DISABLE),"FW_version"

OK

读取命令¶

命令：

AT+TCOTASET?

响应：

OK
+TCOTASET: <ctlstate>,<fw_ver>

或

+CME ERROR:<err>

设置命令¶

命令：

AT+TCOTASET=<ctlstate>,<fw_ver>

响应：

OK

或

+CME ERROR:<err>

说明：

如果输入合法，模组会先返回 OK，然后订阅 OTA 的 Topic（用户无须手动订阅 Topic) ，启动 OTA 后台任务，并上报本地版本，返回执行结果。如果后台任务已经启动并且不处于下载状态，则执行该命令会再次上报本地固件版本。如果已经在 OTA 下载状态中，执行该命令则会返回错误。
该命令执行成功之后，模组会处于监听升级命令状态，这个时候如果用户通过控制台下发升级固件的命令，模组解析命令成功之后会进入 OTA 下载状态并上报 +TCOTASTATUS:ENTERUPDATE 的 URC 给 MCU。进入 OTA 下载状态之后，会禁用部分 AT 命令，直到固件下载结束。
当固件下载结束，成功会上报 +TCOTASTATUS:UPDATESUCCESS，失败会上报 +TCOTASTATUS:UPDATEFAIL，并退出后台任务。这个时候需要再次执行该命令，才会重新启动后台下载任务。
固件下载支持断点续传，异常失败重新启动后，已下载部分无需重新下载。
通过该命令启动固件升级任务，会支持 MCU 测固件下载以及模组自身的固件升级。对于模组自身的固件升级，在固件下载成功之后会上报 +TCOTASTATUS:UPDATERESET，并在 2 秒后自动重启进入新固件。
- +TCOTASET:OK: OTA 功能设置 OK
- +TCOTASET:FAIL,<err_code>：OTA 功能设置失败

参数¶

<ctlstate>：OTA 使能控制，布尔型，0 关闭，1 使能。enable 上报本地版本并启动后台下载任务；disable 则取消后台下载任务
<fw_ver>：系统当前固件版本信息，字符型，版本格式：V.R.C，譬如 1.0.0. 长度 1 ~ 32 字节

示例¶

AT+TCOTASET=1,"1.0.1"
OK
+TCOTASET:OK

AT+TCFWINFO：读取模组缓存的固件信息 ¶

功能¶

读取模组缓存的固件信息

测试命令¶

命令：

AT+TCFWINFO=?

响应：

+TCFWINFO: "FW_VERSION","FW_SIZE","FW_MD5","FW_MAX_SIZE_OF_MODULE"

OK

说明：

FW_MAX_SIZE_OF_MODULE 是用户待升级的 OTA 固件的最大字节数，模组根据自身资源情况返回，最小必须是 128 KB

读取命令¶

命令：

AT+TCFWINFO?

响应：

OK
+TCFWINFO:<fw_verion>,<fw_size>,<fw_md5>,<module_buffer_size>

或

+CME ERROR:<err>

说明：

每执行一次固件信息读取，已读取的固件数据偏移位置初始化为 0
如果已经在 OTA 下载状态中，则返回错误

示例¶

AT+TCFWINFO？

OK
+TCFWINFO:"2.0.0",516360,"93412d9ab8f3039caed9667a1d151e86"

AT+TCREADFWDATA：读取模组缓存的固件数据 ¶

功能¶

读取模组缓存的固件数据

测试命令¶

命令：

AT+TCREADFWDATA=?

响应：

+TCREADFWDATA: "LEN_FOR_READ"
OK

设置命令¶

命令：

AT+TCREADFWDATA=<len>

响应：

+CME ERROR:<err>

或

+TCREADFWDATA:len,hexdata…

说明：

每读一次，模组实现偏移累加，用户需要根据固件大小判断是否读取完毕。如果 AT 返回成功，但返回的长度小于要读取的长度，则表示固件已经读取到尽头。用户再次读取会返回错误，需要发起 AT+TCFWINFO 命令将偏移量清零，才可以重新开始读取固件。
如果正在 OTA 下载状态中，则返回错误。

参数¶

<len>：读取的固件长度，整型

示例¶

AT+TCREADFWDATA=512
OK
+TCREADFWDATA:512,01020AF5…..

模组配合腾讯云 IoT 平台进行 OTA 功能流程框图 ¶

URC 模组主动上报 MCU 消息 ¶

+TCMQTTRCVPUB（收到订阅的 Topic 时上报的消息）¶

功能¶

收到订阅的 Topic 的消息时上报给 MCU 的信息

消息格式¶

+TCMQTTRCVPUB: <topic>,<message_len>,<message>

参数¶

<topic>：收到消息的 Topic
<message_len>：数值型，收到消息体的长度（不含 ""）
<message>：收到消息体的内容

说明¶

模组不区分下行数据是二进制数据还是字符串数据，所以 message 内容统一加 ""，如果订阅的 Topic 下行的数据是二进制（Topic 下行的数据是字符串还是二进制，开发者自己需要清楚），需要注意去掉首部和尾部的 "。譬如下示例，Topic $thing/down/raw/CTQS08Y5LG/Dev01 下行二进制数据 1234 为 0x1234，两个字节，是非可见字符，串口工具看到是乱码。

示例¶

+TCMQTTRCVPUB:"CTQS08Y5LG/Dev01/get",11,"hello world"

+TCMQTTDISCON（MQTT 断开时上报的信息）¶

功能¶

MQTT 连接与服务器断开时上报的 URC 及断开的错误码

说明¶

Code 错误码详情可以查询服务端相关 err code

示例¶

+TCMQTTDISCON,<err_code>

+TCMQTTRECONNECTING（MQTT 正在重连时上报的信息）¶

功能¶

MQTT 连接与服务器断开并正在进行自动重连时候上报的 URC

示例¶

+TCMQTTRECONNECTING

+TCMQTTRECONNECTED（MQTT 重连成功时上报的信息）¶

功能¶

MQTT 连接与服务器断开后自动重连成功时上报的 URC

示例¶

+TCMQTTRECONNECTED

+TCOTASTATUS（上报 OTA 状态）¶

功能¶

OTA 状态发生变化时上报的 URC

消息格式¶

+TCOTASTATUS: <state>

参数¶

<state>：OTA 状态
- ENTERUPDATE：模组进入 OTA 固件下载状态
- UPDATESUCCESS：固件下载成功（包括固件校验和缓存成功）
- UPDATEFAIL,<err_code>：固件下载失败
- UPDATERESET: 模组自身固件升级成功，在 2 秒后会自动重启

示例¶

+TCOTASTATUS: UPDATESUCCESS

Wi-Fi 配网及 AT 辅助命令 ¶

AT+TCSTARTSMART：以 SmartConfig 方式进行 Wi-Fi 配网及设备绑定 ¶

功能¶

以 SmartConfig 方式进行 Wi-Fi 配网及腾讯云设备绑定，需要与腾讯连连小程序配合完成。目前仅支持乐鑫 ESP-TOUCH 方式。具体配网协议请参考腾讯云物联网开发平台官网文档。

测试命令¶

命令：

AT+TCSTARTSMART=?

响应：

AT+TCSTARTSMART: CMD FOR START SMARTCONFIG
OK

执行命令¶

命令：

AT+TCSTARTSMART

响应：

首先返回

OK

或

+CME ERROR: <err>

然后启动配网及绑定后台任务，并返回

+TCSTARTSMART:OK     // 进入配网状态成功

或

+TCSTARTSMART:FAIL,<err_code>    // 进入配网状态失败

在配网及绑定操作成功之后返回

+TCSTARTSMART:WIFI_CONNECT_SUCCESS

或

+TCSTARTSMART:WIFI_CONNECT_FAILED, <err_code,sub_code>

说明：

如果模组处于 MQTT 已连接状态中，则不支持该设置命令，会返回错误。需要先断开 MQTT 连接。
该命令执行成功后，蓝色 Wi-Fi 指示灯会进入 500 ms 为周期的闪烁状态，这个时候执行腾讯连连小程序上面的添加设备操作并按照指示进行。
如果在 5 分钟内没有执行操作，模组自动退出配网状态，并返回超时错误：+TCSTARTSMART:FAIL,202。

示例¶

AT+TCSTARTSMART

OK
+TCSTARTSMART:WIFI_CONNECT_SUCCESS

AT+TCSTOPSMART：退出 SmartConfig 方式 Wi-Fi 配网状态 ¶

功能¶

退出 SmartConfig 方式配网状态

测试命令¶

命令：

AT+TCSTOPSMART=?

响应：

AT+TCSTOPSMART: CMD TO STOP SMARTCONFIG
OK

执行命令¶

命令：

AT+TCSTOPSMART

响应：

OK

或

+CME ERROR: <err>

说明：

如果模组处于 MQTT 已连接状态中，则不支持该设置命令，会返回错误。需要先断开 MQTT 连接。

示例¶

AT+TCSTOPSMART

OK

AT+TCSAP：以 softAP 方式进行 Wi-Fi 配网及设备绑定 ¶

功能¶

以 softAP 方式进行 Wi-Fi 配网及腾讯云设备绑定，需要与腾讯连连小程序配合完成。具体配网协议请参考腾讯云物联网开发平台官网文档。

测试命令¶

命令：

AT+TCSAP=?

响应：

+TCSAP=<ssid>[,<pwd>,<ch>]

OK

读取命令¶

命令：

AT+TCSAP?

响应：

OK

设置命令¶

命令：

AT+TCSAP=<ssid>[,<pwd>,<ch>]

响应：

首先返回

OK

或

+CME ERROR: <err>

然后启动配网及绑定后台任务，并返回

+TCSAP:OK    // 进入配网状态成功

或

+TCSAP:FAIL<err_code>    // 进入配网状态失败

在配网及绑定操作成功之后返回

+TCSAP:WIFI_CONNECT_SUCCESS

否则返回

+TCSAP:WIFI_CONNECT_FAILED,<err_code,sub_code>

说明：

如果模组处于 MQTT 已连接状态中，则不支持该设置命令，会返回错误。需要先断开 MQTT 连接。
该命令执行成功后，蓝色 Wi-Fi 指示灯会进入 200 ms 为周期的闪烁状态，这个时候执行腾讯连连小程序上面的添加设备操作并按照指示进行。
如果在 5 分钟内没有执行操作，模组自动退出配网状态，并返回超时错误：+TCSAP:FAIL,202。

参数¶

<ssid>：热点 ssid，设备作为 softAP 时 ssid，最大长度 32 字节
<pwd>：热点密码，设备作为 softAP 时 psw，最大长度 32 字节，可选参数
<ch>：热点信道，设备作为 softAP 时的信道，可选参数

说明¶

下发此命令后，可以搜索到所配置的 ssid 的热点，手机可以按配置的密码选择连接此热点，模组同时会起一个 UDP server，serverip:192.168.4.1。
APP 和模组的配网可进行交互数据流。
如果只提供 ssid，则会启动无加密的 Wi-Fi 热点。

示例¶

AT+TCSAP="Test-SoftAP","12345678"

OK
+TCSAP:WIFI_CONNECT_SUCCESS

AT+TCSTOPSAP：退出 softAP 方式 Wi-Fi 配网状态 ¶

功能¶

退出 softAP 方式配网状态

测试命令¶

命令：

AT+TCSTOPSAP=?

响应：

AT+TCSTOPSAP: CMD TO STOP SOFTAP
OK

执行命令¶

命令：

AT+TCSTOPSAP

响应：

OK

或

+CME ERROR: <err>

说明：

如果模组处于 MQTT 已连接状态中，则不支持该设置命令，会返回错误。需要先断开 MQTT 连接。

示例¶

AT+TCSTOPSAP

OK

AT+TCMODINFOSET：ESP 模组信息设置 ¶

功能¶

设置 ESP 模组相关的信息，如模组名称，flash 大小等

测试命令¶

命令：

AT+TCMODINFOSET?

响应：

+TCMODINFOSET:"MODULE NAME","FLASH_SIZE (2/4)","WIFI LED GPIO","FW BASE ADDR","FW MAX SIZE","FIXED CONNID"

OK

读取命令¶

命令：

AT+TCMODINFOSET?

响应：

+TCMODINFOSET:<module_name>,<flash_size>,<WiFi_LED_GPIO>,<fw_base_addr>,<fw_max_size>,<fixed_conn_id>

OK

设置命令¶

命令：

AT+TCMODINFOSET=<module_name>,<flash_size>,<WiFi_LED_GPIO>,<fw_base_addr>,<fw_max_size>,<fixed_conn_id>

响应：

OK

或

+CME ERROR: <err>

说明：

如果模组已经连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送断开连接命令 (AT+TCMQTTDISCONN) 才能执行该命令。
如果输入合法，首先返回 OK，接下来返回设备信息设置成功与否
- +TCMODINFOSET:OK：设置成功，模组数据会保存到 flash，掉电不丢失
- +TCMODINFOSET:FAIL,<err_code>：设置失败

参数¶

<module_name>：模组名称，字符串类型，最大长度 30
<flash_size>：模组 flash 大小（单位 MB），2 或者 4，数值类型
<WiFi_LED_GPIO>：模组使用哪个 GPIO 口来控制 Wi-Fi 状态灯，数值类型
<fw_base_addr>：模组提供给上位机 OTA 升级的固件数据保存地址，数值类型，该值需为 0x1000 的整数倍并且不小于 0x111000
<fw_max_size>：模组提供给上位机 OTA 升级的固件最大空间，数值类型，该值不大于 716800 (700 KB)
<fixed_conn_id>：保留选项，默认为 1

说明¶

ESP Wi-Fi 模组固件和模组信息存储于不同 flash 分区，模组固件在启动时候会读取模组信息并做相应配置，这样可以使得同一版本模组固件可以适配不同的模组硬件

示例¶

// 设置成功
AT+TCMODINFOSET="ESP-WROOM-02D",2,0,1118208,716800,1

OK
+TCMODINFOSET:OK

AT+TCMQTTSRV：设置腾讯云 MQTT 服务器地址 ¶

功能¶

设置腾讯云 MQTT 服务器 host 地址，适用于私有化部署或者边缘计算场景

测试命令¶

命令：

AT+TCMQTTSRV=?

响应：

+TCMQTTSRV: "MQTT SERVER IP"

OK

读取命令¶

命令：

AT+TCMQTTSRV?

响应：

+TCMQTTSRV:192.168.10.118
OK

设置命令¶

命令：

AT+TCMQTTSRV=<Host addr>

响应：

OK

或

+CME ERROR:<err>

说明：

如果输入合法，首先返回 OK，然后返回设置成功与否
- +TCMQTTSRV:OK：设置 IP 成功
- +TCMQTTSRV:FAIL：设置 IP 失败
如果模组处于 MQTT 已连接状态中，则不支持该设置命令，会返回错误。需要先断开 MQTT 连接。

参数¶

<Host addr>：腾讯云 MQTT 服务器 IP 或域名地址

AT+TCVER：读取模组固件 IoT SDK 版本信息 ¶

功能¶

读取模组固件 IoT SDK 版本信息

执行命令¶

命令：

AT+TCVER

示例¶

AT+TCVER
Tencent Cloud IoT AT  version: QCloud_AT_ESP32_v2.0.0
Tencent Cloud IoT SDK version: 3.2.0
Firmware compile time: Jun 17 2020 16:25:27
Tencent Technology Co. Ltd.

OK

TC 网关子设备命令 ¶

AT+TCGWBIND：网关绑定子设备命令 ¶

功能¶

当 AT 模组用于网关设备上时，可以通过该命令对其下的子设备进行绑定与解绑操作。仅支持密钥方式的子设备。

测试命令¶

命令：

AT+TCGWBIND=?

响应：

+TCGWBIND:"MODE","PRODUCT_ID","DEVICE_NAME","DEVICE_SECRET"

OK

读取命令¶

命令：

AT+TCGWBIND?

响应：

OK

或

+TCGWBIND: <product_id>,<device_name>
:
:list of all bind sub-devices
+TCGWBIND: <product_id>,<device_name>

OK

说明：

读取命令会通过 MQTT 消息去物联网后台查询已经绑定在当前网关的所有子设备信息，并返回子设备列表。

设置命令¶

命令：

AT+TCGWBIND=<mode>,<productId>,<deviceName>[,<deviceSecret>]

响应：

OK

或

+CME ERROR: <err>

说明：

如果模组尚未连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送连接命令 (AT+TCMQTTCONN) 才能发布消息。
该命令为基于 MQTT 消息的同步操作，会阻塞直至绑定或解绑操作完成或超时退出。
如果输入合法，首先返回 OK，接下来返回绑定或解绑子设备操作成功与否
- +TCGWBIND:OK：操作成功。对于绑定操作，重复绑定也返回成功。对于解绑操作，解绑未绑定的设备也返回成功。
- + TCGWBIND:FAIL,<err_code>：操作失败

参数¶

<mode>：模式参数，必填项
- 0：绑定操作
- 1：解绑操作
<productId>：子设备产品 id，必填项，字符串类型，最大长度 10 字节。
<deviceName>：子设备名称，必填项，字符串类型，最大长度 48 字节。
<deviceSecret>：子设备密钥，可选项，字符串类型，最大长度 44 字节。在解绑操作时候，不需要提供子设备密钥。在绑定操作时候，如果不提供子设备密钥，则网关模组从已经存储的子设备三元组中读取密钥信息（该信息由子设备信息设置命令提供或者子设备动态注册命令获取）。

示例¶

// 绑定子设备成功
AT+TCGWBIND=0,"CTQS08Y5LG","Dev01","ZHNkIGRzZCA="

OK
+TCGWBIND:OK

AT+TCGWONLINE：网关代理子设备上下线命令 ¶

功能¶

当 AT 模组用于网关设备上时，可以通过该命令代理其下的子设备上线和下线操作，仅支持密钥方式的子设备

测试命令¶

命令：

AT+TCGWONLINE=?

响应：

+TCGWONLINE:"MODE","PRODUCT_ID","DEVICE_NAME"

OK

读取命令¶

命令：

AT+TCGWONLINE?

响应：

OK

或

+TCGWONLINE: <product_id>,<device_name>
:
:list of online sub-device
+TCGWONLINE: <product_id>,<device_name>

OK

说明：

如果有已经在线的子设备，返回已在线的子设备信息列表

设置命令¶

命令：

AT+TCGWONLINE=<mode>,<productId>,<deviceName>

响应：

OK

或

+CME ERROR: <err>

说明：

如果模组尚未连接腾讯云 MQTT 服务器，则返回错误，用户需要先发送连接命令 (AT+TCMQTTCONN) 才能发布消息。
该命令为基于 MQTT 消息的同步操作，会阻塞直至上下线操作完成或超时退出。
如果输入合法，首先返回 OK，接下来返回绑定或解绑子设备操作成功与否
- +TCGWONLINE:OK：操作成功
- + TCGWONLINE:FAIL,<err_code>：操作失败

参数¶

<mode>：模式参数，必填项
- 0：上线操作
- 1：下线操作
<productId>：子设备产品 id，必填项，字符串类型，最大长度 10 字节
<deviceName>：子设备名称，必填项，字符串类型，最大长度 48 字节

示例¶

// 子设备上线成功
AT+TCGWONLINE=0,"CTQS08Y5LG","Dev01"

OK
+TCGWONLINE:OK

// 子设备上线成功后，网关可以代理子设备上线
AT+TCMQTTPUB="CTQS08Y5LG/Dev01/data",0,"hello world"

OK
+TCMQTTPUB: OK

AT+TCSUBDEVINFOSET：子设备信息设置 ¶

功能¶

设置腾讯云物联网平台创建的子设备信息，用于网关代理子设备通讯场景

测试命令¶

命令：

AT+TCSUBDEVINFOSET=?

响应：

+TCSUBDEVINFOSET:"MODE","PRODUCT_ID","DEVICE_NAME","DEVICE_SECRET_BCC","PRODUCT_REGION"

OK

读取命令¶

命令：

AT+TCSUBDEVINFOSET?

响应：

+TCSUBDEVINFOSET: <product_id>,<device_name>,<devicesecret_checksum>,<product_region>

OK

或

+CME ERROR: <err>

说明：

不返回 devicesecret 的字符串内容，只返回 devicesecret 字符串的校验和 (BCC)

设置命令¶

命令：

AT+TCSUBDEVINFOSET=<mode>,<product_id>,<device_name>,<device_secret>[,<product_region>]

响应：

OK

或

+CME ERROR: <err>

说明：

该命令不会影响当前网关的 MQTT 连接
如果输入合法，首先返回 OK，接下来返回设备信息设置成功与否
- +TCSUBDEVINFOSET:OK：设置成功
- + TCSUBDEVINFOSET:FAIL<err_code>：设置失败

参数¶

<mode>：模式参数，必填项
- 0：设置操作
- 1：删除操作
<product_id>：产品 id，必填项，字符串类型，最大长度 10 字节
<device_name>：设备名称，必填项，字符串类型，最大长度 48 字节
<device_secret>：设备密钥，必填项，字符串类型，最大长度 44 字节
<product_region>：产品区域，选填项，字符串类型，最大长度 24 字节，如果不提供，默认为中国大陆公有云 “ap-guangzhou”

示例¶

// 设置成功
AT+TCSUBDEVINFOSET=0,"CTQS08Y5LG","Dev01","ZHNkIGRzZCA="

OK
+TCSUBDEVINFOSET:OK

AT+TCSUBDEVPRDSET：子设备产品信息设置 ¶

功能¶

设置腾讯云物联网平台创建的子设备产品信息，适用于网关代理子设备进行动态注册场景

测试命令¶

命令：

AT+TCSUBDEVPRDSET=?

响应：

+TCSUBDEVPRDSET:"MODE","PRODUCT_ID","PRODUCT_SECRET_BCC","DEVICE_NAME","PRODUCT_REGION"

OK

读取命令¶

命令：

AT+TCSUBDEVPRDSET?

响应：

OK

或

+TCSUBDEVPRDSET:<product_ID>,<product_secret_checksum>,<device_name>,<product_region>
:
:list of all sub-device
+TCSUBDEVPRDSET:<product_ID>,<product_secret_checksum>,<device_name>,<product_region>

OK

说明：

如果有已经设置的子设备，返回已设置的子设备信息列表

设置命令¶

命令：

AT+TCSUBDEVPRDSET=<mode>,<product_ID>,<product_secret>,<device_name>[,<product_region>]

响应：

OK

或

+CME ERROR: <err>

说明：

该命令不会影响当前网关的 MQTT 连接
如果输入合法，首先返回 OK，接下来返回子设备信息设置成功与否
- +TCSUBDEVPRDSET:OK：设置成功，产品数据会保存到 flash，掉电不丢失
- +TCSUBDEVPRDSET:FAIL,<err_code>：设置失败

参数¶

<mode>：模式参数，必填项
- 0：设置操作
- 1：删除操作
<product_ID>：产品 ID，必填项，字符串类型，最大长度 10。
<product_secret>：产品密钥，必填项，字符串类型，最大长度 32。
<device_name>：设备名称，必填项，字符串类型，最大长度 48。
<product_region>：产品区域，选填项，字符串类型，最大长度 24 字节，如果不提供，默认为中国大陆公有云 “ap-guangzhou”。

示例¶

// 设置成功
AT+TCSUBDEVPRDSET=0,"CTQS08Y5LG","ZHNkIGRzZCA=","Dev01"

OK
+TCSUBDEVPRDSET:OK

AT+TCSUBDEVREG：执行子设备动态注册 ¶

功能¶

设置了子设备产品级密钥场景下，网关代理子设备进行动态注册并存储设备信息

测试命令¶

命令：

AT+TCSUBDEVREG=?

响应：

+TCSUBDEVREG:"PRODUCT_ID","DEVICE_NAME"

OK

读取命令¶

命令：

AT+TCSUBDEVREG?

响应：

OK

或

+TCSUBDEVREG: <product_id>,<device_name>
:
:list of registered sub-device
+TCSUBDEVREG: <product_id>,<device_name>

OK

说明：

如果有已经注册成功的子设备，返回已注册的子设备信息列表

执行命令¶

命令：

AT+TCSUBDEVREG=<productId>,<deviceName>

响应：

OK

或

+CME ERROR: <err>

说明：

如果执行状态合法，首先返回 OK，接下来返回子设备注册成功与否

+TCSUBDEVREG:OK：动态注册成功，子设备密钥信息会保存到 flash

+TCSUBDEVREG:FAIL,<err_code>：动态注册失败，返回错误码，具体参见本文档错误码章节

参数¶

<productId>：子设备产品 id，必填项，字符串类型，最大长度 10 字节
<deviceName>：子设备名称，必填项，字符串类型，最大长度 48 字节

说明¶

使用子设备动态注册的逻辑说明：

如果模组上面没有完整的子设备信息，即子设备未注册未激活，则正常注册，返回成功/失败。
模组上已存在一个子设备 A，且是已注册未激活状态，如果用户使用 AT+TCSUBDEVPRDSET 提供的子设备信息也是 A，则正常注册，云端会重新分配 PSK，返回成功/失败。
模组上已存在一个子设备 A，且是已注册已激活状态，如果用户使用 AT+TCSUBDEVPRDSET 提供的子设备信息也是 A，则会注册失败，AT 命令返回错误，用户需要更换子设备信息或在云端将子设备重置。
模组已存在子设备 A 的信息，如果用户使用 AT+TCSUBDEVPRDSET 提供了一个新的设备 B 的信息，则会使用新的设备 B 的信息去注册，注册成功则会增加设备 B 的信息，即模组存在 A 和 B 的设备信息。
正常情况下，设备动态注册仅需执行一次，执行成功后，设备密钥信息已经保存在模组 flash 中，后续上电初始化时可通过命令 AT+TCSUBDEVINFOSET? 查询是否存在正确的子设备信息。
子设备动态注册成功后必须先通过网关绑定命令 AT+TCGWBIND 进行绑定，再通过 AT+TCGWONLINE 上线后，才能进行 MQTT 通讯。

示例¶

AT+TCSUBDEVREG="CTQS08Y5LG","Dev01"

OK
+TCSUBDEVREG:OK

错误码 ¶

服务端相关 err code ¶

<err> 代码¶
<err> 代码	中文含义	内部字段
101	设备连接失败	device connect fail
110	设备订阅失败：无 Topic 权限	device subscribe fail: unauthorized operation
111	设备订阅失败：系统错误	device subscribe fail: system error
120	设备退订失败：系统错误	device unsubscribe fail: system error
130	设备发布消息失败：无 Topic 发布权限	device publish message to topic fail：unauthorized operation
131	设备发布消息失败：publish 超过频率限制	device publish message to topic fail：reach max limit
132	设备发布消息失败：payload 超过长度限制	device publish message to topic fail：payload too long

执行错误码¶
执行错误码	中文含义	内部字段
-1001	表示失败返回	QCLOUD_ERR_FAILURE
-1002	表示参数无效错误，比如空指针	QCLOUD_ERR_INVAL

-3,	远程主机关闭连接	QCLOUD_ERR_HTTP_CLOSED
-4,	HTTP 未知错误	QCLOUD_ERR_HTTP
-5,	协议错误	QCLOUD_ERR_HTTP_PRTCL
-6,	域名解析失败	QCLOUD_ERR_HTTP_UNRESOLVED_DNS
-7,	URL 解析失败	QCLOUD_ERR_HTTP_PARSE
-8,	HTTP 连接失败	QCLOUD_ERR_HTTP_CONN
-9,	HTTP 鉴权问题	QCLOUD_ERR_HTTP_AUTH
-10,	HTTP 404	QCLOUD_ERR_HTTP_NOT_FOUND
-11,	HTTP 超时	QCLOUD_ERR_HTTP_TIMEOUT

-102	表示往等待 ACK 列表中添加元素失败	QCLOUD_ERR_MQTT_PUSH_TO_LIST_FAILED
-103	表示未与 MQTT 服务器建立连接或已经断开连接	QCLOUD_ERR_MQTT_NO_CONN
-104	表示 MQTT 相关的未知错误	QCLOUD_ERR_MQTT_UNKNOWN
-105	表示正在与 MQTT 服务重新建立连接	QCLOUD_ERR_MQTT_ATTEMPTING_RECONNECT
-106	表示重连已经超时	QCLOUD_ERR_MQTT_RECONNECT_TIMEOUT
-107	表示超过可订阅的主题数	QCLOUD_ERR_MQTT_MAX_SUBSCRIPTIONS
-108	表示订阅主题失败, 即服务器拒绝	QCLOUD_ERR_MQTT_SUB
-109	表示无 MQTT 相关报文可以读取	QCLOUD_ERR_MQTT_NOTHING_TO_READ
-110	表示读取的 MQTT 报文有问题	QCLOUD_ERR_MQTT_PACKET_READ
-111	表示 MQTT 相关操作请求超时	QCLOUD_ERR_MQTT_REQUEST_TIMEOUT
-112	表示客户端 MQTT 连接未知错误	QCLOUD_ERR_MQTT_CONNACK_UNKNOWN
-113	表示客户端 MQTT 版本错误	QCLOUD_ERR_MQTT_CONANCK_UNACCEPTABLE_PROTOCOL_VERSION
-114	表示客户端标识符错误	QCLOUD_ERR_MQTT_CONNACK_IDENTIFIER_REJECTED
-115	表示服务器不可用	QCLOUD_ERR_MQTT_CONNACK_SERVER_UNAVAILABLE
-116	表示客户端连接参数中的 username 或 password 错误	QCLOUD_ERR_MQTT_CONNACK_BAD_USERDATA
-117	表示客户端连接认证失败	QCLOUD_ERR_MQTT_CONNACK_NOT_AUTHORIZED
-118	表示收到的消息无效	QCLOUD_ERR_RX_MESSAGE_INVAL
-119	表示消息接收缓冲区的长度小于消息的长度	QCLOUD_ERR_BUF_TOO_SHORT
-120	表示该 QoS 级别不支持	QCLOUD_ERR_MQTT_QOS_NOT_SUPPORT
-121	表示取消订阅主题失败,比如该主题不存在	QCLOUD_ERR_MQTT_UNSUB_FAIL

-132	表示 JSON 解析错误	QCLOUD_ERR_JSON_PARSE
-133	表示 JSON 文档会被截断	QCLOUD_ERR_JSON_BUFFER_TRUNCATED
-134	表示存储 JSON 文档的缓冲区太小	QCLOUD_ERR_JSON_BUFFER_TOO_SMALL
-135	表示 JSON 文档生成错误	QCLOUD_ERR_JSON
-136	表示超过 JSON 文档中的最大 Token 数	QCLOUD_ERR_MAX_JSON_TOKEN
-137	表示超过同时最大的文档请求	QCLOUD_ERR_MAX_APPENDING_REQUEST
-138	表示超过规定最大的 Topic 长度	QCLOUD_ERR_MAX_TOPIC_LENGTH

-601	表示 TCP 连接建立套接字失败	QCLOUD_ERR_TCP_SOCKET_FAILED
-602	表示无法通过主机名获取 IP 地址	QCLOUD_ERR_TCP_UNKNOWN_HOST
-603	表示建立 TCP 连接失败	QCLOUD_ERR_TCP_CONNECT
-604	表示 TCP 读超时	QCLOUD_ERR_TCP_READ_TIMEOUT
-605	表示 TCP 写超时	QCLOUD_ERR_TCP_WRITE_TIMEOUT
-606	表示 TCP 读错误	QCLOUD_ERR_TCP_READ_FAIL
-607	表示 TCP 写错误	QCLOUD_ERR_TCP_WRITE_FAIL
-608	表示 TCP 对端关闭了连接	QCLOUD_ERR_TCP_PEER_SHUTDOWN
-609	表示底层没有数据可以读取	QCLOUD_ERR_TCP_NOTHING_TO_READ

-701	表示 SSL 初始化失败	QCLOUD_ERR_SSL_INIT
-702	表示 SSL 证书相关问题	QCLOUD_ERR_SSL_CERT
-703	表示 SSL 连接失败	QCLOUD_ERR_SSL_CONNECT
-704	表示 SSL 连接超时	QCLOUD_ERR_SSL_CONNECT_TIMEOUT
-705	表示 SSL 写超时	QCLOUD_ERR_SSL_WRITE_TIMEOUT
-706	表示 SSL 写错误	QCLOUD_ERR_SSL_WRITE
-707	表示 SSL 读超时	QCLOUD_ERR_SSL_READ_TIMEOUT
-708	表示 SSL 读错误	QCLOUD_ERR_SSL_READ
-709	表示底层没有数据可以读取	QCLOUD_ERR_SSL_NOTHING_TO_READ

CME ERROR 列表扩展 ¶

<err> 代码	含义
200	Previous command is not complete
201	msg packet over size
202	command timeout
203	check failed
204	Parameter invalid
205	No valid firmware
206	Memory allocation error
207	Flash access error
208	State error or not ready. eg: pub msg when MQTT not connected
209	Command execution error
210	Unknown error
211	Module self-OTA error
212	FLASH ERASE is going on
213	HTTP error

设备动态注册错误码 ¶

错误码	内部字段	说明
1000	ErrorCode_SDK_InternalError	内部错误
1004	ErrorCode_SDK_ProductNotExists	产品不存在
1006	ErrorCode_SDK_InvalidParam	参数错误
1010	ErrorCode_SDK_CheckSecretError	验签失败
1011	ErrorCode_SDK_NotSupportRegister	产品不支持动态注册
1012	ErrorCode_SDK_ExceedRegisterTimes	超过设备最大注册次数
1020	ErrorCode_SDK_NoSuchDevice	预创建注册模式未定义设备
1021	ErrorCode_SDK_DeviceHasRegisted	设备已注册
1031	ErrorCode_SDK_ExceedRegisterLimits	设备超过设定最大自动创建注册数量

模组配网及设备绑定错误类型 ¶

<err>代码	含义
1	MQTT connect error
2	APP command error
3	WIFI boarding stop
4	RTOS task error
5	RTOS queue error
6	WIFI STA init error
7	WIFI AP init error
8	WIFI start error
9	WIFI config error
10	WIFI connect error
11	WIFI disconnect error
12	WIFI AP STA error
13	Smartconfig start error
14	Smartconfig data error
15-22	TCP/UDP socket error

网关子设备命令相关错误类型 ¶

错误码	描述
0	成功
-1	网关设备未绑定该子设备
-2	系统错误，子设备上线或者下线失败
801	请求参数错误
802	设备名非法，或者设备不存在
803	签名校验失败
804	签名方法不支持
805	签名请求已过期
806	该设备已被绑定
807	非普通设备不能被绑定
808	不允许的操作
809	重复绑定
810	不支持的子设备

应用说明 ¶

密钥认证方式连接腾讯云 MQTT 服务器 ¶

设置设备信息

命令

AT+TCDEVINFOSET="1","CTQS08Y5LG","device1","ZHNkIGRzZCA="

响应
```
OK
+TCDEVINFOSET: OK
```

TLS 密钥方式，超时时间设置为 5000 ms，心跳间隔为 240 s，clean session 为 1，使能自动重连，并连接 MQTT 服务器
- 命令
```
AT+TCMQTTCONN=1,5000,240,1,1
```
- 响应
```
OK
+TCMQTTCONN:OK
```

订阅消息 ¶

命令

AT+TCMQTTSUB="CTQS08Y5LG/device1/control"

响应

OK
+TCMQTTSUB: OK

发布消息 ¶

发布消息，如果已经成功订阅过该主题并在云端配置了消息转发引擎，则设备会收到自己发布的消息，并通过 URC 自动上报

命令

AT+TCMQTTPUB="CTQS08Y5LG/device1/data",0," {\"action\":\"test\"\,\"time\":1565075992}"

响应

OK
+TCMQTTPUB: OK

+TCMQTTRCVPUB:"CTQS08Y5LG/device1/data",35,"{"action":"test","time":1565075992}"

数据通讯应用协议 ¶

设备通过 MQTT 协议与腾讯云物联网进行数据交互时，可使用下面几种应用协议：

物联网开发平台 – 数据模板协议

平台基于物模型和数据模板协议，可实现高效的物联网应用开发，并可让设备与腾讯连连小程序交互，具体请参考文档数据模板协议。
物联网通信 – 设备影子协议

设备影子文档是服务器端为设备缓存的一份状态和配置数据，设备可通过影子数据流进行状态同步，具体请参考文档设备影子详情。
自定义

用户可使用自定义的 MQTT 主题和应用协议。

使用建议 ¶

上位机或 MCU 使用 ESP 设备定制 AT 固件与腾讯云交互，可按下面不同阶段的使用建议进行相关命令的操作。

检查及配置腾讯云物联网设备信息

上电之后，MCU 应先检查模组是否配置了物联网设备信息，如果不存在或者设备信息有误，应通过命令配置设备三元组信息。如果使用动态注册，则应查询并设置产品级信息。

相关命令
- AT+TCDEVINFOSET
- AT+TCPRDINFOSET
查询 Wi-Fi 连接状态及配网操作

在配置设备信息之后，MCU 可先查询 Wi-Fi 模组是否已经成功连接 Wi-Fi，如果没有联网，则可以通过配网命令使模组进入配网状态并可通过腾讯连连小程序进行配网及设备绑定操作。

注意如果模组没有设备密钥，并已经配置好产品级密钥及设备名，则在配网成功之后会自动进行动态注册。

相关命令
MQTT 连接及订阅

在设备信息正确配置及 Wi-Fi 连接成功之后，MCU 可通过 MQTT 连接物联网服务，根据自身应用情况配置连接参数（超时时间/心跳间隔等）以及订阅相应的消息 Topic，并在 MCU 配置相关 MQTT 消息上报及连接状态 URC 的回调处理机制。

相关命令
MQTT收发消息

MCU 在发送消息时，根据消息长度选择使用 PUB 或者 PUBL 命令。注意如果是 JSON 数据需要进行转义处理再发送给模组。

相关命令
- AT+TCMQTTPUB
- AT+TCMQTTPUBL
OTA 使能及监听

建议在 MQTT 连接成功之后，使能 OTA 功能，模组会启动后台 OTA 任务监听云端的升级命令，接收到升级命令后会自动下载固件到模组 flash，并通过 URC 通知 MCU，MCU 需要处理 OTA 相关 URC 消息，在下载成功之后可以通过相关命令读取 MCU 的新版本固件。

相关命令
断开 MQTT

设备主动断开 MQTT 需要执行断开命令，否则云端不会马上感知到设备离线，需要等待心跳超时。

执行断开命令会取消所有订阅的 Topic，如重新上线需要再次订阅

相关命令
- AT+TCMQTTDISCONN

Tencent Cloud IoT AT Firmware¶

ESP32¶

待添加

ESP32-C3¶

待添加

AT FAQ¶

[English]

AT 固件
AT 命令与响应
硬件
性能
其他

AT 固件 ¶

我的模组没有官方发布的固件，如何获取适用的固件？¶

如果 AT 固件章节中没有发布相关固件，您可考虑以下选择：

使用相同硬件配置的模组的固件（点击 ESP-AT 固件差异。
为你的模组创建出厂参数二进制文件并自行编译固件。

如何获取 AT 固件源码？¶

ESP-AT 固件部分开源，开源仓库参考 esp-at。

官网上放置的 AT 固件如何下载？¶

烧录工具请下载 Flash 下载工具。

烧录地址请参考 AT 下载指南。

如何整合 ESP-AT 编译出来的所有 bin 文件？¶

可以使用 Flash 下载工具的 combine 按钮进行整合。

新购买的 ESP32-WROVE-E 模组上电后，串口打印错误 “flash read err,1000” 是什么原因？该模组如何使用 AT 命令？¶

ESP32-WROVER-E 的模组出厂没有烧录 ESP-AT 固件，因此出现 “flash read err” 的错误。

如果想要使用 ESP32-WROVER-E 模组的 AT 命令功能，请参考如下链接获取固件和烧录固件。

下载固件;

连接硬件;

烧录固件.

模组出厂 AT 固件是否支持流控？¶

该模组支持硬件流控，但是不支持软件流控。

对于是否开启硬件流控，您可以通过串口命令 AT+UART_CUR 或者 AT+UART_DEF 进行修改。

硬件接线参考。

新客户使用 ESP8266 NONOS AT 固件，如何建议客户切换到 ESP8266 RTOS AT 固件？¶

NONOS 版本 AT 固件属于老版本的固件，我们推荐使用 RTOS 版本 AT 版本，目前这个是我们主推的版本。

RTOS 和 NONOS 逻辑有很大的差异，并且 RTOS 上支持了更多的功能，fix 掉了更多的问题，这些问题有可能在 NONOS 版本 AT 上出现，以后 RTOS AT 也是我们重点维护的版本，会更加及时的修复问题和不断的添加新的功能。

请下载 RTOS 版本的 AT 固件。

AT 命令与响应 ¶

AT 提示 busy 是什么原因？¶

提示 “busy” 表示正在处理前⼀条命令，⽆法响应当前输⼊。因为 AT 命令的处理是线性的，只有处理完前⼀条命令后，才能接收下⼀条命令。

当有多余的不可⻅字符输⼊时，系统也会提示 “busy” 或 “ERROR”，因为任何串⼝的输⼊，均被认为是命令输⼊。

串⼝输⼊ AT+GMR (换⾏符 CR LF) (空格符)，由于 AT+GMR (换⾏符 CR LF) 已经是⼀条完整的 AT 命令了，系统会执⾏该命令。此时如果系统尚未完成 AT+GMR 操作，就收到了后⾯的空格符，将被认为是新的命令输⼊，系统提示 “busy”。但如果是系统已经完成了 AT+GMR 操作，再收到后⾯的空格符，空格符将被认为是⼀条错误的命令，系统提示 “ERROR”。

MCU 发送 AT+CIPSEND 后，收到 busy p.. 响应，MCU 需要重新发送数据。因为 busy p.. 代表上一条命令正在执行，当前输入无效。建议等 AT 上一条命令响应后，MCU 再重新发送新命令。

AT 固件，上电后发送第一个命令总是会返回下面的信息，为什么？¶

ERR CODE:0x010b0000
busy p...
此信息代表的是”正在处理上一条命令”。

一般情况下只会显示”busy p…”，显示 ERR CODE 是因为打开了错误代码提示。

如果是上电的第一条命令就返回了这个错误码信息，可能的原因是：这条命令后面多跟了换行符/空格/其他符号，或者连续发送了两个或多个 AT 命令。

在不同模组上的默认 AT 固件支持哪些命令，以及哪些命令从哪个版本开始支持？¶

如果您想了解 ESP-AT 在不同模组上默认固件都支持哪些命令，您可以参考 ESP-AT 固件差异以及 ESP-AT 固件差异。

如果您想查找某个命令从哪个版本开始支持，以及各个版本上修复了哪些问题，您可以参考 release notes。

主 MCU 给 ESP32 设备（下载的是 AT V2.1.0.0 版本的固件）发 AT 命令无返回，是什么原因？¶

当主 MCU 给 ESP32 设备发送 AT 命令后需要添加结束符号，在程序中的写法为：”ATrn”。可参见检查 AT 固件是否烧录成功。

ESP-AT 命令是否支持 ESP-WIFI-MESH？¶

ESP-AT 当前不支持 ESP-WIFI-MESH。

AT 是否支持 websocket 命令？¶

默认命令不支持 websocket 命令。

可通过自定义命令实现，代码参考 websocket，以及添加自定义 AT 命令。

是否有 AT 命令连接阿里云以及腾讯云示例？¶

若使用通用 AT 固件，可参考以下示例：

阿里云应用参考：AT+MQTT aliyun。

腾讯云应用参考：AT+MQTT QCloud。

若使用 QCloud AT 固件，请采用腾讯云 AT 命令连接至腾讯云。

AT 命令是否可以设置低功耗蓝牙发射功率？¶

可以。ESP32 和 ESP32-C3 的 Wi-Fi 和 Bluetooth LE 共用一根天线，可使用 AT+RFPOWER 命令设置。

可以通过 AT 命令将 ESP32-WROOM-32 模块设置为 HID 键盘模式吗？¶

可以的，请参考 Bluetooth LE AT 命令集。下面这个链接是简单的演示链接：https://pan.baidu.com/s/1TgNE2DpJtVARGqB-jb8UIQ 提取码：f6hu。

如何支持那些默认固件不支持但可以在配置和编译 ESP-AT 工程后支持的命令？¶

例如在 ESP32-WROOM 系列支持蓝牙功能，需编译时在 menuconfig 中开启蓝牙功能 ./build.py menuconfig > Component config > AT > [*]AT bt command support。

AT 命令中特殊字符如何处理？¶

可以参考 AT 命令分类章节中的转义字符语法。

AT 命令中串口波特率是否可以修改？（默认：115200）¶

AT 命令串口的波特率是可以修改的。

第一种方法，您可以通过串口命令 AT+UART_CUR 或 AT+UART_DEF。

第二种方法，您可以重新编译 AT 固件，编译介绍：如何编译 AT 工程与修改 UART 波特率配置。

ESP32 使用 AT 指令进入透传模式，如果连接的热点断开，ESP32 能否给出相应的提示信息？¶

可以通过命令 AT+SYSMSG 进行配置，可设置 AT+SYSMSG=4，如果连接的热点断开，串口会上报 “WIFI DISCONNECTrn”。

需要注意的是，该命令在 AT v2.1.0 之后添加，v2.1.0 及之前的版本无法使用该命令。

ADV 广播参数超过 32 字节之后应该如何设置？¶

AT+BLEADVDATA 命令支持 adv 广播参数最大为 32 字节，如果需要设置更长的广播参数，请调用 AT+BLESCANRSPDATA 命令来设置。

ESP8266 从 NONOS AT 切换到 RTOS AT (v2.0.0.0 以及以上版本)，烧录成功后，AT 固件启动没有收到 ready 字样？¶

ESP8266 RTOS 版本 AT 通信管脚做了修改，更换为 GPIO13 和 GPIO15 管脚了。

硬件连接参考。

硬件 ¶

在不同模组上的 AT 固件要求芯片 flash 多大？¶

对于 ESP32 以及 ESP32-C3 系列模组，您可以参考 ESP-AT 固件差异。

对于 ESP8266 系列模组，您可以参考 How to understand the differences of each type of module。

ESP32 AT 如何从 UART0 口通信？¶

默认 AT 固件是通过 UART1 口通信的，如果要从 UART0 通信，需要下载并编译 ESP-AT。

参考编译 ESP-AT 工程搭建好编译环境；

修改 factory_param_data.csv 表中对应模组的 UART 管脚，将 uart_tx_pin 修改为 GPIO1，uart_tx_pin 修改为 GPIO3；

调整配置：./build.py menuconfig > Component config > Common ESP-related > UART for console output(Custom) > Uart peripheral to use for console output(0-1)(UART1) > (1)UART TX on GPIO# (NEW) > (3)UART TX on GPIO# (NEW)。

AT 固件如何查看 error log？¶

ESP32 在 download port 查看 error log，默认 UART0 为 GPIO1、GPIO3。

ESP32-C3 在 download port 查看 error log，默认 UART0 为 GPIO21、GPIO20。

ESP8266 在 GPIO2 查看 error log，GPIO2 是 UART1 TX。

详情可以参阅硬件连接。

AT 在 ESP32 模组上的 UART1 通信管脚与 ESP32 模组的 datasheet 默认 UART1 管脚不一致？¶

ESP32 支持 IO 矩阵变换，在编译 ESP-AT 的时候，可以在 menuconfig 中通过软件配置修改 UART1 的管脚配置，所以就会出现和 datasheet 管脚不一致的情况。

管脚详情可以参阅 factory_param_data.csv。

性能 ¶

AT Wi-Fi 连接耗时多少？¶

在办公室场景下，AT Wi-Fi 连接耗时实测为 5 秒。但在实际使用中，Wi-Fi 连接时间取决于路由器性能，⽹络环境，模块天线性能等多个条件。

可以通过 AT+CWJAP 的 <jap_timeout> 参数，来设置最大超时时间。

ESP-AT 固件中 TCP 发送窗口大小是否可以修改？¶

TCP 发送窗口当前无法通过命令修改，需要配置和编译 ESP-AT 工程生成新的固件。

可以重新配置 menuconfig 参数，Component config > LWIP > TCP > Default send buffer size。

ESP32 AT 吞吐量如何测试及优化？¶

AT 吞吐量测试的影响因素较多，建议使⽤ esp-idf 中的 iperf 示例进行测试（用 AT 测试时，请使用透传方式，并将数据量调整为 1460 字节连续发送）。

若测试速率不满⾜需求，您可以参考如何提高 ESP-AT 吞吐性能来提高速率。

ESP32 AT 默认固件 Bluetooth LE UART 透传的最大传输率是？¶

办公室开放环境下，串口波特率为 2000000 时，ESP-AT Bluetooth 平均传输速率为 0.56 Mbps，ESP-AT Bluetooth LE 平均传输速率为 0.101 Mbps。

其他 ¶

乐鑫芯片可以通过哪些接口来传输 AT 命令？¶

ESP8266 只支持 UART 接口通信。ESP32 支持 SDIO，SPI，UART 接口通信。ESP32-C3 支持 UART，SPI 接口通信。

AT 默认固件是使用 UART 接口来传输。用户如果需要使用 SDIO 或者 SPI 接口进行通信，可以基于 ESP-AT 配置编译，详情请见编译和开发。

更多资料请参考使用 AT SDIO 接口，使用 AT SPI 接口，或使用 AT 套接字接口。

ESP32 AT 以太网功能如何使用？¶

AT 默认固件是不开启以太网功能的，您如果想要开启以太网功能，您可以参考如何启用 ESP-AT 以太网功能。

ESP-AT 如何进行 BQB 认证？¶

可参考 ESP32 更新多项 BQB 蓝牙认证。

ESP32 AT 如何指定 TLS 协议版本？¶

编译 ESP-AT 工程时，可以在 ./build.py menuconfig -> Component config -> mbedTLS 目录下，可以将不需要的版本关闭使能。

AT 固件如何修改 TCP 连接数？¶

目前 AT 默认固件的 TCP 最大连接数为 5。

ESP32 AT 最大支持 16 个 TCP 连接，可以在 menuconfig 中进行配置，配置方法如下：

./build.py menuconfig—> Component config—> AT—> (16)AT socket maximum connection number

./build.py menuconfig—> LWIP—> (16)Max number of open sockets

ESP8266 AT 最大支持 5 个 TCP 连接，可以在 menuconfig 中进行配置，配置方法如下：

./build.py menuconfig—> Component config—> AT—> (5)AT socket maximum connection number

./build.py menuconfig—> LWIP—> (10)Max number of open sockets

Index of Abbreviations¶

A2DP

Advanced Audio Distribution Profile

高级音频分发框架

ADC

Analog-to-Digital Converter

模拟数字转换器

ALPN

Application Layer Protocol Negotiation

应用层协议协商

AT

AT stands for “attention”.

AT 是 attention 的缩写。

AT command port

The port that is used to send AT commands and receive responses. More details are in the AT port introduction.

AT 命令端口

也称为 AT 命令口，用于发送 AT 命令和接收响应的端口。更多介绍请参考 AT 端口。

AT log port

The port that is used to output log. More details are in the AT port introduction.

AT 日志端口

也称为 AT 日志口，用于输出 AT 日志的端口。更多介绍请参考 AT 端口。

AT port

AT port is the general name of AT log port (that is used to output log) and AT command port (that is used to send AT commands and receive responses). Please refer to 硬件连接 for default AT port pins and 如何设置 AT 端口管脚 for how to customize them.

AT 端口

AT 端口是 AT 日志端口（用于输出日志）和 AT 命令端口（用于发送 AT 命令和接收响应）的总称。请参考硬件连接了解默认的 AT 端口管脚，参考如何设置 AT 端口管脚了解如何自定义 AT 端口管脚。

Bluetooth LE

Bluetooth Low Energy

低功耗蓝牙

BluFi

Wi-Fi network configuration function via Bluetooth channel

BluFi 是一款基于蓝牙通道的 Wi-Fi 网络配置功能

Command Mode

Default operating mode of AT. In the command mode, any character received by the AT command port will be treated as an AT command, and AT returns the command execution result to the AT command port. AT enters Data Mode from Command Mode in the following cases.

After sending the AT+CIPSEND set command successfully and returns >.
After sending the AT+CIPSEND execute command successfully and returns >.
After sending the AT+CIPSENDL set command successfully and returns >.
After sending the AT+CIPSENDEX set command successfully and returns >.
After sending the AT+SAVETRANSLINK set command successfully and sending the AT+RST command and restart the module.
After sending the AT+BTSPPSEND execute command successfully and returns >.
After sending the AT+BLESPP execute command successfully and returns >.

In the data mode, send the +++ command, AT will exit from Data Mode and enter the Command Mode.

命令模式

AT 的默认工作模式。在命令模式下，AT 命令端口收到的任何字符都会被当作 AT 命令进行处理，同时 AT 会在命令端口回复命令执行结果。 AT 在下列情况下，会从命令模式进入数据模式。

发送 AT+CIPSEND 设置命令成功，回复 > 之后
发送 AT+CIPSEND 执行命令成功，回复 > 之后
发送 AT+CIPSENDL 设置命令成功，回复 > 之后
发送 AT+CIPSENDEX 设置命令成功，回复 > 之后
发送 AT+SAVETRANSLINK 设置命令成功，再发送 (AT+RST) 命令，模组重启之后
发送 AT+BTSPPSEND 执行命令成功，回复 > 之后
发送 AT+BLESPP 执行命令成功，回复 > 之后

在数据模式下，发送 +++ 命令，会从数据模式退出，进入命令模式。

Data Mode

In the data mode, any character received by the AT command port will be treated as data (except for special +++) instead of the AT command, and these data will be sent to the opposite end without modification. AT enters Data Mode from Command Mode in the following cases.

After sending the AT+CIPSEND set command successfully and returns >.
After sending the AT+CIPSEND execute command successfully and returns >.
After sending the AT+CIPSENDL set command successfully and returns >.
After sending the AT+CIPSENDEX set command successfully and returns >.
After sending the AT+SAVETRANSLINK set command successfully and sending the AT+RST command and restart the module.
After sending the AT+BTSPPSEND execute command successfully and returns >.
After sending the AT+BLESPP execute command successfully and returns >.

In the data mode, send the +++ command, AT will exit from Data Mode and enter the Command Mode.

数据模式

在数据模式下，AT 命令端口收到的任何字符都会被当作数据（除了特殊的 +++），而不是 AT 命令，这些数据会无修改的发往对端。 AT 在下列情况下，会从命令模式进入数据模式。

发送 AT+CIPSEND 设置命令成功，回复 > 之后
发送 AT+CIPSEND 执行命令成功，回复 > 之后
发送 AT+CIPSENDL 设置命令成功，回复 > 之后
发送 AT+CIPSENDEX 设置命令成功，回复 > 之后
发送 AT+SAVETRANSLINK 设置命令成功，再发送 AT+RST 命令，模组重启之后
发送 AT+BTSPPSEND 执行命令成功，回复 > 之后
发送 AT+BLESPP 执行命令成功，回复 > 之后

在数据模式下，发送 +++ 命令，会从数据模式退出，进入命令模式。

DHCP

Dynamic Host Configuration Protocol

动态主机配置协议

DNS

Domain Name System

域名系统

DTIM

Delivery Traffic Indication Map

延迟传输指示映射

GATTC

Generic Attributes client

GATT 客户端

GATTS

Generic Attributes server

GATT 服务器

HID

Human Interface Device

人机接口设备

I2C

Inter-Integrated Circuit

集成电路总线

ICMP

Intemet Control Message Protocol

因特网控制报文协议

LWT

Last Will and Testament

遗嘱

MAC

Media Access Control

MAC 地址

mDNS

Multicast Domain Name System

多播 DNS

MSB

Most Significant Bit

最高有效位

MTU

maximum transmission unit

最大传输单元

NVS

Non-Volatile Storage

非易失性存储器

Normal Transmission Mode

Default Transmission Mode

In normal transmission mode, users can send AT commands. For examples, users can send MCU data received by AT command port to the opposite end of transmission by AT+CIPSEND; and the data received from the opposite end of transmission will also be returned to MCU through AT command port with additional prompt: +IPD.

During a normal transmission, if the connection breaks, ESP devices will give a prompt and will not attempt to reconnect.

More details are in Transmission Mode Shift Diagram.

普通传输模式

默认传输模式

在普通传输模式下，用户可以发送 AT 命令。例如，用户可以通过 AT+CIPSEND 命令，发送 AT 命令口收到的 MCU 数据到传输对端。从传输对端收到的数据，会通过 AT 命令口返回给 MCU，同时会附带 +IPD 信息。

普通传输模式时，如果连接断开，ESP 不会重连，并提示连接断开。

更多介绍请参考 Transmission Mode Shift Diagram。

Passthrough Mode

Also called as “Passthrough Sending & Receiving Mode”.

In passthrough mode, users cannot send AT commands except special +++ command. All MCU data received by AT command port will be sent to the opposite end of transmission without any modification; and the data received from the opposite end of transmission will also be returned to MCU through AT command port without any modification.

During the Wi-Fi passthrough transmission, if the connection breaks, ESP devices will keep trying to reconnect until +++ is input to exit the passthrough transmission.

More details are in Transmission Mode Shift Diagram.

透传模式

也称为 “透传发送接收模式”。

在透传模式下，用户不能发送其它 AT 命令，除了特别的 +++ 命令。AT 命令口收到的所有的 MCU 数据都将无修改地，发送到传输对端。从传输对端收到的数据也会通过 AT 命令口无修改地，返回给 MCU。

Wi-Fi 透传模式传输时，如果连接断开，ESP 会不停地尝试重连，此时单独输入 +++ 退出透传，则停止重连。

更多介绍请参考 Transmission Mode Shift Diagram。

Transmission Mode Shift Diagram

More details are in the following introduction.

Normal Transmission Mode (普通传输模式)
Passthrough Receiving Mode (透传接收模式)
Passthrough Mode (透传模式)
AT+CIPMODE
AT+CIPSEND
+++
AT+SAVETRANSLINK

Passthrough Receiving Mode

The temporary mode between Normal Transmission Mode and Passthrough Mode.

In passthrough receiving mode, AT cannot send any data to the opposite end of transmission; but the data received from the opposite end of transmission can be returned to MCU through AT command port without any modification. More details are in Transmission Mode Shift Diagram.

透传接收模式

在普通传输模式和透传模式之间的一个临时模式。

在透传接收模式，AT 不能发送数据到传输对端；但 AT 可以收到来自传输对端的数据，通过 AT 命令口无修改地返回给 MCU。更多介绍请参考 Transmission Mode Shift Diagram。

PBC

Push Button Configuration

按钮配置

PCI Authentication

Payment Card Industry Authentication. In ESP-AT project, it refers to all Wi-Fi authentication modes except OPEN and WEP.

PCI 认证，在 ESP-AT 工程中指的是除 OPEN 和 WEP 以外的 Wi-Fi 认证模式。

PKI

A public key infrastructure (PKI) is a set of roles, policies, hardware, software and procedures needed to create, manage, distribute, use, store and revoke digital certificates and manage public-key encryption.

More details are in Public Key Infrastructure.

公开密钥基础建设。公开密钥基础建设（PKI）是一组由硬件、软件、参与者、管理政策与流程组成的基础架构，其目的在于创造、管理、分配、使用、存储以及撤销数字证书。

更多介绍请参考公开密钥基础建设。

PLCP

Physical Layer Convergence Procedure

PLCP 协议，即物理层会聚协议

PMF

protected management frame

受保护的管理帧

PSK

Pre-shared Key

预共享密钥

PWM

Pulse-Width Modulation

脉冲宽度调制

QoS

Quality of Service

服务质量

RTC

Real Time Controller. A group of circuits in SoC that keeps working in any chip mode and at any time.

实时控制器，为 SoC 中的一组电路，在任何芯片模式下都能随时保持工作。

SMP

Security Manager Protocol

安全管理协议

SNI

Server Name Indication

服务器名称指示

SNTP

Simple Network Time Protocol

简单网络时间协议

SPI

Serial Peripheral Interface

串行外设接口

SPP

Serial Port Profile

SPP 协议，即串口协议

SSL

Secure Sockets Layer

SSL 协议，即安全套接字协议

TLS

Transport Layer Security

TLS 协议，即传输层安全性协议

URC

Unsolicited Result Code

非请求结果码，一般为模组给 MCU 的串口返回

UTC

Coordinated Universal Time

协调世界时

UUID

universally unique identifier

通用唯一识别码

WEP

Wired-Equivalent Privacy

WEP 加密方式，即有线等效加密

WPA

Wi-Fi Protected Access

Wi-Fi 保护访问

WPA2

Wi-Fi Protected Access II

Wi-Fi 保护访问 II

WPS

Wi-Fi Protected Setup

Wi-Fi 保护设置

关于 ESP-AT¶

[English]

这是 ESP-AT 的文档，ESP-AT 是乐鑫开发的可与乐鑫产品快速简单交互的解决方案。

乐鑫 Wi-Fi 和蓝牙芯片可以用作附加模块，可以完美集成在其他新产品或现有产品上，提供无线通讯功能。为降低客户开发成本，乐鑫开发了 AT 固件和各类 AT 命令，方便客户简单快速地使用 AT 命令来控制芯片。

乐鑫提供的 AT 固件具有以下特色，利于芯片快速集成到应用中：

内置 TCP/IP 堆栈和数据缓冲
能便捷地集成到资源受限的主机平台中
主机对指令的回应易于解析
用户可自定义 AT 命令

索引

提供有关此文档的反馈

设定值	读取值	实际值	实际 dBm
[40,80]	<设定值>	<设定值>	<设定值> * 0.25
[81,84]	<设定值>	80	20

通道	管脚
0	GPIO36
1	GPIO37
2	GPIO38
3	GPIO39
4	GPIO32
5	GPIO33
6	GPIO34
7	GPIO35

位	权限
0	BROADCAST
1	READ
2	WRITE WITHOUT RESPONSE
3	WRITE
4	NOTIFY
5	INDICATE
6	AUTHENTICATION SIGNED WRITES
7	EXTENDED PROPERTIES