esp8266/doc/ideoptions.rst

esp8266 configuration
=====================

Overview
--------

There are a number of specific options for esp8266 in the Arduino IDE Tools
menu.  Not all of them are available for every board.  If one is needed and
not visible, please try using the generic esp8266 or esp8285 board.

In every menu entry, the first option is the default one and is suitable for
most users (except for flash size in the generic ESP8266 board).

Note about PlatformIO
---------------------

`PlatformIO specific documentation
<https://docs.platformio.org/en/latest/platforms/espressif8266.html#espressif-8266>`__
is also available.  Note that this link is available here for reference and
is not maintained by the esp8266 Arduino core platform team.

Arduino IDE Tools Menu
----------------------

Board
~~~~~

Most of the time there is only one type of ESP8266 chip and only one type of
ESP8285(1M) chip shipped with hardware or DIY boards.  Capabilities are the
same everywhere.  Hardware devices differ only on routed GPIO and external
components.

If a specific hardware is not available in this list, "Generic ESP82xx"
always work.

Upload Speed
~~~~~~~~~~~~

This the UART speed setup for flashing the ESP.  It is not related with the
UART(Serial) speed programmed from inside the sketch, if enabled.  Default
values are legacy.  The highest speed option (around 1Mbaud) should always
work.  For specific boards, defaults can be updated using the `board.txt
generator <faq/a05-board-generator.rst>`__.

CPU Frequency
~~~~~~~~~~~~~

Any ESP82xx can run at 80 or 160MHz.

Crystal Frequency
~~~~~~~~~~~~~~~~~

This is the on-board crystal frequency (26 or 40Mhz).  Default is 26MHz.
But the chip was designed with 40MHz.  It explains the default strange 74880
baud rate at boot, which is 115200\*26/40 (115200 being quite a lot used
by default nowadays).

Flash Size
~~~~~~~~~~

With the Arduino core, ESP82xx can use at most 1MB to store the main sketch
in flash memory.

ESP8285 has 1MB internal flash capacity.  ESP8266 is always shipped with an
external flash chip that is most often 1MB (esp01, esp01s, lots of
commercial appliances), 4MB (DIY boards like wemos/lolin D1 mini or nodemcu)
or 16MB (lolin D1 mini pro).  But configurations with 2MB and 8MB also
exist.  This core is also able to use older 512KB chips that are today not
much used and officially deprecated by Espressif.

Flash space is divided into 3 main zones.  The first is the user program
space, 1MB at most.  The second is enough space for the OTA ability.  The
third, the remaining space, can be used to hold a filesystem (LittleFS).

This list proposes many different configurations.  In the generic board
list, the first one of each size is the default and suitable for many cases.

Example: ``4MB (FS:2MB OTA:~1019KB)``:

- 4MB is the flash chip size (= 4 MBytes, sometimes oddly noted 32Mbits)
- ``OTA:~1019KB`` (around 1MB) is used for Over The Air flashing (note that OTA binary can be gzip-ed)
- ``FS:2MB`` means that 2MBytes are used for an internal filesystem (LittleFS).

Flash Mode
~~~~~~~~~~

There are four options.  The most compatible and slowest is ``DOUT``.  The
fasted is ``QIO``.  ESP8266 mcu is able to use any of these modes, but
depending on the flash chips capabilities and how it is connected to the
esp8266, the fastest mode may not be working.  Note that ESP8285 requires
the ``DOUT`` mode.

Here is some more insights about that in `esp32 forums <https://www.esp32.com/viewtopic.php?t=1250#p5523>`__.

Reset Method
~~~~~~~~~~~~

| On some boards (commonly NodeMCU, Lolin/Wemos) an electronic trick allows to
  use the UART DTR line to reset the esp8266 *and* put it in flash mode.  This
  is the default ``dtr (aka nodemcu)`` option.  It provides an extra-easy way of
  flashing from serial port.
| When not available, the ``no dtr`` option can be
  used in conjunction with a flash button on the board (or by driving the ESP
  dedicated GPIOs to boot in flash mode at power-on).

Debug Port
~~~~~~~~~~

There are three UART options:

- disabled
- Serial
- Serial1

When on ``Serial`` or ``Serial1`` options (see
`reference <reference.rst#serial>`__), messages are sent at 74880 bauds at
boot time then baud rate is changed to user configuration in sketch.  These
messages are generated by the internal bootloader.  Subsequent serial data
are coming either from the firmware, this Arduino core, and user application.

Debug Level
~~~~~~~~~~~

