1.. _commands: 2 3Basic Commands 4============== 5 6Write Binary Data to Flash: write_flash 7---------------------------------------- 8 9Binary data can be written to the ESP's flash chip via the serial ``write_flash`` command: 10 11:: 12 13 esptool.py --port COM4 write_flash 0x1000 my_app-0x01000.bin 14 15Multiple flash addresses and file names can be given on the same command line: 16 17:: 18 19 esptool.py --port COM4 write_flash 0x00000 my_app.elf-0x00000.bin 0x40000 my_app.elf-0x40000.bin 20 21The ``--chip`` argument is optional when writing to flash, esptool will detect the type of chip when it connects to the serial port. 22 23The ``--port`` argument is documented under :ref:`serial-port`. 24 25.. only:: esp8266 26 27 The next arguments to ``write_flash`` are one or more pairs of offset (address) and file name. When generating ESP8266 "version 1" images, the file names created by ``elf2image`` include the flash offsets as part of the file name. 28 For other types of images, consult your SDK documentation to determine the files to flash at which offsets. 29 30.. only:: not esp8266 31 32 The next arguments to ``write_flash`` are one or more pairs of offset (address) and file name. Consult your SDK documentation to determine the files to flash at which offsets. 33 34Numeric values passed to write_flash (and other commands) can be specified either in hex (ie 0x1000), or in decimal (ie 4096). 35 36See the :ref:`troubleshooting` section if the ``write_flash`` command is failing, or the flashed module fails to boot. 37 38Setting Flash Mode and Size 39^^^^^^^^^^^^^^^^^^^^^^^^^^^ 40 41You may also need to specify arguments for :ref:`flash mode and flash size <flash-modes>`, if you wish to override the defaults. For example: 42 43:: 44 45 esptool.py --port /dev/ttyUSB0 write_flash --flash_mode qio --flash_size 32m 0x0 bootloader.bin 0x1000 my_app.bin 46 47Since esptool v2.0, these options are not often needed as the default is to keep the flash mode and size from the ``.bin`` image file. See the :ref:`flash-modes` section for more details. 48 49Compression 50^^^^^^^^^^^ 51 52By default, the serial transfer data is compressed for better performance. The ``-u/--no-compress`` option disables this behaviour. 53 54Erasing Flash Before Write 55^^^^^^^^^^^^^^^^^^^^^^^^^^ 56 57To successfully write data into flash, all 4096-byte memory sectors (the smallest erasable unit) affected by the operation have to be erased first. As a result, when the flashing offset address or the data are not 4096-byte aligned, more memory is erased than actually needed. 58Esptool will display information about which flash memory sectors will be erased. 59 60Use the ``-e/--erase-all`` option to erase all flash sectors (not just the write areas) before programming. 61 62.. only:: not esp8266 63 64 Bootloader Protection 65 ^^^^^^^^^^^^^^^^^^^^^ 66 67 Flashing into the bootloader region (``0x0`` -> ``0x8000``) is disabled by default if active `Secure Boot <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/secure-boot-v2.html>`_ is detected. 68 This is a safety measure to prevent accidentally overwriting the secure bootloader, which **can ultimately lead to bricking the device**. 69 70 This behavior can be overridden with the ``--force`` option. **Use this only at your own risk and only if you know what you are doing!** 71 72 73 Encrypted Flash Protection 74 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 75 76 .. only:: esp32 77 78 Overwriting the encrypted firmware (bootloader, application, etc.) without the ``--encrypt`` option is disabled, if `Flash Encryption <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/flash-encryption.html>`_ is enabled and Encrypted Download being disabled (efuse bit ``EFUSE_DISABLE_DL_ENCRYPT`` is set). 79 80 .. only:: not esp32 81 82 Overwriting the encrypted firmware (bootloader, application, etc.) without the ``--encrypt`` option is disabled, if: 83 84 * `Flash Encryption <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/flash-encryption.html>`_ and Secure Download Mode are enabled or 85 * `Flash Encryption <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/flash-encryption.html>`_ is enabled but Encrypted Download is disabled (efuse bit ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` is set). 86 87 This is a safety measure to prevent accidentally overwriting the encrypted firmware with a plaintext binary, which **can ultimately lead to bricking the device**. 88 89 This behavior can be overridden with the ``--force`` option. **Use this option provided that the flash encryption key is generated external to the device and you could perform the encryption on the host machine.** 90 91 Flashing an Incompatible Image 92 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 93 94 ``esptool.py`` checks every binary before flashing. If a valid firmware image is detected, the ``Chip ID`` and ``Minimum chip revision`` fields in its :ref:`header <image-format>` are compared against the actually connected chip. 95 If the image turns out to be incompatible with the chip in use or requires a newer chip revision, flashing is stopped. 96 97 This behavior can be overridden with the ``--force`` option. 98 99Read Flash Contents: read_flash 100-------------------------------- 101 102The read_flash command allows reading back the contents of flash. The arguments to the command are an address, a size, and a filename to dump the output to. For example, to read a full 2MB of attached flash: 103 104:: 105 106 esptool.py -p PORT -b 460800 read_flash 0 0x200000 flash_contents.bin 107 108 109It is also possible to autodetect flash size by using ``ALL`` as size. The above example with autodetection would look like this: 110 111:: 112 113 esptool.py -p PORT -b 460800 read_flash 0 ALL flash_contents.bin 114 115 116.. note:: 117 118 When using the ``read_flash`` command in combination with the ``--no-stub`` argument, it may be necessary to also set the ``--flash_size`` argument to ensure proper reading of the flash contents by the ROM. 119 120 121.. note:: 122 123 If ``write_flash`` updated the boot image's :ref:`flash mode and flash size <flash-modes>` during flashing then these bytes may be different when read back. 124 125.. _erase_flash: 126 127Erase Flash: erase_flash & erase_region 128--------------------------------------- 129 130To erase the entire flash chip (all data replaced with 0xFF bytes): 131 132:: 133 134 esptool.py erase_flash 135 136To erase a region of the flash, starting at address 0x20000 with length 0x4000 bytes (16KB): 137 138:: 139 140 esptool.py erase_region 0x20000 0x4000 141 142The address and length must both be multiples of the SPI flash erase sector size. This is 0x1000 (4096) bytes for supported flash chips. 143 144.. only:: not esp8266 145 146 Flash Protection 147 ^^^^^^^^^^^^^^^^ 148 149 Erasing the flash chip is disabled by default if either active `Secure Boot <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/secure-boot-v2.html>`_ or 150 `Flash Encryption <https://docs.espressif.com/projects/esp-idf/en/latest/{IDF_TARGET_PATH_NAME}/security/flash-encryption.html>`_ is detected. 151 This is a safety measure to prevent accidentally deleting the secure bootloader or encrypted data, which **can ultimately lead to bricking the device**. 152 153 This behavior can be overridden with the ``--force`` option. **Use this only at your own risk and only if you know what you are doing!** 154 155Read Built-in MAC Address: read_mac 156------------------------------------ 157 158:: 159 160 esptool.py read_mac 161 162.. _read-spi-flash-id: 163 164Read SPI Flash ID: flash_id 165--------------------------- 166 167:: 168 169 esptool.py flash_id 170 171Example output: 172 173:: 174 175 Manufacturer: e0 176 Device: 4016 177 Detected flash size: 4MB 178 179Refer to `flashrom source code <https://github.com/flashrom/flashrom/blob/master/include/flashchips.h>`__ for flash chip manufacturer name and part number. 180 181.. _elf-2-image: 182 183Convert ELF to Binary: elf2image 184-------------------------------- 185 186The ``elf2image`` command converts an ELF file (from compiler/linker output) into the binary executable images which can be flashed and then booted into: 187 188:: 189 190 esptool.py --chip {IDF_TARGET_NAME} elf2image my_app.elf 191 192This command does not require a serial connection. 193 194``elf2image`` also accepts the `Flash Modes <#flash-modes>`__ arguments ``--flash_freq`` and ``--flash_mode``, which can be used to set the default values in the image header. This is important when generating any image which will be booted directly by the chip. 195These values can also be overwritten via the ``write_flash`` command, see the `write_flash command <#write-binary-data-to-flash-write-flash>`__ for details. Overwriting these values via the ``write_flash`` command will produce an image with a recalculated SHA256 digest, otherwise, the image SHA256 digest would be invalidated by rewriting the image header. There is an option to skip appending a SHA256 digest after the image with ``--dont-append-digest`` argument of the ``elf2image`` command. 196 197By default, ``elf2image`` uses the sections in the ELF file to generate each segment in the binary executable. To use segments (PHDRs) instead, pass the ``--use_segments`` option. 198 199.. only:: esp8266 200 201 The default command output for {IDF_TARGET_NAME} is two binary files: ``my_app.elf-0x00000.bin`` and ``my_app.elf-0x40000.bin``. You can alter the firmware file name prefix using the ``--output/-o`` option. 202 203 ``elf2image`` can also produce a "version 2" image file suitable for use with a software bootloader stub such as `rboot <https://github.com/raburton/rboot>`__ or the Espressif bootloader program. You can't flash a "version 2" image without also flashing a suitable bootloader. 204 205 :: 206 207 esptool.py --chip {IDF_TARGET_NAME} elf2image --version=2 -o my_app-ota.bin my_app.elf 208 209.. only:: not esp8266 210 211 For {IDF_TARGET_NAME}, elf2image produces a single output binary "image file". By default this has the same name as the .elf file, with a .bin extension. For example: 212 213 :: 214 215 esptool.py --chip {IDF_TARGET_NAME} elf2image my_esp_app.elf 216 217 In the above example, the output image file would be called ``my_esp_app.bin``. 218 219 The ``--ram-only-header`` configuration is mainly applicable for use within the Espressif's SIMPLE_BOOT option from 3rd party OSes such as ZephyrOS and NuttX OS. 220 This option makes only the RAM segments visible to the ROM bootloader placing them at the beginning of the file and altering the segment count from the image header with the quantity of these segments, and also writing only their checksum. This segment placement may result in a more fragmented binary because of flash alignment constraints. 221 It is strongly recommended to use this configuration with care, because the image built must then handle the basic hardware initialization and the flash mapping for code execution after ROM bootloader boot it. 222 223.. _image-info: 224 225Output .bin Image Details: image_info 226------------------------------------- 227 228The ``image_info`` command outputs some information (load addresses, sizes, etc) about a ``.bin`` file created by ``elf2image``. Command also supports ``.hex`` file created by ``merge_bin`` command from supported ``.bin`` files. 229 230To view more information about the image, such as set flash size, frequency and mode, or extended header information, use the ``--version 2`` option. This extended output will become the default in a future major release. 231 232This information corresponds to the headers described in :ref:`image-format`. 233 234:: 235 236 esptool.py image_info --version 2 my_esp_app.bin 237 238.. only:: not esp8266 239 240 If the given binary file is an application and a valid `ESP-IDF application header <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/app_image_format.html#application-description>`__ is detected in the image, specific fields describing the application are also displayed. 241 242 If the given binary file is a bootloader and a valid `ESP-IDF bootloader header <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/bootloader_image_format.html#bootloader-description>`__ is detected in the image, specific fields describing the bootloader are also displayed. 243 244.. _merge-bin: 245 246Merge Binaries for Flashing: merge_bin 247-------------------------------------- 248The ``merge_bin`` command will merge multiple binary files (of any kind) into a single file that can be flashed to a device later. Any gaps between the input files are padded based on the selected output format. 249 250For example: 251 252:: 253 254 esptool.py --chip {IDF_TARGET_NAME} merge_bin -o merged-flash.bin --flash_mode dio --flash_size 4MB 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin 255 256Will create a file ``merged-flash.bin`` with the contents of the other 3 files. This file can be later written to flash with ``esptool.py write_flash 0x0 merged-flash.bin``. 257 258 259**Common options:** 260 261* The ``merge_bin`` command supports the same ``--flash_mode``, ``--flash_size`` and ``--flash_freq`` options as the ``write_flash`` command to override the bootloader flash header (see above for details). 262 These options are applied to the output file contents in the same way as when writing to flash. Make sure to pass the ``--chip`` parameter if using these options, as the supported values and the bootloader offset both depend on the chip. 263* The ``--format`` option will change the format of the output file. For more information about formats see formats description below. 264* The input files can be in either ``bin`` or ``hex`` format and they will be automatically converted to type selected by ``--format`` argument. 265* It is possible to append options from a text file with ``@filename`` (see the advanced options page :ref:`Specifying Arguments via File <specify_arguments_via_file>` section for details). As an example, this can be conveniently used with the ESP-IDF build system, which produces a ``flash_args`` file in the build directory of a project: 266 267.. code:: sh 268 269 cd build # The build directory of an ESP-IDF project 270 esptool.py --chip {IDF_TARGET_NAME} merge_bin -o merged-flash.bin @flash_args 271 272 273HEX Output Format 274^^^^^^^^^^^^^^^^^ 275 276The output of the command will be in `Intel Hex format <https://www.intel.com/content/www/us/en/support/programmable/articles/000076770.html>`__. The gaps between the files won't be padded. 277 278Intel Hex format offers distinct advantages when compared to the binary format, primarily in the following areas: 279 280* **Transport**: Intel Hex files are represented in ASCII text format, significantly increasing the likelihood of flawless transfers across various mediums. 281* **Size**: Data is carefully allocated to specific memory addresses eliminating the need for unnecessary padding. Binary images often lack detailed addressing information, leading to the inclusion of data for all memory locations from the file's initial address to its end. 282* **Validity Checks**: Each line in an Intel Hex file has a checksum to help find errors and make sure data stays unchanged. 283 284.. code:: sh 285 286 esptool.py --chip {IDF_TARGET_NAME} merge_bin --format hex -o merged-flash.hex --flash_mode dio --flash_size 4MB 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin 287 288 289RAW Output Format 290^^^^^^^^^^^^^^^^^ 291 292The output of the command will be in ``raw`` format and gaps between individual files will be filled with `0xFF` bytes (same as unwritten flash contents). 293 294.. note:: 295 296 Because gaps between the input files are padded with `0xFF` bytes, when the merged binary is written then any flash sectors between the individual files will be erased. To avoid this, write the files individually. 297 298 299**RAW options:** 300 301* The ``--fill-flash-size SIZE`` option will pad the merged binary with `0xFF` bytes to the full flash specified size, for example ``--fill-flash-size 4MB`` will create a 4MB binary file. 302* The ``--target-offset 0xNNN`` option will create a merged binary that should be flashed at the specified offset, instead of at offset 0x0. 303 304 305UF2 Output Format 306^^^^^^^^^^^^^^^^^ 307 308This command will generate a UF2 (`USB Flashing Format <https://github.com/microsoft/uf2>`_) binary. 309This UF2 file can be copied to a USB mass storage device exposed by another ESP running the `ESP USB Bridge <https://github.com/espressif/esp-usb-bridge>`_ project. The bridge MCU will use it to flash the target MCU. This is as simple copying (or "drag-and-dropping") the file to the exposed disk accessed by a file explorer in your machine. 310 311Gaps between the files will be filled with `0x00` bytes. 312 313**UF2 options:** 314 315* The ``--chunk-size`` option will set what portion of 512 byte block will be used for data. A common value is 256 bytes. By default, the largest possible value will be used. 316* The ``--md5-disable`` 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>`__. 317 318.. code:: sh 319 320 esptool.py --chip {IDF_TARGET_NAME} merge_bin --format uf2 -o merged-flash.uf2 --flash_mode dio --flash_size 4MB 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin 321 322 323Advanced Commands 324----------------- 325 326The following commands are less commonly used, or only of interest to advanced users. They are documented in the :ref:`advanced-commands` section: 327 328.. list:: 329 330 * :ref:`verify-flash` 331 * :ref:`dump-mem` 332 * :ref:`load-ram` 333 * :ref:`read-mem-write-mem` 334 * :ref:`read-flash-status` 335 * :ref:`write-flash-status` 336 :esp8266: * :ref:`chip-id` 337 :esp8266: * :ref:`make-image` 338 :esp8266: * :ref:`run` 339
