1{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000", esp32p4="0x2000"} 2 3.. _advanced-commands: 4 5Advanced Commands 6================= 7 8The ``write_flash``, ``read_flash``, ``erase_flash``, ``erase_region``, ``read_mac``, ``flash_id``, ``elf2image``, ``image_info`` and ``merge_bin`` commands are all documented in the :ref:`commands` section. 9 10The following less common commands are for more advanced users. 11 12.. _verify-flash: 13 14Verify Flash Data: verify_flash 15------------------------------- 16 17The ``verify_flash`` command allows you to verify that data in flash matches a local file. 18 19The ``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: 20 21:: 22 23 esptool.py verify_flash --diff yes 0x40000 my_app.elf-0x40000.bin 24 25 26The ``--diff yes`` option specifies that if the files are different, the details should be printed to the console. 27 28.. note:: 29 30 .. list:: 31 32 * If verifying a default boot image (offset {IDF_TARGET_BOOTLOADER_OFFSET} for {IDF_TARGET_NAME}) 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. 33 * Another way to compare flash contents is to use the ``read_flash`` command, and then use binary diffing tools on the host. 34 35.. _dump-mem: 36 37Dump a Memory Region to File: dump_mem 38-------------------------------------- 39 40The ``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: 41 42:: 43 44 esptool.py dump_mem 0x40000000 65536 iram0.bin 45 46.. _load-ram: 47 48Load a Binary to RAM: load_ram 49------------------------------ 50 51The ``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. 52 53:: 54 55 esptool.py --no-stub load_ram ./test/images/helloworld-esp8266.bin 56 57.. note:: 58 59 * 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. 60 * 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. 61 * 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. 62 63.. _read-mem-write-mem: 64 65Read or Write RAM: read_mem / write_mem 66--------------------------------------- 67 68The ``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. 69 70:: 71 72 esptool.py write_mem 0x400C0000 0xabad1dea 73 74:: 75 76 esptool.py read_mem 0x400C0000 77 78.. _read-flash-status: 79 80Read Flash Chip Registers: read_flash_status 81-------------------------------------------- 82 83This 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: 84 85:: 86 87 esptool.py read_flash_status --bytes 2 88 89The ``--bytes`` argument determines how many status register bytes are read. 90 91* ``--bytes 1`` sends the most common ``RDSR`` command (05h) and returns a single byte of status. 92* ``--bytes 2`` sends both ``RDSR`` (05h) and ``RDSR2`` (35h), reads one byte of status from each, and returns a two byte status. 93* ``--bytes 3`` sends ``RDSR`` (05h), ``RDSR2`` (35h), and ``RDSR3`` (15h), reads one byte of status from each, and returns a 3 byte status. 94 95.. note:: 96 97 Not all flash chips support all of these commands. Consult the specific flash chip datasheet for details. 98 99.. _write-flash-status: 100 101Write Flash Chip Registers: write_flash_status 102----------------------------------------------- 103 104This 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: 105 106:: 107 108 esptool.py write_flash_status --bytes 2 --non-volatile 0 109 110The ``--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. 111Otherwise, each command is accompanied by 8-bits of the new status register value. 112 113A 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``. 114 115.. note:: 116 117 Consult the specific flash chip datasheet for details about which commands are recognised by a particular chip. 118 119.. warning:: 120 121 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! 122 123.. _read-flash-sfdp: 124 125Read Serial Flash Discoverable Parameters (SFDP) 126------------------------------------------------ 127 128The 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: 129 130:: 131 esptool.py read_flash_sfdp 16 4 132 133This will read 4 bytes from SFDP address 16. 134 135.. only:: esp8266 136 137 .. _chip-id: 138 139 Read the Chip ID: chip_id 140 ------------------------- 141 142 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. 143 144 On {IDF_TARGET_NAME}, 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. 145 146 :: 147 148 esptool.py chip_id 149 150 .. _make-image: 151 152 Assemble a Firmware Image: make_image 153 ------------------------------------- 154 155 ``make_image`` allows you to manually assemble a firmware image from binary segments (such as those extracted from objcopy). For example: 156 157 :: 158 159 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 160 161 This command does not require a serial connection. 162 163 .. note:: 164 165 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. 166 167 .. _run: 168 169 Boot Application Code: run 170 -------------------------- 171 172 The ``run`` command immediately exits the bootloader and attempts to boot the normal application code. 173
