Boot Mode Selection

This guide explains how to select the boot mode correctly and describes the boot log messages of ESP8266.

On many development boards with built-in USB/Serial, this is done for you and esptool can automatically reset the board into bootloader mode. For other configurations, you will need to follow these steps:

Required Pins

The following ESP8266 pins must be in a known state for either normal (flash boot) or serial bootloader operation. Most development boards or modules make necessary connections already, internally:

GPIO

State

15

Pulled Low/GND (directly connected to GND, or external pull-down resistor)

2

Pull-up resistor High/VCC, or No Connection (pin has internal weak pullup, external pullup resistor is optional)

If these pins are set differently to shown, nothing on the ESP8266 will work as expected. See ESP8266 Pin List document to see what boot modes are enabled for different pin combinations.

When the ESP8266 goes into serial bootloader mode, the Boot ROM switches GPIO2 to an output and the UART TX signal is also output to this pin. For this reason GPIO2 should not be directly connected to VCC. Similarly, make sure GPIO2 is not connected to another peripheral where this may cause an issue when in download mode.

Select Bootloader Mode

The ESP8266 will enter the serial bootloader when GPIO0 is held low on reset. Otherwise it will run the program in flash.

GPIO0 Input

Mode

Low/GND

ROM serial bootloader for esptool

High/VCC

Normal execution mode

Many configurations use a “Flash” button that pulls GPIO0 low when pressed.

Automatic Bootloader

esptool.py resets ESP8266 automatically by asserting DTR and RTS control lines of the USB to serial converter chip, i.e., FTDI, CP210x, or CH340x. The DTR and RTS control lines are in turn connected to GPIO0 and EN (CHIP_PU) pins of ESP8266, thus changes in the voltage levels of DTR and RTS will boot the ESP8266 into Firmware Download mode.

Note

When developing esptool.py, keep in mind DTR and RTS are active low signals, i.e., True = pin @ 0V, False = pin @ VCC.

As an example of auto-reset curcuitry implementation, check the schematic of the ESP32 DevKitC development board:

  • The Micro USB 5V & USB-UART section shows the DTR and RTS control lines of the USB to serial converter chip connected to GPIO0 and EN pins of the ESP module.

  • Some OS and/or drivers may activate RTS and or DTR automatically when opening the serial port (true only for some serial terminal programs, not esptool.py), pulling them low together and holding the ESP in reset. If RTS is wired directly to EN then RTS/CTS “hardware flow control” needs to be disabled in the serial program to avoid this. An additional circuitry is implemented in order to avoid this problem - if both RTS and DTR are asserted together, this doesn’t reset the chip. The schematic shows this specific circuit with two transistors and its truth table.

  • If this circuitry is implemented (all Espressif boards have it), adding a capacitor between the EN pin and GND (in the 1uF-10uF range) is necessary for the reset circuitry to work reliably. This is shown in the ESP32 Module section of the schematic.

  • The Switch Button section shows buttons needed for manually switching to bootloader.

Make the following connections for esptool to automatically enter the bootloader of an ESP8266 chip:

ESP Pin

Serial Pin

EN

RTS

GPIO0

DTR

In Linux serial ports by default will assert RTS when nothing is attached to them. This can hold the ESP8266 in a reset loop which may cause some serial adapters to subsequently reset loop. This functionality can be disabled by disabling HUPCL (ie sudo stty -F /dev/ttyUSB0 -hupcl).

(Some third party ESP8266 development boards use an automatic reset circuit for EN & GPIO0 pins, but don’t add a capacitor on the EN pin. This results in unreliable automatic reset, especially on Windows. Adding a 1uF (or higher) value capacitor between EN pin and GND may make automatic reset more reliable.)

In general, you should have no problems with the official Espressif development boards. However, esptool.py is not able to reset your hardware automatically in the following cases:

  • Your hardware does not have the DTR and RTS lines connected to GPIO0 and EN (CHIP_PU)

  • The DTR and RTS lines are configured differently

  • There are no such serial control lines at all

Manual Bootloader

Depending on the kind of hardware you have, it may also be possible to manually put your ESP8266 board into Firmware Download mode (reset).

  • For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset a development board, hold down the Boot button (GPIO0) and press the EN button (EN (CHIP_PU)).

  • For other types of hardware, try pulling GPIO0 down.

Note

If esptool is able to reset the chip but for some reason the chip is not entering into bootloader mode then hold down the Boot button (or pull down GPIO0) while you start esptool and keep it down during reset.

Boot Log

The ESP8266 boot rom writes a log to the UART when booting. The timing is a little bit unusual: 74880 baud (see Serial Port Settings).

ets Jan  8 2014,rst cause 1, boot mode:(3,7)

load 0x40100000, len 24236, room 16
tail 12
chksum 0xb7
ho 0 tail 12 room 4
load 0x3ffe8000, len 3008, room 12
tail 4
chksum 0x2c
load 0x3ffe8bc0, len 4816, room 4
tail 12
chksum 0x46
csum 0x46

Explanation

rst_cause:

Value

Meaning

1

power-on

2

external-reset

4

hardware watchdog-reset

The first parameter of boot_mode:

Value

Meaning

1 (eg. boot mode:(1,x))

UART download mode (download FW into Flash)

2 (eg. boot mode:(3,x))

Boot from flash mode

chksum:

If value of “chksum” == value of “csum”, it means flash has been read correctly during booting.

The rest of boot messages are used internally by Espressif.