espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-10-02 10:00:57 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat: Update esptool to v5

Browse Source
This commit is contained in:
Peter Dragun
2025-08-11 16:11:49 +02:00
parent 053fb47e78
commit e3198fff3c
129 changed files with 1237 additions and 1318 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/ISSUE_TEMPLATE/02_runtime_bug.yml vendored
View File

@@ -26,7 +26,7 @@ body:
id: chip_revision
attributes:
label: Espressif SoC revision.
description: On which Espressif SoC revision does your application run on? Run `esptool chip_id` to find it.
description: On which Espressif SoC revision does your application run on? Run `esptool chip-id` to find it.
placeholder: ex. ESP32-C3 (QFN32) (revision v0.3)
validations:
required: true

2
COMPATIBILITY.md
View File

@@ -10,7 +10,7 @@ NOTE: This document on release branches may be out-of-date. Check the [Compatibi
See [Compatibility Advisory for Chip Revision Numbering Scheme](https://www.espressif.com/sites/default/files/advisory_downloads/AR2022-005%20Compatibility%20Advisory%20for%20Chip%20Revision%20Numbering%20%20Scheme.pdf) on the versioning of Espressif SoC revisions.
You can run `esptool chip_id` to detect the series and revision of an SoC. See [SoC Errata](https://www.espressif.com/en/support/documents/technical-documents?keys=errata) for more on how to distinguish between chip revisions, and the improvements provided by chip revisions. And run `idf.py --version` to know the version of current ESP-IDF.
You can run `esptool chip-id` to detect the series and revision of an SoC. See [SoC Errata](https://www.espressif.com/en/support/documents/technical-documents?keys=errata) for more on how to distinguish between chip revisions, and the improvements provided by chip revisions. And run `idf.py --version` to know the version of current ESP-IDF.
## ESP-IDF Support for Different Chip Revisions

2
COMPATIBILITY_CN.md
View File

@@ -10,7 +10,7 @@
有关乐鑫芯片版本的编码方式，请参考 [关于芯片版本 (Chip Revision) 编码方式的兼容性公告](https://www.espressif.com/sites/default/files/advisory_downloads/AR2022-005%20%E5%85%B3%E4%BA%8E%E8%8A%AF%E7%89%87%E7%89%88%E6%9C%AC%E7%BC%96%E7%A0%81%E6%96%B9%E5%BC%8F%20%28Chip%20Revision%29%20%E7%9A%84%E5%85%BC%E5%AE%B9%E6%80%A7%E5%85%AC%E5%91%8A.pdf)。
运行 `esptool chip_id` 可查看芯片系列及其版本。有关区分芯片版本及版本改进内容的更多信息，请参考 [芯片勘误表](https://www.espressif.com.cn/zh-hans/support/documents/technical-documents?keys=%E5%8B%98%E8%AF%AF%E8%A1%A8)。运行 `idf.py --version` 可查看当前的 ESP-IDF 版本。
运行 `esptool chip-id` 可查看芯片系列及其版本。有关区分芯片版本及版本改进内容的更多信息，请参考 [芯片勘误表](https://www.espressif.com.cn/zh-hans/support/documents/technical-documents?keys=%E5%8B%98%E8%AF%AF%E8%A1%A8)。运行 `idf.py --version` 可查看当前的 ESP-IDF 版本。
## ESP-IDF 对各芯片版本的支持

4
Kconfig
View File

@@ -219,10 +219,10 @@ mainmenu "Espressif IoT Development Framework Configuration"
When loading the BIN with UART, the ROM will jump to ram and run the app after finishing the ROM
startup code, so there's no additional startup initialization required. You can use the
`load_ram` in esptool.py to load the generated .bin file into ram and execute.
`load-ram` in esptool to load the generated .bin file into ram and execute.
Example:
esptool.py --chip {chip} -p {port} -b {baud} --no-stub load_ram {app.bin}
esptool --chip {chip} -p {port} -b {baud} --no-stub load-ram {app.bin}
Recommended sdkconfig.defaults for building loadable ELF files is as follows.
CONFIG_APP_BUILD_TYPE_RAM is required, other options help reduce application

2
README.md
View File

@@ -83,7 +83,7 @@ See the Getting Started guide links above for a detailed setup guide. This is a
## Flashing the Project
When the build finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this automatically by running:
When the build finishes, it will print a command line to use `esptool` to flash the chip. However you can also do this automatically by running:
`idf.py -p PORT flash`

2
README_CN.md
View File

@@ -83,7 +83,7 @@ ESP-IDF 中的子模块采用相对路径（[详见 .gitmodules 文件](.gitmodu
## 烧写项目
当构建结束，终端会打印出一条命令行，告知如何使用 esptool.py 工具烧写项目到芯片中。但你也可以运行下面这条命令来自动烧写：
当构建结束，终端会打印出一条命令行，告知如何使用 `esptool` 工具烧写项目到芯片中。但你也可以运行下面这条命令来自动烧写：
`idf.py -p PORT flash`

106
components/app_update/otatool.py
View File

@@ -3,10 +3,8 @@
# otatool is used to perform ota-level operations - flashing ota partition
# erasing ota partition and switching ota partition
#
# SPDX-FileCopyrightText: 2018-2021 Espressif Systems (Shanghai) CO LTD
# SPDX-FileCopyrightText: 2018-2025 Espressif Systems (Shanghai) CO LTD
# SPDX-License-Identifier: Apache-2.0
from __future__ import division, print_function
import argparse
import binascii
import collections
@@ -16,12 +14,18 @@ import sys
import tempfile
try:
from parttool import PARTITION_TABLE_OFFSET, PartitionName, PartitionType, ParttoolTarget
from parttool import PARTITION_TABLE_OFFSET
from parttool import PartitionName
from parttool import PartitionType
from parttool import ParttoolTarget
except ImportError:
COMPONENTS_PATH = os.path.expandvars(os.path.join('$IDF_PATH', 'components'))
PARTTOOL_DIR = os.path.join(COMPONENTS_PATH, 'partition_table')
sys.path.append(PARTTOOL_DIR)
from parttool import PARTITION_TABLE_OFFSET, PartitionName, PartitionType, ParttoolTarget
from parttool import PARTITION_TABLE_OFFSET
from parttool import PartitionName
from parttool import PartitionType
from parttool import ParttoolTarget
__version__ = '2.0'
@@ -35,15 +39,31 @@ def status(msg):
print(msg)
class OtatoolTarget():
class OtatoolTarget:
OTADATA_PARTITION = PartitionType('data', 'ota')
def __init__(self, port=None, baud=None, partition_table_offset=PARTITION_TABLE_OFFSET, partition_table_file=None,
spi_flash_sec_size=SPI_FLASH_SEC_SIZE, esptool_args=[], esptool_write_args=[],
esptool_read_args=[], esptool_erase_args=[]):
self.target = ParttoolTarget(port, baud, partition_table_offset, partition_table_file, esptool_args,
esptool_write_args, esptool_read_args, esptool_erase_args)
def __init__(
self,
port=None,
baud=None,
partition_table_offset=PARTITION_TABLE_OFFSET,
partition_table_file=None,
spi_flash_sec_size=SPI_FLASH_SEC_SIZE,
esptool_args=[],
esptool_write_args=[],
esptool_read_args=[],
esptool_erase_args=[],
):
self.target = ParttoolTarget(
port,
baud,
partition_table_offset,
partition_table_file,
esptool_args,
esptool_write_args,
esptool_read_args,
esptool_erase_args,
)
self.spi_flash_sec_size = spi_flash_sec_size
temp_file = tempfile.NamedTemporaryFile(delete=False)
@@ -118,7 +138,9 @@ class OtatoolTarget():
try:
if isinstance(ota_id, int):
ota_partition_next = filter(lambda p: p.subtype - gen.MIN_PARTITION_SUBTYPE_APP_OTA == ota_id, ota_partitions)
ota_partition_next = filter(
lambda p: p.subtype - gen.MIN_PARTITION_SUBTYPE_APP_OTA == ota_id, ota_partitions
)
else:
ota_partition_next = filter(lambda p: p.name == ota_id, ota_partitions)
@@ -192,8 +214,8 @@ class OtatoolTarget():
def read_ota_partition(self, ota_id, output):
self.target.read_partition(self._get_partition_id_from_ota_id(ota_id), output)
def write_ota_partition(self, ota_id, input):
self.target.write_partition(self._get_partition_id_from_ota_id(ota_id), input)
def write_ota_partition(self, ota_id, input_file):
self.target.write_partition(self._get_partition_id_from_ota_id(ota_id), input_file)
def erase_ota_partition(self, ota_id):
self.target.erase_partition(self._get_partition_id_from_ota_id(ota_id))
@@ -205,8 +227,10 @@ def _read_otadata(target):
otadata_info = target._get_otadata_info()
print(' {:8s} \t {:8s} | \t {:8s} \t {:8s}'.format('OTA_SEQ', 'CRC', 'OTA_SEQ', 'CRC'))
print('Firmware: 0x{:08x} \t0x{:08x} | \t0x{:08x} \t 0x{:08x}'.format(otadata_info[0].seq, otadata_info[0].crc,
otadata_info[1].seq, otadata_info[1].crc))
print(
f'Firmware: {otadata_info[0].seq:#08x} \t{otadata_info[0].crc:#08x} | '
f'\t{otadata_info[1].seq:#08x} \t {otadata_info[1].crc:#08x}'
)
def _erase_otadata(target):
@@ -220,12 +244,12 @@ def _switch_ota_partition(target, ota_id):
def _read_ota_partition(target, ota_id, output):
target.read_ota_partition(ota_id, output)
status('Read ota partition contents to file {}'.format(output))
status(f'Read ota partition contents to file {output}')
def _write_ota_partition(target, ota_id, input):
target.write_ota_partition(ota_id, input)
status('Written contents of file {} to ota partition'.format(input))
def _write_ota_partition(target, ota_id, input_file):
target.write_ota_partition(ota_id, input_file)
status(f'Written contents of file {input_file} to ota partition')
def _erase_ota_partition(target, ota_id):
@@ -240,9 +264,13 @@ def main():
parser.add_argument('--quiet', '-q', help='suppress stderr messages', action='store_true')
parser.add_argument('--esptool-args', help='additional main arguments for esptool', nargs='+')
parser.add_argument('--esptool-write-args', help='additional subcommand arguments for esptool write_flash', nargs='+')
parser.add_argument('--esptool-read-args', help='additional subcommand arguments for esptool read_flash', nargs='+')
parser.add_argument('--esptool-erase-args', help='additional subcommand arguments for esptool erase_region', nargs='+')
parser.add_argument(
'--esptool-write-args', help='additional subcommand arguments for esptool write-flash', nargs='+'
)
parser.add_argument('--esptool-read-args', help='additional subcommand arguments for esptool read-flash', nargs='+')
parser.add_argument(
'--esptool-erase-args', help='additional subcommand arguments for esptool erase-region', nargs='+'
)
# There are two possible sources for the partition table: a device attached to the host
# or a partition table CSV/binary file. These sources are mutually exclusive.
@@ -252,8 +280,12 @@ def main():
parser.add_argument('--partition-table-offset', '-o', help='offset to read the partition table from', type=str)
parser.add_argument('--partition-table-file', '-f', help='file (CSV/binary) to read the partition table from; \
overrides device attached to specified port as the partition table source when defined')
parser.add_argument(
'--partition-table-file',
'-f',
help='file (CSV/binary) to read the partition table from; '
'overrides device attached to specified port as the partition table source when defined',
)
subparsers = parser.add_subparsers(dest='operation', help='run otatool -h for additional help')
@@ -269,15 +301,25 @@ def main():
slot_or_name_parser_args.add_argument('--slot', help='slot number of the ota partition', type=int)
slot_or_name_parser_args.add_argument('--name', help='name of the ota partition')
subparsers.add_parser('switch_ota_partition', help='switch otadata partition', parents=[slot_or_name_parser, spi_flash_sec_size])
subparsers.add_parser(
'switch_ota_partition', help='switch otadata partition', parents=[slot_or_name_parser, spi_flash_sec_size]
)
read_ota_partition_subparser = subparsers.add_parser('read_ota_partition', help='read contents of an ota partition', parents=[slot_or_name_parser])
read_ota_partition_subparser.add_argument('--output', help='file to write the contents of the ota partition to', required=True)
read_ota_partition_subparser = subparsers.add_parser(
'read_ota_partition', help='read contents of an ota partition', parents=[slot_or_name_parser]
)
read_ota_partition_subparser.add_argument(
'--output', help='file to write the contents of the ota partition to', required=True
)
write_ota_partition_subparser = subparsers.add_parser('write_ota_partition', help='write contents to an ota partition', parents=[slot_or_name_parser])
write_ota_partition_subparser = subparsers.add_parser(
'write_ota_partition', help='write contents to an ota partition', parents=[slot_or_name_parser]
)
write_ota_partition_subparser.add_argument('--input', help='file whose contents to write to the ota partition')
subparsers.add_parser('erase_ota_partition', help='erase contents of an ota partition', parents=[slot_or_name_parser])
subparsers.add_parser(
'erase_ota_partition', help='erase contents of an ota partition', parents=[slot_or_name_parser]
)
args = parser.parse_args()
@@ -343,7 +385,7 @@ def main():
'switch_ota_partition': (_switch_ota_partition, ota_id),
'read_ota_partition': (_read_ota_partition, ['output'] + ota_id),
'write_ota_partition': (_write_ota_partition, ['input'] + ota_id),
'erase_ota_partition':(_erase_ota_partition, ota_id)
'erase_ota_partition': (_erase_ota_partition, ota_id),
}
(op, op_args) = otatool_ops[args.operation]

2
components/bootloader/Kconfig.bootloader_rollback
View File

@@ -20,7 +20,7 @@ menu "Recovery Bootloader and Rollback"
Flash address where the recovery bootloader is stored.
This value must be written to the eFuse field (ESP_EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR)
to activate the recovery bootloader in the ROM bootloader. The eFuse can be programmed
using espefuse.py or in the user application with the API esp_efuse_set_recovery_bootloader_offset().
using espefuse or in the user application with the API esp_efuse_set_recovery_bootloader_offset().
Setting this value in the config allows parttool.py to verify that it does not overlap with existing
partitions in the partition table.

22
components/bootloader/Kconfig.projbuild
View File

@@ -695,7 +695,7 @@ menu "Security features"
If enabled (default), these binary files are signed as part of the build process. The file named in
"Secure boot private signing key" will be used to sign the image.
If disabled, unsigned app/partition data will be built. They must be signed manually using espsecure.py.
If disabled, unsigned app/partition data will be built. They must be signed manually using espsecure.
Version 1 to enable ECDSA Based Secure Boot and Version 2 to enable RSA based Secure Boot.
(for example, on a remote signing server.)
@@ -712,7 +712,7 @@ menu "Security features"
Path is evaluated relative to the project directory.
You can generate a new signing key by running the following command:
espsecure.py generate_signing_key secure_boot_signing_key.pem
espsecure generate-signing-key secure_boot_signing_key.pem
See the Secure Boot section of the ESP-IDF Programmer's Guide for this version for details.
@@ -726,8 +726,8 @@ menu "Security features"
app, to verify app images.
Key file is in raw binary format, and can be extracted from a
PEM formatted private key using the espsecure.py
extract_public_key command.
PEM formatted private key using the espsecure
extract-public-key command.
Refer to the Secure Boot section of the ESP-IDF Programmer's Guide for this version before enabling.
@@ -769,7 +769,7 @@ menu "Security features"
NOTE: If "UART ROM download mode (Permanently disabled (recommended))" or
"UART ROM download mode (Permanently switch to Secure mode (recommended))" is set,
then it is __NOT__ possible to read/write efuses using espefuse.py utility.
then it is __NOT__ possible to read/write efuses using espefuse utility.
However, efuse can be read/written from the application
Please refer to the Secure Boot V2 documentation guide for more information.
@@ -798,7 +798,7 @@ menu "Security features"
help
In reflashable secure bootloader mode, a hardware key is derived from the signing key (with SHA-256) and
can be written to eFuse with espefuse.py.
can be written to eFuse with espefuse.
Normally this is a 256-bit key, but if 3/4 Coding Scheme is used on the device then the eFuse key is
truncated to 192 bits.
@@ -1036,7 +1036,7 @@ menu "Security features"
If flash encryption is enabled in eFuses, this option does not change the bootloader behavior.
Only use this option in testing environments, to avoid accidentally enabling flash encryption on
the wrong device. The device needs to have flash encryption already enabled using espefuse.py.
the wrong device. The device needs to have flash encryption already enabled using espefuse.
config SECURE_FLASH_SKIP_WRITE_PROTECTION_CACHE
bool "Skip write-protection of DIS_CACHE (DIS_ICACHE, DIS_DCACHE)"
@@ -1164,7 +1164,7 @@ menu "Security features"
bool "UART ROM download mode (Permanently disabled (recommended))"
help
If set, during startup the app will burn an eFuse bit to permanently disable the UART ROM
Download Mode. This prevents any future use of esptool.py, espefuse.py and similar tools.
Download Mode. This prevents any future use of esptool, espefuse and similar tools.
Once disabled, if the SoC is booted with strapping pins set for ROM Download Mode
then an error is printed instead.
@@ -1186,10 +1186,10 @@ menu "Security features"
Secure Download mode limits the use of Download Mode functions to update SPI config,
changing baud rate, basic flash write and a command to return a summary of currently
enabled security features (`get_security_info`).
enabled security features (`get-security-info`).
Secure Download mode is not compatible with the esptool.py flasher stub feature,
espefuse.py, read/writing memory or registers, encrypted download, or any other
Secure Download mode is not compatible with the esptool flasher stub feature,
espefuse, read/writing memory or registers, encrypted download, or any other
features that interact with unsupported Download Mode commands.
Secure Download mode should be enabled in any application where Flash Encryption

18
components/bootloader/subproject/CMakeLists.txt
View File

@@ -108,7 +108,7 @@ idf_component_get_property(espefuse_py_cmd esptool_py ESPEFUSEPY_CMD)
# String for printing flash command
string(REPLACE ";" " " esptoolpy_write_flash
"${esptool_py_cmd} --port=(PORT) --baud=(BAUD) ${main_args} "
"write_flash ${sub_args}")
"write-flash ${sub_args}")
string(REPLACE ";" " " espsecurepy "${espsecure_py_cmd}")
string(REPLACE ";" " " espefusepy "${espefuse_py_cmd}")
@@ -132,7 +132,7 @@ if(CONFIG_SECURE_BOOTLOADER_REFLASHABLE)
ABSOLUTE BASE_DIR "${CMAKE_BINARY_DIR}")
add_custom_command(OUTPUT "${secure_bootloader_key}"
COMMAND ${espsecure_py_cmd} digest_private_key
COMMAND ${espsecure_py_cmd} digest-private-key
--keylen "${key_digest_len}"
--keyfile "${SECURE_BOOT_SIGNING_KEY}"
"${secure_bootloader_key}"
@@ -146,9 +146,9 @@ if(CONFIG_SECURE_BOOTLOADER_REFLASHABLE)
"No pre-generated key for a reflashable secure bootloader is available, "
"due to signing configuration."
"\nTo generate one, you can use this command:"
"\n\t${espsecurepy} generate_flash_encryption_key ${secure_bootloader_key}"
"\n\t${espsecurepy} generate-flash-encryption-key ${secure_bootloader_key}"
"\nIf a signing key is present, then instead use:"
"\n\t${espsecurepy} digest_private_key "
"\n\t${espsecurepy} digest-private-key "
"--keylen (192/256) --keyfile KEYFILE "
"${secure_bootloader_key}")
endif()
@@ -157,7 +157,7 @@ if(CONFIG_SECURE_BOOTLOADER_REFLASHABLE)
add_custom_command(OUTPUT "${bootloader_digest_bin}"
COMMAND ${CMAKE_COMMAND} -E echo "DIGEST ${bootloader_digest_bin}"
COMMAND ${espsecure_py_cmd} digest_secure_bootloader --keyfile "${secure_bootloader_key}"
COMMAND ${espsecure_py_cmd} digest-secure-bootloader --keyfile "${secure_bootloader_key}"
-o "${bootloader_digest_bin}" "${CMAKE_BINARY_DIR}/bootloader.bin"
MAIN_DEPENDENCY "${CMAKE_BINARY_DIR}/.bin_timestamp"
DEPENDS gen_secure_bootloader_key gen_project_binary
@@ -178,7 +178,7 @@ if(CONFIG_SECURE_BOOT_V2_ENABLED)
"Secure Boot Signing Key Not found."
"\nGenerate the Secure Boot V2 RSA-PSS 3072 Key."
"\nTo generate one, you can use this command:"
"\n\t${espsecurepy} generate_signing_key --version 2 your_key.pem"
"\n\t${espsecurepy} generate-signing-key --version 2 your_key.pem"
)
endif()
@@ -224,7 +224,7 @@ elseif(CONFIG_SECURE_BOOTLOADER_REFLASHABLE)
COMMAND ${CMAKE_COMMAND} -E echo
"Burn secure boot key to efuse using:"
COMMAND ${CMAKE_COMMAND} -E echo
"\t${espefusepy} burn_key secure_boot_v1 ${secure_bootloader_key}"
"\t${espefusepy} burn-key secure_boot_v1 ${secure_bootloader_key}"
COMMAND ${CMAKE_COMMAND} -E echo
"First time flash command is:"
COMMAND ${CMAKE_COMMAND} -E echo
@@ -255,8 +255,8 @@ elseif(
COMMAND ${CMAKE_COMMAND} -E echo
"To sign the bootloader with additional private keys."
COMMAND ${CMAKE_COMMAND} -E echo
"\t${espsecurepy} sign_data -k secure_boot_signing_key2.pem -v 2 \
--append_signatures -o signed_bootloader.bin build/bootloader/bootloader.bin"
"\t${espsecurepy} sign-data -k secure_boot_signing_key2.pem -v 2 \
--append-signatures -o signed_bootloader.bin build/bootloader/bootloader.bin"
COMMAND ${CMAKE_COMMAND} -E echo
"Secure boot enabled, so bootloader not flashed automatically."
COMMAND ${CMAKE_COMMAND} -E echo

4
components/bootloader_support/CMakeLists.txt
View File

@@ -167,7 +167,7 @@ if(CONFIG_SECURE_SIGNED_APPS AND (CONFIG_SECURE_BOOT_V1_ENABLED OR CONFIG_SECURE
ABSOLUTE BASE_DIR "${CMAKE_CURRENT_BINARY_DIR}")
add_custom_command(OUTPUT "${secure_boot_verification_key}"
COMMAND ${espsecure_py_cmd}
extract_public_key --keyfile "${secure_boot_signing_key}"
extract-public-key --keyfile "${secure_boot_signing_key}"
"${secure_boot_verification_key}"
DEPENDS ${secure_boot_signing_key}
VERBATIM)
@@ -195,7 +195,7 @@ if(CONFIG_SECURE_SIGNED_APPS AND (CONFIG_SECURE_BOOT_V1_ENABLED OR CONFIG_SECURE
add_custom_command(OUTPUT "${secure_boot_verification_key}"
COMMAND ${espsecure_py_cmd}
extract_public_key --keyfile "${secure_boot_signing_key}"
extract-public-key --keyfile "${secure_boot_signing_key}"
"${secure_boot_verification_key}"
WORKING_DIRECTORY ${project_dir}
DEPENDS ${secure_boot_signing_key}

4
components/bootloader_support/bootloader_flash/include/bootloader_flash_override.h
View File

@@ -89,8 +89,8 @@ void bootloader_write_status_8b_xmc25qu64a(unsigned new_status);
/* Array of known flash chips and data to enable Quad I/O mode
Manufacturer & flash ID can be tested by running "esptool.py
flash_id"
Manufacturer & flash ID can be tested by running "esptool
flash-id"
If manufacturer ID matches, and flash ID ORed with flash ID mask
matches, enable_qio_mode() will execute "Read Cmd", test if bit

4
components/bootloader_support/bootloader_flash/src/flash_qio_mode.c
View File

@@ -25,8 +25,8 @@ ESP_LOG_ATTR_TAG(TAG, "qio_mode");
/* Array of known flash chips and data to enable Quad I/O mode
Manufacturer & flash ID can be tested by running "esptool.py
flash_id"
Manufacturer & flash ID can be tested by running "esptool
flash-id"
If manufacturer ID matches, and flash ID ORed with flash ID mask
matches, enable_qio_mode() will execute "Read Cmd", test if bit

2
components/bootloader_support/include/esp_secure_boot.h
View File

@@ -137,7 +137,7 @@ static inline bool esp_secure_boot_enabled(void)
* If first boot gets interrupted after calling this function
* but before esp_secure_boot_permanently_enable() is called, then
* the key burned on EFUSE will not be regenerated, unless manually
* done using espefuse.py tool
* done using espefuse tool
*
* @return ESP_OK if secure boot digest is generated
* successfully or found to be already present

2
components/bootloader_support/src/esp_image_format.c
View File

@@ -173,7 +173,7 @@ static esp_err_t image_load(esp_image_load_mode_t mode, const esp_partition_pos_
#else // Secure boot not enabled
// For secure boot V1 on ESP32, we don't calculate SHA or verify signature on bootloaders.
// (For non-secure boot, we don't verify any SHA-256 hash appended to the bootloader because
// esptool.py may have rewritten the header - rely on esptool.py having verified the bootloader at flashing time, instead.)
// esptool may have rewritten the header - rely on esptool having verified the bootloader at flashing time, instead.)
verify_sha = !is_bootloader(part->offset) && do_verify;
#endif

2
components/esp_tee/subproject/CMakeLists.txt
View File

@@ -82,7 +82,7 @@ if(CONFIG_SECURE_BOOT_V2_ENABLED)
"Secure Boot Signing Key Not found."
"\nGenerate the Secure Boot V2 RSA-PSS 3072 Key."
"\nTo generate one, you can use this command:"
"\n\t${espsecure_py_cmd} generate_signing_key --version 2 your_key.pem"
"\n\t${espsecure_py_cmd} generate-signing-key --version 2 your_key.pem"
)
endif()

2
components/esp_tee/test_apps/tee_cli_app/README.md
View File

@@ -29,7 +29,7 @@ Configure the Secure Storage mode for determining how the NVS XTS encryption key
openssl rand -out hmac_key_file.bin 32
# Programming the HMAC key (256-bit) in eFuse
# Here, BLOCK_KEYx is a free eFuse key-block between BLOCK_KEY0 and BLOCK_KEY5
espefuse.py -p PORT burn_key BLOCK_KEYx hmac_key_file.bin HMAC_UP
espefuse -p PORT burn-key BLOCK_KEYx hmac_key_file.bin HMAC_UP
```
### Build and Flash

12
components/esp_tee/test_apps/tee_test_fw/conftest.py
View File

@@ -172,7 +172,7 @@ class TEESerial(IdfSerial):
flash_size = self._get_flash_size()
esptool.main(
f'--no-stub write_flash {offs} {bootloader_path} --force {encrypt} --flash_size {flash_size}'.split(),
f'--no-stub write-flash {offs} {bootloader_path} --force {encrypt} --flash-size {flash_size}'.split(),
esp=self.esp,
)
@@ -189,7 +189,7 @@ class TEESerial(IdfSerial):
temp_file.flush()
esptool.main(
f'--no-stub write_flash {offs} {temp_file.name} --flash_size {flash_size}'.split(), esp=self.esp
f'--no-stub write-flash {offs} {temp_file.name} --flash-size {flash_size}'.split(), esp=self.esp
)
else:
self.erase_partition(partition)
@@ -201,11 +201,11 @@ class TEESerial(IdfSerial):
flash_size = self._get_flash_size()
flash_file = bin_path
args = f'{no_stub} write_flash {offs} {flash_file}'.split()
args = f'{no_stub} write-flash {offs} {flash_file}'.split()
if encrypt:
args.append('--encrypt')
args += f'--flash_size {flash_size}'.split()
args += f'--flash-size {flash_size}'.split()
esptool.main(args, esp=self.esp)
@@ -229,10 +229,10 @@ class TEESerial(IdfSerial):
keyfile = self.app.sdkconfig.get('SECURE_BOOT_SIGNING_KEY')
espsecure.main(
[
'sign_data',
'sign-data',
'--version',
'2',
'--append_signatures',
'--append-signatures',
'--keyfile',
keyfile,
'--output',

14
components/esptool_py/Kconfig.projbuild
View File

@@ -73,7 +73,7 @@ menu "Serial flasher config"
bool "DTR Mode"
endchoice
# Note: we use esptool.py to flash bootloader in
# Note: we use esptool to flash bootloader in
# dio mode for QIO/QOUT, bootloader then upgrades
# itself to quad mode during initialisation
config ESPTOOLPY_FLASHMODE
@@ -160,7 +160,7 @@ menu "Serial flasher config"
prompt "Before flashing"
default ESPTOOLPY_BEFORE_RESET
help
Configure whether esptool.py should reset the ESP32 before flashing.
Configure whether esptool should reset the ESP32 before flashing.
Automatic resetting depends on the RTS & DTR signals being
wired from the serial port to the ESP32. Most USB development
@@ -174,14 +174,14 @@ menu "Serial flasher config"
config ESPTOOLPY_BEFORE
string
default "default_reset" if ESPTOOLPY_BEFORE_RESET
default "no_reset" if ESPTOOLPY_BEFORE_NORESET
default "default-reset" if ESPTOOLPY_BEFORE_RESET
default "no-reset" if ESPTOOLPY_BEFORE_NORESET
choice ESPTOOLPY_AFTER
prompt "After flashing"
default ESPTOOLPY_AFTER_RESET
help
Configure whether esptool.py should reset the ESP32 after flashing.
Configure whether esptool should reset the ESP32 after flashing.
Automatic resetting depends on the RTS & DTR signals being
wired from the serial port to the ESP32. Most USB development
@@ -195,8 +195,8 @@ menu "Serial flasher config"
config ESPTOOLPY_AFTER
string
default "hard_reset" if ESPTOOLPY_AFTER_RESET
default "no_reset" if ESPTOOLPY_AFTER_NORESET
default "hard-reset" if ESPTOOLPY_AFTER_RESET
default "no-reset" if ESPTOOLPY_AFTER_NORESET
config ESPTOOLPY_MONITOR_BAUD
int

6
components/esptool_py/espefuse.cmake
View File

@@ -1,11 +1,11 @@
cmake_minimum_required(VERSION 3.22)
# Executes a espefuse.py command and returns a cleaned log
# Executes a espefuse command and returns a cleaned log
function(espefuse_cmd cmd output_log)
# espefuse_cmd can be called from a project's CMakeLists.txt file, which
# can invoke this function in CMake scripting mode (-P). If that is the case,
# we do not have access to convenience functions like idf_component_get_property.
# In scripting mode, the path to espefuse.py must be passed in via the
# In scripting mode, the path to espefuse must be passed in via the
# 'ESPEFUSEPY' variable using the -D flag.
#
# When called during the normal build configuration phase, 'ESPEFUSEPY' is not
@@ -36,7 +36,7 @@ function(espefuse_cmd cmd output_log)
set(${output_log} "${final_log}" PARENT_SCOPE)
endfunction()
# Reads efuses "espefuse.py summary" and returns JSON string
# Reads efuses "espefuse summary" and returns JSON string
function(espefuse_get_json_summary json_str)
espefuse_cmd("summary;--format;json" output_log)
set(${json_str} "${output_log}" PARENT_SCOPE)

5
components/esptool_py/esptool/espefuse.py
View File

@@ -8,4 +8,9 @@ import subprocess
import sys
if __name__ == '__main__':
print(
"Warning: DEPRECATED: 'espefuse.py' wrapper is deprecated. "
"Please use 'espefuse' or 'python -m espefuse' instead.",
file=sys.stderr,
)
sys.exit(subprocess.run([sys.executable, '-m', 'espefuse'] + sys.argv[1:]).returncode)

5
components/esptool_py/esptool/espsecure.py
View File

@@ -8,4 +8,9 @@ import subprocess
import sys
if __name__ == '__main__':
print(
"Warning: DEPRECATED: 'espsecure.py' wrapper is deprecated. "
"Please use 'espsecure' or 'python -m espsecure' instead.",
file=sys.stderr,
)
sys.exit(subprocess.run([sys.executable, '-m', 'espsecure'] + sys.argv[1:]).returncode)

4
components/esptool_py/esptool/esptool.py
View File

@@ -7,4 +7,8 @@ import subprocess
import sys
if __name__ == '__main__':
print(
"Warning: DEPRECATED: 'esptool.py' wrapper is deprecated. Please use 'esptool' or 'python -m esptool' instead.",
file=sys.stderr,
)
sys.exit(subprocess.run([sys.executable, '-u', '-m', 'esptool'] + sys.argv[1:]).returncode)

6
components/esptool_py/flasher_args.json.in
View File

@@ -1,7 +1,7 @@
{
"write_flash_args" : [ "--flash_mode", "${ESPFLASHMODE}",
"--flash_size", "${ESPFLASHSIZE}",
"--flash_freq", "${ESPFLASHFREQ}" ],
"write_flash_args" : [ "--flash-mode", "${ESPFLASHMODE}",
"--flash-size", "${ESPFLASHSIZE}",
"--flash-freq", "${ESPFLASHFREQ}" ],
"flash_settings" : {
"flash_mode": "${ESPFLASHMODE}",
"flash_size": "${ESPFLASHSIZE}",

69
components/esptool_py/project_include.cmake
View File

@@ -149,15 +149,15 @@ endfunction()
# esptool_py_flash_target
#
# @brief Create a flash target that can flash multiple images using esptool.py.
# @brief Create a flash target that can flash multiple images using esptool.
#
# This function is the core of the flashing mechanism. It creates a custom target
# and attaches the actual esptool.py command to it as a POST_BUILD step. This
# and attaches the actual esptool command to it as a POST_BUILD step. This
# ensures that the flash command only runs after all of the target's dependencies
# (like binary generation) have been successfully built.
#
# It works by generating an argument file (`<prefix>_args`) that contains all the
# necessary parameters for esptool.py. This file's content is constructed using
# necessary parameters for esptool. This file's content is constructed using
# CMake generator expressions, which are resolved at build time. This allows the
# final list of binaries to be flashed to be collected from properties on the
# target.
@@ -166,8 +166,8 @@ endfunction()
# target, which handles the logic for encrypting all or a subset of the binaries.
#
# @param[in] target_name Name of the flash target to create
# @param[in] main_args Main esptool.py arguments (before write_flash command)
# @param[in] sub_args Sub-arguments for write_flash command (flash mode, frequency, size)
# @param[in] main_args Main esptool arguments (before write-flash command)
# @param[in] sub_args Sub-arguments for write-flash command (flash mode, frequency, size)
# @param[in, optional] FILENAME_PREFIX (single value) Prefix for generated argument files.
# If not specified, uses target_name as prefix.
# @param[in, optional] ALWAYS_PLAINTEXT (option) Force all images to be flashed as plain text.
@@ -196,7 +196,7 @@ function(esptool_py_flash_target target_name main_args sub_args)
COMMAND ${CMAKE_COMMAND}
-D "IDF_PATH=${idf_path}"
-D "SERIAL_TOOL=${esptool_py_cmd}"
-D "SERIAL_TOOL_ARGS=${main_args};write_flash;@${filename_prefix}_args"
-D "SERIAL_TOOL_ARGS=${main_args};write-flash;@${filename_prefix}_args"
-D "WORKING_DIRECTORY=${build_dir}"
-P ${esptool_py_dir}/run_serial_tool.cmake
WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
@@ -242,7 +242,7 @@ $<JOIN:$<TARGET_PROPERTY:${target_name},IMAGES>,\n>")
COMMAND ${CMAKE_COMMAND}
-D "IDF_PATH=${idf_path}"
-D "SERIAL_TOOL=${esptool_py_cmd}"
-D "SERIAL_TOOL_ARGS=${main_args};write_flash;@encrypted_${filename_prefix}_args"
-D "SERIAL_TOOL_ARGS=${main_args};write-flash;@encrypted_${filename_prefix}_args"
-D "WORKING_DIRECTORY=${build_dir}"
-P ${esptool_py_dir}/run_serial_tool.cmake
WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
@@ -250,7 +250,7 @@ $<JOIN:$<TARGET_PROPERTY:${target_name},IMAGES>,\n>")
VERBATIM
)
# Generate the parameters for esptool.py command
# Generate the parameters for esptool command
# In case we have both non encrypted and encrypted files to flash, we
# can use --encrypt-files parameter to specify which ones should be
# encrypted.
@@ -258,7 +258,7 @@ $<JOIN:$<TARGET_PROPERTY:${target_name},IMAGES>,\n>")
# --encrypt parameter.
# As the properties ENCRYPTED_IMAGES and NON_ENCRYPTED_IMAGES have not
# been generated yet, we must use CMake expression generator to test
# which esptool.py options we can use.
# which esptool options we can use.
# The variable has_non_encrypted_image will be evaluated to "1" if some
# images must not be encrypted. This variable will be used in the next
@@ -350,30 +350,35 @@ endfunction()
# __esptool_py_setup_tools
#
# @brief Sets up esptool.py, espsecure.py, and espefuse.py tool commands.
# @brief Sets up esptool, espsecure, and espefuse tool commands.
#
# This function retrieves the necessary paths and Python interpreter, then
# constructs the full command-line strings for `esptool.py`, `espsecure.py`,
# and `espefuse.py`. It stores these commands as properties of the `esptool_py`
# constructs the full command-line strings for `esptool`, `espsecure`,
# and `espefuse`. It stores these commands as properties of the `esptool_py`
# component for later use by other functions or components.
function(__esptool_py_setup_tools)
idf_build_get_property(target IDF_TARGET)
idf_build_get_property(python PYTHON)
idf_component_get_property(esptool_py_dir esptool_py COMPONENT_DIR)
set(esptool_py_cmd ${python} "$ENV{ESPTOOL_WRAPPER}" "${esptool_py_dir}/esptool/esptool.py" --chip ${target})
# If ESPTOOL_WRAPPER is set, use it as the wrapper script, otherwise use 'python -m esptool'
if(DEFINED ENV{ESPTOOL_WRAPPER} AND NOT "$ENV{ESPTOOL_WRAPPER}" STREQUAL "")
set(esptool_py_cmd ${python} "$ENV{ESPTOOL_WRAPPER}" "esptool" "--chip" ${target})
else()
set(esptool_py_cmd ${python} "-m" "esptool" "--chip" ${target})
endif()
idf_component_set_property(esptool_py ESPTOOLPY_CMD "${esptool_py_cmd}")
set(espsecure_py_cmd ${python} "${esptool_py_dir}/esptool/espsecure.py")
set(espsecure_py_cmd ${python} "-m" "espsecure")
idf_component_set_property(esptool_py ESPSECUREPY_CMD "${espsecure_py_cmd}")
set(espefuse_py_cmd ${python} "${esptool_py_dir}/esptool/espefuse.py")
set(espefuse_py_cmd ${python} "-m" "espefuse")
idf_component_set_property(esptool_py ESPEFUSEPY_CMD "${espefuse_py_cmd}")
endfunction()
# __esptool_py_setup_esptool_py_args
#
# @brief Sets up esptool.py arguments for elf2image and flash targets.
# @brief Sets up esptool arguments for elf2image and flash targets.
#
# This function determines the appropriate flash mode, frequency, and size based
# on the project configuration (Kconfig values). It assembles argument lists
@@ -398,9 +403,9 @@ function(__esptool_py_setup_esptool_py_args)
set(ESPFLASHSIZE ${CONFIG_ESPTOOLPY_FLASHSIZE})
set(esptool_elf2image_args
--flash_mode ${ESPFLASHMODE}
--flash_freq ${ESPFLASHFREQ}
--flash_size ${ESPFLASHSIZE}
--flash-mode ${ESPFLASHMODE}
--flash-freq ${ESPFLASHFREQ}
--flash-size ${ESPFLASHSIZE}
)
if(BOOTLOADER_BUILD AND CONFIG_SECURE_BOOT_V2_ENABLED)
@@ -408,7 +413,7 @@ function(__esptool_py_setup_esptool_py_args)
# If CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES is NOT set, the bootloader
# image generated is not 4KB aligned for external HSM to sign it readily.
# Following esptool option --pad-to-size 4KB generates a 4K aligned bootloader image.
# In case of signing during build, espsecure.py "sign_data" operation handles the 4K alignment of the image.
# In case of signing during build, espsecure "sign-data" operation handles the 4K alignment of the image.
if(NOT CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES)
list(APPEND esptool_elf2image_args --pad-to-size 4KB)
endif()
@@ -469,7 +474,7 @@ function(__esptool_py_setup_esptool_py_args)
if(CONFIG_SECURE_BOOT OR CONFIG_SECURE_FLASH_ENC_ENABLED)
# If security enabled then override post flash option
list(APPEND esptool_flash_main_args "--after=no_reset")
list(APPEND esptool_flash_main_args "--after=no-reset")
else()
list(APPEND esptool_flash_main_args "--after=${CONFIG_ESPTOOLPY_AFTER}")
endif()
@@ -481,7 +486,7 @@ function(__esptool_py_setup_esptool_py_args)
# Save flash arguments to component property
idf_component_set_property(esptool_py FLASH_ARGS "${esptool_flash_main_args}")
idf_component_set_property(esptool_py FLASH_SUB_ARGS
"--flash_mode ${ESPFLASHMODE} --flash_freq ${ESPFLASHFREQ} --flash_size ${ESPFLASHSIZE}")
"--flash-mode ${ESPFLASHMODE} --flash-freq ${ESPFLASHFREQ} --flash-size ${ESPFLASHSIZE}")
# Save arguments for flasher_args.json
idf_component_set_property(esptool_py ESPFLASHMODE "${ESPFLASHMODE}")
@@ -491,7 +496,7 @@ endfunction()
# __ensure_esptool_py_setup
#
# @brief Ensures that the esptool.py setup functions have been called once.
# @brief Ensures that the esptool setup functions have been called once.
#
# This function acts as an initializer. It checks if the esptool_py
# setup has already been performed by checking a component property. If not, it
@@ -512,7 +517,7 @@ endfunction()
# @brief Sets up the primary target for generating a .bin file from an .elf file.
#
# This function creates the custom command and target required to generate a
# project binary (`.bin`) file from the final `.elf` executable. It uses `esptool.py
# project binary (`.bin`) file from the final `.elf` executable. It uses `esptool
# elf2image` to perform the conversion and manages dependencies to ensure the
# binary is regenerated whenever the ELF file changes.
#
@@ -530,7 +535,7 @@ function(__idf_build_binary OUTPUT_BIN_FILENAME TARGET_NAME)
idf_build_get_property(elf_name EXECUTABLE_NAME)
idf_build_get_post_elf_dependencies("${elf_name}.elf" post_elf_deps)
# Get esptool.py arguments for elf2image target
# Get esptool arguments for elf2image target
idf_component_get_property(esptool_elf2image_args esptool_py ESPTOOL_PY_ELF2IMAGE_ARGS)
# Create a custom command and target to generate binary from elf file
@@ -574,7 +579,7 @@ endfunction()
# @brief Sets up targets for generating a signed binary for Secure Boot.
#
# If Secure Boot is enabled, this function adds a custom command to sign the
# previously generated application binary using `espsecure.py`. It creates a
# previously generated application binary using `espsecure`. It creates a
# target that depends on the unsigned binary and produces a signed one, which
# is required for the bootloader to authenticate the application.
#
@@ -616,7 +621,7 @@ function(__idf_build_secure_binary UNSIGNED_BIN_FILENAME SIGNED_BIN_FILENAME TAR
endif()
add_custom_command(OUTPUT "${build_dir}/.signed_bin_timestamp"
COMMAND ${espsecure_py_cmd} sign_data
COMMAND ${espsecure_py_cmd} sign-data
--version ${secure_boot_version} --keyfile "${secure_boot_signing_key}"
-o "${build_dir}/${SIGNED_BIN_FILENAME}" "${build_dir}/${UNSIGNED_BIN_FILENAME}"
COMMAND ${CMAKE_COMMAND} -E echo "Generated signed binary image ${build_dir}/${SIGNED_BIN_FILENAME}"
@@ -651,7 +656,7 @@ function(__idf_build_secure_binary UNSIGNED_BIN_FILENAME SIGNED_BIN_FILENAME TAR
COMMAND ${CMAKE_COMMAND} -E echo
"${comment_text}"
COMMAND ${CMAKE_COMMAND} -E echo
"\t${espsecurepy} sign_data --keyfile KEYFILE --version ${secure_boot_version} \
"\t${espsecurepy} sign-data --keyfile KEYFILE --version ${secure_boot_version} \
${build_dir}/${UNSIGNED_BIN_FILENAME}"
VERBATIM)
endif()
@@ -659,7 +664,7 @@ endfunction()
# __esptool_py_setup_utility_targets
#
# @brief Sets up common utility targets like `erase_flash`, `merge-bin`, and `monitor`
# @brief Sets up common utility targets like `erase-flash`, `merge-bin`, and `monitor`
#
function(__esptool_py_setup_utility_targets)
__ensure_esptool_py_setup()
@@ -673,18 +678,18 @@ function(__esptool_py_setup_utility_targets)
idf_component_get_property(esptool_py_cmd esptool_py ESPTOOLPY_CMD)
idf_component_get_property(esptool_py_dir esptool_py COMPONENT_DIR)
add_custom_target(erase_flash
add_custom_target(erase-flash
COMMAND ${CMAKE_COMMAND}
-D "IDF_PATH=${idf_path}"
-D "SERIAL_TOOL=${esptool_py_cmd}"
-D "SERIAL_TOOL_ARGS=erase_flash"
-D "SERIAL_TOOL_ARGS=erase-flash"
-P run_serial_tool.cmake
WORKING_DIRECTORY ${esptool_py_dir}
USES_TERMINAL
VERBATIM
)
set(MERGE_BIN_ARGS merge_bin)
set(MERGE_BIN_ARGS merge-bin)
if(DEFINED ENV{ESP_MERGE_BIN_OUTPUT})
list(APPEND MERGE_BIN_ARGS "-o" "$ENV{ESP_MERGE_BIN_OUTPUT}")
else()

32
components/hal/test_apps/crypto/README.md
View File

@@ -74,46 +74,46 @@ This contains tests for the following features of the crypto peripherals:
> **_NOTE:_** The verification tests for the HMAC, Digital Signature, ECDSA and XTS-AES peripherals would get exercised only by enabling the example config in an FPGA environment.
# Burning the HMAC key
The HMAC tests need an HMAC key to be burned in the `BLOCK_KEY4` and `BLOCK_KEY5` of the efuses. As this verification application is independent of the efuse component, the user needs to manually burn the keys and their key purposes using `espefuse.py`.
The HMAC tests need an HMAC key to be burned in the `BLOCK_KEY4` and `BLOCK_KEY5` of the efuses. As this verification application is independent of the efuse component, the user needs to manually burn the keys and their key purposes using `espefuse`.
```bash
espefuse.py -p $ESPPORT burn_key BLOCK_KEY4 main/hmac/hmac_key.bin HMAC_DOWN_JTAG
espefuse -p $ESPPORT burn-key BLOCK_KEY4 main/hmac/hmac_key.bin HMAC_DOWN_JTAG
espefuse.py -p $ESPPORT burn_key BLOCK_KEY5 main/hmac/hmac_key.bin HMAC_UP
espefuse -p $ESPPORT burn-key BLOCK_KEY5 main/hmac/hmac_key.bin HMAC_UP
```
# Burning the HMAC keys for Digital Signature tests
The tests needs some HMAC keys to be burned in the `BLOCK_KEY0`, `BLOCK_KEY1` and `BLOCK_KEY2` of the efuses. As this verification application is independent of the efuse component, the user needs to manually burn the keys and their key purposes using `espefuse.py`.
The tests needs some HMAC keys to be burned in the `BLOCK_KEY0`, `BLOCK_KEY1` and `BLOCK_KEY2` of the efuses. As this verification application is independent of the efuse component, the user needs to manually burn the keys and their key purposes using `espefuse`.
If SOC_DS_SIGNATURE_MAX_BIT_LEN == 3072:
```bash
espefuse.py -p $ESPPORT burn_key BLOCK_KEY0 main/ds/keys/3072/ds_key1.bin HMAC_DOWN_DIGITAL_SIGNATURE
espefuse -p $ESPPORT burn-key BLOCK_KEY0 main/ds/keys/3072/ds_key1.bin HMAC_DOWN_DIGITAL_SIGNATURE
espefuse.py -p $ESPPORT burn_key BLOCK_KEY1 main/ds/keys/3072/ds_key2.bin HMAC_DOWN_DIGITAL_SIGNATURE
espefuse -p $ESPPORT burn-key BLOCK_KEY1 main/ds/keys/3072/ds_key2.bin HMAC_DOWN_DIGITAL_SIGNATURE
espefuse.py -p $ESPPORT burn_key BLOCK_KEY2 main/ds/keys/3072/ds_key3.bin HMAC_DOWN_DIGITAL_SIGNATURE
espefuse -p $ESPPORT burn-key BLOCK_KEY2 main/ds/keys/3072/ds_key3.bin HMAC_DOWN_DIGITAL_SIGNATURE
```
If SOC_DS_SIGNATURE_MAX_BIT_LEN == 4096:
```bash
espefuse.py -p $ESPPORT burn_key BLOCK_KEY0 main/ds/keys/4096/ds_key1.bin HMAC_DOWN_DIGITAL_SIGNATURE
espefuse -p $ESPPORT burn-key BLOCK_KEY0 main/ds/keys/4096/ds_key1.bin HMAC_DOWN_DIGITAL_SIGNATURE
espefuse.py -p $ESPPORT burn_key BLOCK_KEY1 main/ds/keys/4096/ds_key2.bin HMAC_DOWN_DIGITAL_SIGNATURE
espefuse -p $ESPPORT burn-key BLOCK_KEY1 main/ds/keys/4096/ds_key2.bin HMAC_DOWN_DIGITAL_SIGNATURE
espefuse.py -p $ESPPORT burn_key BLOCK_KEY2 main/ds/keys/4096/ds_key3.bin HMAC_DOWN_DIGITAL_SIGNATURE
espefuse -p $ESPPORT burn-key BLOCK_KEY2 main/ds/keys/4096/ds_key3.bin HMAC_DOWN_DIGITAL_SIGNATURE
```
# Burning the ECDSA keys
By default, ECDSA tests are disabled. You can enable it after disabling HMAC & DS tests using `idf.py menuconfig -> Test App Configuration -> Enable ECDSA Peripheral test cases`
The ECDSA tests need some ECDSA keys to be burned in the `BLOCK_KEY3` and `BLOCK_KEY4` of the efuses. As this verification application is independent of the efuse component, the user needs to manually burn the keys and their key purposes using `espefuse.py`.
The ECDSA tests need some ECDSA keys to be burned in the `BLOCK_KEY3` and `BLOCK_KEY4` of the efuses. As this verification application is independent of the efuse component, the user needs to manually burn the keys and their key purposes using `espefuse`.
```bash
espefuse.py -p $ESPPORT burn_key BLOCK_KEY3 main/ecdsa/ecdsa192_priv_key.pem ECDSA_KEY
espefuse -p $ESPPORT burn-key BLOCK_KEY3 main/ecdsa/ecdsa192_priv_key.pem ECDSA_KEY
espefuse.py -p $ESPPORT burn_key BLOCK_KEY4 main/ecdsa/ecdsa256_priv_key.pem ECDSA_KEY
espefuse -p $ESPPORT burn-key BLOCK_KEY4 main/ecdsa/ecdsa256_priv_key.pem ECDSA_KEY
```
# Burning the XTS-AES key
@@ -122,18 +122,18 @@ By default, XTS-AES tests are disabled. You can enable it after disabling Digita
The XTS-AES tests contain tests for both the modes, XTS-AES-128 and XTS-AES-256, but as per the peripheral design we can test only one mode at a time. Thus, we need to burn one key at a time.
These keys can be burned in the `BLOCK_KEY0` (for XTS-AES-128), whereas, `BLOCK_KEY0` and `BLOCK_KEY1` (for XTS-AES-256) of the efuses. As this verification application is independent of the efuse component, the user needs to manually burn the keys and their key purposes using `espefuse.py`.
These keys can be burned in the `BLOCK_KEY0` (for XTS-AES-128), whereas, `BLOCK_KEY0` and `BLOCK_KEY1` (for XTS-AES-256) of the efuses. As this verification application is independent of the efuse component, the user needs to manually burn the keys and their key purposes using `espefuse`.
While running the XTS-AES-128 tests:
```bash
espefuse.py -p $ESPPORT burn_key BLOCK_KEY0 main/xts_aes/xts_aes_128_key.bin XTS_AES_128_KEY
espefuse -p $ESPPORT burn-key BLOCK_KEY0 main/xts_aes/xts_aes_128_key.bin XTS_AES_128_KEY
```
While running the XTS-AES-256 tests:
```bash
espefuse.py -p $ESPPORT burn_key BLOCK_KEY0 main/xts_aes/xts_aes_256_key.bin XTS_AES_256_KEY
espefuse -p $ESPPORT burn-key BLOCK_KEY0 main/xts_aes/xts_aes_256_key.bin XTS_AES_256_KEY
```
# Building

24
components/hal/test_apps/crypto/main/xts_aes/generate_xts_aes_encrypt_test_cases.py
View File

@@ -1,5 +1,5 @@
#!/usr/bin/env python
# SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
# SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
# SPDX-License-Identifier: Unlicense OR CC0-1.0
# import struct
import sys
@@ -17,31 +17,35 @@ def encrypt_and_print_aes_xts(keyfile:str, plaintext:bytes, address:int) -> None
with open(inputfile.name, 'wb') as f:
f.write(plaintext)
espsecure.main([
'encrypt_flash_data',
'--aes_xts',
espsecure.main(
[
'encrypt-flash-data',
'--aes-xts',
'--keyfile',
f'{keyfile}',
'--output',
f'{outputfile.name}',
'--address',
f'{address}',
f'{inputfile.name}'
])
f'{inputfile.name}',
]
)
with open(outputfile.name, 'rb') as f:
ciphertext = f.read()
assert len(ciphertext) == len(plaintext)
print((
# fmt: off
print(
'{\n'
f' .address = 0x{address:08x},\n'
f' .address = {address:#08x},\n'
' .ciphertext = {\n'
f'{as_c_array(ciphertext)}\n'
' },\n'
'},'
))
)
# fmt: on
def as_c_array(byte_arr: bytes) -> str:
@@ -50,7 +54,7 @@ def as_c_array(byte_arr: bytes) -> str:
for idx, byte in enumerate(byte_arr):
if idx % bytes_per_line == 0:
hex_str += ' '
hex_str += '0x{:02x}, '.format(byte)
hex_str += f'{byte:#02x}, '
if idx % bytes_per_line == bytes_per_line - 1 and idx != (len(byte_arr) - 1):
hex_str += '\n'

6
components/hal/test_apps/crypto/pytest_crypto.py
View File

@@ -32,9 +32,9 @@ def test_xts_aes_encryption(negotiated_key: bytes, plaintext_data: bytes, encryp
plaintext_file.write(plaintext_data)
command = [
'espsecure.py',
'encrypt_flash_data',
'--aes_xts',
'espsecure',
'encrypt-flash-data',
'--aes-xts',
'--keyfile',
'test/negotiated_key.bin',
'--address',

2
components/mbedtls/Kconfig
View File

@@ -1461,7 +1461,7 @@ menu "mbedTLS"
with key purpose set to ECDSA_KEY.
If no key is burnt, it will report an error
The key should be burnt in little endian format. espefuse.py utility handles it internally
The key should be burnt in little endian format. espefuse utility handles it internally
but care needs to be taken while burning using esp_efuse APIs
config MBEDTLS_TEE_SEC_STG_ECDSA_SIGN

4
components/partition_table/CMakeLists.txt
View File

@@ -145,7 +145,7 @@ if(CONFIG_SECURE_SIGNED_APPS_ECDSA_SCHEME)
"${build_dir}/partition_table/${unsigned_partition_bin}")
add_custom_command(OUTPUT "${build_dir}/partition_table/${final_partition_bin}"
COMMAND ${espsecure_py_cmd} sign_data --version 1 --keyfile "${SECURE_BOOT_SIGNING_KEY}"
COMMAND ${espsecure_py_cmd} sign-data --version 1 --keyfile "${SECURE_BOOT_SIGNING_KEY}"
-o "${build_dir}/partition_table/${final_partition_bin}"
"${build_dir}/partition_table/${unsigned_partition_bin}"
DEPENDS "${build_dir}/partition_table/${unsigned_partition_bin}"
@@ -156,7 +156,7 @@ if(CONFIG_SECURE_SIGNED_APPS_ECDSA_SCHEME)
COMMAND ${CMAKE_COMMAND} -E echo
"Partition table built but not signed. Sign partition data before flashing:"
COMMAND ${CMAKE_COMMAND} -E echo
"\t${espsecurepy} sign_data --keyfile KEYFILE ${build_dir}/partition_table/${final_partition_bin}"
"\t${espsecurepy} sign-data --keyfile KEYFILE ${build_dir}/partition_table/${final_partition_bin}"
VERBATIM)
endif()
elseif(CONFIG_SECURE_SIGNED_APPS_RSA_SCHEME OR CONFIG_SECURE_SIGNED_APPS_ECDSA_V2_SCHEME)

39
components/partition_table/parttool.py
View File

@@ -17,7 +17,6 @@ import gen_esp32part as gen
__version__ = '2.2'
COMPONENTS_PATH = os.path.expandvars(os.path.join('$IDF_PATH', 'components'))
ESPTOOL_PY = os.path.join(COMPONENTS_PATH, 'esptool_py', 'esptool', 'esptool.py')
PARTITION_TABLE_OFFSET = 0x8000
@@ -100,7 +99,7 @@ class ParttoolTarget:
try:
self._call_esptool(
['read_flash', str(partition_table_offset), str(gen.MAX_PARTITION_LENGTH), temp_file.name]
['read-flash', str(partition_table_offset), str(gen.MAX_PARTITION_LENGTH), temp_file.name]
)
with open(temp_file.name, 'rb') as f:
partition_table = gen.PartitionTable.from_binary(f.read())
@@ -113,7 +112,7 @@ class ParttoolTarget:
# otherwise set `out` to file descriptor
# beware that the method does not close the file descriptor
def _call_esptool(self, args, out=None):
esptool_args = [sys.executable, ESPTOOL_PY] + self.esptool_args
esptool_args = [sys.executable, '-m', 'esptool'] + self.esptool_args
if self.port:
esptool_args += ['--port', self.port]
@@ -123,7 +122,7 @@ class ParttoolTarget:
esptool_args += args
print('Running %s...' % (' '.join(esptool_args)))
print(f'Running {" ".join(esptool_args)}...')
try:
subprocess.check_call(esptool_args, stdout=out, stderr=subprocess.STDOUT)
except subprocess.CalledProcessError as e:
@@ -140,7 +139,7 @@ class ParttoolTarget:
if not partition_id.part_list:
partition = partition[0]
else: # default boot partition
search = ['factory'] + ['ota_{}'.format(d) for d in range(16)]
search = ['factory'] + [f'ota_{d}' for d in range(16)]
for subtype in search:
partition = next(self.partition_table.find_by_type('app', subtype), None)
if partition:
@@ -153,11 +152,11 @@ class ParttoolTarget:
def erase_partition(self, partition_id):
partition = self.get_partition_info(partition_id)
self._call_esptool(['erase_region', str(partition.offset), str(partition.size)] + self.esptool_erase_args)
self._call_esptool(['erase-region', str(partition.offset), str(partition.size)] + self.esptool_erase_args)
def read_partition(self, partition_id, output):
partition = self.get_partition_info(partition_id)
self._call_esptool(['read_flash', str(partition.offset), str(partition.size), output] + self.esptool_read_args)
self._call_esptool(['read-flash', str(partition.offset), str(partition.size), output] + self.esptool_read_args)
def write_partition(self, partition_id, input, ignore_readonly=False): # noqa: A002
partition = self.get_partition_info(partition_id)
@@ -173,29 +172,27 @@ class ParttoolTarget:
if content_len > partition.size:
raise Exception('Input file size exceeds partition size')
self._call_esptool(['write_flash', str(partition.offset), input] + self.esptool_write_args)
self._call_esptool(['write-flash', str(partition.offset), input] + self.esptool_write_args)
def _write_partition(target, partition_id, input, ignore_readonly=False): # noqa: A002
target.write_partition(partition_id, input, ignore_readonly)
partition = target.get_partition_info(partition_id)
status("Written contents of file '{}' at offset 0x{:x}".format(input, partition.offset))
status(f"Written contents of file '{input}' at offset 0x{partition.offset:x}")
def _read_partition(target, partition_id, output):
target.read_partition(partition_id, output)
partition = target.get_partition_info(partition_id)
status(
"Read partition '{}' contents from device at offset 0x{:x} to file '{}'".format(
partition.name, partition.offset, output
)
f"Read partition '{partition.name}' contents from device at offset 0x{partition.offset:x} to file '{output}'"
)
def _erase_partition(target, partition_id):
target.erase_partition(partition_id)
partition = target.get_partition_info(partition_id)
status("Erased partition '{}' at offset 0x{:x}".format(partition.name, partition.offset))
status(f"Erased partition '{partition.name}' at offset 0x{partition.offset:x}")
def _get_partition_info(target, partition_id, info):
@@ -211,18 +208,18 @@ def _get_partition_info(target, partition_id, info):
try:
for p in partitions:
info_dict = {
'name': '{}'.format(p.name),
'type': '{}'.format(p.type),
'subtype': '{}'.format(p.subtype),
'offset': '0x{:x}'.format(p.offset),
'size': '0x{:x}'.format(p.size),
'encrypted': '{}'.format(p.encrypted),
'readonly': '{}'.format(p.readonly),
'name': f'{p.name}',
'type': f'{p.type}',
'subtype': f'{p.subtype}',
'offset': f'0x{p.offset:x}',
'size': f'0x{p.size:x}',
'encrypted': f'{p.encrypted}',
'readonly': f'{p.readonly}',
}
for i in info:
infos += [info_dict[i]]
except KeyError:
raise RuntimeError('Request for unknown partition info {}'.format(i))
raise RuntimeError(f'Request for unknown partition info {i}')
print(' '.join(infos))

4
components/spi_flash/test_apps/flash_encryption/encrypt_flash.sh
View File

@@ -10,5 +10,5 @@ dd if=/dev/zero of=key.bin bs=1 count=32
# Change the first byte as espsecure uses modules that won't
# allow symmetric keys
echo -ne \\xFF | dd conv=notrunc bs=1 count=1 of=key.bin
espefuse.py --do-not-confirm -p $ESPPORT burn_efuse SPI_BOOT_CRYPT_CNT 0x1
espefuse.py --do-not-confirm -p $ESPPORT burn_key BLOCK_KEY2 key.bin XTS_AES_128_KEY
espefuse --do-not-confirm -p $ESPPORT burn-efuse SPI_BOOT_CRYPT_CNT 0x1
espefuse --do-not-confirm -p $ESPPORT burn-key BLOCK_KEY2 key.bin XTS_AES_128_KEY

4
components/xtensa/trax/test/Makefile
View File

@@ -22,10 +22,10 @@ $(PROG_ELF): $(OBJ)
$(LD) $(LDFLAGS) -o $@ $<
$(PROG_BIN): $(PROG_ELF)
esptool.py --chip esp32 elf2image --output $@ --flash_freq 40m --flash_mode dio $<
esptool --chip esp32 elf2image --output $@ --flash-freq 40m --flash-mode dio $<
flash: $(PROG_BIN)
esptool.py --port $(ESPPORT) write_flash 0x1000 $(PROG_BIN)
esptool --port $(ESPPORT) write-flash 0x1000 $(PROG_BIN)
test:
rm -f $(TRACE_FILE)

2
docs/en/COPYRIGHT.rst
View File

@@ -145,7 +145,7 @@ Copyright (C) 2011 ChaN, all right reserved.
.. _Newlib: https://sourceware.org/newlib/
.. _Picolibc: https://keithp.com/picolibc/
.. _FreeRTOS: https://freertos.org/
.. _esptool.py: https://github.com/espressif/esptool
.. _esptool: https://github.com/espressif/esptool
.. _LWIP: https://savannah.nongnu.org/projects/lwip/
.. _TinyBasic: https://github.com/BleuLlama/TinyBasicPlus
.. _miniz: https://code.google.com/archive/p/miniz/

2
docs/en/api-guides/bootloader.rst
View File

@@ -202,7 +202,7 @@ If the bootloader grows too large then it can collide with the partition table,
The recovery bootloader feature enables safe OTA updates of the bootloader itself. When the eFuse field ``ESP_EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR`` is set, it specifies the flash address (in sectors) of the recovery bootloader. If the primary bootloader at {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} fails to load, the ROM bootloader attempts to load the recovery bootloader from this address.
- The eFuse can be set using ``espefuse.py`` or by calling :cpp:func:`esp_efuse_set_recovery_bootloader_offset()` in the user application.
- The eFuse can be set using ``espefuse`` or by calling :cpp:func:`esp_efuse_set_recovery_bootloader_offset()` in the user application.
- The address can be set using ``CONFIG_BOOTLOADER_RECOVERY_OFFSET``. This value must be a multiple of the flash sector size (0x1000 bytes). The Kconfig option helps ensure that the recovery bootloader does not overlap with existing partitions.
- Note that the eFuse field stores the offset in sectors. Setting it to the maximum value ``0xFFF`` disables the feature.
- The recovery bootloader image at the ``CONFIG_BOOTLOADER_RECOVERY_OFFSET`` is not flashed by default. It can be written as part of the OTA update process.

14
docs/en/api-guides/build-system.rst
View File

@@ -54,7 +54,7 @@ The ``idf.py`` command-line tool provides a front-end for easily managing your p
- CMake_, which configures the project to be built
- Ninja_ which builds the project
- `esptool.py`_ for flashing the target.
- `esptool`_ for flashing the target.
For more details about configuring the build system using ``idf.py``, please refer to :doc:`IDF Frontend <tools/idf-py>`.
@@ -718,7 +718,7 @@ Project_include.cmake
For components that have build requirements that must be evaluated before any component CMakeLists files are evaluated, you can create a file called ``project_include.cmake`` in the component directory. This CMake file is included when ``project.cmake`` is evaluating the entire project.
``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool`` command line arguments and the ``bootloader`` "special app".
Unlike component ``CMakeLists.txt`` files, when including a ``project_include.cmake`` file the current source directory (``CMAKE_CURRENT_SOURCE_DIR`` and working directory) is the project directory. Use the variable ``COMPONENT_DIR`` for the absolute directory of the component.
@@ -1109,7 +1109,7 @@ You can find more detailed information on how the project configuration works in
Flash Arguments
===============
There are some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py.
There are some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool and esptool write-flash arguments. It's simple to write a script to save binaries and esptool.
After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files:
@@ -1119,9 +1119,9 @@ After running a project build, the build directory contains binary output files
.. highlight:: bash
You can pass any of these flasher argument files to ``esptool.py`` as follows::
You can pass any of these flasher argument files to ``esptool`` as follows::
python esptool.py --chip esp32 write_flash @build/flash_project_args
esptool --chip esp32 write-flash @build/flash_project_args
Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line.
@@ -1567,7 +1567,7 @@ For integration into IDEs and other build systems, when CMake runs the build pro
- ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it.
- ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc.
- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_.
- ``flasher_args.json`` contains esptool arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool. See `Flash arguments`_.
- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc.
- ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values.
- ``config/kconfig_menus.json`` is a JSON-formatted version of the menus shown in menuconfig, for use in external IDE UIs.
@@ -1750,7 +1750,7 @@ Application Examples
.. _esp-idf-template: https://github.com/espressif/esp-idf-template
.. _cmake: https://cmake.org
.. _ninja: https://ninja-build.org
.. _esptool.py: https://github.com/espressif/esptool/#readme
.. _esptool: https://github.com/espressif/esptool/#readme
.. _CMake v3.22 documentation: https://cmake.org/cmake/help/v3.22/index.html
.. _cmake command line documentation: https://cmake.org/cmake/help/v3.22/manual/cmake.1.html#options
.. _cmake add_library: https://cmake.org/cmake/help/v3.22/command/add_library.html

8
docs/en/api-guides/partition-tables.rst
View File

@@ -311,14 +311,14 @@ The binary format of the partition table contains an MD5 checksum computed based
Flashing the Partition Table
----------------------------
* ``idf.py partition-table-flash``: will flash the partition table with esptool.py.
* ``idf.py partition-table-flash``: will flash the partition table with esptool.
* ``idf.py flash``: Will flash everything including the partition table.
A manual flashing command is also printed as part of ``idf.py partition-table`` output.
.. note::
Note that updating the partition table does not erase data that may have been stored according to the old partition table. You can use ``idf.py erase-flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents.
Note that updating the partition table does not erase data that may have been stored according to the old partition table. You can use ``idf.py erase-flash`` (or ``esptool erase-flash``) to erase the entire flash contents.
Partition Tool (``parttool.py``)
@@ -406,13 +406,13 @@ The command-line interface of `parttool.py` has the following structure:
.. note::
If the device has already enabled ``Flash Encryption`` or ``Secure Boot``, attempting to use commands that modify the flash content, such as ``erase_partition`` or ``write_partition``, will result in an error. This error is generated by the erase command of ``esptool.py``, which is called first before writing. This error is done as a safety measure to prevent bricking your device.
If the device has already enabled ``Flash Encryption`` or ``Secure Boot``, attempting to use commands that modify the flash content, such as ``erase_partition`` or ``write_partition``, will result in an error. This error is generated by the erase command of ``esptool``, which is called first before writing. This error is done as a safety measure to prevent bricking your device.
.. code-block:: none
A fatal error occurred: Active security features detected, erasing flash is disabled as a safety measure. Use --force to override, please use with caution, otherwise it may brick your device!
To work around this, you need use the ``--force`` flag with ``esptool.py``. Specifically, the ``parttool.py`` provides the ``--esptool-erase-args`` argument that help to pass this flag to ``esptool.py``.
To work around this, you need use the ``--force`` flag with ``esptool``. Specifically, the ``parttool.py`` provides the ``--esptool-erase-args`` argument that help to pass this flag to ``esptool``.
.. code-block:: bash

2
docs/en/api-guides/tools/idf-docker-image.rst
View File

@@ -130,7 +130,7 @@ And then starting the server by executing
.. code-block:: bash
esp_rfc2217_server.py -v -p 4000 /dev/ttyUSB0
esp_rfc2217_server -v -p 4000 /dev/ttyUSB0
Now the device attached to the host can be flashed from inside a Docker container by using:

8
docs/en/api-guides/tools/idf-py.rst
View File

@@ -7,7 +7,7 @@ The ``idf.py`` command-line tool provides a front-end for easily managing your p
- CMake_, which configures the project to be built.
- Ninja_, which builds the project.
- `esptool.py`_, which flashes the target.
- `esptool`_, which flashes the target.
The :ref:`Step 5. First Steps on ESP-IDF <get-started-configure>` contains a brief introduction on how to set up ``idf.py`` to configure, build, and flash projects.
@@ -120,7 +120,7 @@ This command automatically builds the project if necessary, and then flash it to
.. note:: The environment variables ``ESPPORT`` and ``ESPBAUD`` can be used to set default values for the ``-p`` and ``-b`` options, respectively. Providing these options on the command line overrides the default.
``idf.py`` uses the ``write_flash`` command of ``esptool.py`` under the hood to flash the target. You can pass additional arguments to configure the flash writing process using the ``--extra-args`` option. For example, to `write to an external SPI flash chip <https://docs.espressif.com/projects/esptool/en/latest/esptool/advanced-options.html#custom-spi-pin-configuration>`_, use the following command: ``idf.py flash --extra-args="--spi-connection <CLK>,<Q>,<D>,<HD>,<CS>"``. To see the full list of available arguments, run ``esptool.py write_flash --help`` or see the `esptool.py documentation <https://docs.espressif.com/projects/esptool/en/latest/esptool/index.html>`_.
``idf.py`` uses the ``write-flash`` command of ``esptool`` under the hood to flash the target. You can pass additional arguments to configure the flash writing process using the ``--extra-args`` option. For example, to `write to an external SPI flash chip <https://docs.espressif.com/projects/esptool/en/latest/esptool/advanced-options.html#custom-spi-pin-configuration>`_, use the following command: ``idf.py flash --extra-args="--spi-connection <CLK>,<Q>,<D>,<HD>,<CS>"``. To see the full list of available arguments, run ``esptool write-flash --help`` or see the `esptool documentation <https://docs.espressif.com/projects/esptool/en/latest/esptool/index.html>`_.
Similarly to the ``build`` command, the command can be run with ``app``, ``bootloader`` and ``partition-table`` arguments to flash only the app, bootloader or partition table as applicable.
@@ -152,7 +152,7 @@ There are also some format specific options, which are listed below:
- Only for raw format:
- ``--flash-offset``: This option will create a merged binary that should be flashed at the specified offset, instead of at the standard offset of 0x0.
- ``--fill-flash-size``: If set, the final binary file will be padded with FF bytes up to this flash size in order to fill the full flash content with the image and re-write the whole flash chip upon flashing.
- ``--pad-to-size``: If set, the final binary file will be padded with FF bytes up to this flash size in order to fill the full flash content with the image and re-write the whole flash chip upon flashing.
- Only for uf2 format:
@@ -407,6 +407,6 @@ Basic Usage Examples
.. _cmake: https://cmake.org
.. _ninja: https://ninja-build.org
.. _esptool.py: https://github.com/espressif/esptool/#readme
.. _esptool: https://github.com/espressif/esptool/#readme
.. _CCache: https://ccache.dev/
.. _click context: https://click.palletsprojects.com/en/stable/api/#context

2
docs/en/api-guides/usb-otg-console.rst
View File

@@ -6,7 +6,7 @@ USB OTG Console
On chips with an integrated USB peripheral, it is possible to use USB Communication Device Class (CDC) to implement the serial console, instead of using UART with an external USB-UART bridge chip. {IDF_TARGET_NAME} ROM code contains a USB CDC implementation, which supports for some basic functionality without requiring the application to include the USB stack:
* Bidirectional serial console, which can be used with :doc:`IDF Monitor <tools/idf-monitor>` or another serial monitor.
* Flashing using ``esptool.py`` and ``idf.py flash``.
* Flashing using ``esptool`` and ``idf.py flash``.
* :doc:`Device Firmware Update (DFU) <dfu>` interface for flashing the device using ``dfu-util`` and ``idf.py dfu``.
.. note::

2
docs/en/api-guides/usb-serial-jtag-console.rst
View File

@@ -9,7 +9,7 @@ Generally, ESP chips implement a serial port using UART and can be connected to
{IDF_TARGET_NAME} contains a USB Serial/JTAG Controller providing the following functions:
* Bidirectional serial console, which can be used with :doc:`IDF Monitor <tools/idf-monitor>` or another serial monitor.
* Flashing using ``esptool.py`` and ``idf.py flash``.
* Flashing using ``esptool`` and ``idf.py flash``.
* JTAG debugging, performed simultaneously with serial operations using tools like OpenOCD.
.. note::

6
docs/en/api-reference/peripherals/sd_pullup_requirements.rst
View File

@@ -218,11 +218,11 @@ No Pull-ups
Burning eFuses is irreversible! The issue list above might be out of date, so please make sure that the module you are burning has a 3.3 V flash chip by checking the information on https://www.espressif.com/. If you burn the 3.3 V eFuses on a module with a 1.8 V flash chip, the module will stop functioning.
If you are sure that you need to irreversibly burn eFuses, go to your ESP-IDF directory and run the following command using ``espefuse.py`` tool:
If you are sure that you need to irreversibly burn eFuses, go to your ESP-IDF directory and run the following command using ``espefuse`` tool:
.. code-block:: bash
components/esptool_py/esptool/espefuse.py set_flash_voltage 3.3V
espefuse set-flash-voltage 3.3V
This command burns the ``XPD_SDIO_TIEH``, ``XPD_SDIO_FORCE``, and ``XPD_SDIO_REG`` eFuses. After all the three eFuses are burned to value 1, the internal VDD_SDIO flash voltage regulator is permanently set to 3.3 V. You will see the following log if the burning succeeds:
@@ -244,7 +244,7 @@ No Pull-ups
idf.py efuse-summary
If running from an automated flashing script, it is better to use standalone eFuse tool ``espefuse.py``. This tool also has an option ``--do-not-confirm`` to burn eFuses without confirmation.
If running from an automated flashing script, it is better to use standalone eFuse tool ``espefuse``. This tool also has an option ``--do-not-confirm`` to burn eFuses without confirmation.
For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].

2
docs/en/api-reference/peripherals/spi_flash/index.rst
View File

@@ -118,7 +118,7 @@ SPI Flash Size
The SPI flash size is configured by writing a field in the ESP-IDF second stage bootloader image header, flashed at offset 0x1000.
By default, the SPI flash size is detected by ``esptool.py`` when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in the project configuration.
By default, the SPI flash size is detected by ``esptool`` when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in the project configuration.
If it is necessary to override the configured flash size at runtime, it is possible to set the ``chip_size`` member of the ``g_rom_flashchip`` structure. This size is used by ``esp_flash_*`` functions (in both software & ROM) to check the bounds.

2
docs/en/api-reference/storage/fatfs.rst
View File

@@ -149,7 +149,7 @@ For example::
fatfs_create_spiflash_image(my_fatfs_partition my_folder FLASH_IN_PROJECT)
If FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using ``esptool.py`` or a custom build system target.
If FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using ``esptool`` or a custom build system target.
For an example, see :example:`storage/fatfs/fatfsgen`.

10
docs/en/api-reference/storage/spiffs.rst
View File

@@ -43,7 +43,7 @@ There are also other arguments that control image generation. Documentation on t
These optional arguments correspond to a possible SPIFFS build configuration. To generate the right image, please make sure that you use the same arguments/configuration as were used to build SPIFFS. As a guide, the help output indicates the SPIFFS build configuration to which the argument corresponds. In cases when these arguments are not specified, the default values shown in the help output will be used.
When the image is created, it can be flashed using ``esptool.py`` or ``parttool.py``.
When the image is created, it can be flashed using ``esptool`` or ``parttool.py``.
Aside from invoking the ``spiffsgen.py`` standalone by manually running it from the command line or a script, it is also possible to invoke ``spiffsgen.py`` directly from the build system by calling ``spiffs_create_partition_image``::
@@ -57,7 +57,7 @@ Optionally, users can opt to have the image automatically flashed together with
spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT)
If FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using ``esptool.py``, ``parttool.py``, or a custom build system target.
If FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using ``esptool``, ``parttool.py``, or a custom build system target.
There are cases where the contents of the base directory itself is generated at build time. Users can use DEPENDS/SPIFFS_IMAGE_DEPENDS to specify targets that should be executed before generating the image::
@@ -70,7 +70,7 @@ For an example, see :example:`storage/spiffsgen`. This example demonstrates how
``mkspiffs``
^^^^^^^^^^^^
Another tool for creating SPIFFS partition images is `mkspiffs <https://github.com/igrr/mkspiffs>`_. Similar to ``spiffsgen.py``, it can be used to create an image from a given folder and then flash that image using ``esptool.py``
Another tool for creating SPIFFS partition images is `mkspiffs <https://github.com/igrr/mkspiffs>`_. Similar to ``spiffsgen.py``, it can be used to create an image from a given folder and then flash that image using ``esptool``
For that, you need to obtain the following parameters:
@@ -85,11 +85,11 @@ To pack a folder into a 1-Megabyte image, run::
To flash the image onto {IDF_TARGET_NAME} at offset 0x110000, run::
python esptool.py --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin
esptool --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write-flash -z 0x110000 spiffs.bin
.. note::
You can configure the ``write_flash`` command of ``esptool.py`` to `write the spiffs data to an external SPI flash chip <https://docs.espressif.com/projects/esptool/en/latest/esptool/advanced-options.html#custom-spi-pin-configuration>`_ using the ``--spi-connection <CLK>,<Q>,<D>,<HD>,<CS>`` option. Just specify the GPIO pins assigned to the external flash, e.g., ``python esptool.py write_flash --spi-connection 6,7,8,9,11 -z 0x110000 spiffs.bin``.
You can configure the ``write-flash`` command of ``esptool`` to `write the spiffs data to an external SPI flash chip <https://docs.espressif.com/projects/esptool/en/latest/esptool/advanced-options.html#custom-spi-pin-configuration>`_ using the ``--spi-connection <CLK>,<Q>,<D>,<HD>,<CS>`` option. Just specify the GPIO pins assigned to the external flash, e.g., ``esptool write-flash --spi-connection 6,7,8,9,11 -z 0x110000 spiffs.bin``.
Notes on Which SPIFFS Tool to Use
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

67
docs/en/api-reference/system/app_image_format.rst
View File

@@ -24,30 +24,57 @@ To get the list of your image segments, please run the following command:
.. code-block::
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/app.bin
esptool --chip {IDF_TARGET_PATH_NAME} image-info build/app.bin
.. code-block::
esptool.py v2.3.1
Image version: 1
Entry point: 40080ea4
13 segments
esptool v5.0.2
Image size: 137312 bytes
Segment 1: len 0x13ce0 load 0x3f400020 file_offs 0x00000018 SOC_DROM
Segment 2: len 0x00000 load 0x3ff80000 file_offs 0x00013d00 SOC_RTC_DRAM
Segment 3: len 0x00000 load 0x3ff80000 file_offs 0x00013d08 SOC_RTC_DRAM
Segment 4: len 0x028e0 load 0x3ffb0000 file_offs 0x00013d10 DRAM
Segment 5: len 0x00000 load 0x3ffb28e0 file_offs 0x000165f8 DRAM
Segment 6: len 0x00400 load 0x40080000 file_offs 0x00016600 SOC_IRAM
Segment 7: len 0x09600 load 0x40080400 file_offs 0x00016a08 SOC_IRAM
Segment 8: len 0x62e4c load 0x400d0018 file_offs 0x00020010 SOC_IROM
Segment 9: len 0x06cec load 0x40089a00 file_offs 0x00082e64 SOC_IROM
Segment 10: len 0x00000 load 0x400c0000 file_offs 0x00089b58 SOC_RTC_IRAM
Segment 11: len 0x00004 load 0x50000000 file_offs 0x00089b60 SOC_RTC_DATA
Segment 12: len 0x00000 load 0x50000004 file_offs 0x00089b6c SOC_RTC_DATA
Segment 13: len 0x00000 load 0x50000004 file_offs 0x00089b74 SOC_RTC_DATA
Checksum: e8 (valid)
Validation Hash: 407089ca0eae2bbf83b4120979d3354b1c938a49cb7a0c997f240474ef2ec76b (valid)
ESP32 Image Header
==================
Image version: 1
Entry point: 0x40081214
Segments: 6
Flash size: 2MB
Flash freq: 40m
Flash mode: DIO
ESP32 Extended Image Header
===========================
WP pin: 0xee (disabled)
Flash pins drive settings: clk_drv: 0x0, q_drv: 0x0, d_drv: 0x0, cs0_drv: 0x0, hd_drv: 0x0, wp_drv: 0x0
Chip ID: 0 (ESP32)
Minimal chip revision: v0.0, (legacy min_rev = 0)
Maximal chip revision: v3.99
Segments Information
====================
Segment Length Load addr File offs Memory types
------- ------- ---------- ---------- ------------
0 0x0711c 0x3f400020 0x00000018 DROM
1 0x0241c 0x3ffb0000 0x0000713c BYTE_ACCESSIBLE, DRAM
2 0x06ab0 0x40080000 0x00009560 IRAM
3 0x0b724 0x400d0020 0x00010018 IROM
4 0x060c0 0x40086ab0 0x0001b744 IRAM
5 0x00024 0x50000000 0x0002180c RTC_DATA
ESP32 Image Footer
==================
Checksum: 0x4b (valid)
Validation hash: 8808f05a62fe1a6e1e6830414b95229454b012eb2001511ca434d34e9e63c962 (valid)
Application Information
=======================
Project name: hello_world
App version: qa-test-esp32c61-master-2025070
Compile time: Aug 12 2025 16:36:40
ELF file SHA256: 10972f521b52276e988631d7408de388d639437118e8217c366f2bd93b52e1b6
ESP-IDF: v6.0-dev-1692-g7aad0d47e66-dirt
Minimal eFuse block revision: 0.0
Maximal eFuse block revision: 0.99
MMU page size: 64 KB
Secure version: 0
You can also see the information on segments in the ESP-IDF logs while your application is booting:

38
docs/en/api-reference/system/bootloader_image_format.rst
View File

@@ -9,50 +9,50 @@ To get information about the bootloader image, please run the following command:
.. code-block::
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/bootloader/bootloader.bin --version 2
esptool --chip {IDF_TARGET_PATH_NAME} image-info ./build/bootloader/bootloader.bin
The resultant output will resemble the following:
.. code-block::
File size: 26576 (bytes)
esptool v5.0.2
Image size: 26352 bytes
ESP32 image header
ESP32 Image Header
==================
Image version: 1
Entry point: 0x40080658
Segments: 4
Entry point: 0x40080644
Segments: 3
Flash size: 2MB
Flash freq: 40m
Flash mode: DIO
ESP32 extended image header
ESP32 Extended Image Header
===========================
WP pin: 0xee
WP pin: 0xee (disabled)
Flash pins drive settings: clk_drv: 0x0, q_drv: 0x0, d_drv: 0x0, cs0_drv: 0x0, hd_drv: 0x0, wp_drv: 0x0
Chip ID: 0
Chip ID: 0 (ESP32)
Minimal chip revision: v0.0, (legacy min_rev = 0)
Maximal chip revision: v3.99
Segments information
Segments Information
====================
Segment Length Load addr File offs Memory types
------- ------- ---------- ---------- ------------
1 0x01bb0 0x3fff0030 0x00000018 BYTE_ACCESSIBLE, DRAM, DIRAM_DRAM
2 0x03c90 0x40078000 0x00001bd0 CACHE_APP
3 0x00004 0x40080400 0x00005868 IRAM
4 0x00f2c 0x40080404 0x00005874 IRAM
0 0x018e8 0x3fff0030 0x00000018 BYTE_ACCESSIBLE, DRAM, DIRAM_DRAM
1 0x03e58 0x40078000 0x00001908 CACHE_APP
2 0x00f5c 0x40080400 0x00005768 IRAM
ESP32 image footer
ESP32 Image Footer
==================
Checksum: 0x65 (valid)
Validation hash: 6f31a7f8512f26f6bce7c3b270f93bf6cf1ee4602c322998ca8ce27433527e92 (valid)
Checksum: 0x6b (valid)
Validation hash: 09fdc81d436a927b5018e19073a787cd37ffce655f505ad92675edd784419034 (valid)
Bootloader information
Bootloader Information
======================
Bootloader version: 1
ESP-IDF: v5.1-dev-4304-gcb51a3b-dirty
Compile time: Mar 30 2023 19:14:17
ESP-IDF: v6.0-dev-1620-g15d7e41a848-dirt
Compile time: Aug 8 2025 16:22:1
.. _image-format-bootloader-description:

2
docs/en/api-reference/system/chip_revision.rst
View File

@@ -179,7 +179,7 @@ Backward Compatibility with Bootloaders Built by Older ESP-IDF Versions
{IDF_TARGET_NAME} chip support was added in ESP-IDF v4.2. {IDF_TARGET_NAME} chips have ``rev_min`` in :cpp:type:`esp_image_header_t` header set to ``0`` because ``Minimum Supported ESP32-S2 Revision`` Kconfig option was not introduced, which means that the old bootloader does not check the chip revision. Any app can be loaded by such bootloader in range ``v0.0`` to ``v3.15``.
Please check the chip version using ``esptool chip_id`` command.
Please check the chip version using ``esptool chip-id`` command.
References
----------

14
docs/en/api-reference/system/efuse.rst
View File

@@ -20,7 +20,7 @@ The eFuse Manager component is a collection of tools and APIs that assist with d
eFuse Manager vs ``idf.py``
---------------------------
``idf.py`` provides a subset of the functionality of the eFuse Manager via the ``idf.py efuse-<subcommand>`` commands. In this documentation, mostly ``idf.py`` based commands will be used, although you can still see some ``espefuse.py`` based commands for advanced or rare cases. To see all available commands, run ``idf.py --help`` and search for those prefixed with ``efuse-``.
``idf.py`` provides a subset of the functionality of the eFuse Manager via the ``idf.py efuse-<subcommand>`` commands. In this documentation, mostly ``idf.py`` based commands will be used, although you can still see some ``espefuse`` based commands for advanced or rare cases. To see all available commands, run ``idf.py --help`` and search for those prefixed with ``efuse-``.
Hardware Description
--------------------
@@ -488,7 +488,7 @@ Get eFuses During Build
There is a way to get the state of eFuses at the build stage of the project. There are two CMake functions for this:
* ``espefuse_get_json_summary()`` - It calls the ``espefuse.py summary --format json`` command and returns a JSON string (it is not stored in a file).
* ``espefuse_get_json_summary()`` - It calls the ``espefuse summary --format json`` command and returns a JSON string (it is not stored in a file).
* ``espefuse_get_efuse()`` - It finds a given eFuse name in the JSON string and returns its property.
The JSON string has the following properties:
@@ -522,7 +522,7 @@ These functions can be used from a top-level project ``CMakeLists.txt`` (:exampl
espefuse_get_efuse(ret_data ${efuse_json} "MAC" "value")
message("MAC:" ${ret_data})
The format of the ``value`` property is the same as shown in ``espefuse.py summary`` or ``idf.py efuse-summary``.
The format of the ``value`` property is the same as shown in ``espefuse summary`` or ``idf.py efuse-summary``.
.. code-block:: none
@@ -557,12 +557,12 @@ Flash encryption is a hardware feature that requires the physical burning of eFu
The :cpp:func:`bootloader_flash_write` is adapted for this purpose. But if flash encryption is already enabled on the chip when the application is run, or if the bootloader is created with the :ref:`CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH` option, then the flash encryption/decryption operations will work properly. This means that data are encrypted as it is written into an encrypted flash partition and decrypted when they are read from an encrypted partition.
``espefuse.py``
^^^^^^^^^^^^^^^
``espefuse``
^^^^^^^^^^^^
esptool includes a useful tool for reading/writing {IDF_TARGET_NAME} eFuse bits - `espefuse.py <https://docs.espressif.com/projects/esptool/en/latest/{IDF_TARGET_PATH_NAME}/espefuse/index.html>`_.
esptool includes a useful tool for reading/writing {IDF_TARGET_NAME} eFuse bits - `espefuse <https://docs.espressif.com/projects/esptool/en/latest/{IDF_TARGET_PATH_NAME}/espefuse/index.html>`_.
Part of the functionality of this tool is also provided directly by ``idf.py`` commands. For example, the ``idf.py efuse-summary`` command is equivalent to ``espefuse.py summary``.
Part of the functionality of this tool is also provided directly by ``idf.py`` commands. For example, the ``idf.py efuse-summary`` command is equivalent to ``espefuse summary``.
.. include:: inc/espefuse_summary_{IDF_TARGET_NAME}.rst

43
docs/en/get-started/esp32_output_log.inc
View File

@@ -3,37 +3,28 @@
.. code-block:: none
...
esptool.py --chip esp32 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size 2MB 0x8000 partition_table/partition-table.bin 0x1000 bootloader/bootloader.bin 0x10000 hello_world.bin
esptool.py v3.0-dev
Serial port /dev/ttyUSB0
Connecting........_
Chip is ESP32D0WDQ6 (revision 0)
Features: WiFi, BT, Dual Core, Coding Scheme None
Crystal is 40MHz
esptool --chip esp32 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 40m --flash-size 2MB 0x8000 partition_table/partition-table.bin 0x1000 bootloader/bootloader.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32 on /dev/ttyUSB0:
Chip type: ESP32-U4WDH (revision v3.0)
Features: Wi-Fi, BT, Dual Core + LP Core, 240MHz, Embedded Flash, Vref calibration in eFuse, Coding Scheme None
Crystal frequency: 40MHz
MAC: 24:0a:c4:05:b9:14
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 5962.8 kbit/s)...
Flash will be erased from 0x00008000 to 0x00008fff...
Flash will be erased from 0x00001000 to 0x00007fff...
Flash will be erased from 0x00010000 to 0x00031fff...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (279.3 kbit/s).
Hash of data verified.
Compressed 26096 bytes to 15408...
Writing at 0x00001000... (100 %)
Wrote 26096 bytes (15408 compressed) at 0x00001000 in 0.4 seconds (effective 546.7 kbit/s)...
SHA digest in image updated.
Wrote 26352 bytes (16660 compressed) at 0x00001000 in 0.9 seconds (239.3 kbit/s).
Hash of data verified.
Compressed 147104 bytes to 77364...
Writing at 0x00010000... (20 %)
Writing at 0x00014000... (40 %)
Writing at 0x00018000... (60 %)
Writing at 0x0001c000... (80 %)
Writing at 0x00020000... (100 %)
Wrote 147104 bytes (77364 compressed) at 0x00010000 in 1.9 seconds (effective 615.5 kbit/s)...
Wrote 137312 bytes (78774 compressed) at 0x00010000 in 2.2 seconds (490.8 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
Done

43
docs/en/get-started/esp32c2_output_log.inc
View File

@@ -3,39 +3,28 @@
.. code-block:: none
...
esptool.py esp32c2 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 60m --flash_size 2MB 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool.py v3.3.1
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-C2 (revision 1)
Features: Wi-Fi
Crystal is 40MHz
MAC: 10:97:bd:f0:e5:0c
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32c2 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 60m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-C2 on /dev/ttyUSB0:
Chip type: ESP32-C2 (revision v2.0)
Features: Wi-Fi, BT 5 (LE), Single Core, 120MHz
Crystal frequency: 40MHz
MAC: 10:97:bd:f5:36:98
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Flash will be erased from 0x00000000 to 0x00004fff...
Flash will be erased from 0x00010000 to 0x0002ffff...
Flash will be erased from 0x00008000 to 0x00008fff...
Compressed 18192 bytes to 10989...
Writing at 0x00000000... (100 %)
Wrote 18192 bytes (10989 compressed) at 0x00000000 in 0.6 seconds (effective 248.5 kbit/s)...
Flash will be erased from 0x00010000 to 0x00028fff...
SHA digest in image updated.
Wrote 19680 bytes (12357 compressed) at 0x00000000 in 0.5 seconds (292.1 kbit/s).
Hash of data verified.
Compressed 128640 bytes to 65895...
Writing at 0x00010000... (20 %)
Writing at 0x00019539... (40 %)
Writing at 0x00020bf2... (60 %)
Writing at 0x00027de1... (80 %)
Writing at 0x0002f480... (100 %)
Wrote 128640 bytes (65895 compressed) at 0x00010000 in 1.7 seconds (effective 603.0 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (296.4 kbit/s).
Hash of data verified.
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (effective 360.1 kbit/s)...
Wrote 98416 bytes (52689 compressed) at 0x00010000 in 1.8 seconds (438.9 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...

45
docs/en/get-started/esp32c3_output_log.inc
View File

@@ -3,37 +3,28 @@
.. code-block:: none
...
esptool.py --chip esp32c3 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 80m --flash_size 2MB 0x8000 partition_table/partition-table.bin 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin
esptool.py v3.0
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-C3
Features: Wi-Fi
Crystal is 40MHz
MAC: 7c:df:a1:40:02:a4
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32c3 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-C3 on /dev/ttyUSB0:
Chip type: ESP32-C3 (QFN32) (revision v1.0)
Features: Wi-Fi, BT 5 (LE), Single Core, 160MHz, Embedded Flash 4MB (XMC)
Crystal frequency: 40MHz
MAC: 60:55:f9:f7:7d:20
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 4238.1 kbit/s)...
Flash will be erased from 0x00000000 to 0x00005fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Flash will be erased from 0x00010000 to 0x00031fff...
SHA digest in image updated.
Wrote 21072 bytes (13320 compressed) at 0x00000000 in 0.7 seconds (232.1 kbit/s).
Hash of data verified.
Compressed 18960 bytes to 11311...
Writing at 0x00000000... (100 %)
Wrote 18960 bytes (11311 compressed) at 0x00000000 in 0.3 seconds (effective 584.9 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (240.8 kbit/s).
Hash of data verified.
Compressed 145520 bytes to 71984...
Writing at 0x00010000... (20 %)
Writing at 0x00014000... (40 %)
Writing at 0x00018000... (60 %)
Writing at 0x0001c000... (80 %)
Writing at 0x00020000... (100 %)
Wrote 145520 bytes (71984 compressed) at 0x00010000 in 2.3 seconds (effective 504.4 kbit/s)...
Wrote 135328 bytes (74697 compressed) at 0x00010000 in 2.6 seconds (419.7 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
Done

39
docs/en/get-started/esp32c5_output_log.inc
View File

@@ -3,39 +3,30 @@
.. code-block:: none
...
esptool.py --chip esp32c5 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset --no-stub write_flash --flash_mode dio --flash_freq 80m --flash_size 2MB 0x2000 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool.py v4.9.dev6
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-C5 (revision v1.0)
Features: WiFi 6, BT 5, IEEE802.15.4
Crystal is 48MHz
esptool --chip esp32c5 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset --no-stub write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x2000 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool v5.0.2
Connected to ESP32-C5 on /dev/ttyUSB0:
Chip type: ESP32-C5 (revision v1.0)
Features: Wi-Fi 6 (dual-band), BT 5 (LE), IEEE802.15.4, Single Core + LP Core, 240MHz
Crystal frequency: 48MHz
MAC: 30:ed:a0:ff:fe:e0:af:38
BASE MAC: 30:ed:a0:e0:af:38
MAC_EXT: ff:fe
ROM expects crystal freq: 48 MHz, detected 48 MHz
Changing baud rate to 460800
Stub flasher running.
Changing baud rate to 460800...
Changed.
Enabling default SPI flash mode...
Configuring flash size...
Flash will be erased from 0x00002000 to 0x00007fff...
Flash will be erased from 0x00010000 to 0x00034fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Erasing flash...
Took 0.09s to erase flash block
Writing at 0x00007400... (100 %)
Wrote 22528 bytes at 0x00002000 in 0.7 seconds (276.3 kbit/s)...
Flash will be erased from 0x00010000 to 0x00032fff...
SHA digest in image updated.
Wrote 21888 bytes (13489 compressed) at 0x00002000 in 0.5 seconds (348.1 kbit/s).
Hash of data verified.
Erasing flash...
Took 0.37s to erase flash block
Writing at 0x00034c00... (100 %)
Wrote 151552 bytes at 0x00010000 in 4.4 seconds (275.6 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (316.0 kbit/s).
Hash of data verified.
Erasing flash...
Took 0.02s to erase flash block
Writing at 0x00008800... (100 %)
Wrote 3072 bytes at 0x00008000 in 0.1 seconds (281.8 kbit/s)...
Wrote 141248 bytes (75783 compressed) at 0x00010000 in 2.1 seconds (536.0 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...

55
docs/en/get-started/esp32c6_output_log.inc
View File

@@ -3,47 +3,30 @@
.. code-block:: none
...
esptool esp32c6 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset --no-stub write_flash --flash_mode dio --flash_freq 80m --flash_size 2MB 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool.py v4.3
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-C6 (revision v0.0)
Features: WiFi 6, BT 5
Crystal is 40MHz
MAC: 60:55:f9:f6:01:38
Changing baud rate to 460800
esptool --chip esp32c6 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-C6 on /dev/ttyUSB0:
Chip type: ESP32-C6 (QFN40) (revision v0.0)
Features: Wi-Fi 6, BT 5 (LE), IEEE802.15.4, Single Core + LP Core, 160MHz
Crystal frequency: 40MHz
MAC: 40:4c:ca:ff:fe:50:bf:18
BASE MAC: 40:4c:ca:50:bf:18
MAC_EXT: ff:fe
Stub flasher running.
Changing baud rate to 460800...
Changed.
Enabling default SPI flash mode...
Configuring flash size...
Flash will be erased from 0x00000000 to 0x00004fff...
Flash will be erased from 0x00010000 to 0x00028fff...
Flash will be erased from 0x00000000 to 0x00005fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Erasing flash...
Took 0.17s to erase flash block
Writing at 0x00000000... (5 %)
Writing at 0x00000c00... (23 %)
Writing at 0x00001c00... (47 %)
Writing at 0x00003000... (76 %)
Writing at 0x00004000... (100 %)
Wrote 17408 bytes at 0x00000000 in 0.5 seconds (254.6 kbit/s)...
Flash will be erased from 0x00010000 to 0x0002efff...
SHA digest in image updated.
Wrote 22512 bytes (13994 compressed) at 0x00000000 in 0.3 seconds (662.3 kbit/s).
Hash of data verified.
Erasing flash...
Took 0.85s to erase flash block
Writing at 0x00010000... (1 %)
Writing at 0x00014c00... (20 %)
Writing at 0x00019c00... (40 %)
Writing at 0x0001ec00... (60 %)
Writing at 0x00023c00... (80 %)
Writing at 0x00028c00... (100 %)
Wrote 102400 bytes at 0x00010000 in 3.2 seconds (253.5 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (630.2 kbit/s).
Hash of data verified.
Erasing flash...
Took 0.04s to erase flash block
Writing at 0x00008000... (33 %)
Writing at 0x00008400... (66 %)
Writing at 0x00008800... (100 %)
Wrote 3072 bytes at 0x00008000 in 0.1 seconds (269.0 kbit/s)...
Wrote 122976 bytes (63916 compressed) at 0x00010000 in 0.9 seconds (1087.1 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...

45
docs/en/get-started/esp32h2_output_log.inc
View File

@@ -3,39 +3,30 @@
.. code-block:: none
...
esptool esp32h2 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 48m --flash_size 2MB 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool.py v4.6
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-H2 (revision v0.1)
Features: BLE
Crystal is 32MHz
MAC: 60:55:f9:f7:3e:93:ff:fe
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32h2 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 48m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-H2 on /dev/ttyUSB0:
Chip type: ESP32-H2 (revision v0.2)
Features: BT 5 (LE), IEEE802.15.4, Single Core, 96MHz
Crystal frequency: 32MHz
MAC: 60:55:f9:ff:fe:f7:3a:56
BASE MAC: 60:55:f9:f7:3a:56
MAC_EXT: ff:fe
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Flash will be erased from 0x00000000 to 0x00005fff...
Flash will be erased from 0x00010000 to 0x00034fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Compressed 20880 bytes to 12788...
Writing at 0x00000000... (100 %)
Wrote 20880 bytes (12788 compressed) at 0x00000000 in 0.6 seconds (effective 297.5 kbit/s)...
Flash will be erased from 0x00010000 to 0x00032fff...
SHA digest in image updated.
Wrote 22192 bytes (13780 compressed) at 0x00000000 in 0.7 seconds (252.5 kbit/s).
Hash of data verified.
Compressed 149424 bytes to 79574...
Writing at 0x00010000... (20 %)
Writing at 0x00019959... (40 %)
Writing at 0x00020bb5... (60 %)
Writing at 0x00026d8f... (80 %)
Writing at 0x0002e60a... (100 %)
Wrote 149424 bytes (79574 compressed) at 0x00010000 in 2.1 seconds (effective 571.7 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (248.5 kbit/s).
Hash of data verified.
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 539.7 kbit/s)...
Wrote 141920 bytes (76653 compressed) at 0x00010000 in 2.5 seconds (458.5 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...

40
docs/en/get-started/esp32p4_output_log.inc
View File

@@ -4,36 +4,28 @@
.. code-block:: none
...
esptool.py v4.8.dev3
Serial port /dev/cu.SLAB_USBtoUART
Connecting....
Chip is ESP32-P4 (revision v0.0)
Features: High-Performance MCU
Crystal is 40MHz
MAC: 00:00:00:00:00:00
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32p4 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x2000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-P4 on /dev/ttyUSB0:
Chip type: ESP32-P4 (revision v1.0)
Features: Dual Core + LP Core, 400MHz
Crystal frequency: 40MHz
MAC: 60:55:f9:fc:00:a2
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Flash will be erased from 0x00002000 to 0x00007fff...
Flash will be erased from 0x00010000 to 0x0003bfff...
Flash will be erased from 0x00008000 to 0x00008fff...
SHA digest in image updated
Compressed 20960 bytes to 12653...
Writing at 0x00002000... (100 %)
Wrote 20960 bytes (12653 compressed) at 0x00002000 in 0.6 seconds (effective 277.1 kbit/s)...
Flash will be erased from 0x00010000 to 0x00038fff...
SHA digest in image updated.
Wrote 22896 bytes (13985 compressed) at 0x00002000 in 0.4 seconds (477.0 kbit/s).
Hash of data verified.
Compressed 179584 bytes to 94528...
Writing at 0x00035efb... (100 %)
Wrote 179584 bytes (94528 compressed) at 0x00010000 in 2.6 seconds (effective 549.9 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (416.6 kbit/s).
Hash of data verified.
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (effective 420.7 kbit/s)...
Wrote 164496 bytes (87363 compressed) at 0x00010000 in 1.4 seconds (931.3 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
Done

45
docs/en/get-started/esp32s2_output_log.inc
View File

@@ -3,37 +3,28 @@
.. code-block:: none
...
esptool.py --chip esp32s2 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size 2MB 0x8000 partition_table/partition-table.bin 0x1000 bootloader/bootloader.bin 0x10000 hello_world.bin
esptool.py v3.0-dev
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-S2
Features: WiFi
Crystal is 40MHz
MAC: 18:fe:34:72:50:e3
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32s2 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-S2 on /dev/ttyUSB0:
Chip type: ESP32-S2FH4 (revision v0.0)
Features: Wi-Fi, Single Core, 240MHz, Embedded Flash 4MB, No Embedded PSRAM, ADC and temperature sensor calibration in BLK2 of eFuse V1
Crystal frequency: 40MHz
MAC: 84:f7:03:e3:3f:bc
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 3851.6 kbit/s)...
Flash will be erased from 0x00001000 to 0x00006fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Flash will be erased from 0x00010000 to 0x00030fff...
SHA digest in image updated.
Wrote 21968 bytes (13914 compressed) at 0x00001000 in 0.7 seconds (251.0 kbit/s).
Hash of data verified.
Compressed 22592 bytes to 13483...
Writing at 0x00001000... (100 %)
Wrote 22592 bytes (13483 compressed) at 0x00001000 in 0.3 seconds (effective 595.1 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (238.5 kbit/s).
Hash of data verified.
Compressed 140048 bytes to 70298...
Writing at 0x00010000... (20 %)
Writing at 0x00014000... (40 %)
Writing at 0x00018000... (60 %)
Writing at 0x0001c000... (80 %)
Writing at 0x00020000... (100 %)
Wrote 140048 bytes (70298 compressed) at 0x00010000 in 1.7 seconds (effective 662.5 kbit/s)...
Wrote 132096 bytes (76394 compressed) at 0x00010000 in 2.2 seconds (486.9 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
Done

47
docs/en/get-started/esp32s3_output_log.inc
View File

@@ -3,41 +3,28 @@
.. code-block:: none
...
esptool.py esp32s3 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 80m --flash_size 2MB 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool.py v3.2-dev
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-S3
Features: WiFi, BLE
Crystal is 40MHz
MAC: 7c:df:a1:e0:00:64
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32s3 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-S3 on /dev/ttyUSB0:
Chip type: ESP32-S3 (QFN56) (revision v0.1)
Features: Wi-Fi, BT 5 (LE), Dual Core + LP Core, 240MHz, Embedded Flash 8MB (GD)
Crystal frequency: 40MHz
MAC: f4:12:fa:87:c6:dc
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Flash will be erased from 0x00000000 to 0x00004fff...
Flash will be erased from 0x00010000 to 0x00039fff...
Flash will be erased from 0x00000000 to 0x00005fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Compressed 18896 bytes to 11758...
Writing at 0x00000000... (100 %)
Wrote 18896 bytes (11758 compressed) at 0x00000000 in 0.5 seconds (effective 279.9 kbit/s)...
Flash will be erased from 0x00010000 to 0x00037fff...
SHA digest in image updated.
Wrote 21280 bytes (13578 compressed) at 0x00000000 in 0.6 seconds (298.1 kbit/s).
Hash of data verified.
Compressed 168208 bytes to 88178...
Writing at 0x00010000... (16 %)
Writing at 0x0001a80f... (33 %)
Writing at 0x000201f1... (50 %)
Writing at 0x00025dcf... (66 %)
Writing at 0x0002d0be... (83 %)
Writing at 0x00036c07... (100 %)
Wrote 168208 bytes (88178 compressed) at 0x00010000 in 2.4 seconds (effective 569.2 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (315.1 kbit/s).
Hash of data verified.
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (effective 478.9 kbit/s)...
Wrote 161744 bytes (90141 compressed) at 0x00010000 in 2.5 seconds (513.7 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
Done

6
docs/en/get-started/flashing-troubleshooting.rst
View File

@@ -8,11 +8,11 @@ Failed to Connect
{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9", esp32c6="GPIO9", esp32h2="GPIO9", esp32p4="GPIO35", esp32c5="GPIO28"}
If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the first stage (ROM) bootloader, and flash firmware. One simple solution to try is to manually reset as described below. If it does not help, you can find more details about possible issues in the `esptool troubleshooting <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ page.
If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool``, the utility that is called by the build system to reset the chip, interact with the first stage (ROM) bootloader, and flash firmware. One simple solution to try is to manually reset as described below. If it does not help, you can find more details about possible issues in the `esptool troubleshooting <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ page.
``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB-to-UART bridge, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
``esptool`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB-to-UART bridge, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
In general, you should have no problems with the `official esp-idf development boards <https://www.espressif.com/en/products/devkits>`_. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases:
In general, you should have no problems with the `official esp-idf development boards <https://www.espressif.com/en/products/devkits>`_. However, ``esptool`` is not able to reset your hardware automatically in the following cases:
- Your hardware does not have the DTR and RTS lines connected to ``{IDF_TARGET_STRAP_GPIO}`` and ``CHIP_PU``.
- The DTR and RTS lines are configured differently.

11
docs/en/get-started/start-project.rst
View File

@@ -27,11 +27,14 @@ This command compiles the application and all ESP-IDF components, then it genera
... (more lines of build system output)
[527/527] Generating hello_world.bin
esptool.py v2.3.1
esptool v5.0.2
Project build complete. To flash, run this command:
../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello_world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
or run 'idf.py -p PORT flash'
Project build complete. To flash, run:
idf.py flash
or
idf.py -p PORT flash
or
esptool -p (PORT) -b 921600 write-flash --flash-mode dio --flash-size detect --flash-freq 40m 0x10000 build/hello_world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
If there are no errors, the build finishes by generating the firmware binary .bin files.

26
docs/en/security/flash-encryption.rst
View File

@@ -13,7 +13,7 @@ This is a quick start guide to {IDF_TARGET_NAME}'s flash encryption feature. Usi
.. note::
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure.py <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure.py`` based counterparts.
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
Introduction
------------
@@ -55,7 +55,7 @@ Other types of data can be encrypted conditionally:
Relevant eFuses
---------------
The flash encryption operation is controlled by various eFuses available on {IDF_TARGET_NAME}. The list of eFuses and their descriptions is given in the table below. The names in eFuse column are also used by ``espefuse.py`` tool and ``idf.py`` based eFuse commands. For usage in the eFuse API, modify the name by adding ``ESP_EFUSE_``, for example: esp_efuse_read_field_bit (ESP_EFUSE_DISABLE_DL_ENCRYPT).
The flash encryption operation is controlled by various eFuses available on {IDF_TARGET_NAME}. The list of eFuses and their descriptions is given in the table below. The names in eFuse column are also used by ``espefuse`` tool and ``idf.py`` based eFuse commands. For usage in the eFuse API, modify the name by adding ``ESP_EFUSE_``, for example: esp_efuse_read_field_bit (ESP_EFUSE_DISABLE_DL_ENCRYPT).
.. Comment: As text in cells of list-table header rows does not wrap, it is necessary to make 0 header rows and apply bold typeface to the first row. Otherwise, the table goes beyond the html page limits on the right.
@@ -164,7 +164,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF
* R/W access control is available for all the eFuse bits listed in the table above.
* The default value of these bits is 0 after manufacturing.
Read and write access to eFuse bits is controlled by appropriate fields in the registers ``WR_DIS`` and ``RD_DIS``. For more information on {IDF_TARGET_NAME} eFuses, see :doc:`eFuse manager <../api-reference/system/efuse>`. To change protection bits of eFuse field using ``idf.py``, use these two commands: efuse-read-protect and efuse-write-protect (idf.py based aliases of espefuse.py commands write_protect_efuse and read_protect_efuse). Example ``idf.py efuse-write-protect DISABLE_DL_ENCRYPT``.
Read and write access to eFuse bits is controlled by appropriate fields in the registers ``WR_DIS`` and ``RD_DIS``. For more information on {IDF_TARGET_NAME} eFuses, see :doc:`eFuse manager <../api-reference/system/efuse>`. To change protection bits of eFuse field using ``idf.py``, use these two commands: efuse-read-protect and efuse-write-protect (idf.py based aliases of espefuse commands write-protect-efuse and read-protect-efuse). Example ``idf.py efuse-write-protect DISABLE_DL_ENCRYPT``.
.. only:: esp32c2
@@ -462,8 +462,8 @@ To use a host generated key, take the following steps:
.. code-block:: bash
espefuse.py --port PORT --chip esp32c2 burn_key_digest secure_boot_signing_key.pem \
burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
espefuse --port PORT --chip esp32c2 burn-key-digest secure_boot_signing_key.pem \
burn-key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
If the key is not burned and the device is started after enabling flash encryption, the {IDF_TARGET_NAME} will generate a random key that software cannot access or modify.
@@ -571,7 +571,7 @@ When using Flash Encryption in production:
- Do not reuse the same flash encryption key between multiple devices. This means that an attacker who copies encrypted data from one device cannot transfer it to a second device.
:esp32: - When using ESP32 V3, if the UART ROM Download Mode is not needed for a production device then it should be disabled to provide an extra level of protection. Do this by calling :cpp:func:`esp_efuse_disable_rom_download_mode` during application startup. Alternatively, configure the project :ref:`CONFIG_ESP32_REV_MIN` level to 3 (targeting ESP32 V3 only) and select the :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` to "Permanently disable ROM Download Mode (recommended)". The ability to disable ROM Download Mode is not available on earlier ESP32 versions.
:not esp32: - The UART ROM Download Mode should be disabled entirely if it is not needed, or permanently set to "Secure Download Mode" otherwise. Secure Download Mode permanently limits the available commands to updating SPI config, changing baud rate, basic flash write, and returning a summary of the currently enabled security features with the `get_security_info` command. The default behaviour is to set Secure Download Mode on first boot in Release mode. To disable Download Mode entirely, select :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` to "Permanently disable ROM Download Mode (recommended)" or call :cpp:func:`esp_efuse_disable_rom_download_mode` at runtime.
:not esp32: - The UART ROM Download Mode should be disabled entirely if it is not needed, or permanently set to "Secure Download Mode" otherwise. Secure Download Mode permanently limits the available commands to updating SPI config, changing baud rate, basic flash write, and returning a summary of the currently enabled security features with the `get-security-info` command. The default behaviour is to set Secure Download Mode on first boot in Release mode. To disable Download Mode entirely, select :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` to "Permanently disable ROM Download Mode (recommended)" or call :cpp:func:`esp_efuse_disable_rom_download_mode` at runtime.
- Enable :doc:`Secure Boot <secure-boot-v2>` as an extra layer of protection, and to prevent an attacker from selectively corrupting any part of the flash before boot.
Enable Flash Encryption Externally
@@ -961,7 +961,7 @@ However, before the first boot you can choose to keep any of these features enab
Write protection of all the three eFuses is controlled by one bit. It means that write-protecting one eFuse bit will inevitably write-protect all unset eFuse bits.
Write protecting these eFuses to keep them unset is not currently very useful, as ``esptool.py`` does not support reading encrypted flash.
Write protecting these eFuses to keep them unset is not currently very useful, as ``esptool`` does not support reading encrypted flash.
.. only:: esp32
@@ -1018,7 +1018,7 @@ For example, these are the steps to encrypt the file ``my-app.bin`` to flash at
idf.py secure-encrypt-flash-data --aes-xts --keyfile /path/to/key.bin --address 0x10000 --output my-app-ciphertext.bin my-app.bin
The file ``my-app-ciphertext.bin`` can then be flashed to offset 0x10000 using ``esptool.py``. To see all of the command line options recommended for ``esptool.py``, see the output printed when ``idf.py build`` succeeds.
The file ``my-app-ciphertext.bin`` can then be flashed to offset 0x10000 using ``esptool``. To see all of the command line options recommended for ``esptool``, see the output printed when ``idf.py build`` succeeds.
.. note::
@@ -1075,9 +1075,9 @@ The following sections provide some reference information about the operation of
- The high 19 bits of the block offset (bit 5 to bit 23) are XORed with the main flash encryption key. This range is chosen for two reasons: the maximum flash size is 16MB (24 bits), and each block is 32 bytes so the least significant 5 bits are always zero.
- There is a particular mapping from each of the 19 block offset bits to the 256 bits of the flash encryption key to determine which bit is XORed with which. See the variable ``_FLASH_ENCRYPTION_TWEAK_PATTERN`` in the ``espsecure.py`` source code for complete mapping.
- There is a particular mapping from each of the 19 block offset bits to the 256 bits of the flash encryption key to determine which bit is XORed with which. See the variable ``_FLASH_ENCRYPTION_TWEAK_PATTERN`` in the ``espsecure`` source code for complete mapping.
- To see the full flash encryption algorithm implemented in Python, refer to the ``_flash_encryption_operation()`` function in the ``espsecure.py`` source code.
- To see the full flash encryption algorithm implemented in Python, refer to the ``_flash_encryption_operation()`` function in the ``espsecure`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
@@ -1092,7 +1092,7 @@ The following sections provide some reference information about the operation of
- The flash encryption key is stored in one or two ``BLOCK_KEYN`` eFuses and, by default, is protected from further writes or software readout.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
@@ -1108,7 +1108,7 @@ The following sections provide some reference information about the operation of
- The flash encryption key is stored in one ``BLOCK_KEYN`` eFuse and, by default, is protected from further writes or software readout.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
@@ -1123,7 +1123,7 @@ The following sections provide some reference information about the operation of
- The flash encryption key is stored in ``BLOCK_KEY0`` eFuse and, by default, is protected from further writes or software readout.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND

16
docs/en/security/secure-boot-v1.rst
View File

@@ -19,7 +19,7 @@ Secure boot is separate from the :doc:`flash-encryption` feature, and you can us
.. note::
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure.py <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure.py`` based counterparts.
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
Background
----------
@@ -105,7 +105,7 @@ How to Enable Secure Boot
For production environments, we recommend generating the key pair using OpenSSL or another industry-standard encryption program. See :ref:`secure-boot-generate-key` for more details.
5. Run ``idf.py bootloader`` to build a secure boot-enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool.py write_flash``.
5. Run ``idf.py bootloader`` to build a secure boot-enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool write-flash``.
.. _secure-boot-resume-normal-flashing:
@@ -149,7 +149,7 @@ To enable a reflashable bootloader:
1. In the :ref:`project-configuration-menu`, select ``Bootloader Config`` > :ref:`CONFIG_SECURE_BOOT` > ``CONFIG_SECURE_BOOT_V1_ENABLED`` > :ref:`CONFIG_SECURE_BOOTLOADER_MODE` > ``Reflashable``.
2. If necessary, set the :ref:`CONFIG_SECURE_BOOTLOADER_KEY_ENCODING` based on the coding scheme used by the device. The coding scheme is shown in the ``Features`` line when ``esptool.py`` connects to the chip, or in the ``idf.py efuse-summary`` output.
2. If necessary, set the :ref:`CONFIG_SECURE_BOOTLOADER_KEY_ENCODING` based on the coding scheme used by the device. The coding scheme is shown in the ``Features`` line when ``esptool`` connects to the chip, or in the ``idf.py efuse-summary`` output.
3. Please follow the steps shown in :ref:`secure-boot-generate-key` to generate the signing key. The path of the generated key file must be specified in the ``Secure Boot Configuration`` menu.
@@ -181,7 +181,7 @@ Remember that the strength of the secure boot system depends on keeping the sign
Remote Signing of Images
------------------------
For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine, which is the default ESP-IDF secure boot configuration. The ``espsecure.py`` command line program can be used to sign app images & partition table data for secure boot, on a remote system.
For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine, which is the default ESP-IDF secure boot configuration. The ``espsecure`` command line program can be used to sign app images & partition table data for secure boot, on a remote system.
To use remote signing, disable the option ``Sign binaries during build``. The private signing key does not need to be present on the build system. However, the public signature verification key is required because it is compiled into the bootloader, and can be used to verify image signatures during OTA updates.
@@ -189,7 +189,7 @@ To extract the public key from the private key:
.. code-block::
espsecure.py extract_public_key --keyfile PRIVATE_SIGNING_KEY PUBLIC_VERIFICATION_KEY
espsecure extract-public-key --keyfile PRIVATE_SIGNING_KEY PUBLIC_VERIFICATION_KEY
The path to the public signature verification key needs to be specified in the menuconfig under ``Secure boot public signature verification key`` in order to build the secure bootloader.
@@ -211,7 +211,7 @@ Secure Boot Best Practices
* Generate the signing key on a system with a quality source of entropy.
* Keep the signing key private at all times. A leak of this key will compromise the secure boot system.
* Do not allow any third party to observe any aspects of the key generation or signing process using ``espsecure.py`` or ``idf.py secure-`` subcommands. Both processes are vulnerable to timing or other side-channel attacks.
* Do not allow any third party to observe any aspects of the key generation or signing process using ``espsecure`` or ``idf.py secure-`` subcommands. Both processes are vulnerable to timing or other side-channel attacks.
* Enable all secure boot options in Secure Boot Configuration. These include flash encryption, disabling of JTAG, disabling BASIC ROM interpreter, and disabling the UART bootloader encrypted flash access.
* Use secure boot in combination with :doc:`flash-encryption` to prevent local readout of the flash contents.
@@ -245,7 +245,7 @@ Secure Bootloader Digest Algorithm
Starting with an "image" of binary data as input, this algorithm generates a digest as output. The digest is sometimes referred to as an "abstract" in hardware documentation.
For a Python version of this algorithm, see the ``espsecure.py`` tool in the :component:`/esptool_py` directory. Specifically, the ``digest_secure_bootloader`` command.
For a Python version of this algorithm, see the ``espsecure`` tool in the :component:`/esptool_py` directory. Specifically, the ``digest-secure-bootloader`` command.
Items marked with (^) are to fulfill hardware restrictions, as opposed to cryptographic restrictions.
@@ -309,7 +309,7 @@ The output of the ``idf.py secure-digest-secure-bootloader`` command is a single
.. code-block::
esptool.py write_flash 0x0 bootloader-digest.bin
esptool write-flash 0x0 bootloader-digest.bin
.. _secure-boot-and-flash-encr:

16
docs/en/security/secure-boot-v2.rst
View File

@@ -50,7 +50,7 @@ Secure Boot v2
.. note::
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure.py <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure.py`` based counterparts.
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
Background
----------
@@ -350,7 +350,7 @@ In the Secure Boot v2 scheme, the application image is padded to the flash MMU p
- Default flash MMU page size is 64 KB
:SOC_MMU_PAGE_SIZE_CONFIGURABLE: - {IDF_TARGET_NAME} supports configurable flash MMU page size, and ``CONFIG_MMU_PAGE_SIZE`` gets set based on the :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`
- Secure padding is applied through the option ``--secure-pad-v2`` in the ``elf2image`` conversion using ``esptool.py``
- Secure padding is applied through the option ``--secure-pad-v2`` in the ``elf2image`` conversion using ``esptool``
The following table explains the Secure Boot v2 signed image with secure padding and signature block appended:
@@ -487,7 +487,7 @@ How To Enable Secure Boot v2
For production environments, we recommend generating the key pair using OpenSSL or another industry-standard encryption program. See :ref:`secure-boot-v2-generate-key` for more details.
7. Run ``idf.py bootloader`` to build a Secure Boot-enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool.py write_flash``.
7. Run ``idf.py bootloader`` to build a Secure Boot-enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool write-flash``.
8. When you are ready to flash the bootloader, run the specified command and then wait for flashing to complete. You have to enter it yourself, this step is not performed by the build system.
@@ -621,7 +621,7 @@ Remote Signing of Images
Signing Using ``idf.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine (which is the default ESP-IDF Secure Boot configuration). The ``espsecure.py`` command line program can be used to sign app images and partition table data for Secure Boot, on a remote system.
For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine (which is the default ESP-IDF Secure Boot configuration). The ``espsecure`` command line program can be used to sign app images and partition table data for Secure Boot, on a remote system.
To use remote signing, disable the option :ref:`CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES` and build the firmware. The private signing key does not need to be present on the build system.
@@ -663,7 +663,7 @@ In such cases, disable the option :ref:`CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES
.. note::
For all the above three remote signing workflows, the signed binary is written to the filename provided to the ``--output`` argument, and the option ``--append_signatures`` allows us to append multiple signatures (up to 3) to the image.
For all the above three remote signing workflows, the signed binary is written to the filename provided to the ``--output`` argument, and the option ``--append-signatures`` allows us to append multiple signatures (up to 3) to the image.
.. only:: not SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
@@ -689,7 +689,7 @@ Secure Boot Best Practices
* Between 1 and 3 {IDF_TARGET_SBV2_KEY} public key pairs (Keys #0, #1, #2) should be computed independently and stored separately.
* The KEY_DIGEST eFuses should be write-protected after being programmed.
* The unused KEY_DIGEST slots must have their corresponding KEY_REVOKE eFuse burned to permanently disable them. This must happen before the device leaves the factory.
* The eFuses can either be written by the second stage bootloader during first boot after enabling ``Secure Boot v2`` from menuconfig or can be done using ``espefuse.py`` which communicates with the serial bootloader program in ROM.
* The eFuses can either be written by the second stage bootloader during first boot after enabling ``Secure Boot v2`` from menuconfig or can be done using ``espefuse`` which communicates with the serial bootloader program in ROM.
* The KEY_DIGESTs should be numbered sequentially beginning at key digest #0. If key digest #1 is used, key digest #0 should be used. If key digest #2 is used, key digest #0 & #1 must be used.
* The second stage bootloader is non-OTA upgradeable, and is signed using at least one, possibly all three, private keys and flashed in the factory.
* Apps should only be signed with a single private key, with the others being stored securely elsewhere. However, they may be signed with multiple private keys if some are being revoked, see :ref:`secure-boot-v2-key-revocation` below.
@@ -704,14 +704,14 @@ Secure Boot Best Practices
.. code-block::
idf.py secure-sign-data -k secure_boot_signing_key2.pem --append_signatures -o signed_bootloader.bin build/bootloader/bootloader.bin
idf.py secure-sign-data -k secure_boot_signing_key2.pem --append-signatures -o signed_bootloader.bin build/bootloader/bootloader.bin
* While signing with multiple private keys, it is recommended that the private keys be signed independently, if possible on different servers and stored separately.
* You can check the signatures attached to a binary using:
.. code-block::
espsecure.py signature_info_v2 datafile.bin
espsecure signature-info-v2 datafile.bin
.. only:: SOC_ECDSA_SUPPORT_CURVE_P384

116
docs/en/security/security-features-enablement-workflows.rst
View File

@@ -9,7 +9,7 @@ Security Features Enablement Workflows
{IDF_TARGET_CRYPT_CNT:default="SPI_BOOT_CRYPT_CNT",esp32="FLASH_CRYPT_CNT"}
{IDF_TARGET_CRYPT_CNT_MAX_VAL:default="7",esp32="127"}
{IDF_TARGET_SBV2_DEFAULT_SCHEME:default="RSA", esp32c2="ECDSA (V2)"}
{IDF_TARGET_FLASH_ENC_ARGS:default="--aes_xts", esp32=""}
{IDF_TARGET_FLASH_ENC_ARGS:default="--aes-xts", esp32=""}
Introduction
------------
@@ -83,7 +83,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
esptool.py --port PORT erase_flash
esptool --port PORT erase-flash
2. Generate a Flash Encryption key
@@ -93,7 +93,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
@@ -101,20 +101,20 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
else if :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-256 (512-bit key):
.. code-block:: bash
espsecure.py generate_flash_encryption_key --keylen 512 my_flash_encryption_key.bin
espsecure generate-flash-encryption-key --keylen 512 my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
@@ -122,13 +122,13 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
else if :ref:`Size of generated AES-XTS key <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` is AES-128 key derived from 128 bits (SHA256(128 bits)):
.. code-block:: bash
espsecure.py generate_flash_encryption_key --keylen 128 my_flash_encryption_key.bin
espsecure generate-flash-encryption-key --keylen 128 my_flash_encryption_key.bin
3. Burn the Flash Encryption key into eFuse
@@ -142,13 +142,13 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin
espefuse --port PORT burn-key flash_encryption my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin KEYPURPOSE
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin KEYPURPOSE
where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``. And ``KEYPURPOSE`` is either ``XTS_AES_256_KEY_1``, ``XTS_AES_256_KEY_2``, ``XTS_AES_128_KEY``. See `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ for a description of the key purposes.
@@ -156,28 +156,28 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
For AES-256 (512-bit key) - ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2``. ``espefuse.py`` supports burning both these two key purposes together with a 512-bit key to two separate key blocks via the virtual key purpose ``XTS_AES_256_KEY``. When this is used ``espefuse.py`` will burn the first 256 bits of the key to the specified ``BLOCK`` and burn the corresponding block key purpose to ``XTS_AES_256_KEY_1``. The last 256 bits of the key will be burned to the first free key block after ``BLOCK`` and the corresponding block key purpose to ``XTS_AES_256_KEY_2``
For AES-256 (512-bit key) - ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2``. ``espefuse`` supports burning both these two key purposes together with a 512-bit key to two separate key blocks via the virtual key purpose ``XTS_AES_256_KEY``. When this is used ``espefuse`` will burn the first 256 bits of the key to the specified ``BLOCK`` and burn the corresponding block key purpose to ``XTS_AES_256_KEY_1``. The last 256 bits of the key will be burned to the first free key block after ``BLOCK`` and the corresponding block key purpose to ``XTS_AES_256_KEY_2``
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_256_KEY
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin XTS_AES_256_KEY
If you wish to specify exactly which two blocks are used then it is possible to divide the key into two 256-bit keys, and manually burn each half with ``XTS_AES_256_KEY_1`` and ``XTS_AES_256_KEY_2`` as key purposes:
.. code-block:: bash
split -b 32 my_flash_encryption_key.bin my_flash_encryption_key.bin
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin.aa XTS_AES_256_KEY_1
espefuse.py --port PORT burn_key BLOCK+1 my_flash_encryption_key.bin.ab XTS_AES_256_KEY_2
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin.aa XTS_AES_256_KEY_1
espefuse --port PORT burn-key BLOCK+1 my_flash_encryption_key.bin.ab XTS_AES_256_KEY_2
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``.
@@ -187,20 +187,20 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK_KEY0 flash_encryption_key256.bin XTS_AES_128_KEY
espefuse --port PORT burn-key BLOCK_KEY0 flash_encryption_key256.bin XTS_AES_128_KEY
For AES-128 key derived from SHA256(128 eFuse bits) - ``XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS``. The FE key will be written in the lower part of eFuse BLOCK_KEY0. The upper 128 bits are not used and will remain available for reading by software. Using the special mode of the espefuse tool, shown in the ``For burning both keys together`` section below, the user can write their data to it using any espefuse commands.
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
espefuse --port PORT burn-key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
For burning both keys together (Secure Boot and Flash Encryption):
.. code-block:: bash
espefuse.py --port PORT --chip esp32c2 burn_key_digest secure_boot_signing_key.pem \
burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
espefuse --port PORT --chip esp32c2 burn-key-digest secure_boot_signing_key.pem \
burn-key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
.. only:: SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK
@@ -216,7 +216,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse {IDF_TARGET_CRYPT_CNT} {IDF_TARGET_CRYPT_CNT_MAX_VAL}
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse {IDF_TARGET_CRYPT_CNT} {IDF_TARGET_CRYPT_CNT_MAX_VAL}
.. only:: esp32
@@ -224,7 +224,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse FLASH_CRYPT_CONFIG 0xF
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse FLASH_CRYPT_CONFIG 0xF
5. Burn Flash Encryption-related security eFuses as listed below
@@ -256,11 +256,11 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1
espefuse burn-efuse --port PORT EFUSE_NAME 0x1
.. note::
Please update the ``EFUSE_NAME`` with the eFuse that you need to burn. Multiple eFuses can be burned at the same time by appending them to the above command (e.g., ``EFUSE_NAME VAL EFUSE_NAME2 VAL2``). More documentation about `espefuse.py` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_.
Please update the ``EFUSE_NAME`` with the eFuse that you need to burn. Multiple eFuses can be burned at the same time by appending them to the above command (e.g., ``EFUSE_NAME VAL EFUSE_NAME2 VAL2``). More documentation about `espefuse` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_.
.. only:: esp32
@@ -270,7 +270,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
espefuse.py --port PORT write_protect_efuse DIS_CACHE
espefuse --port PORT write-protect-efuse DIS_CACHE
.. note::
@@ -284,7 +284,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
espefuse.py --port PORT write_protect_efuse DIS_ICACHE
espefuse --port PORT write-protect-efuse DIS_ICACHE
.. note::
@@ -312,15 +312,15 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code-block:: bash
espsecure.py encrypt_flash_data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} --output bootloader-enc.bin build/bootloader/bootloader.bin
espsecure encrypt-flash-data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} --output bootloader-enc.bin build/bootloader/bootloader.bin
espsecure.py encrypt_flash_data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
espsecure encrypt-flash-data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
espsecure.py encrypt_flash_data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
espsecure encrypt-flash-data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
In the above command, the offsets are used for a sample firmware, and the actual offset for your firmware can be obtained by checking the partition table entry or by running `idf.py partition-table`. Please note that not all the binaries need to be encrypted, the encryption applies only to those generated from the partitions which are marked as ``encrypted`` in the partition table definition file. Other binaries are flashed unencrypted, i.e., as a plain output of the build process.
The above files can then be flashed to their respective offset using ``esptool.py``. To see all of the command line options recommended for ``esptool.py``, see the output printed when ``idf.py build`` succeeds.
The above files can then be flashed to their respective offset using ``esptool``. To see all of the command line options recommended for ``esptool``, see the output printed when ``idf.py build`` succeeds.
When the application contains the following partition: ``otadata`` and ``nvs_encryption_keys``, they need to be encrypted as well. Please refer to :ref:`encrypted-partitions` for more details about encrypted partitions.
@@ -330,9 +330,9 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. only:: esp32
If your ESP32 uses non-default :ref:`FLASH_CRYPT_CONFIG value in eFuse <setting-flash-crypt-config>` then you will need to pass the ``--flash_crypt_conf`` argument to ``espsecure.py`` to set the matching value. This will not happen when the Flash Encryption is enabled by the second stage bootloader but may happen when burning eFuses manually to enable Flash Encryption.
If your ESP32 uses non-default :ref:`FLASH_CRYPT_CONFIG value in eFuse <setting-flash-crypt-config>` then you will need to pass the ``--flash-crypt-conf`` argument to ``espsecure`` to set the matching value. This will not happen when the Flash Encryption is enabled by the second stage bootloader but may happen when burning eFuses manually to enable Flash Encryption.
The command ``espsecure.py decrypt_flash_data`` can be used with the same options (and different input or output files), to decrypt ciphertext flash contents or a previously encrypted file.
The command ``espsecure decrypt-flash-data`` can be used with the same options (and different input or output files), to decrypt ciphertext flash contents or a previously encrypted file.
8. Secure the ROM download mode
@@ -352,7 +352,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS
espefuse --port PORT burn-efuse UART_DOWNLOAD_DIS
.. only:: not esp32
@@ -366,7 +366,7 @@ In this case all the eFuses related to Flash Encryption are written with help of
.. code:: bash
espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD
espefuse --port PORT burn-efuse ENABLE_SECURITY_DOWNLOAD
.. important::
@@ -396,7 +396,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py generate_signing_key --version 2 --scheme rsa3072 secure_boot_signing_key.pem
espsecure generate-signing-key --version 2 --scheme rsa3072 secure_boot_signing_key.pem
.. only:: SOC_SECURE_BOOT_V2_ECC
@@ -404,7 +404,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py generate_signing_key --version 2 --scheme ecdsa256 secure_boot_signing_key.pem
espsecure generate-signing-key --version 2 --scheme ecdsa256 secure_boot_signing_key.pem
.. only:: not SOC_ECDSA_SUPPORT_CURVE_P384
@@ -424,7 +424,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py digest_sbv2_public_key --keyfile secure_boot_signing_key.pem --output digest.bin
espsecure digest-sbv2-public-key --keyfile secure_boot_signing_key.pem --output digest.bin
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
@@ -438,19 +438,19 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT --chip esp32 burn_key secure_boot_v2 digest.bin
espefuse --port PORT --chip esp32 burn-key secure_boot_v2 digest.bin
.. only:: esp32c2
.. code:: bash
espefuse.py --port PORT --chip esp32c2 burn_key KEY_BLOCK0 digest.bin SECURE_BOOT_DIGEST
espefuse --port PORT --chip esp32c2 burn-key KEY_BLOCK0 digest.bin SECURE_BOOT_DIGEST
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_key BLOCK digest.bin SECURE_BOOT_DIGEST0
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-key BLOCK digest.bin SECURE_BOOT_DIGEST0
where ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``.
@@ -464,13 +464,13 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT --chip esp32 burn_efuse ABS_DONE_1
espefuse --port PORT --chip esp32 burn-efuse ABS_DONE_1
.. only:: not esp32
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse SECURE_BOOT_EN
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse SECURE_BOOT_EN
.. only:: SOC_ECDSA_SUPPORT_CURVE_P384
@@ -478,7 +478,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse SECURE_BOOT_SHA384_EN
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse SECURE_BOOT_SHA384_EN
5. Burn relevant eFuses
@@ -507,11 +507,11 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1
espefuse burn-efuse --port PORT EFUSE_NAME 0x1
.. note::
Please update the EFUSE_NAME with the eFuse that you need to burn. Multiple eFuses can be burned at the same time by appending them to the above command (e.g., EFUSE_NAME VAL EFUSE_NAME2 VAL2). More documentation about `espefuse.py` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_
Please update the EFUSE_NAME with the eFuse that you need to burn. Multiple eFuses can be burned at the same time by appending them to the above command (e.g., EFUSE_NAME VAL EFUSE_NAME2 VAL2). More documentation about `espefuse` can be found `here <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_
B) Secure Boot v2-related eFuses
@@ -521,7 +521,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py -p $ESPPORT write_protect_efuse RD_DIS
espefuse -p $ESPPORT write-protect-efuse RD_DIS
.. important::
@@ -535,7 +535,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse EFUSE_REVOKE_BIT
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse EFUSE_REVOKE_BIT
The ``EFUSE_REVOKE_BIT`` in the above command can be ``SECURE_BOOT_KEY_REVOKE0`` or ``SECURE_BOOT_KEY_REVOKE1`` or ``SECURE_BOOT_KEY_REVOKE2``. Please note that only the unused key digests must be revoked. Once revoked, the respective digest cannot be used again.
@@ -565,9 +565,9 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output bootloader-signed.bin build/bootloader/bootloader.bin
espsecure sign-data --version 2 --keyfile secure_boot_signing_key.pem --output bootloader-signed.bin build/bootloader/bootloader.bin
espsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output my-app-signed.bin build/my-app.bin
espsecure sign-data --version 2 --keyfile secure_boot_signing_key.pem --output my-app-signed.bin build/my-app.bin
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
@@ -575,9 +575,9 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py sign_data --keyfile secure_boot_signing_key2.pem --version 2 --append_signatures -o bootloader-signed2.bin bootloader-signed.bin
espsecure sign-data --keyfile secure_boot_signing_key2.pem --version 2 --append-signatures -o bootloader-signed2.bin bootloader-signed.bin
espsecure.py sign_data --keyfile secure_boot_signing_key2.pem --version 2 --append_signatures -o my-app-signed2.bin my-app-signed.bin
espsecure sign-data --keyfile secure_boot_signing_key2.pem --version 2 --append-signatures -o my-app-signed2.bin my-app-signed.bin
The same process can be repeated for the third key. Note that the names of the input and output files must not be the same.
@@ -585,9 +585,9 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espsecure.py signature_info_v2 bootloader-signed.bin
espsecure signature-info-v2 bootloader-signed.bin
The above files along with other binaries (e.g., partition table) can then be flashed to their respective offset using ``esptool.py``. To see all of the command line options recommended for ``esptool.py``, see the output printed when ``idf.py build`` succeeds. The flash offset for your firmware can be obtained by checking the partition table entry or by running ``idf.py partition-table``.
The above files along with other binaries (e.g., partition table) can then be flashed to their respective offset using ``esptool``. To see all of the command line options recommended for ``esptool``, see the output printed when ``idf.py build`` succeeds. The flash offset for your firmware can be obtained by checking the partition table entry or by running ``idf.py partition-table``.
8. Secure the ROM download mode
@@ -607,7 +607,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS
espefuse --port PORT burn-efuse UART_DOWNLOAD_DIS
.. only:: not esp32
@@ -621,7 +621,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us
.. code:: bash
espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD
espefuse --port PORT burn-efuse ENABLE_SECURITY_DOWNLOAD
Secure Boot v2 Guidelines
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -667,7 +667,7 @@ The details about NVS encryption and related schemes can be found at :doc:`NVS E
.. code:: bash
espefuse.py --port PORT burn_key BLOCK hmac_key.bin HMAC_UP
espefuse --port PORT burn-key BLOCK hmac_key.bin HMAC_UP
Here, ``BLOCK`` is a free keyblock between ``BLOCK_KEY0`` and ``BLOCK_KEY5``.
@@ -697,7 +697,7 @@ The details about NVS encryption and related schemes can be found at :doc:`NVS E
5. Flash NVS partition
The NVS partition (``nvs_encr_partition.bin``) generated in Step 3 can then be flashed to its respective offset using ``esptool.py``. To see all of the command line options recommended for ``esptool.py``, check the output printed when ``idf.py build`` succeeds.
The NVS partition (``nvs_encr_partition.bin``) generated in Step 3 can then be flashed to its respective offset using ``esptool``. To see all of the command line options recommended for ``esptool``, check the output printed when ``idf.py build`` succeeds.
If Flash Encryption is enabled for the chip, please encrypt the partition first before flashing. More details please refer to the flashing related steps of `Flash Encryption workflow <enable-flash-encryption-externally_>`_.
@@ -743,6 +743,6 @@ In this case we generate NVS Encryption keys on a host. This key is then flashed
4. Flash NVS partition and NVS encryption keys
The NVS partition (``nvs_encr_partition.bin``) and NVS encryption key (``nvs_encr_key.bin``) can then be flashed to their respective offset using ``esptool.py``. To see all of the command line options recommended for ``esptool.py``, check the output print when ``idf.py build`` succeeds.
The NVS partition (``nvs_encr_partition.bin``) and NVS encryption key (``nvs_encr_key.bin``) can then be flashed to their respective offset using ``esptool``. To see all of the command line options recommended for ``esptool``, check the output print when ``idf.py build`` succeeds.
If Flash Encryption is enabled for the chip, then please encrypt the partition first before flashing. You may refer the flashing related steps of `Flash Encryption workflow <enable-flash-encryption-externally_>`_.

10
docs/en/security/security.rst
View File

@@ -11,7 +11,7 @@ This guide provides an overview of the overall security features available in va
.. note::
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure.py <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure.py`` based counterparts.
In this guide, most used commands are in the form of ``idf.py secure-<command>``, which is a wrapper around corresponding ``espsecure <command>``. The ``idf.py`` based commands provides more user-friendly experience, although may lack some of the advanced functionality of their ``espsecure`` based counterparts.
.. only:: TARGET_SUPPORT_QEMU
@@ -55,7 +55,7 @@ Secure Boot Best Practices
* Generate the signing key on a system with a quality source of entropy.
* Always keep the signing key private. A leak of this key will compromise the Secure Boot system.
* Do not allow any third party to observe any aspects of the key generation or signing process using ``idf.py secure-`` or ``espsecure.py`` commands. Both processes are vulnerable to timing or other side-channel attacks.
* Do not allow any third party to observe any aspects of the key generation or signing process using ``idf.py secure-`` or ``espsecure`` commands. Both processes are vulnerable to timing or other side-channel attacks.
* Ensure that all security eFuses have been correctly programmed, including disabling of the debug interfaces, non-required boot mediums (e.g., UART DL mode), etc.
@@ -183,7 +183,7 @@ UART Download Mode
.. important::
If UART Download mode is disabled then ``esptool.py`` can not work on the device.
If UART Download mode is disabled then ``esptool`` can not work on the device.
.. only:: SOC_SUPPORTS_SECURE_DL_MODE
@@ -191,12 +191,12 @@ UART Download Mode
* Secure UART Download mode can also be enabled by calling :cpp:func:`esp_efuse_enable_rom_secure_download_mode`.
* This mode does not allow any arbitrary code to execute if downloaded through the UART download mode.
* It also limits the available commands in Download mode to update SPI config, e.g., changing baud rate, basic flash write, and the command to return a summary of currently enabled security features (``get_security_info``).
* It also limits the available commands in Download mode to update SPI config, e.g., changing baud rate, basic flash write, and the command to return a summary of currently enabled security features (``get-security-info``).
* To disable Download Mode entirely, select the :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` to the recommended option ``Permanently disable ROM Download Mode`` or call :cpp:func:`esp_efuse_disable_rom_download_mode` at runtime.
.. important::
In Secure UART Download mode, ``esptool.py`` can only work with the argument ``--no-stub``.
In Secure UART Download mode, ``esptool`` can only work with the argument ``--no-stub``.
.. only:: SOC_WIFI_SUPPORTED

2
docs/zh_CN/COPYRIGHT.rst
View File

@@ -145,7 +145,7 @@ TJpgDec - Tiny JPEG 解压器 R0.01 (C) 2011 ChaN，是一个用于小型嵌入
.. _Newlib: https://sourceware.org/newlib/
.. _Picolibc: https://keithp.com/picolibc/
.. _FreeRTOS: https://freertos.org/
.. _esptool.py: https://github.com/espressif/esptool
.. _esptool: https://github.com/espressif/esptool
.. _LWIP: https://savannah.nongnu.org/projects/lwip/
.. _TinyBasic: https://github.com/BleuLlama/TinyBasicPlus
.. _miniz: https://code.google.com/archive/p/miniz/

14
docs/zh_CN/api-guides/build-system.rst
View File

@@ -54,7 +54,7 @@ idf.py
- CMake_，配置待构建的项目
- Ninja_，用于构建项目
- `esptool.py`_，烧录目标硬件设备
- `esptool`_，烧录目标硬件设备
可通过 ``idf.py`` 配置构建系统，具体可参考 :doc:`IDF 前端工具 <tools/idf-py>`。
@@ -718,7 +718,7 @@ project_include.cmake
如果组件的某些构建行为需要在组件 CMakeLists 文件之前被执行，你可以在组件目录下创建名为 ``project_include.cmake`` 的文件，``project.cmake`` 在运行过程中会导入此 CMake 文件。
``project_include.cmake`` 文件在 ESP-IDF 内部使用，以定义项目范围内的构建功能，比如 ``esptool.py`` 的命令行参数和 ``bootloader`` 这个特殊的应用程序。
``project_include.cmake`` 文件在 ESP-IDF 内部使用，以定义项目范围内的构建功能，比如 ``esptool`` 的命令行参数和 ``bootloader`` 这个特殊的应用程序。
与组件 ``CMakeLists.txt`` 文件有所不同，在导入 ``project_include.cmake`` 文件的时候，当前源文件目录（即 ``CMAKE_CURRENT_SOURCE_DIR`` 和工作目录）为项目目录。如果想获得当前组件的绝对路径，可以使用 ``COMPONENT_PATH`` 变量。
@@ -1109,7 +1109,7 @@ ExternalProject 的依赖与构建清理
flash 参数
==========
有些情况下，我们希望在没有 IDF 时也能烧写目标板，为此，我们希望可以保存已构建的二进制文件、esptool.py 和 esptool write_flash 命令的参数。可以通过编写一段简单的脚本来保存二进制文件和 esptool.py。
有些情况下，我们希望在没有 IDF 时也能烧写目标板，为此，我们希望可以保存已构建的二进制文件、esptool 和 esptool write-flash 命令的参数。可以通过编写一段简单的脚本来保存二进制文件和 esptool。
运行项目构建之后，构建目录将包含项目二进制输出文件（``.bin`` 文件），同时也包含以下烧录数据文件：
@@ -1119,9 +1119,9 @@ flash 参数
.. highlight:: bash
你可以参照如下命令将任意烧录参数文件传递给 ``esptool.py``::
你可以参照如下命令将任意烧录参数文件传递给 ``esptool``::
python esptool.py --chip {IDF_TARGET_PATH_NAME} write_flash @build/flash_project_args
esptool --chip {IDF_TARGET_PATH_NAME} write-flash @build/flash_project_args
也可以手动复制参数文件中的数据到命令行中执行。
@@ -1568,7 +1568,7 @@ ESP-IDF 中的组件使用了第三方的 Git CMake 集成模块（:idf_file:`/t
- ``compile_commands.json`` 是标准格式的 JSON 文件，它描述了在项目中参与编译的每个源文件。CMake 其中的一个功能就是生成此文件，许多 IDE 都知道如何解析此文件。
- ``project_description.json`` 包含有关 ESP-IDF 项目、已配置路径等的一些常规信息。
- ``flasher_args.json`` 包含 esptool.py 工具用于烧录项目二进制文件的参数，此外还有 ``flash_*_args`` 文件，可直接与 esptool.py 一起使用。更多详细信息请参阅 :ref:`flash_parameters`。
- ``flasher_args.json`` 包含 esptool 工具用于烧录项目二进制文件的参数，此外还有 ``flash_*_args`` 文件，可直接与 esptool 一起使用。更多详细信息请参阅 :ref:`flash_parameters`。
- ``CMakeCache.txt`` 是 CMake 的缓存文件，包含 CMake 进程、工具链等其它信息。
- ``config/sdkconfig.json`` 包含 JSON 格式的项目配置结果。
- ``config/kconfig_menus.json`` 是在 menuconfig 中显示菜单的 JSON 格式版本，用于外部 IDE 的 UI。
@@ -1751,7 +1751,7 @@ CMake 中不可用的功能
.. _esp-idf-template: https://github.com/espressif/esp-idf-template
.. _Cmake: https://cmake.org
.. _ninja: https://ninja-build.org
.. _esptool.py: https://github.com/espressif/esptool/#readme
.. _esptool: https://github.com/espressif/esptool/#readme
.. _CMake v3.22 官方文档: https://cmake.org/cmake/help/v3.22/index.html
.. _cmake 命令行文档: https://cmake.org/cmake/help/v3.22/manual/cmake.1.html#options
.. _cmake add_library: https://cmake.org/cmake/help/v3.22/command/add_library.html

2
docs/zh_CN/api-guides/flash_psram_config.rst
View File

@@ -241,7 +241,7 @@ F4R4 硬件
load:0x3fcd0108,len:0x171c
ets_loader.c 78
这可能意味着必要的 efuse 未得到正确烧录。请使用命令 ``espefuse.py summary``，检查芯片的 eFuse 位。
这可能意味着必要的 efuse 未得到正确烧录。请使用命令 ``espefuse summary``，检查芯片的 eFuse 位。
一级 (ROM) 引导加载程序可通过 eFuse 位 ``FLASH_TYPE`` 将 flash 复位为默认模式（SPI 模式）。如果未烧录此位，且 flash 处于 OPI 模式，则一级 (ROM) 引导加载程序可能无法从 flash 中读取并加载以下图像。

8
docs/zh_CN/api-guides/partition-tables.rst
View File

@@ -311,14 +311,14 @@ MD5 校验和
烧写分区表
----------
* ``idf.py partition-table-flash`` ：使用 esptool.py 工具烧写分区表。
* ``idf.py partition-table-flash`` ：使用 esptool 工具烧写分区表。
* ``idf.py flash`` ：会烧写所有内容，包括分区表。
在执行 ``idf.py partition-table`` 命令时，手动烧写分区表的命令也将打印在终端上。
.. note::
分区表的更新并不会擦除根据旧分区表存储的数据。此时，可以使用 ``idf.py erase-flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。
分区表的更新并不会擦除根据旧分区表存储的数据。此时，可以使用 ``idf.py erase-flash`` 命令或者 ``esptool erase-flash`` 命令来擦除 flash 中的所有内容。
分区工具 (``parttool.py``)
@@ -406,13 +406,13 @@ Python API
.. note::
如果设备启用了 ``Flash Encryption`` 或 ``Secure Boot``，尝试使用修改 flash 内容的命令（如 ``erase_partition`` 或 ``write_partition``）会导致错误。这是因为 ``esptool.py`` 的擦除命令会在写入之前先被调用。这个“错误”实际上是一个用来防止设备变砖的安全措施。
如果设备启用了 ``Flash Encryption`` 或 ``Secure Boot``，尝试使用修改 flash 内容的命令（如 ``erase_partition`` 或 ``write_partition``）会导致错误。这是因为 ``esptool`` 的擦除命令会在写入之前先被调用。这个“错误”实际上是一个用来防止设备变砖的安全措施。
.. code-block:: none
A fatal error occurred: Active security features detected, erasing flash is disabled as a safety measure. Use --force to override, please use with caution, otherwise it may brick your device!
要解决此问题，需在运行 ``esptool.py`` 时使用 ``--force`` 参数。具体而言，``parttool.py`` 提供了 ``--esptool-erase-args`` 参数，用来将 ``--force`` 参数传递给 ``esptool.py``。
要解决此问题，需在运行 ``esptool`` 时使用 ``--force`` 参数。具体而言，``parttool.py`` 提供了 ``--esptool-erase-args`` 参数，用来将 ``--force`` 参数传递给 ``esptool``。
.. code-block:: bash

2
docs/zh_CN/api-guides/tools/idf-docker-image.rst
View File

@@ -130,7 +130,7 @@ Docker 也支持以交互方式进行构建，以调试构建问题或测试自
.. code-block:: bash
esp_rfc2217_server.py -v -p 4000 /dev/ttyUSB0
esp_rfc2217_server -v -p 4000 /dev/ttyUSB0
此时，便可使用以下命令，从 Docker 容器内部烧写连接到主机的设备：

8
docs/zh_CN/api-guides/tools/idf-py.rst
View File

@@ -7,7 +7,7 @@ IDF 前端工具 - ``idf.py``
- CMake_ 用于配置要构建的工程。
- Ninja_ 用于构建工程。
- `esptool.py`_ 用于烧录目标芯片。
- `esptool`_ 用于烧录目标芯片。
:ref:`第五步：开始使用 ESP-IDF 吧 <get-started-configure>` 简要介绍了设置 ``idf.py`` 以配置、构建及烧录工程的操作流程。
@@ -120,7 +120,7 @@ ESP-IDF 支持多个目标芯片，运行 ``idf.py --list-targets`` 查看当前
.. note:: 环境变量 ``ESPPORT`` 和 ``ESPBAUD`` 可分别设置 ``-p`` 和 ``-b`` 选项的默认值，在命令行上设置这些选项的参数可覆盖默认值。
``idf.py`` 在内部使用 ``esptool.py`` 的 ``write_flash`` 命令来烧录目标设备。通过 ``--extra-args`` 选项传递额外的参数，并配置烧录过程。例如，要 `写入到外部 SPI flash 芯片 <https://docs.espressif.com/projects/esptool/en/latest/esptool/advanced-options.html#custom-spi-pin-configuration>`_，请使用以下命令： ``idf.py flash --extra-args="--spi-connection <CLK>,<Q>,<D>,<HD>,<CS>"``。要查看所有可用参数，请运行 ``esptool.py write_flash --help`` 或查看 `esptool.py 文档 <https://docs.espressif.com/projects/esptool/en/latest/esptool/index.html>`_。
``idf.py`` 在内部使用 ``esptool`` 的 ``write-flash`` 命令来烧录目标设备。通过 ``--extra-args`` 选项传递额外的参数，并配置烧录过程。例如，要 `写入到外部 SPI flash 芯片 <https://docs.espressif.com/projects/esptool/en/latest/esptool/advanced-options.html#custom-spi-pin-configuration>`_，请使用以下命令： ``idf.py flash --extra-args="--spi-connection <CLK>,<Q>,<D>,<HD>,<CS>"``。要查看所有可用参数，请运行 ``esptool write-flash --help`` 或查看 `esptool 文档 <https://docs.espressif.com/projects/esptool/en/latest/esptool/index.html>`_。
与 ``build`` 命令类似，使用 ``app``、``bootloader`` 或 ``partition-table`` 参数运行此命令，可选择仅烧录应用程序、引导加载程序或分区表。
@@ -152,7 +152,7 @@ uf2 二进制文件也可以通过 :ref:`idf.py uf2 <generate-uf2-binary>` 生
- 仅针对 raw 格式：
- ``--flash-offset``：此选项创建的合并二进制文件应在指定偏移处进行烧录，而不是在标准偏移地址 0x0 处。
- ``--fill-flash-size``：设置此选项，系统将在最终的二进制文件中添加 FF 字节直至文件大小与 flash 大小等同，从而确保烧录范围能够完整地覆盖整个 flash 芯片，且在烧录时整个 flash 芯片都被重写。
- ``--pad-to-size``：设置此选项，系统将在最终的二进制文件中添加 FF 字节直至文件大小与 flash 大小等同，从而确保烧录范围能够完整地覆盖整个 flash 芯片，且在烧录时整个 flash 芯片都被重写。
- 仅针对 uf2 格式：
@@ -407,6 +407,6 @@ uf2 二进制文件也可以通过 :ref:`idf.py uf2 <generate-uf2-binary>` 生
.. _cmake: https://cmake.org
.. _ninja: https://ninja-build.org
.. _esptool.py: https://github.com/espressif/esptool/#readme
.. _esptool: https://github.com/espressif/esptool/#readme
.. _CCache: https://ccache.dev/
.. _click context: https://click.palletsprojects.com/en/stable/api/#context

2
docs/zh_CN/api-guides/usb-otg-console.rst
View File

@@ -6,7 +6,7 @@ USB OTG 控制台
在集成了 USB 外设的芯片上，可以使用 USB 通信设备类 (CDC) 来实现串行控制台，而不是使用带有外部 USB-UART 桥接芯片的 UART，{IDF_TARGET_NAME} ROM 中包含 USB CDC 实现，支持一些基本功能，而无需应用程序包含 USB 协议栈：
* 双向串行控制台，可与 :doc:`IDF 监视器 <tools/idf-monitor>` 或其他串行监视器一起使用。
* 使用 ``esptool.py`` 和 ``idf.py flash`` 进行烧录。
* 使用 ``esptool`` 和 ``idf.py flash`` 进行烧录。
* :doc:`设备固件更新 (DFU) <dfu>` 接口，可通过 ``dfu-util`` 和 ``dfu-util`` 烧录设备。
.. note::

2
docs/zh_CN/api-guides/usb-serial-jtag-console.rst
View File

@@ -9,7 +9,7 @@ ESP 芯片通常使用 UART 实现串口，并可以通过外部 USB-UART 桥接
拥有 USB 串行/JTAG 控制器时，{IDF_TARGET_NAME} 支持以下功能：
* 双向串行控制台，可与 :doc:`IDF 监视器 <tools/idf-monitor>` 或其他串行监视器一起使用。
* 使用 ``esptool.py`` 和 ``idf.py flash`` 烧录。
* 使用 ``esptool`` 和 ``idf.py flash`` 烧录。
* 使用 OpenOCD 等工具进行 JTAG 调试，同时进行串行操作。
.. note::

6
docs/zh_CN/api-reference/peripherals/sd_pullup_requirements.rst
View File

@@ -218,11 +218,11 @@ SD 上拉需求
烧录 eFuse 是不可逆的！上述问题清单可能已经过时，因此请确保要烧录的模组内嵌 3.3 V flash 芯片，可前往 https://www.espressif.com/ 进行确认。如果在带有 1.8 V flash 芯片的模组上烧录 3.3 V eFuse，模组将停止工作。
如果确定要烧录 eFuse，请转到 ESP-IDF 目录下，通过 ``espefuse.py`` 工具运行以下命令：
如果确定要烧录 eFuse，请转到 ESP-IDF 目录下，通过 ``espefuse`` 工具运行以下命令：
.. code-block:: bash
components/esptool_py/esptool/espefuse.py set_flash_voltage 3.3V
espefuse set-flash-voltage 3.3V
此命令将烧录 ``XPD_SDIO_TIEH``、``XPD_SDIO_FORCE`` 和 ``XPD_SDIO_REG`` eFuse。当以上三个 eFuse 被烧录为 1 时，内部 VDD_SDIO flash 电压调节器将被永久设置为 3.3 V。如果烧录成功，将看到以下日志：
@@ -244,7 +244,7 @@ SD 上拉需求
idf.py efuse-summary
如果运行自动烧录脚本，最好使用独立的 eFuse 工具 ``espefuse.py``。此工具还具有 ``--do-not-confirm`` 选项，可在无需确认的情况下烧录 eFuse。
如果运行自动烧录脚本，最好使用独立的 eFuse 工具 ``espefuse``。此工具还具有 ``--do-not-confirm`` 选项，可在无需确认的情况下烧录 eFuse。
有关烧录 eFuse 的更多信息，请参阅 **{IDF_TARGET_NAME} 技术参考手册** [`PDF <{IDF_TARGET_TRM_CN_URL}#efuse>`__]。

2
docs/zh_CN/api-reference/peripherals/spi_flash/index.rst
View File

@@ -118,7 +118,7 @@ SPI flash 容量
SPI flash 容量由引导加载程序镜像头部（烧录偏移量为 0x1000）的一个字段进行配置。
默认情况下，引导加载程序被写入 flash 时，``esptool.py`` 会自动检测 SPI flash 容量，同时使用正确容量更新引导加载程序的头部。也可以在工程配置中设置 :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`，生成固定的 flash 容量。
默认情况下，引导加载程序被写入 flash 时，``esptool`` 会自动检测 SPI flash 容量，同时使用正确容量更新引导加载程序的头部。也可以在工程配置中设置 :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`，生成固定的 flash 容量。
如需在运行时覆盖已配置的 flash 容量，请配置 ``g_rom_flashchip`` 结构中的 ``chip_size``。``esp_flash_*`` 函数使用此容量（于软件和 ROM 中）进行边界检查。

2
docs/zh_CN/api-reference/storage/fatfs.rst
View File

@@ -149,7 +149,7 @@ FatFs 分区生成器
fatfs_create_partition_image(my_fatfs_partition my_folder FLASH_IN_PROJECT)
没有指定 FLASH_IN_PROJECT 时也可以生成分区镜像，但是用户需要使用 ``esptool.py`` 或自定义的构建系统目标对其手动烧录。
没有指定 FLASH_IN_PROJECT 时也可以生成分区镜像，但是用户需要使用 ``esptool`` 或自定义的构建系统目标对其手动烧录。
相关示例请查看 :example:`storage/fatfs/fatfsgen`。

10
docs/zh_CN/api-reference/storage/spiffs.rst
View File

@@ -43,7 +43,7 @@ SPIFFS 是一个用于 SPI NOR flash 设备的嵌入式文件系统，支持磨
上述可选参数对应 SPIFFS 构建配置选项。若想顺利生成可用的镜像，请确保使用的参数或配置与构建 SPIFFS 时所用的参数或配置相同。运行帮助命令将显示参数所对应的 SPIFFS 构建配置。如未指定参数，将使用帮助信息中的默认值。
镜像生成后，用户可以使用 ``esptool.py`` 或 ``parttool.py`` 烧录镜像。
镜像生成后，用户可以使用 ``esptool`` 或 ``parttool.py`` 烧录镜像。
用户可以在命令行或脚本中手动单独调用 ``spiffsgen.py``，也可以直接从构建系统调用 ``spiffs_create_partition_image`` 来使用 ``spiffsgen.py``::
@@ -57,7 +57,7 @@ SPIFFS 是一个用于 SPI NOR flash 设备的嵌入式文件系统，支持磨
spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT)
不指定 FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT 也可以生成镜像，但须使用 ``esptool.py``、``parttool.py`` 或自定义构建系统目标手动烧录。
不指定 FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT 也可以生成镜像，但须使用 ``esptool``、``parttool.py`` 或自定义构建系统目标手动烧录。
有时基本目录中的内容是在构建时生成的，用户可以使用 DEPENDS/SPIFFS_IMAGE_DEPENDS 指定目标，因此可以在生成镜像之前执行此目标::
@@ -70,7 +70,7 @@ SPIFFS 是一个用于 SPI NOR flash 设备的嵌入式文件系统，支持磨
``mkspiffs``
^^^^^^^^^^^^
用户也可以使用 `mkspiffs <https://github.com/igrr/mkspiffs>`_ 工具创建 SPIFFS 分区镜像。与 ``spiffsgen.py`` 相似，`mkspiffs <https://github.com/igrr/mkspiffs>`_ 也可以用于从指定文件夹中生成镜像，然后使用 ``esptool.py`` 烧录镜像。
用户也可以使用 `mkspiffs <https://github.com/igrr/mkspiffs>`_ 工具创建 SPIFFS 分区镜像。与 ``spiffsgen.py`` 相似，`mkspiffs <https://github.com/igrr/mkspiffs>`_ 也可以用于从指定文件夹中生成镜像，然后使用 ``esptool`` 烧录镜像。
该工具需要获取以下参数：
@@ -85,11 +85,11 @@ SPIFFS 是一个用于 SPI NOR flash 设备的嵌入式文件系统，支持磨
运行以下命令，将镜像烧录到 {IDF_TARGET_NAME}（偏移量：0x110000）::
python esptool.py --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin
esptool --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write-flash -z 0x110000 spiffs.bin
.. note::
可以使用 ``esptool.py`` 的 ``write_flash`` 命令，通过 ``--spi-connection <CLK>,<Q>,<D>,<HD>,<CS>`` 选项 `将 spiffs 数据写入外部 SPI flash 芯片 <https://docs.espressif.com/projects/esptool/en/latest/esptool/advanced-options.html#custom-spi-pin-configuration>`_。只需指定分配给外部 flash 的 GPIO 管脚，如 ``python esptool.py write_flash --spi-connection 6,7,8,9,11 -z 0x110000 spiffs.bin``。
可以使用 ``esptool`` 的 ``write-flash`` 命令，通过 ``--spi-connection <CLK>,<Q>,<D>,<HD>,<CS>`` 选项 `将 spiffs 数据写入外部 SPI flash 芯片 <https://docs.espressif.com/projects/esptool/en/latest/esptool/advanced-options.html#custom-spi-pin-configuration>`_。只需指定分配给外部 flash 的 GPIO 管脚，如 ``esptool write-flash --spi-connection 6,7,8,9,11 -z 0x110000 spiffs.bin``。
选择合适的 SPIFFS 工具
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

67
docs/zh_CN/api-reference/system/app_image_format.rst
View File

@@ -24,30 +24,57 @@
.. code-block::
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/app.bin
esptool --chip {IDF_TARGET_PATH_NAME} image-info build/app.bin
.. code-block::
esptool.py v2.3.1
Image version: 1
Entry point: 40080ea4
13 segments
esptool v5.0.2
Image size: 137312 bytes
Segment 1: len 0x13ce0 load 0x3f400020 file_offs 0x00000018 SOC_DROM
Segment 2: len 0x00000 load 0x3ff80000 file_offs 0x00013d00 SOC_RTC_DRAM
Segment 3: len 0x00000 load 0x3ff80000 file_offs 0x00013d08 SOC_RTC_DRAM
Segment 4: len 0x028e0 load 0x3ffb0000 file_offs 0x00013d10 DRAM
Segment 5: len 0x00000 load 0x3ffb28e0 file_offs 0x000165f8 DRAM
Segment 6: len 0x00400 load 0x40080000 file_offs 0x00016600 SOC_IRAM
Segment 7: len 0x09600 load 0x40080400 file_offs 0x00016a08 SOC_IRAM
Segment 8: len 0x62e4c load 0x400d0018 file_offs 0x00020010 SOC_IROM
Segment 9: len 0x06cec load 0x40089a00 file_offs 0x00082e64 SOC_IROM
Segment 10: len 0x00000 load 0x400c0000 file_offs 0x00089b58 SOC_RTC_IRAM
Segment 11: len 0x00004 load 0x50000000 file_offs 0x00089b60 SOC_RTC_DATA
Segment 12: len 0x00000 load 0x50000004 file_offs 0x00089b6c SOC_RTC_DATA
Segment 13: len 0x00000 load 0x50000004 file_offs 0x00089b74 SOC_RTC_DATA
Checksum: e8 (valid)
Validation Hash: 407089ca0eae2bbf83b4120979d3354b1c938a49cb7a0c997f240474ef2ec76b (valid)
ESP32 Image Header
==================
Image version: 1
Entry point: 0x40081214
Segments: 6
Flash size: 2MB
Flash freq: 40m
Flash mode: DIO
ESP32 Extended Image Header
===========================
WP pin: 0xee (disabled)
Flash pins drive settings: clk_drv: 0x0, q_drv: 0x0, d_drv: 0x0, cs0_drv: 0x0, hd_drv: 0x0, wp_drv: 0x0
Chip ID: 0 (ESP32)
Minimal chip revision: v0.0, (legacy min_rev = 0)
Maximal chip revision: v3.99
Segments Information
====================
Segment Length Load addr File offs Memory types
------- ------- ---------- ---------- ------------
0 0x0711c 0x3f400020 0x00000018 DROM
1 0x0241c 0x3ffb0000 0x0000713c BYTE_ACCESSIBLE, DRAM
2 0x06ab0 0x40080000 0x00009560 IRAM
3 0x0b724 0x400d0020 0x00010018 IROM
4 0x060c0 0x40086ab0 0x0001b744 IRAM
5 0x00024 0x50000000 0x0002180c RTC_DATA
ESP32 Image Footer
==================
Checksum: 0x4b (valid)
Validation hash: 8808f05a62fe1a6e1e6830414b95229454b012eb2001511ca434d34e9e63c962 (valid)
Application Information
=======================
Project name: hello_world
App version: qa-test-esp32c61-master-2025070
Compile time: Aug 12 2025 16:36:40
ELF file SHA256: 10972f521b52276e988631d7408de388d639437118e8217c366f2bd93b52e1b6
ESP-IDF: v6.0-dev-1692-g7aad0d47e66-dirt
Minimal eFuse block revision: 0.0
Maximal eFuse block revision: 0.99
MMU page size: 64 KB
Secure version: 0
应用程序启动时，ESP-IDF 日志中也会包含段的相关信息：

38
docs/zh_CN/api-reference/system/bootloader_image_format.rst
View File

@@ -9,50 +9,50 @@
.. code-block::
esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/bootloader/bootloader.bin --version 2
esptool --chip {IDF_TARGET_PATH_NAME} image-info ./build/bootloader/bootloader.bin
输出结果如下形式所示：
.. code-block::
File size: 26576 (bytes)
esptool v5.0.2
Image size: 26352 bytes
ESP32 image header
ESP32 Image Header
==================
Image version: 1
Entry point: 0x40080658
Segments: 4
Entry point: 0x40080644
Segments: 3
Flash size: 2MB
Flash freq: 40m
Flash mode: DIO
ESP32 extended image header
ESP32 Extended Image Header
===========================
WP pin: 0xee
WP pin: 0xee (disabled)
Flash pins drive settings: clk_drv: 0x0, q_drv: 0x0, d_drv: 0x0, cs0_drv: 0x0, hd_drv: 0x0, wp_drv: 0x0
Chip ID: 0
Chip ID: 0 (ESP32)
Minimal chip revision: v0.0, (legacy min_rev = 0)
Maximal chip revision: v3.99
Segments information
Segments Information
====================
Segment Length Load addr File offs Memory types
------- ------- ---------- ---------- ------------
1 0x01bb0 0x3fff0030 0x00000018 BYTE_ACCESSIBLE, DRAM, DIRAM_DRAM
2 0x03c90 0x40078000 0x00001bd0 CACHE_APP
3 0x00004 0x40080400 0x00005868 IRAM
4 0x00f2c 0x40080404 0x00005874 IRAM
0 0x018e8 0x3fff0030 0x00000018 BYTE_ACCESSIBLE, DRAM, DIRAM_DRAM
1 0x03e58 0x40078000 0x00001908 CACHE_APP
2 0x00f5c 0x40080400 0x00005768 IRAM
ESP32 image footer
ESP32 Image Footer
==================
Checksum: 0x65 (valid)
Validation hash: 6f31a7f8512f26f6bce7c3b270f93bf6cf1ee4602c322998ca8ce27433527e92 (valid)
Checksum: 0x6b (valid)
Validation hash: 09fdc81d436a927b5018e19073a787cd37ffce655f505ad92675edd784419034 (valid)
Bootloader information
Bootloader Information
======================
Bootloader version: 1
ESP-IDF: v5.1-dev-4304-gcb51a3b-dirty
Compile time: Mar 30 2023 19:14:17
ESP-IDF: v6.0-dev-1620-g15d7e41a848-dirt
Compile time: Aug 8 2025 16:22:1
.. _image-format-bootloader-description:

2
docs/zh_CN/api-reference/system/chip_revision.rst
View File

@@ -179,7 +179,7 @@ EFuse 块版本号与芯片版本号类似，但是它主要影响在 eFuse 中
在 ESP-IDF v4.2 中添加了对 {IDF_TARGET_NAME} 芯片的支持。 由于 ``Minimum Supported ESP32-S2 Revision`` Kconfig 选项未引入，{IDF_TARGET_NAME} 芯片在 :cpp:type:`esp_image_header_t` 头文件中将 ``rev_min`` 设置为 0。这表明旧版引导加载程序不会检查芯片版本。在 v0.0 至 v3.15 范围内，任何应用程序都可以通过此类引导加载程序加载。
请使用 ``esptool chip_id`` 命令查看芯片版本。
请使用 ``esptool chip-id`` 命令查看芯片版本。
参考链接
----------

14
docs/zh_CN/api-reference/system/efuse.rst
View File

@@ -20,7 +20,7 @@ eFuse 管理器组件中集合了多种工具和 API，可帮助定义、烧录
eFuse Manager 与 ``idf.py``
---------------------------
``idf.py`` 通过 ``idf.py efuse-<subcommand>`` 命令为 eFuse 管理器提供了部分功能。本文档主要使用基于 ``idf.py`` 的命令，只有在涉及高级功能或罕见情况时，会使用基于 ``espefuse.py`` 的命令。要查看所有可用的命令，请运行 ``idf.py --help`` 并搜索以 ``efuse-`` 为前缀的命令。
``idf.py`` 通过 ``idf.py efuse-<subcommand>`` 命令为 eFuse 管理器提供了部分功能。本文档主要使用基于 ``idf.py`` 的命令，只有在涉及高级功能或罕见情况时，会使用基于 ``espefuse`` 的命令。要查看所有可用的命令，请运行 ``idf.py --help`` 并搜索以 ``efuse-`` 为前缀的命令。
硬件描述
--------------------
@@ -488,7 +488,7 @@ eFuse 位序采取小字节序（参见下方示例），这说明 eFuse 位按
要在项目的构建阶段获取 eFuse 状态，可以使用以下两个 CMake 函数：
* ``espefuse_get_json_summary()`` - 调用 ``espefuse.py summary --format json`` 命令并返回一个 JSON 字符串（该字符串不存储在文件中）。
* ``espefuse_get_json_summary()`` - 调用 ``espefuse summary --format json`` 命令并返回一个 JSON 字符串（该字符串不存储在文件中）。
* ``espefuse_get_efuse()`` - 在此 JSON 字符串中找到给定的 eFuse 名称并返回其属性。
该 JSON 字符串具有以下属性：
@@ -522,7 +522,7 @@ eFuse 位序采取小字节序（参见下方示例），这说明 eFuse 位按
espefuse_get_efuse(ret_data ${efuse_json} "MAC" "value")
message("MAC:" ${ret_data})
``value`` 属性的格式与 ``espefuse.py summary`` 或 ``idf.py efuse-summary`` 中显示的格式相同。
``value`` 属性的格式与 ``espefuse summary`` 或 ``idf.py efuse-summary`` 中显示的格式相同。
.. code-block:: none
@@ -557,12 +557,12 @@ flash 加密是一项硬件功能，需要物理烧录 eFuse ``key`` 和 ``FLASH
为此，可使用 :cpp:func:`bootloader_flash_write` 函数。但是，如果运行应用程序时芯片已启用 flash 加密，或者以 :ref:`CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH` 选项创建了引导加载程序，则 flash 加密/解密操作会正常进行。这意味着数据写入加密 flash 分区时被加密，从加密分区读取时被解密。
``espefuse.py``
^^^^^^^^^^^^^^^
``espefuse``
^^^^^^^^^^^^
esptool 中包含一个用于读取/写入 {IDF_TARGET_NAME} eFuse 位的有用工具： `espefuse.py <https://docs.espressif.com/projects/esptool/en/latest/{IDF_TARGET_PATH_NAME}/espefuse/index.html>`_。
esptool 中包含一个用于读取/写入 {IDF_TARGET_NAME} eFuse 位的有用工具： `espefuse <https://docs.espressif.com/projects/esptool/en/latest/{IDF_TARGET_PATH_NAME}/espefuse/index.html>`_。
``idf.py`` 命令也可以直接提供上述工具的部分功能。例如，运行 ``idf.py efuse-summary`` 命令，效果等同于 ``espefuse.py summary``。
``idf.py`` 命令也可以直接提供上述工具的部分功能。例如，运行 ``idf.py efuse-summary`` 命令，效果等同于 ``espefuse summary``。
.. include:: inc/espefuse_summary_{IDF_TARGET_NAME}.rst

43
docs/zh_CN/get-started/esp32_output_log.inc
View File

@@ -3,37 +3,28 @@
.. code-block:: none
...
esptool.py --chip esp32 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size 2MB 0x8000 partition_table/partition-table.bin 0x1000 bootloader/bootloader.bin 0x10000 hello_world.bin
esptool.py v3.0-dev
Serial port /dev/ttyUSB0
Connecting........_
Chip is ESP32D0WDQ6 (revision 0)
Features: WiFi, BT, Dual Core, Coding Scheme None
Crystal is 40MHz
esptool --chip esp32 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 40m --flash-size 2MB 0x8000 partition_table/partition-table.bin 0x1000 bootloader/bootloader.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32 on /dev/ttyUSB0:
Chip type: ESP32-U4WDH (revision v3.0)
Features: Wi-Fi, BT, Dual Core + LP Core, 240MHz, Embedded Flash, Vref calibration in eFuse, Coding Scheme None
Crystal frequency: 40MHz
MAC: 24:0a:c4:05:b9:14
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 5962.8 kbit/s)...
Flash will be erased from 0x00008000 to 0x00008fff...
Flash will be erased from 0x00001000 to 0x00007fff...
Flash will be erased from 0x00010000 to 0x00031fff...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (279.3 kbit/s).
Hash of data verified.
Compressed 26096 bytes to 15408...
Writing at 0x00001000... (100 %)
Wrote 26096 bytes (15408 compressed) at 0x00001000 in 0.4 seconds (effective 546.7 kbit/s)...
SHA digest in image updated.
Wrote 26352 bytes (16660 compressed) at 0x00001000 in 0.9 seconds (239.3 kbit/s).
Hash of data verified.
Compressed 147104 bytes to 77364...
Writing at 0x00010000... (20 %)
Writing at 0x00014000... (40 %)
Writing at 0x00018000... (60 %)
Writing at 0x0001c000... (80 %)
Writing at 0x00020000... (100 %)
Wrote 147104 bytes (77364 compressed) at 0x00010000 in 1.9 seconds (effective 615.5 kbit/s)...
Wrote 137312 bytes (78774 compressed) at 0x00010000 in 2.2 seconds (490.8 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
Done

43
docs/zh_CN/get-started/esp32c2_output_log.inc
View File

@@ -3,39 +3,28 @@
.. code-block:: none
...
esptool.py esp32c2 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 60m --flash_size 2MB 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool.py v3.3.1
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-C2 (revision 1)
Features: Wi-Fi
Crystal is 40MHz
MAC: 10:97:bd:f0:e5:0c
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32c2 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 60m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-C2 on /dev/ttyUSB0:
Chip type: ESP32-C2 (revision v2.0)
Features: Wi-Fi, BT 5 (LE), Single Core, 120MHz
Crystal frequency: 40MHz
MAC: 10:97:bd:f5:36:98
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Flash will be erased from 0x00000000 to 0x00004fff...
Flash will be erased from 0x00010000 to 0x0002ffff...
Flash will be erased from 0x00008000 to 0x00008fff...
Compressed 18192 bytes to 10989...
Writing at 0x00000000... (100 %)
Wrote 18192 bytes (10989 compressed) at 0x00000000 in 0.6 seconds (effective 248.5 kbit/s)...
Flash will be erased from 0x00010000 to 0x00028fff...
SHA digest in image updated.
Wrote 19680 bytes (12357 compressed) at 0x00000000 in 0.5 seconds (292.1 kbit/s).
Hash of data verified.
Compressed 128640 bytes to 65895...
Writing at 0x00010000... (20 %)
Writing at 0x00019539... (40 %)
Writing at 0x00020bf2... (60 %)
Writing at 0x00027de1... (80 %)
Writing at 0x0002f480... (100 %)
Wrote 128640 bytes (65895 compressed) at 0x00010000 in 1.7 seconds (effective 603.0 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (296.4 kbit/s).
Hash of data verified.
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (effective 360.1 kbit/s)...
Wrote 98416 bytes (52689 compressed) at 0x00010000 in 1.8 seconds (438.9 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...

45
docs/zh_CN/get-started/esp32c3_output_log.inc
View File

@@ -3,37 +3,28 @@
.. code-block:: none
...
esptool.py --chip esp32c3 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 80m --flash_size 2MB 0x8000 partition_table/partition-table.bin 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin
esptool.py v3.0
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-C3
Features: Wi-Fi
Crystal is 40MHz
MAC: 7c:df:a1:40:02:a4
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32c3 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-C3 on /dev/ttyUSB0:
Chip type: ESP32-C3 (QFN32) (revision v1.0)
Features: Wi-Fi, BT 5 (LE), Single Core, 160MHz, Embedded Flash 4MB (XMC)
Crystal frequency: 40MHz
MAC: 60:55:f9:f7:7d:20
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 4238.1 kbit/s)...
Flash will be erased from 0x00000000 to 0x00005fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Flash will be erased from 0x00010000 to 0x00031fff...
SHA digest in image updated.
Wrote 21072 bytes (13320 compressed) at 0x00000000 in 0.7 seconds (232.1 kbit/s).
Hash of data verified.
Compressed 18960 bytes to 11311...
Writing at 0x00000000... (100 %)
Wrote 18960 bytes (11311 compressed) at 0x00000000 in 0.3 seconds (effective 584.9 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (240.8 kbit/s).
Hash of data verified.
Compressed 145520 bytes to 71984...
Writing at 0x00010000... (20 %)
Writing at 0x00014000... (40 %)
Writing at 0x00018000... (60 %)
Writing at 0x0001c000... (80 %)
Writing at 0x00020000... (100 %)
Wrote 145520 bytes (71984 compressed) at 0x00010000 in 2.3 seconds (effective 504.4 kbit/s)...
Wrote 135328 bytes (74697 compressed) at 0x00010000 in 2.6 seconds (419.7 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
Done

39
docs/zh_CN/get-started/esp32c5_output_log.inc
View File

@@ -3,39 +3,30 @@
.. code-block:: none
...
esptool.py --chip esp32c5 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset --no-stub write_flash --flash_mode dio --flash_freq 80m --flash_size 2MB 0x2000 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool.py v4.9.dev6
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-C5 (revision v1.0)
Features: WiFi 6, BT 5, IEEE802.15.4
Crystal is 48MHz
esptool --chip esp32c5 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset --no-stub write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x2000 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool v5.0.2
Connected to ESP32-C5 on /dev/ttyUSB0:
Chip type: ESP32-C5 (revision v1.0)
Features: Wi-Fi 6 (dual-band), BT 5 (LE), IEEE802.15.4, Single Core + LP Core, 240MHz
Crystal frequency: 48MHz
MAC: 30:ed:a0:ff:fe:e0:af:38
BASE MAC: 30:ed:a0:e0:af:38
MAC_EXT: ff:fe
ROM expects crystal freq: 48 MHz, detected 48 MHz
Changing baud rate to 460800
Stub flasher running.
Changing baud rate to 460800...
Changed.
Enabling default SPI flash mode...
Configuring flash size...
Flash will be erased from 0x00002000 to 0x00007fff...
Flash will be erased from 0x00010000 to 0x00034fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Erasing flash...
Took 0.09s to erase flash block
Writing at 0x00007400... (100 %)
Wrote 22528 bytes at 0x00002000 in 0.7 seconds (276.3 kbit/s)...
Flash will be erased from 0x00010000 to 0x00032fff...
SHA digest in image updated.
Wrote 21888 bytes (13489 compressed) at 0x00002000 in 0.5 seconds (348.1 kbit/s).
Hash of data verified.
Erasing flash...
Took 0.37s to erase flash block
Writing at 0x00034c00... (100 %)
Wrote 151552 bytes at 0x00010000 in 4.4 seconds (275.6 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (316.0 kbit/s).
Hash of data verified.
Erasing flash...
Took 0.02s to erase flash block
Writing at 0x00008800... (100 %)
Wrote 3072 bytes at 0x00008000 in 0.1 seconds (281.8 kbit/s)...
Wrote 141248 bytes (75783 compressed) at 0x00010000 in 2.1 seconds (536.0 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...

55
docs/zh_CN/get-started/esp32c6_output_log.inc
View File

@@ -3,47 +3,30 @@
.. code-block:: none
...
esptool esp32c6 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset --no-stub write_flash --flash_mode dio --flash_freq 80m --flash_size 2MB 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool.py v4.3
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-C6 (revision v0.0)
Features: WiFi 6, BT 5
Crystal is 40MHz
MAC: 60:55:f9:f6:01:38
Changing baud rate to 460800
esptool --chip esp32c6 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-C6 on /dev/ttyUSB0:
Chip type: ESP32-C6 (QFN40) (revision v0.0)
Features: Wi-Fi 6, BT 5 (LE), IEEE802.15.4, Single Core + LP Core, 160MHz
Crystal frequency: 40MHz
MAC: 40:4c:ca:ff:fe:50:bf:18
BASE MAC: 40:4c:ca:50:bf:18
MAC_EXT: ff:fe
Stub flasher running.
Changing baud rate to 460800...
Changed.
Enabling default SPI flash mode...
Configuring flash size...
Flash will be erased from 0x00000000 to 0x00004fff...
Flash will be erased from 0x00010000 to 0x00028fff...
Flash will be erased from 0x00000000 to 0x00005fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Erasing flash...
Took 0.17s to erase flash block
Writing at 0x00000000... (5 %)
Writing at 0x00000c00... (23 %)
Writing at 0x00001c00... (47 %)
Writing at 0x00003000... (76 %)
Writing at 0x00004000... (100 %)
Wrote 17408 bytes at 0x00000000 in 0.5 seconds (254.6 kbit/s)...
Flash will be erased from 0x00010000 to 0x0002efff...
SHA digest in image updated.
Wrote 22512 bytes (13994 compressed) at 0x00000000 in 0.3 seconds (662.3 kbit/s).
Hash of data verified.
Erasing flash...
Took 0.85s to erase flash block
Writing at 0x00010000... (1 %)
Writing at 0x00014c00... (20 %)
Writing at 0x00019c00... (40 %)
Writing at 0x0001ec00... (60 %)
Writing at 0x00023c00... (80 %)
Writing at 0x00028c00... (100 %)
Wrote 102400 bytes at 0x00010000 in 3.2 seconds (253.5 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (630.2 kbit/s).
Hash of data verified.
Erasing flash...
Took 0.04s to erase flash block
Writing at 0x00008000... (33 %)
Writing at 0x00008400... (66 %)
Writing at 0x00008800... (100 %)
Wrote 3072 bytes at 0x00008000 in 0.1 seconds (269.0 kbit/s)...
Wrote 122976 bytes (63916 compressed) at 0x00010000 in 0.9 seconds (1087.1 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...

45
docs/zh_CN/get-started/esp32h2_output_log.inc
View File

@@ -3,39 +3,30 @@
.. code-block:: none
...
esptool esp32h2 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 48m --flash_size 2MB 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool.py v4.6
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-H2 (revision v0.1)
Features: BLE
Crystal is 32MHz
MAC: 60:55:f9:f7:3e:93:ff:fe
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32h2 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 48m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-H2 on /dev/ttyUSB0:
Chip type: ESP32-H2 (revision v0.2)
Features: BT 5 (LE), IEEE802.15.4, Single Core, 96MHz
Crystal frequency: 32MHz
MAC: 60:55:f9:ff:fe:f7:3a:56
BASE MAC: 60:55:f9:f7:3a:56
MAC_EXT: ff:fe
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Flash will be erased from 0x00000000 to 0x00005fff...
Flash will be erased from 0x00010000 to 0x00034fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Compressed 20880 bytes to 12788...
Writing at 0x00000000... (100 %)
Wrote 20880 bytes (12788 compressed) at 0x00000000 in 0.6 seconds (effective 297.5 kbit/s)...
Flash will be erased from 0x00010000 to 0x00032fff...
SHA digest in image updated.
Wrote 22192 bytes (13780 compressed) at 0x00000000 in 0.7 seconds (252.5 kbit/s).
Hash of data verified.
Compressed 149424 bytes to 79574...
Writing at 0x00010000... (20 %)
Writing at 0x00019959... (40 %)
Writing at 0x00020bb5... (60 %)
Writing at 0x00026d8f... (80 %)
Writing at 0x0002e60a... (100 %)
Wrote 149424 bytes (79574 compressed) at 0x00010000 in 2.1 seconds (effective 571.7 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (248.5 kbit/s).
Hash of data verified.
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 539.7 kbit/s)...
Wrote 141920 bytes (76653 compressed) at 0x00010000 in 2.5 seconds (458.5 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...

40
docs/zh_CN/get-started/esp32p4_output_log.inc
View File

@@ -4,36 +4,28 @@
.. code-block:: none
...
esptool.py v4.8.dev3
Serial port /dev/cu.SLAB_USBtoUART
Connecting....
Chip is ESP32-P4 (revision v0.0)
Features: High-Performance MCU
Crystal is 40MHz
MAC: 00:00:00:00:00:00
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32p4 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x2000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-P4 on /dev/ttyUSB0:
Chip type: ESP32-P4 (revision v1.0)
Features: Dual Core + LP Core, 400MHz
Crystal frequency: 40MHz
MAC: 60:55:f9:fc:00:a2
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Flash will be erased from 0x00002000 to 0x00007fff...
Flash will be erased from 0x00010000 to 0x0003bfff...
Flash will be erased from 0x00008000 to 0x00008fff...
SHA digest in image updated
Compressed 20960 bytes to 12653...
Writing at 0x00002000... (100 %)
Wrote 20960 bytes (12653 compressed) at 0x00002000 in 0.6 seconds (effective 277.1 kbit/s)...
Flash will be erased from 0x00010000 to 0x00038fff...
SHA digest in image updated.
Wrote 22896 bytes (13985 compressed) at 0x00002000 in 0.4 seconds (477.0 kbit/s).
Hash of data verified.
Compressed 179584 bytes to 94528...
Writing at 0x00035efb... (100 %)
Wrote 179584 bytes (94528 compressed) at 0x00010000 in 2.6 seconds (effective 549.9 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (416.6 kbit/s).
Hash of data verified.
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (effective 420.7 kbit/s)...
Wrote 164496 bytes (87363 compressed) at 0x00010000 in 1.4 seconds (931.3 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
Done

45
docs/zh_CN/get-started/esp32s2_output_log.inc
View File

@@ -3,37 +3,28 @@
.. code-block:: none
...
esptool.py --chip esp32s2 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size 2MB 0x8000 partition_table/partition-table.bin 0x1000 bootloader/bootloader.bin 0x10000 hello_world.bin
esptool.py v3.0-dev
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-S2
Features: WiFi
Crystal is 40MHz
MAC: 18:fe:34:72:50:e3
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32s2 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-S2 on /dev/ttyUSB0:
Chip type: ESP32-S2FH4 (revision v0.0)
Features: Wi-Fi, Single Core, 240MHz, Embedded Flash 4MB, No Embedded PSRAM, ADC and temperature sensor calibration in BLK2 of eFuse V1
Crystal frequency: 40MHz
MAC: 84:f7:03:e3:3f:bc
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 3851.6 kbit/s)...
Flash will be erased from 0x00001000 to 0x00006fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Flash will be erased from 0x00010000 to 0x00030fff...
SHA digest in image updated.
Wrote 21968 bytes (13914 compressed) at 0x00001000 in 0.7 seconds (251.0 kbit/s).
Hash of data verified.
Compressed 22592 bytes to 13483...
Writing at 0x00001000... (100 %)
Wrote 22592 bytes (13483 compressed) at 0x00001000 in 0.3 seconds (effective 595.1 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (238.5 kbit/s).
Hash of data verified.
Compressed 140048 bytes to 70298...
Writing at 0x00010000... (20 %)
Writing at 0x00014000... (40 %)
Writing at 0x00018000... (60 %)
Writing at 0x0001c000... (80 %)
Writing at 0x00020000... (100 %)
Wrote 140048 bytes (70298 compressed) at 0x00010000 in 1.7 seconds (effective 662.5 kbit/s)...
Wrote 132096 bytes (76394 compressed) at 0x00010000 in 2.2 seconds (486.9 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
Done

47
docs/zh_CN/get-started/esp32s3_output_log.inc
View File

@@ -3,41 +3,28 @@
.. code-block:: none
...
esptool.py esp32s3 -p /dev/ttyUSB0 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 80m --flash_size 2MB 0x0 bootloader/bootloader.bin 0x10000 hello_world.bin 0x8000 partition_table/partition-table.bin
esptool.py v3.2-dev
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32-S3
Features: WiFi, BLE
Crystal is 40MHz
MAC: 7c:df:a1:e0:00:64
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
esptool --chip esp32s3 -p /dev/ttyUSB0 -b 460800 --before=default-reset --after=hard-reset write-flash --flash-mode dio --flash-freq 80m --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin
esptool v5.0.2
Connected to ESP32-S3 on /dev/ttyUSB0:
Chip type: ESP32-S3 (QFN56) (revision v0.1)
Features: Wi-Fi, BT 5 (LE), Dual Core + LP Core, 240MHz, Embedded Flash 8MB (GD)
Crystal frequency: 40MHz
MAC: f4:12:fa:87:c6:dc
Stub flasher running.
Changing baud rate to 460800...
Changed.
Configuring flash size...
Flash will be erased from 0x00000000 to 0x00004fff...
Flash will be erased from 0x00010000 to 0x00039fff...
Flash will be erased from 0x00000000 to 0x00005fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Compressed 18896 bytes to 11758...
Writing at 0x00000000... (100 %)
Wrote 18896 bytes (11758 compressed) at 0x00000000 in 0.5 seconds (effective 279.9 kbit/s)...
Flash will be erased from 0x00010000 to 0x00037fff...
SHA digest in image updated.
Wrote 21280 bytes (13578 compressed) at 0x00000000 in 0.6 seconds (298.1 kbit/s).
Hash of data verified.
Compressed 168208 bytes to 88178...
Writing at 0x00010000... (16 %)
Writing at 0x0001a80f... (33 %)
Writing at 0x000201f1... (50 %)
Writing at 0x00025dcf... (66 %)
Writing at 0x0002d0be... (83 %)
Writing at 0x00036c07... (100 %)
Wrote 168208 bytes (88178 compressed) at 0x00010000 in 2.4 seconds (effective 569.2 kbit/s)...
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (315.1 kbit/s).
Hash of data verified.
Compressed 3072 bytes to 103...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (effective 478.9 kbit/s)...
Wrote 161744 bytes (90141 compressed) at 0x00010000 in 2.5 seconds (513.7 kbit/s).
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
Done

6
docs/zh_CN/get-started/flashing-troubleshooting.rst
View File

@@ -8,11 +8,11 @@
{IDF_TARGET_STRAP_GPIO:default="[NEEDS TO BE UPDATED]", esp32="GPIO0", esp32s2="GPIO0", esp32s3="GPIO0", esp32c2="GPIO9", esp32c3="GPIO9", esp32c6="GPIO9", esp32h2="GPIO9", esp32p4="GPIO35", esp32c5="GPIO28"}
如果在运行给定命令时出现如“连接失败”这样的错误，造成该错误的原因之一可能是运行 ``esptool.py`` 时出现错误。 ``esptool.py`` 是构建系统调用的程序，用于重置芯片、与 ROM 引导加载器交互以及烧录固件的工具。可以按照以下步骤进行手动复位，轻松解决该问题。如果问题仍未解决，请参考 `esptool 故障排除 <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ 获取更多信息。
如果在运行给定命令时出现如“连接失败”这样的错误，造成该错误的原因之一可能是运行 ``esptool`` 时出现错误。 ``esptool`` 是构建系统调用的程序，用于重置芯片、与 ROM 引导加载器交互以及烧录固件的工具。可以按照以下步骤进行手动复位，轻松解决该问题。如果问题仍未解决，请参考 `esptool 故障排除 <https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html>`_ 获取更多信息。
``esptool.py`` 通过使 USB 至 UART 桥（如 FTDI 或 CP210x）的 DTR 和 RTS 控制线生效来自动复位 {IDF_TARGET_NAME}（请参考 :doc:`establish-serial-connection` 获取更多详细信息）。DTR 和 RTS 控制线又连接到 {IDF_TARGET_NAME} 的 ``{IDF_TARGET_STRAP_GPIO}`` 和 ``CHIP_PU`` (EN) 管脚上，因此 DTR 和 RTS 的电压电平变化会使 {IDF_TARGET_NAME} 进入固件下载模式。相关示例可查看 ESP32 DevKitC 开发板的 `原理图 <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_。
``esptool`` 通过使 USB 至 UART 桥（如 FTDI 或 CP210x）的 DTR 和 RTS 控制线生效来自动复位 {IDF_TARGET_NAME}（请参考 :doc:`establish-serial-connection` 获取更多详细信息）。DTR 和 RTS 控制线又连接到 {IDF_TARGET_NAME} 的 ``{IDF_TARGET_STRAP_GPIO}`` 和 ``CHIP_PU`` (EN) 管脚上，因此 DTR 和 RTS 的电压电平变化会使 {IDF_TARGET_NAME} 进入固件下载模式。相关示例可查看 ESP32 DevKitC 开发板的 `原理图 <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_。
一般来说，使用官方的 ESP-IDF 开发板不会出现问题。但是， ``esptool.py`` 在以下情况下不能自动重置硬件：
一般来说，使用官方的 ESP-IDF 开发板不会出现问题。但是， ``esptool`` 在以下情况下不能自动重置硬件：
- 硬件未连接到 ``{IDF_TARGET_STRAP_GPIO}`` 和 ``CIHP_PU`` 的 DTR 和 RTS 控制线。
- DTR 和 RTS 控制线的配置方式不同。

11
docs/zh_CN/get-started/start-project.rst
View File

@@ -27,11 +27,14 @@
... (more lines of build system output)
[527/527] Generating hello_world.bin
esptool.py v2.3.1
esptool v5.0.2
Project build complete. To flash, run this command:
../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello_world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
or run 'idf.py -p PORT flash'
Project build complete. To flash, run:
idf.py flash
or
idf.py -p PORT flash
or
esptool -p (PORT) -b 921600 write-flash --flash-mode dio --flash-size detect --flash-freq 40m 0x10000 build/hello_world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
如果一切正常，编译完成后将生成 .bin 文件。

26
docs/zh_CN/security/flash-encryption.rst
View File

@@ -13,7 +13,7 @@ flash 加密
.. note::
在本指南中，最常用的命令形式为 ``idf.py secure-<command>``，这是对应 ``espsecure.py <command>`` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure.py`` 的命令相比，可能会损失一部分高级功能。
在本指南中，最常用的命令形式为 ``idf.py secure-<command>``，这是对应 ``espsecure <command>`` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure`` 的命令相比，可能会损失一部分高级功能。
概述
------
@@ -55,7 +55,7 @@ flash 加密功能用于加密与 {IDF_TARGET_NAME} 搭载使用的片外 flash
相关 eFuses
------------------------------
flash 加密操作由 {IDF_TARGET_NAME} 上的多个 eFuse 控制，具体 eFuse 名称及其描述请参见下表。``espefuse.py`` 工具和基于 ``idf.py`` 的 eFuse 指令也会使用下表中的 eFuse 名。为了能在 eFuse API 中使用，请在名称前加上 ``ESP_EFUSE_``，如：esp_efuse_read_field_bit (ESP_EFUSE_DISABLE_DL_ENCRYPT)。
flash 加密操作由 {IDF_TARGET_NAME} 上的多个 eFuse 控制，具体 eFuse 名称及其描述请参见下表。``espefuse`` 工具和基于 ``idf.py`` 的 eFuse 指令也会使用下表中的 eFuse 名。为了能在 eFuse API 中使用，请在名称前加上 ``ESP_EFUSE_``，如：esp_efuse_read_field_bit (ESP_EFUSE_DISABLE_DL_ENCRYPT)。
.. Comment: As text in cells of list-table header rows does not wrap, it is necessary to make 0 header rows and apply bold typeface to the first row. Otherwise, the table goes beyond the html page limits on the right.
@@ -164,7 +164,7 @@ flash 加密操作由 {IDF_TARGET_NAME} 上的多个 eFuse 控制，具体 eFuse
* 上表中列出的所有 eFuse 位都提供读/写访问控制。
* 这些位的默认值是 0。
对上述 eFuse 位的读写访问由 ``WR_DIS`` 和 ``RD_DIS`` 寄存器中的相应字段控制。有关 {IDF_TARGET_NAME} eFuse 的详细信息，请参考 :doc:`eFuse 管理器 <../api-reference/system/efuse>`。要使用 ``idf.py`` 更改 eFuse 字段的保护位，请使用以下两个命令：efuse-read-protect 和 efuse-write-protect（``idf.py`` 基于 ``espefuse.py`` 命令 write_protect_efuse 和 read_protect_efuse 的别名）。例如 ``idf.py efuse-write-protect DISABLE_DL_ENCRYPT``。
对上述 eFuse 位的读写访问由 ``WR_DIS`` 和 ``RD_DIS`` 寄存器中的相应字段控制。有关 {IDF_TARGET_NAME} eFuse 的详细信息，请参考 :doc:`eFuse 管理器 <../api-reference/system/efuse>`。要使用 ``idf.py`` 更改 eFuse 字段的保护位，请使用以下两个命令：efuse-read-protect 和 efuse-write-protect（``idf.py`` 基于 ``espefuse`` 命令 write-protect-efuse 和 read-protect-efuse 的别名）。例如 ``idf.py efuse-write-protect DISABLE_DL_ENCRYPT``。
.. only:: esp32c2
@@ -462,8 +462,8 @@ flash 加密设置
.. code-block:: bash
espefuse.py --port PORT --chip esp32c2 burn_key_digest secure_boot_signing_key.pem \
burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
espefuse --port PORT --chip esp32c2 burn-key-digest secure_boot_signing_key.pem \
burn-key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
如果未烧录密钥并在启用 flash 加密后启动设备，{IDF_TARGET_NAME} 将生成一个软件无法访问或修改的随机密钥。
@@ -571,7 +571,7 @@ flash 加密设置
- 不要在多个设备之间重复使用同一个 flash 加密密钥，这样攻击者就无法从一台设备上复制加密数据后再将其转移到第二台设备上。
:esp32: - 在使用 ESP32 V3 时，如果生产设备不需要 UART ROM 下载模式，那么则该禁用该模式以增加设备安全性。这可以通过在应用程序启动时调用 :cpp:func:`esp_efuse_disable_rom_download_mode` 来实现。或者，可将项目 :ref:`CONFIG_ESP32_REV_MIN` 级别配置为 3（仅针对 ESP32 V3），然后选择 :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` 为“永久性的禁用 ROM 下载模式（推荐）”。在早期的 ESP32 版本上无法禁用 ROM 下载模式。
:not esp32: - 如果不需要 UART ROM 下载模式，则应完全禁用该模式，或者永久设置为“安全下载模式”。安全下载模式永久性地将可用的命令限制在更新 SPI 配置、更改波特率、基本的 flash 写入和使用 `get_security_info` 命令返回当前启用的安全功能摘要。默认在量产模式下第一次启动时设置为安全下载模式。要完全禁用下载模式，请选择 :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` 为“永久禁用 ROM 下载模式（推荐）”或在运行时调用 :cpp:func:`esp_efuse_disable_rom_download_mode`。
:not esp32: - 如果不需要 UART ROM 下载模式，则应完全禁用该模式，或者永久设置为“安全下载模式”。安全下载模式永久性地将可用的命令限制在更新 SPI 配置、更改波特率、基本的 flash 写入和使用 `get-security-info` 命令返回当前启用的安全功能摘要。默认在量产模式下第一次启动时设置为安全下载模式。要完全禁用下载模式，请选择 :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` 为“永久禁用 ROM 下载模式（推荐）”或在运行时调用 :cpp:func:`esp_efuse_disable_rom_download_mode`。
- 启用 :doc:`安全启动<secure-boot-v2>` 作为额外的保护层，防止攻击者在启动前有选择地破坏 flash 中某部分。
外部启用 flash 加密
@@ -961,7 +961,7 @@ flash 加密的高级功能
一个位可以控制三个 eFuse 的写保护，这意味着写保护一个 eFuse 位将写保护所有未设置的 eFuse 位。
由于 ``esptool.py`` 目前不支持读取加密 flash，所以对这些 eFuse 进行写保护从而使其保持未设置目前来说并不是很有用。
由于 ``esptool`` 目前不支持读取加密 flash，所以对这些 eFuse 进行写保护从而使其保持未设置目前来说并不是很有用。
.. only:: esp32
@@ -1018,7 +1018,7 @@ JTAG 调试
idf.py secure-encrypt-flash-data --aes-xts --keyfile /path/to/key.bin --address 0x10000 --output my-app-ciphertext.bin my-app.bin
然后可以使用 ``esptool.py`` 将文件 ``my-app-ciphertext.bin`` 写入偏移量 0x10000。 关于为 ``esptool.py`` 推荐的所有命令行选项，请查看 idf.py build 成功时打印的输出。
然后可以使用 ``esptool`` 将文件 ``my-app-ciphertext.bin`` 写入偏移量 0x10000。 关于为 ``esptool`` 推荐的所有命令行选项，请查看 idf.py build 成功时打印的输出。
.. note::
@@ -1075,9 +1075,9 @@ JTAG 调试
- 块偏移的 19 个高位（第 5-23 位）由 flash 加密的主密钥进行 XOR 运算。选定该范围的原因为：flash 的大小最大为 16 MB（24 位），每个块大小为 32 字节，因而 5 个最低有效位始终为 0。
- 从 19 个块偏移位中每个位到 flash 加密密钥的 256 位都有一个特殊的映射，以决定与哪个位进行 XOR 运算。有关完整映射可参见 ``espsecure.py`` 源代码中的变量 ``_FLASH_ENCRYPTION_TWEAK_PATTERN``。
- 从 19 个块偏移位中每个位到 flash 加密密钥的 256 位都有一个特殊的映射，以决定与哪个位进行 XOR 运算。有关完整映射可参见 ``espsecure`` 源代码中的变量 ``_FLASH_ENCRYPTION_TWEAK_PATTERN``。
- 有关在 Python 中实现的完整 flash 加密算法，可参见 ``espsecure.py`` 源代码中的函数 ``_flash_encryption_operation()``。
- 有关在 Python 中实现的完整 flash 加密算法，可参见 ``espsecure`` 源代码中的函数 ``_flash_encryption_operation()``。
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
@@ -1092,7 +1092,7 @@ JTAG 调试
- flash 加密的密钥存储于一个或两个 ``BLOCK_KEYN`` eFuse 中，默认受保护防止进一步写入或软件读取。
- 有关在 Python 中实现的完整 flash 加密算法，可参见 ``espsecure.py`` 源代码中的函数 ``_flash_encryption_operation()``。
- 有关在 Python 中实现的完整 flash 加密算法，可参见 ``espsecure`` 源代码中的函数 ``_flash_encryption_operation()``。
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
@@ -1108,7 +1108,7 @@ JTAG 调试
- flash 加密的密钥存储于一个 ``BLOCK_KEYN`` eFuse 中，默认受保护防止进一步写入或软件读取。
- 有关在 Python 中实现的完整 flash 加密算法，可参见 ``espsecure.py`` 源代码中的函数 ``_flash_encryption_operation()``。
- 有关在 Python 中实现的完整 flash 加密算法，可参见 ``espsecure`` 源代码中的函数 ``_flash_encryption_operation()``。
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
@@ -1123,7 +1123,7 @@ JTAG 调试
- flash 加密的密钥存储于一个 ``BLOCK_KEY0`` eFuse 中，默认受保护防止进一步写入或软件读取。
- 有关在 Python 中实现的完整 flash 加密算法，可参见 ``espsecure.py`` 源代码中的函数 ``_flash_encryption_operation()``。
- 有关在 Python 中实现的完整 flash 加密算法，可参见 ``espsecure`` 源代码中的函数 ``_flash_encryption_operation()``。
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND

16
docs/zh_CN/security/secure-boot-v1.rst
View File

@@ -19,7 +19,7 @@
.. note::
在本指南中，最常用的命令形式为 ``idf.py secure-<command>``，这是对应 ``espsecure.py <command>`` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure.py`` 的命令相比，可能会损失一部分高级功能。
在本指南中，最常用的命令形式为 ``idf.py secure-<command>``，这是对应 ``espsecure <command>`` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure`` 的命令相比，可能会损失一部分高级功能。
背景信息
----------
@@ -105,7 +105,7 @@
在生产环境下，建议使用 OpenSSL 或其他行业标准的加密程序生成密钥对，详情请参阅 :ref:`secure-boot-generate-key`。
5. 运行 ``idf.py bootloader`` 构建启用了安全启动的引导加载程序，构建输出中包含一个使用 ``esptool.py write_flash`` 烧录命令的提示。
5. 运行 ``idf.py bootloader`` 构建启用了安全启动的引导加载程序，构建输出中包含一个使用 ``esptool write-flash`` 烧录命令的提示。
.. _secure-boot-resume-normal-flashing:
@@ -149,7 +149,7 @@
1. 在 :ref:`project-configuration-menu` 中，选择 ``Bootloader Config`` > :ref:`CONFIG_SECURE_BOOT` > ``CONFIG_SECURE_BOOT_V1_ENABLED`` > :ref:`CONFIG_SECURE_BOOTLOADER_MODE` > ``Reflashable``。
2. 如有需要，按照设备使用的编码方案设置 :ref:`CONFIG_SECURE_BOOTLOADER_KEY_ENCODING`。编码方案将在 ``esptool.py`` 连接到芯片时显示在 ``Features`` 行中，或在 ``idf.py efuse-summary`` 输出中显示。
2. 如有需要，按照设备使用的编码方案设置 :ref:`CONFIG_SECURE_BOOTLOADER_KEY_ENCODING`。编码方案将在 ``esptool`` 连接到芯片时显示在 ``Features`` 行中，或在 ``idf.py efuse-summary`` 输出中显示。
3. 请按 :ref:`secure-boot-generate-key` 中的步骤生成签名密钥。生成的密钥文件路径必须在 ``Secure Boot Configuration`` 菜单中指定。
@@ -181,7 +181,7 @@
远程镜像签名
------------------------
生产构建中，建议使用远程签名服务器，而非将签名密钥存储在构建机器上，这也是默认的 ESP-IDF 安全启动配置。可以使用命令行工具 ``espsecure.py`` 在远程系统上为应用程序镜像和分区表数据签名，供安全启动使用。
生产构建中，建议使用远程签名服务器，而非将签名密钥存储在构建机器上，这也是默认的 ESP-IDF 安全启动配置。可以使用命令行工具 ``espsecure`` 在远程系统上为应用程序镜像和分区表数据签名，供安全启动使用。
使用远程签名时，请禁用选项 ``Sign binaries during build``。此时，签名私钥无需存在于构建系统，但签名公钥必须存在，它会编译到引导加载程序中，并在 OTA 更新期间验证镜像签名。
@@ -189,7 +189,7 @@
.. code-block::
espsecure.py extract_public_key --keyfile PRIVATE_SIGNING_KEY PUBLIC_VERIFICATION_KEY
espsecure extract-public-key --keyfile PRIVATE_SIGNING_KEY PUBLIC_VERIFICATION_KEY
请在 ``Secure boot public signature verification key`` 下的 menuconfig 中指定公共签名验证密钥的路径，构建安全引导加载程序。
@@ -211,7 +211,7 @@
* 在具备高质量熵源的系统上生成签名密钥。
* 时刻对签名密钥保密，泄漏此密钥将危及安全启动系统。
* 不允许第三方使用 ``espsecure.py`` 命令或 ``idf.py secure-`` 子命令来观察密钥生成或是签名过程的任何细节，这两个过程都容易受到定时攻击或其他侧信道攻击的威胁。
* 不允许第三方使用 ``espsecure`` 命令或 ``idf.py secure-`` 子命令来观察密钥生成或是签名过程的任何细节，这两个过程都容易受到定时攻击或其他侧信道攻击的威胁。
* 在安全启动配置中启用所有安全启动选项，包括 flash 加密、禁用 JTAG、禁用 BASIC ROM 解释器和禁用 UART 引导加载程序的加密 flash 访问。
* 结合 :doc:`flash-encryption` 使用安全启动，防止本地读取 flash 内容。
@@ -245,7 +245,7 @@
输入二进制数据镜像，该算法会生成并输出摘要 (digest)，此摘要在硬件文档中有时也称摘要 (abstract)。
请前往 :component:`/esptool_py` 目录，查看 ``espsecure.py`` 工具，了解算法使用的 Python 版本。具体而言，请查看 ``digest_secure_bootloader`` 命令。
请前往 :component:`/esptool_py` 目录，查看 ``espsecure`` 工具，了解算法使用的 Python 版本。具体而言，请查看 ``digest-secure-bootloader`` 命令。
以下带有 (^) 标记的项目用于满足硬件限制，而非密码学限制。
@@ -309,7 +309,7 @@ keyfile 是设备的 32 字节原始安全启动密钥。
.. code-block::
esptool.py write_flash 0x0 bootloader-digest.bin
esptool write-flash 0x0 bootloader-digest.bin
.. _secure-boot-and-flash-encr:

16
docs/zh_CN/security/secure-boot-v2.rst
View File

@@ -50,7 +50,7 @@
.. note::
在本指南中，最常用的命令形式为 ``idf.py secure-<command>``，这是对应 ``espsecure.py <command>`` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure.py`` 的命令相比，可能会损失一部分高级功能。
在本指南中，最常用的命令形式为 ``idf.py secure-<command>``，这是对应 ``espsecure <command>`` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure`` 的命令相比，可能会损失一部分高级功能。
背景
----
@@ -350,7 +350,7 @@
- 默认 flash MMU 页面大小为 64 KB
:SOC_MMU_PAGE_SIZE_CONFIGURABLE: - {IDF_TARGET_NAME} 支持配置 flash MMU 页面大小，``CONFIG_MMU_PAGE_SIZE`` 根据 :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` 设置
- 在进行由 ``esptool.py`` 执行的 ``elf2image`` 转换时，可以通过使用选项 ``--secure-pad-v2`` 应用安全填充
- 在进行由 ``esptool`` 执行的 ``elf2image`` 转换时，可以通过使用选项 ``--secure-pad-v2`` 应用安全填充
带有安全填充和签名块的安全启动 v2 签名镜像的内容如下表所示：
@@ -487,7 +487,7 @@
在生产环境下，建议使用 OpenSSL 或其他行业标准的加密程序生成密钥对，详情请参阅 :ref:`secure-boot-v2-generate-key`。
7. 运行 ``idf.py bootloader`` 构建启用了安全启动的引导加载程序，构建输出中会包含一个烧录命令的提示，使用 ``esptool.py write_flash`` 烧录。
7. 运行 ``idf.py bootloader`` 构建启用了安全启动的引导加载程序，构建输出中会包含一个烧录命令的提示，使用 ``esptool write-flash`` 烧录。
8. 烧录引导加载程序前，请运行指定命令并等待烧录完成。注意，此处的指定命令需要手动输入，构建系统不会执行此过程。
@@ -621,7 +621,7 @@
使用 ``idf.py`` 进行签名
~~~~~~~~~~~~~~~~~~~~~~~~
对于生产构建，将签名密钥存储在远程签名服务器上，而不是本地构建机器上，是一种比较好的方案，这也是默认的 ESP-IDF 安全启动配置。可以使用命令行工具 ``espsecure.py`` 在远程系统上为应用程序镜像和分区表数据签名，供安全启动使用。
对于生产构建，将签名密钥存储在远程签名服务器上，而不是本地构建机器上，是一种比较好的方案，这也是默认的 ESP-IDF 安全启动配置。可以使用命令行工具 ``espsecure`` 在远程系统上为应用程序镜像和分区表数据签名，供安全启动使用。
使用远程签名时，请禁用选项 :ref:`CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES`，并构建固件。此时，私钥无需存在于构建系统中。
@@ -663,7 +663,7 @@
.. note::
在上述三种远程签名工作流程中，已签名的二进制文件将写入提供给 ``--output`` 参数的文件名中。选项 ``--append_signatures`` 支持将多个签名（最多 3 个）附加到镜像中。
在上述三种远程签名工作流程中，已签名的二进制文件将写入提供给 ``--output`` 参数的文件名中。选项 ``--append-signatures`` 支持将多个签名（最多 3 个）附加到镜像中。
.. only:: not SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
@@ -689,7 +689,7 @@
* 应独立计算并分别存储 1 到 3 个 {IDF_TARGET_SBV2_KEY} 公钥对（密钥 #0, #1, #2）。
* 完成烧录后，应设置 KEY_DIGEST eFuse 为写保护位。
* 未使用的 KEY_DIGEST 槽必须烧录其相应的 KEY_REVOKE eFuse，以永久禁用。请在设备离开工厂前完成此操作。
* 烧录 eFuse 可以由二级引导加载程序在首次从 menuconfig 启用 ``Secure Boot v2`` 后进行，也可以使用 ``espefuse.py``，后者与 ROM 中的串行引导加载程序通信。
* 烧录 eFuse 可以由二级引导加载程序在首次从 menuconfig 启用 ``Secure Boot v2`` 后进行，也可以使用 ``espefuse``，后者与 ROM 中的串行引导加载程序通信。
* KEY_DIGEST 应从密钥摘要 #0 开始，按顺序编号。如果使用了密钥摘要 #1，则必须使用密钥摘要 #0。如果使用了密钥摘要 #2，则必须使用密钥摘要 #0 和 #1。
* 二级引导加载程序不支持 OTA 升级，它将至少由一个私钥签名，也可能使用全部三个私钥，并在工厂内烧录。
* 应用程序应仅由单个私钥签名，其他私钥应妥善保管。但如果需要注销某些私钥，也可以使用多个签名私钥，请参阅下文的 :ref:`secure-boot-v2-key-revocation`。
@@ -704,14 +704,14 @@
.. code-block::
idf.py secure-sign-data -k secure_boot_signing_key2.pem --append_signatures -o signed_bootloader.bin build/bootloader/bootloader.bin
idf.py secure-sign-data -k secure_boot_signing_key2.pem --append-signatures -o signed_bootloader.bin build/bootloader/bootloader.bin
* 使用多个私钥签名时，建议独立签名这些私钥，可以的话请在不同服务器上进行签名，并将它们分开存储。
* 可以使用以下命令查看附加到二进制文件的签名：
.. code-block::
espsecure.py signature_info_v2 datafile.bin
espsecure signature-info-v2 datafile.bin
.. only:: SOC_ECDSA_SUPPORT_CURVE_P384

116
docs/zh_CN/security/security-features-enablement-workflows.rst
View File

@@ -9,7 +9,7 @@
{IDF_TARGET_CRYPT_CNT:default="SPI_BOOT_CRYPT_CNT",esp32="FLASH_CRYPT_CNT"}
{IDF_TARGET_CRYPT_CNT_MAX_VAL:default="7",esp32="127"}
{IDF_TARGET_SBV2_DEFAULT_SCHEME:default="RSA", esp32c2="ECDSA (V2)"}
{IDF_TARGET_FLASH_ENC_ARGS:default="--aes_xts", esp32=""}
{IDF_TARGET_FLASH_ENC_ARGS:default="--aes-xts", esp32=""}
概述
----
@@ -83,7 +83,7 @@
.. code:: bash
esptool.py --port PORT erase_flash
esptool --port PORT erase-flash
2. 生成一个 flash 加密密钥
@@ -93,7 +93,7 @@
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
@@ -101,20 +101,20 @@
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
如果 :ref:`生成的 AES-XTS 密钥的大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 为 AES-256（512 位密钥）：
.. code-block:: bash
espsecure.py generate_flash_encryption_key --keylen 512 my_flash_encryption_key.bin
espsecure generate-flash-encryption-key --keylen 512 my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
@@ -122,13 +122,13 @@
.. code-block:: bash
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
espsecure generate-flash-encryption-key my_flash_encryption_key.bin
如果 :ref:`生成的 AES-XTS 密钥的大小 <CONFIG_SECURE_FLASH_ENCRYPTION_KEYSIZE>` 是从 128 位（SHA256（128 位））派生的 AES-128 密钥：
.. code-block:: bash
espsecure.py generate_flash_encryption_key --keylen 128 my_flash_encryption_key.bin
espsecure generate-flash-encryption-key --keylen 128 my_flash_encryption_key.bin
3. 将 flash 加密密钥烧录到 eFuse 中
@@ -142,13 +142,13 @@
.. code-block:: bash
espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin
espefuse --port PORT burn-key flash-encryption my_flash_encryption_key.bin
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin KEYPURPOSE
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin KEYPURPOSE
其中， ``BLOCK`` 是位于 ``BLOCK_KEY0`` 和 ``BLOCK_KEY5`` 之间的空闲密钥块， ``KEYPURPOSE`` 是 ``XTS_AES_256_KEY_1``， ``XTS_AES_256_KEY_2`` 或 ``XTS_AES_128_KEY``。有关密钥用途的说明，请参阅 `{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_EN_URL}>`__。
@@ -156,28 +156,28 @@
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
对于 AES-256（512 位密钥）- ``XTS_AES_256_KEY_1`` 和 ``XTS_AES_256_KEY_2``。 ``espefuse.py`` 支持通过虚拟密钥用途 ``XTS_AES_256_KEY`` 将这两个密钥用途和一个 512 位密钥一起烧录到两个单独的密钥块中。使用时， ``espefuse.py`` 会把密钥的前 256 位烧录到指定的 ``BLOCK``，并把相应块的密钥用途烧录为 ``XTS_AES_256_KEY_1``。密钥的后 256 位会被烧录到 ``BLOCK`` 后的第一个空闲密钥块，相应块的密钥用途会烧录为 ``XTS_AES_256_KEY_2``。
对于 AES-256（512 位密钥）- ``XTS_AES_256_KEY_1`` 和 ``XTS_AES_256_KEY_2``。 ``espefuse`` 支持通过虚拟密钥用途 ``XTS_AES_256_KEY`` 将这两个密钥用途和一个 512 位密钥一起烧录到两个单独的密钥块中。使用时， ``espefuse`` 会把密钥的前 256 位烧录到指定的 ``BLOCK``，并把相应块的密钥用途烧录为 ``XTS_AES_256_KEY_1``。密钥的后 256 位会被烧录到 ``BLOCK`` 后的第一个空闲密钥块，相应块的密钥用途会烧录为 ``XTS_AES_256_KEY_2``。
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_256_KEY
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin XTS_AES_256_KEY
如果要指定使用两个块，那么可以将密钥分成两个 256 位密钥并手动烧录，以 ``XTS_AES_256_KEY_1`` 和 ``XTS_AES_256_KEY_2`` 作为密钥用途：
.. code-block:: bash
split -b 32 my_flash_encryption_key.bin my_flash_encryption_key.bin
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin.aa XTS_AES_256_KEY_1
espefuse.py --port PORT burn_key BLOCK+1 my_flash_encryption_key.bin.ab XTS_AES_256_KEY_2
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin.aa XTS_AES_256_KEY_1
espefuse --port PORT burn-key BLOCK+1 my_flash_encryption_key.bin.ab XTS_AES_256_KEY_2
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_128 and not SOC_FLASH_ENCRYPTION_XTS_AES_256 and not SOC_EFUSE_CONSISTS_OF_ONE_KEY_BLOCK
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
espefuse --port PORT burn-key BLOCK my_flash_encryption_key.bin XTS_AES_128_KEY
其中， ``BLOCK`` 是 ``BLOCK_KEY0`` 和 ``BLOCK_KEY5`` 之间的空闲密钥块。
@@ -187,20 +187,20 @@
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK_KEY0 flash_encryption_key256.bin XTS_AES_128_KEY
espefuse --port PORT burn-key BLOCK_KEY0 flash_encryption_key256.bin XTS_AES_128_KEY
对于从 SHA256（128 eFuse 位）派生的 AES-128 密钥 - ``XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS``。FE 密钥会被写入 eFuse BLOCK_KEY0 的后半部分。前 128 位不会被使用，并保持可供软件读取状态。使用 espefuse 工具的特殊模式，可以用任何 espefuse 命令将数据写入其中，可参考下文 ``同时烧录两个密钥``。
.. code-block:: bash
espefuse.py --port PORT burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
espefuse --port PORT burn-key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
同时烧录两个密钥（Secure Boot 和 flash 加密）：
.. code-block:: bash
espefuse.py --port PORT --chip esp32c2 burn_key_digest secure_boot_signing_key.pem \
burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
espefuse --port PORT --chip esp32c2 burn-key-digest secure_boot_signing_key.pem \
burn-key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS
.. only:: SOC_EFUSE_BLOCK9_KEY_PURPOSE_QUIRK
@@ -216,7 +216,7 @@
.. code-block:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse {IDF_TARGET_CRYPT_CNT} {IDF_TARGET_CRYPT_CNT_MAX_VAL}
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse {IDF_TARGET_CRYPT_CNT} {IDF_TARGET_CRYPT_CNT_MAX_VAL}
.. only:: esp32
@@ -224,7 +224,7 @@
.. code-block:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse FLASH_CRYPT_CONFIG 0xF
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse FLASH_CRYPT_CONFIG 0xF
5. 烧录下列与 flash 加密相关的安全 eFuse
@@ -256,11 +256,11 @@
.. code:: bash
espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1
espefuse --port PORT burn-efuse EFUSE_NAME 0x1
.. note::
请将 ``EFUSE_NAME`` 更新为需要烧录的 eFuse。可以在上述命令中添加多个 efuse 同时进行烧录（例如：``EFUSE_NAME VAL EFUSE_NAME2 VAL2``）。有关 `espefuse.py` 的更多信息，请参阅 `此文档 <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`__。
请将 ``EFUSE_NAME`` 更新为需要烧录的 eFuse。可以在上述命令中添加多个 efuse 同时进行烧录（例如：``EFUSE_NAME VAL EFUSE_NAME2 VAL2``）。有关 `espefuse` 的更多信息，请参阅 `此文档 <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`__。
.. only:: esp32
@@ -270,7 +270,7 @@
.. code:: bash
espefuse.py --port PORT write_protect_efuse DIS_CACHE
espefuse --port PORT write-protect-efuse DIS_CACHE
.. note::
@@ -284,7 +284,7 @@
.. code:: bash
espefuse.py --port PORT write_protect_efuse DIS_ICACHE
espefuse --port PORT write-protect-efuse DIS_ICACHE
.. note::
@@ -312,15 +312,15 @@
.. code-block:: bash
espsecure.py encrypt_flash_data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} --output bootloader-enc.bin build/bootloader/bootloader.bin
espsecure encrypt-flash-data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} --output bootloader-enc.bin build/bootloader/bootloader.bin
espsecure.py encrypt_flash_data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
espsecure encrypt-flash-data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x8000 --output partition-table-enc.bin build/partition_table/partition-table.bin
espsecure.py encrypt_flash_data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
espsecure encrypt-flash-data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin
上述命令中的偏移量仅适用于示例固件，请通过检查分区表条目或运行 `idf.py partition-table` 来获取你固件的实际偏移量。请注意，不需要加密所有二进制文件，只需加密在分区表定义文件中带有 ``encrypted`` 标记的文件，其他二进制文件只作为构建过程的普通输出进行烧录。
使用 ``esptool.py`` 可以将上述文件烧写到各自的偏移地址。要查看所有推荐的 ``esptool.py`` 命令行选项，请查阅 ``idf.py build`` 构建成功后打印的输出。
使用 ``esptool`` 可以将上述文件烧写到各自的偏移地址。要查看所有推荐的 ``esptool`` 命令行选项，请查阅 ``idf.py build`` 构建成功后打印的输出。
若应用程序包含分区 ``otadata`` 和 ``nvs_encryption_keys``，则该分区也需加密。详情请参阅 :ref:`encrypted-partitions`。
@@ -330,9 +330,9 @@
.. only:: esp32
如果 ESP32 在 eFuse 中使用非默认的 :ref:`FLASH_CRYPT_CONFIG 值 <setting-flash-crypt-config>`，需要将 ``--flash_crypt_conf`` 参数传递给 ``espsecure.py`` 以设置匹配值。如果通过二级引导加载程序配置 flash 加密，则不会发生这种情况，但是如果手动烧录了 eFuses 启用 flash 加密，就有可能发生。
如果 ESP32 在 eFuse 中使用非默认的 :ref:`FLASH_CRYPT_CONFIG 值 <setting-flash-crypt-config>`，需要将 ``--flash-crypt-conf`` 参数传递给 ``espsecure`` 以设置匹配值。如果通过二级引导加载程序配置 flash 加密，则不会发生这种情况，但是如果手动烧录了 eFuses 启用 flash 加密，就有可能发生。
使用 ``espsecure.py decrypt_flash_data`` 命令时，可以用相同的选项（和不同的输入或输出文件）来解密密文 flash 或之前加密的文件。
使用 ``espsecure decrypt-flash-data`` 命令时，可以用相同的选项（和不同的输入或输出文件）来解密密文 flash 或之前加密的文件。
8. 确保 ROM 下载模式安全
@@ -352,7 +352,7 @@
.. code:: bash
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS
espefuse --port PORT burn-efuse UART_DOWNLOAD_DIS
.. only:: not esp32
@@ -366,7 +366,7 @@
.. code:: bash
espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD
espefuse --port PORT burn-efuse ENABLE_SECURITY_DOWNLOAD
.. important::
@@ -396,7 +396,7 @@ flash 加密指南
.. code:: bash
espsecure.py generate_signing_key --version 2 --scheme rsa3072 secure_boot_signinig_key.pem
espsecure generate-signing-key --version 2 --scheme rsa3072 secure_boot_signinig_key.pem
.. only:: SOC_SECURE_BOOT_V2_ECC
@@ -404,7 +404,7 @@ flash 加密指南
.. code:: bash
bashespsecure.py generate_signing_key --version 2 --scheme ecdsa256 secure_boot_signing_key.pem
espsecure generate-signing-key --version 2 --scheme ecdsa256 secure_boot_signing_key.pem
.. only:: not SOC_ECDSA_SUPPORT_CURVE_P384
@@ -424,7 +424,7 @@ flash 加密指南
.. code:: bash
espsecure.py digest_sbv2_public_key --keyfile secure_boot_signing_key.pem --output digest.bin
espsecure digest-sbv2-public-key --keyfile secure_boot_signing_key.pem --output digest.bin
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
@@ -438,19 +438,19 @@ flash 加密指南
.. code:: bash
espefuse.py --port PORT --chip esp32 burn_key secure_boot_v2 digest.bin
espefuse --port PORT --chip esp32 burn-key secure_boot_v2 digest.bin
.. only:: esp32c2
.. code:: bash
espefuse.py --port PORT --chip esp32c2 burn_key KEY_BLOCK0 digest.bin SECURE_BOOT_DIGEST
espefuse --port PORT --chip esp32c2 burn-key KEY_BLOCK0 digest.bin SECURE_BOOT_DIGEST
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_key BLOCK digest.bin SECURE_BOOT_DIGEST0
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-key BLOCK digest.bin SECURE_BOOT_DIGEST0
其中，``BLOCK`` 是 ``BLOCK_KEY0`` 和 ``BLOCK_KEY5`` 之间的一个空闲密钥块。
@@ -464,13 +464,13 @@ flash 加密指南
.. code:: bash
espefuse.py --port PORT --chip esp32 burn_efuse ABS_DONE_1
espefuse --port PORT --chip esp32 burn-efuse ABS_DONE_1
.. only:: not esp32
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse SECURE_BOOT_EN
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse SECURE_BOOT_EN
.. only:: SOC_ECDSA_SUPPORT_CURVE_P384
@@ -478,7 +478,7 @@ flash 加密指南
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse SECURE_BOOT_SHA384_EN
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse SECURE_BOOT_SHA384_EN
5. 烧录相关 eFuse
@@ -507,11 +507,11 @@ flash 加密指南
.. code:: bash
espefuse.py burn_efuse --port PORT EFUSE_NAME 0x1
espefuse --port PORT burn-efuse EFUSE_NAME 0x1
.. note::
请将 EFUSE_NAME 更新为需烧录的 eFuse。在上述命令中添加多个 eFuse 可以同时烧录（例如：EFUSE_NAME VAL EFUSE_NAME2 VAL2）。有关 `espefuse.py` 的更多信息，请参阅 `此文档 <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`__。
请将 EFUSE_NAME 更新为需烧录的 eFuse。在上述命令中添加多个 eFuse 可以同时烧录（例如：EFUSE_NAME VAL EFUSE_NAME2 VAL2）。有关 `espefuse` 的更多信息，请参阅 `此文档 <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`__。
B) 与 Secure Boot v2 相关的 eFuse
@@ -521,7 +521,7 @@ flash 加密指南
.. code:: bash
espefuse.py -p $ESPPORT write_protect_efuse RD_DIS
espefuse -p $ESPPORT write-protect-efuse RD_DIS
.. important::
@@ -535,7 +535,7 @@ flash 加密指南
.. code:: bash
espefuse.py --port PORT --chip {IDF_TARGET_PATH_NAME} burn_efuse EFUSE_REVOKE_BIT
espefuse --port PORT --chip {IDF_TARGET_PATH_NAME} burn-efuse EFUSE_REVOKE_BIT
上述命令中的 ``EFUSE_REVOKE_BIT`` 可以是 ``SECURE_BOOT_KEY_REVOKE0`` 或 ``SECURE_BOOT_KEY_REVOKE1`` 或 ``SECURE_BOOT_KEY_REVOKE2``。注意，只有未使用的密钥摘要必须吊销。一旦吊销，相应的摘要就不能再次使用。
@@ -565,9 +565,9 @@ flash 加密指南
.. code:: bash
espsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output bootloader-signed.bin build/bootloader/bootloader.bin
espsecure sign-data --version 2 --keyfile secure_boot_signing_key.pem --output bootloader-signed.bin build/bootloader/bootloader.bin
espsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output my-app-signed.bin build/my-app.bin
espsecure sign-data --version 2 --keyfile secure_boot_signing_key.pem --output my-app-signed.bin build/my-app.bin
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
@@ -575,9 +575,9 @@ flash 加密指南
.. code:: bash
espsecure.py sign_data --keyfile secure_boot_signing_key2.pem --version 2 --amend_signatures -o bootloader-signed.bin bootloader-signed.bin
espsecure sign-data --keyfile secure_boot_signing_key2.pem --version 2 --append-signatures -o bootloader-signed.bin bootloader-signed.bin
espsecure.py sign_data --keyfile secure_boot_signing_key2.pem --version 2 --apend_signatures -o my-app-signed.bin my-app-signed.bin
espsecure sign-data --keyfile secure_boot_signing_key2.pem --version 2 --append-signatures -o my-app-signed.bin my-app-signed.bin
如果有第三个密钥，则可以重复以上过程。注意：输入和输出文件不能用相同名字来命名。
@@ -585,9 +585,9 @@ flash 加密指南
.. code:: bash
espsecure.py signature_info_v2 bootloader-signed.bin
espsecure signature-info-v2 bootloader-signed.bin
然后使用 ``esptool.py`` 将上述文件和其他二进制文件（如分区表）烧录到各自的偏移地址。要查看所有推荐的 ``esptool.py`` 命令行选项，请参阅 ``idf.py build`` 的输出结果。要获得固件的 flash 偏移地址，可查找分区表条目或运行 ``idf.py partition-table`` 查看。
然后使用 ``esptool`` 将上述文件和其他二进制文件（如分区表）烧录到各自的偏移地址。要查看所有推荐的 ``esptool`` 命令行选项，请参阅 ``idf.py build`` 的输出结果。要获得固件的 flash 偏移地址，可查找分区表条目或运行 ``idf.py partition-table`` 查看。
8. 确保 ROM 下载模式安全
@@ -607,7 +607,7 @@ flash 加密指南
.. code:: bash
espefuse.py --port PORT burn_efuse UART_DOWNLOAD_DIS
espefuse --port PORT burn-efuse UART_DOWNLOAD_DIS
.. only:: not esp32
@@ -621,7 +621,7 @@ flash 加密指南
.. code:: bash
espefuse.py --port PORT burn_efuse ENABLE_SECURITY_DOWNLOAD
espefuse --port PORT burn-efuse ENABLE_SECURITY_DOWNLOAD
Secure Boot v2 指南
~~~~~~~~~~~~~~~~~~~
@@ -667,7 +667,7 @@ Secure Boot v2 指南
.. code:: bash
espefuse.py --port PORT burn_key BLOCK hmac_key.bin HMAC_UP
espefuse --port PORT burn-key BLOCK hmac_key.bin HMAC_UP
其中，``BLOCK`` 是 ``BLOCK_KEY0`` 和 ``BLOCK_KEY5`` 之间的一个空闲密钥块。
@@ -697,7 +697,7 @@ Secure Boot v2 指南
5. 烧录 NVS 分区
使用 ``esptool.py`` 命令，将步骤 3 中生成的 NVS 分区 (``nvs_encr_partition.bin``) 烧录到相应的偏移地址。要查看所有推荐的 ``esptool.py`` 命令行选项，请查阅 ``idf.py build`` 构建成功后打印的输出。
使用 ``esptool`` 命令，将步骤 3 中生成的 NVS 分区 (``nvs_encr_partition.bin``) 烧录到相应的偏移地址。要查看所有推荐的 ``esptool`` 命令行选项，请查阅 ``idf.py build`` 构建成功后打印的输出。
如果芯片启用了 flash 加密，请先加密分区再进行烧录。详情请参阅 `flash 加密工作流程 <enable-flash-encryption-externally_>`_ 的相关烧录步骤。
@@ -743,6 +743,6 @@ Secure Boot v2 指南
4. 烧录 NVS 分区和 NVS 加密密钥
使用 ``esptool.py`` 命令，将 NVS 分区 (``nvs_encr_partition.bin``) 和 NVS 加密密钥 (``nvs_encr_key.bin``) 烧录到各自的偏移地址。通过 ``idf.py build`` 成功后打印的输出，可查看所有推荐的 ``esptool.py`` 命令行选项。
使用 ``esptool`` 命令，将 NVS 分区 (``nvs_encr_partition.bin``) 和 NVS 加密密钥 (``nvs_encr_key.bin``) 烧录到各自的偏移地址。通过 ``idf.py build`` 成功后打印的输出，可查看所有推荐的 ``esptool`` 命令行选项。
若芯片启用了 flash 加密，请在烧录之前先加密分区。详情请参阅 `flash 加密工作流程 <enable-flash-encryption-externally_>`_ 中与烧录相关的步骤。

10
docs/zh_CN/security/security.rst
View File

@@ -11,7 +11,7 @@
.. note::
在本指南中，最常用的命令形式为 ``idf.py secure-<command>``，这是对应 ``espsecure.py <command>`` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure.py`` 的命令相比，可能会损失一部分高级功能。
在本指南中，最常用的命令形式为 ``idf.py secure-<command>``，这是对应 ``espsecure <command>`` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure`` 的命令相比，可能会损失一部分高级功能。
.. only:: TARGET_SUPPORT_QEMU
@@ -55,7 +55,7 @@
* 在具备高质量熵源的系统上生成签名密钥。
* 签名密钥始终保密；签名密钥泄露会危及安全启动系统。
* 不允许第三方使用 ``idf.py secure-`` 或 ``espsecure.py`` 命令来观察密钥生成或是签名过程的任何细节，这两个过程都容易受到定时攻击或其他侧信道攻击的威胁。
* 不允许第三方使用 ``idf.py secure-`` 或 ``espsecure`` 命令来观察密钥生成或是签名过程的任何细节，这两个过程都容易受到定时攻击或其他侧信道攻击的威胁。
* 确保正确烧录所有安全性 eFuse，包括禁用调试接口以及非必需的启动介质（例如 UART 下载模式）等。
@@ -183,7 +183,7 @@ UART 下载模式
.. important::
如果禁用了 UART 下载模式，则无法在设备上使用 ``esptool.py``。
如果禁用了 UART 下载模式，则无法在设备上使用 ``esptool``。
.. only:: SOC_SUPPORTS_SECURE_DL_MODE
@@ -191,12 +191,12 @@ UART 下载模式
* 要启用安全 UART 下载模式，也可以调用 :cpp:func:`esp_efuse_enable_rom_secure_download_mode`。
* 该模式下，禁止执行通过 UART 下载模式下载的任意代码。
* 该模式将限制部分涉及更新 SPI 配置的命令，如更改波特率、基本的 flash 写入以及通过 ``get_security_info`` 返回当前启用的安全功能摘要。
* 该模式将限制部分涉及更新 SPI 配置的命令，如更改波特率、基本的 flash 写入以及通过 ``get-security-info`` 返回当前启用的安全功能摘要。
* 要完全禁用安全 UART 下载模式，可以将 :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` 设置为建议选项 ``Permanently disable ROM Download Mode``，或者在运行时调用 :cpp:func:`esp_efuse_disable_rom_download_mode`。
.. important::
安全 UART 下载模式下，仅支持使用 ``--no-stub`` 参数调用 ``esptool.py``。
安全 UART 下载模式下，仅支持使用 ``--no-stub`` 参数调用 ``esptool``。
.. only:: SOC_WIFI_SUPPORTED

2
examples/build_system/cmake/idf_as_lib/run-esp32.sh
View File

@@ -1,4 +1,4 @@
#!/usr/bin/env bash
cd build
python $IDF_PATH/components/esptool_py/esptool/esptool.py -p $1 write_flash @flash_project_args
python -m esptool -p $1 write-flash @flash_project_args
python -m esp_idf_monitor -p $1 idf_as_lib.elf

42
examples/security/flash_encryption/README.md
View File

@@ -118,7 +118,7 @@ Steps:
1. Generate an unique flash encryption key on a host
```
espsecure.py generate_flash_encryption_key example_flash_encryption_key.bin
espsecure generate-flash-encryption-key example_flash_encryption_key.bin
```
Alternatively, if you want to further develop the workflow, it might be useful to use all-zeroes "easy to restore" flash encryption key instead. However, never use this key in a production!
@@ -170,17 +170,17 @@ The offsets of the bootloader, application code and the partition table binaries
From the example application perspective it is necessary to encrypt every artefact except for 'nvs', 'custom_nvs' and 'fat_not_encr' partitions, as their content is expected to be plaintext.
```
espsecure.py encrypt_flash_data --keyfile example_flash_encryption_key.bin --output build/bootloader_encrypted.bin --address 0x1000 build/bootloader/bootloader.bin
espsecure.py encrypt_flash_data --keyfile example_flash_encryption_key.bin --output build/flash_encryption_encrypted.bin --address 0x20000 build/flash_encryption.bin
espsecure.py encrypt_flash_data --keyfile example_flash_encryption_key.bin --output build/partition_table_encrypted.bin --address 0xd000 build/partition_table/partition-table.bin
espsecure.py encrypt_flash_data --keyfile example_flash_encryption_key.bin --output build/storage_encrypted.bin --address 0x14000 build/storage.bin
espsecure.py encrypt_flash_data --keyfile example_flash_encryption_key.bin --output build/sample_encryption_keys_encrypted.bin --address 0x120000 sample_encryption_keys.bin
espsecure.py encrypt_flash_data --keyfile example_flash_encryption_key.bin --output build/fat_encrypted_encrypted.bin --address 0x127000 build/fat_encrypted.bin
espsecure encrypt-flash-data --keyfile example_flash_encryption_key.bin --output build/bootloader_encrypted.bin --address 0x1000 build/bootloader/bootloader.bin
espsecure encrypt-flash-data --keyfile example_flash_encryption_key.bin --output build/flash_encryption_encrypted.bin --address 0x20000 build/flash_encryption.bin
espsecure encrypt-flash-data --keyfile example_flash_encryption_key.bin --output build/partition_table_encrypted.bin --address 0xd000 build/partition_table/partition-table.bin
espsecure encrypt-flash-data --keyfile example_flash_encryption_key.bin --output build/storage_encrypted.bin --address 0x14000 build/storage.bin
espsecure encrypt-flash-data --keyfile example_flash_encryption_key.bin --output build/sample_encryption_keys_encrypted.bin --address 0x120000 sample_encryption_keys.bin
espsecure encrypt-flash-data --keyfile example_flash_encryption_key.bin --output build/fat_encrypted_encrypted.bin --address 0x127000 build/fat_encrypted.bin
```
5. Merge all the flash artefacts into one file
```
esptool.py --chip ESP32 merge_bin -o build\merged_encrypted_flash.bin --flash_mode dio --flash_size 4MB \
esptool --chip ESP32 merge-bin -o build\merged_encrypted_flash.bin --flash-mode dio --flash-size 4MB \
0x1000 build/bootloader_encrypted.bin \
0xd000 build/partition_table_encrypted.bin \
0xe000 build/nvs.bin \
@@ -199,24 +199,24 @@ Output flash binary file is `build\merged_encrypted_flash.bin`
This step can be performed only once. If the workflow is using non-zero flash encryption key generated in step 1, keep the encryption key file on a safe place for future application updates.
```
espefuse.py --chip esp32 --do-not-confirm --port $PORT burn_key flash_encryption example_flash_encryption_key.bin
espefuse.py --chip esp32 --do-not-confirm --port $PORT burn_efuse FLASH_CRYPT_CONFIG 0xf
espefuse.py --chip esp32 --do-not-confirm --port $PORT burn_efuse FLASH_CRYPT_CNT 127
espefuse --chip esp32 --do-not-confirm --port $PORT burn-key flash_encryption example_flash_encryption_key.bin
espefuse --chip esp32 --do-not-confirm --port $PORT burn-efuse FLASH_CRYPT_CONFIG 0xf
espefuse --chip esp32 --do-not-confirm --port $PORT burn-efuse FLASH_CRYPT_CNT 127
```
7. Burn security eFuses
WARNING: This step can be performed only once!
```
espefuse.py --chip esp32 --do-not-confirm --port $PORT burn_efuse DISABLE_DL_ENCRYPT 0x1
espefuse.py --chip esp32 --do-not-confirm --port $PORT burn_efuse DISABLE_DL_DECRYPT 0x1
espefuse.py --chip esp32 --do-not-confirm --port $PORT burn_efuse DISABLE_DL_CACHE 0x1
espefuse.py --chip esp32 --do-not-confirm --port $PORT burn_efuse JTAG_DISABLE 0x1
espefuse --chip esp32 --do-not-confirm --port $PORT burn-efuse DISABLE_DL_ENCRYPT 0x1
espefuse --chip esp32 --do-not-confirm --port $PORT burn-efuse DISABLE_DL_DECRYPT 0x1
espefuse --chip esp32 --do-not-confirm --port $PORT burn-efuse DISABLE_DL_CACHE 0x1
espefuse --chip esp32 --do-not-confirm --port $PORT burn-efuse JTAG_DISABLE 0x1
```
8. Flash the image to the ESP32-based device
```
python -m esptool --chip esp32 --port $PORT -b 460800 write_flash --force --flash_mode dio \
--flash_size 4MB --flash_freq 40m \
esptool --chip esp32 --port $PORT -b 460800 write-flash --force --flash-mode dio \
--flash-size 4MB --flash-freq 40m \
0x0000 build\merged_encrypted_flash.bin
```
@@ -227,7 +227,7 @@ idf.py --port $PORT monitor
10. You can verify the efuse settings using
```
espefuse.py --chip esp32 --port $PORT summary
espefuse --chip esp32 --port $PORT summary
```
For subsequent application update, only steps 4,5,8 are required.
@@ -375,12 +375,10 @@ I (7413) example: NVS partition "custom_nvs" is encrypted.
## Troubleshooting
It is also possible to use esptool.py utility to read the eFuse values and check if flash encryption is enabled or not
It is also possible to use espefuse utility to read the eFuse values and check if flash encryption is enabled or not
```
python $IDF_PATH/components/esptool_py/esptool/espefuse.py --port $PORT summary
espefuse --port $PORT summary
```
If FLASH_CRYPT_CNT (for ESP32) or SPI_BOOT_CRYPT_CNT (for ESP32-S2 and newer targets) eFuse value is non-zero, the flash encryption is enabled

25
examples/security/flash_encryption/pytest_flash_encryption.py
View File

@@ -1,7 +1,6 @@
# SPDX-FileCopyrightText: 2018-2025 Espressif Systems (Shanghai) CO LTD
# SPDX-License-Identifier: Apache-2.0
import binascii
from collections import namedtuple
from io import BytesIO
import espsecure
@@ -13,9 +12,9 @@ from pytest_embedded_idf.utils import idf_parametrize
# 1. Generate zero flash encryption key:
# dd if=/dev/zero of=key.bin bs=1 count=32
# 2.Burn Efuses:
# espefuse.py --do-not-confirm -p $ESPPORT burn_efuse FLASH_CRYPT_CONFIG 0xf
# espefuse.py --do-not-confirm -p $ESPPORT burn_efuse FLASH_CRYPT_CNT 0x1
# espefuse.py --do-not-confirm -p $ESPPORT burn_key flash_encryption key.bin
# espefuse --do-not-confirm -p $ESPPORT burn-efuse FLASH_CRYPT_CONFIG 0xf
# espefuse --do-not-confirm -p $ESPPORT burn-efuse FLASH_CRYPT_CNT 0x1
# espefuse --do-not-confirm -p $ESPPORT burn-key flash_encryption key.bin
def _test_flash_encryption(dut: Dut) -> None:
@@ -36,17 +35,17 @@ def _test_flash_encryption(dut: Dut) -> None:
key_bytes = b'\xff' + b'\x00' * 31
aes_xts = True
EncryptFlashDataArgs = namedtuple(
'EncryptFlashDataArgs', ['output', 'plaintext_file', 'address', 'keyfile', 'flash_crypt_conf', 'aes_xts']
output = BytesIO()
espsecure.encrypt_flash_data(
output=output,
plaintext_file=BytesIO(plain_data),
address=flash_addr,
keyfile=BytesIO(key_bytes),
flash_crypt_conf=0xF,
aes_xts=aes_xts,
)
args = EncryptFlashDataArgs(BytesIO(), BytesIO(plain_data), flash_addr, BytesIO(key_bytes), 0xF, aes_xts)
try:
# espsecure 5.0 arguments are passed one by one; the following will convert tuple to dict and unwrap it
espsecure.encrypt_flash_data(**args._asdict())
except TypeError:
espsecure.encrypt_flash_data(args)
expected_ciphertext = args.output.getvalue()
expected_ciphertext = output.getvalue()
hex_ciphertext = binascii.hexlify(expected_ciphertext).decode('ascii')
expected_str = (
' '.join(hex_ciphertext[i : i + 2] for i in range(0, 16, 2))

Some files were not shown because too many files have changed in this diff Show More