--- /dev/null
+NVS 分区生成程序
+===============================
+
+:link_to_translation:`en:[English]`
+
+介绍
+------------
+
+NVS 分区生成程序 (:component_file:`nvs_flash/nvs_partition_generator/nvs_partition_gen.py`) 根据 CSV 文件中的键值对生成二进制文件。该二进制文件与 :doc:`非易失性存储器 (NVS) </api-reference/storage/nvs_flash>` 中定义的 NVS 结构兼容。NVS 分区生成程序适合用于生成二进制数据（Blob），其中包括设备生产时可从外部烧录的 ODM/OEM 数据。这也使得生产制造商在使用同一个固件的基础上，通过自定义参数，如序列号等，为每个设备生成不同配置。
+
+准备工作
+-------------
+
+在加密模式下使用该程序，需安装下列软件包：
+ - cryptography package
+
+根目录下的 `requirements.txt` 包含必需 python 包，请预先安装。
+
+
+CSV 文件格式
+---------------
+
+.csv 文件每行需包含四个参数，以逗号隔开。具体参数描述见下表：
+
++------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
+| 序号 | 参数 | 描述 | 说明 |
++======+==========+==============================================================+=================================================================+
+| 1 | Key | 主键，应用程序可通过查询此键来获取数据。 | |
++------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
+| 2 | Type | 支持 ``file``、``data`` 和 ``namespace``。 | |
++------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
+| 3 | Encoding | 支持 ``u8``、``i8``、``u16``、``u32``、 | ``file`` |
+| | | ``i32``、``string``、``hex2bin``、``base64`` 和 ``binary``。 | 类型当前仅支持 |
+| | | 决定二进制 ``bin`` 文件中 value 被编码成的类型。 | ``hex2bin``、``base64``、 |
+| | | ``string`` 和 ``binary`` 编码的区别在于， | ``string`` 和 ``binary`` 编码。 |
+| | | ``string`` 数据以 NULL 字符结尾，``binary`` 数据则不是。 | |
++------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
+| 4 | Value | Data value | ``namespace`` 字段的 ``encoding`` 和 ``value`` 应为空。 |
+| | | | ``namespace`` 的 ``encoding`` 和 ``value`` 为固定值，不可设置。 |
+| | | | 这些单元格中的所有值都会被忽视。 |
++------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
+
+.. note:: CSV 文件的第一行应为列标题，不可设置。
+
+此类 CSV 文件的 Dump 示例如下::
+
+ key,type,encoding,value <-- 列标题
+ namespace_name,namespace,, <-- 第一个条目为 "namespace"
+ key1,data,u8,1
+ key2,file,string,/path/to/file
+
+
+.. note::
+
+ 请确保：
+ - 逗号 ',' 前后无空格；
+ - CSV 文件每行末尾无空格。
+
+NVS 条目和命名空间 (namespace)
+-----------------------------------
+
+如 CSV 文件中出现命名空间条目，后续条目均会被视为该命名空间的一部分，直至找到下一个命名空间条目。找到新命名空间条目后，后续所有条目都会被视为新命名空间的一部分。
+
+.. note:: CSV 文件中第一个条目应始终为 ``namespace``。
+
+
+支持多页 Blob
+----------------------
+
+默认情况下，二进制 Blob 可跨多页，格式参考 :ref:`structure_of_entry` 章节。如需使用旧版格式，可在程序中禁用该功能。
+
+
+支持加密
+-------------------
+
+NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。更多信息详见 :ref:`nvs_encryption`。
+
+支持解密
+-------------------
+如果 NVS 二进制文件采用了 AES-XTS 加密，该程序还可对此类文件进行解密，更多信息详见 :ref:`nvs_encryption`。
+
+运行程序
+-------------------
+
+**使用方法**::
+
+ python nvs_partition_gen.py [-h] {generate,generate-key,encrypt,decrypt} ...
+
+**可选参数**：
+
++------+------------+----------------------+
+| 序号 | 参数 | 描述 |
++------+------------+----------------------+
+| 1 | -h, --help | 显示帮助信息并退出 |
++------+------------+----------------------+
+
+**命令**::
+
+ 运行 nvs_partition_gen.py {command} -h 查看更多帮助信息
+
++------+--------------+---------------+
+| 序号 | 参数 | 描述 |
++------+--------------+---------------+
+| 1 | generate | 生成 NVS 分区 |
++------+--------------+---------------+
+| 2 | generate-key | 生成加密密钥 |
++------+--------------+---------------+
+| 3 | encrypt | 加密 NVS 分区 |
++------+--------------+---------------+
+| 4 | decrypt | 解密 NVS 分区 |
++------+--------------+---------------+
+
+
+生成 NVS 分区（默认模式）
+----------------------------------
+
+**使用方法**::
+
+ python nvs_partition_gen.py generate [-h] [--version {1,2}] [--outdir OUTDIR]
+ input output size
+
+**位置参数**：
+
++--------+--------------------------------------------------+
+| 参数 | 描述 |
++--------+--------------------------------------------------+
+| input | 待解析的 CSV 文件路径 |
++--------+--------------------------------------------------+
+| output | NVS 二进制文件的输出路径 |
++--------+--------------------------------------------------+
+| size | NVS 分区大小（以字节为单位，且为 4096 的整数倍） |
++--------+--------------------------------------------------+
+
+**可选参数**：
+
++-----------------+------------------------------------------------+
+| 参数 | 描述 |
++-----------------+------------------------------------------------+
+| -h, --help | 显示帮助信息并退出 |
++-----------------+------------------------------------------------+
+| --version {1,2} | - 设置多页 Blob 版本。 |
+| | - 版本 1：禁用多页 Blob； |
+| | - 版本 2：启用多页 Blob； |
+| | - 默认版本：版本 2。 |
++-----------------+------------------------------------------------+
+| --outdir OUTDIR | 输出目录，用于存储创建的文件。（默认当前目录） |
++-----------------+------------------------------------------------+
+
+运行如下命令创建 NVS 分区，该程序同时会提供 CSV 示例文件::
+
+ python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000
+
+仅生成加密密钥
+-----------------------
+
+**使用方法**::
+
+ python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE]
+ [--outdir OUTDIR]
+
+**可选参数**：
+
++-------------------+------------------------------------------------+
+| 参数 | 描述 |
++-------------------+------------------------------------------------+
+| -h, --help | 显示帮助信息并退出 |
++-------------------+------------------------------------------------+
+| --keyfile KEYFILE | 加密密钥文件的输出路径 |
++-------------------+------------------------------------------------+
+| --outdir OUTDIR | 输出目录，用于存储创建的文件。（默认当前目录） |
++-------------------+------------------------------------------------+
+
+运行以下命令仅生成加密密钥::
+
+ python nvs_partition_gen.py generate-key
+
+生成 NVS 加密分区
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**使用方法**::
+
+ python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen]
+ [--keyfile KEYFILE] [--inputkey INPUTKEY]
+ [--outdir OUTDIR]
+ input output size
+
+**位置参数**：
+
++--------+--------------------------------------+
+| 参数 | 描述 |
++--------+--------------------------------------+
+| input | 待解析 CSV 文件的路径 |
++--------+--------------------------------------+
+| output | NVS 二进制文件的输出路径 |
++--------+--------------------------------------+
+| size | NVS 分区大小 |
+| | （以字节为单位，且为 4096 的整数倍） |
++--------+--------------------------------------+
+
+**可选参数**：
+
++---------------------+------------------------------+
+| 参数 | 描述 |
++---------------------+------------------------------+
+| -h, --help | 显示帮助信息并退出 |
++---------------------+------------------------------+
+| --version {1,2} | - 设置多页 Blob 版本。 |
+| | - 版本 1：禁用多页 Blob； |
+| | - 版本 2：启用多页 Blob； |
+| | - 默认版本：版本 2。 |
++---------------------+------------------------------+
+| --keygen | 生成 NVS 分区加密密钥 |
++---------------------+------------------------------+
+| --keyfile KEYFILE | 密钥文件的输出路径 |
++---------------------+------------------------------+
+| --inputkey INPUTKEY | 内含 NVS 分区加密密钥的文件 |
++---------------------+------------------------------+
+| --outdir OUTDIR | 输出目录，用于存储创建的文件 |
+| | （默认当前目录） |
++---------------------+------------------------------+
+
+运行以下命令加密 NVS 分区，该程序同时会提供一个 CSV 示例文件。
+
+- 通过 NVS 分区生成程序生成加密密钥来加密::
+
+ python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen
+
+.. note:: 创建的加密密钥格式为 ``<outdir>/keys/keys-<timestamp>.bin``。
+
+- 通过 NVS 分区生成程序生成加密密钥，并将密钥存储于自定义的文件中::
+
+ python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen --keyfile sample_keys.bin
+
+.. note:: 创建的加密密钥格式为 ``<outdir>/keys/keys-<timestamp>.bin``。
+.. note:: 加密密钥存储于新建文件的 ``keys/`` 目录下，与 NVS 密钥分区结构兼容。更多信息请参考 :ref:`nvs_key_partition`。
+
+- 将加密密钥用作二进制输入文件来进行加密::
+
+ python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --inputkey sample_keys.bin
+
+解密 NVS 分区
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**使用方法**::
+
+ python nvs_partition_gen.py decrypt [-h] [--outdir OUTDIR] input key output
+
+**位置参数**：
+
++--------+-------------------------------+
+| 参数 | 描述 |
++--------+-------------------------------+
+| input | 待解析的 NVS 加密分区文件路径 |
++--------+-------------------------------+
+| key | 含有解密密钥的文件路径 |
++--------+-------------------------------+
+| output | 已解密的二进制文件输出路径 |
++--------+-------------------------------+
+
+**可选参数**：
+
++-----------------+------------------------------+
+| 参数 | 描述 |
++-----------------+------------------------------+
+| -h, --help | 显示帮助信息并退出 |
++-----------------+------------------------------+
+| --outdir OUTDIR | 输出目录，用于存储创建的文件 |
+| | （默认当前目录） |
++-----------------+------------------------------+
+
+运行以下命令解密已加密的 NVS 分区::
+
+ python nvs_partition_gen.py decrypt sample_encr.bin sample_keys.bin sample_decr.bin
+
+您可以自定义格式版本号：
+
+- 版本 1：禁用多页 Blob
+- 版本 2：启用多页 Blob
+
+版本 1：禁用多页 Blob
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+如需禁用多页 Blob，请按照如下命令将版本参数设置为 1，以此格式运行分区生成程序。该程序同时会提供一个 CSV 示例文件::
+
+ python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000 --version 1
+
+版本 2：启用多页 Blob
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+如需启用多页 Blob，请按照如下命令将版本参数设置为 2，以此格式运行分区生成程序。该程序同时会提供一个 CSV 示例文件::
+
+ python nvs_partition_gen.py generate sample_multipage_blob.csv sample.bin 0x4000 --version 2
+
+.. note:: NVS 分区最小为 0x3000 字节。
+
+.. note:: 将二进制文件烧录至设备时，请确保与应用的 sdkconfig 设置一致。
+
+
+说明
+-------
+
+- 分区生成程序不会对重复键进行检查，而将数据同时写入这两个重复键中。请注意不要使用同名的键；
+- 新页面创建后，前一页的空白处不会再写入数据。CSV 文件中的字段须按次序排列以优化内存；
+- 暂不支持 64 位数据类型。
--- /dev/null
+量产程序
+=====================
+
+: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/`` 存储加密密钥（创建工厂加密映像时会用到）
+
projects / esp-idf / commitdiff