Skip to content

Commit 7861780

Browse files
leeeboleeebo
committed
docs(mass_production): update mp related tools
1 parent 8370121 commit 7861780

File tree

1 file changed

+35
-222
lines changed

1 file changed

+35
-222
lines changed

‎docs/zh_CN/security_solution/mass_produce.rst‎

Lines changed: 35 additions & 222 deletions
Original file line numberDiff line numberDiff line change
@@ -1,243 +1,56 @@
1-
启用安全加密的生产方案
2-
===========================
3-
4-
Windows 平台的下载工具
5-
************************
6-
7-
- 乐鑫提供 windows 平台的下载工具，能够在工厂生产环境中批量烧写固件
8-
- 生产下载工具的配置文件在 configure 文件夹内，涉及安全特性的配置在 security.conf 中，目前涉及的配置内容如下表：
9-
10-
11-
.. list-table:: Configuration Table
12-
:widths: 25 50 10
13-
:header-rows: 1
14-
15-
* - Item
16-
- Function
17-
- Default
18-
* - debug_enable
19-
- 是否开启 debug 模式，在 debug 模式下，工具会根据 pem 文件产生相同密钥，否则随机生成密钥
20-
- True
21-
* - debug_pem_path
22-
- 设置证书地址，用于生成可重复烧写的密钥，仅在 debug 模式下有效
23-
-
24-
* - SECURE BOOT
25-
-
26-
-
27-
* - secure_boot_en
28-
- 开启 secure boot 功能
29-
- False
30-
* - burn_secure_boot_key
31-
- 使能 secure boot key 烧写
32-
- False
33-
* - secure_boot_force_write
34-
- 是否检查 secure boot key block，强制烧写 key
35-
- False
36-
* - secure_boot_rw_protect
37-
- 开启 secure boot key 区域的读写保护
38-
- False
39-
* - FLASH ENCRYPTION
40-
-
41-
-
42-
* - flash_encryption_en
43-
- 开启 flash 加密功能
44-
- False
45-
* - burn_flash_encryption_key
46-
- 使能 flash encrypt key 烧写
47-
- False
48-
* - flash_encrypt_force_write
49-
- 是否检查 flash encrypt key block，强制烧写 key
50-
- False
51-
* - flash_encrypt_rw_protect
52-
- 开启 flash encrypt key 区域的读写保护
53-
- False
54-
* - AES KEY
55-
- 暂未使用
56-
-
57-
* - DISABLE FUNC
58-
-
59-
-
60-
* - jtag_disable
61-
- 是否关闭 JTAG 调试功能
62-
- False
63-
* - dl_encrypt_disable
64-
- 是否关闭下载模式下 flash 加密功能
65-
- False
66-
* - dl_decrypt_disable
67-
- 是否关闭下载模式下 flash 解密功能
68-
- False
69-
* - dl_cache_disable
70-
- 是否关闭下载模式下的 flash cache 功能
71-
- False
72-
73-
- 下载工具的内部逻辑和流程如下：
74-
75-
.. figure:: ../../_static/secure_encrypt/download_tool_flow_chart.png
76-
:align: center
77-
78-
79-
操作步骤
80-
**********
81-
82-
准备工作
83-
~~~~~~~~
84-
85-
- 安装 eptool
86-
87-
- esptool 默认路径在 $IDF\_PATH/components/esptool\_py/esptool/
88-
- 也可以通过 python 安装：
89-
90-
::
91-
92-
pip install esptool
93-
或者
94-
pip3 install esptool
95-
96-
方案 1: 通过 bootloader 完成 security 特性初始化
97-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98-
99-
- ``优势``: 可以批量进行 flash 烧录，初始化的固件相同，密钥在第一次上电有在设备内随机生成。
100-
- ``缺陷``: 设备在首次初始化过程所用时间较长，如果在首次初始化过程发生掉电等意外情况，设备可能无法正常启动。
101-
- 由芯片端自动随机生成 secure boot 与 flash encrypton 密钥，并写入芯片 efuse 中, 密钥写入后，对应的 efuse block 会被设置为读写保护状态，软件与工具都无法读取出密钥。
102-
- 所有编译出的 images 都按正常情况烧写，芯片会在第一次 boot 时进行配置。
103-
- 通过 make menuconfig 配置 secure boot 和 flash encryption，按照第一、二节介绍的步骤执行即可，具体操作步骤如下，如果了解第一、二节的内容，可以跳过：
1+
量产方案
2+
========
1043

