1.. _advanced-options:
2
3Advanced Options
4================
5
6The following advanced configuration options can be used for all esptool commands (they are placed before the command name on the command line).
7
8For basic/fundamental configuration options, see the :ref:`options` page.
9
10Reset Modes
11-----------
12
13By default, esptool 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 ``--before`` and ``--after`` options allow this behavior to be changed:
14
15Reset Before Operation
16^^^^^^^^^^^^^^^^^^^^^^
17
18The ``--before`` argument allows you to specify whether the chip needs resetting into bootloader mode before esptool talks to it.
19
20.. list::
21
22    * ``--before default_reset`` is the default, which uses DTR & RTS serial control lines (see :ref:`entering-the-bootloader`) to try to reset the chip into bootloader mode.
23    * ``--before no_reset`` will skip DTR/RTS control signal assignments 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.
24    * ``--before no_reset_no_sync`` will skip DTR/RTS control signal assignments and skip also the serial synchronization command. This is useful if your chip is already running the :ref:`stub bootloader <stub>` and you want to avoid resetting the chip and uploading the stub again.
25    :esp32c3 or esp32s3 or esp32c6 or esp32h2 or esp32p4: * ``--before usb_reset`` will use custom reset sequence for USB-JTAG-Serial (used for example for ESP chips connected through the USB-JTAG-Serial peripheral). Usually, this option doesn't have to be used directly. Esptool should be able to detect connection through USB-JTAG-Serial.
26
27Reset After Operation
28^^^^^^^^^^^^^^^^^^^^^
29
30The ``--after`` argument allows you to specify whether the chip should be reset after the esptool operation completes:
31
32.. list::
33
34    * ``--after hard_reset`` is the default. The DTR serial control line is used to reset the chip into a normal boot sequence.
35    :esp8266:* ``--after soft_reset`` This runs the user firmware, but any subsequent reset will return to the serial bootloader. This was the reset behaviour in esptool v1.x.
36    * ``--after no_reset`` leaves the chip in the serial bootloader, no reset is performed.
37    * ``--after no_reset_stub`` leaves the chip in the stub bootloader, no reset is performed.
38
39
40Connect Loop
41------------
42
43Esptool supports connection loops, where the user can specify how many times to try to open a port. The delay between retries is 0.1 seconds. This can be useful for example when the chip is in deep sleep or esptool was started before the chip was connected to the PC. A connection loop can be created by setting the ``ESPTOOL_OPEN_PORT_ATTEMPTS`` environment variable.
44This feature can also be enabled by using the ``open_port_attempts`` configuration option, for more details regarding config options see :ref:`Configuration file <config>` section.
45There are 3 possible values for this option:
46
47.. list::
48
49    * ``0`` will keep trying to connect to the chip indefinitely
50    * ``1`` will try to connect to the chip only once (default)
51    * ``N`` will try to connect to the chip N times
52
53
54.. note::
55
56    This option is only available if both the ``--port`` and ``--chip`` arguments are set.
57
58
59
60.. _disable_stub:
61
62Disabling the Stub Loader
63-------------------------
64
65The ``--no-stub`` option disables uploading of a software "stub loader" that manages flash operations, and only talks directly to the loader in ROM.
66
67Passing ``--no-stub`` will disable certain options, as not all options are implemented in every chip's ROM loader.
68
69.. only:: not esp8266
70
71    Overriding SPI Flash Connections
72    --------------------------------
73
74    The optional ``--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 can be used to communicate with a different SPI flash chip to the default.
75
76    Supply the ``--spi-connection`` argument after the ``esptool.py`` command, ie ``esptool.py flash_id --spi-connection HSPI``.
77
78    Default Behavior
79    ^^^^^^^^^^^^^^^^
80
81    If the ``--spi-connection`` argument is not provided, the SPI flash is configured to use :ref:`pin numbers set in efuse <espefuse-spi-flash-pins>`. These are the same SPI flash pins that are used during a normal boot.
82
83    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.
84
85    .. only:: esp32
86
87        SPI Mode
88        ^^^^^^^^
89
90        ``--spi-connection SPI`` uses the default SPI pins:
91
92        * CLK = GPIO 6
93        * Q = GPIO 7
94        * D = GPIO 8
95        * HD = GPIO 9
96        * CS = GPIO 11
97
98        During normal booting, this configuration is selected if all SPI pin efuses are unset and GPIO1 (U0TXD) is not pulled low (default).
99
100        This is the normal pin configuration for ESP32 chips that do not contain embedded flash.
101
102        HSPI Mode
103        ^^^^^^^^^
104
105        ``--spi-connection HSPI`` uses the HSPI peripheral instead of the SPI peripheral for SPI flash communications, via the following HSPI pins:
106
107        * CLK = GPIO 14
108        * Q = GPIO 12
109        * D = GPIO 13
110        * HD = GPIO 4
111        * CS = GPIO 15
112
113        During normal booting, this configuration is selected if all SPI pin efuses are unset and GPIO1 (U0TXD) is pulled low on reset.
114
115    Custom SPI Pin Configuration
116    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
117
118    ``--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.
119
120    .. only:: esp32
121
122        For example, ``--spi-connection 6,17,8,11,16`` sets an identical configuration to the factory efuse configuration for ESP32s with embedded flash.
123
124        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.
125
126    .. note::
127
128        Some GPIO pins might be shared with other peripherals. Therefore, some SPI pad pin configurations might not work reliably or at all. Use a different combination of pins if you encounter issues.
129
130Specifying Arguments via File
131-----------------------------
132.. _specify_arguments_via_file:
133
134Anywhere on the esptool 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 command line.
135
136An example of this is available in the :ref:`merge_bin <merge-bin>` command description.
137
138.. note:: PowerShell users
139
140    Because of `splatting <https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting?view=powershell-7.3>`__ in PowerShell (method of passing a collection of parameter values to a command as a unit) there is a need to add quotes around @filename.txt ("@filename.txt") to be correctly resolved.
141
142Filtering serial ports
143----------------------
144.. _filtering_serial_ports:
145
146``--port-filter <FilterType>=<FilterValue>`` allows limiting ports that will be tried. This can be useful when esptool is run on a system
147with many serial ports. There are a few different types that can be combined. A port must match all specified FilterTypes, and must match
148at least one FilterValue for each specified FilterType to be considered. Example filter configurations:
149
150.. list::
151
152    * ``--port-filter vid=0x303A`` matches ports with the Espressif USB VID.
153    * ``--port-filter vid=0x303A --port-filter vid=0x0403`` matches Espressif and FTDI ports by VID.
154    * ``--port-filter vid=0x303A --port-filter pid=0x0002`` matches Espressif ESP32-S2 in USB-OTG mode by VID and PID.
155    * ``--port-filter vid=0x303A --port-filter pid=0x1001`` matches Espressif USB-Serial/JTAG unit used by multiple chips by VID and PID.
156    * ``--port-filter name=ttyUSB`` matches ports where the port name contains the specified text.
157
158See also the `Espressif USB customer-allocated PID repository <https://github.com/espressif/usb-pids>`_
159