How to Add Support for a Module

[中文]

The ESP-AT project supports multiple modules, and provides configuration for them in the factory_param_data.csv table and the files in the module_config folder. If you want to add support for an ESP32 module in your ESP-AT project, you need to modify those configuration files. The “ESP32 module” here means:

  • Modules that the ESP-AT project has not supported yet, including those of supported platform and not supported platform. However, adding support for the latter requires extra huge work, thus not recommended and not explained in this document.

  • Modules that the ESP-AT project supports, but you want to modify the default configuration.

This document will explain how to add new module support for a ESP32 chip/module that ESP-AT already supports in the ESP-AT project. The following example will enable the default FileSystem AT commands and add support for a new module.

Step 1: Configure the Factory Parameters for the New Module

Open your local factory_param_data.csv , insert a new row at the end, and set the relevant parameters as needed. In this example, we set platform to PLATFORM_ESP32 and module_name to ESP32-USER-DEFINED. The values for other parameters are shown in the table below (for parameter meanings, please refer to Factory Parameter Configuration).

  • platform: PLATFORM_ESP32

  • module_name: ESP32-USER-DEFINED

  • description:

  • version: 4

  • max_tx_power: 78

  • uart_port: 1

  • start_channel: 1

  • channel_num: 13

  • country_code: CN

  • uart_baudrate: -1

  • uart_tx_pin: -1

  • uart_rx_pin: -1

  • uart_cts_pin: -1

  • uart_rts_pin: -1

Step 2: Configure OTA for the Newly Added Module

Add customized module information in the s_module_info structure in at/src/at_default_config.c.

The s_module_info structure provides OTA upgrade verification token:

typedef struct {
    char* module_name;
    char* ota_token;
    char* ota_ssl_token;
} at_module_info_t;

If you do not want to use OTA features, member 2 ota_token and member 3 ota_ssl_token should be set to NULL. Member 1 module_name must correspond to the field module_name in the factory_param_data.csv file.

The modified s_module_info structure is as follows:

static const at_module_info_t s_module_info[] = {
#if defined(CONFIG_IDF_TARGET_ESP32)
  ...
#endif

#if defined(CONFIG_IDF_TARGET_ESP32C3)
  ...
#endif

#if defined(CONFIG_IDF_TARGET_ESP32C2)
  ...
#endif

#if defined(CONFIG_IDF_TARGET_ESP32C5)
  ...
#endif

#if defined(CONFIG_IDF_TARGET_ESP32C6)
  ...
#endif

#if defined(CONFIG_IDF_TARGET_ESP32)
  {"MY_MODULE",       CONFIG_ESP_AT_OTA_TOKEN_MY_MODULE,      CONFIG_ESP_AT_OTA_SSL_TOKEN_MY_MODULE },     // MY_MODULE
#endif
};

Macro CONFIG_ESP_AT_OTA_TOKEN_MY_MODULE and macro CONFIG_ESP_AT_OTA_SSL_TOKEN_MY_MODULE are defined in the header file at/private_include/at_ota_token.h.

#if defined(CONFIG_IDF_TARGET_ESP32)
...
#define CONFIG_ESP_AT_OTA_TOKEN_MY_MODULE       CONFIG_ESP_AT_OTA_TOKEN_DEFAULT

...
#define CONFIG_ESP_AT_OTA_SSL_TOKEN_MY_MODULE       CONFIG_ESP_AT_OTA_SSL_TOKEN_DEFAULT

Step 3: Add New Module Configuration

The ESP-AT project supports multiple platforms, each of which supports multiple module configurations and provides configuration files for each module configuration: factory_param_data.csv and module_config. The table below lists the names of the platforms (i.e., chip series) supported by the ESP-AT project, the names of the module configurations, and the locations of the corresponding configuration files for each module configuration.

Platform

Module Configuration Name

Corresponding Default Configuration File

ESP32

WROOM-32

ESP32

PICO-D4

ESP32

SOLO-1

ESP32

MINI-1

ESP32

WROVER-32

ESP32

ESP32-D2WD

ESP32

ESP32-SDIO

ESP32-C2

ESP32C2-2MB

ESP32-C2

ESP32C2-2MB-BLE

ESP32-C2

ESP32C2-4MB

ESP32-C3

MINI-1

ESP32-C3

ESP32C3-SPI

ESP32-C3

ESP32C3_RAINMAKER

ESP32-C5

ESP32C5-4MB

ESP32-C6

ESP32C6-4MB

ESP32-C61

ESP32C61-4MB

Note

  • When the silence mode in python build.py install is 0, the default sdkconfig corresponding to the module is sdkconfig.defaults.

  • When the silence mode in python build.py install is 1, the default sdkconfig corresponding to the module is sdkconfig_silence.defaults.

Firstly, enter module_config folder, and create a new folder to store all the configuration files for your module. Note that the folder name should be in lower case. Then, add the configuration files in the new folder: IDF_VERSION, patch, at_customize.csv, partitions_at.csv, sdkconfig.defaults, and sdkconfig_silence.defaults.

In this example, we copy the module_esp32_default folder as well as the files within it and rename it as module_esp32-user-defined. The copied IDF_VERSION, patch, at_customize.csv, and partitions_at.csv do not need any modification in our case. We only need to modify the sdkconfig.defaults and sdkconfig_silence.defaults:

  • Modify the two files to use the partition table in the module_esp32-user-defined folder as follows:

    CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="module_config/module_esp32-user-defined/partitions_at.csv"
CONFIG_PARTITION_TABLE_FILENAME="module_config/module_esp32-user-defined/partitions_at.csv"
CONFIG_AT_CUSTOMIZED_PARTITION_TABLE_FILE="module_config/module_esp32-user-defined/at_customize.csv"

After completing the above steps, you can recompile the ESP-AT project to generate the module firmware. In this example, when we compile the AT firmware locally during Step 3: Install Environment, we can select PLATFORM_ESP32 and ESP32-USER-DEFINED to generate the AT firmware.

Provide feedback about this document