105-
1. 随机生成 RSA 密钥文件：
4+
本文档集合了用于乐鑫芯片量产的多种工具，包括烧录、测试、治具规范、配网及射频工具等内容。
1065

107-
::
6+
**Flash 下载工具**
7+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1088

109-
espsecure.py generate_signing_key secure_boot_signing_key.pem
110-
or
111-
openssl ecparam -name prime256v1 -genkey -noout -out secure_boot_signing_key.pem
9+
该工具面向生产环节，用于将量产固件高效烧录到芯片 flash，支持多芯片并行烧录和多种烧录参数配置。它解决了量产过程中固件更新、批量烧录、自动化测试等问题，提升生产效率，降低人为失误。适用于产线固件部署、批量升级、调试流程。参考 `Esp32 生产阶段 <https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/production_stage/index.html>`_ 。
11210

113-
2. 在 menuconfig 中，选择 Sign binaries during build,并指定刚才生成的密钥路径, 如下图。
11411

115-
.. figure:: ../../_static/secure_encrypt/menuconfig_02.png
116-
:align: center
117-
118-
3. 分别编译 bootloader 与应用代码
119-
120-
::
121-
122-
make bootloader
123-
make
124-
125-
4. 使用 esptool 将编译生成的bin文件写入flash对应地址,以 example 中 hellow-world 工程为例：
126-
127-
::
128-
129-
bootloader.bin --> 0x1000
130-
partition.bin --> 0x8000
131-
app.bin --> 0x10000
132-
python $IDF_PATH/components/esptool_py/esptool/esptool.py --chip esp32 --port /dev/cu.SLAB_USBtoUART --baud 1152000 --before default_reset --after no_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 $IDS_PATH/esp-idf/examples/get-started/hello_world/build/bootloader/bootloader.bin 0xf000 $IDF_PATH/esp-idf/examples/get-started/hello_world/build/phy_init_data.bin 0x10000 $IDF_PATH/examples/get-started/hello_world/build/hello-world.bin 0x8000 $IDF_PATH/examples/get-started/hello_world/build/partitions_singleapp.bin
12+
.. image:: https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/_images/factorymultidownload_interface.png
13+
:alt: Factory Multi Download Interface
14+
:align: center
13315

134-
.. note::
135-
以上命令仅是示例代码，请在使用时，替换其中的文件路径以及所选参数，包括串口、波特率、SPI 模式和频率等。
16+
**乐鑫产测工具**
17+
~~~~~~~~~~~~~~~~~~~~
13618

137-
5. 我们也可以使用 window 平台的下载工具来完成工厂下载。需要在配置文件中，关闭工具的 security 功能，这样工具端就不会操作 security 相关特性，完全由硬件和 bootloader 来完成初始化：
19+
该工具是一拖四的产线测试上位机，采用“RAM 运行测试”方式，支持自动化配置和执行测试流程。功能包括 RF 性能测试、GPIO 导通测试、固件版本校验、Flash 读写/ID 测试等，能够自动生成测试日志和统计报表，并支持测试 bin、阈值和系统配置管理。它解决了产线测试效率低、人工操作繁琐、数据统计难等问题，适用于大批量生产测试、产线质量管控。参考 `Esp32 产测指南-产测工具 <https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/production_stage/tools/esp_production_testing_guide.html#production-testing-tool>`_ 。
13820

139-
::
14021

141-
[SECURE BOOT]
142-
secure_boot_en * False
143-
[FLASH ENCRYPTION]
144-
flash_encryption_en * False
22+
.. image:: https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/_images/finish.png
23+
:alt: Factory Test UI Tool 测试完成界面
24+
:align: center
14525

146-
.. note::
147-
修改并保存参数前，请先关闭下载工具，配置文件修改完成并保存后，再开启运行下载工具。
26+
**模组冶具制作规范**
27+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
14828

