diff --git a/.github/ISSUE_TEMPLATE/02_runtime_bug.yml b/.github/ISSUE_TEMPLATE/02_runtime_bug.yml index f2d6236312..54b533f4ab 100644 --- a/.github/ISSUE_TEMPLATE/02_runtime_bug.yml +++ b/.github/ISSUE_TEMPLATE/02_runtime_bug.yml @@ -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 diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index d1a8d6fe85..7d2d62882c 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -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 diff --git a/COMPATIBILITY_CN.md b/COMPATIBILITY_CN.md index 97625bf60b..02175e87e4 100644 --- a/COMPATIBILITY_CN.md +++ b/COMPATIBILITY_CN.md @@ -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 对各芯片版本的支持 diff --git a/Kconfig b/Kconfig index ca849382cd..6ed57da043 100644 --- a/Kconfig +++ b/Kconfig @@ -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 diff --git a/README.md b/README.md index 147944cccd..c4c0a2e2c3 100644 --- a/README.md +++ b/README.md @@ -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` diff --git a/README_CN.md b/README_CN.md index 11fedc3ea1..5d63f6aeac 100644 --- a/README_CN.md +++ b/README_CN.md @@ -83,7 +83,7 @@ ESP-IDF 中的子模块采用相对路径（[详见 .gitmodules 文件](.gitmodu ## 烧写项目 -当构建结束，终端会打印出一条命令行，告知如何使用 esptool.py 工具烧写项目到芯片中。但你也可以运行下面这条命令来自动烧写： +当构建结束，终端会打印出一条命令行，告知如何使用 `esptool` 工具烧写项目到芯片中。但你也可以运行下面这条命令来自动烧写： `idf.py -p PORT flash` diff --git a/components/app_update/otatool.py b/components/app_update/otatool.py index 75298e1bc1..0e122987b5 100755 --- a/components/app_update/otatool.py +++ b/components/app_update/otatool.py @@ -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) @@ -71,8 +91,8 @@ class OtatoolTarget(): for i in range(2): start = i * (self.spi_flash_sec_size >> 1) - seq = bytearray(self.otadata[start:start + 4]) - crc = bytearray(self.otadata[start + 28:start + 32]) + seq = bytearray(self.otadata[start : start + 4]) + crc = bytearray(self.otadata[start + 28 : start + 32]) seq = struct.unpack('I', seq) crc = struct.unpack('I', crc) @@ -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. @@ -250,10 +278,14 @@ def main(): parser.add_argument('--baud', '-b', help='baudrate to use', type=int) - parser.add_argument('--partition-table-offset', '-o', help='offset to read the partition table from', type=str) + 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() @@ -324,7 +366,7 @@ def main(): target = OtatoolTarget(**target_args) # Create the operation table and execute the operation - common_args = {'target':target} + common_args = {'target': target} ota_id = [] @@ -338,18 +380,18 @@ def main(): pass otatool_ops = { - 'read_otadata':(_read_otadata, []), - 'erase_otadata':(_erase_otadata, []), - '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) + 'read_otadata': (_read_otadata, []), + 'erase_otadata': (_erase_otadata, []), + '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), } (op, op_args) = otatool_ops[args.operation] for op_arg in op_args: - common_args.update({op_arg:vars(args)[op_arg]}) + common_args.update({op_arg: vars(args)[op_arg]}) try: common_args['ota_id'] = common_args.pop('name') diff --git a/components/bootloader/Kconfig.bootloader_rollback b/components/bootloader/Kconfig.bootloader_rollback index 7a905cbf92..fc868f9cb3 100644 --- a/components/bootloader/Kconfig.bootloader_rollback +++ b/components/bootloader/Kconfig.bootloader_rollback @@ -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. diff --git a/components/bootloader/Kconfig.projbuild b/components/bootloader/Kconfig.projbuild index 2f4ecf9cc1..e2e45a895f 100644 --- a/components/bootloader/Kconfig.projbuild +++ b/components/bootloader/Kconfig.projbuild @@ -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 diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt index 9909718b88..3f0c8ddada 100644 --- a/components/bootloader/subproject/CMakeLists.txt +++ b/components/bootloader/subproject/CMakeLists.txt @@ -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 diff --git a/components/bootloader_support/CMakeLists.txt b/components/bootloader_support/CMakeLists.txt index 65c9252d8d..bd6cc2fe8e 100644 --- a/components/bootloader_support/CMakeLists.txt +++ b/components/bootloader_support/CMakeLists.txt @@ -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} diff --git a/components/bootloader_support/bootloader_flash/include/bootloader_flash_override.h b/components/bootloader_support/bootloader_flash/include/bootloader_flash_override.h index b910a8d6bc..75caf28bae 100644 --- a/components/bootloader_support/bootloader_flash/include/bootloader_flash_override.h +++ b/components/bootloader_support/bootloader_flash/include/bootloader_flash_override.h @@ -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 diff --git a/components/bootloader_support/bootloader_flash/src/flash_qio_mode.c b/components/bootloader_support/bootloader_flash/src/flash_qio_mode.c index 664d3f03a5..4b0ec90ef6 100644 --- a/components/bootloader_support/bootloader_flash/src/flash_qio_mode.c +++ b/components/bootloader_support/bootloader_flash/src/flash_qio_mode.c @@ -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 diff --git a/components/bootloader_support/include/esp_secure_boot.h b/components/bootloader_support/include/esp_secure_boot.h index aa1d738a9f..8e43bb6f79 100644 --- a/components/bootloader_support/include/esp_secure_boot.h +++ b/components/bootloader_support/include/esp_secure_boot.h @@ -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 diff --git a/components/bootloader_support/src/esp_image_format.c b/components/bootloader_support/src/esp_image_format.c index c947afb983..67bce232a4 100644 --- a/components/bootloader_support/src/esp_image_format.c +++ b/components/bootloader_support/src/esp_image_format.c @@ -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 diff --git a/components/esp_tee/subproject/CMakeLists.txt b/components/esp_tee/subproject/CMakeLists.txt index ce1028c462..81e184313b 100644 --- a/components/esp_tee/subproject/CMakeLists.txt +++ b/components/esp_tee/subproject/CMakeLists.txt @@ -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() diff --git a/components/esp_tee/test_apps/tee_cli_app/README.md b/components/esp_tee/test_apps/tee_cli_app/README.md index b9f4c39908..13b75c25d5 100644 --- a/components/esp_tee/test_apps/tee_cli_app/README.md +++ b/components/esp_tee/test_apps/tee_cli_app/README.md @@ -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 diff --git a/components/esp_tee/test_apps/tee_test_fw/conftest.py b/components/esp_tee/test_apps/tee_test_fw/conftest.py index 2a180f99b9..8b365947b5 100644 --- a/components/esp_tee/test_apps/tee_test_fw/conftest.py +++ b/components/esp_tee/test_apps/tee_test_fw/conftest.py @@ -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', diff --git a/components/esptool_py/Kconfig.projbuild b/components/esptool_py/Kconfig.projbuild index 2bb777e3d5..bbaa954ff1 100644 --- a/components/esptool_py/Kconfig.projbuild +++ b/components/esptool_py/Kconfig.projbuild @@ -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 diff --git a/components/esptool_py/espefuse.cmake b/components/esptool_py/espefuse.cmake index 5cf23bc98e..6e78421f79 100644 --- a/components/esptool_py/espefuse.cmake +++ b/components/esptool_py/espefuse.cmake @@ -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) diff --git a/components/esptool_py/esptool/espefuse.py b/components/esptool_py/esptool/espefuse.py index 507de8bf2a..39ba9a764e 100644 --- a/components/esptool_py/esptool/espefuse.py +++ b/components/esptool_py/esptool/espefuse.py @@ -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) diff --git a/components/esptool_py/esptool/espsecure.py b/components/esptool_py/esptool/espsecure.py index 3979e83eaa..6ff2f9be9a 100644 --- a/components/esptool_py/esptool/espsecure.py +++ b/components/esptool_py/esptool/espsecure.py @@ -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) diff --git a/components/esptool_py/esptool/esptool.py b/components/esptool_py/esptool/esptool.py index 2cad600ed8..1508f78061 100644 --- a/components/esptool_py/esptool/esptool.py +++ b/components/esptool_py/esptool/esptool.py @@ -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) diff --git a/components/esptool_py/flasher_args.json.in b/components/esptool_py/flasher_args.json.in index 1efa47b9db..224ace0b23 100644 --- a/components/esptool_py/flasher_args.json.in +++ b/components/esptool_py/flasher_args.json.in @@ -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}", diff --git a/components/esptool_py/project_include.cmake b/components/esptool_py/project_include.cmake index 7110dacf37..dbbb5eb884 100644 --- a/components/esptool_py/project_include.cmake +++ b/components/esptool_py/project_include.cmake @@ -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 (`_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 @@ $,\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 @@ $,\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 @@ $,\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() diff --git a/components/hal/test_apps/crypto/README.md b/components/hal/test_apps/crypto/README.md index a9bc97c10f..e4d1567f23 100644 --- a/components/hal/test_apps/crypto/README.md +++ b/components/hal/test_apps/crypto/README.md @@ -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 diff --git a/components/hal/test_apps/crypto/main/xts_aes/generate_xts_aes_encrypt_test_cases.py b/components/hal/test_apps/crypto/main/xts_aes/generate_xts_aes_encrypt_test_cases.py index f62b4d95cb..3a7dcf43b1 100644 --- a/components/hal/test_apps/crypto/main/xts_aes/generate_xts_aes_encrypt_test_cases.py +++ b/components/hal/test_apps/crypto/main/xts_aes/generate_xts_aes_encrypt_test_cases.py @@ -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 @@ -8,7 +8,7 @@ import tempfile import espsecure -def encrypt_and_print_aes_xts(keyfile:str, plaintext:bytes, address:int) -> None: +def encrypt_and_print_aes_xts(keyfile: str, plaintext: bytes, address: int) -> None: ciphertext = b'' inputfile = tempfile.NamedTemporaryFile() @@ -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', - '--keyfile', - f'{keyfile}', - '--output', - f'{outputfile.name}', - '--address', - f'{address}', - f'{inputfile.name}' - ]) + espsecure.main( + [ + 'encrypt-flash-data', + '--aes-xts', + '--keyfile', + f'{keyfile}', + '--output', + f'{outputfile.name}', + '--address', + f'{address}', + 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' diff --git a/components/hal/test_apps/crypto/pytest_crypto.py b/components/hal/test_apps/crypto/pytest_crypto.py index 0b8f3dab83..edcedc8339 100644 --- a/components/hal/test_apps/crypto/pytest_crypto.py +++ b/components/hal/test_apps/crypto/pytest_crypto.py @@ -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', diff --git a/components/mbedtls/Kconfig b/components/mbedtls/Kconfig index d0fc97a097..28295bf7e2 100644 --- a/components/mbedtls/Kconfig +++ b/components/mbedtls/Kconfig @@ -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 diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt index be94b4e011..fca05efc85 100644 --- a/components/partition_table/CMakeLists.txt +++ b/components/partition_table/CMakeLists.txt @@ -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) diff --git a/components/partition_table/parttool.py b/components/partition_table/parttool.py index 7d507b77eb..8f2bcdf2c4 100755 --- a/components/partition_table/parttool.py +++ b/components/partition_table/parttool.py @@ -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)) diff --git a/components/spi_flash/test_apps/flash_encryption/encrypt_flash.sh b/components/spi_flash/test_apps/flash_encryption/encrypt_flash.sh index 8d33f85e2f..172e0a1c76 100644 --- a/components/spi_flash/test_apps/flash_encryption/encrypt_flash.sh +++ b/components/spi_flash/test_apps/flash_encryption/encrypt_flash.sh @@ -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 diff --git a/components/xtensa/trax/test/Makefile b/components/xtensa/trax/test/Makefile index c8c24904c0..3f9cbdd9f6 100644 --- a/components/xtensa/trax/test/Makefile +++ b/components/xtensa/trax/test/Makefile @@ -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) diff --git a/docs/en/COPYRIGHT.rst b/docs/en/COPYRIGHT.rst index c863d2d56b..e787062d70 100644 --- a/docs/en/COPYRIGHT.rst +++ b/docs/en/COPYRIGHT.rst @@ -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/ diff --git a/docs/en/api-guides/bootloader.rst b/docs/en/api-guides/bootloader.rst index 688277c623..5bde5e8a21 100644 --- a/docs/en/api-guides/bootloader.rst +++ b/docs/en/api-guides/bootloader.rst @@ -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. diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index f1f880fa2c..3b3e75c4bb 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -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 `. @@ -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 diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index 37460548a6..8b2f1e9a05 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -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 diff --git a/docs/en/api-guides/tools/idf-docker-image.rst b/docs/en/api-guides/tools/idf-docker-image.rst index 8002c03d96..38d2a65631 100644 --- a/docs/en/api-guides/tools/idf-docker-image.rst +++ b/docs/en/api-guides/tools/idf-docker-image.rst @@ -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: diff --git a/docs/en/api-guides/tools/idf-py.rst b/docs/en/api-guides/tools/idf-py.rst index 917286147f..84b1d639df 100644 --- a/docs/en/api-guides/tools/idf-py.rst +++ b/docs/en/api-guides/tools/idf-py.rst @@ -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 ` 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 `_, use the following command: ``idf.py flash --extra-args="--spi-connection ,,,,"``. To see the full list of available arguments, run ``esptool.py write_flash --help`` or see the `esptool.py documentation `_. +``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 `_, use the following command: ``idf.py flash --extra-args="--spi-connection ,,,,"``. To see the full list of available arguments, run ``esptool write-flash --help`` or see the `esptool documentation `_. 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 diff --git a/docs/en/api-guides/usb-otg-console.rst b/docs/en/api-guides/usb-otg-console.rst index 537e5a39b9..0f75665c23 100644 --- a/docs/en/api-guides/usb-otg-console.rst +++ b/docs/en/api-guides/usb-otg-console.rst @@ -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 ` or another serial monitor. -* Flashing using ``esptool.py`` and ``idf.py flash``. +* Flashing using ``esptool`` and ``idf.py flash``. * :doc:`Device Firmware Update (DFU) ` interface for flashing the device using ``dfu-util`` and ``idf.py dfu``. .. note:: diff --git a/docs/en/api-guides/usb-serial-jtag-console.rst b/docs/en/api-guides/usb-serial-jtag-console.rst index ea97d5a0c2..1df2cd7b34 100644 --- a/docs/en/api-guides/usb-serial-jtag-console.rst +++ b/docs/en/api-guides/usb-serial-jtag-console.rst @@ -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 ` 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:: diff --git a/docs/en/api-reference/peripherals/sd_pullup_requirements.rst b/docs/en/api-reference/peripherals/sd_pullup_requirements.rst index 21e8e1e5ed..ee71488b85 100644 --- a/docs/en/api-reference/peripherals/sd_pullup_requirements.rst +++ b/docs/en/api-reference/peripherals/sd_pullup_requirements.rst @@ -218,25 +218,37 @@ 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: .. code-block:: bash - espefuse.py v2.6 + espefuse v5.0.2 Connecting.... - Enable internal flash voltage regulator (VDD_SDIO) to 3.3 V. + === Run "set-flash-voltage" command === + Enable internal flash voltage regulator (VDD_SDIO) to 3.3V. The following eFuses are burned: XPD_SDIO_FORCE, XPD_SDIO_REG, XPD_SDIO_TIEH. - This is an irreversible operation. + VDD_SDIO setting complete. + + Check all blocks for burn... + idx, BLOCK_NAME, Conclusion + [00] BLOCK0 is not empty + (written ): 0x0000000400182226000004320000a8b0002bc8f09e47e69800000000 + (to write): 0x00000000000000000001c00000000000000000000000000000000000 + (coding scheme = NONE) + . + This is an irreversible operation! Type 'BURN' (all capitals) to continue. BURN - VDD_SDIO setting complete. + BURN BLOCK0 - OK (write block == read block) + Reading updated eFuses... + Successful. To check the status of the eFuses, run: @@ -244,7 +256,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>`__]. diff --git a/docs/en/api-reference/peripherals/spi_flash/index.rst b/docs/en/api-reference/peripherals/spi_flash/index.rst index c48dfc577b..72dab9451b 100644 --- a/docs/en/api-reference/peripherals/spi_flash/index.rst +++ b/docs/en/api-reference/peripherals/spi_flash/index.rst @@ -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. diff --git a/docs/en/api-reference/storage/fatfs.rst b/docs/en/api-reference/storage/fatfs.rst index 88c51eff6b..67c0409a91 100644 --- a/docs/en/api-reference/storage/fatfs.rst +++ b/docs/en/api-reference/storage/fatfs.rst @@ -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`. diff --git a/docs/en/api-reference/storage/spiffs.rst b/docs/en/api-reference/storage/spiffs.rst index 28ab070455..18e16b44ba 100644 --- a/docs/en/api-reference/storage/spiffs.rst +++ b/docs/en/api-reference/storage/spiffs.rst @@ -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 `_. 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 `_. 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 `_ using the ``--spi-connection ,,,,`` 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 `_ using the ``--spi-connection ,,,,`` 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/en/api-reference/system/app_image_format.rst b/docs/en/api-reference/system/app_image_format.rst index df22a0efab..34235d4afd 100644 --- a/docs/en/api-reference/system/app_image_format.rst +++ b/docs/en/api-reference/system/app_image_format.rst @@ -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: diff --git a/docs/en/api-reference/system/bootloader_image_format.rst b/docs/en/api-reference/system/bootloader_image_format.rst index 98710de96f..44c6d4c0f2 100644 --- a/docs/en/api-reference/system/bootloader_image_format.rst +++ b/docs/en/api-reference/system/bootloader_image_format.rst @@ -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: diff --git a/docs/en/api-reference/system/chip_revision.rst b/docs/en/api-reference/system/chip_revision.rst index e3e4895558..65b03e5b31 100644 --- a/docs/en/api-reference/system/chip_revision.rst +++ b/docs/en/api-reference/system/chip_revision.rst @@ -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 ---------- diff --git a/docs/en/api-reference/system/efuse.rst b/docs/en/api-reference/system/efuse.rst index afe131b556..cfc99b5fa1 100644 --- a/docs/en/api-reference/system/efuse.rst +++ b/docs/en/api-reference/system/efuse.rst @@ -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-`` 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-`` 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 `_. +esptool includes a useful tool for reading/writing {IDF_TARGET_NAME} eFuse bits - `espefuse `_. -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 diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C2_dump.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C2_dump.rst index d0178a7be9..23db498b6b 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C2_dump.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C2_dump.rst @@ -3,10 +3,12 @@ idf.py efuse-dump Executing action: efuse-dump - Running espefuse.py in directory - Executing "espefuse.py dump --chip esp32c2"... - espefuse.py v4.6-dev - Connecting.... + Running espefuse in directory + Executing "espefuse dump --chip esp32c2"... + espefuse v5.0.2 + Connecting... + + === Run "dump" command === BLOCK0 (BLOCK0 ) [0 ] read_regs: 00000000 00000000 BLOCK1 (BLOCK1 ) [1 ] read_regs: 00000000 00000000 00000000 BLOCK2 (BLOCK2 ) [2 ] read_regs: 8d5c4b94 8252083a 5c01e953 80d0a824 c0860b18 00006890 00000000 4b000000 @@ -14,5 +16,3 @@ BLOCK0 (BLOCK0 ) [0 ] err__regs: 00000000 00000000 EFUSE_RD_RS_ERR_REG 0x00000000 - - === Run "dump" command === diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C3_dump.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C3_dump.rst index eac0fe28da..710d100ccf 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C3_dump.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C3_dump.rst @@ -3,10 +3,12 @@ idf.py efuse-dump Executing action: efuse-dump - Running espefuse.py in directory - Executing "espefuse.py dump --chip esp32c3"... - espefuse.py v4.6-dev + Running espefuse in directory + Executing "espefuse dump --chip esp32c3"... + espefuse v5.0.2 Connecting.... + + === Run "dump" command === BLOCK0 ( ) [0 ] read_regs: 00000000 00000000 00000000 00000000 80000000 00000000 MAC_SPI_8M_0 (BLOCK1 ) [1 ] read_regs: 790f968c 000058cf 00000000 020c0000 715424e0 0047d2f2 BLOCK_SYS_DATA (BLOCK2 ) [2 ] read_regs: 96046025 6f41fdc3 512cedbe 217ee31d d864ea41 5aba3a86 1e260363 00000009 @@ -22,5 +24,3 @@ BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 EFUSE_RD_RS_ERR0_REG 0x00000000 EFUSE_RD_RS_ERR1_REG 0x00000000 - - === Run "dump" command === diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C5.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C5.rst index c1acf3cf6b..f59087a18f 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C5.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C5.rst @@ -1,8 +1,9 @@ .. code-block:: none - espefuse.py -p PORT summary + idf.py -p PORT efuse-summary - espefuse.py v4.8.dev4 + Executing action: efuse-summary + (...) === Run "summary" command === EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C5_dump.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C5_dump.rst index a38afb695b..8e96f47a74 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C5_dump.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C5_dump.rst @@ -1,10 +1,14 @@ .. code-block:: none - espefuse.py dump + idf.py efuse-dump - espefuse.py v4.8.dev4 + Executing action: efuse-dump + Running espefuse in directory + Executing "espefuse dump --chip esp32c5"... + espefuse v5.0.2 Connecting.... - Detecting chip type... ESP32-C5 + + === Run "dump" command === BLOCK0 ( ) [0 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 MAC_SPI_8M_0 (BLOCK1 ) [1 ] read_regs: f9f95440 fffe6055 00000000 00000000 00000000 00000000 BLOCK_SYS_DATA (BLOCK2 ) [2 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 @@ -20,5 +24,3 @@ BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 EFUSE_RD_RS_ERR0_REG 0x00000000 EFUSE_RD_RS_ERR1_REG 0x00000000 - - === Run "dump" command === diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C61.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C61.rst index 7838b515cf..0326cfbdd1 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C61.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C61.rst @@ -2,8 +2,8 @@ idf.py -p /dev/ttyUSB0 efuse-summary - espefuse.py v4.10.dev2 - Connecting.... + Executing action: efuse-summary + (...) === Run "summary" command === EFUSE_NAME (Block) Description = [Meaningful Value] [Readable/Writeable] (Hex Value) diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C61_dump.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C61_dump.rst index 797bd7e973..9b7638b241 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C61_dump.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C61_dump.rst @@ -2,7 +2,10 @@ idf.py -p /dev/ttyUSB0 efuse-dump - espefuse.py v4.10.dev2 + espefuse v5.0.2 + Executing action: efuse-dump + Running espefuse in directory + Executing "espefuse dump --chip esp32c61"... Connecting.... === Run "dump" command === diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C6_dump.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C6_dump.rst index 8d52e713fb..c52442c4e6 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C6_dump.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-C6_dump.rst @@ -3,10 +3,12 @@ idf.py efuse-dump Executing action: efuse-dump - Running espefuse.py in directory - Executing "espefuse.py dump --chip esp32c6"... - espefuse.py v4.6-dev + Running espefuse in directory + Executing "espefuse dump --chip esp32c6"... + espefuse v5.0.2 Connecting.... + + === Run "dump" command === BLOCK0 ( ) [0 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 MAC_SPI_8M_0 (BLOCK1 ) [1 ] read_regs: f9f7529c 00006055 00000000 01040000 00000000 00000000 BLOCK_SYS_DATA (BLOCK2 ) [2 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 @@ -22,5 +24,3 @@ BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 EFUSE_RD_RS_ERR0_REG 0x00000000 EFUSE_RD_RS_ERR1_REG 0x00000000 - - === Run "dump" command === diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-H2_dump.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-H2_dump.rst index 6818c475e7..b22319eed4 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-H2_dump.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-H2_dump.rst @@ -3,10 +3,12 @@ idf.py efuse-dump Executing action: efuse-dump - Running espefuse.py in directory - Executing "espefuse.py dump --chip esp32h2"... - espefuse.py v4.6-dev + Running espefuse in directory + Executing "espefuse dump --chip esp32h2"... + espefuse v5.0.2 Connecting.... + + === Run "dump" command === BLOCK0 ( ) [0 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 MAC_SPI_8M_0 (BLOCK1 ) [1 ] read_regs: f9f72ca2 fffe6055 00000000 00000000 00000000 00000000 BLOCK_SYS_DATA (BLOCK2 ) [2 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 @@ -22,5 +24,3 @@ BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 EFUSE_RD_RS_ERR0_REG 0x00000000 EFUSE_RD_RS_ERR1_REG 0x00000000 - - === Run "dump" command === diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-P4_dump.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-P4_dump.rst index b05d66bb06..121db9d3cc 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-P4_dump.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-P4_dump.rst @@ -3,10 +3,12 @@ idf.py efuse-dump Executing action: efuse-dump - Running espefuse.py in directory - Executing "espefuse.py dump --chip esp32p4"... - espefuse.py v4.7.dev1 + Running espefuse in directory + Executing "espefuse dump --chip esp32p4"... + espefuse v5.0.2 Connecting.... + + === Run "dump" command === BLOCK0 ( ) [0 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 MAC_SPI_8M_0 (BLOCK1 ) [1 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 BLOCK_SYS_DATA (BLOCK2 ) [2 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 @@ -21,5 +23,3 @@ BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 EFUSE_RD_RS_ERR0_REG 0x00000000 EFUSE_RD_RS_ERR1_REG 0x00000000 - - === Run "dump" command === diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S2_dump.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S2_dump.rst index 882467597f..326804869e 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S2_dump.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S2_dump.rst @@ -3,10 +3,12 @@ idf.py efuse-dump Executing action: efuse-dump - Running espefuse.py in directory - Executing "espefuse.py dump --chip esp32s2"... - espefuse.py v4.6-dev + Running espefuse in directory + Executing "espefuse dump --chip esp32s2"... + espefuse v5.0.2 Connecting.... + + === Run "dump" command === BLOCK0 ( ) [0 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 MAC_SPI_8M_0 (BLOCK1 ) [1 ] read_regs: 79b3b954 000058cf 00000000 10440000 00000000 00000000 BLOCK_SYS_DATA (BLOCK2 ) [2 ] read_regs: f1c60eea 8238f201 595b98e9 0200fe81 1c549f24 88491102 06461421 070c2083 @@ -22,5 +24,3 @@ BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 EFUSE_RD_RS_ERR0_REG 0x00000000 EFUSE_RD_RS_ERR1_REG 0x00000000 - - === Run "dump" command === diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S3_dump.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S3_dump.rst index 1b21b5359a..e2e9d37893 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S3_dump.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32-S3_dump.rst @@ -3,9 +3,11 @@ idf.py efuse-dump Executing action: efuse-dump - Running espefuse.py in directory - Executing "espefuse.py dump --chip esp32s3"... - espefuse.py v4.6-dev + Running espefuse in directory + Executing "espefuse dump --chip esp32s3"... + espefuse v5.0.2 + + === Run "dump" command === Connecting.... BLOCK0 ( ) [0 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 MAC_SPI_8M_0 (BLOCK1 ) [1 ] read_regs: 3b41f270 0000ecda 00000000 030c0000 2c707800 9800cc58 @@ -22,5 +24,3 @@ BLOCK0 ( ) [0 ] err__regs: 00000000 00000000 00000000 00000000 00000000 00000000 EFUSE_RD_RS_ERR0_REG 0x00000000 EFUSE_RD_RS_ERR1_REG 0x00000000 - - === Run "dump" command === diff --git a/docs/en/api-reference/system/inc/espefuse_summary_ESP32_dump.rst b/docs/en/api-reference/system/inc/espefuse_summary_ESP32_dump.rst index e946529de6..6235abd311 100644 --- a/docs/en/api-reference/system/inc/espefuse_summary_ESP32_dump.rst +++ b/docs/en/api-reference/system/inc/espefuse_summary_ESP32_dump.rst @@ -3,15 +3,15 @@ idf.py efuse-dump Executing action: efuse-dump - Running espefuse.py in directory - Executing "espefuse.py dump --chip esp32"... - espefuse.py v4.6-dev + Running espefuse in directory + Executing "espefuse dump --chip esp32"... + espefuse v5.0.2 Connecting.... + + === Run "dump" command === BLOCK0 ( ) [0 ] read_regs: 00000000 7e5a6e58 00e294b9 0000a200 00000333 00100000 00000004 BLOCK1 (flash_encryption) [1 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 BLOCK2 (secure_boot_v1 s) [2 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 BLOCK3 ( ) [3 ] read_regs: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 EFUSE_REG_DEC_STATUS 0x00000000 - - === Run "dump" command === diff --git a/docs/en/get-started/esp32_output_log.inc b/docs/en/get-started/esp32_output_log.inc index 67b270cf31..ac2ad71563 100644 --- a/docs/en/get-started/esp32_output_log.inc +++ b/docs/en/get-started/esp32_output_log.inc @@ -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 - MAC: 24:0a:c4:05:b9:14 - Uploading stub... - Running stub... - Stub running... - Changing baud rate to 460800 + 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 + + 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 \ No newline at end of file diff --git a/docs/en/get-started/esp32c2_output_log.inc b/docs/en/get-started/esp32c2_output_log.inc index e194676a33..e447264010 100644 --- a/docs/en/get-started/esp32c2_output_log.inc +++ b/docs/en/get-started/esp32c2_output_log.inc @@ -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... \ No newline at end of file + Hard resetting via RTS pin... diff --git a/docs/en/get-started/esp32c3_output_log.inc b/docs/en/get-started/esp32c3_output_log.inc index 33d56b5e48..a8991197e1 100644 --- a/docs/en/get-started/esp32c3_output_log.inc +++ b/docs/en/get-started/esp32c3_output_log.inc @@ -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 \ No newline at end of file diff --git a/docs/en/get-started/esp32c5_output_log.inc b/docs/en/get-started/esp32c5_output_log.inc index fd464e12d9..4ece795892 100644 --- a/docs/en/get-started/esp32c5_output_log.inc +++ b/docs/en/get-started/esp32c5_output_log.inc @@ -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 - 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 + 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 + + 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... diff --git a/docs/en/get-started/esp32c6_output_log.inc b/docs/en/get-started/esp32c6_output_log.inc index 7c640c2a12..90da96614a 100644 --- a/docs/en/get-started/esp32c6_output_log.inc +++ b/docs/en/get-started/esp32c6_output_log.inc @@ -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... \ No newline at end of file + Hard resetting via RTS pin... diff --git a/docs/en/get-started/esp32h2_output_log.inc b/docs/en/get-started/esp32h2_output_log.inc index fe526e923d..c25d86eee3 100644 --- a/docs/en/get-started/esp32h2_output_log.inc +++ b/docs/en/get-started/esp32h2_output_log.inc @@ -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... \ No newline at end of file + Hard resetting via RTS pin... diff --git a/docs/en/get-started/esp32p4_output_log.inc b/docs/en/get-started/esp32p4_output_log.inc index e8d0eb6553..eaadbd8fe2 100644 --- a/docs/en/get-started/esp32p4_output_log.inc +++ b/docs/en/get-started/esp32p4_output_log.inc @@ -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 diff --git a/docs/en/get-started/esp32s2_output_log.inc b/docs/en/get-started/esp32s2_output_log.inc index 95279df68b..1c87cccf0e 100644 --- a/docs/en/get-started/esp32s2_output_log.inc +++ b/docs/en/get-started/esp32s2_output_log.inc @@ -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 \ No newline at end of file diff --git a/docs/en/get-started/esp32s3_output_log.inc b/docs/en/get-started/esp32s3_output_log.inc index b8caeaed3c..f0b350adce 100644 --- a/docs/en/get-started/esp32s3_output_log.inc +++ b/docs/en/get-started/esp32s3_output_log.inc @@ -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 \ No newline at end of file diff --git a/docs/en/get-started/flashing-troubleshooting.rst b/docs/en/get-started/flashing-troubleshooting.rst index b9b663b73c..76e4f657de 100644 --- a/docs/en/get-started/flashing-troubleshooting.rst +++ b/docs/en/get-started/flashing-troubleshooting.rst @@ -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 `_ 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 `_ 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 `_ 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 `_ for the ESP32 DevKitC development board. -In general, you should have no problems with the `official esp-idf development boards `_. 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 `_. 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. diff --git a/docs/en/get-started/start-project.rst b/docs/en/get-started/start-project.rst index 3ee0868893..29b01e28c6 100644 --- a/docs/en/get-started/start-project.rst +++ b/docs/en/get-started/start-project.rst @@ -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. diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index efe90e745c..1775063ae4 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -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-``, which is a wrapper around corresponding ``espsecure.py ``. 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-``, which is a wrapper around corresponding ``espsecure ``. 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 ` 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 diff --git a/docs/en/security/secure-boot-v1.rst b/docs/en/security/secure-boot-v1.rst index d67b75999a..03eebd1f20 100644 --- a/docs/en/security/secure-boot-v1.rst +++ b/docs/en/security/secure-boot-v1.rst @@ -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-``, which is a wrapper around corresponding ``espsecure.py ``. 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-``, which is a wrapper around corresponding ``espsecure ``. 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: diff --git a/docs/en/security/secure-boot-v2.rst b/docs/en/security/secure-boot-v2.rst index 2f1eb1e1fa..06b10c0594 100644 --- a/docs/en/security/secure-boot-v2.rst +++ b/docs/en/security/secure-boot-v2.rst @@ -50,7 +50,7 @@ Secure Boot v2 .. note:: - In this guide, most used commands are in the form of ``idf.py secure-``, which is a wrapper around corresponding ``espsecure.py ``. 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-``, which is a wrapper around corresponding ``espsecure ``. 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 diff --git a/docs/en/security/security-features-enablement-workflows.rst b/docs/en/security/security-features-enablement-workflows.rst index 51d587cfb1..22a7a95cb3 100644 --- a/docs/en/security/security-features-enablement-workflows.rst +++ b/docs/en/security/security-features-enablement-workflows.rst @@ -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 ` 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 ` 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 `_. + 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 `_. .. 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 ` 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 ` 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 `_ + 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 `_ 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 `_. @@ -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 `_. diff --git a/docs/en/security/security.rst b/docs/en/security/security.rst index 4df4311225..9889e0c756 100644 --- a/docs/en/security/security.rst +++ b/docs/en/security/security.rst @@ -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-``, which is a wrapper around corresponding ``espsecure.py ``. 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-``, which is a wrapper around corresponding ``espsecure ``. 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 diff --git a/docs/zh_CN/COPYRIGHT.rst b/docs/zh_CN/COPYRIGHT.rst index 6607f98998..cb90842108 100644 --- a/docs/zh_CN/COPYRIGHT.rst +++ b/docs/zh_CN/COPYRIGHT.rst @@ -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/ diff --git a/docs/zh_CN/api-guides/bootloader.rst b/docs/zh_CN/api-guides/bootloader.rst index 4c217de8b5..83396708e6 100644 --- a/docs/zh_CN/api-guides/bootloader.rst +++ b/docs/zh_CN/api-guides/bootloader.rst @@ -202,7 +202,7 @@ ESP-IDF 二级引导加载程序位于 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_O 恢复引导加载程序功能可在 OTA 升级失败时为引导加载程序提供安全回退机制。eFuse 字段 ``ESP_EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR`` 将指定恢复引导加载程序的 flash（以扇区为单位）地址。如果位于 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 的主引导加载程序加载失败，ROM 引导加载程序会尝试从指定地址加载恢复引导加载程序。 - - 可以使用 ``espefuse.py`` 或在用户应用程序中调用 :cpp:func:`esp_efuse_set_recovery_bootloader_offset()` 来设置 eFuse。 + - 可以使用 ``espefuse`` 或在用户应用程序中调用 :cpp:func:`esp_efuse_set_recovery_bootloader_offset()` 来设置 eFuse。 - 该地址可通过 ``CONFIG_BOOTLOADER_RECOVERY_OFFSET`` 进行设置，且必须为 flash 扇区大小（0x1000 字节）的整数倍。此 Kconfig 选项有助于确保恢复引导加载程序不会与现有分区重叠。 - 注意，eFuse 字段存储的是以扇区为单位的偏移量。将其设置为最大值 ``0xFFF`` 可禁用恢复引导加载程序功能。 - 默认情况下，``CONFIG_BOOTLOADER_RECOVERY_OFFSET`` 处的恢复引导加载程序镜像不会被烧录，但可以作为 OTA 升级流程的一部分进行写入。 diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index b507cf06b4..718d35e29b 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -54,7 +54,7 @@ idf.py - CMake_，配置待构建的项目 - Ninja_，用于构建项目 -- `esptool.py`_，烧录目标硬件设备 +- `esptool`_，烧录目标硬件设备 可通过 ``idf.py`` 配置构建系统，具体可参考 :doc:`IDF 前端工具 `。 @@ -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 也可以手动复制参数文件中的数据到命令行中执行。 @@ -1380,7 +1380,6 @@ ESP-IDF 构建命令 # 注册该依赖，使其在 ELF 链接完成后、BIN 生成之前运行 idf_build_add_post_elf_dependency("${CMAKE_PROJECT_NAME}.elf" strip_elf) - .. code-block:: none idf_build_get_post_elf_dependencies(elf_filename out_var) @@ -1568,7 +1567,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 +1750,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 diff --git a/docs/zh_CN/api-guides/flash_psram_config.rst b/docs/zh_CN/api-guides/flash_psram_config.rst index 0dafd6a52f..b439c20d2f 100644 --- a/docs/zh_CN/api-guides/flash_psram_config.rst +++ b/docs/zh_CN/api-guides/flash_psram_config.rst @@ -241,7 +241,7 @@ F4R4 硬件 load:0x3fcd0108,len:0x171c ets_loader.c 78 - 这可能意味着必要的 efuse 未得到正确烧录。请使用命令 ``espefuse.py summary``，检查芯片的 eFuse 位。 + 这可能意味着必要的 efuse 未得到正确烧录。请使用命令 ``idf.py efuse-summary``，检查芯片的 eFuse 位。 一级 (ROM) 引导加载程序可通过 eFuse 位 ``FLASH_TYPE`` 将 flash 复位为默认模式（SPI 模式）。如果未烧录此位，且 flash 处于 OPI 模式，则一级 (ROM) 引导加载程序可能无法从 flash 中读取并加载以下图像。 diff --git a/docs/zh_CN/api-guides/partition-tables.rst b/docs/zh_CN/api-guides/partition-tables.rst index 9bda03b105..de42a789fa 100644 --- a/docs/zh_CN/api-guides/partition-tables.rst +++ b/docs/zh_CN/api-guides/partition-tables.rst @@ -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 diff --git a/docs/zh_CN/api-guides/tools/idf-docker-image.rst b/docs/zh_CN/api-guides/tools/idf-docker-image.rst index 76a4e33010..b9279247cd 100644 --- a/docs/zh_CN/api-guides/tools/idf-docker-image.rst +++ b/docs/zh_CN/api-guides/tools/idf-docker-image.rst @@ -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 容器内部烧写连接到主机的设备： diff --git a/docs/zh_CN/api-guides/tools/idf-py.rst b/docs/zh_CN/api-guides/tools/idf-py.rst index a00bae8a4d..6713c24a92 100644 --- a/docs/zh_CN/api-guides/tools/idf-py.rst +++ b/docs/zh_CN/api-guides/tools/idf-py.rst @@ -7,7 +7,7 @@ IDF 前端工具 - ``idf.py`` - CMake_ 用于配置要构建的工程。 - Ninja_ 用于构建工程。 -- `esptool.py`_ 用于烧录目标芯片。 +- `esptool`_ 用于烧录目标芯片。 :ref:`第五步：开始使用 ESP-IDF 吧 ` 简要介绍了设置 ``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 芯片 `_，请使用以下命令： ``idf.py flash --extra-args="--spi-connection ,,,,"``。要查看所有可用参数，请运行 ``esptool.py write_flash --help`` 或查看 `esptool.py 文档 `_。 +``idf.py`` 在内部使用 ``esptool`` 的 ``write-flash`` 命令来烧录目标设备。通过 ``--extra-args`` 选项传递额外的参数，并配置烧录过程。例如，要 `写入到外部 SPI flash 芯片 `_，请使用以下命令： ``idf.py flash --extra-args="--spi-connection ,,,,"``。要查看所有可用参数，请运行 ``esptool write-flash --help`` 或查看 `esptool 文档 `_。 与 ``build`` 命令类似，使用 ``app``、``bootloader`` 或 ``partition-table`` 参数运行此命令，可选择仅烧录应用程序、引导加载程序或分区表。 @@ -152,7 +152,7 @@ uf2 二进制文件也可以通过 :ref:`idf.py uf2 ` 生 - 仅针对 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 ` 生 .. _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 diff --git a/docs/zh_CN/api-guides/usb-otg-console.rst b/docs/zh_CN/api-guides/usb-otg-console.rst index dcaa6f76e1..da5ab27985 100644 --- a/docs/zh_CN/api-guides/usb-otg-console.rst +++ b/docs/zh_CN/api-guides/usb-otg-console.rst @@ -6,7 +6,7 @@ USB OTG 控制台 在集成了 USB 外设的芯片上，可以使用 USB 通信设备类 (CDC) 来实现串行控制台，而不是使用带有外部 USB-UART 桥接芯片的 UART，{IDF_TARGET_NAME} ROM 中包含 USB CDC 实现，支持一些基本功能，而无需应用程序包含 USB 协议栈： * 双向串行控制台，可与 :doc:`IDF 监视器 ` 或其他串行监视器一起使用。 -* 使用 ``esptool.py`` 和 ``idf.py flash`` 进行烧录。 +* 使用 ``esptool`` 和 ``idf.py flash`` 进行烧录。 * :doc:`设备固件更新 (DFU) ` 接口，可通过 ``dfu-util`` 和 ``dfu-util`` 烧录设备。 .. note:: diff --git a/docs/zh_CN/api-guides/usb-serial-jtag-console.rst b/docs/zh_CN/api-guides/usb-serial-jtag-console.rst index 52b4ef8417..4591b335aa 100644 --- a/docs/zh_CN/api-guides/usb-serial-jtag-console.rst +++ b/docs/zh_CN/api-guides/usb-serial-jtag-console.rst @@ -9,7 +9,7 @@ ESP 芯片通常使用 UART 实现串口，并可以通过外部 USB-UART 桥接 拥有 USB 串行/JTAG 控制器时，{IDF_TARGET_NAME} 支持以下功能： * 双向串行控制台，可与 :doc:`IDF 监视器 ` 或其他串行监视器一起使用。 -* 使用 ``esptool.py`` 和 ``idf.py flash`` 烧录。 +* 使用 ``esptool`` 和 ``idf.py flash`` 烧录。 * 使用 OpenOCD 等工具进行 JTAG 调试，同时进行串行操作。 .. note:: diff --git a/docs/zh_CN/api-reference/peripherals/sd_pullup_requirements.rst b/docs/zh_CN/api-reference/peripherals/sd_pullup_requirements.rst index 16f88d6884..bc2ac35e9c 100644 --- a/docs/zh_CN/api-reference/peripherals/sd_pullup_requirements.rst +++ b/docs/zh_CN/api-reference/peripherals/sd_pullup_requirements.rst @@ -218,25 +218,37 @@ 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。如果烧录成功，将看到以下日志： .. code-block:: bash - espefuse.py v2.6 + espefuse v5.0.2 Connecting.... - Enable internal flash voltage regulator (VDD_SDIO) to 3.3 V. + === Run "set-flash-voltage" command === + Enable internal flash voltage regulator (VDD_SDIO) to 3.3V. The following eFuses are burned: XPD_SDIO_FORCE, XPD_SDIO_REG, XPD_SDIO_TIEH. - This is an irreversible operation. + VDD_SDIO setting complete. + + Check all blocks for burn... + idx, BLOCK_NAME, Conclusion + [00] BLOCK0 is not empty + (written ): 0x0000000400182226000004320000a8b0002bc8f09e47e69800000000 + (to write): 0x00000000000000000001c00000000000000000000000000000000000 + (coding scheme = NONE) + . + This is an irreversible operation! Type 'BURN' (all capitals) to continue. BURN - VDD_SDIO setting complete. + BURN BLOCK0 - OK (write block == read block) + Reading updated eFuses... + Successful. 要检查 eFuse 的状态，请运行： @@ -244,7 +256,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>`__]。 diff --git a/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst b/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst index f017079316..5a0017103a 100644 --- a/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst +++ b/docs/zh_CN/api-reference/peripherals/spi_flash/index.rst @@ -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 中）进行边界检查。 diff --git a/docs/zh_CN/api-reference/storage/fatfs.rst b/docs/zh_CN/api-reference/storage/fatfs.rst index f36df695cd..6df8f9cedc 100644 --- a/docs/zh_CN/api-reference/storage/fatfs.rst +++ b/docs/zh_CN/api-reference/storage/fatfs.rst @@ -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`。 diff --git a/docs/zh_CN/api-reference/storage/spiffs.rst b/docs/zh_CN/api-reference/storage/spiffs.rst index da68b7a670..7cdfc29ccb 100644 --- a/docs/zh_CN/api-reference/storage/spiffs.rst +++ b/docs/zh_CN/api-reference/storage/spiffs.rst @@ -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 `_ 工具创建 SPIFFS 分区镜像。与 ``spiffsgen.py`` 相似，`mkspiffs `_ 也可以用于从指定文件夹中生成镜像，然后使用 ``esptool.py`` 烧录镜像。 +用户也可以使用 `mkspiffs `_ 工具创建 SPIFFS 分区镜像。与 ``spiffsgen.py`` 相似，`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 ,,,,`` 选项 `将 spiffs 数据写入外部 SPI flash 芯片 `_。只需指定分配给外部 flash 的 GPIO 管脚，如 ``python esptool.py write_flash --spi-connection 6,7,8,9,11 -z 0x110000 spiffs.bin``。 + 可以使用 ``esptool`` 的 ``write-flash`` 命令，通过 ``--spi-connection ,,,,`` 选项 `将 spiffs 数据写入外部 SPI flash 芯片 `_。只需指定分配给外部 flash 的 GPIO 管脚，如 ``esptool write-flash --spi-connection 6,7,8,9,11 -z 0x110000 spiffs.bin``。 选择合适的 SPIFFS 工具 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/zh_CN/api-reference/system/app_image_format.rst b/docs/zh_CN/api-reference/system/app_image_format.rst index aface2b8c1..55251a40ee 100644 --- a/docs/zh_CN/api-reference/system/app_image_format.rst +++ b/docs/zh_CN/api-reference/system/app_image_format.rst @@ -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 日志中也会包含段的相关信息： diff --git a/docs/zh_CN/api-reference/system/bootloader_image_format.rst b/docs/zh_CN/api-reference/system/bootloader_image_format.rst index 1f7073bf1d..2bbf5cf166 100644 --- a/docs/zh_CN/api-reference/system/bootloader_image_format.rst +++ b/docs/zh_CN/api-reference/system/bootloader_image_format.rst @@ -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: diff --git a/docs/zh_CN/api-reference/system/chip_revision.rst b/docs/zh_CN/api-reference/system/chip_revision.rst index c700d56946..16b928f971 100644 --- a/docs/zh_CN/api-reference/system/chip_revision.rst +++ b/docs/zh_CN/api-reference/system/chip_revision.rst @@ -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`` 命令查看芯片版本。 参考链接 ---------- diff --git a/docs/zh_CN/api-reference/system/efuse.rst b/docs/zh_CN/api-reference/system/efuse.rst index c3b4bd624f..e2c30d0458 100644 --- a/docs/zh_CN/api-reference/system/efuse.rst +++ b/docs/zh_CN/api-reference/system/efuse.rst @@ -20,7 +20,7 @@ eFuse 管理器组件中集合了多种工具和 API，可帮助定义、烧录 eFuse Manager 与 ``idf.py`` --------------------------- -``idf.py`` 通过 ``idf.py efuse-`` 命令为 eFuse 管理器提供了部分功能。本文档主要使用基于 ``idf.py`` 的命令，只有在涉及高级功能或罕见情况时，会使用基于 ``espefuse.py`` 的命令。要查看所有可用的命令，请运行 ``idf.py --help`` 并搜索以 ``efuse-`` 为前缀的命令。 +``idf.py`` 通过 ``idf.py efuse-`` 命令为 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 `_。 +esptool 中包含一个用于读取/写入 {IDF_TARGET_NAME} eFuse 位的有用工具： `espefuse `_。 -``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 diff --git a/docs/zh_CN/get-started/esp32_output_log.inc b/docs/zh_CN/get-started/esp32_output_log.inc index 67b270cf31..ac2ad71563 100644 --- a/docs/zh_CN/get-started/esp32_output_log.inc +++ b/docs/zh_CN/get-started/esp32_output_log.inc @@ -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 - MAC: 24:0a:c4:05:b9:14 - Uploading stub... - Running stub... - Stub running... - Changing baud rate to 460800 + 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 + + 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 \ No newline at end of file diff --git a/docs/zh_CN/get-started/esp32c2_output_log.inc b/docs/zh_CN/get-started/esp32c2_output_log.inc index e194676a33..e447264010 100644 --- a/docs/zh_CN/get-started/esp32c2_output_log.inc +++ b/docs/zh_CN/get-started/esp32c2_output_log.inc @@ -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... \ No newline at end of file + Hard resetting via RTS pin... diff --git a/docs/zh_CN/get-started/esp32c3_output_log.inc b/docs/zh_CN/get-started/esp32c3_output_log.inc index 33d56b5e48..a8991197e1 100644 --- a/docs/zh_CN/get-started/esp32c3_output_log.inc +++ b/docs/zh_CN/get-started/esp32c3_output_log.inc @@ -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 \ No newline at end of file diff --git a/docs/zh_CN/get-started/esp32c5_output_log.inc b/docs/zh_CN/get-started/esp32c5_output_log.inc index fd464e12d9..4ece795892 100644 --- a/docs/zh_CN/get-started/esp32c5_output_log.inc +++ b/docs/zh_CN/get-started/esp32c5_output_log.inc @@ -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 - 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 + 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 + + 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... diff --git a/docs/zh_CN/get-started/esp32c6_output_log.inc b/docs/zh_CN/get-started/esp32c6_output_log.inc index 7c640c2a12..90da96614a 100644 --- a/docs/zh_CN/get-started/esp32c6_output_log.inc +++ b/docs/zh_CN/get-started/esp32c6_output_log.inc @@ -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... \ No newline at end of file + Hard resetting via RTS pin... diff --git a/docs/zh_CN/get-started/esp32h2_output_log.inc b/docs/zh_CN/get-started/esp32h2_output_log.inc index fe526e923d..c25d86eee3 100644 --- a/docs/zh_CN/get-started/esp32h2_output_log.inc +++ b/docs/zh_CN/get-started/esp32h2_output_log.inc @@ -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... \ No newline at end of file + Hard resetting via RTS pin... diff --git a/docs/zh_CN/get-started/esp32p4_output_log.inc b/docs/zh_CN/get-started/esp32p4_output_log.inc index e8d0eb6553..eaadbd8fe2 100644 --- a/docs/zh_CN/get-started/esp32p4_output_log.inc +++ b/docs/zh_CN/get-started/esp32p4_output_log.inc @@ -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 diff --git a/docs/zh_CN/get-started/esp32s2_output_log.inc b/docs/zh_CN/get-started/esp32s2_output_log.inc index 95279df68b..1c87cccf0e 100644 --- a/docs/zh_CN/get-started/esp32s2_output_log.inc +++ b/docs/zh_CN/get-started/esp32s2_output_log.inc @@ -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 \ No newline at end of file diff --git a/docs/zh_CN/get-started/esp32s3_output_log.inc b/docs/zh_CN/get-started/esp32s3_output_log.inc index b8caeaed3c..f0b350adce 100644 --- a/docs/zh_CN/get-started/esp32s3_output_log.inc +++ b/docs/zh_CN/get-started/esp32s3_output_log.inc @@ -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 \ No newline at end of file diff --git a/docs/zh_CN/get-started/flashing-troubleshooting.rst b/docs/zh_CN/get-started/flashing-troubleshooting.rst index 17e1ce7851..d49a072b45 100644 --- a/docs/zh_CN/get-started/flashing-troubleshooting.rst +++ b/docs/zh_CN/get-started/flashing-troubleshooting.rst @@ -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 故障排除 `_ 获取更多信息。 +如果在运行给定命令时出现如“连接失败”这样的错误，造成该错误的原因之一可能是运行 ``esptool`` 时出现错误。 ``esptool`` 是构建系统调用的程序，用于重置芯片、与 ROM 引导加载器交互以及烧录固件的工具。可以按照以下步骤进行手动复位，轻松解决该问题。如果问题仍未解决，请参考 `esptool 故障排除 `_ 获取更多信息。 -``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 开发板的 `原理图 `_。 +``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 开发板的 `原理图 `_。 -一般来说，使用官方的 ESP-IDF 开发板不会出现问题。但是， ``esptool.py`` 在以下情况下不能自动重置硬件： +一般来说，使用官方的 ESP-IDF 开发板不会出现问题。但是， ``esptool`` 在以下情况下不能自动重置硬件： - 硬件未连接到 ``{IDF_TARGET_STRAP_GPIO}`` 和 ``CIHP_PU`` 的 DTR 和 RTS 控制线。 - DTR 和 RTS 控制线的配置方式不同。 diff --git a/docs/zh_CN/get-started/start-project.rst b/docs/zh_CN/get-started/start-project.rst index bcc0ff1d8e..abc3ceed85 100644 --- a/docs/zh_CN/get-started/start-project.rst +++ b/docs/zh_CN/get-started/start-project.rst @@ -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 文件。 diff --git a/docs/zh_CN/security/flash-encryption.rst b/docs/zh_CN/security/flash-encryption.rst index fb57142778..c7cc1e84e3 100644 --- a/docs/zh_CN/security/flash-encryption.rst +++ b/docs/zh_CN/security/flash-encryption.rst @@ -13,7 +13,7 @@ flash 加密 .. note:: - 在本指南中，最常用的命令形式为 ``idf.py secure-``，这是对应 ``espsecure.py `` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure.py`` 的命令相比，可能会损失一部分高级功能。 + 在本指南中，最常用的命令形式为 ``idf.py secure-``，这是对应 ``espsecure `` 的封装。基于 ``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:`安全启动` 作为额外的保护层，防止攻击者在启动前有选择地破坏 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 diff --git a/docs/zh_CN/security/secure-boot-v1.rst b/docs/zh_CN/security/secure-boot-v1.rst index 69ee5be89d..2c8951efd7 100644 --- a/docs/zh_CN/security/secure-boot-v1.rst +++ b/docs/zh_CN/security/secure-boot-v1.rst @@ -19,7 +19,7 @@ .. note:: - 在本指南中，最常用的命令形式为 ``idf.py secure-``，这是对应 ``espsecure.py `` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure.py`` 的命令相比，可能会损失一部分高级功能。 + 在本指南中，最常用的命令形式为 ``idf.py secure-``，这是对应 ``espsecure `` 的封装。基于 ``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: diff --git a/docs/zh_CN/security/secure-boot-v2.rst b/docs/zh_CN/security/secure-boot-v2.rst index df92a801b6..62e7526e52 100644 --- a/docs/zh_CN/security/secure-boot-v2.rst +++ b/docs/zh_CN/security/secure-boot-v2.rst @@ -50,7 +50,7 @@ .. note:: - 在本指南中，最常用的命令形式为 ``idf.py secure-``，这是对应 ``espsecure.py `` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure.py`` 的命令相比，可能会损失一部分高级功能。 + 在本指南中，最常用的命令形式为 ``idf.py secure-``，这是对应 ``espsecure `` 的封装。基于 ``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 diff --git a/docs/zh_CN/security/security-features-enablement-workflows.rst b/docs/zh_CN/security/security-features-enablement-workflows.rst index d8e5e7dc01..a8363353bc 100644 --- a/docs/zh_CN/security/security-features-enablement-workflows.rst +++ b/docs/zh_CN/security/security-features-enablement-workflows.rst @@ -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 密钥的大小 ` 为 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 密钥的大小 ` 是从 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` 的更多信息，请参阅 `此文档 `__。 + 请将 ``EFUSE_NAME`` 更新为需要烧录的 eFuse。可以在上述命令中添加多个 efuse 同时进行烧录（例如：``EFUSE_NAME VAL EFUSE_NAME2 VAL2``）。有关 `espefuse` 的更多信息，请参阅 `此文档 `__。 .. 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 值 `，需要将 ``--flash_crypt_conf`` 参数传递给 ``espsecure.py`` 以设置匹配值。如果通过二级引导加载程序配置 flash 加密，则不会发生这种情况，但是如果手动烧录了 eFuses 启用 flash 加密，就有可能发生。 + 如果 ESP32 在 eFuse 中使用非默认的 :ref:`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` 的更多信息，请参阅 `此文档 `__。 + 请将 EFUSE_NAME 更新为需烧录的 eFuse。在上述命令中添加多个 eFuse 可以同时烧录（例如：EFUSE_NAME VAL EFUSE_NAME2 VAL2）。有关 `espefuse` 的更多信息，请参阅 `此文档 `__。 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 加密工作流程 `_ 的相关烧录步骤。 @@ -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 加密工作流程 `_ 中与烧录相关的步骤。 diff --git a/docs/zh_CN/security/security.rst b/docs/zh_CN/security/security.rst index d78d525e0d..69c619803a 100644 --- a/docs/zh_CN/security/security.rst +++ b/docs/zh_CN/security/security.rst @@ -11,7 +11,7 @@ .. note:: - 在本指南中，最常用的命令形式为 ``idf.py secure-``，这是对应 ``espsecure.py `` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure.py`` 的命令相比，可能会损失一部分高级功能。 + 在本指南中，最常用的命令形式为 ``idf.py secure-``，这是对应 ``espsecure `` 的封装。基于 ``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 diff --git a/examples/build_system/cmake/idf_as_lib/run-esp32.sh b/examples/build_system/cmake/idf_as_lib/run-esp32.sh index 3d9e0bfba5..c104fd10fd 100755 --- a/examples/build_system/cmake/idf_as_lib/run-esp32.sh +++ b/examples/build_system/cmake/idf_as_lib/run-esp32.sh @@ -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 diff --git a/examples/security/flash_encryption/README.md b/examples/security/flash_encryption/README.md index 7b7e05f2ab..54d524739d 100644 --- a/examples/security/flash_encryption/README.md +++ b/examples/security/flash_encryption/README.md @@ -4,11 +4,11 @@ # Flash Encryption The example demonstrates the flash encryption application by providing a code using FATFS and NVS partitions on a device with the flash encryption enabled. -As the flash encryption can be enabled either in Development or Release mode, a guidance of how to use either mode is provided. +As the flash encryption can be enabled either in Development or Release mode, a guidance of how to use either mode is provided. The example code checks if the flash encryption feature is enabled/disabled and if enabled, it prints a status information of all the eFuses related to the flash encryption mode (Development/Release) and FLASH_CRYPT_CNT (for ESP32) or SPI_BOOT_CRYPT_CNT (for ESP32-S2 and newer targets). -The example also demonstrates: +The example also demonstrates: 1. Writing and reading encrypted partitions in the flash memory. 2. Initialization of FATFS, formatting, writing and reading file. Both encrypted as well as non-encrypted. @@ -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! @@ -142,8 +142,8 @@ dd if=/dev/zero bs=1 count=0x96000 of=build/fat_encrypted.bin dd if=/dev/zero bs=1 count=0x96000 of=build/fat_not_encr.bin ``` -4. Encrypt flash artefacts on a host using flash encryption key. -First, figure out the offsets of particular artefacts in the flash memory, as it is one of the inputs to the encryption algorithm. +4. Encrypt flash artefacts on a host using flash encryption key. +First, figure out the offsets of particular artefacts in the flash memory, as it is one of the inputs to the encryption algorithm. Lookup the section listing partition table in output of the command `idf.py build` i.e. ``` Partition table binary generated. Contents: @@ -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 \ @@ -196,41 +196,41 @@ Ignore the warning `Warning: Image file at 0x1000 doesn't look like an image fil Output flash binary file is `build\merged_encrypted_flash.bin` 6. Burn the encryption key and set the efuses in ESP32-based device -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. +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! +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 ``` -9. Monitor the output, then reset the device +9. Monitor the output, then reset the device ``` 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. +For subsequent application update, only steps 4,5,8 are required. ## Example Output @@ -255,7 +255,7 @@ Reading with spi_flash_read: I (408) example: 0x3ffb4da0 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f |................| I (418) example: 0x3ffb4db0 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f |................| .... -I (509) example: FAT partition "fat_not_encr" is not encrypted. Size is (0x96000 bytes) +I (509) example: FAT partition "fat_not_encr" is not encrypted. Size is (0x96000 bytes) .... I (3429) example: Read partition using esp_flash_read until test string is found I (3649) example: 0x3ffb4f90 74 68 65 20 71 75 69 63 6b 20 62 72 6f 77 6e 20 |the quick brown | @@ -265,13 +265,13 @@ I (3669) example: Test string was found at offset (0x7000) .... I (3679) example: FAT partition "fat_encrypted" is not encrypted. Size is (0x96000 bytes) .... -I (7099) example: Read partition using esp_flash_read at expected offset (0x7000) +I (7099) example: Read partition using esp_flash_read at expected offset (0x7000) I (7099) example: 0x3ffb4f84 74 68 65 20 71 75 69 63 6b 20 62 72 6f 77 6e 20 |the quick brown | I (7099) example: 0x3ffb4f94 66 6f 78 20 6a 75 6d 70 65 64 20 6f 76 65 72 20 |fox jumped over | I (7109) example: 0x3ffb4fa4 74 68 65 20 6c 61 7a 79 20 64 6f 67 |the lazy dog| I (7119) example: Data matches test string ``` -Note: Above, the partition `fat_encrypted` has flag `encrypted` set in partition table, but it's actual state +Note: Above, the partition `fat_encrypted` has flag `encrypted` set in partition table, but it's actual state is `not encrypted` until the flash encryption is enabled in security part of menuconfig as demonstrated below. After enabling flash encryption in Development mode, the output shows the process of enabling the flash encryption: @@ -318,9 +318,9 @@ I (4083) example: 0x3ffb4fc0 66 6f 78 20 6a 75 6d 70 65 64 20 6f 76 65 72 20 I (4093) example: 0x3ffb4fd0 74 68 65 20 6c 61 7a 79 20 64 6f 67 |the lazy dog| I (4103) example: Test string was found at offset (0x7000) .... -I (4113) example: FAT partition "fat_encrypted" is encrypted. Size is (0x96000 bytes) +I (4113) example: FAT partition "fat_encrypted" is encrypted. Size is (0x96000 bytes) .... -I (8033) example: Read partition using esp_flash_read at expected offset (0x7000) +I (8033) example: Read partition using esp_flash_read at expected offset (0x7000) I (8033) example: 0x3ffb4fa4 a7 ea d5 a7 ed cf f6 f7 4a a2 54 a0 4f 92 73 7b |........J.T.O.s{| I (8043) example: 0x3ffb4fb4 63 eb 5d fc 14 b9 da 3b f2 be d0 94 de eb b2 dc |c.]....;........| I (8053) example: 0x3ffb4fc4 38 aa 14 62 b7 23 61 7d b6 34 43 53 |8..b.#a}.4CS| @@ -359,9 +359,9 @@ I (3803) example_fatfs: 0x3ffb4fd0 66 6f 78 20 6a 75 6d 70 65 64 20 6f 76 65 I (3803) example_fatfs: 0x3ffb4fe0 74 68 65 20 6c 61 7a 79 20 64 6f 67 |the lazy dog| I (3813) example_fatfs: Test string was found at offset (0x7000) .... -I (3823) example_fatfs: FAT partition "fat_encrypted" is encrypted. Size is (0x96000 bytes) +I (3823) example_fatfs: FAT partition "fat_encrypted" is encrypted. Size is (0x96000 bytes) .... -I (7303) example_fatfs: Read partition using esp_flash_read at expected offset (0x7000) +I (7303) example_fatfs: Read partition using esp_flash_read at expected offset (0x7000) I (7303) example_fatfs: 0x3ffb4fb4 3b 8f f4 e1 c1 f4 73 43 d9 28 3f 57 f3 2b d2 b0 |;.....sC.(?W.+..| I (7313) example_fatfs: 0x3ffb4fc4 41 7a 8f 09 81 1d 92 51 74 8a ee 2a c3 64 8f 75 |Az.....Qt..*.d.u| I (7323) example_fatfs: 0x3ffb4fd4 61 fe 08 b6 b4 0c cb 08 5a b8 65 29 |a.......Z.e)| @@ -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 - - diff --git a/examples/security/flash_encryption/pytest_flash_encryption.py b/examples/security/flash_encryption/pytest_flash_encryption.py index cbb32a23f4..1fe6002ff2 100644 --- a/examples/security/flash_encryption/pytest_flash_encryption.py +++ b/examples/security/flash_encryption/pytest_flash_encryption.py @@ -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)) diff --git a/examples/security/hmac_soft_jtag/README.md b/examples/security/hmac_soft_jtag/README.md index 623fd532fe..15669b0313 100644 --- a/examples/security/hmac_soft_jtag/README.md +++ b/examples/security/hmac_soft_jtag/README.md @@ -40,7 +40,7 @@ This generates a new 32-byte random HMAC key and store it in given file. **Step 3:** Run the following command to burn the eFuse with the generated HMAC key with appropriate purpose. You can use purpose either HMAC_DOWN_ALL or HMAC_DOWN_JTAG. Check efuse summary to identify an available empty key block. ```bash -espefuse.py -p $ESPPORT burn_key .bin HMAC_DOWN_ALL +espefuse -p $ESPPORT burn-key .bin HMAC_DOWN_ALL ``` **Step 4:** Generate token data from the HMAC key. Keep this token data handy before re-enabling JTAG access. @@ -76,7 +76,7 @@ See the Getting Started Guide for full steps to configure and use ESP-IDF to bui This re-enables JTAG access until the next reboot or until disabled using this example. For disabling JTAG, refer [Disable JTAG](#Disable-JTAG) -**Note:** Even upon successful return, JTAG will only be enabled with a valid token_data. +**Note:** Even upon successful return, JTAG will only be enabled with a valid token_data. ```bash enable_jtag @@ -94,7 +94,7 @@ esp32c6> enable_jtag b2a49b1cce1be922bb7e431277413e3e8e6c3e8e6e17625c50ac66a9a85 I (10974) jtag_re_enable: Device is ready to re-enable. I (10974) jtag_re_enable: Using HMAC key at block 8 with purpose HMAC_DOWN_JTAG I (10984) jtag: JTAG re-enablement workflow performed, please check the JTAG connection manually -esp32c6> +esp32c6> ``` #### Disable JTAG @@ -110,5 +110,5 @@ Console logs while disabling JTAG: ```bash esp32c6> disable_jtag I (25104) jtag_re_enable: JTAG disabled temporarily -esp32c6> +esp32c6> ``` diff --git a/examples/security/hmac_soft_jtag/jtag_example_helper.py b/examples/security/hmac_soft_jtag/jtag_example_helper.py index ad7eef2464..38babb0b06 100644 --- a/examples/security/hmac_soft_jtag/jtag_example_helper.py +++ b/examples/security/hmac_soft_jtag/jtag_example_helper.py @@ -1,4 +1,4 @@ -# 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 argparse import binascii @@ -6,10 +6,9 @@ import hashlib import hmac import os import subprocess -from typing import Optional -def generate_token_data(hmac_key_file: str, output_file: Optional[str] = None) -> None: +def generate_token_data(hmac_key_file: str, output_file: str | None = None) -> None: with open(hmac_key_file, 'rb') as file: key_data = file.read() data = bytes([0] * 32) @@ -40,10 +39,12 @@ def check_jtag_status() -> None: if not esp_port: raise RuntimeError('ESPPORT not specified') - output = subprocess.check_output(['espefuse.py', 'summary']).decode('utf-8') + output = subprocess.check_output(['espefuse', 'summary']).decode('utf-8') # check if JTAG is permenently/hard disabled - if ('DIS_PAD_JTAG' in output and 'JTAG = True' in output) or ('HARD_DIS_JTAG' in output and 'JTAG = True' in output): + if ('DIS_PAD_JTAG' in output and 'JTAG = True' in output) or ( + 'HARD_DIS_JTAG' in output and 'JTAG = True' in output + ): print('JTAG functionality is permanently disabled') else: print('JTAG functionality is not permanently disabled') @@ -67,7 +68,10 @@ def check_jtag_status() -> None: else: print('SOFT_DIS_JTAG value not found in the output') - print('If JTAG is permenently disabled, it cannot be re-enabled.\nThis example re-enables only software disabled JTAG access') + print( + 'If JTAG is permenently disabled, it cannot be re-enabled.\n' + 'This example re-enables only software disabled JTAG access' + ) def main() -> None: diff --git a/examples/security/nvs_encryption_hmac/README.md b/examples/security/nvs_encryption_hmac/README.md index 073937ccdc..88b2e14c71 100644 --- a/examples/security/nvs_encryption_hmac/README.md +++ b/examples/security/nvs_encryption_hmac/README.md @@ -28,7 +28,7 @@ The HMAC key stored at this key block will be used to generate the encryption ke ```shell # Burning the HMAC-key in eFuse block 0 - key ID 0 -espefuse.py -p PORT burn_key BLOCK_KEY0 hmac_key_file.bin HMAC_UP +espefuse -p PORT burn-key BLOCK_KEY0 hmac_key_file.bin HMAC_UP ``` ### Build and Flash diff --git a/examples/security/security_features_app/README.md b/examples/security/security_features_app/README.md index 4ca74af4a8..df0aa1b27a 100644 --- a/examples/security/security_features_app/README.md +++ b/examples/security/security_features_app/README.md @@ -213,7 +213,7 @@ Follow below steps to enable Flash Encryption: idf.py qemu --efuse-file qemu_efuse.bin efuse-burn-key BLOCK_KEY1 my_flash_encryption_key.bin XTS_AES_128_KEY ``` - + We have used `BLOCK_KEY1` here to store the Flash Encryption key. Generally, the `BLOCK` can be a free key block from `BLOCK_KE0` to `BLOCK_KEY4`. @@ -222,7 +222,7 @@ Follow below steps to enable Flash Encryption: ``` idf.py --port $ESPPORT efuse-burn SPI_BOOT_CRYPT_CNT 7 ``` - +
Enable Flash Encryption for QEMU For QEMU emulation, the above command can be updated as follows: @@ -231,7 +231,7 @@ Follow below steps to enable Flash Encryption: idf.py qemu --efuse-file qemu_efuse.bin efuse-burn SPI_BOOT_CRYPT_CNT 7 ```
- + At this point the Flash Encryption feature is enabled for the device. The necessary `security eFuses` shall be enabled by the `security_features_app` firmware. #### Encrypting the partitions @@ -317,7 +317,7 @@ We shall use the [nvs_partition_gen.py](../../../components/nvs_flash/nvs_partit idf.py qemu --efuse-file qemu_efuse.bin efuse-burn-key BLOCK_KEY2 keys/hmac_key.bin HMAC_UP ``` - + We have used `BLOCK_KEY2` here to store the HMAC key. Generally, `BLOCK` can be a free keyblock between `BLOCK_KEY0` and `BLOCK_KEY5`. If you want to change the value of the eFuse key block for this example, make sure to update the same value in `menuconfig → Component config → NVS Security Provider → eFuse key ID storing the HMAC key`. @@ -371,7 +371,7 @@ The target provides an ability to disable JTAG access in the device for the soft 3. Burn the key in the eFuse ```shell - idf.py --port $ESPPORT efuse-burn-key BLOCK_KEY3 secure_jtag_hmac_key.bin HMAC_DOWN_JTAG + idf.py --port $ESPPORT efuse-burn-key BLOCK_KEY3 secure_jtag_hmac_key.bin HMAC_DOWN_JTAG ```
@@ -439,7 +439,7 @@ The offsets at which the partitions need to be flashed can be found out by execu The partitions can be flashed with help of the `esptool` utility. ```sh -esptool.py -p $ESPPORT write_flash /* Placeholder for offset */ /* Placeholder for file name */ +esptool -p $ESPPORT write-flash /* Placeholder for offset */ /* Placeholder for file name */ ``` Along with these, esptool command may need some additional options. @@ -448,7 +448,7 @@ Please check the output of `idf.py build` command executed earlier for all the n For this example the following command can be used ```sh -esptool.py --chip -b 115200 --before default_reset --after no_reset --no-stub -p $ESPPORT write_flash 0x0 build/encrypted_data/bootloader-enc.bin 0xd000 build/encrypted_data/partition-table-enc.bin 0x20000 build/encrypted_data/security_features-enc.bin --force +esptool --chip -b 115200 --before default-reset --after no-reset --no-stub -p $ESPPORT write-flash 0x0 build/encrypted_data/bootloader-enc.bin 0xd000 build/encrypted_data/partition-table-enc.bin 0x20000 build/encrypted_data/security_features-enc.bin --force ```
diff --git a/examples/security/tee/tee_secure_storage/README.md b/examples/security/tee/tee_secure_storage/README.md index 194e22420e..0b3255d0c6 100644 --- a/examples/security/tee/tee_secure_storage/README.md +++ b/examples/security/tee/tee_secure_storage/README.md @@ -48,7 +48,7 @@ TEE Secure Storage follows the NVS partition format and uses an AES-XTS encrypti 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 diff --git a/examples/storage/perf_benchmark/README.md b/examples/storage/perf_benchmark/README.md index d18c76cbe9..07f72279bc 100644 --- a/examples/storage/perf_benchmark/README.md +++ b/examples/storage/perf_benchmark/README.md @@ -88,12 +88,12 @@ GPIO12 is used as a bootstrapping pin to select output voltage of an internal re The following command can be used to program flash voltage selection efuses **to 3.3V**: ```sh - components/esptool_py/esptool/espefuse.py set_flash_voltage 3.3V + espefuse set-flash-voltage 3.3V ``` This command will burn the `XPD_SDIO_TIEH`, `XPD_SDIO_FORCE`, and `XPD_SDIO_REG` efuses. With all three burned to value 1, the internal VDD_SDIO flash voltage regulator is permanently enabled at 3.3V. See the technical reference manual for more details. -`espefuse.py` has a `--do-not-confirm` option if running from an automated flashing script. +`espefuse` has a `--do-not-confirm` option if running from an automated flashing script. See [the document about pullup requirements](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/sd_pullup_requirements.html) for more details about pullup support and compatibility of modules and development boards. diff --git a/examples/storage/sd_card/sdmmc/README.md b/examples/storage/sd_card/sdmmc/README.md index ca074a7d18..43943d00e8 100644 --- a/examples/storage/sd_card/sdmmc/README.md +++ b/examples/storage/sd_card/sdmmc/README.md @@ -113,12 +113,12 @@ GPIO12 is used as a bootstrapping pin to select output voltage of an internal re The following command can be used to program flash voltage selection efuses **to 3.3V**: ```sh - espefuse.py set_flash_voltage 3.3V + espefuse set-flash-voltage 3.3V ``` This command will burn the `XPD_SDIO_TIEH`, `XPD_SDIO_FORCE`, and `XPD_SDIO_REG` efuses. With all three burned to value 1, the internal VDD_SDIO flash voltage regulator is permanently enabled at 3.3V. See the technical reference manual for more details. -`espefuse.py` has a `--do-not-confirm` option if running from an automated flashing script. +`espefuse` has a `--do-not-confirm` option if running from an automated flashing script. See [the document about pullup requirements](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/sd_pullup_requirements.html) for more details about pullup support and compatibility of modules and development boards. @@ -257,4 +257,4 @@ In the absence of connected pullups and having the weak pullups enabled, you can It will also provide the voltage levels at the corresponding SD pins. By default, this information is provided for ESP32 chip only, and for other chipsets, verify the availability of ADC pins for the respective GPIO using [this](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/gpio.html#gpio-summary) and configure ADC mapped pins using menuconfig. Then test the voltage levels accordingly. -You can monitor the voltage levels of individual pins using `PIN voltage levels` and `PIN voltage levels with weak pullup`. However, if one pin being pulled low and experiencing interference with another pin, you can detect it through `PIN cross-talk` and `PIN cross-talk with weak pullup`. In the absence of pullups, voltage levels at each pin should range from 0 to 0.3V. With 10k pullups connected, the voltage will be between 3.1V to 3.3V, contingent on the connection between ADC pins and SD pins, and with weak pullups connected, it can fluctuate between 0.8V to 1.2V, depending on pullup strength. \ No newline at end of file +You can monitor the voltage levels of individual pins using `PIN voltage levels` and `PIN voltage levels with weak pullup`. However, if one pin being pulled low and experiencing interference with another pin, you can detect it through `PIN cross-talk` and `PIN cross-talk with weak pullup`. In the absence of pullups, voltage levels at each pin should range from 0 to 0.3V. With 10k pullups connected, the voltage will be between 3.1V to 3.3V, contingent on the connection between ADC pins and SD pins, and with weak pullups connected, it can fluctuate between 0.8V to 1.2V, depending on pullup strength. diff --git a/examples/storage/sd_card/sdspi/README.md b/examples/storage/sd_card/sdspi/README.md index efca4a4c37..0386e4d1f7 100644 --- a/examples/storage/sd_card/sdspi/README.md +++ b/examples/storage/sd_card/sdspi/README.md @@ -74,8 +74,8 @@ Default pins for SDSPI are listed in the table above [Pin assignments](#1-pin-as However on some development boards the SD card slot can be wired to default dedicated pins for SDMMC, which are listed in the table below. -SD card pin | ESP32-P4 pin -------------|-------------- +SD card pin | ESP32-P4 pin +------------|-------------- D0 (MISO) | GPIO39 D3 (CS) | GPIO42 CLK (SCK) | GPIO43 @@ -160,7 +160,7 @@ Check you board documentation/schematics for appropriate procedure. An attempt to download a new firmware under this conditions may also result in the board's serial port disappearing from your PC device list - rebooting your computer should fix the issue. After your device is back, use -`esptool.py --port PORT --before no_reset --baud 115200 --chip esp32 erase_flash` +`esptool --port PORT --before no-reset --baud 115200 --chip esp32 erase-flash` to erase your board's flash, then flash the firmware again. diff --git a/examples/system/efuse/README.md b/examples/system/efuse/README.md index 4e24ad1c18..9641ed8fd6 100644 --- a/examples/system/efuse/README.md +++ b/examples/system/efuse/README.md @@ -37,32 +37,29 @@ CUSTOM_SECURE_VERSION, EFUSE_BLK3, 78, 16, Custom secure versio To run this example, you need to use the ESP32 developer board. If your ESP32 has the `None` coding scheme of eFuse, then write and read operations have no limitations. But if it has the `3/4` or `RS` coding scheme, the writing may lead to an error due to the fact that some coded value was written earlier. A simple way to find out what coding scheme your chip has, you can see in the log while esptool is working or the log of the program: ``` -esptool.py v2.7-dev -Serial port /dev/ttyUSB0 -Connecting........_____.....__ -Detecting chip type... ESP32 -Chip is ESP32-PICO-D4 (revision 1) -Features: WiFi, BT, Dual Core, Embedded Flash, Coding Scheme None -MAC: d8:a0:1d:40:ac:90 +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: d8:a0:1d:40:ac:90 ``` -The esptool also has a command to get general information about the chip `esptool.py chip_id`: +The esptool also has a command to get general information about the chip `esptool chip-id`: ``` -esptool.py v2.8-dev -Found 1 serial ports -Serial port /dev/ttyUSB0 -Connecting........_ -Detecting chip type... ESP32 -Chip is ESP32-PICO-D4 (revision 1) -Features: WiFi, BT, Dual Core, Embedded Flash, Coding Scheme None -Crystal is 40MHz -MAC: d8:a0:1d:40:ac:90 -Uploading stub... -Running stub... -Stub running... -Warning: ESP32 has no Chip ID. Reading MAC instead. -MAC: d8:a0:1d:40:ac:90 +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: d8:a0:1d:40:ac:90 + +Stub flasher running. + +Warning: ESP32 has no chip ID. Reading MAC address instead. +MAC: d8:a0:1d:40:ac:90 + Hard resetting via RTS pin... ``` diff --git a/examples/system/ota/otatool/get_running_partition.py b/examples/system/ota/otatool/get_running_partition.py index 5a05fca8ac..333224086d 100644 --- a/examples/system/ota/otatool/get_running_partition.py +++ b/examples/system/ota/otatool/get_running_partition.py @@ -3,7 +3,7 @@ # Demonstrates the use of otatool.py, a tool for performing ota partition level # operations. # -# SPDX-FileCopyrightText: 2018-2022 Espressif Systems (Shanghai) CO LTD +# SPDX-FileCopyrightText: 2018-2025 Espressif Systems (Shanghai) CO LTD # SPDX-License-Identifier: Apache-2.0 import argparse import os @@ -13,31 +13,22 @@ import sys from subprocess import CalledProcessError import serial +from esptool.loader import ESPLoader def get_running_partition(port=None): # Monitor the serial output of target device. The firmware outputs the currently # running partition - IDF_PATH = os.path.expandvars('$IDF_PATH') - sys.path.append(os.path.join(IDF_PATH, 'components', 'esptool_py', 'esptool')) - - try: - # esptool>=4.0 - from esptool.loader import ESPLoader - except (AttributeError, ModuleNotFoundError): - # esptool<4.0 - from esptool import ESPLoader - - ESPTOOL_PY = os.path.join(IDF_PATH, 'components', 'esptool_py', 'esptool', 'esptool.py') - baud = os.environ.get('ESPTOOL_BAUD', ESPLoader.ESP_ROM_BAUD) if not port: error_message = 'Unable to obtain default target device port.\nSerial log:\n\n' try: - # Check what esptool.py finds on what port the device is connected to - output = subprocess.check_output([sys.executable, ESPTOOL_PY, 'chip_id']) # may raise CalledProcessError + # Check what esptool finds on what port the device is connected to + output = subprocess.check_output( + [sys.executable, '-m', 'esptool', 'chip-id'] + ) # may raise CalledProcessError pattern = r'Serial port ([^:\s]+)' pattern = re.compile(pattern.encode()) diff --git a/examples/wifi/wifi_nvs_config/README.md b/examples/wifi/wifi_nvs_config/README.md index ccab6ce2cd..830af736e3 100644 --- a/examples/wifi/wifi_nvs_config/README.md +++ b/examples/wifi/wifi_nvs_config/README.md @@ -43,7 +43,7 @@ python nvs_partition_gen.py generate nvs_station_data.csv sample_nvs.bin 0x6000 ### 3) Flash the NVS Binary File to the ESP Device - Check the offset of the NVS partition in the `partition_example.csv` file. -- After flashing the build, flash the `sample_nvs.bin` file to the ESP device at the specified offset using `esptool.py`. +- After flashing the build, flash the `sample_nvs.bin` file to the ESP device at the specified offset using `esptool`. - Refer to the [Esptool Documentation](https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/index.html) for detailed usage. ### 4) Build and Flash diff --git a/tools/ci/ignore_build_warnings.txt b/tools/ci/ignore_build_warnings.txt index 81c42ae5fb..dddea3463f 100644 --- a/tools/ci/ignore_build_warnings.txt +++ b/tools/ci/ignore_build_warnings.txt @@ -39,8 +39,3 @@ warning: unknown kconfig symbol 'UNITY_FREERTOS_STACK_SIZE' assigned to '12288' warning: unknown kconfig symbol 'WPA3_SAE' assigned to 'y' in .*/components/wpa_supplicant/test_apps/sdkconfig.defaults ld: warning: ignoring duplicate libraries archive library: .+ the table of contents is empty -Warning: Deprecated: Option '--flash_size' is deprecated. Use '--flash-size' instead. -Warning: Deprecated: Option '--flash_mode' is deprecated. Use '--flash-mode' instead. -Warning: Deprecated: Option '--flash_freq' is deprecated. Use '--flash-freq' instead. -Warning: Deprecated: Command 'sign_data' is deprecated. Use 'sign-data' instead. -Warning: Deprecated: Command 'extract_public_key' is deprecated. Use 'extract-public-key' instead. diff --git a/tools/cmake/build.cmake b/tools/cmake/build.cmake index e87ec1f6e0..fc4af4b86e 100644 --- a/tools/cmake/build.cmake +++ b/tools/cmake/build.cmake @@ -777,7 +777,7 @@ macro(idf_build_process target) idf_build_set_property(COMPILE_DEFINITIONS "ESP_PLATFORM" APPEND) # Create flash targets early so components can attach images to them. - # These targets will be appended with actual esptool.py command later + # These targets will be appended with actual esptool command later # in the build process when __idf_build_setup_flash_targets() is called. if(NOT BOOTLOADER_BUILD AND NOT ESP_TEE_BUILD AND NOT "${target}" STREQUAL "linux") __build_create_flash_targets() @@ -875,7 +875,7 @@ function(idf_build_executable elf) # Setup flash targets and flash configuration __idf_build_setup_flash_targets() - # Setup utility targets such as monitor, erase_flash, merge-bin + # Setup utility targets such as monitor, erase-flash, merge-bin __esptool_py_setup_utility_targets() # Setup post-build validation checks diff --git a/tools/cmake/flash_targets.cmake b/tools/cmake/flash_targets.cmake index 942a5bf671..fa5795be02 100644 --- a/tools/cmake/flash_targets.cmake +++ b/tools/cmake/flash_targets.cmake @@ -36,8 +36,9 @@ function(__idf_build_generate_flasher_args) idf_build_get_property(target IDF_TARGET) set(ESPTOOLPY_CHIP "${target}") - set(ESPTOOLPY_BEFORE "${CONFIG_ESPTOOLPY_BEFORE}") - set(ESPTOOLPY_AFTER "${CONFIG_ESPTOOLPY_AFTER}") + # Hyphenate reset modes for esptool v5 + string(REPLACE "_" "-" ESPTOOLPY_BEFORE "${CONFIG_ESPTOOLPY_BEFORE}") + string(REPLACE "_" "-" ESPTOOLPY_AFTER "${CONFIG_ESPTOOLPY_AFTER}") if(CONFIG_ESPTOOLPY_NO_STUB) set(ESPTOOLPY_WITH_STUB false) else() @@ -46,7 +47,7 @@ function(__idf_build_generate_flasher_args) if(CONFIG_SECURE_BOOT OR CONFIG_SECURE_FLASH_ENC_ENABLED) # If security enabled then override post flash option - set(ESPTOOLPY_AFTER "no_reset") + set(ESPTOOLPY_AFTER "no-reset") endif() idf_component_get_property(ESPFLASHMODE esptool_py ESPFLASHMODE) diff --git a/tools/export_utils/shell_types.py b/tools/export_utils/shell_types.py index d14e3a57c1..331c20a1a0 100644 --- a/tools/export_utils/shell_types.py +++ b/tools/export_utils/shell_types.py @@ -238,12 +238,13 @@ class PowerShell(Shell): self.new_esp_idf_env['IDF_TOOLS_EXPORT_CMD'] = os.path.join(conf.IDF_PATH, 'export.ps1') def get_functions(self) -> str: + ESPTOOL_WRAPPERS = r'$Env:IDF_PATH\components\esptool_py\esptool' return '\n'.join( [ r'function idf.py { &python "$Env:IDF_PATH\tools\idf.py" $args }', - r'function global:esptool.py { &python -m esptool $args }', - r'function global:espefuse.py { &python -m espefuse $args }', - r'function global:espsecure.py { &python -m espsecure $args }', + rf'function global:esptool.py {{ &python "{ESPTOOL_WRAPPERS}\esptool.py" $args }}', + rf'function global:espefuse.py {{ &python "{ESPTOOL_WRAPPERS}\espefuse.py" $args }}', + rf'function global:espsecure.py {{ &python "{ESPTOOL_WRAPPERS}\espsecure.py" $args }}', r'function global:otatool.py { &python "$Env:IDF_PATH\components\app_update\otatool.py" $args }', r'function global:parttool.py { &python "$Env:IDF_PATH\components\partition_table\parttool.py" $args }', ] @@ -294,9 +295,9 @@ class WinCmd(Shell): return '\n'.join( [ r'DOSKEY idf.py=python.exe "%IDF_PATH%\tools\idf.py" $*', - r'DOSKEY esptool.py=python.exe -m esptool $*', - r'DOSKEY espefuse.py=python.exe -m espefuse $*', - r'DOSKEY espsecure.py=python.exe -m espsecure $*', + r'DOSKEY esptool.py=python.exe "%IDF_PATH%\components\esptool_py\esptool\esptool.py" $*', + r'DOSKEY espefuse.py=python.exe "%IDF_PATH%\components\esptool_py\esptool\espefuse.py" $*', + r'DOSKEY espsecure.py=python.exe "%IDF_PATH%\components\esptool_py\esptool\espsecure.py" $*', r'DOSKEY otatool.py=python.exe "%IDF_PATH%\components\app_update\otatool.py" $*', r'DOSKEY parttool.py=python.exe "%IDF_PATH%\components\partition_table\parttool.py" $*', ] diff --git a/tools/idf.py b/tools/idf.py index bba0590599..6ab1d6a983 100755 --- a/tools/idf.py +++ b/tools/idf.py @@ -586,7 +586,7 @@ def init_cli(verbose_output: list | None = None) -> Any: if args.port: esptool_cmd += [f'-p {args.port}'] - esptool_cmd += ['write_flash'] + esptool_cmd += ['write-flash'] print('or') print(' {}'.format(' '.join(esptool_cmd + [cmd.strip()]))) diff --git a/tools/idf_py_actions/qemu_ext.py b/tools/idf_py_actions/qemu_ext.py index 98c84d9538..680d361cd5 100644 --- a/tools/idf_py_actions/qemu_ext.py +++ b/tools/idf_py_actions/qemu_ext.py @@ -207,7 +207,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: for task in tasks: if fnmatch.fnmatch(task.name, 'efuse-*'): if 'before' in task.action_args.keys(): - task.action_args['before'] = 'no_reset' + task.action_args['before'] = 'no-reset' def _get_project_desc(args: PropertyDict, ctx: Context) -> Any: desc_path = os.path.join(args.build_dir, 'project_description.json') @@ -263,9 +263,9 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: '-m', 'esptool', f'--chip={target}', - 'merge_bin', + 'merge-bin', f'--output={bin_path}', - f'--fill-flash-size={flash_size}', + f'--pad-to-size={flash_size}', '@flash_args', ], cwd=args.build_dir, diff --git a/tools/idf_py_actions/serial_ext.py b/tools/idf_py_actions/serial_ext.py index 09692ce077..d1b5f47fb9 100644 --- a/tools/idf_py_actions/serial_ext.py +++ b/tools/idf_py_actions/serial_ext.py @@ -59,14 +59,15 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: return project_desc def _get_esptool_args(args: PropertyDict) -> list: - esptool_path = os.path.join(os.environ['IDF_PATH'], 'components/esptool_py/esptool/esptool.py') esptool_wrapper_path = os.environ.get('ESPTOOL_WRAPPER', '') if args.port is None: args.port = get_default_serial_port() result = [PYTHON] if os.path.exists(esptool_wrapper_path): result += [esptool_wrapper_path] - result += [esptool_path] + else: + result += ['-m'] + result += ['esptool'] result += ['-p', args.port] result += ['-b', str(args.baud)] @@ -74,8 +75,9 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: flasher_args = json.load(f) extra_esptool_args = flasher_args['extra_esptool_args'] - result += ['--before', extra_esptool_args['before']] - result += ['--after', extra_esptool_args['after']] + # esptool v5 expects hyphenated reset modes + result += ['--before', extra_esptool_args['before'].replace('_', '-')] + result += ['--after', extra_esptool_args['after'].replace('_', '-')] result += ['--chip', extra_esptool_args['chip']] if not extra_esptool_args['stub']: result += ['--no-stub'] @@ -236,13 +238,13 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: 'SERIAL_TOOL_EXTRA_PRE_CMD_ARGS': ';'.join(extra_pre), 'SERIAL_TOOL_EXTRA_ARGS': ';'.join(extra_post), } - run_target(action, args, env, force_progression=True) + run_target(action, args, env, force_progression=True, interactive=True) def erase_flash(action: str, ctx: click.core.Context, args: PropertyDict) -> None: ensure_build_directory(args, ctx.info_name) esptool_args = _get_esptool_args(args) - esptool_args += ['erase_flash'] - RunTool('esptool.py', esptool_args, args.build_dir, hints=not args.no_hints)() + esptool_args += ['erase-flash'] + RunTool('esptool', esptool_args, args.build_dir, hints=not args.no_hints, interactive=True)() def global_callback(ctx: click.core.Context, global_args: dict, tasks: PropertyDict) -> None: encryption = any([task.name in ('encrypted-flash', 'encrypted-app-flash') for task in tasks]) @@ -261,7 +263,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: """ args.port = args.port or get_default_serial_port() ensure_build_directory(args, ctx.info_name) - run_target(target_name, args, {'ESPBAUD': str(args.baud), 'ESPPORT': args.port}) + run_target(target_name, args, {'ESPBAUD': str(args.baud), 'ESPPORT': args.port}, interactive=True) def merge_bin( action: str, @@ -271,15 +273,16 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: format: str, # noqa: A002 md5_disable: str, flash_offset: str, - fill_flash_size: str, + pad_to_size: str, merge_args: tuple[str], + fill_flash_size: str = '', ) -> None: ensure_build_directory(args, ctx.info_name) project_desc = _get_project_desc(ctx, args) merge_bin_args = [PYTHON, '-m', 'esptool'] target = project_desc['target'] merge_bin_args += ['--chip', target] - merge_bin_args += ['merge_bin'] # needs to be after the --chip option + merge_bin_args += ['merge-bin'] # needs to be after the --chip option if not output: if format in ('raw', 'uf2'): output = 'merged-binary.bin' @@ -298,19 +301,17 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: yellow_print('idf.py merge-bin: --flash-offset is only valid for RAW format. Option will be ignored.') else: merge_bin_args += ['-t', flash_offset] - if fill_flash_size: + if pad_to_size or fill_flash_size: if format != 'raw': - yellow_print( - 'idf.py merge-bin: --fill-flash-size is only valid for RAW format, option will be ignored.' - ) + yellow_print('idf.py merge-bin: --pad-to-size is only valid for RAW format, option will be ignored.') else: - merge_bin_args += ['--fill-flash-size', fill_flash_size] + merge_bin_args += ['--pad-to-size', pad_to_size or fill_flash_size] if merge_args: merge_bin_args += list(merge_args) else: merge_bin_args += ['@flash_args'] print(f'Merged binary {output} will be created in the build directory...') - RunTool('merge_bin', merge_bin_args, args.build_dir, build_dir=args.build_dir, hints=not args.no_hints)() + RunTool('merge-bin', merge_bin_args, args.build_dir, build_dir=args.build_dir, hints=not args.no_hints)() def secure_decrypt_flash_data( action: str, @@ -324,9 +325,9 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: **extra_args: str, ) -> None: ensure_build_directory(args, ctx.info_name) - decrypt_flash_data_args = [PYTHON, '-m', 'espsecure', 'decrypt_flash_data'] + decrypt_flash_data_args = [PYTHON, '-m', 'espsecure', 'decrypt-flash-data'] if aes_xts: - decrypt_flash_data_args += ['--aes_xts'] + decrypt_flash_data_args += ['--aes-xts'] if keyfile: decrypt_flash_data_args += ['--keyfile', keyfile] if output: @@ -334,7 +335,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: if address: decrypt_flash_data_args += ['--address', address] if flash_crypt_conf: - decrypt_flash_data_args += ['--flash_crypt_conf', flash_crypt_conf] + decrypt_flash_data_args += ['--flash-crypt-conf', flash_crypt_conf] if extra_args['encrypted_file']: decrypt_flash_data_args += [extra_args['encrypted_file']] RunTool('espsecure', decrypt_flash_data_args, args.build_dir)() @@ -343,7 +344,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: action: str, ctx: click.core.Context, args: PropertyDict, keyfile: str, output: str, iv: str, **extra_args: str ) -> None: ensure_build_directory(args, ctx.info_name) - digest_secure_bootloader_args = [PYTHON, '-m', 'espsecure', 'digest_secure_bootloader'] + digest_secure_bootloader_args = [PYTHON, '-m', 'espsecure', 'digest-secure-bootloader'] if keyfile: digest_secure_bootloader_args += ['--keyfile', keyfile] if output: @@ -366,9 +367,9 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: **extra_args: str, ) -> None: ensure_build_directory(args, ctx.info_name) - encrypt_flash_data_args = [PYTHON, '-m', 'espsecure', 'encrypt_flash_data'] + encrypt_flash_data_args = [PYTHON, '-m', 'espsecure', 'encrypt-flash-data'] if aes_xts: - encrypt_flash_data_args += ['--aes_xts'] + encrypt_flash_data_args += ['--aes-xts'] if keyfile: encrypt_flash_data_args += ['--keyfile', keyfile] if output: @@ -376,7 +377,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: if address: encrypt_flash_data_args += ['--address', address] if flash_crypt_conf: - encrypt_flash_data_args += ['--flash_crypt_conf', flash_crypt_conf] + encrypt_flash_data_args += ['--flash-crypt-conf', flash_crypt_conf] if extra_args['plaintext_file']: encrypt_flash_data_args += [extra_args['plaintext_file']] RunTool('espsecure', encrypt_flash_data_args, args.build_dir)() @@ -385,7 +386,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: action: str, ctx: click.core.Context, args: PropertyDict, keylen: str, **extra_args: str ) -> None: ensure_build_directory(args, ctx.info_name) - generate_flash_encryption_key_args = [PYTHON, '-m', 'espsecure', 'generate_flash_encryption_key'] + generate_flash_encryption_key_args = [PYTHON, '-m', 'espsecure', 'generate-flash-encryption-key'] if keylen: generate_flash_encryption_key_args += ['--keylen', keylen] if extra_args['keyfile']: @@ -396,7 +397,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: action: str, ctx: click.core.Context, args: PropertyDict, version: str, scheme: str, **extra_args: str ) -> None: ensure_build_directory(args, ctx.info_name) - generate_signing_key_args = [PYTHON, '-m', 'espsecure', 'generate_signing_key'] + generate_signing_key_args = [PYTHON, '-m', 'espsecure', 'generate-signing-key'] project_desc = _get_project_desc(ctx, args) ecdsa_scheme = get_sdkconfig_value(project_desc['config_file'], 'CONFIG_SECURE_SIGNED_APPS_ECDSA_SCHEME') ecdsa_v2_scheme = get_sdkconfig_value(project_desc['config_file'], 'CONFIG_SECURE_SIGNED_APPS_ECDSA_V2_SCHEME') @@ -417,7 +418,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: action: str, ctx: click.core.Context, args: PropertyDict, keyfile: str, output: str, **extra_args: str ) -> None: ensure_build_directory(args, ctx.info_name) - generate_key_digest_args = [PYTHON, '-m', 'espsecure', 'digest_sbv2_public_key'] + generate_key_digest_args = [PYTHON, '-m', 'espsecure', 'digest-sbv2-public-key'] if keyfile: generate_key_digest_args += ['--keyfile', keyfile] if output: @@ -437,13 +438,13 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: **extra_args: str, ) -> None: ensure_build_directory(args, ctx.info_name) - sign_data_args = [PYTHON, '-m', 'espsecure', 'sign_data'] + sign_data_args = [PYTHON, '-m', 'espsecure', 'sign-data'] if version: sign_data_args += ['--version', version] if keyfile: sign_data_args += ['--keyfile', keyfile] if append_signatures: - sign_data_args += ['--append_signatures'] + sign_data_args += ['--append-signatures'] if pub_key: sign_data_args += ['--pub-key', pub_key] if signature: @@ -458,7 +459,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: action: str, ctx: click.core.Context, args: PropertyDict, version: str, keyfile: str, **extra_args: str ) -> None: ensure_build_directory(args, ctx.info_name) - verify_signature_args = [PYTHON, '-m', 'espsecure', 'verify_signature'] + verify_signature_args = [PYTHON, '-m', 'espsecure', 'verify-signature'] if version: verify_signature_args += ['--version', version] if keyfile: @@ -510,7 +511,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: if extra_args['virt']: efuse_args += ['--virt'] if extra_args['before']: - efuse_args += ['--before', extra_args['before'].replace('-', '_')] + efuse_args += ['--before', extra_args['before']] if extra_args['debug']: efuse_args += ['--debug'] if extra_args['do_not_confirm']: @@ -521,7 +522,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: ensure_build_directory(args, ctx.info_name) burn_efuse_args = [PYTHON, '-m', 'espefuse'] burn_efuse_args += _parse_efuse_args(ctx, args, extra_args) - burn_efuse_args.append('burn_efuse') + burn_efuse_args.append('burn-efuse') if extra_args['efuse_positional_args']: burn_efuse_args += list(extra_args['efuse_positional_args']) RunTool('espefuse', burn_efuse_args, args.build_dir)() @@ -530,7 +531,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: ensure_build_directory(args, ctx.info_name) burn_key_args = [PYTHON, '-m', 'espefuse'] burn_key_args += _parse_efuse_args(ctx, args, extra_args) - burn_key_args.append('burn_key') + burn_key_args.append('burn-key') if extra_args['no_protect_key']: burn_key_args += ['--no-protect-key'] if extra_args['force_write_always']: @@ -539,7 +540,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: burn_key_args += ['--show-sensitive-info'] if extra_args['efuse_positional_args']: burn_key_args += extra_args['efuse_positional_args'] - RunTool('espefuse.py', burn_key_args, args.project_dir, build_dir=args.build_dir)() + RunTool('espefuse', burn_key_args, args.project_dir, build_dir=args.build_dir)() def efuse_dump( action: str, ctx: click.core.Context, args: PropertyDict, file_name: str, **extra_args: dict @@ -549,14 +550,14 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: dump_args += _parse_efuse_args(ctx, args, extra_args) dump_args.append('dump') if file_name: - dump_args += ['--file_name', file_name] + dump_args += ['--file-name', file_name] RunTool('espefuse', dump_args, args.build_dir)() def efuse_read_protect(action: str, ctx: click.core.Context, args: PropertyDict, **extra_args: dict) -> None: ensure_build_directory(args, ctx.info_name) read_protect_args = [PYTHON, '-m', 'espefuse'] read_protect_args += _parse_efuse_args(ctx, args, extra_args) - read_protect_args.append('read_protect_efuse') + read_protect_args.append('read-protect-efuse') if extra_args['efuse_positional_args']: read_protect_args += list(extra_args['efuse_positional_args']) RunTool('espefuse', read_protect_args, args.build_dir)() @@ -582,7 +583,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: ensure_build_directory(args, ctx.info_name) write_protect_args = [PYTHON, '-m', 'espefuse'] write_protect_args += _parse_efuse_args(ctx, args, extra_args) - write_protect_args.append('write_protect_efuse') + write_protect_args.append('write-protect-efuse') if extra_args['efuse_positional_args']: write_protect_args += list(extra_args['efuse_positional_args']) RunTool('espefuse', write_protect_args, args.build_dir)() @@ -603,8 +604,8 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: 'names': ['--extra-args'], 'help': ( 'Pass extra arguments to esptool separated by space. For more details see ' - '`esptool.py write_flash --help`. For example to compress and verify data use: ' - '`idf.py flash --extra-args="--compress --verify"`. Use with caution!' + '`esptool write-flash --help`. For example to compress and (auto-)verify use: ' + '`idf.py flash --extra-args="--compress"`. Use with caution!' ), }, ] @@ -683,6 +684,17 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: }, { 'names': ['--fill-flash-size'], + 'deprecated': { + 'since': 'v6.0', + 'message': 'Did you want to use "--pad-to-size" instead?', + }, + 'hidden': True, + 'type': click.Choice( + ['256KB', '512KB', '1MB', '2MB', '4MB', '8MB', '16MB', '32MB', '64MB', '128MB'] + ), + }, + { + 'names': ['--pad-to-size'], 'help': ( '[ONLY RAW] If set, the final binary file will be padded with FF bytes up to this ' 'flash size.' @@ -1031,7 +1043,7 @@ def action_extensions(base_actions: dict, project_path: str) -> dict: 'names': ['--file-name'], 'help': ( 'Saves dump for each block into separate file. Provide the common path name /path/blk.bin, ' - 'it will create: blk0.bin, blk1.bin ... blkN.bin. Use burn_block_data to write it back to ' + 'it will create: blk0.bin, blk1.bin ... blkN.bin. Use burn-block-data to write it back to ' 'another chip.' ), }, diff --git a/tools/ldgen/samples/sdkconfig b/tools/ldgen/samples/sdkconfig index dd9a47e81a..8ec30824f5 100644 --- a/tools/ldgen/samples/sdkconfig +++ b/tools/ldgen/samples/sdkconfig @@ -44,10 +44,10 @@ CONFIG_ESPTOOLPY_FLASHSIZE="2MB" CONFIG_ESPTOOLPY_FLASHSIZE_DETECT=y CONFIG_ESPTOOLPY_BEFORE_RESET=y CONFIG_ESPTOOLPY_BEFORE_NORESET= -CONFIG_ESPTOOLPY_BEFORE="default_reset" +CONFIG_ESPTOOLPY_BEFORE="default-reset" CONFIG_ESPTOOLPY_AFTER_RESET=y CONFIG_ESPTOOLPY_AFTER_NORESET= -CONFIG_ESPTOOLPY_AFTER="hard_reset" +CONFIG_ESPTOOLPY_AFTER="hard-reset" CONFIG_ESPTOOLPY_MONITOR_BAUD_9600B= CONFIG_ESPTOOLPY_MONITOR_BAUD_57600B= CONFIG_ESPTOOLPY_MONITOR_BAUD_115200B=y diff --git a/tools/mass_mfg/docs/README.rst b/tools/mass_mfg/docs/README.rst index 42b3a91280..2e3b65b3be 100644 --- a/tools/mass_mfg/docs/README.rst +++ b/tools/mass_mfg/docs/README.rst @@ -10,7 +10,7 @@ This utility is designed to create instances of factory NVS partition images on Please note that this utility only creates manufacturing binary images which then need to be flashed onto your devices using: -- `esptool.py`_ +- `esptool`_ - `Flash Download tool `_ (available on Windows only) - Download and unzip it, and follow the instructions inside the *doc* folder. - Direct flash programming using custom production tools. @@ -304,4 +304,4 @@ While running the manufacturing utility, the following folders will be created i - ``csv/`` for storing the generated intermediate CSV files - ``keys/`` for storing encryption keys (when generating encrypted factory images) -.. _esptool.py: https://github.com/espressif/esptool/#readme +.. _esptool: https://github.com/espressif/esptool/#readme diff --git a/tools/mass_mfg/docs/README_CN.rst b/tools/mass_mfg/docs/README_CN.rst index cee900f122..9f1c8f3081 100644 --- a/tools/mass_mfg/docs/README_CN.rst +++ b/tools/mass_mfg/docs/README_CN.rst @@ -10,7 +10,7 @@ 注意，该程序仅创建用于量产的二进制镜像，您需要使用以下工具将镜像烧录到设备上： -- `esptool.py`_ +- `esptool`_ - `Flash 下载工具 `_ （仅适用于 Windows）。下载后解压，然后按照 doc 文件夹中的说明操作。 - 使用定制的生产工具直接烧录程序 @@ -252,4 +252,4 @@ CSV 配置文件示例如下:: - ``csv/`` 存储生成的中间 CSV 文件 - ``keys/`` 存储加密密钥（创建工厂加密镜像时会用到） -.. _esptool.py: https://github.com/espressif/esptool/#readme +.. _esptool: https://github.com/espressif/esptool/#readme diff --git a/tools/mkdfu.py b/tools/mkdfu.py index aac138c7a3..725ad994af 100755 --- a/tools/mkdfu.py +++ b/tools/mkdfu.py @@ -59,7 +59,7 @@ def make_cpio_header(filename_len, file_len, is_trailer=False): # type: (int, i """Returns CPIOHeader for the given file name and file size""" def as_hex(val): # type: (int) -> bytes - return '{:08x}'.format(val).encode('ascii') + return f'{val:08x}'.encode('ascii') hex_0 = as_hex(0) mode = hex_0 if is_trailer else as_hex(0o0100644) @@ -135,10 +135,10 @@ def flash_size_bytes(size): # type: (str) -> int try: return int(size.rstrip('MB'), 10) * 1024 * 1024 except ValueError: - raise argparse.ArgumentTypeError('Unknown size {}'.format(size)) + raise argparse.ArgumentTypeError(f'Unknown size {size}') -class EspDfuWriter(object): +class EspDfuWriter: def __init__(self, dest_file, pid, part_size): # type: (typing.BinaryIO, int, int) -> None self.dest = dest_file self.pid = pid @@ -153,7 +153,7 @@ class EspDfuWriter(object): Corresponds to the "flashchip" data structure that the ROM has in RAM. - See flash_set_parameters() in esptool.py for more info + See flash_set_parameters() in esptool for more info """ flash_params = FlashParamsData( ishspi=0, @@ -238,7 +238,7 @@ def action_write(args): # type: (typing.Mapping[str, typing.Any]) -> None print('Adding flash chip parameters file with flash_size = {}'.format(args['flash_size'])) writer.add_flash_params_file(args['flash_size']) for addr, f in args['files']: - print('Adding {} at {:#x}'.format(f, addr)) + print(f'Adding {f} at {addr:#x}') writer.add_file(addr, f) writer.finish() print('"{}" has been written. You may proceed with DFU flashing.'.format(args['output_file'].name)) @@ -284,7 +284,7 @@ def main(): # type: () -> None def check_file(file_name): # type: (str) -> str if not os.path.isfile(file_name): - raise RuntimeError('{} is not a regular file!'.format(file_name)) + raise RuntimeError(f'{file_name} is not a regular file!') return file_name files = [] diff --git a/tools/mkuf2.py b/tools/mkuf2.py index 90e8572cba..ff2cc95262 100755 --- a/tools/mkuf2.py +++ b/tools/mkuf2.py @@ -1,6 +1,6 @@ #!/usr/bin/env python # -# SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD +# SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD # SPDX-License-Identifier: Apache-2.0 # Module was moved to the esptool in ESP-IDF v5.2 and relicensed under GPL v2.0 license. import argparse @@ -8,8 +8,6 @@ import json import os import subprocess import sys -from typing import List -from typing import Tuple def main() -> None: @@ -20,14 +18,14 @@ def main() -> None: print("DEPRECATED option '--chip-id'. Please consider using '--chip' instead") # DO NOT add new IDs; they are now maintained in esptool. ids = { - 0x1c5f21b0: 'esp32', - 0xbfdd4eee: 'esp32s2', - 0xd42ba06c: 'esp32c3', - 0xc47e5767: 'esp32s3', - 0x332726f6: 'esp32h2', - 0x2b88d29c: 'esp32c2', - 0x540ddf62: 'esp32c6', - 0x3d308e94: 'esp32p4', + 0x1C5F21B0: 'esp32', + 0xBFDD4EEE: 'esp32s2', + 0xD42BA06C: 'esp32c3', + 0xC47E5767: 'esp32s3', + 0x332726F6: 'esp32h2', + 0x2B88D29C: 'esp32c2', + 0x540DDF62: 'esp32c6', + 0x3D308E94: 'esp32p4', } try: return ids[int(string, 16)] @@ -37,44 +35,40 @@ def main() -> None: # Provision to add "info" command subparsers = parser.add_subparsers(dest='command') write_parser = subparsers.add_parser('write') - write_parser.add_argument('-o', '--output-file', - help='Filename for storing the output UF2 image', - required=True) + write_parser.add_argument('-o', '--output-file', help='Filename for storing the output UF2 image', required=True) group = write_parser.add_mutually_exclusive_group(required=True) # chip-id used just for backwards compatibility, UF2 family IDs are now stored in esptool - group.add_argument('--chip-id', - type=parse_chip_id, - help=argparse.SUPPRESS) - group.add_argument('--chip', - type=str, - help='Target chip type') - write_parser.add_argument('--chunk-size', - required=False, - type=int, - default=None, - help='Specify the used data part of the 512 byte UF2 block. A common value is 256. By ' - 'default the largest possible value will be used.') - write_parser.add_argument('--json', - help='Optional file for loading "flash_files" dictionary with
items') - write_parser.add_argument('--bin', - help='Use only a subset of binaries from the JSON file, e.g. "partition_table ' - 'bootloader app"', - nargs='*') - write_parser.add_argument('--md5-disable', - help='Disable MD5 checksum. Useful for compatibility with e.g. TinyUF2', - action='store_true') - write_parser.add_argument('files', - metavar='
', help='Add at
', - nargs='*') + group.add_argument('--chip-id', type=parse_chip_id, help=argparse.SUPPRESS) + group.add_argument('--chip', type=str, help='Target chip type') + write_parser.add_argument( + '--chunk-size', + required=False, + type=int, + default=None, + help='Specify the used data part of the 512 byte UF2 block. A common value is 256. By ' + 'default the largest possible value will be used.', + ) + write_parser.add_argument( + '--json', help='Optional file for loading "flash_files" dictionary with
items' + ) + write_parser.add_argument( + '--bin', + help='Use only a subset of binaries from the JSON file, e.g. "partition_table bootloader app"', + nargs='*', + ) + write_parser.add_argument( + '--md5-disable', help='Disable MD5 checksum. Useful for compatibility with e.g. TinyUF2', action='store_true' + ) + write_parser.add_argument('files', metavar='
', help='Add at
', nargs='*') args = parser.parse_args() def check_file(file_name: str) -> str: if not os.path.isfile(file_name): - raise RuntimeError('{} is not a regular file!'.format(file_name)) + raise RuntimeError(f'{file_name} is not a regular file!') return file_name - files: List[Tuple[int, str]] = [] + files: list[tuple[int, str]] = [] if args.files: files += [(addr, check_file(f_name)) for addr, f_name in zip(args.files[::2], args.files[1::2])] @@ -82,10 +76,10 @@ def main() -> None: json_dir = os.path.dirname(os.path.abspath(args.json)) def process_json_file(path: str) -> str: - ''' + """ The input path is relative to json_dir. This function makes it relative to the current working directory. - ''' + """ return check_file(os.path.abspath(os.path.join(json_dir, path))) with open(args.json, encoding='utf-8') as f: @@ -112,14 +106,19 @@ def main() -> None: files_flatten = [item for t in files for item in t] cmd = [ - sys.executable, '-m', 'esptool', - '--chip', args.chip_id or args.chip, - 'merge_bin', - '--format', 'uf2', - '-o', args.output_file, + sys.executable, + '-m', + 'esptool', + '--chip', + args.chip_id or args.chip, + 'merge-bin', + '--format', + 'uf2', + '-o', + args.output_file, ] if args.chunk_size: - cmd.extend(['--chunk_size', args.chunk_size]) + cmd.extend(['--chunk-size', args.chunk_size]) if args.md5_disable: cmd.append('--md5-disable') diff --git a/tools/test_apps/security/secure_boot/README.md b/tools/test_apps/security/secure_boot/README.md index 4252dc963f..8e978da32b 100644 --- a/tools/test_apps/security/secure_boot/README.md +++ b/tools/test_apps/security/secure_boot/README.md @@ -23,7 +23,7 @@ idf.py menuconfig * To change the chip revision, set "Component Config" -> "ESP32- Specific"->"Minimum Supported ESP32 Revision" to Rev 3. Now, set Secure Boot V2 option can now be enabled under "Enable hardware Secure Boot in bootloader" -> "Secure Boot Version". -* Specify the apt secure boot signing key path. If not present generate one using `python $IDF_PATH/components/esptool_py/esptool/espsecure.py generate_signing_key --version {VERSION} secure_boot_signing_key.pem` +* Specify the apt secure boot signing key path. If not present generate one using `espsecure generate-signing-key --version {VERSION} secure_boot_signing_key.pem` * Ensure Bootloader log verbosity is Info under Bootloader config. @@ -31,7 +31,7 @@ idf.py menuconfig ### Build and Flash -- The below steps can be used in any application to enable secure boot. +- The below steps can be used in any application to enable secure boot. - Secure Boot is an irreversible operation, please read the Secure Boot section in ESP-IDF Programming Manual. diff --git a/tools/test_apps/security/secure_boot/conftest.py b/tools/test_apps/security/secure_boot/conftest.py index 03a1ee672d..6267ca6949 100644 --- a/tools/test_apps/security/secure_boot/conftest.py +++ b/tools/test_apps/security/secure_boot/conftest.py @@ -40,7 +40,7 @@ class FpgaSerial(IdfSerial): """ offs = int(self.app.sdkconfig.get('BOOTLOADER_OFFSET_IN_FLASH', 0)) esptool.main( - f'--port {self.esp_port} --no-stub write_flash {str(offs)} {bootloader_path} --force'.split(), esp=self.esp + f'--port {self.esp_port} --no-stub write-flash {str(offs)} {bootloader_path} --force'.split(), esp=self.esp ) @EspSerial.use_esptool() @@ -52,7 +52,7 @@ class FpgaSerial(IdfSerial): """ offs = int(self.app.flash_args['partition-table']['offset'], 16) esptool.main( - f'--port {self.esp_port} --no-stub write_flash {str(offs)} {partition_table_path}'.split(), esp=self.esp + f'--port {self.esp_port} --no-stub write-flash {str(offs)} {partition_table_path}'.split(), esp=self.esp ) @EspSerial.use_esptool() @@ -63,7 +63,7 @@ class FpgaSerial(IdfSerial): :return: None """ offs = int(self.app.flash_args['app']['offset'], 16) - esptool.main(f'--port {self.esp_port} --no-stub write_flash {str(offs)} {app_path}'.split(), esp=self.esp) + esptool.main(f'--port {self.esp_port} --no-stub write-flash {str(offs)} {app_path}'.split(), esp=self.esp) def erase_app_header(self) -> None: """ @@ -81,16 +81,16 @@ class FpgaSerial(IdfSerial): @EspSerial.use_esptool() def burn_efuse_key_digest(self, key: str, purpose: str, block: str) -> None: espefuse.main( - f'--port {self.esp_port} burn_key_digest {block} {key} {purpose} --do-not-confirm'.split(), esp=self.esp + f'--port {self.esp_port} burn-key-digest {block} {key} {purpose} --do-not-confirm'.split(), esp=self.esp ) @EspSerial.use_esptool() def burn_efuse(self, field: str, val: int) -> None: - espefuse.main(f'--port {self.esp_port} burn_efuse {field} {str(val)} --do-not-confirm'.split(), esp=self.esp) + espefuse.main(f'--port {self.esp_port} burn-efuse {field} {str(val)} --do-not-confirm'.split(), esp=self.esp) @EspSerial.use_esptool() def burn_efuse_key(self, key: str, purpose: str, block: str) -> None: - espefuse.main(f'--port {self.esp_port} burn_key {block} {key} {purpose} --do-not-confirm'.split(), esp=self.esp) + espefuse.main(f'--port {self.esp_port} burn-key {block} {key} {purpose} --do-not-confirm'.split(), esp=self.esp) def reset_efuses(self) -> None: with serial.Serial(self.efuse_reset_port) as efuseport: @@ -127,7 +127,7 @@ class Esp32c3FpgaDut(FpgaDut): self.serial.burn_efuse(self.SECURE_BOOT_EN_KEY, self.SECURE_BOOT_EN_VAL) def secure_boot_burn_digest(self, digest: str, key_index: int = 0, block: int = 0) -> None: - self.serial.burn_efuse_key_digest(digest, 'SECURE_BOOT_DIGEST%d' % key_index, 'BLOCK_KEY%d' % block) + self.serial.burn_efuse_key_digest(digest, f'SECURE_BOOT_DIGEST{key_index}', f'BLOCK_KEY{block}') class Esp32s3FpgaDut(FpgaDut): @@ -143,7 +143,7 @@ class Esp32s3FpgaDut(FpgaDut): self.serial.burn_efuse(self.SECURE_BOOT_EN_KEY, self.SECURE_BOOT_EN_VAL) def secure_boot_burn_digest(self, digest: str, key_index: int = 0, block: int = 0) -> None: - self.serial.burn_efuse_key_digest(digest, 'SECURE_BOOT_DIGEST%d' % key_index, 'BLOCK_KEY%d' % block) + self.serial.burn_efuse_key_digest(digest, f'SECURE_BOOT_DIGEST{key_index}', f'BLOCK_KEY{block}') class Esp32p4FpgaDut(FpgaDut): @@ -157,7 +157,7 @@ class Esp32p4FpgaDut(FpgaDut): self.serial.burn_efuse(self.SECURE_BOOT_EN_KEY, self.SECURE_BOOT_EN_VAL) def secure_boot_burn_digest(self, digest: str, key_index: int = 0, block: int = 0) -> None: - self.serial.burn_efuse_key_digest(digest, 'SECURE_BOOT_DIGEST%d' % key_index, 'BLOCK_KEY%d' % block) + self.serial.burn_efuse_key_digest(digest, f'SECURE_BOOT_DIGEST{key_index}', f'BLOCK_KEY{block}') class Esp32c5FpgaDut(FpgaDut): @@ -171,7 +171,7 @@ class Esp32c5FpgaDut(FpgaDut): self.serial.burn_efuse(self.SECURE_BOOT_EN_KEY, self.SECURE_BOOT_EN_VAL) def secure_boot_burn_digest(self, digest: str, key_index: int = 0, block: int = 0) -> None: - self.serial.burn_efuse_key_digest(digest, 'SECURE_BOOT_DIGEST%d' % key_index, 'BLOCK_KEY%d' % block) + self.serial.burn_efuse_key_digest(digest, f'SECURE_BOOT_DIGEST{key_index}', f'BLOCK_KEY{block}') class Esp32c61FpgaDut(FpgaDut): @@ -185,7 +185,7 @@ class Esp32c61FpgaDut(FpgaDut): self.serial.burn_efuse(self.SECURE_BOOT_EN_KEY, self.SECURE_BOOT_EN_VAL) def secure_boot_burn_digest(self, digest: str, key_index: int = 0, block: int = 0) -> None: - self.serial.burn_efuse_key_digest(digest, 'SECURE_BOOT_DIGEST%d' % key_index, 'BLOCK_KEY%d' % block) + self.serial.burn_efuse_key_digest(digest, f'SECURE_BOOT_DIGEST{key_index}', f'BLOCK_KEY{block}') class Esp32h21FpgaDut(FpgaDut): @@ -199,7 +199,7 @@ class Esp32h21FpgaDut(FpgaDut): self.serial.burn_efuse(self.SECURE_BOOT_EN_KEY, self.SECURE_BOOT_EN_VAL) def secure_boot_burn_digest(self, digest: str, key_index: int = 0, block: int = 0) -> None: - self.serial.burn_efuse_key_digest(digest, 'SECURE_BOOT_DIGEST%d' % key_index, 'BLOCK_KEY%d' % block) + self.serial.burn_efuse_key_digest(digest, f'SECURE_BOOT_DIGEST{key_index}', f'BLOCK_KEY{block}') @pytest.fixture(scope='module') diff --git a/tools/test_apps/security/secure_boot/main/CMakeLists.txt b/tools/test_apps/security/secure_boot/main/CMakeLists.txt index bce7659f1a..cdd6164ed5 100644 --- a/tools/test_apps/security/secure_boot/main/CMakeLists.txt +++ b/tools/test_apps/security/secure_boot/main/CMakeLists.txt @@ -18,7 +18,7 @@ if(CONFIG_EXAMPLE_TARGET_QEMU) add_custom_target(sign_bootloader ALL COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_BINARY_DIR}/bootloader/bootloader.bin" "${CMAKE_BINARY_DIR}/bootloader/${bootloader_unsigned_bin}" - COMMAND ${espsecure_py_cmd} sign_data --version 2 --keyfile + COMMAND ${espsecure_py_cmd} sign-data --version 2 --keyfile ${PROJECT_DIR}/test/secure_boot_signing_key0.pem ${PROJECT_DIR}/test/secure_boot_signing_key1.pem ${PROJECT_DIR}/test/secure_boot_signing_key2.pem @@ -34,7 +34,7 @@ if(CONFIG_EXAMPLE_TARGET_QEMU) add_custom_target(sign_app ALL COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_BINARY_DIR}/${PROJECT_BIN}.bin" "${CMAKE_BINARY_DIR}/${app_unsigned_bin}" - COMMAND ${espsecure_py_cmd} sign_data --version 2 --keyfile + COMMAND ${espsecure_py_cmd} sign-data --version 2 --keyfile ${PROJECT_DIR}/test/secure_boot_signing_key1.pem -o "${CMAKE_BINARY_DIR}/${PROJECT_BIN}.bin" "${CMAKE_BINARY_DIR}/${app_unsigned_bin}" diff --git a/tools/test_apps/system/gdb_loadable_elf/test_gdb_loadable_elf_util/loadable_app_serial.py b/tools/test_apps/system/gdb_loadable_elf/test_gdb_loadable_elf_util/loadable_app_serial.py index 2519751bb3..7b6013ada3 100644 --- a/tools/test_apps/system/gdb_loadable_elf/test_gdb_loadable_elf_util/loadable_app_serial.py +++ b/tools/test_apps/system/gdb_loadable_elf/test_gdb_loadable_elf_util/loadable_app_serial.py @@ -1,7 +1,6 @@ # SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD # SPDX-License-Identifier: Unlicense OR CC0-1.0 import logging -from collections import namedtuple from typing import Any import esptool @@ -40,8 +39,4 @@ class LoadableAppSerial(EspSerial): with open(self.app.bin_file, 'rb') as f_bin_file: self.esp.change_baud(460800) - try: - # esptool v5.0+ - esptool.load_ram(self.esp, input=f_bin_file) - except TypeError: - esptool.load_ram(self.esp, namedtuple('args', 'filename')(f_bin_file)) + esptool.load_ram(self.esp, f_bin_file) diff --git a/tools/test_apps/system/ram_loadable_app/README.md b/tools/test_apps/system/ram_loadable_app/README.md index 84892aa9ba..f33ad5d479 100644 --- a/tools/test_apps/system/ram_loadable_app/README.md +++ b/tools/test_apps/system/ram_loadable_app/README.md @@ -35,7 +35,7 @@ idf.py set-target {target name} idf.py build -esptool.py -p PORT --no-stub load_ram build/ram_loadable_app.bin +esptool -p PORT --no-stub load-ram build/ram_loadable_app.bin idf.py -p PORT monitor --no-reset ``` diff --git a/tools/test_build_system/test_build.py b/tools/test_build_system/test_build.py index 90835693bf..de2d9f3825 100644 --- a/tools/test_build_system/test_build.py +++ b/tools/test_build_system/test_build.py @@ -2,7 +2,6 @@ # SPDX-License-Identifier: Apache-2.0 import logging import os -import re import shutil import stat import sys @@ -183,18 +182,18 @@ def test_build_dfu(idf_py: IdfPyFunc) -> None: def test_build_uf2(idf_py: IdfPyFunc) -> None: logging.info('UF2 build works') ret = idf_py('uf2') - assert re.search(r"build/uf2.bin'?, ready to be flashed with any ESP USB Bridge", ret.stdout) is not None, ( + assert "build/uf2.bin', ready to be flashed with any ESP USB Bridge" in ret.stdout, ( 'UF2 build should work for esp32' ) assert_built(BOOTLOADER_BINS + APP_BINS + PARTITION_BIN + ['build/uf2.bin']) ret = idf_py('uf2-app') - assert re.search(r"build/uf2-app.bin'?, ready to be flashed with any ESP USB Bridge", ret.stdout) is not None, ( + assert "build/uf2-app.bin', ready to be flashed with any ESP USB Bridge" in ret.stdout, ( 'UF2 build should work for application binary' ) assert_built(['build/uf2-app.bin']) idf_py('set-target', 'esp32s2') ret = idf_py('uf2') - assert re.search(r"build/uf2.bin'?, ready to be flashed with any ESP USB Bridge", ret.stdout) is not None, ( + assert "build/uf2.bin', ready to be flashed with any ESP USB Bridge" in ret.stdout, ( 'UF2 build should work for esp32s2' ) assert_built(BOOTLOADER_BINS + APP_BINS + PARTITION_BIN + ['build/uf2.bin']) diff --git a/tools/test_idf_py/test_idf_py.py b/tools/test_idf_py/test_idf_py.py index fcb885b7e5..18b1dfa16b 100755 --- a/tools/test_idf_py/test_idf_py.py +++ b/tools/test_idf_py/test_idf_py.py @@ -362,6 +362,7 @@ class TestWrapperCommands(TestCase): ) return output except subprocess.CalledProcessError as e: + print(e.output.decode('utf-8', 'ignore')) self.fail(f'Process should have exited normally, but it exited with a return code of {e.returncode}') @classmethod @@ -373,8 +374,8 @@ class TestWrapperCommands(TestCase): class TestEFuseCommands(TestWrapperCommands): """ - Test if wrapper commands for espefuse.py are working as expected. - The goal is NOT to test the functionality of espefuse.py + Test if wrapper commands for espefuse are working as expected. + The goal is NOT to test the functionality of espefuse but to test if the wrapper commands are working as expected. """ @@ -437,8 +438,8 @@ class TestEFuseCommands(TestWrapperCommands): class TestSecureCommands(TestWrapperCommands): """ - Test if wrapper commands for espsecure.py are working as expected. - The goal is NOT to test the functionality of espsecure.py + Test if wrapper commands for espsecure are working as expected. + The goal is NOT to test the functionality of espsecure but to test if the wrapper commands are working as expected. """ @@ -458,7 +459,7 @@ class TestSecureCommands(TestWrapperCommands): self.flash_encryption_key, ] output = self.call_command(generate_key_command) - self.assertRegex(output, f'Writing 256 random bits to key file "?{self.flash_encryption_key}"?') + self.assertIn(f'Writing 256 random bits to key file "{self.flash_encryption_key}".', output) def secure_encrypt_flash_data(self): self.secure_generate_flash_encryption_key() @@ -542,7 +543,7 @@ class TestSecureCommands(TestWrapperCommands): self.signing_key, ] output = self.call_command(generate_key_command) - self.assertRegex(output, f'RSA 3072 private key in PEM format written to "?{self.signing_key}"?') + self.assertIn(f'RSA 3072 private key in PEM format written to "{self.signing_key}".', output) def test_secure_generate_key_digest(self): self.secure_generate_signing_key() @@ -556,7 +557,7 @@ class TestSecureCommands(TestWrapperCommands): 'key_digest.bin', ] output = self.call_command(digest_command) - self.assertRegex(output, f'Writing the public key digest of "?{self.signing_key}"? to "?key_digest.bin"?.') + self.assertIn(f'Writing the public key digest of "{self.signing_key}" to "key_digest.bin".', output) def test_secure_generate_nvs_partition_key(self): generate_key_command = [ @@ -577,7 +578,7 @@ class TestSecureCommands(TestWrapperCommands): class TestMergeBinCommands(TestWrapperCommands): """ Test if merge-bin command is invoked as expected. - This test is not testing the functionality of esptool.py merge_bin command + This test is not testing the functionality of esptool merge-bin command, but the invocation of the command from idf.py. """ @@ -585,7 +586,7 @@ class TestMergeBinCommands(TestWrapperCommands): merge_bin_command = [sys.executable, idf_py_path, 'merge-bin'] merged_binary_name = 'test-merge-binary.bin' output = self.call_command(merge_bin_command + ['--output', merged_binary_name]) - self.assertRegex(output, f"file '?{merged_binary_name}'?, ready to flash to offset 0x0") + self.assertIn(f"file '{merged_binary_name}', ready to flash to offset 0x0", output) self.assertIn(f'Merged binary {merged_binary_name} will be created in the build directory...', output)