There are a number of options.

- The first (``None``) is explained by itself.
- The last (``NoAssert - NDEBUG``) is even quieter than the first (some
  internal guards are skipped to save more flash).
- The other ones may be used when asked by a maintainer or if you are a
  developper trying to debug some issues.

lwIP variant
~~~~~~~~~~~~

`lwIP <https://en.wikipedia.org/wiki/LwIP>`__ is the internal network
software stack.  It is highly configurable and comes with features that can
be enabled, at the price of RAM or FLASH space usage.

There are 6 variants.  As always, the first and default option is a good
compromise.  Note that cores v2.x were or could be using the lwIP-v1 stack.
Only lwIP-v2 is available on cores v3+.

- v2 Lower Memory

  This is lwIP-v2 with MSS=536 bytes.  MSS is TCP's `Maximum Segment Size`,
  and different from MTU (IP's Maximum Transfer Unit) which is always 1480
  in our case.
  Using such value for MSS is 99.9% compatible with any TCP peers, allows to
  store less data in RAM, and is consequently slower when transmitting large
  segments of data (using TCP) because of a larger overhead and latency due to
  smaller payload and larger number of packets.

  UDP and other IP protocols are not affected by MSS value.

- v2 Higher Bandwidth

  When streaming large amount of data, prefer this option.  It uses more
  memory (MSS=1460) so it allows faster transfers thanks to a smaller number
  of packets providing lower overhead and higher bandwidth.

- ... (no features)

  Disabled features to get more flash space and RAM for users are:

  -  No IP Forwarding (=> no NAT),

  -  No IP Fragmentation and reassembly,

  -  No AutoIP (not getting 169.254.x.x on DHCP request when there is no DHCP answer),

  -  | No SACK-OUT (= no Selective ACKnowledgements for OUTput):
     | no better stability with long distance TCP transfers,

  -  No listen backlog (no protection against DOS attacks for TCP server).

- IPv6 ...

  With these options, IPv6 is enabled, with features.  It uses about 20-30KB
  of supplementary flash space.

VTable location
~~~~~~~~~~~~~~~

This is the mechanism used in C++ to support dynamic dispatch of virtual
methods.  By default these tables are stored in flash to save precious RAM
bytes, but in very specific cases they can be stored in Heap space, or IRAM
space (both in RAM).

C++ Exceptions
~~~~~~~~~~~~~~

-  C++ exceptions are disabled by default.  Consequently the ``new``
   operator will cause a general failure and a reboot when memory is full.

   Note that the C-``malloc`` function always returns ``nullptr`` when
   memory is full.

-  Enabled: on this Arduino core, exceptions are possible.  Note that they
   are quite ram and flash consuming.

Stack protection
~~~~~~~~~~~~~~~~

-  This is disabled by default

-  When Enabled, the compiler generated extra code to check for stack
   overflows.  When this happens, an exception is raised with a message and
   the ESP reboots.

Erase Flash
~~~~~~~~~~~

-  ``Only sketch``: When WiFi is enabled at boot and persistent WiFi
   credentials are enabled, these data are preserved across flashings.
   Filesystem is preserved.

-  ``Sketch + WiFi settings``: persistent WiFi settings are not
   preserved accross flashings. Filesystem is preserved.

-  ``All Flash``: WiFi settings and Filesystems are erased.

Espressif Firmware
~~~~~~~~~~~~~~~~~~

There are a number of available espressif firmwares.  The first / default
choice is fine.  Only try with others after reading on the issue tracker
that something has to be tried with them.  Note that Espressif obsoleted
all of them at the time of writing.

SSL Support
~~~~~~~~~~~

The first and default choice (``All SSL ciphers``) is good.  The second
option enables only the main ciphers and can be used to lower flash
occupation.

MMU (Memory Management Unit)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Head to its `specific documentation <mmu.rst>`__.  Note that there is an option
providing an additional 16KB of IRAM to your application which can be used
with ``new`` and ``malloc``.

Non-32-Bit Access
~~~~~~~~~~~~~~~~~

On esp82xx architecture, DRAM can be accessed byte by byte, but read-only
flash space (``PROGMEM`` variables) and IRAM cannot.  By default they can
only be safely accessed in a compatible way using special macros
``pgm_read_some()``.

With the non-default option ``Byte/Word access``, an exception manager
allows to transparently use them as if they were byte-accessible.  As a
result, any type of access works but in a very slow way for the usually
illegal ones.  This mode can also be enabled from the MMU options.