.. _config:

Configuration File
==================

``esptool.py`` relies on serial communication when connecting to, reading from, or writing to an ESP chip.
To ensure this two-way serial connection works properly, ``esptool.py`` is tuned with several pre-defined
variables describing the timings and other nuances when sending or receiving data.
These variables have been finely tuned to work in absolute majority of environments.
However, it is impossible to cover all of the existing combinations of hardware, OS, and drivers.
Sometimes little tweaking is necessary to cover even the most extreme edge cases.

These options can be specified in a configuration file. This makes it easy to run
``esptool.py`` with custom settings, and also allows for specification of options
that are otherwise not available to a user without having to tamper with the source code.

File Location
-------------

The default name for a configuration file is ``esptool.cfg``. First, the same
directory ``esptool.py`` is being run in is inspected.

If a configuration file is not found here, the current user's OS configuration directory is inspected next:

 - Linux: ``/home/<user>/.config/esptool/``
 - MacOS ``/Users/<user>/.config/esptool/``
 - Windows: ``c:\Users\<user>\AppData\Local\esptool\``

If a configuration file is still not found, the last inspected location is the home directory:

 - Linux: ``/home/<user>/``
 - MacOS ``/Users/<user>/``
 - Windows: ``c:\Users\<user>\``

On Windows, the home directory can be set with the ``HOME`` or ``USERPROFILE`` environment variables.
Therefore, the Windows configuration directory location also depends on these.

A different location for the configuration file can be specified with the ``ESPTOOL_CFGFILE``
environment variable, e.g. ``ESPTOOL_CFGFILE = ~/custom_config.cfg``.
This overrides the search priorities described above.

``esptool.py`` will read settings from other usual configuration files if no other
configuration file is used.  It will automatically read from ``setup.cfg`` or
``tox.ini`` if they exist.

As a result, the order of priority of inspected configuration files is:

#. a file specified with the ``ESPTOOL_CFGFILE`` environment variable
#. ``esptool.cfg``
#. ``setup.cfg``
#. ``tox.ini``

Syntax
------

An ``esptool.py`` configuration file is in .ini file format: it must be
introduced by an ``[esptool]`` header to be recognized as valid.
This section then contains ``name = value`` entries.
Lines beginning with ``#`` or ``;`` are ignored as comments.

Delay and timeout options accept float values,
other numeric options are integers. Strings don't need quotes.

Sample configuration file:

.. code-block:: text

    # esptool.cfg file to configure internal settings of esptool
    [esptool]
    chip_erase_timeout = 140
    serial_write_timeout = 8.5
    connect_attempts = 7
    write_block_attempts = 2
    reset_delay = 0.75
    # Overriding the default reset sequence to work in an abnormal environment
    custom_reset_sequence = D0|R1|W0.1|D1|R0|W0.5|D0

Options
-------

Complete list configurable options:

+------------------------------+-----------------------------------------------------------+----------+
| Option                       | Description                                               | Default  |
+==============================+===========================================================+==========+
| timeout                      | Timeout for most flash operations                         | 3 s      |
+------------------------------+-----------------------------------------------------------+----------+
| chip_erase_timeout           | Timeout for a full chip erase                             | 120 s    |
+------------------------------+-----------------------------------------------------------+----------+
| max_timeout                  | The longest any command can run                           | 240 s    |
+------------------------------+-----------------------------------------------------------+----------+
| sync_timeout                 | Timeout for syncing with the bootloader                   | 0.1 s    |
+------------------------------+-----------------------------------------------------------+----------+
| md5_timeout_per_mb           | Timeout (per megabyte) for calculating md5sum             | 8 s      |
+------------------------------+-----------------------------------------------------------+----------+
| erase_region_timeout_per_mb  | Timeout (per megabyte) for erasing a region               | 30 s     |
+------------------------------+-----------------------------------------------------------+----------+
| erase_write_timeout_per_mb   | Timeout (per megabyte) for erasing and writing data       | 40 s     |
+------------------------------+-----------------------------------------------------------+----------+
| mem_end_rom_timeout          | Short timeout for ESP_MEM_END                             | 0.2 s    |
+------------------------------+-----------------------------------------------------------+----------+
| serial_write_timeout         | Timeout for serial port write                             | 10 s     |
+------------------------------+-----------------------------------------------------------+----------+
| connect_attempts             | Default number of times to try connection                 | 7        |
+------------------------------+-----------------------------------------------------------+----------+
| write_block_attempts         | Number of times to try writing a data block               | 3        |
+------------------------------+-----------------------------------------------------------+----------+
| reset_delay                  | Time to wait before the boot pin is released after reset  | 0.05 s   |
+------------------------------+-----------------------------------------------------------+----------+
| custom_reset_sequence        | Custom reset sequence for resetting into the bootloader   |          |
+------------------------------+-----------------------------------------------------------+----------+

Custom Reset Sequence
---------------------

The ``custom_reset_sequence`` configuration option allows you to define a reset sequence which will get
used when an :ref:`automatic reset into the serial bootloader <automatic-bootloader>` is performed.

The sequence is defined with a string in the following format:

- Consists of individual commands divided by ``|`` (e.g. ``R0|D1|W0.5``).
- Commands (e.g. ``R0``) are defined by a code (``R``) and an argument (``0``).

+------+-----------------------------------------------------------+-----------------+
| Code | Action                                                    | Argument        |
+======+===========================================================+=================+
| D    | Set DTR control line                                      | ``1``/``0``     |
+------+-----------------------------------------------------------+-----------------+
| R    | Set RTS control line                                      | ``1``/``0``     |
+------+-----------------------------------------------------------+-----------------+
| U    | Set DTR and RTS control lines at the same time            | ``0,0``/``0,1`` |
|      | (Unix-like systems only)                                  | ``1,0``/``1,1`` |
+------+-----------------------------------------------------------+-----------------+
| W    | Wait for ``N`` seconds (where ``N`` is a float)           | ``N``           |
+------+-----------------------------------------------------------+-----------------+


For example: ``D0|R1|W0.1|D1|R0|W0.5|D0`` represents the following classic reset sequence:

.. code-block:: python

    _setDTR(False)  # IO0=HIGH
    _setRTS(True)   # EN=LOW, chip in reset
    time.sleep(0.1)
    _setDTR(True)   # IO0=LOW
    _setRTS(False)  # EN=HIGH, chip out of reset
    time.sleep(0.05)
    _setDTR(False)  # IO0=HIGH, done
