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 ESP32-S3) then any
--flash_mode
,--flash_size
and--flash_freq
arguments which were passed to write_flash must also be passed toverify_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 withets_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 commonRDSR
command (05h) and returns a single byte of status.--bytes 2
sends bothRDSR
(05h) andRDSR2
(35h), reads one byte of status from each, and returns a two byte status.--bytes 3
sendsRDSR
(05h),RDSR2
(35h), andRDSR3
(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.