AT FAQ

[English]

AT 文档

如何选择正确的 AT 文档版本？

请根据实际使用的 AT 固件版本，选择对应芯片平台和文档版本；不同固件版本之间可能存在功能和行为差异。

  • 对于 官方发布版固件，可直接通过 AT+USERDOCS? 命令获取对应文档链接，无需额外确认版本信息。

  • 对于非官方发布版固件，请先确认以下信息，再选择与之相匹配的文档版本：

    • 所用 AT 固件对应的芯片平台（如 ESP32、ESP32-C3 等）

    • AT 固件版本号（可通过 AT+GMR 命令查看 AT 核心库的版本号）

    选择 AT 文档目标和版本

AT 固件

我的模组没有官方发布的固件，如何获取适用的固件？

如果 AT 固件 中没有相关固件，可：

如何获取 AT 固件源码？

esp-at 项目以源代码和预编译库的组合形式在此仓库中分发。预编译的核心库（位于 esp-at/components/at/lib/ 目录下）是闭源的，无开源计划。

官网上放置的 AT 固件如何下载？

使用 Flash 下载工具 烧录，详细指导参阅 Flash 下载工具用户指南。烧录地址参考 AT 下载指南。

如何整合 ESP-AT 编译出来的所有 bin 文件？

无需手动整合。发布的固件和编译生成的固件已自带合成好的 2MB/4MB bin 文件，位于 build/factory 目录下。

新购买的 ESP 系列模组上电后，串口打印错误 “flash read err” 是什么原因？该模组如何使用 AT 命令？

ESP 系列模组出厂时 Flash 中未烧录 ESP-AT 固件，上电后会提示 “flash read err” 错误。如需使用 AT 命令功能，请参考 AT 下载指南。

模组出厂 AT 固件是否支持流控？

支持硬件流控，不支持软件流控。可通过 AT+UART_CUR 或 AT+UART_DEF 配置硬件流控。硬件接线参考 硬件连接。

AT 命令与响应

AT 提示 busy p… 是什么原因？

提示 “busy p…” 表示正在处理前一条命令，无法响应当前输入。AT 命令处理是线性的，必须等前一条命令完成后才能接收下一条。

当有多余的不可见字符输入时（如命令后的空格），系统也会提示 “busy p…” 或 “ERROR”，因为任何串口输入均被视为命令输入。

如果 MCU 发送 AT+CIPSEND 后收到 busy p… 响应，表示上一条命令正在执行，当前输入无效。建议等待上一条命令响应完成后再发送新命令。

AT 固件，上电后发送第一个命令总是会返回下面的信息，为什么？

ERR CODE:0x010b0000
busy p...

表示”正在处理上一条命令”。一般只显示 “busy p…”，显示 ERR CODE 是因为打开了错误代码提示。

如果上电后的第一条命令就返回此错误，可能原因：

  • 命令后多跟了换行符/空格/其他符号

  • 连续发送了多个 AT 命令

在不同模组上的默认 AT 固件支持哪些命令，以及哪些命令从哪个版本开始支持？

各模组默认固件支持的命令：参考 ESP-AT 固件差异

命令版本支持和修复问题：参考 release notes

MCU 给 ESP32-C6 设备发 AT 命令无返回，是什么原因？

发送 AT 命令后需添加结束符号，程序中写法为：”AT\r\n”。参考 检查 AT 固件是否烧录成功。

AT 命令中特殊字符如何处理？

可以参考 AT 命令分类 章节中的转义字符语法。

AT 命令中串口波特率是否可以修改？（默认：115200）

可以修改，方法：

如何修改 AT 命令端口的 UART 管脚？

有多种方法可以修改 AT 命令端口的 UART 管脚：

  • 第一种方法，请参考 如何设置 AT 端口管脚 文档，修改 factory_param_data.csv 文件中的 UART 配置参数，然后重新编译和烧录固件。

  • 第二种方法，如果你想在运行时通过 AT 命令修改 UART 配置而无需重新编译固件，请参考 AT+SYSMFG 命令示例。此方法可以动态修改出厂默认的 UART 配置，包括波特率、管脚等参数。

  • 第三种方法，如果你已有 AT 固件并且只需要修改 UART 管脚，可以使用 at.py 工具 直接修改固件参数，无需重新编译。

如何解决 TCP/SSL 数据传输时的丢失问题？

若在未启用硬件流控时出现数据丢失，建议先启用硬件流控（AT+UART_CUR 或 AT+UART_DEF）验证是否由此导致。若启用流控后问题仍存在，请参考 调试 TCP 连接的数据发送和接收过程 进一步排查；如确认为 AT 引发的问题，请在 esp-at/issues 提交 issue。

ESP32-C6 使用 AT 命令进入透传模式，如果连接的热点断开，ESP32-C6 能否给出相应的提示信息？

可通过 AT+SYSMSG 配置，设置 AT+SYSMSG=4，热点断开时串口会上报 WIFI DISCONNECT\\r\\n。

注意：该命令在 AT v2.1.0.0 之后添加，v2.1.0.0 及之前的版本无法使用。

