mirror of
https://github.com/espressif/esp-idf.git
synced 2025-11-20 02:46:26 +00:00
feat: Update esptool to v5
This commit is contained in:
Peter Dragun
@@ -218,11 +218,11 @@ No Pull-ups
|
||||
|
||||
Burning eFuses is irreversible! The issue list above might be out of date, so please make sure that the module you are burning has a 3.3 V flash chip by checking the information on https://www.espressif.com/. If you burn the 3.3 V eFuses on a module with a 1.8 V flash chip, the module will stop functioning.
|
||||
|
||||
If you are sure that you need to irreversibly burn eFuses, go to your ESP-IDF directory and run the following command using ``espefuse.py`` tool:
|
||||
If you are sure that you need to irreversibly burn eFuses, go to your ESP-IDF directory and run the following command using ``espefuse`` tool:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
components/esptool_py/esptool/espefuse.py set_flash_voltage 3.3V
|
||||
espefuse set-flash-voltage 3.3V
|
||||
|
||||
This command burns the ``XPD_SDIO_TIEH``, ``XPD_SDIO_FORCE``, and ``XPD_SDIO_REG`` eFuses. After all the three eFuses are burned to value 1, the internal VDD_SDIO flash voltage regulator is permanently set to 3.3 V. You will see the following log if the burning succeeds:
|
||||
|
||||
@@ -244,7 +244,7 @@ No Pull-ups
|
||||
|
||||
idf.py efuse-summary
|
||||
|
||||
If running from an automated flashing script, it is better to use standalone eFuse tool ``espefuse.py``. This tool also has an option ``--do-not-confirm`` to burn eFuses without confirmation.
|
||||
If running from an automated flashing script, it is better to use standalone eFuse tool ``espefuse``. This tool also has an option ``--do-not-confirm`` to burn eFuses without confirmation.
|
||||
|
||||
For more details, see **{IDF_TARGET_NAME} Technical Reference Manual** [`PDF <{IDF_TARGET_TRM_EN_URL}#efuse>`__].
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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`.
|
||||
|
||||
|
||||
@@ -43,7 +43,7 @@ There are also other arguments that control image generation. Documentation on t
|
||||
|
||||
These optional arguments correspond to a possible SPIFFS build configuration. To generate the right image, please make sure that you use the same arguments/configuration as were used to build SPIFFS. As a guide, the help output indicates the SPIFFS build configuration to which the argument corresponds. In cases when these arguments are not specified, the default values shown in the help output will be used.
|
||||
|
||||
When the image is created, it can be flashed using ``esptool.py`` or ``parttool.py``.
|
||||
When the image is created, it can be flashed using ``esptool`` or ``parttool.py``.
|
||||
|
||||
Aside from invoking the ``spiffsgen.py`` standalone by manually running it from the command line or a script, it is also possible to invoke ``spiffsgen.py`` directly from the build system by calling ``spiffs_create_partition_image``::
|
||||
|
||||
@@ -57,7 +57,7 @@ Optionally, users can opt to have the image automatically flashed together with
|
||||
|
||||
spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT)
|
||||
|
||||
If FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using ``esptool.py``, ``parttool.py``, or a custom build system target.
|
||||
If FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using ``esptool``, ``parttool.py``, or a custom build system target.
|
||||
|
||||
There are cases where the contents of the base directory itself is generated at build time. Users can use DEPENDS/SPIFFS_IMAGE_DEPENDS to specify targets that should be executed before generating the image::
|
||||
|
||||
@@ -70,7 +70,7 @@ For an example, see :example:`storage/spiffsgen`. This example demonstrates how
|
||||
``mkspiffs``
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Another tool for creating SPIFFS partition images is `mkspiffs <https://github.com/igrr/mkspiffs>`_. Similar to ``spiffsgen.py``, it can be used to create an image from a given folder and then flash that image using ``esptool.py``
|
||||
Another tool for creating SPIFFS partition images is `mkspiffs <https://github.com/igrr/mkspiffs>`_. Similar to ``spiffsgen.py``, it can be used to create an image from a given folder and then flash that image using ``esptool``
|
||||
|
||||
For that, you need to obtain the following parameters:
|
||||
|
||||
@@ -85,11 +85,11 @@ To pack a folder into a 1-Megabyte image, run::
|
||||
|
||||
To flash the image onto {IDF_TARGET_NAME} at offset 0x110000, run::
|
||||
|
||||
python esptool.py --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin
|
||||
esptool --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write-flash -z 0x110000 spiffs.bin
|
||||
|
||||
.. note::
|
||||
|
||||
You can configure the ``write_flash`` command of ``esptool.py`` to `write the spiffs data to an external SPI flash chip <https://docs.espressif.com/projects/esptool/en/latest/esptool/advanced-options.html#custom-spi-pin-configuration>`_ using the ``--spi-connection <CLK>,<Q>,<D>,<HD>,<CS>`` option. Just specify the GPIO pins assigned to the external flash, e.g., ``python esptool.py write_flash --spi-connection 6,7,8,9,11 -z 0x110000 spiffs.bin``.
|
||||
You can configure the ``write-flash`` command of ``esptool`` to `write the spiffs data to an external SPI flash chip <https://docs.espressif.com/projects/esptool/en/latest/esptool/advanced-options.html#custom-spi-pin-configuration>`_ using the ``--spi-connection <CLK>,<Q>,<D>,<HD>,<CS>`` option. Just specify the GPIO pins assigned to the external flash, e.g., ``esptool write-flash --spi-connection 6,7,8,9,11 -z 0x110000 spiffs.bin``.
|
||||
|
||||
Notes on Which SPIFFS Tool to Use
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
----------
|
||||
|
||||
@@ -20,7 +20,7 @@ The eFuse Manager component is a collection of tools and APIs that assist with d
|
||||
eFuse Manager vs ``idf.py``
|
||||
---------------------------
|
||||
|
||||
``idf.py`` provides a subset of the functionality of the eFuse Manager via the ``idf.py efuse-<subcommand>`` commands. In this documentation, mostly ``idf.py`` based commands will be used, although you can still see some ``espefuse.py`` based commands for advanced or rare cases. To see all available commands, run ``idf.py --help`` and search for those prefixed with ``efuse-``.
|
||||
``idf.py`` provides a subset of the functionality of the eFuse Manager via the ``idf.py efuse-<subcommand>`` commands. In this documentation, mostly ``idf.py`` based commands will be used, although you can still see some ``espefuse`` based commands for advanced or rare cases. To see all available commands, run ``idf.py --help`` and search for those prefixed with ``efuse-``.
|
||||
|
||||
Hardware Description
|
||||
--------------------
|
||||
@@ -488,7 +488,7 @@ Get eFuses During Build
|
||||
|
||||
There is a way to get the state of eFuses at the build stage of the project. There are two CMake functions for this:
|
||||
|
||||
* ``espefuse_get_json_summary()`` - It calls the ``espefuse.py summary --format json`` command and returns a JSON string (it is not stored in a file).
|
||||
* ``espefuse_get_json_summary()`` - It calls the ``espefuse summary --format json`` command and returns a JSON string (it is not stored in a file).
|
||||
* ``espefuse_get_efuse()`` - It finds a given eFuse name in the JSON string and returns its property.
|
||||
|
||||
The JSON string has the following properties:
|
||||
@@ -522,7 +522,7 @@ These functions can be used from a top-level project ``CMakeLists.txt`` (:exampl
|
||||
espefuse_get_efuse(ret_data ${efuse_json} "MAC" "value")
|
||||
message("MAC:" ${ret_data})
|
||||
|
||||
The format of the ``value`` property is the same as shown in ``espefuse.py summary`` or ``idf.py efuse-summary``.
|
||||
The format of the ``value`` property is the same as shown in ``espefuse summary`` or ``idf.py efuse-summary``.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -557,12 +557,12 @@ Flash encryption is a hardware feature that requires the physical burning of eFu
|
||||
|
||||
The :cpp:func:`bootloader_flash_write` is adapted for this purpose. But if flash encryption is already enabled on the chip when the application is run, or if the bootloader is created with the :ref:`CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH` option, then the flash encryption/decryption operations will work properly. This means that data are encrypted as it is written into an encrypted flash partition and decrypted when they are read from an encrypted partition.
|
||||
|
||||
``espefuse.py``
|
||||
^^^^^^^^^^^^^^^
|
||||
``espefuse``
|
||||
^^^^^^^^^^^^
|
||||
|
||||
esptool includes a useful tool for reading/writing {IDF_TARGET_NAME} eFuse bits - `espefuse.py <https://docs.espressif.com/projects/esptool/en/latest/{IDF_TARGET_PATH_NAME}/espefuse/index.html>`_.
|
||||
esptool includes a useful tool for reading/writing {IDF_TARGET_NAME} eFuse bits - `espefuse <https://docs.espressif.com/projects/esptool/en/latest/{IDF_TARGET_PATH_NAME}/espefuse/index.html>`_.
|
||||
|
||||
Part of the functionality of this tool is also provided directly by ``idf.py`` commands. For example, the ``idf.py efuse-summary`` command is equivalent to ``espefuse.py summary``.
|
||||
Part of the functionality of this tool is also provided directly by ``idf.py`` commands. For example, the ``idf.py efuse-summary`` command is equivalent to ``espefuse summary``.
|
||||
|
||||
.. include:: inc/espefuse_summary_{IDF_TARGET_NAME}.rst
|
||||
|
||||
|
||||
Reference in New Issue
Block a user