The purpose of this FAQ / Troubleshooting is to respond to questions commonly asked in Issues section and on ESP8266 Community forum.
Where possible we are going right to the answer and provide it within one or two paragraphs. If it takes more than that, you will see a link to "Read more" details.
Please feel free to contribute if you believe that some frequent issues are not covered below.
This message indicates issue with uploading ESP module over a serial connection. There are couple of possible causes, that depend on the type of your module, if you use separate USB to serial converter.
Do not worry about "Programmer" menu of Arduino IDE. It doesn't matter what is selected in it — upload now always defaults to using esptool.
The code may crash because of s/w bug or issue with your h/w. Before entering an issue report, please perform initial troubleshooting.
Using
*printf()with floats is enabled by default. Some KBs of flash can be saved by using the option--nofloatwith the boards generator:./tools/boards.txt.py --nofloat --boardsgenUse the debug level option
NoAssert-NDEBUG(in the Tools menu)
From release 2.4.2 and ahead, not using WPS will give an extra ~4.5KB in heap.
In release 2.4.2 only, WPS is disabled by default and the board generator is required to enable it:
./tools/boards.txt.py --allowWPS --boardsgen
For platformIO (and maybe other build environments), you will also need to add the build flag: -D NO_EXTRA_4K_HEAP
This manual selection is not needed starting from 2.5.0 (and in git version). WPS is always available, and not using it will give an extra ~4.5KB compared to releases until 2.4.1 included.
You would like to use this Arduino library with ESP8266 and it does not perform. It is not listed among libraries verified to work with ESP8266.
In the IDE, for ESP-12E that has 4M flash, I can choose 4M (1M FS) or 4M (3M FS). No matter what I select, the IDE tells me the maximum code space is about 1M. Where does my flash go?
The reason we cannot have more than 1MB of code in flash has to do with a hardware limitation. Flash cache hardware on the ESP8266 only allows mapping 1MB of code into the CPU address space at any given time. You can switch mapping offset, so technically you can have more than 1MB total, but switching such "banks" on the fly is not easy and efficient, so we don't bother doing that. Besides, no one has so far complained about 1MB of code space being insufficient for practical purposes.
The option to choose 3M or 1M filesystem is to optimize the upload time.
Uploading 3MB takes a long time so sometimes you can just use 1MB. Other
2MB of flash can still be used with ESP.flashRead and
ESP.flashWrite APIs if necessary.
You will see this issue only if serial upload was not followed by a
physical reset (e.g. power-on reset). For a device being in that state
ESP.restart will not work. Apparently the issue is caused by one of
internal registers not being properly updated until physical
reset.
This issue concerns only serial uploads. OTA uploads are not affected.
If you are using ESP.restart, the work around is to reset ESP once
after each serial upload.
This error may pop up after switching between staging and stable esp8266 / Arduino package installations, or after upgrading the package version Read more.
This is not needed anymore:
PCBs in time-wait state are limited to 5 and removed when that number is exceeded.
For reference:
Time-wait PCB state helps TCP not confusing two consecutive connections with the same (s-ip,s-port,d-ip,d-port) when the first is already closed but still having duplicate packets lost in internet arriving later during the second. Artificially clearing them is a workaround to help saving precious heap.
// no need for #include
struct tcp_pcb;
extern struct tcp_pcb* tcp_tw_pcbs;
extern "C" void tcp_abort (struct tcp_pcb* pcb);
void tcpCleanup (void) {
while (tcp_tw_pcbs)
tcp_abort(tcp_tw_pcbs);
}Ref. #1923
The board generator is a python script originally intended to ease the Arduino IDE's boards.txt configuration file about the multitude of available boards, especially when common parameters have to be updated for all of them.
This script is also used to manage uncommon options that are currently not available in the IDE menu.
When you implement deep sleep using WAKE_RF_DISABLED, this forces what
appears to be a bare metal disabling of WiFi functionality, which is not
restored using WiFi.forceSleepWake() or WiFi.mode(WIFI_STA). If you need
to implement deep sleep with WAKE_RF_DISABLED and later connect to WiFi, you
will need to implement an additional (short) deep sleep using
WAKE_RF_DEFAULT.
Ref. #3072
This was WiFi persistence. Starting from version 3 of this core, WiFi is indeed off at boot and is powered on only when starting to be used with the regular API.
Read more at former WiFi persistent mode.
Please read flash layout documentation entry.
By using a uniquely named .h file, macro definitions can be created and globally used. Additionally, compiler command-line options can be embedded in this file as a unique block comment.