Wi-Fi 为什么断开 (WIFI DISCONNECT)？

可在 AT 日志端口 查看断开原因，通常打印 wifi disconnected, rc:<reason_code>。 原因代码说明见 Wi-Fi Reason Code。

通用固件可能无法提供详细原因。若需获取具体信息，需在代码中注册 Wi-Fi disconnect 事件并输出原因代码。

Wi-Fi 常见的兼容性问题有哪些？

  • AMPDU 兼容性问题。

    • 如果路由器不支持 AMPDU，那么 ESP32-C6 会在和路由器交互时，自动关闭 AMPDU 功能。

    • 如果路由器支持 AMPDU，但是路由器和 ESP32-C6 之间的 AMPDU 传输存在兼容性问题，那么建议关闭路由器的 AMPDU 功能或者 ESP32-C6 的 AMPDU 功能。如果你要禁用 ESP32-C6 的 AMPDU 功能，请自行 编译 ESP-AT 工程，在第五步配置工程里选择：

      • 禁用 Component config > Wi-Fi > WiFi AMPDU TX

      • 禁用 Component config > Wi-Fi > WiFi AMPDU RX

  • phy mode 兼容性问题。如果路由器和 ESP32-C6 之间的 phy mode 存在兼容性问题，那么建议切换路由器的 phy mode 或者 ESP32-C6 的 phy mode。如果你要切换 ESP32-C6 的 phy mode，请参考 AT+CWSTAPROTO 命令。

AT 命令是否支持 ESP-WIFI-MESH？

AT 当前不支持 ESP-WIFI-MESH。

是否有 AT 命令连接阿里云以及腾讯云示例？

AT 命令是否可以设置低功耗蓝牙发射功率？

可以。ESP32-C6 的 Wi-Fi 和 Bluetooth LE 共用一根天线，使用 AT+RFPOWER 命令设置。

低功耗蓝牙客户端如何使能 notify 和 indicate 功能？

  • 低功耗蓝牙的特征的属性除了读、写还有 notify 和 indicate。这两种都是服务端向客户端发送数据的方式，但是要想真的发送成功需要客户端提前注册 notification，也就是写 CCCD 的值。

  • 如果要使能 notify，需要写 0x01；如果要使能 indicate，需要写 0x02 （写 0x2902 这个描述符）；如果是既想使能 notify 又想使能 indicate，需要写 0x03。

  • 比如，ESP-AT 的默认的服务中，0xC305 是可 notify 的，0xC306 是可 indicate 的。我们分别写这两个特征下面的 0x2902 描述符：

    AT+BLEGATTCWR=0,3,6,1,2
>
// 写低位 0x01 高位 0x00（如果要使用 hex 格式写的话就是：0100）
OK
// server: +WRITE:0,1,6,1,2,<0x01>,<0x00>
AT+BLEGATTCWR=0,3,7,1,2
>
// 写低位 0x02 高位 0x00（如果要使用 hex 格式写的话就是：0200）
OK
// server: +WRITE:0,1,6,1,2,<0x02>,<0x00>
// 写 ccc 是 server 可以发送 notify 和 indicate 的前提条件

硬件

在不同模组上的 AT 固件要求芯片 flash 多大？

参考 ESP-AT 固件差异。

AT 固件如何查看 error log？

通常从 AT 日志端口 查看 error log。

AT 在 ESP32-C6 模组上的 UART1 通信管脚与 ESP32-C6 模组的 datasheet 默认 UART1 管脚不一致？

ESP32-C6 支持 IO 矩阵变换，编译 ESP-AT 时可在 menuconfig 中配置 UART1 管脚，因此可能与 datasheet 默认管脚不一致。 管脚详情参考 factory_param_data.csv。

性能

AT Wi-Fi 连接耗时多少？

办公室场景下实测约 5 秒。实际耗时取决于路由器性能、网络环境、模块天线性能等因素。 可通过 AT+CWJAP 的 <jap_timeout> 参数设置最大超时时间。

AT 固件中 TCP 发送窗口大小是否可以修改？

无法通过命令修改，需重新编译固件。在 menuconfig 中配置：Component config > LWIP > TCP > Default send buffer size。

AT 吞吐量如何测试及优化？

建议使用 esp-idf 中的 iperf 示例进行测试（AT 测试时请使用透传方式，并将数据量调整为 1460 字节连续发送）。 若速率不满足需求，参考 如何提高 ESP-AT 吞吐性能 进行优化。

如何修改 AT 默认 TCP 数据段最大重传次数？

默认重传最大次数为 6 次，取值范围 [3-12]。重新配置方法：

其他

乐鑫芯片可以通过哪些接口来传输 AT 命令？

AT 如何使能调试日志？

参考 如何启用更多 AT 调试日志 文档。

如何修改 AT 固件首次启动时的默认 Wi-Fi 模式？

修改源码，在 esp_at_ready_before() 函数中调用 esp_wifi_set_mode() 设置 Wi-Fi 模式，例如 esp_wifi_set_mode(WIFI_MODE_STA)。

AT 指令如何实现 HTTP 断点续传功能？

