ESP-IDF Development Tools Guide — Part I | by Pedro Minatel | The ESP Journal | Jun, 2021

Spread the love

The ROM Bootloader Utility, also known as esptool, is the tool used to write the firmware to the device and also for other memory and binary operations.

Below you will see the full list of functionalities on the --help

The uses the in several commands, including flash and erase. You might need to use the esptool for some other specific reasons.

The command syntax is defined below:


Here are some commands:

  • write_flash — Write a binary blob to the device flash.

Syntax: -p [PORT] write_flash [ADDRESS1] [PATH_TO_BINARY1]… [ADDRESS2] [PATH_TO_BINARY2]

The write_flash command supports multiple binaries in the same command.

This command also allows some before-and-after commands:

–before: What to do before connecting to the chip.


This option usually is used with default_reset by the when flashing the device. For some special demands, you can change this behavior.

— after: What to do after is finished.


For this option, the default option is the hard_reset. It means that the device will be hard reset after flashing is done.

If you need to keep the device into download state, you can use the “no_reset” argument for this option.

Syntax: -p [PORT] --before [ARG_BEFORE] --after [ARG_AFTER] write_flash [ADDRESS] [PATH_TO_BINARY]
  • verify_flash — Verify a binary blob against flash.

This option is used to verify the integrity of the compiled version to the flashed into the device. This kind of verification is often used to check or verify possible errors after flashing the device.

Syntax: -p [PORT] verify_flash [ADDRESS] [PATH_TO_BINARY]

  • image_info — Dump headers from an application image.

Syntax: --chip [CHIP] image_info [PATH_TO_BINARY]

  • read_mac — Read MAC address from OTP ROM.

Syntax: -p [PORT] read_mac

  • erase_flash — Perform Chip Erase on SPI flash. Same as erase_flash.

It wipes the whole flash memory and could take some time depending on the flash size.

Syntax: -p [PORT] erase_flash

  • erase_region — Erase a region of the flash.

This partially wipes the flash memory. This can be used to erase a specific partition or some other area specified by the addresses.

Syntax: -p [PORT] erase_region [START_ADDRESS] [END_ADDRESS]

Note: The use this option on to erase the selected partition.

  • chip_id — Read Chip ID from OTP ROM, if available.

Syntax: -p [PORT] chip_id

  • flash_id — Read SPI flash manufacturer and device ID.

You can use this option to detect the flash information, like size and manufacturer. You can also use this to get the chip details such as:

  • Chip type and revision
  • Crystal frequency
  • MAC Address

Syntax: -p [PORT] flash_id

  • merge_bin — Merge multiple raw binary files into a single file for later flashing.

This option is useful when distributing the full image. You can merge all binaries files generated by the build, including bootloader, app, partitions, ota, etc.

Merge Command Syntax: merge_bin [OUT] [OPTIONS] [ADDRESS1] [PATH_TO_BINARY1]...[ADDRESS2] [PATH_TO_BINARY2]

Merge Advanced Options:

--flash_freq: Defines the flash SPI speed (in MHz)
◦ keep
◦ 40m
◦ 26m
◦ 20m
◦ 80m
--flash_mode: Defines the SPI flash memory connection mode.
◦ keep
◦ qio
◦ qout
◦ dio
◦ dout
--flash_size [FLASH_SIZE]: Defines the flash memory size.--spi-connection [SPI_CONNECTION]: Defines the flash pinout configuration. If not defined, the default will be used from efuse.--target-offset [TARGET_OFFSET]: This option define the memory ofsset that the binary will be flashed. The default option is 0x0.--fill-flash-size [FILL_FLASH_SIZE]: Use this option to fill the binary with 0xff padding. This option will increase the binary size up to the defined flash size.

Here is an example to merge three binaries into one for an ESP32 with 4MB of flash in DIO mode: --chip esp32 merge_bin -o my_app_merged.bin --flash_mode dio --flash_size 4MB 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/my_app.bin

Note that the addresses may vary from one application to another. A good way to check this is through the partitions CSV file or the output from the command build.

Then, the output file can be flashed at the offset 0x0. write_flash 0x0  my_app_merged.bin

Optional arguments

The has some optional arguments that help the commands to be more specific or to change some default options. Here are the arguments:

If not set, the default will be used.

--help: Shows the help information.--chip: Set the target chip type. Can be used to avoid mistakes such as sending a command to the wrong chip type.--port: Set the serial port device.--baud: Set the serial port device speed.--before: What to do before connecting to the chip.--after: What to do after running• --no-stub: Disable launching the flasher stub, only talk to ROM bootloader.--trace: Enable trace-level output of interactions.--override-vddsdio: Override ESP32 VDDSDIO internal voltage regulator (use with care).--connect-attempts: Number of attempts to connect, negative or 0 for infinite. Default: 7.

The get the full potential of the ESP-IDF, you must also know how to use the set of tools available. Using these tools’ functionalities, you can build automation for your project or manufacturing process, creating scripts that perform specific functions.

Mastering the ESP-IDF tools could save time and get your development process even easier on the daily tasks!

Source link

Leave a Reply

Your email address will not be published. Required fields are marked *