149-
.. figure:: ../../_static/secure_encrypt/download_frame_02.png
150-
:align: center
29+
该规范指导产测治具的结构设计与制作工艺，确保测试夹具在量产过程中具备一致性和可靠性。通过标准化治具设计，减少因治具差异导致的测试误差和不良品率，提升测试效率和产品质量。适用于量产测试夹具开发、产线治具选型。参考 `Esp32 生产阶段 <https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/production_stage/index.html>`_ 。
15130

152-
6. 或者我们可以通过下载工具的 combine 功能，将多个 bin 文件打包为一个文件，再由工厂 flash 烧录器烧录进 flash 进行批量生产。
15331

154-
- 选择bin文件并制定 flash 中的地址
155-
- 选中 ‘DoNotChgBin’ 选项，这样工具不会对bin文件的配置(SPI模式速率等)进行任何修改。
156-
- 点击 ‘CombineBin' 按键，生产合并后的bin文件。
157-
- 在 ‘combine’ 文件夹下，生成 target.bin，将其烧写到 Flash 的 0x0 地址即可。
158-
- 工具只会对填写的最大地址范围内的空白区域填充 0xff。并将文件按地址组合。
32+
.. image:: https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/_images/test_fixture_structure_cn.png
33+
:alt: 测试夹具结构示意图
34+
:align: center
15935

160-
.. figure:: ../../_static/secure_encrypt/combine_01.png
161-
:align: center
36+
**Matter QR 二维码生成工具**
37+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16238

163-
7. 下载完成后，需要运行一次程序，使 bootloader 完成 security 相关特性的初始化，包括AES密钥的随机生成并写入EFUSE，以及对明文的flash进行首次加密。
39+
该工具用于生成 Matter 设备的配网二维码，支持批量生成和自定义参数配置。它解决了产线设备快速入网、自动化配网、批量验证等问题，提升量产设备的联网效率和一致性。适用于 Matter 设备生产、产线配网、入网验证等场景。参考 `Esp32 生产阶段 <https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/production_stage/index.html>`_ 。
16440

165-
.. note::
166-
请误在首次启动完成前，将芯片断电，以免造成芯片无法启动的情况。
16741

168-
- ``注意事项``\ ：
42+
.. image:: https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/_images/ui_main.png
43+
:alt: Matter QR 二维码生成工具主界面
44+
:align: center
16945

170-
- 用于签名的私钥需要保密，如果泄漏，app.bin 有被伪造的可能性。
171-
- 使用者不能遗失私钥，必须使用私钥用于对 OTA app 签名（如果有 OTA 功能）。
172-
- 芯片通过软件 bootloader 对 flash 加密是一个比较缓慢的过程，对于较大的 partition 可能需要花费一分钟左右
173-
- 若第一次执行 bootloader，flash 加密进行到一半芯片掉电
46+
**EspRFTestTool 工具包**
47+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17448

175-
- 没有使能 secure boot 时，可重新将 images 明文烧写到 flash
176-
中，让芯片下次 boot 时重新加密 flash
177-
- 使能了 secure boot 时，由于无法重新烧写 flash，芯片将永久无法 boot
49+
* EspRFTestTool：用于射频测试的上位机工具，支持 Wi‑Fi 非信令测试、蓝牙/低功耗蓝牙非信令测试、Wi‑Fi 自适应测试等。该工具集成串口配置、固件快速烧录、测试参数配置与状态日志窗口，能够帮助研发人员在芯片开发阶段快速验证关键 RF 指标，发现并定位射频性能问题，提升产品可靠性。适用于芯片初期调试、射频性能评估、认证前预检等场景。下载入口见 `EspRFTestTool 工具包 <https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/development_stage/index.html>`_ 。
50+
* DownloadTool：用于将测试固件烧录到芯片，支持 RAM 和 flash 两种烧录模式，并可指定烧录地址。该工具主要解决射频测试前固件快速部署的问题，确保测试环境一致性，减少人工操作失误。适用于 RF 测试准备、固件版本切换、批量烧录等需求。参考 `Esp32 工具包 <https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/development_stage/index.html>`_ 。
51+
* PowerLimitTool：用于生成定制化的 phy_init_data 固件，支持灵活配置射频功率限制等参数。该工具帮助用户满足不同国家/地区的射频法规要求，提升产品合规性，并可配合 RF 测试与认证流程使用。适用于认证准备、特殊应用场景功率调整等。参考 `Esp32 工具包 <https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/development_stage/index.html>`_ 。
17852

