esp-idf/tools/mass_mfg/docs/README_CN.rst

257 wiersze
11 KiB
ReStructuredText
Czysty Wina Historia

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

量产程序
=====================
:link_to_translation:`en:[English]`
介绍
------------
这一程序主要用于量产时为每一设备创建工厂 NVS非易失性存储器分区映像。NVS 分区映像由 CSV逗号分隔值文件生成文件中包含了用户提供的配置项及配置值。
注意,该程序仅创建用于量产的二进制映像,您需要使用以下工具将映像烧录到设备上:
- esptool.py
- Flash 下载工具(仅适用于 Windows
- 直接烧录程序
准备工作
-------------
**该程序需要用到分区公用程序。**
* 操作系统要求:
- Linux、MacOS 或 Windows标准版
* 安装依赖包:
- Python最低版本要求为 2.7。下载地址https://www.python.org/downloads/。
.. note::
使用该程序之前,请确保:
- Python 路径已添加到 PATH 环境变量中;
- 已经安装 `requirement.txt` 中的软件包,`requirement.txt` 在 esp-idf 根目录下。
具体流程
-----------
.. blockdiag::
blockdiag {
A [label = "CSV 配置文件"];
B [label = "主 CSV 文件"];
C [label = "二进制 bin 文件", stacked];
A -- B -> C
}
CSV 配置文件
----------------------
CSV 配置文件中包含设备待烧录的配置信息,定义了待烧录的配置项。例如定义 ``firmware_key`` (``key``) 的 ``type````data````encoding````hex2bin``
配置文件中数据格式如下(`REPEAT` 标签可选)::
name1,namespace, <-- 第一行为 "namespace" 条目
key1,type1,encoding1
key2,type2,encoding2,REPEAT
name2,namespace,
key3,type3,encoding3
key4,type4,encoding4
.. note:: 文件第一行应始终为 ``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
.. note::
请确保:
- 逗号 ',' 前后无空格;
- CSV 文件每行末尾无空格。
主 CSV 文件
---------------------
主 CSV 文件中包含设备待烧录的详细信息,文件中每行均对应一个设备实体。主 CSV 文件中的 ``key`` 应首先在 CSV 配置文件中定义。
主 CSV 文件的数据格式如下::
key1,key2,key3,.....
value1,value2,value3,.... <-- 对应一个设备实体
value4,value5,value6,.... <-- 对应一个设备实体
value7,value8,value9,.... <-- 对应一个设备实体
.. note:: 文件中键 (``key``) 名应始终置于文件首行。从配置文件中获取的键,在此文件中的排列顺序应与其在配置文件中的排列顺序相同。主 CSV 文件同时可以包含其它列(键),这些列将被视为元数据,而不会编译进最终二进制文件。
每行应包含相应键的键值 (``value``) ,并用逗号隔开。如果某键带有 ``REPEAT`` 标签,则仅需在第二行(即第一个条目)输入对应的值,后面其他行为空。
参数描述如下:
``value``
Data value
``value`` 是与键对应的键值。
主 CSV 文件示例如下::
id,firmware_key,serial_no,device_no
1,1a2b3c4d5e6faabb,A1,101 <-- 对应一个设备实体(在 CSV 配置文件中标记为 `REPEAT` 的键,除第一个条目外,其他均为空)
2,1a2b3c4d5e6fccdd,,102 <-- 对应一个设备实体
3,1a2b3c4d5e6feeff,,103 <-- 对应一个设备实体
.. note:: 如果出现 `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.csmples/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
.. note:: 创建的加密密钥格式为 ``<outdir>/keys/keys-<prefix>-<fileid>.bin``
.. note:: 加密密钥存储于新建文件的 ``keys/`` 目录下,与 NVS 密钥分区结构兼容。更多信息请参考 :ref:`nvs_key_partition`
- 提供加密密钥用作二进制输入文件来进行加密::
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
.. note:: 创建的加密密钥格式为 ``<outdir>/keys/keys-<timestamp>.bin``。时间戳格式为:``%m-%d_%H-%M``
.. note:: 如需自定义目标文件名,请使用 --keyfile 参数。
生成的加密密钥二进制文件还可以用于为每个设备的工厂映像加密。
``fileid`` 参数的默认值为 1、2、3...,与主 CSV 文件中的行一一对应,内含设备配置值。
运行量产程序时,将在指定的 ``outdir`` 目录下创建以下文件夹:
- ``bin/`` 存储生成的二进制文件
- ``csv/`` 存储生成的中间 CSV 文件
- ``keys/`` 存储加密密钥(创建工厂加密映像时会用到)