1{IDF_TARGET_BOOTLOADER_OFFSET:default="0x0", esp32="0x1000", esp32s2="0x1000", esp32p4="0x2000"} 2 3.. _flashing: 4 5Flashing Firmware 6================= 7 8Esptool is used under the hood of many development frameworks for Espressif SoCs, such as `ESP-IDF <https://docs.espressif.com/projects/esp-idf/>`_, `Arduino <https://docs.espressif.com/projects/arduino-esp32/>`_, or `PlatformIO <https://docs.platformio.org/en/latest/platforms/espressif32.html>`_. 9After the resulting firmware binary files are compiled, esptool is used to flash these into the device. 10 11Sometimes there might be a need to comfortably flash a bigger amount of devices with the same binaries or to share flashing instructions with a third party. 12It is possible to compile the firmware just once and then repeatedly use esptool (manually or :ref:`in a custom script <scripting>`) to flash the files. 13 14Sharing these instructions and below mentioned assets with a third party (for example a manufacturer) should suffice to allow reproducible and quick flashing of your application into an Espressif chip. 15 16.. note:: 17 18 The following texts are just an example, please see the documentation of the development framework of your choice for precise instructions. 19 20Prerequisites 21------------- 22 23* Installed esptool, see the :ref:`installation guide <installation>` for instructions. 24* All of the compiled binary files in a known location. 25* Espressif chip connected to your computer. 26 27Binary Files Location 28--------------------- 29 30The generated binary files are usually stored in the ``build`` folder of your project. 31 32For example, when building the `hello-world example project <https://github.com/espressif/esp-idf/tree/master/examples/get-started/hello_world>`_ in ESP-IDF, the resulting app binary can be found in ``.../esp-idf/examples/get-started/hello_world/build/hello_world.bin``. 33The same applies to the bootloader and the partition table. 34 35The location of generated binaries depends on the used development framework. If you are unsure of the location, see the generated esptool `command <#command>`__ containing the full paths. 36 37Command 38------- 39 40Compile and upload your firmware once with your preferred framework. The detailed esptool command will be displayed in the output right before the flashing happens. 41 42It is also possible to assemble the command manually, please see the :ref:`esptool usage documentation<esptool>` for more information. 43 44ESP-IDF 45^^^^^^^ 46 47ESP-IDF outputs the full esptool command used for flashing after the build is finished, for example:: 48 49 Project build complete. To flash, run this command: 50 python esptool.py -p (PORT) -b 460800 --before default_reset --after hard_reset --chip {IDF_TARGET_PATH_NAME} write_flash --flash_mode dio --flash_size detect --flash_freq 40m {IDF_TARGET_BOOTLOADER_OFFSET} build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin 51 or run 'idf.py -p (PORT) flash' 52 53Arduino 54^^^^^^^ 55 56The full esptool command is hidden from the user by default. To expose it, open the preferences window and check the ``Show verbose output during: upload`` option. A full command will be shown while uploading the sketch. 57 58PlatformIO 59^^^^^^^^^^ 60 61To do a verbose upload and see the exact esptool invocation, run ``pio run -v -t upload`` in the terminal. In the generated output, there is the full esptool command, you will see something like: 62 63:: 64 65 “.../.platformio/penv/bin/python2.7” “.../.platformio/packages/tool-esptoolpy/esptool.py” --chip {IDF_TARGET_PATH_NAME} --port “/dev/cu.usbserial001” --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect {IDF_TARGET_BOOTLOADER_OFFSET} .../.platformio/packages/framework-arduinoespressif32/tools/sdk/bin/bootloader_dio_40m.bin 0x8000 .../project_folder/.pio/build/esp32doit-devkit-v1/partitions.bin 0xe000 .../.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin 0x10000 .pio/build/esp32doit-devkit-v1/firmware.bin 66 67 68Flashing 69-------- 70 71If you split the output, you’ll find the ``write_flash`` command with a list of paths to binary files and their respective flashing offsets. If necessary, change the paths to the actual file locations. 72 73Change ``PORT`` to the name of :ref:`actually used serial port <serial-port>` and run the command. A successful flash looks like this:: 74 75 $ python esptool.py -p /dev/tty.usbserial-0001 -b 460800 --before default_reset --after hard_reset --chip {IDF_TARGET_PATH_NAME} write_flash --flash_mode dio --flash_size detect --flash_freq 40m {IDF_TARGET_BOOTLOADER_OFFSET} build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin 76 esptool.py v3.2-dev 77 Serial port /dev/tty.usbserial-0001 78 Connecting......... 79 Chip is ESP32-D0WD (revision 1) 80 Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None 81 Crystal is 40MHz 82 MAC: de:ad:be:ef:1d:ea 83 Uploading stub... 84 Running stub... 85 Stub running... 86 Changing baud rate to 460800 87 Changed. 88 Configuring flash size... 89 Auto-detected Flash size: 16MB 90 Flash will be erased from 0x00001000 to 0x00007fff... 91 Flash will be erased from 0x00008000 to 0x00008fff... 92 Flash will be erased from 0x00010000 to 0x00039fff... 93 Flash params set to 0x0240 94 Compressed 25536 bytes to 15935... 95 Wrote 25536 bytes (15935 compressed) at 0x00001000 in 0.7 seconds (effective 275.5 kbit/s)... 96 Hash of data verified. 97 Compressed 3072 bytes to 103... 98 Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (effective 334.1 kbit/s)... 99 Hash of data verified. 100 Compressed 169232 bytes to 89490... 101 Wrote 169232 bytes (89490 compressed) at 0x00010000 in 2.6 seconds (effective 513.0 kbit/s)... 102 Hash of data verified. 103 104 Leaving... 105 Hard resetting via RTS pin... 106 107It is now possible to unplug the flashed device and repeat the process by connecting another one and running the command again. 108
