Firmware Update

[中文]

How does the host MCU flash ESP32 via serial interfaces?

How to download firmware for ESP32 series modules using the USB-Serial tool?

How to flash firmware on macOS and Linux?

  • For the Apple system (macOS), you can use esptool downloaded via brew or git to flash firmware.

  • For the Linux system (e.g., Ubuntu), you can use esptool downloaded via apt-get or git to flash firmware.

Does ESP32 support programming using JTAG pins directly?

ESP32 supports flashing programs directly using JTAG pins. Please refer to Upload the application to be debugged. For detailed steps, see Using the ESP32 JTAG interface for firmware download in a Windows environment.

Note: For mass production flashing, it is recommended to use the flash download tool to flash the firmware. For detailed instructions, see Choosing the appropriate burning platform.

Does ESP_Flash_Downloader_Tool support customized programming control?

  • The GUI tool is not open-sourced and does not support embedded executive script.

  • The low-level component esptool is open-sourced and can be used to perform all functions such as flashing and encryption. It is recommended to conduct secondary development based on this component.

Can I enable the Secure Boot function for ESP32 via OTA?

  • It is not recommended to enable Secure Boot through OTA, as it poses operational risks and requires multiple OTA firmware updates.

  • Since the Secure Boot function is in Bootloader, please update Bootloader first to enable this function.

    1. First, check whether the partition table of your current device can store the Bootloader with Secure Boot enabled.

    2. Then, update an intermediate firmware which can be written in the Bootloader partition. By default, the Bootloader partition cannot be erased or written, you need to enable them via make menuconfig.

    3. Sign the intermediate firmware and upgrade it to the target device through OTA. Then upgrade the Bootloader of this firmware and the signed new firmware through OTA.

    4. If there are situations such as powered-down or network break-down and restart during the Bootloader OTA process, the device will not be booted and needs to be re-flashed.

How to resolve the following error that occurred when flashing firmware to ESP32-S2 based on ESP-IDF v4.1?

esptool.py v2.9-dev
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32S2 Beta
Features: Engineering Sample
Crystal is 40MHz
MAC: 7c:df:a1:01:b7:64
Uploading stub...
Running stub...

A fatal error occurred: Invalid head of packet (0x50)
esptool.py failed with exit code 2

Solution:

If you are using ESP32-S2 instead of ESP32-S2 Beta, please update ESP-IDF to v4.2 or later versions.

Notes:

  • ESP-IDF v4.1 only supports ESP32-S2 Beta, which is not compatible with ESP32-S2.

  • The version of esptool that comes with ESP-IDF v4.1 is v2.9-dev, which only supports ESP32-S2 Beta as well.

  • Both ESP-IDF v4.2 and its esptool v3.0-dev support ESP32-S2 series chips.

How to download firmware based on ESP-IDF using flash_download_tool?

  • Please refer to get-started-guide when building an ESP-IDF project for the first time.

  • Taken hello-world example for instance, run idf.py build (supports ESP-IDF v4.0 and later versions, for versions before v4.0, please use make). After building, the following flash command for the bin file will be generated:

#Project build complete. To flash, run this command:
../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
or run 'idf.py -p PORT flash'

You can use flash_download_tool to flash according to the bin file and flash address prompted by this command.

What is the communication protocol for flashing ESP chips?

How to program ESP32-C3’s firmware offline?

  • Currently, no tool supports the offline programming of ESP32-C3’s firmware. However, the official Flash Download Tools can directly download binary firmware and support mass production download mode for up to eight ESP32-C3 devices at the same time.

  • In addition, we also provide Test Fixture for mass production, which supports up to four ESP32-C3 modules to download firmware simultaneously.

How to set the flash SPI mode to QIO mode on ESP32?

Go to menuconfig and set it through Serial flasher config > Flash SPI mode, the corresponding API is esp_image_spi_mode_t.

After downloading the program and powering on EPS8266, the serial port printed the following log. What is the reason?

ets Jan  8 2013,rst cause:1, boot mode:(7,7)
waiting for host

waiting for host means the Boot is in SDIO mode, indicating that GPIO15 (MTDO) is pulled up (HIGH). Please refer to ESP8266 Boot Mode Description.

What are the Espressif module programming tools?

  • For Espressif programming software, please go to Flash Download Tools. Installation-free GUI tools are for the Windows environment only.

  • Espressif programming tool esptool is written based on Python with open-source code, supporting secondary development.

