forked from espressif/esp-idf
docs: Update CN translation for libs-framework.rst and partition-table.rst
This commit is contained in:
shenmengjing
BOT
@@ -17,55 +17,61 @@ The simplest way to use the partition table is to open the project configuration
|
||||
* "Single factory app, no OTA"
|
||||
* "Factory app, two OTA definitions"
|
||||
|
||||
In both cases the factory app is flashed at offset 0x10000. If you execute `idf.py partition-table` then it will print a summary of the partition table.
|
||||
In both cases the factory app is flashed at offset 0x10000. If you execute ``idf.py partition-table`` then it will print a summary of the partition table.
|
||||
|
||||
Built-in Partition Tables
|
||||
-------------------------
|
||||
|
||||
Here is the summary printed for the "Single factory app, no OTA" configuration::
|
||||
Here is the summary printed for the "Single factory app, no OTA" configuration:
|
||||
|
||||
# ESP-IDF Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x6000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
.. code-block:: none
|
||||
|
||||
# ESP-IDF Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x6000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
|
||||
* At a 0x10000 (64 KB) offset in the flash is the app labelled "factory". The bootloader runs this app by default.
|
||||
* There are also two data regions defined in the partition table for storing NVS library partition and PHY init data.
|
||||
|
||||
Here is the summary printed for the "Factory app, two OTA definitions" configuration::
|
||||
Here is the summary printed for the "Factory app, two OTA definitions" configuration:
|
||||
|
||||
# ESP-IDF Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000,
|
||||
otadata, data, ota, 0xd000, 0x2000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
ota_0, app, ota_0, 0x110000, 1M,
|
||||
ota_1, app, ota_1, 0x210000, 1M,
|
||||
.. code-block:: none
|
||||
|
||||
# ESP-IDF Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000,
|
||||
otadata, data, ota, 0xd000, 0x2000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
ota_0, app, ota_0, 0x110000, 1M,
|
||||
ota_1, app, ota_1, 0x210000, 1M,
|
||||
|
||||
* There are now three app partition definitions. The type of the factory app (at 0x10000) and the next two "OTA" apps are all set to "app", but their subtypes are different.
|
||||
* There is also a new "otadata" slot, which holds the data for OTA updates. The bootloader consults this data in order to know which app to execute. If "ota data" is empty, it will execute the factory app.
|
||||
|
||||
Creating Custom Tables
|
||||
-------------------------
|
||||
----------------------
|
||||
|
||||
If you choose "Custom partition table CSV" in menuconfig then you can also enter the name of a CSV file (in the project directory) to use for your partition table. The CSV file can describe any number of definitions for the table you need.
|
||||
|
||||
The CSV format is the same format as printed in the summaries shown above. However, not all fields are required in the CSV. For example, here is the "input" CSV for the OTA partition table::
|
||||
The CSV format is the same format as printed in the summaries shown above. However, not all fields are required in the CSV. For example, here is the "input" CSV for the OTA partition table:
|
||||
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000
|
||||
otadata, data, ota, 0xd000, 0x2000
|
||||
phy_init, data, phy, 0xf000, 0x1000
|
||||
factory, app, factory, 0x10000, 1M
|
||||
ota_0, app, ota_0, , 1M
|
||||
ota_1, app, ota_1, , 1M
|
||||
nvs_key, data, nvs_keys, , 0x1000
|
||||
.. code-block:: none
|
||||
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000
|
||||
otadata, data, ota, 0xd000, 0x2000
|
||||
phy_init, data, phy, 0xf000, 0x1000
|
||||
factory, app, factory, 0x10000, 1M
|
||||
ota_0, app, ota_0, , 1M
|
||||
ota_1, app, ota_1, , 1M
|
||||
nvs_key, data, nvs_keys, , 0x1000
|
||||
|
||||
* Whitespace between fields is ignored, and so is any line starting with # (comments).
|
||||
* Each non-comment line in the CSV file is a partition definition.
|
||||
* The "Offset" field for each partition is empty. The gen_esp32part.py tool fills in each blank offset, starting after the partition table and making sure each partition is aligned correctly.
|
||||
* The ``Offset`` field for each partition is empty. The ``gen_esp32part.py`` tool fills in each blank offset, starting after the partition table and making sure each partition is aligned correctly.
|
||||
|
||||
Name Field
|
||||
~~~~~~~~~~
|
||||
@@ -77,15 +83,17 @@ Type Field
|
||||
|
||||
Partition type field can be specified as a name or a number 0-254 (or as hex 0x00-0xFE). Types 0x00-0x3F are reserved for ESP-IDF core functions.
|
||||
|
||||
- ``app`` (0x00),
|
||||
- ``data`` (0x01),
|
||||
- ``bootloader`` (0x02). By default, this partition is not included in any CSV partition table files because it is not required and does not impact the system's functionality. It is only useful for the bootloader OTA update. Even if this partition is not present in the CSV file, it is still possible to perform the OTA. Please note that if you specify this partition in the CSV file, its address and size must match Kconfigs,
|
||||
- ``partition_table`` (0x03),
|
||||
- ``app`` (0x00).
|
||||
- ``data`` (0x01).
|
||||
- ``bootloader`` (0x02). By default, this partition is not included in any CSV partition table files because it is not required and does not impact the system's functionality. It is only useful for the bootloader OTA update. Even if this partition is not present in the CSV file, it is still possible to perform the OTA. Please note that if you specify this partition in the CSV file, its address and size must match Kconfigs.
|
||||
- ``partition_table`` (0x03).
|
||||
- 0x40-0xFE are reserved for **custom partition types**. If your app needs to store data in a format not already supported by ESP-IDF, then use a value from this range.
|
||||
|
||||
See :cpp:type:`esp_partition_type_t` for the enum definitions for ``app`` and ``data`` partitions.
|
||||
|
||||
If writing in C++ then specifying a application-defined partition type requires casting an integer to :cpp:type:`esp_partition_type_t` in order to use it with the :ref:`partition API<api-reference-partition-table>`. For example::
|
||||
If writing in C++ then specifying a application-defined partition type requires casting an integer to :cpp:type:`esp_partition_type_t` in order to use it with the :ref:`partition API<api-reference-partition-table>`. For example:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
static const esp_partition_type_t APP_PARTITION_TYPE_A = (esp_partition_type_t)0x40;
|
||||
|
||||
@@ -93,6 +101,7 @@ The bootloader ignores any partition types other than ``app`` (0x00) and ``data`
|
||||
|
||||
SubType
|
||||
~~~~~~~
|
||||
|
||||
{IDF_TARGET_ESP_PHY_REF:default = ":ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`", esp32p4, esp32c5, esp32c61="NOT UPDATED YET"}
|
||||
|
||||
The 8-bit SubType field is specific to a given partition type. ESP-IDF currently only specifies the meaning of the subtype field for ``app`` and ``data`` partition types.
|
||||
@@ -101,63 +110,63 @@ See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defin
|
||||
|
||||
* When type is ``app``, the SubType field can be specified as ``factory`` (0x00), ``ota_0`` (0x10) ... ``ota_15`` (0x1F) or ``test`` (0x20).
|
||||
|
||||
- ``factory`` (0x00) is the default app partition. The bootloader will execute the factory app unless there it sees a partition of type data/ota, in which case it reads this partition to determine which OTA image to boot.
|
||||
- ``factory`` (0x00) is the default app partition. The bootloader will execute the factory app unless there it sees a partition of type data/ota, in which case it reads this partition to determine which OTA image to boot.
|
||||
|
||||
- OTA never updates the factory partition.
|
||||
- If you want to conserve flash usage in an OTA project, you can remove the factory partition and use ``ota_0`` instead.
|
||||
- OTA never updates the factory partition.
|
||||
- If you want to conserve flash usage in an OTA project, you can remove the factory partition and use ``ota_0`` instead.
|
||||
|
||||
- ``ota_0`` (0x10) ... ``ota_15`` (0x1F) are the OTA app slots. When :doc:`OTA <../api-reference/system/ota>` is in use, the OTA data partition configures which app slot the bootloader should boot. When using OTA, an application should have at least two OTA application slots (``ota_0`` & ``ota_1``). Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details.
|
||||
- ``test`` (0x20) is a reserved subtype for factory test procedures. It will be used as the fallback boot partition if no other valid app partition is found. It is also possible to configure the bootloader to read a GPIO input during each boot, and boot this partition if the GPIO is held low, see :ref:`bootloader_boot_from_test_firmware`.
|
||||
- ``ota_0`` (0x10) ... ``ota_15`` (0x1F) are the OTA app slots. When :doc:`OTA <../api-reference/system/ota>` is in use, the OTA data partition configures which app slot the bootloader should boot. When using OTA, an application should have at least two OTA application slots (``ota_0`` & ``ota_1``). Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details.
|
||||
- ``test`` (0x20) is a reserved subtype for factory test procedures. It will be used as the fallback boot partition if no other valid app partition is found. It is also possible to configure the bootloader to read a GPIO input during each boot, and boot this partition if the GPIO is held low, see :ref:`bootloader_boot_from_test_firmware`.
|
||||
|
||||
* When type is ``bootloader``, the SubType field can be specified as:
|
||||
|
||||
- ``primary`` (0x00). It is the so-called 2nd stage bootloader, which is placed at the {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} address in the flash. The ``gen_esp32part.py`` does not allow to have this partition in the CSV file for now.
|
||||
- ``ota`` (0x01). It is a temporary bootloader partition used by the bootloader OTA update functionality for downloading a new image.
|
||||
- ``primary`` (0x00). It is the so-called second stage bootloader, which is placed at the {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} address in the flash. The ``gen_esp32part.py`` does not allow to have this partition in the CSV file for now.
|
||||
- ``ota`` (0x01). It is a temporary bootloader partition used by the bootloader OTA update functionality for downloading a new image.
|
||||
|
||||
* When type is ``partition_table``, the SubType field can be specified as:
|
||||
|
||||
- ``primary`` (0x00). It is the primary partition table, which is placed at the :ref:`CONFIG_PARTITION_TABLE_OFFSET` address in the flash. The ``gen_esp32part.py`` does not allow to have this partition in the CSV file for now.
|
||||
- ``ota`` (0x01). It is a temporary partition table partition used by the partition table OTA update functionality for downloading a new image.
|
||||
- ``primary`` (0x00). It is the primary partition table, which is placed at the :ref:`CONFIG_PARTITION_TABLE_OFFSET` address in the flash. The ``gen_esp32part.py`` does not allow to have this partition in the CSV file for now.
|
||||
- ``ota`` (0x01). It is a temporary partition table partition used by the partition table OTA update functionality for downloading a new image.
|
||||
|
||||
* When type is ``data``, the subtype field can be specified as ``ota`` (0x00), ``phy`` (0x01), ``nvs`` (0x02), nvs_keys (0x04), or a range of other component-specific subtypes (see :cpp:type:`subtype enum <esp_partition_subtype_t>`).
|
||||
|
||||
- ``ota`` (0) is the :ref:`OTA data partition <ota_data_partition>` which stores information about the currently selected OTA app slot. This partition should be 0x2000 bytes in size. Refer to the :ref:`OTA documentation <ota_data_partition>` for more details.
|
||||
- ``phy`` (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware.
|
||||
- ``ota`` (0) is the :ref:`OTA data partition <ota_data_partition>` which stores information about the currently selected OTA app slot. This partition should be 0x2000 bytes in size. Refer to the :ref:`OTA documentation <ota_data_partition>` for more details.
|
||||
- ``phy`` (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware.
|
||||
|
||||
- In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space.
|
||||
- To load PHY data from this partition, open the project configuration menu (``idf.py menuconfig``) and enable {IDF_TARGET_ESP_PHY_REF} option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically.
|
||||
- ``nvs`` (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`.
|
||||
- In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space.
|
||||
- To load PHY data from this partition, open the project configuration menu (``idf.py menuconfig``) and enable {IDF_TARGET_ESP_PHY_REF} option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically.
|
||||
- ``nvs`` (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`.
|
||||
|
||||
- NVS is used to store per-device PHY calibration data (different to initialisation data).
|
||||
- NVS is used to store per-device PHY calibration data (different to initialisation data).
|
||||
|
||||
.. only:: SOC_WIFI_SUPPORTED
|
||||
.. only:: SOC_WIFI_SUPPORTED
|
||||
|
||||
- NVS is used to store Wi-Fi data if the :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/network/esp_wifi>` initialization function is used.
|
||||
- NVS is used to store Wi-Fi data if the :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/network/esp_wifi>` initialization function is used.
|
||||
|
||||
- The NVS API can also be used for other application data.
|
||||
- It is strongly recommended that you include an NVS partition of at least 0x3000 bytes in your project.
|
||||
- If using NVS API to store a lot of data, increase the NVS partition size from the default 0x6000 bytes.
|
||||
- ``nvs_keys`` (4) is for the NVS key partition. See :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>` for more details.
|
||||
- The NVS API can also be used for other application data.
|
||||
- It is strongly recommended that you include an NVS partition of at least 0x3000 bytes in your project.
|
||||
- If using NVS API to store a lot of data, increase the NVS partition size from the default 0x6000 bytes.
|
||||
- ``nvs_keys`` (4) is for the NVS key partition. See :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>` for more details.
|
||||
|
||||
- It is used to store NVS encryption keys when `NVS Encryption` feature is enabled.
|
||||
- The size of this partition should be 4096 bytes (minimum partition size).
|
||||
- It is used to store NVS encryption keys when `NVS Encryption` feature is enabled.
|
||||
- The size of this partition should be 4096 bytes (minimum partition size).
|
||||
|
||||
- There are other predefined data subtypes for data storage supported by ESP-IDF. These include:
|
||||
- There are other predefined data subtypes for data storage supported by ESP-IDF. These include:
|
||||
|
||||
- ``coredump`` (0x03) is for storing core dumps while using a custom partition table CSV file. See :doc:`/api-guides/core_dump` for more details.
|
||||
- ``efuse`` (0x05) is for emulating eFuse bits using :ref:`virtual-efuses`.
|
||||
- ``undefined`` (0x06) is implicitly used for data partitions with unspecified (empty) subtype, but it is possible to explicitly mark them as undefined as well.
|
||||
- ``fat`` (0x81) is for :doc:`/api-reference/storage/fatfs`.
|
||||
- ``spiffs`` (0x82) is for :doc:`/api-reference/storage/spiffs`.
|
||||
- ``littlefs`` (0x83) is for `LittleFS filesystem <https://github.com/littlefs-project/littlefs>`_. See :example:`storage/littlefs` example for more details.
|
||||
- ``coredump`` (0x03) is for storing core dumps while using a custom partition table CSV file. See :doc:`/api-guides/core_dump` for more details.
|
||||
- ``efuse`` (0x05) is for emulating eFuse bits using :ref:`virtual-efuses`.
|
||||
- ``undefined`` (0x06) is implicitly used for data partitions with unspecified (empty) subtype, but it is possible to explicitly mark them as undefined as well.
|
||||
- ``fat`` (0x81) is for :doc:`/api-reference/storage/fatfs`.
|
||||
- ``spiffs`` (0x82) is for :doc:`/api-reference/storage/spiffs`.
|
||||
- ``littlefs`` (0x83) is for `LittleFS filesystem <https://github.com/littlefs-project/littlefs>`_. See :example:`storage/littlefs` example for more details.
|
||||
|
||||
.. Comment: ``esphttpd`` (0x80) was not added to the list because there is no docs section for it and it is not clear whether user should use it explicitly.
|
||||
|
||||
Other subtypes of ``data`` type are reserved for future ESP-IDF uses.
|
||||
Other subtypes of ``data`` type are reserved for future ESP-IDF uses.
|
||||
|
||||
* If the partition type is any application-defined value (range 0x40-0xFE), then ``subtype`` field can be any value chosen by the application (range 0x00-0xFE).
|
||||
|
||||
Note that when writing in C++, an application-defined subtype value requires casting to type :cpp:type:`esp_partition_subtype_t` in order to use it with the :ref:`partition API <api-reference-partition-table>`.
|
||||
Note that when writing in C++, an application-defined subtype value requires casting to type :cpp:type:`esp_partition_subtype_t` in order to use it with the :ref:`partition API <api-reference-partition-table>`.
|
||||
|
||||
Extra Partition SubTypes
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -185,17 +194,17 @@ Flags
|
||||
|
||||
Two flags are currently supported, ``encrypted`` and ``readonly``:
|
||||
|
||||
- If ``encrypted`` flag is set, the partition will be encrypted if :doc:`/security/flash-encryption` is enabled.
|
||||
- If ``encrypted`` flag is set, the partition will be encrypted if :doc:`/security/flash-encryption` is enabled.
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
``app`` type partitions will always be encrypted, regardless of whether this flag is set or not.
|
||||
``app`` type partitions will always be encrypted, regardless of whether this flag is set or not.
|
||||
|
||||
- If ``readonly`` flag is set, the partition will be read-only. This flag is only supported for ``data`` type partitions except ``ota``` and ``coredump``` subtypes. This flag can help to protect against accidental writes to a partition that contains critical device-specific configuration data, e.g., factory data partition.
|
||||
- If ``readonly`` flag is set, the partition will be read-only. This flag is only supported for ``data`` type partitions except ``ota``` and ``coredump``` subtypes. This flag can help to protect against accidental writes to a partition that contains critical device-specific configuration data, e.g., factory data partition.
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
Using C file I/O API to open a file (``fopen```) in any write mode (``w``, ``w+``, ``a``, ``a+``, ``r+``) will fail and return ``NULL``. Using ``open`` with any other flag than ``O_RDONLY`` will fail and return ``-1`` while ``errno`` global variable will be set to ``EROFS``. This is also true for any other POSIX syscall function performing write or erase operations. Opening a handle in read-write mode for NVS on a read-only partition will fail and return :c:macro:`ESP_ERR_NOT_ALLOWED` error code. Using a lower level API like ``esp_partition``, ``spi_flash``, etc. to write to a read-only partition will result in :c:macro:`ESP_ERR_NOT_ALLOWED` error code.
|
||||
Using C file I/O API to open a file (``fopen```) in any write mode (``w``, ``w+``, ``a``, ``a+``, ``r+``) will fail and return ``NULL``. Using ``open`` with any other flag than ``O_RDONLY`` will fail and return ``-1`` while ``errno`` global variable will be set to ``EROFS``. This is also true for any other POSIX syscall function performing write or erase operations. Opening a handle in read-write mode for NVS on a read-only partition will fail and return :c:macro:`ESP_ERR_NOT_ALLOWED` error code. Using a lower level API like ``esp_partition``, ``spi_flash``, etc. to write to a read-only partition will result in :c:macro:`ESP_ERR_NOT_ALLOWED` error code.
|
||||
|
||||
You can specify multiple flags by separating them with a colon. For example, ``encrypted:readonly``.
|
||||
|
||||
@@ -206,17 +215,23 @@ The partition table which is flashed to the {IDF_TARGET_NAME} is in a binary for
|
||||
|
||||
If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition-table``, this conversion is done as part of the build process.
|
||||
|
||||
To convert CSV to Binary manually::
|
||||
To convert CSV to Binary manually:
|
||||
|
||||
python gen_esp32part.py input_partitions.csv binary_partitions.bin
|
||||
.. code-block:: none
|
||||
|
||||
To convert binary format back to CSV manually::
|
||||
python gen_esp32part.py input_partitions.csv binary_partitions.bin
|
||||
|
||||
python gen_esp32part.py binary_partitions.bin input_partitions.csv
|
||||
To convert binary format back to CSV manually:
|
||||
|
||||
To display the contents of a binary partition table on stdout (this is how the summaries displayed when running ``idf.py partition-table`` are generated::
|
||||
.. code-block:: none
|
||||
|
||||
python gen_esp32part.py binary_partitions.bin
|
||||
python gen_esp32part.py binary_partitions.bin input_partitions.csv
|
||||
|
||||
To display the contents of a binary partition table on stdout (this is how the summaries displayed when running ``idf.py partition-table`` are generated:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
python gen_esp32part.py binary_partitions.bin
|
||||
|
||||
Partition Size Checks
|
||||
---------------------
|
||||
@@ -230,7 +245,7 @@ Currently these checks are performed for the following binaries:
|
||||
|
||||
.. note::
|
||||
|
||||
Although the build process will fail if the size check returns an error, the binary files are still generated and can be flashed (although they may not work if they are too large for the available space.)
|
||||
Although the build process will fail if the size check returns an error, the binary files are still generated and can be flashed (although they may not work if they are too large for the available space.)
|
||||
|
||||
MD5 Checksum
|
||||
~~~~~~~~~~~~
|
||||
@@ -256,7 +271,7 @@ A manual flashing command is also printed as part of ``idf.py partition-table``
|
||||
|
||||
.. 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.py erase_flash``) to erase the entire flash contents.
|
||||
|
||||
|
||||
Partition Tool (``parttool.py``)
|
||||
@@ -264,10 +279,10 @@ Partition Tool (``parttool.py``)
|
||||
|
||||
The component `partition_table` provides a tool :component_file:`parttool.py <partition_table/parttool.py>` for performing partition-related operations on a target device. The following operations can be performed using the tool:
|
||||
|
||||
- reading a partition and saving the contents to a file (read_partition)
|
||||
- writing the contents of a file to a partition (write_partition)
|
||||
- erasing a partition (erase_partition)
|
||||
- retrieving info such as name, offset, size and flag ("encrypted") of a given partition (get_partition_info)
|
||||
- reading a partition and saving the contents to a file (read_partition)
|
||||
- writing the contents of a file to a partition (write_partition)
|
||||
- erasing a partition (erase_partition)
|
||||
- retrieving info such as name, offset, size and flag ("encrypted") of a given partition (get_partition_info)
|
||||
|
||||
The tool can either be imported and used from another Python script or invoked from shell script for users wanting to perform operation programmatically. This is facilitated by the tool's Python API and command-line interface, respectively.
|
||||
|
||||
@@ -278,38 +293,38 @@ Before anything else, make sure that the `parttool` module is imported.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import sys
|
||||
import os
|
||||
import sys
|
||||
import os
|
||||
|
||||
idf_path = os.environ["IDF_PATH"] # get value of IDF_PATH from environment
|
||||
parttool_dir = os.path.join(idf_path, "components", "partition_table") # parttool.py lives in $IDF_PATH/components/partition_table
|
||||
idf_path = os.environ["IDF_PATH"] # get value of IDF_PATH from environment
|
||||
parttool_dir = os.path.join(idf_path, "components", "partition_table") # parttool.py lives in $IDF_PATH/components/partition_table
|
||||
|
||||
sys.path.append(parttool_dir) # this enables Python to find parttool module
|
||||
from parttool import * # import all names inside parttool module
|
||||
sys.path.append(parttool_dir) # this enables Python to find parttool module
|
||||
from parttool import * # import all names inside parttool module
|
||||
|
||||
The starting point for using the tool's Python API to do is create a `ParttoolTarget` object:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Create a parttool.py target device connected on serial port /dev/ttyUSB1
|
||||
target = ParttoolTarget("/dev/ttyUSB1")
|
||||
# Create a parttool.py target device connected on serial port /dev/ttyUSB1
|
||||
target = ParttoolTarget("/dev/ttyUSB1")
|
||||
|
||||
The created object can now be used to perform operations on the target device:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Erase partition with name 'storage'
|
||||
# Erase partition with name 'storage'
|
||||
target.erase_partition(PartitionName("storage"))
|
||||
|
||||
# Read partition with type 'data' and subtype 'spiffs' and save to file 'spiffs.bin'
|
||||
target.read_partition(PartitionType("data", "spiffs"), "spiffs.bin")
|
||||
# Read partition with type 'data' and subtype 'spiffs' and save to file 'spiffs.bin'
|
||||
target.read_partition(PartitionType("data", "spiffs"), "spiffs.bin")
|
||||
|
||||
# Write to partition 'factory' the contents of a file named 'factory.bin'
|
||||
target.write_partition(PartitionName("factory"), "factory.bin")
|
||||
# Write to partition 'factory' the contents of a file named 'factory.bin'
|
||||
target.write_partition(PartitionName("factory"), "factory.bin")
|
||||
|
||||
# Print the size of default boot partition
|
||||
storage = target.get_partition_info(PARTITION_BOOT_DEFAULT)
|
||||
print(storage.size)
|
||||
# Print the size of default boot partition
|
||||
storage = target.get_partition_info(PARTITION_BOOT_DEFAULT)
|
||||
print(storage.size)
|
||||
|
||||
The partition to operate on is specified using `PartitionName` or `PartitionType` or PARTITION_BOOT_DEFAULT. As the name implies, these can be used to refer to partitions of a particular name, type-subtype combination, or the default boot partition.
|
||||
|
||||
@@ -322,53 +337,54 @@ The command-line interface of `parttool.py` has the following structure:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
parttool.py [command-args] [subcommand] [subcommand-args]
|
||||
parttool.py [command-args] [subcommand] [subcommand-args]
|
||||
|
||||
- command-args - These are arguments that are needed for executing the main command (parttool.py), mostly pertaining to the target device
|
||||
- subcommand - This is the operation to be performed
|
||||
- subcommand-args - These are arguments that are specific to the chosen operation
|
||||
- command-args - These are arguments that are needed for executing the main command (parttool.py), mostly pertaining to the target device
|
||||
- subcommand - This is the operation to be performed
|
||||
- subcommand-args - These are arguments that are specific to the chosen operation
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Erase partition with name 'storage'
|
||||
parttool.py --port "/dev/ttyUSB1" erase_partition --partition-name=storage
|
||||
|
||||
# Read partition with type 'data' and subtype 'spiffs' and save to file 'spiffs.bin'
|
||||
parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs --output "spiffs.bin"
|
||||
|
||||
# Write to partition 'factory' the contents of a file named 'factory.bin'
|
||||
parttool.py --port "/dev/ttyUSB1" write_partition --partition-name=factory --input "factory.bin"
|
||||
|
||||
# Print the size of default boot partition
|
||||
parttool.py --port "/dev/ttyUSB1" get_partition_info --partition-boot-default --info size
|
||||
|
||||
.. 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.
|
||||
|
||||
::
|
||||
|
||||
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``.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Erase partition with name 'storage'
|
||||
# If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force"
|
||||
parttool.py --port "/dev/ttyUSB1" --esptool-erase-args=force erase_partition --partition-name=storage
|
||||
parttool.py --port "/dev/ttyUSB1" erase_partition --partition-name=storage
|
||||
|
||||
# Read partition with type 'data' and subtype 'spiffs' and save to file 'spiffs.bin'
|
||||
parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs --output "spiffs.bin"
|
||||
|
||||
# Write to partition 'factory' the contents of a file named 'factory.bin'
|
||||
# If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force"
|
||||
parttool.py --port "/dev/ttyUSB1" --esptool-erase-args=force write_partition --partition-name=factory --input "factory.bin"
|
||||
parttool.py --port "/dev/ttyUSB1" write_partition --partition-name=factory --input "factory.bin"
|
||||
|
||||
# Print the size of default boot partition
|
||||
parttool.py --port "/dev/ttyUSB1" get_partition_info --partition-boot-default --info size
|
||||
|
||||
.. 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.
|
||||
|
||||
.. 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``.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Erase partition with name 'storage'
|
||||
# If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force"
|
||||
parttool.py --port "/dev/ttyUSB1" --esptool-erase-args=force erase_partition --partition-name=storage
|
||||
|
||||
# Write to partition 'factory' the contents of a file named 'factory.bin'
|
||||
# If Flash Encryption or Secure Boot are enabled then add "--esptool-erase-args=force"
|
||||
parttool.py --port "/dev/ttyUSB1" --esptool-erase-args=force write_partition --partition-name=factory --input "factory.bin"
|
||||
|
||||
More information can be obtained by specifying `--help` as argument:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Display possible subcommands and show main command argument descriptions
|
||||
parttool.py --help
|
||||
# Display possible subcommands and show main command argument descriptions
|
||||
parttool.py --help
|
||||
|
||||
# Show descriptions for specific subcommand arguments
|
||||
parttool.py [subcommand] --help
|
||||
# Show descriptions for specific subcommand arguments
|
||||
parttool.py [subcommand] --help
|
||||
|
||||
.. _secure boot: security/secure-boot-v1.rst
|
||||
|
||||
@@ -107,4 +107,3 @@ ESP-IDF-CXX
|
||||
-----------
|
||||
|
||||
`ESP-IDF-CXX <https://github.com/espressif/esp-idf-cxx>`_ contains C++ wrappers for part of ESP-IDF. The focuses are on ease of use, safety, automatic resource management. They also move error checking from runtime to compile time to prevent running failure. There are C++ classes for ESP-Timer, I2C, SPI, GPIO and other peripherals or features of ESP-IDF. ESP-IDF-CXX is available as a component from `ESP Component Registry <https://components.espressif.com/components/espressif/esp-idf-cxx>`__. Please check the project's `README.md <https://github.com/espressif/esp-idf-cxx/blob/main/README.md>`_ for more information.
|
||||
|
||||
|
||||
@@ -8,64 +8,70 @@
|
||||
|
||||
每片 {IDF_TARGET_NAME} 的 flash 可以包含多个应用程序，以及多种不同类型的数据（例如校准数据、文件系统数据、参数存储数据等）。因此，我们在 flash 的 :ref:`默认偏移地址 <CONFIG_PARTITION_TABLE_OFFSET>` 0x8000 处烧写一张分区表。
|
||||
|
||||
分区表的长度为 0xC00 字节，最多可以保存 95 条分区表条目。MD5 校验和附加在分区表之后，用于在运行时验证分区表的完整性。分区表占据了整个 flash 扇区，大小为 0x1000 (4 KB)。因此，它后面的任何分区至少需要位于 (:ref:`默认偏移地址 <CONFIG_PARTITION_TABLE_OFFSET>`) + 0x1000 处。
|
||||
分区表的长度为 0xC00 字节，最多可以保存 95 条分区表条目。MD5 校验和附加在分区表之后，用于在运行时验证分区表的完整性。分区表占据了整个 flash 扇区，大小为 0x1000 (4 KB)。因此，它后面的任何分区至少需要位于（:ref:`默认偏移地址 <CONFIG_PARTITION_TABLE_OFFSET>`） + 0x1000 处。
|
||||
|
||||
分区表中的每个条目都包括以下几个部分：Name（标签）、Type（app、data 等）、SubType 以及在 flash 中的偏移量（分区的加载地址）。
|
||||
|
||||
在使用分区表时，最简单的方法就是打开项目配置菜单（``idf.py menuconfig``），并在 :ref:`CONFIG_PARTITION_TABLE_TYPE` 下选择一个预定义的分区表：
|
||||
在使用分区表时，最简单的方法就是打开项目配置菜单 (``idf.py menuconfig``)，并在 :ref:`CONFIG_PARTITION_TABLE_TYPE` 下选择一个预定义的分区表：
|
||||
|
||||
- "Single factory app, no OTA"
|
||||
- "Factory app, two OTA definitions"
|
||||
* "Single factory app, no OTA"
|
||||
* "Factory app, two OTA definitions"
|
||||
|
||||
在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 ``idf.py partition-table``，即可以打印当前使用分区表的信息摘要。
|
||||
|
||||
内置分区表
|
||||
------------
|
||||
----------
|
||||
|
||||
以下是 "Single factory app, no OTA" 选项的分区表信息摘要::
|
||||
以下是 "Single factory app, no OTA" 选项的分区表信息摘要：
|
||||
|
||||
# ESP-IDF Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x6000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
.. code-block:: none
|
||||
|
||||
- flash 的 0x10000 (64 KB) 偏移地址处存放一个标记为 "factory" 的二进制应用程序。引导加载程序默认加载这个应用程序。
|
||||
# ESP-IDF Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x6000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
|
||||
- flash 的 0x10000 (64 KB) 偏移地址处存放一个标记为 "factory" 的二进制应用程序，引导加载程序默认加载这个应用程序。
|
||||
- 分区表中还定义了两个数据区域，分别用于存储 NVS 库专用分区和 PHY 初始化数据。
|
||||
|
||||
以下是 "Factory app, two OTA definitions" 选项的分区表信息摘要::
|
||||
以下是 "Factory app, two OTA definitions" 选项的分区表信息摘要：
|
||||
|
||||
# ESP-IDF Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000,
|
||||
otadata, data, ota, 0xd000, 0x2000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
ota_0, app, ota_0, 0x110000, 1M,
|
||||
ota_1, app, ota_1, 0x210000, 1M,
|
||||
.. code-block:: none
|
||||
|
||||
- 分区表中定义了三个应用程序分区，这三个分区的类型都被设置为 “app”，但具体 app 类型不同。其中，位于 0x10000 偏移地址处的为出厂应用程序 (factory)，其余两个为 OTA 应用程序（ota_0，ota_1）。
|
||||
- 新增了一个名为 “otadata” 的数据分区，用于保存 OTA 升级时需要的数据。引导加载程序会查询该分区的数据，以判断该从哪个 OTA 应用程序分区加载程序。如果 “otadata” 分区为空，则会执行出厂程序。
|
||||
# ESP-IDF Partition Table
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000,
|
||||
otadata, data, ota, 0xd000, 0x2000,
|
||||
phy_init, data, phy, 0xf000, 0x1000,
|
||||
factory, app, factory, 0x10000, 1M,
|
||||
ota_0, app, ota_0, 0x110000, 1M,
|
||||
ota_1, app, ota_1, 0x210000, 1M,
|
||||
|
||||
* 分区表中定义了三个应用程序分区，这三个分区的类型都被设置为 “app”，但具体 app 类型不同。其中，位于 0x10000 偏移地址处的为出厂应用程序 (factory)，其余两个为 OTA 应用程序 (ota_0, ota_1)。
|
||||
* 新增了一个名为 "otadata" 的数据分区，用于保存 OTA 升级时需要的数据。引导加载程序会查询该分区的数据，以判断该从哪个 OTA 应用程序分区加载程序。如果 "otadata" 分区为空，则会执行出厂程序。
|
||||
|
||||
创建自定义分区表
|
||||
----------------
|
||||
|
||||
如果在 ``menuconfig`` 中选择了 “Custom partition table CSV”，则还需要输入该分区表的 CSV 文件在项目中的路径。CSV 文件可以根据需要，描述任意数量的分区信息。
|
||||
如果在 ``menuconfig`` 中选择了 "Custom partition table CSV"，则还需要输入该分区表的 CSV 文件在项目中的路径。CSV 文件可以根据需要，描述任意数量的分区信息。
|
||||
|
||||
CSV 文件的格式与上面摘要中打印的格式相同，但是在 CSV 文件中并非所有字段都是必需的。例如下面是一个自定义的 OTA 分区表的 CSV 文件::
|
||||
CSV 文件的格式与上面摘要中打印的格式相同，但是在 CSV 文件中并非所有字段都是必需的。例如下面是一个自定义的 OTA 分区表的 CSV 文件：
|
||||
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000
|
||||
otadata, data, ota, 0xd000, 0x2000
|
||||
phy_init, data, phy, 0xf000, 0x1000
|
||||
factory, app, factory, 0x10000, 1M
|
||||
ota_0, app, ota_0, , 1M
|
||||
ota_1, app, ota_1, , 1M
|
||||
nvs_key, data, nvs_keys, , 0x1000
|
||||
.. code-block:: none
|
||||
|
||||
- 字段之间的空格会被忽略，任何以 ``#`` 开头的行（注释）也会被忽略。
|
||||
- CSV 文件中的每个非注释行均为一个分区定义。
|
||||
- 每个分区的 ``Offset`` 字段可以为空，``gen_esp32part.py`` 工具会从分区表位置的后面开始自动计算并填充该分区的偏移地址，同时确保每个分区的偏移地址正确对齐。
|
||||
# Name, Type, SubType, Offset, Size, Flags
|
||||
nvs, data, nvs, 0x9000, 0x4000
|
||||
otadata, data, ota, 0xd000, 0x2000
|
||||
phy_init, data, phy, 0xf000, 0x1000
|
||||
factory, app, factory, 0x10000, 1M
|
||||
ota_0, app, ota_0, , 1M
|
||||
ota_1, app, ota_1, , 1M
|
||||
nvs_key, data, nvs_keys, , 0x1000
|
||||
|
||||
* 字段之间的空格会被忽略，任何以 ``#`` 开头的行（注释）也会被忽略。
|
||||
* CSV 文件中的每个非注释行均为一个分区定义。
|
||||
* 每个分区的 ``Offset`` 字段可以为空，``gen_esp32part.py`` 工具会从分区表位置的后面开始自动计算并填充该分区的偏移地址，同时确保每个分区的偏移地址正确对齐。
|
||||
|
||||
Name 字段
|
||||
~~~~~~~~~
|
||||
@@ -75,13 +81,19 @@ Name 字段可以是任何有意义的名称，但不能超过 16 个字节，
|
||||
Type 字段
|
||||
~~~~~~~~~
|
||||
|
||||
Type 字段可以指定为 app (0x00) 或者 data (0x01)，也可以直接使用数字 0-254（或者十六进制 0x00-0xFE）。注意，0x00-0x3F 不得使用（预留给 esp-idf 的核心功能）。
|
||||
Type 字段可以指定为名称或数字 0～254（或者十六进制 0x00-0xFE）。注意，不得使用预留给 ESP-IDF 核心功能的 0x00-0x3F。
|
||||
|
||||
如果你的应用程序需要以 ESP-IDF 尚未支持的格式存储数据，请在 0x40-0xFE 内添加一个自定义分区类型。
|
||||
- ``app`` (0x00)。
|
||||
- ``data`` (0x01)。
|
||||
- ``bootloader`` (0x02)。该分区为可选项且不会影响系统功能，因此默认情况下，该分区不会出现在任何 CSV 分区表文件中，仅在引导加载程序 OTA 更新时有用。即使 CSV 文件中没有该分区，仍然可以执行 OTA。请注意，如果在 CSV 文件中指定了该分区，其地址和大小必须与 Kconfig 设置相匹配。
|
||||
- ``partition_table`` (0x03)。
|
||||
- 0x40-0xFE 预留给 **自定义分区类型**。如果你的应用程序需要以 ESP-IDF 尚未支持的格式存储数据，请在 0x40-0xFE 内添加一个自定义分区类型。
|
||||
|
||||
参考 :cpp:type:`esp_partition_type_t` 关于 ``app`` 和 ``data`` 分区的枚举定义。
|
||||
关于 ``app`` 和 ``data`` 分区的枚举定义，请参考 :cpp:type:`esp_partition_type_t`。
|
||||
|
||||
如果用 C++ 编写，那么指定一个应用程序定义的分区类型，需要在 :cpp:type:`esp_partition_type_t` 中使用整数，从而与 :ref:`分区 API<api-reference-partition-table>` 一起使用。例如::
|
||||
如果用 C++ 编写，那么指定一个应用程序定义的分区类型，需要在 :cpp:type:`esp_partition_type_t` 中使用整数，从而与 :ref:`分区 API<api-reference-partition-table>` 一起使用。例如：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
static const esp_partition_type_t APP_PARTITION_TYPE_A = (esp_partition_type_t)0x40;
|
||||
|
||||
@@ -89,61 +101,72 @@ Type 字段可以指定为 app (0x00) 或者 data (0x01)，也可以直接使用
|
||||
|
||||
SubType 字段
|
||||
~~~~~~~~~~~~
|
||||
{IDF_TARGET_ESP_PHY_REF:default = ":ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`", esp32p4, esp32c5, esp32c61 = "NOT UPDATED YET"}
|
||||
|
||||
SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，esp-idf 仅仅规定了 “app” 和 “data” 两种分区类型的子类型含义。
|
||||
{IDF_TARGET_ESP_PHY_REF:default = ":ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`", esp32p4, esp32c5, esp32c61 = "尚未更新"}
|
||||
|
||||
SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，ESP-IDF 仅仅规定了 ``app`` 和 ``data`` 两种分区类型的子类型含义。
|
||||
|
||||
参考 :cpp:type:`esp_partition_subtype_t`，以了解 ESP-IDF 定义的全部子类型列表，包括：
|
||||
|
||||
* 当 Type 定义为 ``app`` 时，SubType 字段可以指定为 ``factory`` (0x00)、 ``ota_0`` (0x10) … ``ota_15`` (0x1F) 或者 ``test`` (0x20)。
|
||||
|
||||
- ``factory`` (0x00) 是默认的 app 分区。引导加载程序默认加载该应用程序。但如果存在类型为 data/ota 的分区，则引导加载程序将加载 data/ota 分区中的数据，进而判断启动哪个 OTA 镜像文件。
|
||||
- ``factory`` (0x00) 是默认的 app 分区。引导加载程序将默认加载该应用程序。但如果存在类型为 data/ota 的分区，则引导加载程序将加载 data/ota 分区中的数据，进而判断启动哪个 OTA 镜像文件。
|
||||
|
||||
- OTA 升级永远都不会更新 factory 分区中的内容。
|
||||
- 如果你希望在 OTA 项目中预留更多 flash，可以删除 factory 分区，转而使用 ota_0 分区。
|
||||
- OTA 升级永远都不会更新 factory 分区中的内容。
|
||||
- 如果你希望在 OTA 项目中预留更多 flash，可以删除 factory 分区，转而使用 ota_0 分区。
|
||||
|
||||
- ota_0 (0x10) … ota_15 (0x1F) 为 OTA 应用程序分区，引导加载程序将根据 OTA 数据分区中的数据来决定加载哪个 OTA 应用程序分区中的程序。在使用 OTA 功能时，应用程序应至少拥有 2 个 OTA 应用程序分区（``ota_0`` 和 ``ota_1``）。更多详细信息，请参考 :doc:`OTA 文档 </api-reference/system/ota>` 。
|
||||
- ``test`` (0x20) 为预留的子类型，用于工厂测试流程。如果没有其他有效 app 分区，test 将作为备选启动分区使用。也可以配置引导加载程序在每次启动时读取 GPIO，如果 GPIO 被拉低则启动该分区。详细信息请查阅 :ref:`bootloader_boot_from_test_firmware`。
|
||||
- ``ota_0`` (0x10) … ``ota_15`` (0x1F) 为 OTA 应用程序分区，引导加载程序将根据 OTA 数据分区中的数据来决定加载哪个 OTA 应用程序分区中的程序。在使用 OTA 功能时，应用程序应至少拥有 2 个 OTA 应用程序分区（``ota_0`` 和 ``ota_1``）。更多详细信息，请参考 :doc:`OTA 文档 </api-reference/system/ota>`。
|
||||
- ``test`` (0x20) 为预留的子类型，用于工厂测试流程。如果没有其他有效 app 分区，test 将作为备选启动分区使用。也可以配置引导加载程序在每次启动时读取 GPIO，如果 GPIO 被拉低则启动该分区。详细信息请查阅 :ref:`bootloader_boot_from_test_firmware`。
|
||||
|
||||
* 当 Type 定义为 ``bootloader`` 时，可以将 SubType 字段指定为：
|
||||
|
||||
- ``primary`` (0x00)，即二级引导加载程序，放置在 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 地址处。目前 ``gen_esp32part.py`` 不支持在 CSV 文件中包含该分区。
|
||||
- ``ota`` (0x01)，是一个临时的引导加载程序分区，在 OTA 更新期间可用于下载新的引导加载程序镜像。
|
||||
|
||||
* 当 Type 定义为 ``partition_table`` 时，可以将 SubType 字段指定为：
|
||||
|
||||
- ``primary`` (0x00)。这是主分区表，放置在 flash 的 :ref:`CONFIG_PARTITION_TABLE_OFFSET` 地址处。目前 ``gen_esp32part.py`` 不支持在 CSV 文件中包含该分区。
|
||||
- ``ota`` (0x01)。这是一个临时的分区表分区，在 OTA 更新期间可用于下载新的分区表镜像。
|
||||
|
||||
* 当 Type 定义为 ``data`` 时，SubType 字段可以指定为 ``ota`` (0x00)、``phy`` (0x01)、``nvs`` (0x02)、``nvs_keys`` (0x04) 或者其他组件特定的子类型（请参考 :cpp:type:`子类型枚举 <esp_partition_subtype_t>`).
|
||||
|
||||
- ``ota`` (0) 即 :ref:`OTA 数据分区 <ota_data_partition>` ，用于存储当前所选的 OTA 应用程序的信息。这个分区的大小需要设定为 0x2000。更多详细信息，请参考 :doc:`OTA 文档 <../api-reference/system/ota>` 。
|
||||
- ``phy`` (1) 分区用于存放 PHY 初始化数据，从而保证可以为每个设备单独配置 PHY，而非必须采用固件中的统一 PHY 初始化数据。
|
||||
- ``ota`` (0) 即 :ref:`OTA 数据分区 <ota_data_partition>` ，用于存储当前所选的 OTA 应用程序的信息。这个分区的大小需要设定为 0x2000。更多详细信息，请参考 :doc:`OTA 文档 <../api-reference/system/ota>` 。
|
||||
- ``phy`` (1) 分区用于存放 PHY 初始化数据，从而保证可以为每个设备单独配置 PHY，而非必须采用固件中的统一 PHY 初始化数据。
|
||||
|
||||
- 默认配置下，phy 分区并不启用，而是直接将 phy 初始化数据编译至应用程序中，从而节省分区表空间（直接将此分区删掉）。
|
||||
- 如果需要从此分区加载 phy 初始化数据，请打开项目配置菜单（``idf.py menuconfig``），并且使能 {IDF_TARGET_ESP_PHY_REF} 选项。此时，还需要手动将 phy 初始化数据烧至设备 flash（esp-idf 编译系统并不会自动完成该操作）。
|
||||
- ``nvs`` (2) 是专门给 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 使用的分区。
|
||||
- 默认配置下，phy 分区并不启用，而是直接将 phy 初始化数据编译至应用程序中，从而节省分区表空间（直接将此分区删掉）。
|
||||
- 如果需要从此分区加载 phy 初始化数据，请打开项目配置菜单（``idf.py menuconfig``），并且使能 {IDF_TARGET_ESP_PHY_REF} 选项。此时，还需要手动将 phy 初始化数据烧至设备 flash（esp-idf 编译系统并不会自动完成该操作）。
|
||||
- ``nvs`` (2) 是专门给 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 使用的分区。
|
||||
|
||||
- 用于存储每台设备的 PHY 校准数据（注意，并不是 PHY 初始化数据）。
|
||||
- 用于存储每台设备的 PHY 校准数据（注意，并不是 PHY 初始化数据）。
|
||||
|
||||
.. only:: SOC_WIFI_SUPPORTED
|
||||
.. only:: SOC_WIFI_SUPPORTED
|
||||
|
||||
- 用于存储 Wi-Fi 数据（如果使用了 :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/network/esp_wifi>` 初始化函数）。
|
||||
- 用于存储 Wi-Fi 数据（如果使用了 :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/network/esp_wifi>` 初始化函数）。
|
||||
|
||||
- NVS API 还可以用于其他应用程序数据。
|
||||
- 强烈建议为 NVS 分区分配至少 0x3000 字节空间。
|
||||
- 如果使用 NVS API 存储大量数据，请增加 NVS 分区的大小（默认是 0x6000 字节）。
|
||||
- ``nvs_keys`` (4) 是 NVS 秘钥分区。详细信息，请参考 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 文档。
|
||||
- NVS API 还可以用于其他应用程序数据。
|
||||
- 强烈建议为 NVS 分区分配至少 0x3000 字节空间。
|
||||
- 如果使用 NVS API 存储大量数据，请增加 NVS 分区的大小（默认是 0x6000 字节）。
|
||||
- ``nvs_keys`` (4) 是 NVS 秘钥分区。详细信息，请参考 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 文档。
|
||||
|
||||
- 用于存储加密密钥（如果启用了 `NVS 加密` 功能）。
|
||||
- 此分区应至少设定为 4096 字节。
|
||||
- 用于存储加密密钥（如果启用了 `NVS 加密` 功能）。
|
||||
- 此分区应至少设定为 4096 字节。
|
||||
|
||||
- ESP-IDF 还支持其他用于数据存储的预定义子类型，包括：
|
||||
- ESP-IDF 还支持其他用于数据存储的预定义子类型，包括：
|
||||
|
||||
- ``coredump`` (0x03) 用于在使用自定义分区表 CSV 文件时存储核心转储，详情请参阅 :doc:`/api-guides/core_dump`。
|
||||
- ``efuse`` (0x05) 使用 :ref:`虚拟 eFuse <virtual-efuses>` 模拟 eFuse 位。
|
||||
- ``undefined`` (0x06) 隐式用于未指定子类型（即子类型为空）的数据分区，但也可显式将其标记为未定义。
|
||||
- ``fat`` (0x81) 用于 :doc:`/api-reference/storage/fatfs`。
|
||||
- ``spiffs`` (0x82) 用于 :doc:`/api-reference/storage/spiffs`。
|
||||
- ``littlefs`` (0x83) 用于 `LittleFS 文件系统 <https://github.com/littlefs-project/littlefs>`_，详情可参阅 :example:`storage/littlefs` 示例。
|
||||
- ``coredump`` (0x03) 用于在使用自定义分区表 CSV 文件时存储核心转储，详情请参阅 :doc:`/api-guides/core_dump`。
|
||||
- ``efuse`` (0x05) 使用 :ref:`虚拟 eFuse <virtual-efuses>` 模拟 eFuse 位。
|
||||
- ``undefined`` (0x06) 隐式用于未指定子类型（即子类型为空）的数据分区，但也可显式将其标记为未定义。
|
||||
- ``fat`` (0x81) 用于 :doc:`/api-reference/storage/fatfs`。
|
||||
- ``spiffs`` (0x82) 用于 :doc:`/api-reference/storage/spiffs`。
|
||||
- ``littlefs`` (0x83) 用于 `LittleFS 文件系统 <https://github.com/littlefs-project/littlefs>`_，详情可参阅 :example:`storage/littlefs` 示例。
|
||||
|
||||
.. Comment: ``esphttpd`` (0x80) was not added to the list because there is no docs section for it and it is not clear whether user should use it explicitly.
|
||||
|
||||
其它数据子类型已预留给 ESP-IDF 未来使用。
|
||||
其它数据子类型已预留给 ESP-IDF 未来使用。
|
||||
|
||||
* 如果分区类型是由应用程序定义的任意值 (0x40-0xFE)，那么 ``subtype`` 字段可以是由应用程序选择的任何值 (0x00-0xFE)。
|
||||
|
||||
请注意，如果用 C++ 编写，应用程序定义的子类型值需要转换为 :cpp:type:`esp_partition_type_t`，从而与 :ref:`分区 API <api-reference-partition-table>` 一起使用。
|
||||
请注意，如果用 C++ 编写，应用程序定义的子类型值需要转换为 :cpp:type:`esp_partition_type_t`，从而与 :ref:`分区 API <api-reference-partition-table>` 一起使用。
|
||||
|
||||
额外分区 SubType 字段
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -152,17 +175,17 @@ SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，esp
|
||||
|
||||
.. _partition-offset-and-size:
|
||||
|
||||
偏移地址 (Offset) 和 大小 (Size) 字段
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
偏移地址 (Offset) 和大小 (Size) 字段
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list::
|
||||
|
||||
- 偏移地址表示 SPI flash 中的分区地址，扇区大小为 0x1000 (4 KB)。因此，偏移地址必须是 4 KB 的倍数。
|
||||
- 若 CSV 文件中的分区偏移地址为空，则该分区会接在前一个分区之后；若为首个分区，则将接在分区表之后。
|
||||
- ``app`` 分区的偏移地址必须与 0x10000 (64 KB) 对齐。如果偏移字段留空，则 ``gen_esp32part.py`` 工具会自动计算得到一个满足对齐要求的偏移地址。如果 ``app`` 分区的偏移地址没有与 0x10000 (64 KB) 对齐，则该工具会报错。
|
||||
- ``app`` 分区的大小必须与 flash 扇区大小对齐。为 ``app`` 分区指定未对齐的大小将返回错误。
|
||||
:SOC_SECURE_BOOT_V1: - 若启用了安全启动 V1，则 ``app`` 分区的大小需与 0x10000 (64 KB) 对齐。
|
||||
- ``app`` 分区的大小和偏移地址可以采用十进制数或是以 0x 为前缀的十六进制数，且支持 K 或 M 的倍数单位（K 和 M 分别代表 1024 和 1024*1024 字节）。
|
||||
- 偏移地址表示 SPI flash 中的分区地址，扇区大小为 0x1000 (4 KB)。因此，偏移地址必须是 4 KB 的倍数。
|
||||
- 若 CSV 文件中的分区偏移地址为空，则该分区会接在前一个分区之后；若为首个分区，则将接在分区表之后。
|
||||
- ``app`` 分区的偏移地址必须与 0x10000 (64 KB) 对齐。如果偏移字段留空，则 ``gen_esp32part.py`` 工具会自动计算得到一个满足对齐要求的偏移地址。如果 ``app`` 分区的偏移地址没有与 0x10000 (64 KB) 对齐，则该工具会报错。
|
||||
- ``app`` 分区的大小必须与 flash 扇区大小对齐。为 ``app`` 分区指定未对齐的大小将返回错误。
|
||||
:SOC_SECURE_BOOT_V1: - 若启用了安全启动 V1，则 ``app`` 分区的大小需与 0x10000 (64 KB) 对齐。
|
||||
- ``app`` 分区的大小和偏移地址可以采用十进制数或是以 0x 为前缀的十六进制数，且支持 K 或 M 的倍数单位（K 和 M 分别代表 1024 和 1024*1024 字节）。
|
||||
|
||||
如果你希望允许分区表中的分区采用任意起始偏移量 (:ref:`CONFIG_PARTITION_TABLE_OFFSET`)，请将分区表（CSV 文件）中所有分区的偏移字段都留空。注意，此时，如果你更改了分区表中任意分区的偏移地址，则其他分区的偏移地址也会跟着改变。这种情况下，如果你之前还曾设定某个分区采用固定偏移地址，则可能造成分区表冲突，从而导致报错。
|
||||
|
||||
@@ -171,17 +194,17 @@ Flags 字段
|
||||
|
||||
目前支持 ``encrypted`` 和 ``readonly`` 标记：
|
||||
|
||||
- 如果 Flags 字段设置为 ``encrypted``，且已启用 :doc:`/security/flash-encryption` 功能，则该分区将会被加密。
|
||||
- 如果 Flags 字段设置为 ``encrypted``，且已启用 :doc:`/security/flash-encryption` 功能，则该分区将会被加密。
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
无论是否设置 Flags 字段，``app`` 分区都将保持加密。
|
||||
无论是否设置 Flags 字段，``app`` 分区都将保持加密。
|
||||
|
||||
- 如果 Flags 字段设置为 ``readonly``，则该分区为只读分区。``readonly`` 标记仅支持除 ``ota`` 和 ``coredump`` 子类型外的 ``data`` 分区。使用该标记，防止意外写入如出厂数据分区等包含关键设备特定配置数据的分区。
|
||||
- 如果 Flags 字段设置为 ``readonly``，则该分区为只读分区。``readonly`` 标记仅支持除 ``ota`` 和 ``coredump`` 子类型外的 ``data`` 分区。使用该标记，防止意外写入如出厂数据分区等包含关键设备特定配置数据的分区。
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
在任何写入模式下 (``w``、``w+``、``a``、``a+``、``r+``)，尝试通过 C 文件 I/O API 打开文件 (``fopen```) 的操作都将失败并返回 ``NULL``。除 ``O_RDONLY`` 外，``open`` 与任何标志一同使用都将失败并返回 ``-1``，全局变量 ``errno`` 也将设置为 ``EROFS``。上述情况同样适用于通过其他 POSIX 系统调用函数执行写入或擦除的操作。在只读分区上，以读写模式打开 NVS 的句柄将失败并返回 :c:macro:`ESP_ERR_NOT_ALLOWED` 错误代码，使用 ``esp_partition`` 或 ``spi_flash`` 等较低级别的 API 进行写入操作也将返回 :c:macro:`ESP_ERR_NOT_ALLOWED` 错误代码。
|
||||
在任何写入模式下 (``w``、``w+``、``a``、``a+``、``r+``)，尝试通过 C 文件 I/O API 打开文件 (``fopen```) 的操作都将失败并返回 ``NULL``。除 ``O_RDONLY`` 外，``open`` 与任何标志一同使用都将失败并返回 ``-1``，全局变量 ``errno`` 也将设置为 ``EROFS``。上述情况同样适用于通过其他 POSIX 系统调用函数执行写入或擦除的操作。在只读分区上，以读写模式打开 NVS 的句柄将失败并返回 :c:macro:`ESP_ERR_NOT_ALLOWED` 错误代码，使用 ``esp_partition`` 或 ``spi_flash`` 等较低级别的 API 进行写入操作也将返回 :c:macro:`ESP_ERR_NOT_ALLOWED` 错误代码。
|
||||
|
||||
可以使用冒号连接不同的标记，来同时指定多个标记，如 ``encrypted:readonly``。
|
||||
|
||||
@@ -192,20 +215,26 @@ Flags 字段
|
||||
|
||||
如果你在项目配置菜单（``idf.py menuconfig``）中设置了分区表 CSV 文件的名称，然后构建项目或执行 ``idf.py partition-table``。这时，转换将在编译过程中自动完成。
|
||||
|
||||
手动将 CSV 文件转换为二进制文件::
|
||||
手动将 CSV 文件转换为二进制文件：
|
||||
|
||||
python gen_esp32part.py input_partitions.csv binary_partitions.bin
|
||||
.. code-block:: none
|
||||
|
||||
手动将二进制文件转换为 CSV 文件::
|
||||
python gen_esp32part.py input_partitions.csv binary_partitions.bin
|
||||
|
||||
python gen_esp32part.py binary_partitions.bin input_partitions.csv
|
||||
手动将二进制文件转换为 CSV 文件：
|
||||
|
||||
在标准输出 (stdout) 上，打印二进制分区表的内容（运行 ``idf.py partition-table`` 时展示的信息摘要也是这样生成的）::
|
||||
.. code-block:: none
|
||||
|
||||
python gen_esp32part.py binary_partitions.bin
|
||||
python gen_esp32part.py binary_partitions.bin input_partitions.csv
|
||||
|
||||
在标准输出 (stdout) 上，打印二进制分区表的内容（运行 ``idf.py partition-table`` 时展示的信息摘要也是这样生成的）：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
python gen_esp32part.py binary_partitions.bin
|
||||
|
||||
分区大小检查
|
||||
---------------------
|
||||
------------
|
||||
|
||||
ESP-IDF 构建系统将自动检查生成的二进制文件大小与可用的分区大小是否匹配，如果二进制文件太大，则会构建失败并报错。
|
||||
|
||||
@@ -216,7 +245,7 @@ ESP-IDF 构建系统将自动检查生成的二进制文件大小与可用的分
|
||||
|
||||
.. note::
|
||||
|
||||
即使分区大小检查返回错误并导致构建失败，仍然会生成可以烧录的二进制文件（它们对于可用空间来说过大，因此无法正常工作）。
|
||||
即使分区大小检查返回错误并导致构建失败，仍然会生成可以烧录的二进制文件（它们对于可用空间来说过大，因此无法正常工作）。
|
||||
|
||||
MD5 校验和
|
||||
~~~~~~~~~~
|
||||
@@ -225,7 +254,7 @@ MD5 校验和
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
用户可通过 ``gen_esp32part.py`` 的 ``--disable-md5sum`` 选项或者 :ref:`CONFIG_PARTITION_TABLE_MD5` 选项关闭 MD5 校验。对于 :ref:`ESP-IDF v3.1 版本前的引导加载程序 <CONFIG_APP_COMPATIBLE_PRE_V3_1_BOOTLOADERS>`，因为它不支持 MD5 校验，所以无法正常启动并报错 ``invalid magic number 0xebeb``，此时用户可以使用此选项关闭 MD5 校验。
|
||||
用户可通过 ``gen_esp32part.py`` 的 ``--disable-md5sum`` 选项或者 :ref:`CONFIG_PARTITION_TABLE_MD5` 选项关闭 MD5 校验。对于 :ref:`ESP-IDF v3.1 版本前的引导加载程序 <CONFIG_APP_COMPATIBLE_PRE_V3_1_BOOTLOADERS>`，因为它不支持 MD5 校验，所以无法正常启动并报错 ``invalid magic number 0xebeb``，此时用户可以使用此选项关闭 MD5 校验。
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
@@ -235,67 +264,67 @@ MD5 校验和
|
||||
烧写分区表
|
||||
----------
|
||||
|
||||
- ``idf.py partition-table-flash`` ：使用 esptool.py 工具烧写分区表。
|
||||
- ``idf.py flash`` ：会烧写所有内容，包括分区表。
|
||||
* ``idf.py partition-table-flash`` ：使用 esptool.py 工具烧写分区表。
|
||||
* ``idf.py flash`` ：会烧写所有内容，包括分区表。
|
||||
|
||||
在执行 ``idf.py partition-table`` 命令时，手动烧写分区表的命令也将打印在终端上。
|
||||
|
||||
.. note::
|
||||
|
||||
分区表的更新并不会擦除根据旧分区表存储的数据。此时，可以使用 ``idf.py erase-flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。
|
||||
分区表的更新并不会擦除根据旧分区表存储的数据。此时，可以使用 ``idf.py erase-flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。
|
||||
|
||||
|
||||
分区工具 (``parttool.py``)
|
||||
---------------------------
|
||||
--------------------------
|
||||
|
||||
`partition_table` 组件中有分区工具 :component_file:`parttool.py<partition_table/parttool.py>`，可以在目标设备上完成分区相关操作。该工具有如下用途：
|
||||
|
||||
- 读取分区，将内容存储到文件中 (read_partition)
|
||||
- 将文件中的内容写至分区 (write_partition)
|
||||
- 擦除分区 (erase_partition)
|
||||
- 检索特定分区的名称、偏移、大小和 flag（“加密”）标志等信息 (get_partition_info)
|
||||
- 读取分区，将内容存储到文件中 (read_partition)
|
||||
- 将文件中的内容写至分区 (write_partition)
|
||||
- 擦除分区 (erase_partition)
|
||||
- 检索特定分区的名称、偏移、大小和 flag（“加密”）标志等信息 (get_partition_info)
|
||||
|
||||
用户若想通过编程方式完成相关操作，可从另一个 Python 脚本导入并使用分区工具，或者从 Shell 脚本调用分区工具。前者可使用工具的 Python API，后者可使用命令行界面。
|
||||
|
||||
Python API
|
||||
~~~~~~~~~~~
|
||||
~~~~~~~~~~
|
||||
|
||||
首先请确保已导入 `parttool` 模块。
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import sys
|
||||
import os
|
||||
import sys
|
||||
import os
|
||||
|
||||
idf_path = os.environ["IDF_PATH"] # 从环境中获取 IDF_PATH 的值
|
||||
parttool_dir = os.path.join(idf_path, "components", "partition_table") # parttool.py 位于 $IDF_PATH/components/partition_table 下
|
||||
idf_path = os.environ["IDF_PATH"] # 从环境中获取 IDF_PATH 的值
|
||||
parttool_dir = os.path.join(idf_path, "components", "partition_table") # parttool.py 位于 $IDF_PATH/components/partition_table 下
|
||||
|
||||
sys.path.append(parttool_dir) # 使能 Python 寻找 parttool 模块
|
||||
from parttool import * # 导入 parttool 模块内的所有名称
|
||||
sys.path.append(parttool_dir) # 使能 Python 寻找 parttool 模块
|
||||
from parttool import * # 导入 parttool 模块内的所有名称
|
||||
|
||||
要使用分区工具的 Python API，第一步是创建 `ParttoolTarget`：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# 创建 parttool.py 的目标设备，并将目标设备连接到串行端口 /dev/ttyUSB1
|
||||
target = ParttoolTarget("/dev/ttyUSB1")
|
||||
# 创建 parttool.py 的目标设备，并将目标设备连接到串行端口 /dev/ttyUSB1
|
||||
target = ParttoolTarget("/dev/ttyUSB1")
|
||||
|
||||
现在，可使用创建的 `ParttoolTarget` 在目标设备上完成操作：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# 擦除名为 'storage' 的分区
|
||||
target.erase_partition(PartitionName("storage"))
|
||||
# 擦除名为 'storage' 的分区
|
||||
target.erase_partition(PartitionName("storage"))
|
||||
|
||||
# 读取类型为 'data'、子类型为 'spiffs' 的分区，保存至文件 'spiffs.bin'
|
||||
target.read_partition(PartitionType("data", "spiffs"), "spiffs.bin")
|
||||
# 读取类型为 'data'、子类型为 'spiffs' 的分区，保存至文件 'spiffs.bin'
|
||||
target.read_partition(PartitionType("data", "spiffs"), "spiffs.bin")
|
||||
|
||||
# 将 'factory.bin' 文件的内容写至 'factory' 分区
|
||||
target.write_partition(PartitionName("factory"), "factory.bin")
|
||||
# 将 'factory.bin' 文件的内容写至 'factory' 分区
|
||||
target.write_partition(PartitionName("factory"), "factory.bin")
|
||||
|
||||
# 打印默认启动分区的大小
|
||||
storage = target.get_partition_info(PARTITION_BOOT_DEFAULT)
|
||||
print(storage.size)
|
||||
# 打印默认启动分区的大小
|
||||
storage = target.get_partition_info(PARTITION_BOOT_DEFAULT)
|
||||
print(storage.size)
|
||||
|
||||
使用 `PartitionName`、`PartitionType` 或 PARTITION_BOOT_DEFAULT 指定要操作的分区。顾名思义，这三个参数可以指向拥有特定名称的分区、特定类型和子类型的分区或默认启动分区。
|
||||
|
||||
@@ -308,44 +337,45 @@ Python API
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
parttool.py [command-args] [subcommand] [subcommand-args]
|
||||
parttool.py [command-args] [subcommand] [subcommand-args]
|
||||
|
||||
- command-args - 执行主命令 (parttool.py) 所需的实际参数，多与目标设备有关
|
||||
- subcommand - 要执行的操作
|
||||
- subcommand-args - 所选操作的实际参数
|
||||
- command-args - 执行主命令 (parttool.py) 所需的实际参数，多与目标设备有关
|
||||
- subcommand - 要执行的操作
|
||||
- subcommand-args - 所选操作的实际参数
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# 擦除名为 'storage' 的分区
|
||||
parttool.py --port "/dev/ttyUSB1" erase_partition --partition-name=storage
|
||||
# 擦除名为 'storage' 的分区
|
||||
parttool.py --port "/dev/ttyUSB1" erase_partition --partition-name=storage
|
||||
|
||||
# 读取类型为 'data'、子类型为 'spiffs' 的分区，保存到 'spiffs.bin' 文件
|
||||
parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs --output "spiffs.bin"
|
||||
# 读取类型为 'data'、子类型为 'spiffs' 的分区，保存到 'spiffs.bin' 文件
|
||||
parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs --output "spiffs.bin"
|
||||
|
||||
# 将 'factory.bin' 文件中的内容写入到 'factory' 分区
|
||||
parttool.py --port "/dev/ttyUSB1" write_partition --partition-name=factory --input "factory.bin"
|
||||
# 将 'factory.bin' 文件中的内容写入到 'factory' 分区
|
||||
parttool.py --port "/dev/ttyUSB1" write_partition --partition-name=factory --input "factory.bin"
|
||||
|
||||
# 打印默认启动分区的大小
|
||||
parttool.py --port "/dev/ttyUSB1" get_partition_info --partition-boot-default --info size
|
||||
# 打印默认启动分区的大小
|
||||
parttool.py --port "/dev/ttyUSB1" get_partition_info --partition-boot-default --info size
|
||||
|
||||
.. note::
|
||||
如果设备启用了 ``Flash Encryption`` 或 ``Secure Boot``，尝试使用修改 flash 内容的命令（如 ``erase_partition`` 或 ``write_partition``）会导致错误。这是因为 ``esptool.py`` 的擦除命令会在写入之前先被调用。这个“错误”实际上是一个用来防止设备变砖的安全措施。
|
||||
|
||||
::
|
||||
如果设备启用了 ``Flash Encryption`` 或 ``Secure Boot``，尝试使用修改 flash 内容的命令（如 ``erase_partition`` 或 ``write_partition``）会导致错误。这是因为 ``esptool.py`` 的擦除命令会在写入之前先被调用。这个“错误”实际上是一个用来防止设备变砖的安全措施。
|
||||
|
||||
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!
|
||||
.. code-block:: none
|
||||
|
||||
要解决此问题，需在运行 ``esptool.py`` 时使用 ``--force`` 参数。具体而言，``parttool.py`` 提供了 ``--esptool-erase-args`` 参数，用来将 ``--force`` 参数传递给 ``esptool.py``。
|
||||
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!
|
||||
|
||||
.. code-block:: bash
|
||||
要解决此问题，需在运行 ``esptool.py`` 时使用 ``--force`` 参数。具体而言，``parttool.py`` 提供了 ``--esptool-erase-args`` 参数，用来将 ``--force`` 参数传递给 ``esptool.py``。
|
||||
|
||||
# 擦除名为 'storage' 的分区
|
||||
# 如果启用了 Flash Encryption 或 Secure Boot，则添加 "--esptool-erase-args=force"
|
||||
parttool.py --port "/dev/ttyUSB1" --esptool-erase-args=force erase_partition --partition-name=storage
|
||||
.. code-block:: bash
|
||||
|
||||
# 将名为 'factory.bin' 的文件内容写入 'factory' 分区
|
||||
# 如果启用了 Flash Encryption 或 Secure Boot，则添加 "--esptool-erase-args=force"
|
||||
parttool.py --port "/dev/ttyUSB1" --esptool-erase-args=force write_partition --partition-name=factory --input "factory.bin"
|
||||
# 擦除名为 'storage' 的分区
|
||||
# 如果启用了 Flash Encryption 或 Secure Boot，则添加 "--esptool-erase-args=force"
|
||||
parttool.py --port "/dev/ttyUSB1" --esptool-erase-args=force erase_partition --partition-name=storage
|
||||
|
||||
# 将名为 'factory.bin' 的文件内容写入 'factory' 分区
|
||||
# 如果启用了 Flash Encryption 或 Secure Boot，则添加 "--esptool-erase-args=force"
|
||||
parttool.py --port "/dev/ttyUSB1" --esptool-erase-args=force write_partition --partition-name=factory --input "factory.bin"
|
||||
|
||||
更多信息可用 `--help` 指令查看：
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
其他库和开发框架
|
||||
=============================
|
||||
================
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本文展示了一系列乐鑫官方发布的库和框架。
|
||||
|
||||
ESP-ADF
|
||||
-------------------------------------
|
||||
-------
|
||||
|
||||
ESP-ADF 是一个全方位的音频应用程序框架，该框架支持：
|
||||
|
||||
@@ -20,14 +20,14 @@ ESP-ADF 是一个全方位的音频应用程序框架，该框架支持：
|
||||
该框架对应的 GitHub 仓库为 `ESP-ADF <https://github.com/espressif/esp-adf>`_。
|
||||
|
||||
ESP-CSI
|
||||
------------------------------------
|
||||
-------
|
||||
|
||||
ESP-CSI 是一个具有实验性的框架，它利用 Wi-Fi 信道状态信息来检测人体存在。
|
||||
|
||||
该框架对应的 GitHub 仓库为 `ESP-CSI <https://github.com/espressif/esp-csi>`_。
|
||||
|
||||
ESP-DSP
|
||||
------------------------------------
|
||||
-------
|
||||
|
||||
ESP-DSP 提供了针对数字信号处理应用优化的算法，该库支持：
|
||||
|
||||
@@ -41,7 +41,7 @@ ESP-DSP 提供了针对数字信号处理应用优化的算法，该库支持：
|
||||
该库对应的 GitHub 仓库为 `ESP-DSP 库 <https://github.com/espressif/esp-dsp>`_。
|
||||
|
||||
ESP-WIFI-MESH
|
||||
------------------------------------------------------
|
||||
-------------
|
||||
|
||||
ESP-WIFI-MESH 基于 ESP-WIFI-MESH 协议搭建，该框架支持：
|
||||
|
||||
@@ -54,21 +54,21 @@ ESP-WIFI-MESH 基于 ESP-WIFI-MESH 协议搭建，该框架支持：
|
||||
该框架对应的 GitHub 仓库为 `ESP-MDF <https://github.com/espressif/esp-mdf>`_。
|
||||
|
||||
ESP-WHO
|
||||
------------------------------
|
||||
-------
|
||||
|
||||
ESP-WHO 框架利用 ESP32 及摄像头实现人脸检测及识别。
|
||||
|
||||
该框架对应的 GitHub 仓库为 `ESP-WHO <https://github.com/espressif/esp-who>`_。
|
||||
|
||||
ESP RainMaker
|
||||
---------------------------------------------
|
||||
-------------
|
||||
|
||||
`ESP RainMaker <https://rainmaker.espressif.com/>`_ 提供了一个快速 AIoT 开发的完整解决方案。使用 ESP RainMaker，用户可以创建多种 AIoT 设备，包括固件 AIoT 以及集成了语音助手、手机应用程序和云后端的 AIoT 等。
|
||||
|
||||
该解决方案对应的 GitHub 仓库为 `GitHub 上的 ESP RainMaker <https://github.com/espressif/esp-rainmaker>`_。
|
||||
|
||||
ESP-IoT-Solution
|
||||
--------------------------------------------------
|
||||
----------------
|
||||
|
||||
`ESP-IoT-Solution <https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/>`_ 涵盖了开发 IoT 系统时常用的设备驱动程序及代码框架。在 ESP-IoT-Solution 中，设备驱动程序和代码框架以独立组件存在，可以轻松地集成到 ESP-IDF 项目中。
|
||||
|
||||
@@ -82,7 +82,7 @@ ESP-IoT-Solution 支持：
|
||||
|
||||
|
||||
ESP-Protocols
|
||||
-----------------------------------------
|
||||
-------------
|
||||
|
||||
`ESP-Protocols <https://github.com/espressif/esp-protocols>`_ 库包含 ESP-IDF 的协议组件集。ESP-Protocols 中的代码以独立组件存在，可以轻松地集成到 ESP-IDF 项目中。此外，每个组件都可以在 `乐鑫组件注册表 <https://components.espressif.com/>`__ 中找到。
|
||||
|
||||
@@ -96,12 +96,14 @@ ESP-Protocols 组件：
|
||||
|
||||
* `asio <https://components.espressif.com/component/espressif/asio>`_ 是一个跨平台的 C++ 库，请参阅 `<https://think-async.com/Asio/>`_。该库基于现代 C++ 提供一致的异步模型，请参阅 `asio 文档 <https://docs.espressif.com/projects/esp-protocols/asio/docs/latest/index.html>`_。
|
||||
|
||||
* `esp_wifi_remote <https://components.espressif.com/component/espressif/esp_wifi_remote>`_ 是一个 Wi-Fi 通信库，提供标准的 Wi-Fi API，并且能够借助指定的传输接口，帮助目标设备通过外部 ESP32 芯片实现 Wi-Fi 通信。详情请参阅 :doc:`../api-guides/wifi-expansion`。
|
||||
|
||||
ESP-BSP
|
||||
----------------------------------------
|
||||
-------
|
||||
|
||||
`ESP-BSP <https://github.com/espressif/esp-bsp>`_ 库包含了各种乐鑫和第三方开发板的板级支持包 (BSP)，可以帮助快速上手特定的开发板。它们通常包含管脚定义和辅助函数，这些函数可用于初始化特定开发板的外设。此外，BSP 还提供了一些驱动程序，可用于开发版上的外部芯片，如传感器、显示屏、音频编解码器等。
|
||||
|
||||
ESP-IDF-CXX
|
||||
----------------------------------------------------------
|
||||
-----------
|
||||
|
||||
`ESP-IDF-CXX <https://github.com/espressif/esp-idf-cxx>`_ 包含了 ESP-IDF 的部分 C++ 封装，重点在实现易用性、安全性、自动资源管理，以及将错误检查转移到编译过程中，以避免运行时失败。它还提供了 ESP 定时器、I2C、SPI、GPIO 等外设或 ESP-IDF 其他功能的 C++ 类。ESP-IDF-CXX 作为组件可以从 `乐鑫组件注册表 <https://components.espressif.com/components/espressif/esp-idf-cxx>`__ 中获取。详情请参阅 `README.md <https://github.com/espressif/esp-idf-cxx/blob/main/README.md>`_。
|
||||
|
||||
Reference in New Issue
Block a user