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 0x0 for ESP8266) 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 the Chip ID: chip_id

The chip_id command allows you to read a 4 byte ID which forms part of the MAC address. It is usually better to use read_mac to identify a chip.

On ESP8266, output is the same as the system_get_chip_id() SDK function. The chip ID is four bytes long, the lower three bytes are the final bytes of the MAC address. The upper byte is zero.

esptool.py chip_id

Assemble a Firmware Image: make_image

make_image allows you to manually assemble a firmware image from binary segments (such as those extracted from objcopy). For example:

esptool.py --chip esp8266 make_image -f app.text.bin -a 0x40100000 -f app.data.bin -a 0x3ffe8000 -f app.rodata.bin -a 0x3ffe8c00 app.flash.bin

This command does not require a serial connection.

Note

In general, it is better to create an ELF image (including any binary data as part of the ELF, by using objcopy or other tools) and then use elf2image to generate the .bin file.

Boot Application Code: run

The run command immediately exits the bootloader and attempts to boot the normal application code.