Compile ESP-AT Project Locally
This document details how to build your own ESP-AT project locally and flash the generated firmware into your ESP32-C2. It comes in handy when the official released fimware cannot meet your needs, for example, to customize the AT port pins and partitions, and so on.
If you have difficulties in compiling ESP-AT project locally, or you only need to modify a small amount of code, we recommend that you use Compile ESP-AT Project on the GitHub Webpage.
Detailed Steps
Please follow the detailed steps below to set up your environment and build the project. It is recommended that you develop the esp-at project on Linux system.
Step 1. Get Started with ESP-IDF
Get started with ESP-IDF before compiling an ESP-AT project, because ESP-AT is developed based on ESP-IDF.
Please follow ESP-IDF v5.0 Get Started guide, configure, build, flash onto the ESP32-C2 device of the hello_world
example.
Note
This step is not a must, but if you are a beginner, you are strongly recommended to complete it in order to familiarize yourself with ESP-IDF and ensure smooth proceeding with the following steps.
After you complete the ESP-IDF get started in the step above, now you can proceed to compile an ESP-AT project according to the following steps.
Step 2. Get ESP-AT
To compile an ESP-AT project, you need the software libraries provided by Espressif in the ESP-AT repository.
To get ESP-AT, navigate to your installation directory and clone the repository with git clone
, following instructions below specific to your operating system.
Linux or macOS
cd ~/esp git clone --recursive https://github.com/espressif/esp-at.git
Windows
For ESP32-C2 series of modules, it is recommended that you run ESP-IDF 5.0 CMD as an administrator first.
cd %userprofile%\esp git clone --recursive https://github.com/espressif/esp-at.git
If you are located in China or have difficulties to access GitHub, you can also use git clone https://jihulab.com/esp-mirror/espressif/esp-at.git
or git clone https://gitee.com/EspressifSystems/esp-at.git
to get ESP-AT, which may be faster.
ESP-AT will be downloaded into ~/esp/esp-at
on Linux or macOS, or %userprofile%\esp\esp-at
on Windows.
Note
This guide uses the directory ~/esp
on Linux or macOS, or %userprofile%\esp
on Windows as an installation folder for ESP-AT. You can use any directory, but you will need to adjust paths for the commands respectively. Keep in mind that ESP-AT does not support spaces in paths.
Step 3. Install Environment
Run the project tool install
to install the environment. This tool will automatically install Python packages, ESP-IDF repository, and the compiler and tools used by ESP-IDF.
Linux or macOS
./build.py install
Windows
python build.py install
Select the following configuration options for your ESP32-C2 if it is your first time.
Select the
Platform name
for your ESP32-C2. For example, selectPLATFORM_ESP32C2
for ESP32-C2 series of products.Platform name
is defined in factory_param_data.csv .Select the
Module name
for your ESP32-C2. For example, selectESP32C2-4MB
for the ESP8684-MINI-1 4MB module.Module name
is defined in factory_param_data.csv .
Before selecting to enable or disable silence mode, please read the documentation to understand silence mode. Generally, it should be disabled.
The above three option items will not appear if the file
build/module_info.json
exists. So please delete it if you want to reconfigure the module information.For example, set
Platform name
toESP32C2
,Module name
toESP32C2-4MB
, and disable silence mode as follows:$ ./build.py install Ready to install ESP-IDF prerequisites.. ... (more lines of install ESP-IDF prerequisites) Ready to install ESP-AT prerequisites.. ... (more lines of install ESP-IDF prerequisites) Platform name: 1. PLATFORM_ESP32 2. PLATFORM_ESP32C3 3. PLATFORM_ESP32C2 4. PLATFORM_ESP32C6 5. PLATFORM_ESP32S2 choose(range[1,5]):3 Module name: 1. ESP32C2-2MB (Firmware description: single Wi-Fi, 2MB, TX:7 RX:6) 2. ESP32C2-4MB (Firmware description: Wi-Fi + BluFi, 4MB, TX:7 RX:6) 3. ESP32C2-BLE-2MB (Firmware description: single BLE, 2MB, TX:7 RX:6) choose(range[1,3]):2 Enable silence mode to remove some logs and reduce the firmware size? 0. No 1. Yes choose(range[0,1]):0 Platform name:ESP32C2 Module name:ESP32C2-4MB Silence:0 Cloning into 'esp-idf'... ... (more lines of clone esp-idf) Ready to set up ESP-IDF tools.. ... (more lines of set up ESP-IDF tools) All done! You can now run: ./build.py build
Step 4. Connect Your Device
Connect your ESP32-C2 device to the PC with a USB cable to download firmware and print log. See Hardware Connection for more information. Note that you do not need to set up the “AT command/response” connection if you do not send AT commands and receive AT responses during the compiling process. You can change default port pins referring to How to Set AT Port Pins.
Step 5. Configure
Run the project configuration utility menuconfig
to configure.
Linux or macOS
./build.py menuconfig
Windows
python build.py menuconfig
If the previous steps have been done correctly, the following menu pops up:
You are using this menu to set up project-specific configuration, e.g. changing AT port pins, enabling Classic Bluetooth function, etc. If you made no changes, it will run with the default configuration.
Step 6. Build the Project
Build the project by running:
Linux or macOS
./build.py build
Windows
python build.py build
If Bluetooth feature is enabled, the firmware size will be much larger. Please make sure it does not exceed the OTA partition size.
After compiled, the combined factory bin will be created in build/factory
. See ESP-AT Firmware Differences for more information.
Step 7. Flash onto the Device
Flash the firmware that you just compiled onto your ESP32-C2 by running:
Linux or macOS
./build.py -p (PORT) flash
Windows
python build.py -p (PORT) flash
Note that you need to replace (PORT)
with your ESP32-C2’s serial port name. Or you can follow the printed instructions to download the bin files into flash. Note that you also need to replace the (PORT)
.
If the ESP-AT bin fails to boot and prints “ota data partition invalid”, you should run python build.py erase_flash
to erase the entire flash, and then reflash the AT firmware.
build.py Advanced Usage
The script build.py
is based on idf.py, which means that all idf.py <cmd>
features should be included in build.py <cmd>
. You can run the following command for more details.
Linux or macOS
./build.py --help
Windows
python build.py --help