1.. _config:
2
3Configuration File
4==================
5
6``esptool.py`` relies on serial communication when connecting to, reading from, or writing to an ESP chip.
7To ensure this two-way serial connection works properly, ``esptool.py`` is tuned with several pre-defined
8variables describing the timings and other nuances when sending or receiving data.
9These variables have been finely tuned to work in absolute majority of environments.
10However, it is impossible to cover all of the existing combinations of hardware, OS, and drivers.
11Sometimes little tweaking is necessary to cover even the most extreme edge cases.
12
13These options can be specified in a configuration file. This makes it easy to run
14``esptool.py`` with custom settings, and also allows for specification of options
15that are otherwise not available to a user without having to tamper with the source code.
16
17File Location
18-------------
19
20The default name for a configuration file is ``esptool.cfg``. First, the same
21directory ``esptool.py`` is being run in is inspected.
22
23If a configuration file is not found here, the current user's OS configuration directory is inspected next:
24
25 - Linux: ``/home/<user>/.config/esptool/``
26 - MacOS ``/Users/<user>/.config/esptool/``
27 - Windows: ``c:\Users\<user>\AppData\Local\esptool\``
28
29If a configuration file is still not found, the last inspected location is the home directory:
30
31 - Linux: ``/home/<user>/``
32 - MacOS ``/Users/<user>/``
33 - Windows: ``c:\Users\<user>\``
34
35On Windows, the home directory can be set with the ``HOME`` or ``USERPROFILE`` environment variables.
36Therefore, the Windows configuration directory location also depends on these.
37
38A different location for the configuration file can be specified with the ``ESPTOOL_CFGFILE``
39environment variable, e.g. ``ESPTOOL_CFGFILE = ~/custom_config.cfg``.
40This overrides the search priorities described above.
41
42``esptool.py`` will read settings from other usual configuration files if no other
43configuration file is used.  It will automatically read from ``setup.cfg`` or
44``tox.ini`` if they exist.
45
46As a result, the order of priority of inspected configuration files is:
47
48#. a file specified with the ``ESPTOOL_CFGFILE`` environment variable
49#. ``esptool.cfg``
50#. ``setup.cfg``
51#. ``tox.ini``
52
53Syntax
54------
55
56An ``esptool.py`` configuration file is in .ini file format: it must be
57introduced by an ``[esptool]`` header to be recognized as valid.
58This section then contains ``name = value`` entries.
59Lines beginning with ``#`` or ``;`` are ignored as comments.
60
61Delay and timeout options accept float values,
62other numeric options are integers. Strings don't need quotes.
63
64Sample configuration file:
65
66.. code-block:: text
67
68    # esptool.cfg file to configure internal settings of esptool
69    [esptool]
70    chip_erase_timeout = 140
71    serial_write_timeout = 8.5
72    connect_attempts = 7
73    write_block_attempts = 2
74    reset_delay = 0.75
75    # Overriding the default reset sequence to work in an abnormal environment
76    custom_reset_sequence = D0|R1|W0.1|D1|R0|W0.5|D0
77
78Options
79-------
80
81Complete list of configurable options:
82
83+------------------------------+-----------------------------------------------------------+----------+
84| Option                       | Description                                               | Default  |
85+==============================+===========================================================+==========+
86| timeout                      | Timeout for most flash operations                         | 3 s      |
87+------------------------------+-----------------------------------------------------------+----------+
88| chip_erase_timeout           | Timeout for a full chip erase                             | 120 s    |
89+------------------------------+-----------------------------------------------------------+----------+
90| max_timeout                  | The longest any command can run                           | 240 s    |
91+------------------------------+-----------------------------------------------------------+----------+
92| sync_timeout                 | Timeout for syncing with the bootloader                   | 0.1 s    |
93+------------------------------+-----------------------------------------------------------+----------+
94| md5_timeout_per_mb           | Timeout (per megabyte) for calculating md5sum             | 8 s      |
95+------------------------------+-----------------------------------------------------------+----------+
96| erase_region_timeout_per_mb  | Timeout (per megabyte) for erasing a region               | 30 s     |
97+------------------------------+-----------------------------------------------------------+----------+
98| erase_write_timeout_per_mb   | Timeout (per megabyte) for erasing and writing data       | 40 s     |
99+------------------------------+-----------------------------------------------------------+----------+
100| mem_end_rom_timeout          | Short timeout for ESP_MEM_END                             | 0.2 s    |
101+------------------------------+-----------------------------------------------------------+----------+
102| serial_write_timeout         | Timeout for serial port write                             | 10 s     |
103+------------------------------+-----------------------------------------------------------+----------+
104| connect_attempts             | Default number of times to try connection                 | 7        |
105+------------------------------+-----------------------------------------------------------+----------+
106| write_block_attempts         | Number of times to try writing a data block               | 3        |
107+------------------------------+-----------------------------------------------------------+----------+
108| reset_delay                  | Time to wait before the boot pin is released after reset  | 0.05 s   |
109+------------------------------+-----------------------------------------------------------+----------+
110| open_port_attempts           | Number of attempts to open the port (0 - infinite)        | 1        |
111+------------------------------+-----------------------------------------------------------+----------+
112| custom_reset_sequence        | Custom reset sequence for resetting into the bootloader   |          |
113+------------------------------+-----------------------------------------------------------+----------+
114
115Custom Reset Sequence
116---------------------
117
118The ``custom_reset_sequence`` configuration option allows you to define a reset sequence which will get
119used when an :ref:`automatic reset into the serial bootloader <automatic-bootloader>` is performed.
120
121The sequence is defined with a string in the following format:
122
123- Consists of individual commands divided by ``|`` (e.g. ``R0|D1|W0.5``).
124- Commands (e.g. ``R0``) are defined by a code (``R``) and an argument (``0``).
125
126+------+-----------------------------------------------------------+-----------------+
127| Code | Action                                                    | Argument        |
128+======+===========================================================+=================+
129| D    | Set DTR control line                                      | ``1``/``0``     |
130+------+-----------------------------------------------------------+-----------------+
131| R    | Set RTS control line                                      | ``1``/``0``     |
132+------+-----------------------------------------------------------+-----------------+
133| U    | Set DTR and RTS control lines at the same time            | ``0,0``/``0,1`` |
134|      | (Unix-like systems only)                                  | ``1,0``/``1,1`` |
135+------+-----------------------------------------------------------+-----------------+
136| W    | Wait for ``N`` seconds (where ``N`` is a float)           | ``N``           |
137+------+-----------------------------------------------------------+-----------------+
138
139
140For example: ``D0|R1|W0.1|D1|R0|W0.5|D0`` represents the following classic reset sequence:
141
142.. code-block:: python
143
144    _setDTR(False)  # IO0=HIGH
145    _setRTS(True)   # EN=LOW, chip in reset
146    time.sleep(0.1)
147    _setDTR(True)   # IO0=LOW
148    _setRTS(False)  # EN=HIGH, chip out of reset
149    time.sleep(0.05)
150    _setDTR(False)  # IO0=HIGH, done
151