量产程序

[English]

介绍

这一程序主要用于量产时为每一设备创建工厂 NVS（非易失性存储器）分区映像。NVS 分区映像由 CSV（逗号分隔值）文件生成，文件中包含了用户提供的配置项及配置值。

注意，该程序仅创建用于量产的二进制映像，您需要使用以下工具将映像烧录到设备上：

  • esptool.py。

  • Flash 下载工具 （仅适用于 Windows）。下载后解压，然后按照 doc 文件夹中的说明操作。

  • 使用定制的生产工具直接烧录程序。

准备工作

该程序需要用到分区公用程序。

  • 操作系统要求：

    • Linux、macOS 或 Windows（标准版）

  • 安装依赖包：

注解

使用该程序之前，请确保：

  • Python 路径已添加到 PATH 环境变量中；

  • 已经安装 requirement.txt 中的软件包，requirement.txt 在 esp-idf 根目录下。

具体流程

CSV 配置文件

CSV 配置文件中包含设备待烧录的配置信息，定义了待烧录的配置项。

配置文件中数据格式如下（REPEAT 标签可选）:

name1,namespace,    <-- 第一行为 "namespace" 条目
key1,type1,encoding1
key2,type2,encoding2,REPEAT
name2,namespace,
key3,type3,encoding3
key4,type4,encoding4

注解

文件第一行应始终为 namespace 条目。

每行应包含三个参数：key、type 和 encoding，并以逗号分隔。如果有 REPEAT 标签，则主 CSV 文件中所有设备此键值均相同。

有关各个参数的详细说明，请参阅 NVS 分区生成程序的 README 文件。

CSV 配置文件示例如下:

app,namespace,
firmware_key,data,hex2bin
serial_no,data,string,REPEAT <-- "serial_no" 被标记为 "REPEAT"
device_no,data,i32

注解

请确保：

  • 逗号 ‘,’ 前后无空格；

  • CSV 文件每行末尾无空格。

主 CSV 文件

主 CSV 文件中包含设备待烧录的详细信息，文件中每行均对应一个设备实体。

主 CSV 文件的数据格式如下:

key1,key2,key3,.....
value1,value2,value3,....

注解

文件中键 (key) 名应始终置于文件首行。从配置文件中获取的键，在此文件中的排列顺序应与其在配置文件中的排列顺序相同。主 CSV 文件同时可以包含其它列（键），这些列将被视为元数据，而不会编译进最终二进制文件。

每行应包含相应键的键值 (value) ，并用逗号隔开。如果某键带有 REPEAT 标签，则仅需在第二行（即第一个条目）输入对应的值，后面其他行为空。

参数描述如下：

value

Data value

value 是与键对应的键值。

主 CSV 文件示例如下:

id,firmware_key,serial_no,device_no
1,1a2b3c4d5e6faabb,A1,101
2,1a2b3c4d5e6fccdd,,102
3,1a2b3c4d5e6feeff,,103

注解

如果出现 REPEAT 标签，则会在相同目录下生成一个新的主 CSV 文件用作主输入文件，并在每行为带有 REPEAT 标签的键插入键值。

量产程序还会创建中间 CSV 文件，NVS 分区程序将使用此 CSV 文件作为输入，然后生成二进制文件。

中间 CSV 文件的格式如下:

key,type,encoding,value
key,namespace, ,
key1,type1,encoding1,value1
key2,type2,encoding2,value2

此步骤将为每一设备生成一个中间 CSV 文件。

运行量产程序

使用方法:

python mfg_gen.py [-h] {generate,generate-key} ...

可选参数：

序号

参数

描述

1

-h, –help

显示帮助信息并退出

命令：

运行 mfg_gen.py {command} -h 查看更多帮助信息

序号

参数

描述

1

generate

生成 NVS 分区

2

generate-key

生成加密密钥

为每个设备生成工厂映像（默认）

使用方法:

python mfg_gen.py generate [-h] [--fileid FILEID] [--version {1,2}] [--keygen]
                                [--keyfile KEYFILE] [--inputkey INPUTKEY]
                                [--outdir OUTDIR]
                                conf values prefix size

位置参数：

参数

描述

conf

待解析的 CSV 配置文件路径

values

待解析的主 CSV 文件路径

prefix

每个输出文件名前缀的唯一名称

size

NVS 分区大小（以字节为单位，且为 4096 的整数倍）

可选参数：

参数

描述

-h, –help

显示帮助信息并退出

–fileid FILEID

每个文件名后缀的唯一文件标识符（主 CSV 文件中的任意键），默认为数值 1、2、3…

–version {1,2}

  • 设置多页 Blob 版本。

  • 版本 1 - 禁用多页 Blob；

  • 版本 2 - 启用多页 Blob；

  • 默认版本：版本 2

–keygen

生成 NVS 分区加密密钥

–inputkey INPUTKEY

内含 NVS 分区加密密钥的文件

–outdir OUTDIR

输出目录，用于存储创建的文件（默认当前目录）

请运行以下命令为每个设备生成工厂映像，量产程序同时提供了一个 CSV 示例文件:

python mfg_gen.py generate samples/sample_config.csv samples/sample_values_singlepage_blob.csv Sample 0x3000

主 CSV 文件应在 file 类型下设置一个相对路径，指向运行该程序的当前目录。

为每个设备生成工厂加密映像

运行以下命令为每一设备生成工厂加密映像，量产程序同时提供了一个 CSV 示例文件。

  • 通过量产程序生成加密密钥来进行加密:

    python mfg_gen.py generate samples/sample_config.csv samples/sample_values_singlepage_blob.csv Sample 0x3000 --keygen

注解

创建的加密密钥格式为 <outdir>/keys/keys-<prefix>-<fileid>.bin。

注解

加密密钥存储于新建文件的 keys/ 目录下，与 NVS 密钥分区结构兼容。更多信息请参考 NVS 密钥分区。

  • 提供加密密钥用作二进制输入文件来进行加密:

    python mfg_gen.py generate samples/sample_config.csv samples/sample_values_singlepage_blob.csv Sample 0x3000 --inputkey keys/sample_keys.bin

仅生成加密密钥

使用方法:

python mfg_gen.py generate-key [-h] [--keyfile KEYFILE] [--outdir OUTDIR]

可选参数：

参数

描述

-h, –help

显示帮助信息并退出

–keyfile KEYFILE

加密密钥文件的输出路径

–outdir OUTDIR

输出目录，用于存储创建的文件（默认当前目录）

运行以下命令仅生成加密密钥:

python mfg_gen.py generate-key

注解

创建的加密密钥格式为 <outdir>/keys/keys-<timestamp>.bin。时间戳格式为：%m-%d_%H-%M。

注解

如需自定义目标文件名，请使用 –keyfile 参数。

生成的加密密钥二进制文件还可以用于为每个设备的工厂映像加密。

fileid 参数的默认值为 1、2、3…，与主 CSV 文件中的行一一对应，内含设备配置值。

运行量产程序时，将在指定的 outdir 目录下创建以下文件夹：

  • bin/ 存储生成的二进制文件

  • csv/ 存储生成的中间 CSV 文件

  • keys/ 存储加密密钥（创建工厂加密映像时会用到）

提供有关此文档的反馈