如何生成出厂参数二进制文件
本文介绍了如何为模组生成一个自定义的 ESP-AT 出厂参数二进制文件 (factory_MODULE_NAME.bin)。例如,您可能想在 ESP-AT 固件中自定义国家代码、射频限制或 UART 管脚,则可以通过下面的两个表格定义此类参数。
下面介绍如何通过修改这两个表格来生成自定义的出厂参数二进制文件。
factory_param_type.csv
factory_param_type.csv 表列出了您可以定义的所有参数,以及每个参数的偏移量、类型和大小,它储存在 customized_partitions/raw_data/factory_param/factory_param_type.csv。
下表提供了每个参数的信息。
param_name |
说明 |
---|---|
description |
在编译 ESP-AT 工程时提示的模组附加信息。 |
magic_flag |
该值必须是 |
version |
供内部使用的出厂参数管理版本,当前版本为 |
reserved1 |
保留。 |
tx_max_power |
ESP32-C3 的 Wi-Fi 最大发射功率:[40,84],详情请见 ESP32-C3 发射功率 设置范围。 |
uart_port |
用于发送 AT 命令和接收 AT 响应的 UART 端口。 |
start_channel |
起始 Wi-Fi 信道。 |
channel_num |
Wi-Fi 的总信道数。 |
country_code |
国家代码。 |
uart_baudrate |
UART 的波特率。 |
uart_tx_pin |
UART tx 管脚。 |
uart_rx_pin |
UART rx 管脚。 |
uart_cts_pin |
UART cts 管脚,不使用时请置为 -1。 |
uart_rts_pin |
UART rts 管脚,不使用时请置为 -1。 |
tx_control_pin |
某些开发板上电时,该 tx 管脚需要与 MCU 分开。不使用时请置为 -1。 |
rx_control_pin |
某些开发板上电时,该 rx 管脚需要与 MCU 分开。不使用时请置为 -1。 |
reserved2 |
保留。 |
platform |
运行当前固件的平台(也称为芯片系列)。 |
module_name |
运行当前固件的模组。 |
factory_param_data.csv
factory_param_data.csv 表格保存了 factory_param_type.csv 中定义的所有参数的值,支持 ESP32-C3 系列的模组。您可通过修改表中的值来自定义出厂参数二进制文件。该表储存在 customized_partitions/raw_data/factory_param/factory_param_data.csv 中。
新增一个自定义模组
本节通过一个示例介绍如何在 factory_param_data.csv 中添加一个自定义模组,并为其生成出厂参数二进制文件。假设您想为一个名为 MY_MODULE
的 ESP32-C3 模组生成出厂参数二进制文件,其国家代码为 JP,Wi-Fi 信道为 1 至 14,其它参数与 PLATFORM_ESP32C3
的 MINI-1
模组相同,可按照以下步骤进行操作。
修改 factory_param_data.csv
在 factory_param_data.csv 表中设置 MY_MODULE
的所有参数值。
首先,在表格底部插入一行,然后输入以下参数值。
param_name: value
platform: PLATFORM_ESP32C3
module_name:
MY_MODULE
description:
MY_DESCRIPTION
magic_flag: 0xfcfc
version: 3
reserved1: 0
tx_max_power: 78
uart_port: 1
start_channel:
1
channel_num:
14
country_code:
JP
uart_baudrate: 115200
uart_tx_pin: 17
uart_rx_pin: 16
uart_cts_pin: 15
uart_rts_pin: 14
tx_control_pin: -1
rx_control_pin: -1
修改后的 factory_param_data.csv 表格如下所示。
platform,module_name,description,magic_flag,version,reserved1,tx_max_power,uart_port,start_channel,channel_num,country_code,uart_baudrate,uart_tx_pin,uart_rx_pin,uart_cts_pin,uart_rts_pin,tx_control_pin,rx_control_pin
PLATFORM_ESP32,WROOM-32,,0xfcfc,3,0,78,1,1,13,CN,115200,17,16,15,14,-1,-1
...
PLATFORM_ESP32C3,MY_MODULE,MY_DESCRIPTION,0xfcfc,3,0,78,1,1,14,JP,115200,17,16,15,14,-1,-1
修改 esp_at_module_info
结构体
在 at/src/at_default_config.c 中的 esp_at_module_info
结构体中添加自定义模组的信息。
esp_at_module_info
结构体提供 OTA
升级验证 token
:
typedef struct {
char* module_name;
char* ota_token;
char* ota_ssl_token;
} esp_at_module_info_t;
若不想使用 OTA
功能,那么第二个参数 ota_token
和第三个参数 ota_ssl_token
应该设置为 NULL
,第一个参数 module_name
必须与 factory_param_data.csv 文件中的 module_name
一致。
下面是修改后的 esp_at_module_info
结构体。
static const esp_at_module_info_t esp_at_module_info[] = {
#if defined(CONFIG_IDF_TARGET_ESP32)
{"WROOM-32", CONFIG_ESP_AT_OTA_TOKEN_WROOM32, CONFIG_ESP_AT_OTA_SSL_TOKEN_WROOM32 }, // 默认:ESP32-WROOM-32
{"WROOM-32", CONFIG_ESP_AT_OTA_TOKEN_WROOM32, CONFIG_ESP_AT_OTA_SSL_TOKEN_WROOM32 }, // ESP32-WROOM-32
{"WROVER-32", CONFIG_ESP_AT_OTA_TOKEN_WROVER32, CONFIG_ESP_AT_OTA_SSL_TOKEN_WROVER32 }, // ESP32-WROVER
{"PICO-D4", CONFIG_ESP_AT_OTA_TOKEN_ESP32_PICO_D4, CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32_PICO_D4}, // ESP32-PICO-D4
{"SOLO-1", CONFIG_ESP_AT_OTA_TOKEN_ESP32_SOLO_1, CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32_SOLO_1 }, // ESP32-SOLO-1
{"MINI-1", CONFIG_ESP_AT_OTA_TOKEN_ESP32_MINI_1, CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32_MINI_1 }, // ESP32-MINI-1
{"ESP32-D2WD", NULL, NULL }, // ESP32-D2WD
{"ESP32_QCLOUD", CONFIG_ESP_AT_OTA_TOKEN_ESP32_QCLOUD, CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32_QCLOUD }, // ESP32-QCLOUD
{"MY_MODULE", CONFIG_ESP_AT_OTA_TOKEN_MY_MODULE, CONFIG_ESP_AT_OTA_SSL_TOKEN_MY_MODULE }, // MY_MODULE
#endif
#if defined(CONFIG_IDF_TARGET_ESP32C3)
{"MINI-1", CONFIG_ESP_AT_OTA_TOKEN_ESP32C3_MINI, CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32C3_MINI },
{"ESP32C3_QCLOUD", CONFIG_ESP_AT_OTA_TOKEN_ESP32C3_MINI_QCLOUD, CONFIG_ESP_AT_OTA_SSL_TOKEN_ESP32C3_MINI_QCLOUD },
#endif
};
宏 CONFIG_ESP_AT_OTA_TOKEN_MY_MODULE
和宏 CONFIG_ESP_AT_OTA_SSL_TOKEN_MY_MODULE
定义在头文件 at/private_include/at_ota_token.h 中。
#if defined(CONFIG_IDF_TARGET_ESP32C3)
...
#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
重新编译工程并选择自定义模组
在添加自定义模组信息后,根据 编译 ESP-AT 工程 重新编译整个工程,在配置工程时选择自定义模组。
Platform name:
1. PLATFORM_ESP32
2. PLATFORM_ESP32C3
choose(range[1,2]):1
Module name:
1. WROOM-32
2. WROVER-32
3. PICO-D4
4. SOLO-1
5. MINI-1 (description: ESP32-U4WDH chip inside)
6. ESP32-D2WD (description: 2MB flash, No OTA)
7. ESP32_QCLOUD (description: QCLOUD TX:17 RX:16)
8. MY_MODULE (description: MY_DESCRIPTION)
choose(range[1,8]):8
编译完成后可在 esp-at/build/customized_partitions
文件夹下找到生成的出厂参数二进制文件。
新增一个自定义参数
本节通过一个示例介绍如何新增一个自定义参数。假设您想为 MY_MODULE
添加参数 date
,并将其设置为 20210603
,可按照以下步骤进行操作。
修改 factory_param_type.csv
在 factory_param_type.csv 中定义参数 date
。
首先,在表格的底部插入一行,然后设置参数的名称 (param_name)、偏移量 (offset)、类型 (type) 和大小 (size)。
param_name |
offset |
type |
size |
---|---|---|---|
description |
-1 |
String |
0 |
… |
… |
… |
… |
|
|
|
|
修改 factory_param_data.csv
在 factory_param_data.csv 最后一列的后面插入一列,并命名为 date
,然后将 MY_MODULE
对应的值设置为 20210603
。
以下是修改后的 CSV 表格。
platform,module_name,description,magic_flag,version,reserved1,tx_max_power,uart_port,start_channel,channel_num,country_code,uart_baudrate,uart_tx_pin,uart_rx_pin,uart_cts_pin,uart_rts_pin,tx_control_pin,rx_control_pin,date
PLATFORM_ESP32,WROOM-32,,0xfcfc,3,0,78,1,1,13,CN,115200,17,16,15,14,-1,-1
...
PLATFORM_ESP32C3,MY_MODULE,MY_DESCRIPTION,0xfcfc,3,0,78,1,1,14,JP,115200,17,16,15,14,-1,-1,20210603
处理自定义参数
您可以自定义函数来处理自定义的参数 date
,以下只是简单输出参数值。
static void esp_at_factory_parameter_date_init(void)
{
const esp_partition_t * partition = esp_at_custom_partition_find(0x40, 0xff, "factory_param");
char* data = NULL;
char* str_date = NULL;
if (!partition) {
printf("factory_parameter partition missed\r\n");
return;
}
data = (char*)malloc(ESP_AT_FACTORY_PARAMETER_SIZE); // 说明
assert(data != NULL);
if(esp_partition_read(partition, 0, data, ESP_AT_FACTORY_PARAMETER_SIZE) != ESP_OK){
free(data);
return;
}
if ((data[0] != 0xFC) || (data[1] != 0xFC)) { // 检查 magic flag 是否为 0xfc 0xfc
return;
}
// 示例代码
// 可自定义如何处理参数 date
// 此处仅简单打印 date 参数值
str_date = &data[88]; // date 字段偏移地址
printf("date is %s\r\n", str_date);
free(data);
return;
}
修改现有模组的出厂参数数据
假设您需要修改 factory_param_data.csv 中现有的某个模组的出厂参数数据,可采用下面任意一种方法。
重新编译整个工程
打开 factory_param_data.csv 并根据需要修改参数。
重新编译 ESP-AT 工程(参考 编译 ESP-AT 工程),出厂参数二进制文件会在 esp-at/build/customized_partitions
文件夹生成。
只编译出厂参数二进制文件
首先,克隆整个 ESP-AT 工程。
然后,前往 ESP-AT 工程的根目录,输入以下命令,并替换一些参数。
python tools/factory_param_generate.py --platform PLATFORM --module MODULE --define_file DEFINE_FILE --module_file MODULE_FILE --bin_name BIN_NAME --log_file LOG_FILE
PLATFORM
替换为模组的平台,必须与 factory_param_data.csv 中platform
的值一致。MODULE
替换为模组的名称,必须与 factory_param_data.csv 中module_name
的值一致。DEFINE_FILE
替换为 factory_param_type.csv 的相对路径。MODULE_FILE
替换为 factory_param_data.csv 的相对路径。BIN_NAME
替换为出厂参数二进制文件名。LOG_FILE
储存模组名称的文件名。
以下为 MY_MODULE
的示例代码。
python tools/factory_param_generate.py --platform PLATFORM_ESP32C3 --module MY_MODULE --define_file components/customized_partitions/raw_data/factory_param/factory_param_type.csv --module_file components/customized_partitions/raw_data/factory_param/factory_param_data.csv --bin_name ./factory_param.bin --log_file ./factory_parameter.log
执行上述命令后,将在当前目录下生成以下三个文件。
factory_param.bin
factory_parameter.log
factory_param_MY_MODULE.bin
将新生成的 factory_param_MY_MODULE.bin
下载到 flash 中,可使用 ESP-AT 提供的 esptool.py 进行下载,在 ESP-AT 项目的根目录下执行以下命令,并替换一些参数。
python esp-idf/components/esptool_py/esptool/esptool.py -p PORT -b BAUD --before default_reset --after hard_reset --chip auto write_flash --flash_mode dio --flash_size detect --flash_freq 40m ADDRESS FILEDIRECTORY
PORT
替换为端口名称。BAUD
替换为波特率。ADDRESS
替换为 flash 中开始的地址。ESP-AT 对ADDRESS
参数有严格的要求,不同固件的出厂参数二进制文件的地址不同,请参考下面的表格。出厂参数二进制文件下载地址 平台
固件
地址
PLATFORM_ESP32C3
MINI-1 固件
0x31000
PLATFORM_ESP32C3
QCLOUD 固件
0x30000
FILEDIRECTORY
替换为出厂参数二进制文件的相对路径。
下面是将生成的出厂参数二进制文件烧录到 MY_MODULE
的命令示例。
python esp-idf/components/esptool_py/esptool/esptool.py -p /dev/ttyUSB0 -b 921600 --before default_reset --after hard_reset --chip auto write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x31000 ./factory_param_MY_MODULE.bin
直接修改出厂参数二进制文件
用二进制工具打开出厂参数二进制文件,根据 factory_param_type.csv 中的参数偏移量,直接在相应位置进行修改。
将修改后的 factory_param.bin 烧录至 flash(详情请见 下载指导)。