Compile ESP-AT Project
This document details how to build your own ESP-AT project and flash the generated firmware into your ESP32-C3. It comes in handy when the official released fimware cannot meet your needs, for example, to customize the AT port pins, Bluetooth LE services, and partitions, and so on.
Detailed Steps
Please follow the detailed steps below to set up your environment and build the project.
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 v4.3 Get Started guide, configure, build, flash onto the ESP32-C3 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-C3 series of modules, it is recommended that you run ESP-IDF 4.3 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://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
Note
Please install the python version between python 3.6
and python 3.8
(inclusive) first, and set it to the current python version.
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-C3 if it is your first time.
Select the
Platform name
for your ESP32-C3. For example, selectPLATFORM_ESP32C3
for ESP32-C3 series of products.Platform name
is defined in factory_param_data.csv .Select the
Module name
for your ESP32-C3. For example, selectMINI-1
for the ESP32-C3-MINI-1 module.Module name
is defined in factory_param_data.csv .Enable or disable
silence mode
. If enabled, it will remove some logs and reduce the firmware size. 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.
Step 4. Connect Your Device
Connect your ESP32-C3 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:
![Project configuration - Home window](../_images/project-configuration.png)
Project configuration - Home window
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-C3 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-C3’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.