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 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.

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.

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), 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 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. 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.