Advanced Commands

The write_flash, read_flash, erase_flash, erase_region, read_mac, flash_id, elf2image, image_info and 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

The verify_flash command allows you to verify that data in flash matches a local file.

The 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

The --diff yes option specifies that if the files are different, the details should be printed to the console.

Note

  • If verifying a default boot image (offset 0x1000 for ESP32-S2) then any --flash_mode, --flash_size and --flash_freq arguments which were passed to write_flash must also be passed to verify_flash. Otherwise, verify_flash will detect mismatches in the header of the image file.

  • Another way to compare flash contents is to use the read_flash command, and then use binary diffing tools on the host.

Dump a Memory Region to File: dump_mem

The 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

The load_ram command allows the loading of an executable binary image (created with the elf2image or 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 .bin files.

esptool.py --no-stub load_ram ./test/images/helloworld-esp8266.bin

Note

  • 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_info command 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-stub to avoid this problem.

  • Due to a limitation in the ROM loader, when using --no-stub any 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

The read_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 RDSR, RDSR2 and/or 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

The --bytes argument determines how many status register bytes are read.

  • --bytes 1 sends the most common RDSR command (05h) and returns a single byte of status.

  • --bytes 2 sends both RDSR (05h) and RDSR2 (35h), reads one byte of status from each, and returns a two byte status.

  • --bytes 3 sends RDSR (05h), RDSR2 (35h), and RDSR3 (15h), reads one byte of status from each, and returns a 3 byte status.

Note

Not all flash chips support all of these commands. 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 WRSR, WRSR2 and/or 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

The --bytes option is similar to the corresponding option for read_flash_status and causes a mix of WRSR (01h), 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 WREN.

Note

Consult the specific flash chip datasheet for details about which commands are recognised by a particular chip.

Warning

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!

Read Serial Flash Discoverable Parameters (SFDP): read_flash_sfdp

The Serial Flash Discoverable Parameters (SFDP) store essential vendor-specific configuration data of the flash memory chip. These parameters help identify and interact with different flash devices. Usage:

esptool.py read_flash_sfdp 16 4

This will read 4 bytes from SFDP address 16.