What is the difference between the Factory mode and Developer mode of the flash download tool?

  • Factory mode supports multi-channel downloads, while Developer mode only supports single channel.

  • The path of bin files under the Factory mode is relative, while under Developer is absolute.

The ESP32-C3 chip should be able to conduct firmware download through USB, but I failed to do so under ESP-IDF v4.3. So, how can I use USB for firmware download?

You need to compile under ESP-IDF v4.4 or above versions. After pulling the latest branch and updating the IDF tool, you can compile normally and use USB for download. Please refer to usb-serial-jtag-console.

Why does the programming fail for the jig with a 4-port hub in factory mode?

:CHIP: ESP32 | ESP8266 :

  • It is because Espressif products complete the calibration operation by transmitting some packets when starting up. This operation requires a 3.3 V voltage and a guaranteed peak current of 500 mA. Therefore, when it comes to more than one port, there will be situations where the computer cannot program or the programming is interrupted due to the insufficient power supply of the computer’s USB when programming via connecting to a computer’s USB. It is recommended to use the hub for programming and supply power to the hub in the meantime.

I’m using an ESP32-WROVER-B module to download the AT firmware via the flash download tool. However, an error occurred after writing to flash. But the same operation succeeded when replacing the module with ESP32-WEOVER-E, what is the reason?

  • The ESP32-WROVER-B module leads out the SPI flash pin, but the ESP32-WROVER-E module does not. Please check whether the SPI flash pin of the ESP32-WROVER-B module is reused by other external application circuits.

  • Connecting the CMD pin of the SPI flash in ESP32-WROVER-B to GND will cause the flash to fail to start. The following error log will be printed:

