From bea507378e2339a59b3ab1d0ccdcbd6f591999e3 Mon Sep 17 00:00:00 2001 From: Wang Fang Date: Fri, 6 Sep 2019 20:18:19 +0800 Subject: [PATCH] Add Chinese translation for README files in components and tools folders, including: 1. components/nvs_flash/nvs_partition_generator/README_CN.rst 2. components/wear_levelling/README_CN.rst 3. tools/mass_mfg/docs/README_CN.rst --- .../nvs_partition_generator/README.rst | 2 + .../nvs_partition_generator/README_CN.rst | 304 ++++++++++++++++++ components/wear_levelling/README.rst | 2 + components/wear_levelling/README_CN.rst | 47 +++ docs/zh_CN/api-reference/storage/mass_mfg.rst | 2 +- .../storage/nvs_partition_gen.rst | 2 +- .../api-reference/storage/wear-levelling.rst | 3 +- tools/mass_mfg/docs/README.rst | 2 + tools/mass_mfg/docs/README_CN.rst | 256 +++++++++++++++ 9 files changed, 617 insertions(+), 3 deletions(-) create mode 100644 components/nvs_flash/nvs_partition_generator/README_CN.rst create mode 100644 components/wear_levelling/README_CN.rst create mode 100644 tools/mass_mfg/docs/README_CN.rst diff --git a/components/nvs_flash/nvs_partition_generator/README.rst b/components/nvs_flash/nvs_partition_generator/README.rst index 800344223e..ae6212f511 100644 --- a/components/nvs_flash/nvs_partition_generator/README.rst +++ b/components/nvs_flash/nvs_partition_generator/README.rst @@ -1,6 +1,8 @@ NVS Partition Generator Utility =============================== +:link_to_translation:`zh_CN:[中文]` + Introduction ------------ diff --git a/components/nvs_flash/nvs_partition_generator/README_CN.rst b/components/nvs_flash/nvs_partition_generator/README_CN.rst new file mode 100644 index 0000000000..24094e9939 --- /dev/null +++ b/components/nvs_flash/nvs_partition_generator/README_CN.rst @@ -0,0 +1,304 @@ +NVS 分区生成程序 +=============================== + +:link_to_translation:`en:[English]` + +介绍 +------------ + +NVS 分区生成程序 (:component_file:`nvs_flash/nvs_partition_generator/nvs_partition_gen.py`) 根据 CSV 文件中的键值对生成二进制文件。该二进制文件与 :doc:`非易失性存储器 (NVS) ` 中定义的 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:: 创建的加密密钥格式为 ``/keys/keys-.bin``。 + +- 通过 NVS 分区生成程序生成加密密钥，并将密钥存储于自定义的文件中:: + + python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen --keyfile sample_keys.bin + +.. note:: 创建的加密密钥格式为 ``/keys/keys-.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 位数据类型。 diff --git a/components/wear_levelling/README.rst b/components/wear_levelling/README.rst index 44def742e5..4623bf12b4 100644 --- a/components/wear_levelling/README.rst +++ b/components/wear_levelling/README.rst @@ -1,6 +1,8 @@ Wear Levelling API ================== +:link_to_translation:`zh_CN:[中文]` + Overview -------- Most of flash memory and especially SPI flash that is used in ESP32 has a sector-based organization and also has a limited number of erase/modification cycles per memory sector. The wear levelling component helps to distribute wear and tear among sectors more evenly without requiring any attention from the user. diff --git a/components/wear_levelling/README_CN.rst b/components/wear_levelling/README_CN.rst new file mode 100644 index 0000000000..13d5abdd0c --- /dev/null +++ b/components/wear_levelling/README_CN.rst @@ -0,0 +1,47 @@ +磨损均衡 API +================== + +:link_to_translation:`en:[English]` + +概述 +-------- + +ESP32 所使用的 flash，特别是 SPI flash 多数具备扇区结构，且每个扇区仅允许有限次数的擦除/修改操作。为了避免过度使用某一扇区，乐鑫提供了磨损均衡组件，无需用户介入即可帮助用户均衡各个扇区之间的磨损。 + +磨损均衡组件包含了通过分区组件对外部 SPI flash 进行数据读取、写入、擦除和存储器映射相关的 API 函数。磨损均衡组件还具有软件上更高级别的 API 函数，与 :doc:`FAT 文件系统 ` 协同工作。 + +磨损均衡组件与 FAT 文件系统组件共用 FAT 文件系统的扇区，扇区大小为 4096 字节，是标准 flash 扇区的大小。在这种模式下，磨损均衡组件性能达到最佳，但需要在 RAM 中占用更多内存。 + +为了节省内存，磨损均衡组件还提供了另外两种模式，均使用 512 字节大小的扇区： + +- **性能模式**：先将数据保存在 RAM 中，擦除扇区，然后将数据存储回 flash。如果设备在扇区擦写过程中突然断电，则整个扇区（4096 字节）数据将全部丢失。 +- **安全模式**：数据先保存在 flash 中空余扇区，擦除扇区后，数据即存储回去。如果设备断电，上电后可立即恢复数据。 + +设备默认设置如下： + +- 定义扇区大小为 512 字节 +- 默认使用性能模式 + +您可以使用配置菜单更改设置。 + +磨损均衡组件不会将数据缓存在 RAM 中。写入和擦除函数直接修改 flash，函数返回后，flash 即完成修改。 + +磨损均衡访问 API +----------------------------------- + +处理 flash 数据常用的 API 如下所示： + +- ``wl_mount`` - 为指定分区挂载并初始化磨损均衡模块 +- ``wl_unmount`` - 卸载分区并释放磨损均衡模块 +- ``wl_erase_range`` - 擦除 flash 中指定的地址范围 +- ``wl_write`` - 将数据写入分区 +- ``wl_read`` - 从分区读取数据 +- ``wl_size`` - 返回可用内存的大小（以字节为单位） +- ``wl_sector_size`` - 返回一个扇区的大小 + +请尽量避免直接使用原始磨损均衡函数，建议您使用文件系统特定的函数。 + +内存大小 +----------- + +内存大小是根据分区参数在磨损均衡模块中计算所得，由于模块使用 flash 部分扇区存储内部数据，因此计算所得内存大小有少许偏差。 diff --git a/docs/zh_CN/api-reference/storage/mass_mfg.rst b/docs/zh_CN/api-reference/storage/mass_mfg.rst index d640f48f48..26e61c402b 100644 --- a/docs/zh_CN/api-reference/storage/mass_mfg.rst +++ b/docs/zh_CN/api-reference/storage/mass_mfg.rst @@ -1 +1 @@ -.. include:: /../../tools/mass_mfg/docs/README.rst +.. include:: /../../tools/mass_mfg/docs/README_CN.rst diff --git a/docs/zh_CN/api-reference/storage/nvs_partition_gen.rst b/docs/zh_CN/api-reference/storage/nvs_partition_gen.rst index c94a708c86..ff70e2bec2 100644 --- a/docs/zh_CN/api-reference/storage/nvs_partition_gen.rst +++ b/docs/zh_CN/api-reference/storage/nvs_partition_gen.rst @@ -1 +1 @@ -.. include:: /../../components/nvs_flash/nvs_partition_generator/README.rst +.. include:: /../../components/nvs_flash/nvs_partition_generator/README_CN.rst diff --git a/docs/zh_CN/api-reference/storage/wear-levelling.rst b/docs/zh_CN/api-reference/storage/wear-levelling.rst index 4c50431d80..45b1e3b16c 100644 --- a/docs/zh_CN/api-reference/storage/wear-levelling.rst +++ b/docs/zh_CN/api-reference/storage/wear-levelling.rst @@ -1,4 +1,4 @@ -.. include:: ../../../../components/wear_levelling/README.rst +.. include:: ../../../../components/wear_levelling/README_CN.rst 另请参阅 ----------- @@ -31,3 +31,4 @@ ----------------------- .. include:: /_build/inc/wear_levelling.inc + diff --git a/tools/mass_mfg/docs/README.rst b/tools/mass_mfg/docs/README.rst index e38b1f1ece..ae1cc649e3 100644 --- a/tools/mass_mfg/docs/README.rst +++ b/tools/mass_mfg/docs/README.rst @@ -1,6 +1,8 @@ Manufacturing Utility ===================== +:link_to_translation:`zh_CN:[中文]` + Introduction ------------ diff --git a/tools/mass_mfg/docs/README_CN.rst b/tools/mass_mfg/docs/README_CN.rst new file mode 100644 index 0000000000..929978e82b --- /dev/null +++ b/tools/mass_mfg/docs/README_CN.rst @@ -0,0 +1,256 @@ +量产程序 +===================== + +: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:: 创建的加密密钥格式为 ``/keys/keys--.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:: 创建的加密密钥格式为 ``/keys/keys-.bin``。时间戳格式为：``%m-%d_%H-%M``。 +.. note:: 如需自定义目标文件名，请使用 --keyfile 参数。 + +生成的加密密钥二进制文件还可以用于为每个设备的工厂映像加密。 + +``fileid`` 参数的默认值为 1、2、3...，与主 CSV 文件中的行一一对应，内含设备配置值。 + +运行量产程序时，将在指定的 ``outdir`` 目录下创建以下文件夹： + +- ``bin/`` 存储生成的二进制文件 +- ``csv/`` 存储生成的中间 CSV 文件 +- ``keys/`` 存储加密密钥（创建工厂加密映像时会用到） +