两种方法：

如何从 HTTP 服务器下载文件并存储到 FATFS，或将 FATFS 文件系统中的文件上传到 HTTP 服务器？

参考 GitHub 示例：

使用 nmap 等工具扫描发现 AT 设备存在开放端口，是否说明固件存在安全风险？

结论：默认 AT 固件连上 Wi-Fi 后 不会主动监听 任何端口。未通过 AT 命令创建连接或服务时，nmap 报告的 open / open|filtered 不是 固件在提供服务。

仅在使用 AT+CIPSTART、AT+CIPSERVER、AT+WEBSERVER、AT+MDNS 等命令时才会占用端口。

误判原因

  • UDP 扫描不可靠：nmap -sU 靠 ICMP port-unreachable 判断端口关闭；未收到回复即标记 open|filtered， 不等于 端口在监听。UDP 及 ICMP 回复 会丢包，全端口高速扫描（如 -p 1-65535 -T4）误报更多， 不能 据此认定设备开放了端口。

  • 扫错目标或已有连接：确认 IP 与 AT+CIFSR 一致；高位 UDP 端口来自 AT+CIPSTART 套接字，5353 仅 AT+MDNS 启用后存在。

排查

  1. AT+CIFSR、AT+CIPSTATE? — 核对 IP 与当前连接，无多余监听即正常。

  2. TCP 扫描：sudo nmap -sS -p- <IP>；未建连时应全部 closed。

  3. 需 UDP 扫描时用 -T2 降速，或抓包确认 port-unreachable 是否到达。

  4. AT+RST 后仅 AT+CWJAP 连 Wi-Fi，再复扫。

仍异常请记录扫描命令、AT+GMR 版本及 AT 命令序列，至 esp-at/issues 反馈。

使用 esp-idf-sbom 扫描 AT 固件出现大量 CVE，是否会影响 RED、EN 18031、CRA 等合规？

esp-idf-sbom 等工具报告的 CVE 针对的是软件组件（库）的特定版本，并不代表最终编译出的 AT 固件一定受影响。多数 CVE 只有在相关功能或代码路径被启用时才会编入固件并具备触发条件；对于 AT 固件中未启用的功能，其源码不会进入最终二进制，对应漏洞也就没有触发条件。因此，这类 CVE 通常不影响 AT 固件满足欧盟无线电设备指令（RED，2014/53/EU）的网络安全要求（委托条例 (EU) 2022/30 及协调标准 EN 18031 系列）以及《网络弹性法案》(CRA) 等合规要求，提供一份自我评估 (self-assessment) 说明即可。

扫描结果之所以会高估风险，主要原因如下：

  • 工具按组件版本号匹配公开漏洞库（如 NVD），只要版本落在受影响范围内即报告，并不分析该漏洞在具体编译配置下是否真正可达。

  • ESP-AT 通过 menuconfig (Kconfig) 裁剪功能，被关闭功能对应的源码不会编入固件，其携带的漏洞也不存在于最终二进制中。

  • 即使代码被编入固件，漏洞往往仍需多个前提条件同时满足才能触发，任一条件不满足即不可利用。

以 CVE-2026-34873（TLS 1.3 会话恢复期间的客户端伪装）为例，该漏洞影响 Mbed TLS 3.5.0 至 3.6.5 及 4.0.0（会被 SBOM 报告）。根据 官方安全公告，仅当以 服务端 角色运行的 Mbed TLS 同时满足以下条件时才可能受影响：

  • 同时支持 TLS 1.2 与 TLS 1.3；

  • 配置为对客户端进行身份认证；

  • 向已认证的客户端签发 TLS 1.3 会话票据 (session ticket) 用于后续会话恢复。

AT 固件虽然可通过 AT+CIPSTART 作为 SSL 客户端、通过 AT+CIPSERVER 作为 SSL 服务端，但其 Mbed TLS 默认未启用 TLS 1.3（需在 menuconfig 中手动开启，参见 修改 TLS 协议版本），因此既不会协商 TLS 1.3，也不会签发 TLS 1.3 会话票据，上述条件无从满足。所以，尽管 SBOM 会因 Mbed TLS 版本报告该 CVE，但在默认 AT 固件配置下，该漏洞无法被触发，因此对固件没有实际影响。

建议按以下步骤处理被报告的 CVE：

  1. 查阅每条 CVE 的官方描述（如 NVD、组件安全公告），确认其触发所需的配置与运行条件。

  2. 对照 AT 固件实际情况，检查相关功能是否启用、代码是否被编译、运行时是否具备触发场景。可参考 本地编译 ESP-AT 工程 确认编译配置。

  3. 对每条 CVE 标注受影响 / 不受影响及判定依据，作为合规所需的自我评估材料。

  4. 若确认某条 CVE 在你的配置下确实可达，可升级到包含修复的组件版本或关闭相关功能后重新编译固件，也欢迎通过 esp-at/issues 联系我们。我们持续跟踪上游组件的安全公告，在适当情况下更新相关依赖，并将适用的安全修复集成到后续发布的 AT 固件版本中。

提供有关此文档的反馈