179-
方案 2: 通过下载工具初始化 security 特性
180-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53+
.. image:: https://docs.espressif.com/projects/esp-test-tools/zh_CN/latest/esp32/_images/powerlimittool_rf_test_setting.png
54+
:alt: PowerLimitTool RF 测试设置界面
55+
:align: center
18156

182-
- ``优势``: 工具进行密钥的随机生成，直接将 image 密文烧写进 flash，然后配置 efuse. 避免过程中掉电造成无法启动的情况。
183-
- ``缺陷``: 每个设备必须通过下载工具进行烧写，因为密钥不同，无法预先烧写相同的固件到 flash 中。
184-
- 使用下载工具应用 secure boot 和 flash encryption，这时用户只需要的在 make menuconfig 中选择“enable secure boot in bootloader”并设置公钥/秘钥路径即可
185-
- 下载工具在运行时，会随机产生 secure boot 与 flash encryption 密钥,并烧写到对应的 EFUSE 位置中。
186-
- 操作步骤：
187-
188-
1. 随机生成 RSA 密钥文件，用于签名固件：
189-
190-
::
191-
192-
espsecure.py generate_signing_key secure_boot_signing_key.pem
193-
or
194-
openssl ecparam -name prime256v1 -genkey -noout -out secure_boot_signing_key.pem
195-
196-
2. 在 menuconfig 中，选择 Sign binaries during build，并指定刚才生成的密钥路径, 如下图。
197-
198-
.. figure:: ../../_static/secure_encrypt/menuconfig_02.png
199-
:align: center
200-
201-
3. 分别编译 bootloader 与应用代码
202-
203-
::
204-
205-
make bootloader
206-
make
207-
208-
4. 设置下载工具的安全配置文件
209-
210-
::
211-
212-
[DEBUG MODE]
213-
debug_enable * False #关闭 debug 模式，工具随机生成密钥。否则根据pem文件产生相同密钥
214-
debug_pem_path * #debug 模式下，设置证书地址，用于生成可重复烧写的密钥
215-
[SECURE BOOT]
216-
secure_boot_en * True #开启 secure boot 功能
217-
burn_secure_boot_key * True #使能 secure boot key 烧写
218-
secure_boot_force_write * False #是否不检查 secure boot key block，强制烧写 key
219-
secure_boot_rw_protect * True #开启 secure boot key 区域的读写保护
220-
[FLASH ENCRYPTION]
221-
flash_encryption_en * True #开启 flash加密功能
222-
burn_flash_encryption_key * True #使能 flash encrypt key 烧写
223-
flash_encrypt_force_write * False #是否不检查 flash encrypt key block，强制烧写 key
224-
flash_encrypt_rw_protect * True #开启 flash encrypt key 区域的读写保护
225-
[AES KEY]
226-
aes_key_en * False #目前未实现，仅保留该选项
227-
burn_aes_key * False #目前未实现，仅保留该选项
228-
[DISABLE FUNC]
229-
jtag_disable * True #是否关闭 JTAG 调试功能
230-
dl_encrypt_disable * True #是否关闭下载模式下 flash 加密功能
231-
dl_decrypt_disable * True #是否关闭下载模式下 flash 解密功能
232-
dl_cache_disable * True #是否关闭下载模式下的 flash cache 功能
233-
234-
注意：
235-
修改并保存参数前，请先关闭下载工具，配置文件修改完成并保存后，再开启运行下载工具。
236-
237-
5. 使用下载工具进行下载，若不希望工具修改任何配置参数(比如 flash 频率和模式)，请勾选 ‘DoNotChgBin’ 选项。下载工具会更具配置文件的设置，在下载过程中完成固件加密下载和密钥随机生成与烧写。
238-
239-
- ``注意事项``:
240-
241-
- 用于签名的私钥需要保密，如果泄漏，app.bin 有被伪造的可能性。
242-
- 使用者不能遗失私钥，必须使用私钥用于对 OTA app 签名（如果有 OTA 功能）。
243-
- 用户可以选择不启用 app image 的签名校验，只需要关闭 menuconfig 中的 secure boot 功能即可。下载工具会更具配置文件，通过 efuse 启用 secure boot。禁用 app image 的签名校验会存在安全隐患。

0 commit comments

Comments
 (0)