Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
The following advanced configuration options can be used for all esptool.py commands (they are placed before the command name on the command line).
For basic/fundamental configuration options, see the esptool.py README.
By default, esptool.py tries to hard reset the chip into bootloader mode before it starts and hard resets the chip to run the normal program once it is complete. The
--after options allow this behaviour to be changed:
Reset Before Operation
--before argument allows you to specify whether the chip needs resetting into bootloader mode before esptool.py talks to it.
--before default_resetis the default, which uses DTR & RTS serial control lines (see Entering The Bootloader) to try and reset the chip into bootloader mode.
--before no_resetwill skip any DTR/RTS control signals and just start sending a serial synchronisation command to the chip. This is useful if your chip doesn't have DTR/RTS, or for some serial interfaces (like Arduino board onboard serial) which behave differently when DTR/RTS are toggled.
Reset After Operation
--after argument allows you to specify whether the chip should be reset after the esptool.py operation completes:
--after hard_resetis the default. The DTR serial control line is used to reset the chip into a normal boot sequence.
--after soft_resetis currently only supported on ESP8266. This runs the user firmware, but any subsequent reset will return to the serial bootloader. This was the reset behaviour in esptool.py v1.x.
--after no_resetleaves the chip in the serial bootloader, no reset is performed.
Disabling Boot Stub
--no-stub option disables uploading of a software "stub loader" that manages flash operations, and only talks directly to the loader in ROM.
--no-stub will disable certain options, as not all options are implemented in every chip's ROM loader.
Overriding SPI Flash Connections
--spi-connection argument overrides the SPI flash connection configuration on ESP32. This means that the SPI flash can be connected to other pins, or esptool.py can be used to communicate with a different SPI flash chip to the default.
--spi-connection argument after the esptool.py command, ie
esptool.py flash_id --spi-connection HSPI.
--spi-connection argument is not provided, the SPI flash is configured to use pin numbers set in efuse. These are the same SPI flash pins that are used during a normal boot.
The only exception to this is if the
--no-stub option is also provided. In this case, efuse values are ignored and
--spi-connection will default to
--spi-connection SPI unless set to a different value.
--spi-connection SPI uses the default SPI pins:
- CLK = GPIO 6
- Q = GPIO 7
- D = GPIO 8
- HD = GPIO 9
- CS = GPIO 11
During normal booting, this configuration is selected if all SPI pin efuses are unset and GPIO1 (U0TXD) is not pulled low (default).
This is the normal pin configuration for ESP32 chips that do not contain embedded flash.
--spi-connection HSPI uses the HSPI peripheral instead of the SPI peripheral for SPI flash communications, via the following HSPI pins:
- CLK = GPIO 14
- Q = GPIO 12
- D = GPIO 13
- HD = GPIO 4
- CS = GPIO 15
During normal booting, this configuration is selected if all SPI pin efuses are unset and GPIO1 (U0TXD) is pulled low on reset.
Custom SPI Pin Configuration
--spi-connection <CLK>,<Q>,<D>,<HD>,<CS> allows a custom list of pins to be configured for the SPI flash connection. This can be used to emulate the flash configuration equivalent to a particular set of SPI pin efuses being burned. The values supplied are GPIO numbers.
--spi-connection 6,17,8,11,16 sets an identical configuration to the factory efuse configuration for ESP32s with embedded flash.
When setting a custom pin configuration, the SPI peripheral (not HSPI) will be used unless the
CLK pin value is set to 14 (HSPI CLK), in which case the HSPI peripheral will be used.
Specifying Arguments Via File
Anywhere on the
esptool.py command line, you can specify a file name as
@filename.txt to read one or more arguments from text file
filename.txt. Arguments can be separated by newlines or spaces, quotes can be used to enclose arguments that span multiple words. Arguments read from the text file are expanded exactly as if they had appeared in that order on the
esptool.py command line.