Downloading Guide

[中文]

This guide takes ESP32-WROOM-32 as an example to describe how to download AT firmware and flash it into the module. The same steps apply to other ESP32 modules.

Before downloading and flashing AT firmware, ensure that the hardware is connected correctly. See Hardware Connection.

The AT commands supported by the default firmware differ across module series. See ESP-AT Firmware Differences.

Follow the steps below to download, flash, and verify the AT firmware.

Step 1. Download AT Firmware
Step 2. Flash AT Firmware into Your Device
- Flash the Factory Bin (Recommended)
  - Windows
  - Linux or macOS
- Flash Multiple Bins According to download.config
  - Windows
  - Linux or macOS
Step 3. Check Whether AT Works

Step 1. Download AT Firmware

Go to ESP32 Released Firmware, download the firmware for your module, and extract the package.

See ESP32-WROOM-32 Series for ESP32-WROOM-32 firmware.

The factory directory contains two combined factory bins. Either can be flashed to address 0x0:

factory/factory_WROOM-32_unfilled.bin (recommended): a single bin with all required functions, and the smallest and fastest to flash. Provided in newly released firmware packages. Necessary unused regions are filled with 0xFF up to the end of the AT application firmware esp-at.bin in the ota_0 partition. If the package does not include this file, use factory/factory_WROOM-32.bin.
factory/factory_WROOM-32.bin: a single bin with all required functions, but larger and slower to flash. The earlier fill method, still included in new firmware packages. Filling extends through the end of the last partition ota_1. The file size is typically 2 MB or 4 MB.

For other files in the package, see Appendix: Firmware Package Contents.

Step 2. Flash AT Firmware into Your Device

Choose a flashing method according to your use case.

Method	Recommended scenario	Notes
Method 1	First-time flashing or factory production	Flash one factory bin to `0x0`. `factory/factory_WROOM-32_unfilled.bin` is recommended.
Method 2	Updating selected partitions or secondary development	Flash multiple bins to the addresses specified in `download.config`.

Flash the Factory Bin (Recommended)

Flash factory/factory_WROOM-32_unfilled.bin (recommended) or factory/factory_WROOM-32.bin to address 0x0.

Windows

Download Flash Download Tool for Windows. See the Flash Download Tool User Guide for details. Confirm the COM port number of the download interface, and select it from the “COM:” dropdown list. To identify the port, see Check port on Windows.

Open Flash Download Tool.
Select chipType. (Here, select ESP32.)
Select a workMode. (Here, select Developer Mode.)
Select a loadMode. (Here, select uart.)

Firmware Download Configurations
Select factory/factory_WROOM-32_unfilled.bin (recommended) or factory/factory_WROOM-32.bin, and set the address to 0x0.
Select “DoNotChgBin” to use the flash parameters in the factory bin.
Select the correct COM port and start flashing.

Download to One Address (click to enlarge)

When you finish flashing, check whether AT works.

Linux or macOS

Install esptool:

pip install esptool

Replace the port name in the following command with the download interface of the board, and run the command in the extracted firmware directory. If you do not know the interface name, see Check port on Linux and macOS. factory/factory_WROOM-32_unfilled.bin is recommended.

esptool --chip auto --port /dev/tty.usbserial-0001 --baud 115200 --before default-reset --after hard-reset write-flash -z --flash-mode dio --flash-freq 40m --flash-size 4MB 0x0 factory/factory_WROOM-32_unfilled.bin

When you finish flashing, check whether AT works.

Flash Multiple Bins According to download.config

Use this method to update selected partitions or for secondary development. Configure the download address of each bin and the flash parameters according to download.config.

The download.config file of the ESP32-WROOM-32 firmware is shown below:

--flash-mode dio --flash-freq 40m --flash-size 4MB
0x1000 bootloader/bootloader.bin
0x8000 partition_table/partition-table.bin
0x10000 ota_data_initial.bin
0x20000 at_customize.bin
0x21000 customized_partitions/mfg_nvs.bin
0x100000 esp-at.bin

--flash-mode dio means the firmware is compiled with flash DIO mode.
--flash-freq 40m means the firmware’s flash frequency is 40 MHz.
--flash-size 4MB means the firmware requires a flash of at least 4 MB.
0x10000 ota_data_initial.bin means downloading ota_data_initial.bin into the address 0x10000.

Windows

The tool configuration is the same as in Flash the Factory Bin (Recommended) for Windows, with the following differences:

Configure each bin and its address according to download.config.
Do not select “DoNotChgBin”. Set SPI SPEED and SPI MODE to match download.config.

Download to Multiple Addresses (click to enlarge)

When you finish flashing, check whether AT works.

Linux or macOS

Replace PORTNAME with the download interface of the board, replace download.config with the parameters in that file, and run the command in the extracted firmware directory. If you do not know the interface name, see Check port on Linux and macOS.

esptool --chip auto --port PORTNAME --baud 115200 --before default-reset --after hard-reset write-flash -z download.config

Below is the example command for ESP32-WROOM-32.

