本地编译 ESP-AT 工程

[English]

本文档详细介绍了如何本地编译 ESP-AT 工程，并将生成的固件烧录到 ESP32 设备中。当默认的官方发布的固件无法满足需求时，如您需要自定义 AT 端口管脚、低功耗蓝牙服务以及分区等，那么就需要编译 ESP-AT 工程。

如果本地编译 ESP-AT 工程有困难，或者需要修改的代码量较少，推荐您通过如何在 GitHub 网页上编译 ESP-AT 工程。

详细步骤

请根据下方详细步骤，完成 ESP-AT 工程的克隆、环境安装、配置、编译以及烧录。推荐您优先选择 Linux 系统开发。

第一步：ESP-IDF 快速入门
第二步：获取 ESP-AT
第三步：安装环境
第四步：连接设备
第五步：配置工程
第六步：编译工程
第七步：烧录到设备
build.py 进阶用法

第一步：ESP-IDF 快速入门

在编译 ESP-AT 工程之前，请先学习使用 ESP-IDF，因为 ESP-AT 是基于 ESP-IDF 开发的。

请您根据 ESP-IDF v5.0 快速入门文档的指导，完成 hello_world 工程的配置、编译以及下载固件至 ESP32 开发板等步骤。

备注

此步骤不是必须的，但如果您是初学者，强烈建议您完成此步骤，以熟悉 ESP-IDF 并确保顺利进行以下步骤。

完成上一步的 ESP-IDF 快速入门后，便可以开始下面的 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 5.0 CMD。

cd %userprofile%\esp
git clone --recursive https://github.com/espressif/esp-at.git

如果您位于中国或访问 GitHub 有困难，也可以使用 git clone https://jihulab.com/esp-mirror/espressif/esp-at.git 或者 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 不支持带有空格的路径。

第三步：安装环境

运行项目工具 install 来安装环境。此安装工具将自动安装依赖的 Python 包、ESP-IDF 仓库以及 ESP-IDF 依赖的编译器、工具等。

Linux 或 macOS
```
./build.py install
```
Windows
```
python build.py install
```

如果是第一次安装环境，请为 ESP32 设备选择以下配置选项。

选择 Platform name，例如 ESP32 系列设备选择 PLATFORM_ESP32。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 文件存在，上述三个配置选项将不会出现。因此，如果您想重新配置模组信息，请删除该文件。

第四步：连接设备

使用 USB 线将您的 ESP32 设备连接到 PC 上，以下载固件和输出日志，详情请见硬件连接。注意，如果您在编译过程中不发送 AT 命令和接收 AT 响应，则不需要建立 “AT 命令/响应” 连接。关于更改默认端口管脚的信息请参考如何设置 AT 端口管脚。

第五步：配置工程

运行项目工具 menuconfig 来配置。

Linux 或 macOS
```
./build.py menuconfig
```
Windows
```
python build.py menuconfig
```

如果以上所有步骤都正确，则会弹出下面的菜单：

此菜单可以用来配置每个工程，如更改 AT 端口管脚、启用经典蓝牙功能等，如果不修改配置，那么就会按照默认配置编译工程。

第六步：编译工程

运行以下命令编译工程。

Linux 或 macOS

./build.py build

Windows

python build.py build

如果启用了蓝牙功能，固件尺寸会大大增加。请确保它不超过 ota 分区的大小。

编译完成后会在 build/factory 路径下生成打包好的量产固件。更多信息请参见 ESP-AT 固件差异。

第七步：烧录到设备

运行以下命令将生成的固件烧录到 ESP32 设备上。

Linux 或 macOS

./build.py -p (PORT) flash

Windows

python build.py -p (PORT) flash

注意请用 ESP32 设备的串口名称替换 (PORT)。或者按照提示信息将固件烧录到 flash 中。仍然需要注意替换 (PORT)。

如果 ESP-AT bin 不能启动，并且打印出 “ota data partition invalid”，请运行 python build.py erase_flash 来擦除整个 flash，然后重新烧录 AT 固件。

build.py 进阶用法

build.py 脚本是基于 idf.py 封装的工具（即 idf.py <cmd> 功能均包含在 build.py <cmd> 里），您可以运行以下命令查看更多用法。

Linux 或 macOS

./build.py --help

Windows

python build.py --help

提供有关此文档的反馈