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¶
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.
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.
Any ESP82xx can run at 80 or 160MHz.
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).
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.
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:2MBmeans that 2MBytes are used for an internal filesystem (LittleFS).
There are four options. The most compatible and slowest 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
Here is some more insights about that in esp32 forums.
dtr (aka nodemcu)option. It provides an extra-easy way of flashing from serial port.
no dtroption 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).
There are three UART options:
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.
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 developer trying to debug some issues.
Due to the limited resources on the device, our default compiler optimizations
focus on creating the smallest code size (
.bin file). That is fine for
release but not ideal for debugging.
Debug Optimization use to improve Exception Decoder results.
Liteimpact on code size uses
-fno-optimize-sibling-callsto alter the
-Oscompiler option to place more caller addresses on the Stack.
Optimumoffers better quality stack content for the Exception Decoder at the expense of a larger code size. It uses the
-Ogcompiler option, which turns off optimizations that can make debugging difficult while keeping others.
Noneno changes for debugging continue using
Take note some sketches may start working after changing the optimization. Or
fail less often. And it is also possible (not likely) that source code that
was working with
-Os may break with
For more topic depth, read Improving Exception Decoder Results
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).
With these options, IPv6 is enabled, with features. It uses about 20-30KB of supplementary flash space.
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 are disabled by default. Consequently the
newoperator will cause a general failure and a reboot when memory is full.
Note that the C-
mallocfunction always returns
nullptrwhen memory is full.
Enabled: on this Arduino core, exceptions are possible. Note that they are quite ram and flash consuming.
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.
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.
NONOS SDK Version¶
Our Core is based on [Espressif NONOS SDK](https://github.com/espressif/ESP8266_NONOS_SDK).
2.2.1+100 (190703) (default)
See our issue tracker in regards to default version selection.
Notice that 3.x.x is provided as-is and remains experimental.
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
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
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
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.