ESP-AT 用户指南 Choose target... Choose version... 入门 AT Binary 列表 AT 命令集 AT 命令示例 AT 版本简介 编译和开发 第三方开放云平台定制化 AT FAQ 缩写词索引 特别声明 关于 ESP-AT ESP-AT 用户指南 ESP-AT 用户指南 在 GitHub 上编辑 ESP-AT 用户指南 [English] 这里是乐鑫 ESP-AT 开发框架的文档中心。ESP-AT 作为由 Espressif Systems 发起和提供技术支持的官方项目，适用于 Windows、Linux、macOS 上的 ESP32、ESP32-C2、ESP32-C3、ESP32-C5、ESP32-C6、ESP32-C61、和 ESP32-S2 系列芯片。 本文档仅包含针对 ESP32-C5 芯片的 ESP-AT 使用。如需了解其他芯片，请在页面左上方的下拉菜单中选择你的目标芯片。 入门 AT Binary 列表 AT 命令集 AT 命令示例 编译和开发 第三方定制化 AT 命令和固件 索引 提供有关此文档的反馈 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download PDF ESP-AT 用户指南 Choose target... Choose version... 入门 ESP-AT 是什么 技术选型 硬件连接 下载指导 AT Binary 列表 AT 命令集 AT 命令示例 AT 版本简介 编译和开发 第三方开放云平台定制化 AT FAQ 缩写词索引 特别声明 关于 ESP-AT ESP-AT 用户指南 入门指南 在 GitHub 上编辑 入门指南 [English] 本指南详细介绍 ESP-AT 是什么、技术选型、如何连接硬件、以及如何下载和烧录 AT 固件，由以下章节组成： ESP-AT 是什么 技术选型 硬件连接 下载指导 如果你尚不了解 ESP-AT 工程，请阅读 ESP-AT 是什么。 如果你想学习如何使用 ESP-AT，请首先阅读 技术选型，帮助你选型硬件和软件，再阅读 硬件连接，了解所需的硬件以及硬件之间如何连接，然后再阅读 下载指导，了解如何下载和烧录 AT 固件。 提供有关此文档的反馈 上一页 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download PDF ESP-AT 用户指南 Choose target... Choose version... 入门 ESP-AT 是什么 技术选型 硬件连接 下载指导 AT Binary 列表 AT 命令集 AT 命令示例 AT 版本简介 编译和开发 第三方开放云平台定制化 AT FAQ 缩写词索引 特别声明 关于 ESP-AT ESP-AT 用户指南 入门指南 ESP-AT 是什么 在 GitHub 上编辑 ESP-AT 是什么 [English] 重要 在使用 ESP-AT 前，请仔细阅读 特别声明，并遵循其中的各项条款和注意事项。 ESP-AT 是乐鑫开发的可直接用于量产的物联网应用固件，旨在降低客户开发成本，快速形成产品。通过 ESP-AT 命令，你可以快速加入无线网络、连接云平台、实现数据通信以及远程控制等功能，真正的通过无线通讯实现万物互联。 ESP-AT 是基于 ESP-IDF 实现的软件工程。它使 ESP32-C5 模组作为从机，MCU 作为主机。MCU 发送 AT 命令给 ESP32-C5 模组，控制 ESP32-C5 模组执行不同的操作，并接收 ESP32-C5 模组返回的 AT 响应。ESP-AT 提供了大量功能不同的 AT 命令，如 Wi-Fi 命令、TCP/IP 命令、Bluetooth LE 命令、MQTT 命令、HTTP 命令等。 ESP-AT 概览 AT 命令以 “AT” 开始，代表 Attention，以新的一行 (CR LF) 为结尾。输入的每条命令都会返回 OK 或 ERROR 的响应，表示当前命令的最终执行结果。注意，所有 AT 命令均为串行执行，每次只能执行一条命令。因此，在使用 AT 命令时，应等待上一条命令执行完毕后，再发送下一条命令。如果上一条命令未执行完毕，又发送了新的命令，则会返回 busy p... 提示。更多有关 AT 命令的信息可参见 AT 命令集。 默认配置下，MCU 通过 UART 连接至 ESP32-C5 模组、发送 AT 命令以及接收 AT 响应。但是，你也可以根据实际使用情况修改程序，使用其他的通信接口，例如 SDIO。 同样，你也可以基于 ESP-AT 工程，自行开发更多的 AT 命令，以实现更多的功能。 提供有关此文档的反馈 上一页 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download PDF ESP-AT 用户指南 Choose target... Choose version... 入门 AT Binary 列表 AT 命令集 AT 命令示例 AT 版本简介 编译和开发 第三方开放云平台定制化 AT FAQ 缩写词索引 特别声明 应用场景验证 兼容性 服务器升级注意事项 无线方案问题处理 使用限制 责任限制 第三方软件和技术 数据保护 版本更新与维护 声明更新 用户责任 关于 ESP-AT ESP-AT 用户指南 特别声明 在 GitHub 上编辑 特别声明 [English] 感谢你选择使用 ESP-AT 方案（固件）。为了确保你对本方案（本固件）的使用安全、合法且符合预期效果，请仔细阅读以下特别声明。本声明旨在明确用户在使用本方案（本固件）过程中需要遵循的各项条款和注意事项。通过继续使用本方案（本固件），你即表示接受并同意遵守这些条款。 应用场景验证 本方案（本固件）为通用版本，尽管针对各种场景做了大量的测试，但测试用例仍存在某些应用场景无法覆盖的风险，在决定基于本方案（本固件）进行商用量产前，请结合自己的应用场景，进行充足且全面的验证。 兼容性 由于技术日新月异，当某一新的技术、方案或标准出现时，可能导致兼容性问题，请结合自己产品做好相应的测试验证，并关注本方案（本固件）的新版本发布情况。 服务器升级注意事项 当对服务器进行升级时，包括但不限于操作系统升级、工具升级、证书升级等，请务必在正式升级前进行测试验证，避免因服务器变动导致的连接问题。 无线方案问题处理 无线方案易受外部因素影响，且问题定位复杂。请结合自身产品和云平台，规划好远程 OTA 和远程问题信息获取的解决方案，否则可能需要用户现场提供日志、数据包等必需的信息进行问题分析。 使用限制 用户不得将本方案（本固件）用于非法活动或违反相关法律法规的用途。用户应确保其使用本方案（本固件）的行为符合所有适用的法律和法规，我司不对因非法使用本方案（固件）而产生的任何后果负责。 责任限制 对于因使用本方案（本固件）造成的直接、间接、偶然、特殊或继发性的损害（包括但不限于数据丢失、利润损失、业务中断等），我司不承担任何责任，即使已被告知可能发生此类损害。 第三方软件和技术 本方案（本固件）可能包含第三方的软件或技术，我司对这些第三方软件或技术的适用性和合规性不承担责任。用户应遵循第三方的许可协议和使用条款。 数据保护 用户在使用本方案（本固件）过程中产生的数据应由用户自行负责保护和备份。我司对因数据丢失或泄露引起的任何损失不承担责任。 版本更新与维护 本方案（本固件）会不定期进行维护更新及版本发布，请自行关注版本状态，恕不另行通知。 声明更新 本声明条款可能会不定期更新，恕不另行通知。 用户责任 强烈建议用户认真阅读并严格遵守本声明条款，由于未遵守导致的风险，需由用户承担。 感谢你的理解与配合！ 提供有关此文档的反馈 上一页 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download PDF ESP-AT 用户指南 Choose target... Choose version... 入门 AT Binary 列表 ESP32-C5 AT 发布版固件 AT 固件简介 AT 命令集 AT 命令示例 AT 版本简介 编译和开发 第三方开放云平台定制化 AT FAQ 缩写词索引 特别声明 关于 ESP-AT ESP-AT 用户指南 AT 固件 在 GitHub 上编辑 AT 固件 [English] 本文档包含以下小节： 下载 ESP32-C5 AT 发布版固件 AT 固件简介：AT 固件包含哪些二进制文件及其作用 备注 若需下载其他芯片系列的发布版固件，请在页面左上方的下拉菜单栏选择相应的芯片，即可跳转至该芯片的文档进行下载。 AT 暂无计划支持 ESP32-H 系列、ESP32-P 系列、ESP32-S3 系列芯片，也暂无对应的 AT 固件。推荐使用 ESP32-C 系列芯片。 AT 固件简介 ESP-AT 固件包含了若干个特定功能的二进制文件： build ├── at_customize.bin // 二级分区表（用户分区表，列出了 mfg_nvs 分区以及 fs_storage 分区的起始地址和分区大小） ├── bootloader │ └── bootloader.bin // 启动加载器 ├── customized_partitions │ └── mfg_nvs.bin // 出厂配置参数，参数值见同级目录下的 mfg_nvs.csv ├── esp-at.bin // AT 应用固件 ├── factory │ └── factory_xxx.bin // 特定功能的二进制文件合集，你可以仅烧录本文件到起始地址为 0 的 flash 空间中，或者根据 download.config 文件中的信息将若干个二进制文件烧录到 flash 中对应起始地址的空间中。 ├── partition_table │ └── partition-table.bin // 一级分区表（系统分区表） └── ota_data_initial.bin // OTA 数据初始化文件 提供有关此文档的反馈 上一页 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download PDF ESP-AT 用户指南 Choose target... Choose version... 入门 AT Binary 列表 ESP32-C5 AT 发布版固件 介绍 ESP32-C5-4MB 系列 订阅 AT 版本发布 AT 发布固件差异 支持的命令集 硬件差异 支持的模组 AT 固件简介 AT 命令集 AT 命令示例 AT 版本简介 编译和开发 第三方开放云平台定制化 AT FAQ 缩写词索引 特别声明 关于 ESP-AT ESP-AT 用户指南 AT 固件 发布的固件 在 GitHub 上编辑 发布的固件 [English] 介绍 ESP32-C5-4MB 系列 订阅 AT 版本发布 AT 发布固件差异 介绍 备注 在使用下面的 AT 固件前，请仔细阅读 特别声明，并遵循其中的各项条款和注意事项。 如果你不确定自己的模组是否可以使用 AT 默认固件，请先阅读 AT 发布固件差异 章节，该章节介绍了 ESP32-C5 AT 固件支持的命令集、硬件配置和支持的模组，帮助你确认你的模组硬件配置是否适合使用 AT 默认固件。 如果你想要修改 AT 固件中下面的配置，你可以通过 at.py 工具 修改 AT 固件并生成新的 AT 固件。 修改 UART 配置 修改 Wi-Fi 配置 修改证书和密钥配置 修改 GATTS 配置 ESP32-C5-4MB 系列 提示 如需测试，请从 GitHub Actions 里下载 esp32c5-4MB-at 固件，或者 本地编译 ESP-AT 工程。 如需量产，请点击下面已发布的版本，填写 AT 固件申请表，获取适用于 ESP32-C5 系列芯片的 AT 固件。 已发布的版本： v5.0.1.0 （推荐） v5.0.0.0 订阅 AT 版本发布 请参考 订阅 AT 版本发布 文档订阅我们的版本发布通知，及时获取最新版本的发布情况。 AT 发布固件差异 本章节比较了以下 ESP32-C5 系列的 AT 发布固件在支持的命令集、硬件、模组方面的差异。 ESP32-C5-4MB-AT-Vx.x.x.x.zip（本节简称为 ESP32-C5-4MB Bin） 支持的命令集 下表列出了官方适配的 ESP32-C5 系列 AT 固件默认支持哪些命令集（用 表示）、默认不支持但可以在配置和编译 ESP-AT 工程后支持的命令集（用 表示）、完全不支持的命令集（用 表示），下表没有列出的命令集也为完全不支持的命令集。正式发布的固件见 AT 固件，已适配但未发布的模组固件，需要自行编译。自行编译的固件无法从乐鑫官方服务器进行 OTA 升级。 命令集 ESP32-C5-4MB Bin base user Wi-Fi TCP-IP mDNS WPS SmartConfig ping MQTT HTTP Bluetooth LE BluFi FileSystem driver WPA2 enterprise Web server WebSocket OTA 硬件差异 硬件 ESP32-C5-4MB Bin Flash 4 MB PSRAM UART 管脚 [1] TX: 23 RX: 24 CTS: 25 RTS: 26 [1] UART 管脚可自定义，详情请参考 如何设置 AT 端口管脚。 支持的模组 下表列出了官方发布的 ESP32-C5 系列 AT 固件默认支持哪些模组或芯片（用 表示）、默认不支持但可以通过 at.py 工具 修改后支持的模组（用 表示），以及完全不支持的模组（用 表示）。对于完全不支持的模组，你可以 本地编译 ESP-AT 工程 修改你需要的配置后支持。 模组/芯片 ESP32-C5-4MB Bin ESP32-C5-MINI-1 ESP32-C5-WROOM-01 提供有关此文档的反馈 上一页 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download PDF ESP-AT 用户指南 Choose target... Choose version... 入门 AT Binary 列表 AT 命令集 AT 命令示例 AT 版本简介 编译和开发 如何本地编译 AT 工程 如何在 GitHub 网页上编译 AT 工程 如何修改 AT 管脚 如何添加自定义 AT 命令 如何提高 ESP-AT 吞吐性能 如何更新 mfg_nvs 分区 如何更新出厂参数 如何更新 PKI 配置 如何自定义低功耗蓝牙服务 如何自定义分区 如何增加一个新的模组支持 如何实现 SDIO AT 如何实现 SPI AT 如何基于乐鑫服务器实现自己的 OTA 管理 如何更新 ESP-IDF 版本 ESP-AT 固件差异 如何从 GitHub 下载最新临时版本 AT 固件 at.py 工具 详细步骤 第一步：Python 安装 第二步：at.py 下载 第三步：at.py 用法说明 第四步：at.py 修改固件中的配置示例 修改 Wi-Fi 配置 修改证书和密钥配置 修改 UART 配置 修改 GATTS 配置 ESP-AT API 参考 如何配置 silence mode 如何启用更多 AT 调试日志 第三方开放云平台定制化 AT FAQ 缩写词索引 特别声明 关于 ESP-AT ESP-AT 用户指南 如何编译和开发自己的 AT 工程 at.py 工具 在 GitHub 上编辑 at.py 工具 [English] at.py 工具用于修改打包好的 2 MB/4 MB AT 量产固件（即 build/factory 目录下的 factory_XXX.bin）中的多种参数配置。这些配置包括 Wi-Fi 配置、证书和密钥配置、UART 配置、GATTS 配置等。当默认的固件无法满足你的需求时，你可以使用 at.py 工具修改固件中的这些参数配置。 详细步骤 请根据下方详细步骤，完成 at.py 工具下载、固件中的配置修改以及固件烧录。推荐你优先选择 Linux 系统开发。 第一步：Python 安装 第二步：at.py 下载 第三步：at.py 用法说明 第四步：at.py 修改固件中的配置示例 第五步：固件烧录 第一步：Python 安装 如果你本地已经安装过 Python，则可以跳过此步骤。否则，请根据 Python 官方文档，完成 Python 的下载和安装。推荐你使用 Python 3.10.0 或更高版本。 安装完成后，你可以在命令行中输入 python --version，查看 Python 版本。 第二步：at.py 下载 访问 at.py 页面，点击 Download raw file 按钮，将 at.py 文件下载到本地。 下载 at.py 文件 第三步：at.py 用法说明 当前 at.py 支持修改固件中的参数配置，请在命令行中输入 python at.py modify_bin --help，查看支持的用法以及说明。 第四步：at.py 修改固件中的配置示例 修改 Wi-Fi 配置 修改证书和密钥配置 修改 UART 配置 修改 GATTS 配置 备注 你可以混合修改多种参数配置，例如，你可以同时修改 Wi-Fi 配置和证书和密钥配置。 待修改的参数配置，脚本并不会检查其合法性，请确保你输入的参数配置是合法的。 修改后的参数配置，在当前 mfg_nvs 目录下的 mfg_nvs.csv 中，会有对应的记录。 修改 Wi-Fi 配置 当前可修改的 Wi-Fi 参数配置如下表所示： 参数 功能 说明 --tx_power Wi-Fi 的最大发射功率 详情见 ESP32-C5 发射功率 --country_code Wi-Fi 国家代码 详情见 Wi-Fi 国家/地区代码 中的 cc 字段 --start_channel Wi-Fi 起始信道 详情见 Wi-Fi 国家/地区代码 中的 schan 字段 --channel_number Wi-Fi 的总信道数 详情见 Wi-Fi 国家/地区代码 中的 nchan 字段 例如，你可以使用以下命令，修改 Wi-Fi 的最大发射功率为 18 dBm，国家代码为 US，起始信道为 1，总信道数为 11： python at.py modify_bin --tx_power 72 --country_code "US" --start_channel 1 --channel_number 11 --input factory_XXX.bin --tx_power 72：单位是 0.25 dBm，72 表示 18 dBm --input factory_XXX.bin：输入的固件文件 修改证书和密钥配置 当前可修改的证书和密钥配置如下表所示： 参数 功能 原始文件 --server_ca TLS 服务器的 CA 证书 server_ca.crt --server_cert TLS 服务器的证书 server_cert.crt --server_key TLS 服务器的密钥 server.key --client_ca0 第 0 套客户端的 CA 证书 client_ca_00.crt --client_cert0 第 0 套客户端的证书 client_cert_00.crt --client_key0 第 0 套客户端的密钥 client_key_00.key --client_ca1 第 1 套客户端的 CA 证书 client_ca_01.crt --client_cert1 第 1 套客户端的证书 client_cert_01.crt --client_key1 第 1 套客户端的密钥 client_key_01.key --mqtt_ca MQTT 客户端的 CA 证书 mqtt_ca.crt --mqtt_cert MQTT 客户端的证书 mqtt_client.crt --mqtt_key MQTT 客户端的密钥 mqtt_client.key --wpa2_ca WPA2-Enterprise 客户端的 CA 证书 wpa2_ca.pem --wpa2_cert WPA2-Enterprise 客户端的证书 wpa2_client.crt --wpa2_key WPA2-Enterprise 客户端的密钥 wpa2_client.key 例如，你可以使用以下命令，修改 MQTT 客户端的 CA 证书、客户端的证书和密钥。 python at.py modify_bin --mqtt_ca mqtt/mqtt_ca.crt --mqtt_cert mqtt/mqtt.crt --mqtt_key mqtt/mqtt.key --input factory_XXX.bin --input factory_XXX.bin：输入的固件文件 修改 UART 配置 可修改的 UART 配置，仅包括 AT 命令端口 的 UART 配置。可修改的参数配置如下表所示： 参数 功能 说明 --uart_num AT 命令口的 UART 号 仅在 AT 日志口同时用作 AT 命令口时，需要修改此参数。同时需保证下面的 tx_pin 和 rx_pin 要配置与 AT 日志端口 的 tx 和 rx 管脚一致，如果 AT 日志端口 只配置了 rx，则下面 tx_pin 需要配置与下载固件口（可查看 硬件连接）的 UART 的 tx 管脚一致。 --baud AT 命令口的波特率 原始值：115200。 --tx_pin AT 命令口的 TX 管脚 请保证待修改的管脚不会和其他管脚冲突。 --rx_pin AT 命令口的 RX 管脚 请保证待修改的管脚不会和其他管脚冲突。 --cts_pin AT 命令口的 CTS 管脚 请保证待修改的管脚不会和其他管脚冲突。不用流控时，修改此参数为 -1。 --rts_pin AT 命令口的 RTS 管脚 请保证待修改的管脚不会和其他管脚冲突。不用流控时，修改此参数为 -1。 例如，你可以使用以下命令，修改 AT 命令口的波特率为 921600，TX 管脚为 17，RX 管脚为 16，禁用流控。 python at.py modify_bin --baud 921600 --tx_pin 17 --rx_pin 16 --cts_pin -1 --rts_pin -1 --input factory_XXX.bin --input factory_XXX.bin：输入的固件文件 修改 GATTS 配置 修改前，请先阅读 如何自定义低功耗蓝牙服务 文档，了解 GATTS 的配置文件 gatts_data.csv 中的各个字段的含义。 当前可修改的