Compile ESP-AT Project

[中文]

This document details how to build your own ESP-AT project and flash the generated firmware into your ESP devices, including ESP32, and 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.

The structure of this document is as follows:

• Overview: Overview of the steps to build an ESP-AT project.

• ESP32 and ESP32-C3 Series: Details steps to build a project for ESP32, and ESP32-C3 series.

Overview

Before compiling an ESP-AT project, you need first get started with ESP-IDF and set up the environment for ESP-IDF, because ESP-AT is based on ESP-IDF.

After the environment is ready, install the tools and ESP-AT SDK. Then, connect your ESP device to PC. Use ./build.py menuconfig to set up some configuration for the project. Build the project and flash the generated bin files onto your ESP device.

Note

Please pay attention to possible conflicts of pins. If choosing AT through HSPI, you can get the information of the HSPI pin by ./build.py menuconfig –> Component config –> AT –> AT hspi settings.

ESP32 and ESP32-C3 Series

This section describes how to compile an ESP-AT project for ESP32 and ESP32-C3 series.

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, and the supported version varies from series to series:

ESP-IDF Versions for Different Series

Project	IDF Version	IDF Documentation Version
ESP32 ESP-AT	release/v4.2	ESP-IDF Get Started Guide v4.2
ESP32-C3 ESP-AT	release/v4.3	ESP-IDF Get Started Guide v4.3

First, set up the development environment for ESP-IDF according to Step 1 to 4 of ESP-IDF Get Started Guide (click the corresponding link in the table above to navigate to the documentation).

Then, start a simple project of hello_world according to Step 5 to 10 of ESP-IDF Get Started Guide to make sure your environment works and familiarize yourself with the process of starting a new project based on ESP-IDF. It is not a must, but you are strongly recommended to do so.

After finishing all the ten steps (if not, at least the first four steps), you can move onto the following steps that are ESP-AT specific.

Note

Please do not set IDF_PATH during the process, otherwise, you would encounter some unexpected issues when compiling ESP-AT projects later.

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 series of modules, it is recommended that you run ESP-IDF 4.2 CMD as an administrator first.

  • 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.

Connect Your Device

Connect your device to the PC with a USB cable to download firmware and log output. 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.

Configure

In this step, you will clone the esp-idf folder into the esp-at folder, set up the development environment in the newly cloned folder, and configure your project.

1. Navigate to ~/esp/esp-at directory.

2. Run the project configuration utility menuconfig to configure.

./build.py menuconfig

3. Select the following configuration options for your ESP device if it is your first time.

• Select the Platform name for your ESP device. For example, select PLATFORM_ESP32 for ESP32 series of products, PLATFORM_ESP32C3 for ESP32-C3 series of products. Platform name is defined in factory_param_data.csv .

• Select the Module name for your ESP device. For example, select WROOM-32 for the ESP32-WROOM-32D 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.

4. Now, the esp-idf folder is created in esp-at folder. This esp-idf is different from that in Get Started with ESP-IDF.

If you encounter any of the cases below, please proceed with the next step to set up the develop environment in the esp-at/esp-idf.

• The terminal prompt an error message like the following:

  The following Python requirements are not satisfied:
  ...
  Please follow the instructions found in the "Set up the tools" section of ESP-IDF Get Started Guide.
  

• If you have compiled an ESP-AT project for an ESP series before and want to switch to another series, you must run rm -rf esp-idf to remove the old esp-idf and then proceed with the next step.

• Your esp-idf is upgraded.

5. Set up the development environment in the esp-at/esp-idf.

• Set up the tools in the folder if it is the first time you compile the ESP-AT project. See Step 3 of ESP-IDF Get Started Guide.

• Set up environment variables in the folder every time you compile an ESP-AT project. See Step 4 of ESP-IDF Get Started Guide.

• Install pyyaml and xlrd packages with pip in the folder if you have not done it.

  python -m pip install pyyaml xlrd
  

If the previous steps have been done correctly, the following menu appears after you run ./build.py menuconfig:

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.

Build the Project

Build the project by running:

./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.

Flash onto the Device

Flash the firmware that you just compiled onto your ESP device by running:

./build.py -p (PORT) flash

• Note that you need to replace PORT with your ESP device’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 ./build.py erase_flash to erase the entire flash, and then re-flash the AT firmware.

Provide feedback about this document