Skip to content

Flashing

Jump to bottom
Calin Crisan edited this page Jul 25, 2020 · 5 revisions

About

The Firmware

Flashing a device refers to downloading a firmware binary file into the flash memory of the device.

Here are a few things that you should know about espQToggle firmware:

  • all versions and models are built to fit within 1MB of flash memory, regardless of device type and actual available flash size
  • it has to be written at flash addess 0x0, since it also contains the boot binary file
  • it contains all required binary files (boot, esp_init_data_default and both user1 and user2 programs)
  • wiping flash memory before writing it is not necessary

If you want to read more on firmware images, see Firmware Image Format and 2a-esp8266-sdk_getting_started_guide_en.pdf, chapter 4 - Flash Maps.

Boot Modes

ESP8266/ESP8285 chips can be booted in two modes:

  • In normal execution mode, the installed firmware is started and runs as programmed.
  • In bootloader mode, also known as flashing mode or UART/serial mode, the flash memory can be read and written using a serial connection.

For flashing purposes, we are looking to boot the ESP into bootloader mode.

ESP chips have a pin called GPIO0 (or simply IO0) that controls the boot mode. It is by default "pulled high" (that is, connected to VCC through a pull-up resistor) and will determine a normal execution boot.

To boot the ESP chip into bootloader mode, GPIO0 must be "pulled low" (that is, connected to GND), when powered up. Some devices have a button that does that when pressed. For other devices, you'll need to identify the GPIO0 pin on the board and temporarily connect a secondary GND wire to it while booting.

If you want to know more about boot modes, see ESP8266 Boot Mode Selection.

Serial Flashing

The actual flashing is done using a a USB-to-serial adapter connected to the device's serial pins and plugged into your laptop's USB port. You'll need to run a flashing tool. See Requirements below for more details.

While the initial serial baud rate at which the bootloader will talk to your laptop is 74880, the flashing baud rate can be set to higher values. With 115200 you'll be on the slow but safe side, while with 921600 the flashing may fail. 460800 is usually a good choice.

An ESP device has a specific flash mode (i.e. the way in which the flash memory is connected to the chip) and flash frequency; these are known as flash parameters. Dedicated device pages on this wiki indicate the flash parameters of each supported device. When flashing, you need to identify and specify these values correctly, or the device won't boot.

Requirements

Please read the USB-to-serial adapter page and make sure the adapter has the correct parameters.

Following are some recommended flashing tools, depending on the OS you run on your laptop. These are not the only options, just some recommendations. If you already have a way of flashing ESP chips, it's probably just as good.

NodeMCU PyFlasher

NodeMCU PyFlasher is a nice tool intended to (but not restricted to) flash NodeMCU firmware. It is available for all 3 OSes (Windows, Linux and macOS).

For Windows or macOS, head over to their releases page and download the release file for your OS. The Linux version needs building from source, though.

When performing the flashing procedure, configure it as follows:

  • allow it to autoselect the serial port
  • use the NodeMCU firmware option to select your firmware file
  • select 460800 baud rate
  • set the flash mode to the one indicated under Flash Parameters in the dedicated device wiki page
  • tell it not to erase the flash

esptool

esptool is the official flashing tool maintained by Espressif, the ESP chip maker. The good news is that it works on all platforms. The bad news is that it is a command-line tool that you may not be comfortable with.

On Windows, you'll need to install Python first. Download the installer from the downloads page (choose the "executable installer", latest version). When installing, make sure you enable the add Python to path option. On Linux and macOS you most likely already have Python installed.

Open a terminal (in Windows, a command prompt) and install esptool using the following command:

pip install esptool

You should now be able to run the esptool.py command in the very same terminal. To start flashing, use the following command:

esptool.py -p <serial_port> -b <baud> write_flash -ff <freq> -fm <mode> -fs 1MB 0 <firmware.bin>

Replace arguments as follows:

  • <serial_port> with the actual serial port (usually /dev/ttyUSB0 on Linux, COM1..COM9 on Windows)
  • <baud> with the desired baud rate (460800 if in doubt)
  • <freq> with flash frequency indicated in your device's wiki page (normally 40m)
  • <mode> with flash frequency indicated in your device's wiki page (dio, dout, qio or qout)
  • <firmware.bin> with the full path to where you downloaded the firmware file

The flashing process should take between 30 seconds and two minutes, depending on selected baud rate. If the output keeps showing "Connecting..." for more than 1-2 seconds, esptool is not able to perform the flashing. In that case, see Troubleshooting below.

Procedure

  1. ⚠️ Do not power the device from mains while flashing! Do not connect it to AC at all during this procedure!
  2. In the wiki page dedicated to your device, make note of the Flash Parameters (flash mode and frequency). You'll need to supply them to the flashing tool.
  3. Go to the latest release page and download the firmware.bin file corresponding to your device flash parameters. Your flashing tool will probably override the flash parameters embedded into the firmware file so you could probably download any of the firmware variant, anyway.
  4. Ensure the USB-to-serial adapter is properly connected.
  5. Ensure your device is booted in bootloader mode (the device wiki page will tell you how to do it).
  6. Pass the required parameters to the flashing tool. Parameters include serial port, baud rate, full path to firmware file, flash mode and optionally flash frequency.
  7. Start the flashing process using your flashing tool.
  8. After the process has successfuly completed, you can disconnect the USB-to-serial adapter from the device.

Troubleshooting

Tips

If the flashing operation fails, here are some ideas:

  • Try swapping the RX and TX connectors.
  • Reduce the baud rate; 115200 is a safe value.
  • Ensure the device has been booted in bootloader mode. Use a serial terminal to verify that if you want to be sure.
  • Ensure that no program other than your flashing tool uses the serial port.
  • Ensure that your USB-to-serial adapter supplies enough current for the device; if your laptop senses that the USB disconnects, it's a sign of reset due to limited current.
  • Double check the wire connections.
  • Try to reset the device by unplugging and plugging back the USB-to-serial adapter or by reconnecting the VCC wire.

Serial Terminal

Using a serial terminal to see what the ESP chip has to say at boot can be a good way of troubleshooting flashing issues.

If you're a Windows user, install your favorite serial terminal program. Termite is just one of the many available solutions.

If you're running Linux or macOS, you can install the PySerial Python package that comes with the miniterm.py command line utility:

pip install pyserial

Then you can run miniterm as follows (replacing /dev/ttyUSB0 with your actual serial port, 74880 being the fixed bootloaderbaud rate):

miniterm.py /dev/ttyUSB0 74880

The boot sequence contains the following line (or similar) indicating the boot mode:

ets Jan  8 2013,rst cause: 1, boot mode:(1,6)

The first value of the boot mode pair will be 1 when device boots in bootloader mode and should be 3 when it boots in normal execution mode.

In normal execution mode, the boot log will continue by indicating the flash parameters and user program number, e.g.:

2nd boot version : 1.7
  SPI Speed      : 40 MHz 
  SPI Mode       : QIO
  SPI Flash Size & Map: 8MBit (512KB+512KB)
jump to user2 @ 81000

Home

Supported Devices

Installing Firmware

Initial Setup

Provisioning

Development

Clone this wiki locally