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
idf.py uses the
esptool.py in several commands, including flash and erase. You might need to use the esptool for some other specific reasons.
esptool.py command syntax is defined below:
esptool.py [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...
Here are some commands:
- write_flash — Write a binary blob to the device flash.
esptool.py -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
idf.py when flashing the device. For some special demands, you can change this behavior.
— after: What to do after
esptool.py is finished.
For this option, the
idf.py 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.
esptool.py -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.
esptool.py -p [PORT] verify_flash [ADDRESS] [PATH_TO_BINARY]
- image_info — Dump headers from an application image.
esptool.py --chip [CHIP] image_info [PATH_TO_BINARY]
- read_mac — Read MAC address from OTP ROM.
esptool.py -p [PORT] read_mac
- erase_flash — Perform Chip Erase on SPI flash. Same as
It wipes the whole flash memory and could take some time depending on the flash size.
esptool.py -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.
esptool.py -p [PORT] erase_region [START_ADDRESS] [END_ADDRESS]
parttool.py use this option on
esptool.py to erase the selected partition.
- chip_id — Read Chip ID from OTP ROM, if available.
esptool.py -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
esptool.py -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:
esptool.py merge_bin [OUT] [OPTIONS] [ADDRESS1] [PATH_TO_BINARY1]...[ADDRESS2] [PATH_TO_BINARY2]
Merge Advanced Options:
• --flash_freq: Defines the flash SPI speed (in MHz)
◦ 80m• --flash_mode: Defines the SPI flash memory connection mode.
◦ 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:
esptool.py --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
Then, the output file can be flashed at the offset
esptool.py write_flash 0x0 my_app_merged.bin
esptool.py 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 esptool.py.• --no-stub: Disable launching the flasher stub, only talk to ROM bootloader.• --trace: Enable trace-level output of esptool.py 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!