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

量产程序
=====================

: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/`` 存储加密密钥（创建工厂加密映像时会用到）