merge_bin commands are all documented in the Basic Commands section.
The following less common commands are for more advanced users.
Verify Flash Data: verify_flash
verify_flash command allows you to verify that data in flash matches a local file.
write_flash command always verifies the MD5 hash of data which is written to flash, so additional verification is not usually needed. However, if you wish to perform a byte-by-byte verification of the flash contents (and optionally print the differences to the console) then you can do so with this command:
esptool.py verify_flash --diff yes 0x40000 my_app.elf-0x40000.bin
--diff yes option specifies that if the files are different, the details should be printed to the console.
If verifying a default boot image (offset 0x1000 for ESP32) then any
--flash_freqarguments which were passed to write_flash must also be passed to
verify_flashwill detect mismatches in the header of the image file.
Another way to compare flash contents is to use the
read_flashcommand, and then use binary diffing tools on the host.
Dump a Memory Region to File: dump_mem
dump_mem command will dump a region from the chip’s memory space to a file. For example, to dump the ROM (64 kB) from an ESP8266:
esptool.py dump_mem 0x40000000 65536 iram0.bin
Load a Binary to RAM: load_ram
load_ram command allows the loading of an executable binary image (created with the
make_image commands) directly into RAM, and then immediately executes the program contained within it. Command also supports
.hex file created by
merge_bin command from supported
esptool.py --no-stub load_ram ./test/images/helloworld-esp8266.bin
The binary image must only contain IRAM- and DRAM-resident segments. Any SPI flash mapped segments will not load correctly and the image will probably crash. The
image_infocommand can be used to check the binary image contents.
Because the software loader is resident in IRAM and DRAM, this limits the region where a new program may be loaded. An error will be printed if the new program overlaps with the software loader in RAM. Older esptool versions may hang. Pass
esptool.py --no-stubto avoid this problem.
Due to a limitation in the ROM loader, when using
--no-stubany very early serial output from a program may be lost if the program resets or reconfigures the UART. To avoid this problem, a program can be compiled with
ets_delay_us(1)as the very first statement after the entry point.
Read or Write RAM: read_mem / write_mem
write_mem commands allow reading and writing single words (4 bytes) of RAM. This can be used to “peek” and “poke” at registers.
esptool.py write_mem 0x400C0000 0xabad1dea
esptool.py read_mem 0x400C0000
Read Flash Chip Registers: read_flash_status
This command is intended for use when debugging hardware flash chip-related problems. It allows sending a
RDSR3 commands to the flash chip to read the status register contents. This can be used to check write protection status, for example:
esptool.py read_flash_status --bytes 2
--bytes argument determines how many status register bytes are read.
--bytes 1sends the most common
RDSRcommand (05h) and returns a single byte of status.
--bytes 2sends both
RDSR2(35h), reads one byte of status from each, and returns a two byte status.
RDSR3(15h), reads one byte of status from each, and returns a 3 byte status.
Not all flash chips support all of these comands. Consult the specific flash chip datasheet for details.
Write Flash Chip Registers: write_flash_status
This command is intended for use when debugging hardware flash chip-related problems. It allows sending
WRSR3 commands to the flash chip to write the status register contents. This can be used to clear write protection bits, for example:
esptool.py write_flash_status --bytes 2 --non-volatile 0
--bytes option is similar to the corresponding option for
read_flash_status and causes a mix of
WRSR2 (31h), and
WRSR3 (11h) commands to be sent to the chip. If
--bytes 2 is used then
WRSR is sent first with a 16-bit argument and then with an 8-bit argument, as different flash chips use this command differently.
Otherwise, each command is accompanied by 8-bits of the new status register value.
A second option
--non-volatile can be used in order to send a
WREN (06h) command before writing the status. This may allow non-volatile status register bits to be set or cleared. If the
--non-volatile option is not supplied, a
WEVSR (50h) command is sent instead of
Consult the specific flash chip datasheet for details about which commands are recognised by a particular chip.
Setting status bits (particularly non-volatile ones) can have permanent side effects for some flash chips, so check carefully before using this command to set any bits!