alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-09-30 19:19:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(tools): Add idf.py merge-bin command and cmake target

Browse Source
This commit is contained in:
Jan Beran
2024-04-15 15:58:58 +02:00
parent e96da70654
commit 0dec6fe65d
4 changed files with 146 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -122,6 +122,37 @@ This command automatically builds the project if necessary, and then flash it to
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.
.. _merging-binaries:
Merge binaries: ``merge-bin``
-----------------------------
.. code-block:: bash
idf.py merge-bin [-o output-file] [-f format] [<format-specific-options>]
There are some situations, e.g. transferring the file to another machine and flashing it without ESP-IDF, where it is convenient to have only one file for flashing instead the several file output of ``idf.py build``.
The command ``idf.py merge-bin`` will merge the bootloader, partition table, the application itself, and other partitions (if there are any) according to the project configuration and create a single binary file ``merged-binary.[bin|hex]`` in the build folder, which can then be flashed later.
It is possible to output merged file in binary (raw), IntelHex (hex) and UF2 (uf2) formats.
The uf2 binary can also be generated by :ref:`idf.py uf2 <generate-uf2-binary>`. The ``idf.py uf2`` is functionally equivalent to ``idf.py merge-bin -f uf2``. However, the ``idf.py merge-bin`` command provides more flexibility and options for merging binaries into various formats described above.
Example usage:
.. code-block:: bash
idf.py merge-bin -o my-merged-binary.bin -f raw
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.
- Only for uf2 format:
- ``--md5-disable``: This option will disable MD5 checksums at the end of each block. This can be useful for integration with e.g. `tinyuf2 <https://github.com/adafruit/tinyuf2>`__.
Hints on How to Resolve Errors
==============================
@@ -201,6 +232,8 @@ Clean the Python Byte Code: ``python-clean``
This command deletes generated python byte code from the ESP-IDF directory. The byte code may cause issues when switching between ESP-IDF and Python versions. It is advised to run this target after switching versions of Python.
.. _generate-uf2-binary:
Generate a UF2 Binary: ``uf2``
------------------------------
@@ -214,6 +247,8 @@ This UF2 file can be copied to a USB mass storage device exposed by another ESP
To generate a UF2 binary for the application only (not including the bootloader and partition table), use the ``uf2-app`` command.
The ``idf.py uf2`` command is functionally equivalent to ``idf.py merge-bin -f uf2`` described :ref:`above <merging-binaries>`. However, the ``idf.py merge-bin`` command provides more flexibility and options for merging binaries into various formats, not only uf2.
.. code-block:: bash
idf.py uf2-app