rst:0x10 (RTCWDT_RTC_RESET),boot:0x1b (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets Jun 8 2016 00:22:57

Why can’t the Flash Download Tools be used to reflash the firmware on a device that has enabled flash encryption but not disabled the download mode?

CHIP: ESP32 | ESP32-S2

  • The default configuration of the flash download tool has enabled eFuse verification. If you want to reflash the firmware of a device that has already enabled flash encryption, please modify the following configuration:

    • Modify the default configuration in the esp32 > security.conf file, change flash_force_write_enable = False to flash_force_write_enable = True.

    • Modify the default configuration in the esp32 > spi_download.conf file, change no_stub = False` to `no_stub = True.

  • Note: When reflashing the firmware on devices with flash encryption enabled, the reflashed firmware must use the same flash encryption key. If the keys do not match, the new firmware will not function properly.

When updating ESP32 firmware through the UART interface based on esptool serial port protocol, can I add a new app partition?

The actual partitioning of the flash primarily depends on the data in partition_table.bin. If partition_table.bin can be updated, the storage space for other data such as bootloader.bin, app.bin, etc., can be re-partitioned, thereby adding a new app partition.

I am using ESP8266 to download the firmware via the flash download tool. After downloading the firmware, there is no programming output log, and the serial port prints the following messages. What could be the reason?

ets Jan  8
2013,rst cause:1, boot mode:(3,7)
ets_main.c

  • Please check whether the hardware wiring is correct. See Boot mode wiring instructions.

  • Please check whether the download offset address of bootloader.bin is correct. The offset address downloaded from bootloader.bin of ESP8266 is “0x0”. If the offset address is wrong, the flash cannot be started.

Why does my USB driver fail to be recognized by the Windows 7 system?

Please download and install the USB Serial JTAG driver manually for the Windows 7 system.

After using the ESP32-WROVER-E module to download the program, the following log is printed after powered on. What could be the reason?

rst：0x10 （RTCWDT_RTC_RESET），boot:0x37（SPI_FLASH_BOOT）
【2020-12-11 15:51:42 049】invalrd header：0xffffffff
invalrd header：0xffffffff
invalrd header：0xffffffff

  • Generally, it is because the GPIO12 was pulled high. It is recommended to pull it low and see the results. Please see ESP32 Boot Log Guide.

When using the Flash Download Tools to flash ESP32-C3 via USB, 8-download data fail occurs repeatedly. How can I solve it?

  • Please erase the chip completely first before flashing.

  • This problem has been solved in V3.9.4 and above versions.

On ESP32, the bootloader.bin of ESP-IDF v3.0 can not start app.bin of ESP-IDF v5.0. Why?

When booting the app.bin of ESP-IDF v5.0 with the bootloader.bin of ESP-IDF v3.0, it is necessary to enable the configuration option idf.py menuconfig > Build type > [*] App compatible with bootloader and partition table before ESP-IDF v3.1 on ESP-IDF v5.0.

Does ESP32-C3 support disabling ROM code logs via OTA?

Yes. You can disable the ROM code log by enabling the Boot ROM Behavior → Permanently change Boot ROM output → (X) Permanently disable logging configuration in the software, and then update the firmware via OTA.

Will the operation of other tasks be affected when the chip is undergoing an OTA firmware upgrade (esp_ota_write())?

During the OTA process, the cache will be turned off when writing to the flash, which will affect peripheral interrupts and some SPI tasks. Therefore, it is not recommended to perform other tasks during this period.

How many devices can be flashed at once in factory mode using Flash Download Tool?

Currently, up to 20 devices are supported. You need to update to the latest version of the Flash Download Tool (3.7.8) and modify the configuration file flash_download_tool\configure\esp32s3\multi_download.conf as follows:

[MULTI_UI_CONFIG]
multi_col = 4

Does ESP32 OTA support resumable uploads?

Supported. Please refer to OTA Resumption.

When using esptool for host computer development, after increasing the download baud rate to above 1,152,000, there is no significant improvement in download speed. Is this a limitation imposed by esptool?

esptool itself does not limit the baud rate. As the baud rate continues to increase, the data processing time of the host computer and the chip becomes the main bottleneck, and simply increasing the baud rate no longer significantly improves the download speed. Currently, there are no more methods to further increase the download speed.

How to resolve the firmware flashing failure when developing with ESP32-P4X-Function-EV-Board based on ESP-IDF v5.5.3 or ESP-IDF v5.5.4?

You may encounter the following error when flashing firmware to the ESP32-P4X-Function-EV-Board (using ESP32-P4 v3.2 chip version):

esptool v5.2.dev1
Serial port COM3:
Note: Pre-connection option "no-reset" was selected. Connection may fail if the chip is not in bootloader or flasher stub mode.
Connected to ESP32-P4 on COM3:
Chip type:        ESP32-P4 (revision v3.2)
Features:         Dual Core + LP Core, 400MHz
Crystal frequency: 40MHz
USB mode:         USB-Serial/JTAG
MAC:              e8:f6:0a:e3:a9:32

Stub flasher running.


Hard resetting via RTS pin...

A serial exception error occurred: Write timeout
Note: This error originates from pySerial. It is likely not a problem with esptool, but with the hardware connection or drivers.
For troubleshooting steps visit: https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html

Or:

esptool.py v4.12.dev1
Serial port /dev/ttyACM0
Connecting...
Chip is ESP32-P4 (revision v3.2)
Features: High-Performance MCU
Crystal is 40MHz
USB mode: USB-Serial/JTAG
MAC: 30:ed:a0:ed:39:9f
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 921600

A fatal error occurred: Guru Meditation Error detected
CMake Error at run_serial_tool.cmake:67 (message):

Solution:

These issues can be resolved by upgrading esptool to v5.3.dev3 or v4.12.dev2 via pip:

pip install esptool==5.3.dev3
pip install esptool==4.12.dev2

If the download is slow, you can configure the pip mirror source:

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Note: After updating esptool, you may encounter an error stating that the esptool version does not meet the constraints when flashing with idf.py flash. To fix this, you need to modify the espidf.constraints.*.txt file in the IDF_TOOLS_PATH directory (for example, the file name for version v5.5 is espidf.constraints.v5.5.txt).

  • Linux/macOS default path: ~/.espressif/espidf.constraints.v5.5.txt

  • Windows default path: %USER_PROFILE%\.espressif\espidf.constraints.v5.5.txt

If you customized the IDF_TOOLS_PATH environment variable during the installation of ESP-IDF, then the constraint file is located under the corresponding custom path. For more details, please refer to Downloadable IDF Tools.

Open the file, locate the line containing the esptool constraint (e.g., esptool==4.12.dev1), and update it to the newly installed version (such as esptool~=5.3.dev3 or esptool~=4.12.dev2). Once saved, idf.py flash should function correctly.


Suggestion on this document?

 Provide feedback