SYNOPSIS
esptool [,FLASH OPTION/]...esptool [,CREATION OPTION/]...
DESCRIPTION
Flash firmware files to ESP8266 or ESP32 boards with ability to automatically put certain boards into UART bootloader programming mode. Or, extract code sections from ELF executable files to create firmware files for ESP chips.OPTIONS
Flash:
- -cp <device>
- Select a serial port device to communicate with an ESP chip. Default is ,/dev/ttyUSB0/ on Linux, COM1 on Windows and ,/dev/tty.usbserial/ on Mac OS X.
- -cb <baudrate>
- Select the baud rate. Default is 115200.
- -ca <address>
- Flash memory address to upload the data to. Default is 0x00000000.
- -cf <filename>
- Upload the file to flash memory. Serial communication parameters and flash memory address must precede this argument.
- -cp <size>
- Pad last written section to the given size, in bytes.
- -cc <chip>
- Select chip to upload to. Currently supported values are: esp8266 (default), esp32.
- -cd <board>
- Reset board into bootloader mode. Default is none.
Resetting methods:
- nodemcu
- GPIO0 and RESET are controlled by two NPN transistors as implemented in NodeMCU devkit.
- wifio
- TXD controls GPIO0 via a PNP transistor, while DTR controls RESET via a capacitor.
- ck
- RTS controls RESET or CH_PD, while DTR controls GPIO0;
- none
- No DTR/RTS manipulation.
Firmware creation:
- -eo <filename>
- Open an ELF object file, parse it and cache information found therein. Only one input file could be opened at a time.
- -es <section> <filename>
- Read the given section from currently opened input file and make raw dump into the specified file.
- -ec
- Close the currently opened input file.
- -bo <filename>
- Prepare a new firmware image file for writing.
- -bm <qio|qout|dio|dout>
- Set the flash chip interface mode. Default is QIO. This parameter is stored in the firmware image header along with the flash size and flash frequency. ROM bootloader in the ESP chip uses this info to know how to talk to the flash memory chip.
- -bz <512K|256K|1M|2M|4M|8M|16M|32M>
- Set the flash chip size. Default is 512K.
- -bf <40|26|20|80>
- Set the flash chip frequency in MHz. Default is 40M.
- -bs <section>
- Read the specified section from the input file and append it to the firmware image. The sections will appear in the same order as the -bs options appear on the command line.
- -bc
- Flush the content into the firmware image and close the file.
Other:
- -v
- Display verbose informational messages. Add more v's to increase verbosity level, e.g. -vv, -vvv.
- -q
- Suppress informational messages.
- --help
- Display help.
- --version
- Display program version information.
EXAMPLES
Flash Lua script firmware to a NodeMCU board:- esptool -cd nodemcu -cf nodemcu_integer_0.9.5_20150318.bin
Flash MicroPython for ESP8266 firmware to a Huzzah or EzSBC ESP board: First reset the board into flash programming mode. Holod GPIO0/Flash button and press reset button, release the reset button and finally release the GPIO0/Flash button. Then run the following command:
- esptool -cf firmware-combined.bin
Flash Espressif AT v0.50 firmware to an ESP board: First manually reset the board into flash programming mode or use correct -cd option, then run:
- esptool -ca 0x00000 -cf noboot/eagle.flash.bin -ca 0x40000 -cf noboot/eagle.irom0text.bin -ca 0x3e000 -cf blank.bin -ca 0x7c000 -cf esp_init_data_default.bin -ca 0x7E000 -cf blank.bin
Create firmware files from app.elf. Note the option for 4M flash size.
- esptool -bz 4M -eo app.elf -bo app_00000.bin -bs .text -bs .data -bs .rodata -bc -ec -eo app.elf -es .irom0.text app_40000.bin -ec
Then, flash the created firmware to the board:
- esptool -cf 00000.bin -ca 0x40000 -cf 40000.bin