esptool --chip auto --port /dev/tty.usbserial-0001 --baud 115200 --before default-reset --after hard-reset write-flash -z --flash-mode dio --flash-freq 40m --flash-size 4MB 0x8000 partition_table/partition-table.bin 0x10000 ota_data_initial.bin 0x1000 bootloader/bootloader.bin 0x100000 esp-at.bin 0x20000 at_customize.bin 0x21000 customized_partitions/mfg_nvs.bin

When you finish flashing, check whether AT works.

Step 3. Check Whether AT Works

Open a serial port tool, such as SecureCRT. Connect to the port attached to the “AT command/response” line (see Hardware Connection) with the following settings:

Parameter	Value
Baudrate	115200
Data Bits	8
Parity	None
Stop Bits	1
Flow Type	None
New line	CR LF

Enter the command AT+GMR with a new line. If the response is OK as shown below, AT works.

AT+GMR
AT version:3.2.0.0(s-ec2dec2 - ESP32 - Jul 28 2023 07:05:28)
SDK version:v5.0.2-376-g24b9d38a24-dirty
compile time(6118fc22):Jul 28 2023 09:47:28
Bin version:v3.2.0.0(WROOM-32)

OK

If there is no OK response, check the ESP32 startup log to confirm that the firmware initialized correctly.

Open a serial port tool and select the port attached to the “Download/Log output” line. See Hardware Connection.
Set Baudrate to 115200, Data Bits to 8, Parity to None, Stop Bits to 1, and Flow Type to None.
Press the RST key of the board. If the log is similar to the reference log below, ESP-AT firmware has been initialized correctly.

Reference Log

ESP32 startup log:

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0030,len:5884
ho 0 tail 12 room 4
load:0x40078000,len:15844
load:0x40080400,len:3560
entry 0x40080604
I (29) boot: ESP-IDF v5.0-541-g885e501d99-dirty 2nd stage bootloader
I (29) boot: compile time 08:40:13
I (29) boot: chip revision: v1.0
I (34) boot.esp32: SPI Speed      : 40MHz
I (38) boot.esp32: SPI Mode       : DIO
I (43) boot.esp32: SPI Flash Size : 4MB
I (47) boot: Enabling RNG early entropy source...
I (53) boot: Partition Table:
I (56) boot: ## Label            Usage          Type ST Offset   Length
I (64) boot:  0 phy_init         RF data          01 01 0000f000 00001000
I (71) boot:  1 otadata          OTA data         01 00 00010000 00002000
I (78) boot:  2 nvs              WiFi data        01 02 00012000 0000e000
I (86) boot:  3 at_customize     unknown          40 00 00020000 000e0000
I (93) boot:  4 ota_0            OTA app          00 10 00100000 00180000
I (101) boot:  5 ota_1            OTA app          00 11 00280000 00180000
I (108) boot: End of partition table
I (113) esp_image: segment 0: paddr=00100020 vaddr=3f400020 size=1a854h (108628) map
I (161) esp_image: segment 1: paddr=0011a87c vaddr=3ff80063 size=00008h (     8) load
I (161) esp_image: segment 2: paddr=0011a88c vaddr=3ffbdb60 size=04d5ch ( 19804) load
I (174) esp_image: segment 3: paddr=0011f5f0 vaddr=40080000 size=00a28h (  2600) load
I (176) esp_image: segment 4: paddr=00120020 vaddr=400d0020 size=11f5c0h (1177024) map
I (609) esp_image: segment 5: paddr=0023f5e8 vaddr=40080a28 size=1e948h (125256) load
I (660) esp_image: segment 6: paddr=0025df38 vaddr=400c0000 size=00064h (   100) load
I (676) boot: Loaded app from partition at offset 0x100000
I (676) boot: Disabling RNG early entropy source...
no external 32k oscillator, disable it now.
at param mode: 1
AT cmd port:uart1 tx:17 rx:16 cts:15 rts:14 baudrate:115200
module_name: WROOM-32
max tx power=78, ret=0
2.5.0

Appendix: Firmware Package Contents

The extracted AT firmware package has the following structure (see also Brief Introduction to AT Firmware):

.
├── at_customize.bin                 // secondary partition table
├── bootloader                       // bootloader
│   └── bootloader.bin
├── customized_partitions            // AT customized binaries
│   ├── mfg_nvs.csv                  // raw data of manufacturing nvs partition
│   └── mfg_nvs.bin                  // manufacturing nvs partition binary
├── download.config                  // configuration of downloading
├── esp-at.bin                       // AT application binary
├── esp-at.elf
├── esp-at.map
├── factory                          // Combined bins for factory downloading
│   ├── factory_XXX.bin              // Combined factory bin filled through the end of ota_1
│   └── factory_XXX_unfilled.bin     // Combined factory bin filled through the end of the AT application (recommended)
├── flasher_args.json                // flasher arguments
├── ota_data_initial.bin             // ota data parameters
├── partition_table                  // primary partition table
│   └── partition-table.bin
└── sdkconfig                        // compilation configuration for AT firmware

Provide feedback about this document