arduino/esp8266
1
0
Fork 0
mirror of https://github.com/esp8266/Arduino.git synced 2025-07-27 18:02:17 +03:00
Code Activity

docs: convert to .rst and add readthedocs

Browse Source
This commit is contained in:
Ivan Grokhotkov
2017-02-19 16:55:37 +08:00
committed by Ivan Grokhotkov
parent 5c7247b0f4
commit 283eb97cd3
81 changed files with 7191 additions and 6324 deletions
Download Patch File Download Diff File Expand all files Collapse all files

284
doc/faq/a01-espcomm_sync-failed.md
View File

@ -1,284 +0,0 @@
---
title: Frequently Asked Questions / Troubleshooting
---
[FAQ list :back:](readme.md)
## I am getting "espcomm_sync failed" error when trying to upload my ESP. How to resolve this issue?
- [Introduction](#Introduction)
- [Initial Checks](#initial-checks)
- [Advanced Checks](#advanced-checks)
- [Reset Methods](#reset-methods)
- [Ck](#ck)
- [Nodemcu](#nodemcu)
- [I'm Stuck](#im-stuck)
- [Conclusion](#conclusion)
### Introduction
This message indicates issue with uploading ESP module over a serial connection. There are couple of possible causes, that depend on the type of module, if you use separate USB to serial converter, what parameters are selected for upload, etc. As result there is no single answer on the root cause. To find it out you may need to complete couple of troubleshooting steps.
> Note: If you are just starting with ESP, to reduce potential issues with uploading, select ESP board with integrated USB to serial converter. This will considerably reduce number of user depended factors or configuration settings that influence upload process.
Example boards with USB to serial converter build in, that will make your initial project development easier, are shown below.
![Example boards with integrated USB to serial converter](pictures/a01-example-boards-with-usb.png)
If you are using a Generic ESP8266 module, separate USB to serial converter and connect them by yourself, please make sure you have the following three things right:
1. Module is provided with enough power,
2. GPIO0, GPIO15 and CH_PD are connected using pull up / pull down resistors,
3. Module is put into boot loader mode.
For specific details please refer to section on [Generic ESP8266 modules](../boards.md#generic-esp8266-modules). Example modules without USB to serial converter on board are shown below.
![Example ESP8266 modules without USB to serial converter](pictures/a01-example-boards-without-usb.png)
### Initial Checks
In order to troubleshoot "espcomm_sync failed" error, please proceed step by step through the checklist below. This list is organized starting with most common and simple to more complex issues.
1. Start with reading exact message displayed in debug window of Arduino IDE. In many cases it provides direct information where the issue is.
!["espcomm_open failed" error](pictures/a01-espcomm_open-failed.png)
For instance message above suggests that Arduino IDE is unable to open a serial port COM3. Check if you have selected port where your module is connected to.
![Serial port selection](pictures/a01-serial-port-selection.png)
2. If a module is connected to the serial port but not responding as a valid ESP8266 device, the message will read slightly different (see below). If you have other modules connected to your PC, make sure that you are uploading code to ESP8266 and not to e.g. Arduino UNO.
![Serial port selection](pictures/a01-espcomm_sync-failed.png)
3. To have your PC talking to ESP, select exact ESP type in upload menu. If selection is incorrect then the upload may fail.
![Board selection](pictures/a01-board-selection.png)
Basing on selected board type, Arduino IDE will apply specific "reset method" to enter the board into boot loading mode. Reset methods are board specific. Some boards do not have the h/w in place to support reset by Arduino IDE. If this is the case, you need to enter such board into boot loading mode manually.
4. Upload may be also failing due to too high speed. If you have long or poor quality USB cable, try reducing selection under *Upload Speed*.
![Serial speed selection](pictures/a01-serial-speed-selection.png)
### Advanced Checks
1. If you are still facing issues, test if module is indeed entering the boot loading mode. You can do it by connecting secondary USB to serial converter and checking the message displayed. Attach RX and GND pins of converter to TX and GND pin of ESP as shown on example below ([get fzz source](pictures/a01-secondary-serial-hookup.fzz)).
![Secondary USB to serial converter hookup](pictures/a01-secondary-serial-hookup.png)
Then open a terminal at 74880 baud, and look what message is reported when ESP is being reset for programming. Correct message looks as follows:
```
ets Jan 8 2013,rst cause:2, boot mode:(1,7)
```
If you see similar message but different values then decode them using [Boot Messages and Modes](../boards.md#boot-messages-and-modes). The key information is contained in first digit / three right-most bits of the boot mode message as shown below.
![Decoding of boot mode](pictures/a01-boot-mode-decoding.png)
For instance message ``` boot mode (3,3) ``` indicates that pins GPIO2 and GPIO0 are set HIGH and GPIO15 is set LOW. This is configuration for [normal operation](../boards.md#minimal-hardware-setup-for-running-only) of module (to execute application from flash), not for [boot loading](../boards.md#minimal-hardware-setup-for-bootloading-only) (flash programming).
> Note: Without having this step right you will not be able to upload your module over a serial port.
2. You have confirmed that module is in boot loading mode but upload still fails. If you are using external USB to serial converter, then check if it operates correctly by looping it back. This is quite simple check. Just connect TX and RX of your converter together like on picture below. Then open Serial Monitor and type some characters. If everything is fine, then you should see what you type immediately printed back on the monitor. For an ESP with USB to serial converter on board, this check may involve breaking some PCB traces. I would not do it unless being desperate. Instead try steps below.
![USB to serial converter loop back](pictures/a01-usb-to-serial-loop-back.png)
3. Next step to try, if not done already, is checking detailed debug messages. Go to *File > Preferences*, enable *Show verbose output during: upload* and try uploading again. For successful upload this log should look similar to example shown below:
```
C:\Users\Krzysztof\AppData\Local\Arduino15\packages\esp8266\tools\esptool\0.4.8/esptool.exe -vv -cd ck -cb 115200 -cp COM3 -ca 0x00000 -cf C:\Users\KRZYSZ~1\AppData\Local\Temp\build7e44b372385012e74d64fb272d24b802.tmp/Blink.ino.bin
esptool v0.4.8 - (c) 2014 Ch. Klippel <ck@atelier-klippel.de>
setting board to ck
setting baudrate from 115200 to 115200
setting port from COM1 to COM3
setting address from 0x00000000 to 0x00000000
espcomm_upload_file
espcomm_upload_mem
setting serial port timeouts to 1000 ms
opening bootloader
resetting board
trying to connect
flush start
setting serial port timeouts to 1 ms
setting serial port timeouts to 1000 ms
flush complete
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
read 0, requested 1
trying to connect
flush start
setting serial port timeouts to 1 ms
setting serial port timeouts to 1000 ms
flush complete
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
espcomm_send_command: receiving 2 bytes of data
Uploading 226368 bytes from to flash at 0x00000000
erasing flash
size: 037440 address: 000000
first_sector_index: 0
total_sector_count: 56
head_sector_count: 16
adjusted_sector_count: 40
erase_size: 028000
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
setting serial port timeouts to 15000 ms
setting serial port timeouts to 1000 ms
espcomm_send_command: receiving 2 bytes of data
writing flash
..............................................................................................................................................................................................................................
starting app without reboot
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
espcomm_send_command: receiving 2 bytes of data
closing bootloader
flush start
setting serial port timeouts to 1 ms
setting serial port timeouts to 1000 ms
flush complete
```
Upload log may be longer depending on number of connection attempts made by esptool. Analyze it for any anomalies to configuration you have selected in Arduino IDE, like different serial port, reset method, baud rate, etc. Resolve all noted differences.
### Reset Methods
If you got to this point and still see ``` espcomm_sync failed ```, then now you need to bring in the heavy guns.
Connect scope or logic analyzer to GPIO0, RST and RXD pins of the ESP to check what's happening.
Then compare your measurements with wave-forms collected for circuits below. They document two standard methods of resetting ESP8266 for upload, that you can select in Arduino IDE - [ck](#ck) and [nodemcu](#nodemcu).
#### Ck
Circuit below has been prepared to collect wave-forms for ck reset method ([get fzz source](pictures/a01-circuit-ck-reset.fzz)). It is simpler than for [nodemcu](#nodemcu) reset and therefore often used to wire up generic ESP modules on a breadboard. Check it against your wiring when comparing your measurements against wave-forms below.
![Sample circuit to check ck method](pictures/a01-circuit-ck-reset.png)
The following wave-forms below show voltage signals on GPIO0 and RST pins of the ESP board when uploading the firmware.
Close up of ck reset method signal sequence at the beginning of upload is shown below.
![Reset Method: ck, close up at the beginning of upload](pictures/a01-reset-ck-closeup.png)
Next picture shows complete upload of [Blink.ino](https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino) example at 921600 baud. This is quite high speed, so the upload takes only about 8s.
![Reset Method: ck, complete upload](pictures/a01-reset-ck-complete.png)
Please note that when esptool is not able to initialize upload at the first time, then it retries reset procedure. Case of one such retry is shown on wave-form below.
![Reset Method: ck, complete upload](pictures/a01-reset-ck-complete-1-retry.png)
Each retry is reported in upload log as follows:
```
resetting board
trying to connect
flush start
setting serial port timeouts to 1 ms
setting serial port timeouts to 1000 ms
flush complete
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
read 0, requested 1
```
Presented circuit has one important limitation when it comes to work with Arduino IDE. After opening Serial Monitor (Ctrl-Shift-M), both RTS and DTR lines are permanently pulled down. As RTS line is connected to REST input of ESP, the module is hold in reset state / not able to run. Therefore after uploading module, you need to disconnect both lines or use different serial terminal program that is not pulling down RTS and DTR lines. Otherwise the module will get stuck waiting for releasing the REST signal and you will see nothing on the Serial Monitor.
As for different serial terminal program you can check Arduino IDE add-on [Serial Monitor for ESP8266]((https://github.com/esp8266/Arduino/issues/1360)) developed by user [@mytrain](https://github.com/mytrain) and discussed in [#1360](https://github.com/esp8266/Arduino/issues/1360).
If you prefer external terminal program, then for Windows users we can recommend free and handy [Termite](http://www.compuphase.com/software_termite.htm).
#### Nodemcu
Nodemcu reset method is named after [NodeMCU](https://github.com/nodemcu/nodemcu-devkit) board where it has been introduced for the first time. It overcomes limitations with handling of RTS and DTR lines discussed for [ck](#ck) reset method above.
Sample circuit to measure wave-form is shown below ([get fzz source](pictures/a01-circuit-nodemcu-reset.fzz)).
![Sample circuit to check nodemcu reset method](pictures/a01-circuit-nodemcu-reset.png)
Close up of voltage signals on GPIO0 and RST pins at the beginning of firmware upload is shown below.
![Reset Method: nodemcu, close up at the beginning of upload](pictures/a01-reset-nodemcu-closeup.png)
Please note that the reset sequence is about 10x shorter comparing to [ck](@ck) reset (about 25ms vs. 250ms).
Next picture covers complete upload of [Blink.ino](https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino) example at 921600 baud. Except for difference of the reset signal sequence, the complete upload looks similar to that of [ck](@ck).
![Reset Method: nodemcu, complete upload](pictures/a01-reset-nodemcu-complete.png)
A sample wave-form below shows another upload of [Blink.ino](https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino) example at 921600 baud, but with two reset retries.
![Reset Method: nodemcu, reset retries](pictures/a01-reset-nodemcu-complete-2-retries.png)
If you are interested how noodemcu reset method is implemented, then check circuit below. As indicated it does not pull to ground RTS and DTR lines once you open Serial Monitor in Arduino IDE.
![Implementation of noodemcu reset](pictures/a01-nodemcu-reset-implementation.png)
It consists of two transistors and resistors that you can locate on NodeMCU board on right. On left you can see complete circuit and the truth table how RTS and DTR signals of the serial interface are translated to RST and GPIO0 on the ESP. For more details please refer to [nodemcu](https://github.com/nodemcu/nodemcu-devkit) repository on GitHub.
### I'm Stuck
Hopefully at this point you were able to resolve ``` espcomm_sync failed ``` issue and now enjoy quick and reliable uploads of your ESP modules.
If this is still not the case, then review once more all discussed steps in the checklist below.
**Initial Checks**
* [ ] Is your module connected to serial port and visible in IDE?
* [ ] Is connected device responding to IDE? What is exact message in debug window?
* [ ] Have you selected correct ESP module type in *Board* menu? What is the selection?
* [ ] Have you tried to reduce upload speed? What speeds have you tried?
**Advanced Checks**
* [ ] What message is reported by ESP at 74880 baud when entering boot loading mode?
* [ ] Have you checked your USB to serial converter by looping it back? What is the result?
* [ ] Is your detailed upload log consistent with settings in IDE? What is the log?
**Reset Method**
* [ ] What reset method do you use?
* [ ] What is your connection diagram? Does it match diagram in this FAQ?
* [ ] What is your wave-form of board reset? Does it match wave-form in this FAQ?
* [ ] What is your wave-form of complete upload? Does it match wave-form in this FAQ?
**Software**
* [ ] Do you use the latest stable version of [esp8266 / Arduino](https://github.com/esp8266/Arduino)? What is it?
* [ ] What is the name and version of your IDE and O/S?
If you are stuck at certain step, then post this list on [ESP8266 Community Forum](http://www.esp8266.com/) asking for support.
### Conclusion
With variety of available ESP8266 modules and boards, as well as possible connection methods, troubleshooting of upload issues may take several steps.
If you are a beginner, then use boards with integrated power supply and USB to serial converter. Check carefully message in debug window and act accordingly. Select your exact module type in IDE and try to adjust upload speed. Check if board is indeed entering boot loading mode. Check operation of your USB to serial converter with loop back. Analyze detailed upload log for inconsistencies with IDE settings.
Verify your connection diagram and wave-form for consistency with selected reset method.
If you get stuck, then ask [community](http://www.esp8266.com/) for support providing summary of all completed checks.
![Test stand used during checking of ck reset method](pictures/a01-test-stand.jpg)
Test stand used for checking of ck reset method is shown above.
No any ESP module has been harmed during preparation of this FAQ item.
[FAQ list :back:](readme.md)

394
doc/faq/a01-espcomm_sync-failed.rst Normal file
View File

@ -0,0 +1,394 @@
:orphan:
I am getting "espcomm\_sync failed" error when trying to upload my ESP. How to resolve this issue?
--------------------------------------------------------------------------------------------------
- `Introduction <#Introduction>`__
- `Initial Checks <#initial-checks>`__
- `Advanced Checks <#advanced-checks>`__
- `Reset Methods <#reset-methods>`__
- `Ck <#ck>`__
- `Nodemcu <#nodemcu>`__
- `I'm Stuck <#im-stuck>`__
- `Conclusion <#conclusion>`__
Introduction
~~~~~~~~~~~~
This message indicates issue with uploading ESP module over a serial
connection. There are couple of possible causes, that depend on the type
of module, if you use separate USB to serial converter, what parameters
are selected for upload, etc. As result there is no single answer on the
root cause. To find it out you may need to complete couple of
troubleshooting steps.
Note: If you are just starting with ESP, to reduce potential issues
with uploading, select ESP board with integrated USB to serial
converter. This will considerably reduce number of user depended
factors or configuration settings that influence upload process.
Example boards with USB to serial converter build in, that will make
your initial project development easier, are shown below.
.. figure:: pictures/a01-example-boards-with-usb.png
:alt: Example boards with integrated USB to serial converter
Example boards with integrated USB to serial converter
If you are using a Generic ESP8266 module, separate USB to serial
converter and connect them by yourself, please make sure you have the
following three things right: 1. Module is provided with enough power,
2. GPIO0, GPIO15 and CH\_PD are connected using pull up / pull down
resistors, 3. Module is put into boot loader mode.
For specific details please refer to section on `Generic ESP8266
modules <../boards.md#generic-esp8266-modules>`__. Example modules
without USB to serial converter on board are shown below.
.. figure:: pictures/a01-example-boards-without-usb.png
:alt: Example ESP8266 modules without USB to serial converter
Example ESP8266 modules without USB to serial converter
Initial Checks
~~~~~~~~~~~~~~
In order to troubleshoot "espcomm\_sync failed" error, please proceed
step by step through the checklist below. This list is organized
starting with most common and simple to more complex issues.
1. Start with reading exact message displayed in debug window of Arduino
IDE. In many cases it provides direct information where the issue is.
.. figure:: pictures/a01-espcomm_open-failed.png
:alt: "espcomm\_open failed" error
"espcomm\_open failed" error
For instance message above suggests that Arduino IDE is unable to open a
serial port COM3. Check if you have selected port where your module is
connected to.
.. figure:: pictures/a01-serial-port-selection.png
:alt: Serial port selection
Serial port selection
2. If a module is connected to the serial port but not responding as a
valid ESP8266 device, the message will read slightly different (see
below). If you have other modules connected to your PC, make sure
that you are uploading code to ESP8266 and not to e.g. Arduino UNO.
.. figure:: pictures/a01-espcomm_sync-failed.png
:alt: Serial port selection
Serial port selection
3. To have your PC talking to ESP, select exact ESP type in upload menu.
If selection is incorrect then the upload may fail.
.. figure:: pictures/a01-board-selection.png
:alt: Board selection
Board selection
Basing on selected board type, Arduino IDE will apply specific "reset
method" to enter the board into boot loading mode. Reset methods are
board specific. Some boards do not have the h/w in place to support
reset by Arduino IDE. If this is the case, you need to enter such board
into boot loading mode manually.
4. Upload may be also failing due to too high speed. If you have long or
poor quality USB cable, try reducing selection under *Upload Speed*.
.. figure:: pictures/a01-serial-speed-selection.png
:alt: Serial speed selection
Serial speed selection
Advanced Checks
~~~~~~~~~~~~~~~
1. If you are still facing issues, test if module is indeed entering the
boot loading mode. You can do it by connecting secondary USB to
serial converter and checking the message displayed. Attach RX and
GND pins of converter to TX and GND pin of ESP as shown on example
below (`get fzz
source <pictures/a01-secondary-serial-hookup.fzz>`__).
.. figure:: pictures/a01-secondary-serial-hookup.png
:alt: Secondary USB to serial converter hookup
Secondary USB to serial converter hookup
Then open a terminal at 74880 baud, and look what message is reported
when ESP is being reset for programming. Correct message looks as
follows:
``ets Jan 8 2013,rst cause:2, boot mode:(1,7)``
If you see similar message but different values then decode them using
`Boot Messages and Modes <../boards.md#boot-messages-and-modes>`__. The
key information is contained in first digit / three right-most bits of
the boot mode message as shown below.
.. figure:: pictures/a01-boot-mode-decoding.png
:alt: Decoding of boot mode
Decoding of boot mode
For instance message ``boot mode (3,3)`` indicates that pins GPIO2 and
GPIO0 are set HIGH and GPIO15 is set LOW. This is configuration for
`normal
operation <../boards.md#minimal-hardware-setup-for-running-only>`__ of
module (to execute application from flash), not for `boot
loading <../boards.md#minimal-hardware-setup-for-bootloading-only>`__
(flash programming).
Note: Without having this step right you will not be able to upload
your module over a serial port.
2. You have confirmed that module is in boot loading mode but upload
still fails. If you are using external USB to serial converter, then
check if it operates correctly by looping it back. This is quite
simple check. Just connect TX and RX of your converter together like
on picture below. Then open Serial Monitor and type some characters.
If everything is fine, then you should see what you type immediately
printed back on the monitor. For an ESP with USB to serial converter
on board, this check may involve breaking some PCB traces. I would
not do it unless being desperate. Instead try steps below.
.. figure:: pictures/a01-usb-to-serial-loop-back.png
:alt: USB to serial converter loop back
USB to serial converter loop back
3. Next step to try, if not done already, is checking detailed debug
messages. Go to *File > Preferences*, enable *Show verbose output
during: upload* and try uploading again. For successful upload this
log should look similar to example shown below:
``C:\Users\Krzysztof\AppData\Local\Arduino15\packages\esp8266\tools\esptool\0.4.8/esptool.exe -vv -cd ck -cb 115200 -cp COM3 -ca 0x00000 -cf C:\Users\KRZYSZ~1\AppData\Local\Temp\build7e44b372385012e74d64fb272d24b802.tmp/Blink.ino.bin esptool v0.4.8 - (c) 2014 Ch. Klippel <ck@atelier-klippel.de> setting board to ck setting baudrate from 115200 to 115200 setting port from COM1 to COM3 setting address from 0x00000000 to 0x00000000 espcomm_upload_file espcomm_upload_mem setting serial port timeouts to 1000 ms opening bootloader resetting board trying to connect flush start setting serial port timeouts to 1 ms setting serial port timeouts to 1000 ms flush complete espcomm_send_command: sending command header espcomm_send_command: sending command payload read 0, requested 1 trying to connect flush start setting serial port timeouts to 1 ms setting serial port timeouts to 1000 ms flush complete espcomm_send_command: sending command header espcomm_send_command: sending command payload espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data espcomm_send_command: receiving 2 bytes of data Uploading 226368 bytes from to flash at 0x00000000 erasing flash size: 037440 address: 000000 first_sector_index: 0 total_sector_count: 56 head_sector_count: 16 adjusted_sector_count: 40 erase_size: 028000 espcomm_send_command: sending command header espcomm_send_command: sending command payload setting serial port timeouts to 15000 ms setting serial port timeouts to 1000 ms espcomm_send_command: receiving 2 bytes of data writing flash .............................................................................................................................................................................................................................. starting app without reboot espcomm_send_command: sending command header espcomm_send_command: sending command payload espcomm_send_command: receiving 2 bytes of data closing bootloader flush start setting serial port timeouts to 1 ms setting serial port timeouts to 1000 ms flush complete``
Upload log may be longer depending on number of connection attempts made
by esptool. Analyze it for any anomalies to configuration you have
selected in Arduino IDE, like different serial port, reset method, baud
rate, etc. Resolve all noted differences.
Reset Methods
~~~~~~~~~~~~~
If you got to this point and still see ``espcomm_sync failed``, then now
you need to bring in the heavy guns.
Connect scope or logic analyzer to GPIO0, RST and RXD pins of the ESP to
check what's happening.
Then compare your measurements with wave-forms collected for circuits
below. They document two standard methods of resetting ESP8266 for
upload, that you can select in Arduino IDE - `ck <#ck>`__ and
`nodemcu <#nodemcu>`__.
Ck
^^
Circuit below has been prepared to collect wave-forms for ck reset
method (`get fzz source <pictures/a01-circuit-ck-reset.fzz>`__). It is
simpler than for `nodemcu <#nodemcu>`__ reset and therefore often used
to wire up generic ESP modules on a breadboard. Check it against your
wiring when comparing your measurements against wave-forms below.
.. figure:: pictures/a01-circuit-ck-reset.png
:alt: Sample circuit to check ck method
Sample circuit to check ck method
The following wave-forms below show voltage signals on GPIO0 and RST
pins of the ESP board when uploading the firmware.
Close up of ck reset method signal sequence at the beginning of upload
is shown below.
.. figure:: pictures/a01-reset-ck-closeup.png
:alt: Reset Method: ck, close up at the beginning of upload
Reset Method: ck, close up at the beginning of upload
Next picture shows complete upload of
`Blink.ino <https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino>`__
example at 921600 baud. This is quite high speed, so the upload takes
only about 8s.
.. figure:: pictures/a01-reset-ck-complete.png
:alt: Reset Method: ck, complete upload
Reset Method: ck, complete upload
Please note that when esptool is not able to initialize upload at the
first time, then it retries reset procedure. Case of one such retry is
shown on wave-form below.
.. figure:: pictures/a01-reset-ck-complete-1-retry.png
:alt: Reset Method: ck, complete upload
Reset Method: ck, complete upload
Each retry is reported in upload log as follows:
::
resetting board
trying to connect
flush start
setting serial port timeouts to 1 ms
setting serial port timeouts to 1000 ms
flush complete
espcomm_send_command: sending command header
espcomm_send_command: sending command payload
read 0, requested 1
Presented circuit has one important limitation when it comes to work
with Arduino IDE. After opening Serial Monitor (Ctrl-Shift-M), both RTS
and DTR lines are permanently pulled down. As RTS line is connected to
REST input of ESP, the module is hold in reset state / not able to run.
Therefore after uploading module, you need to disconnect both lines or
use different serial terminal program that is not pulling down RTS and
DTR lines. Otherwise the module will get stuck waiting for releasing the
REST signal and you will see nothing on the Serial Monitor.
As for different serial terminal program you can check Arduino IDE
add-on `Serial Monitor for
ESP8266 <(https://github.com/esp8266/Arduino/issues/1360)>`__ developed
by user [@mytrain](https://github.com/mytrain) and discussed in
`#1360 <https://github.com/esp8266/Arduino/issues/1360>`__.
If you prefer external terminal program, then for Windows users we can
recommend free and handy
`Termite <http://www.compuphase.com/software_termite.htm>`__.
Nodemcu
^^^^^^^
Nodemcu reset method is named after
`NodeMCU <https://github.com/nodemcu/nodemcu-devkit>`__ board where it
has been introduced for the first time. It overcomes limitations with
handling of RTS and DTR lines discussed for `ck <#ck>`__ reset method
above.
Sample circuit to measure wave-form is shown below (`get fzz
source <pictures/a01-circuit-nodemcu-reset.fzz>`__).
.. figure:: pictures/a01-circuit-nodemcu-reset.png
:alt: Sample circuit to check nodemcu reset method
Sample circuit to check nodemcu reset method
Close up of voltage signals on GPIO0 and RST pins at the beginning of
firmware upload is shown below.
.. figure:: pictures/a01-reset-nodemcu-closeup.png
:alt: Reset Method: nodemcu, close up at the beginning of upload
Reset Method: nodemcu, close up at the beginning of upload
Please note that the reset sequence is about 10x shorter comparing to
`ck <@ck>`__ reset (about 25ms vs. 250ms).
Next picture covers complete upload of
`Blink.ino <https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino>`__
example at 921600 baud. Except for difference of the reset signal
sequence, the complete upload looks similar to that of `ck <@ck>`__.
.. figure:: pictures/a01-reset-nodemcu-complete.png
:alt: Reset Method: nodemcu, complete upload
Reset Method: nodemcu, complete upload
A sample wave-form below shows another upload of
`Blink.ino <https://github.com/esp8266/Arduino/blob/master/libraries/esp8266/examples/Blink/Blink.ino>`__
example at 921600 baud, but with two reset retries.
.. figure:: pictures/a01-reset-nodemcu-complete-2-retries.png
:alt: Reset Method: nodemcu, reset retries
Reset Method: nodemcu, reset retries
If you are interested how noodemcu reset method is implemented, then
check circuit below. As indicated it does not pull to ground RTS and DTR
lines once you open Serial Monitor in Arduino IDE.
.. figure:: pictures/a01-nodemcu-reset-implementation.png
:alt: Implementation of noodemcu reset
Implementation of noodemcu reset
It consists of two transistors and resistors that you can locate on
NodeMCU board on right. On left you can see complete circuit and the
truth table how RTS and DTR signals of the serial interface are
translated to RST and GPIO0 on the ESP. For more details please refer to
`nodemcu <https://github.com/nodemcu/nodemcu-devkit>`__ repository on
GitHub.
I'm Stuck
~~~~~~~~~
Hopefully at this point you were able to resolve ``espcomm_sync failed``
issue and now enjoy quick and reliable uploads of your ESP modules.
If this is still not the case, then review once more all discussed steps
in the checklist below.
**Initial Checks** \* [ ] Is your module connected to serial port and
visible in IDE? \* [ ] Is connected device responding to IDE? What is
exact message in debug window? \* [ ] Have you selected correct ESP
module type in *Board* menu? What is the selection? \* [ ] Have you
tried to reduce upload speed? What speeds have you tried?
**Advanced Checks** \* [ ] What message is reported by ESP at 74880 baud
when entering boot loading mode? \* [ ] Have you checked your USB to
serial converter by looping it back? What is the result? \* [ ] Is your
detailed upload log consistent with settings in IDE? What is the log?
**Reset Method** \* [ ] What reset method do you use? \* [ ] What is
your connection diagram? Does it match diagram in this FAQ? \* [ ] What
is your wave-form of board reset? Does it match wave-form in this FAQ?
\* [ ] What is your wave-form of complete upload? Does it match
wave-form in this FAQ?
**Software** \* [ ] Do you use the latest stable version of `esp8266 /
Arduino <https://github.com/esp8266/Arduino>`__? What is it? \* [ ] What
is the name and version of your IDE and O/S?
If you are stuck at certain step, then post this list on `ESP8266
Community Forum <http://www.esp8266.com/>`__ asking for support.
Conclusion
~~~~~~~~~~
With variety of available ESP8266 modules and boards, as well as
possible connection methods, troubleshooting of upload issues may take
several steps.
If you are a beginner, then use boards with integrated power supply and
USB to serial converter. Check carefully message in debug window and act
accordingly. Select your exact module type in IDE and try to adjust
upload speed. Check if board is indeed entering boot loading mode. Check
operation of your USB to serial converter with loop back. Analyze
detailed upload log for inconsistencies with IDE settings.
Verify your connection diagram and wave-form for consistency with
selected reset method.
If you get stuck, then ask `community <http://www.esp8266.com/>`__ for
support providing summary of all completed checks.
.. figure:: pictures/a01-test-stand.jpg
:alt: Test stand used during checking of ck reset method
Test stand used during checking of ck reset method
Test stand used for checking of ck reset method is shown above.
No any ESP module has been harmed during preparation of this FAQ item.
`FAQ list :back: <readme.md>`__

169
doc/faq/a02-my-esp-crashes.md
View File

@ -1,169 +0,0 @@
---
title: Frequently Asked Questions / Troubleshooting
---
[FAQ list :back:](readme.md)
## My ESP crashes running some code. How to troubleshoot it?
* [Introduction](#introduction)
* [What ESP has to Say](#what-esp-has-to-say)
* [Get Your H/W Right](#get-your-hw-right)
* [What is the Cause of Restart?](#what-is-the-cause-of-restart)
* [Exception](#exception)
* [Watchdog](#watchdog)
* [Check Where the Code Crashes](#check-where-the-code-crashes)
* [If at the Wall, Enter an Issue Report](#if-at-the-wall-enter-an-issue-report)
* [Conclusion](#conclusion)
### Introduction
Your ESP is self restarting. You don't know why and what to do about it.
Do not panic.
In most of cases ESP provides enough clues on serial monitor, that you can interpret to pin down the root cause. The first step is then checking what ESP is saying on serial monitor when it crashes.
### What ESP has to Say
Start off by opening a Serial Monitor (Ctrl+Shift+M) to observe the output. Typical crash log looks as follows:
![Typical crash log](pictures/a02-typical-crash-log.png)
Before rushing to copy and paste displayed code to Google, reflect for a while on the nature of observed restarts:
* Does ESP restart on random basis, or under certain conditions, like serving a web page?
* Do you see always the same exception code and stack trace or it changes?
* Does this issue occur with unmodified standard example code (Arduino IDE > *File > Examples*)?
If restarts are random or the exception code differs between restarts, then the problem may be caused by h/w. If the issue occurs for standard examples and stable [esp8266 / arduino](https://github.com/esp8266/Arduino) core, them the issue is almost certainly caused by h/w.
### Get Your H/W Right
If you suspect the h/w, before troubleshooting the s/w, make sure to get your h/w right. There is no much sense in diagnosing the s/w if you board is randomly crashing because of not enough power, missing boot strapping resistors or loose connections.
If you are using generic ESP modules, please follow [recommendations](Generic ESP8266 modules) on power supply and boot strapping resistors.
For boards with integrated USB to serial converter and power supply, usually it is enough to connect it to an USB hub that provides standard 0.5A and is not shared with other USB devices.
In any case make sure that your module is able to stable run standard example sketches that establish Wi-Fi connection like e.g. [HelloServer.ino](https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer/examples/HelloServer).
### What is the Cause of Restart?
You have verified that the ESP h/w is healthy but it still restarts. This is how ESP reacts to abnormal behavior of application. If something is wrong, it restarts itself to tell you about it.
There are two typical scenarios that trigger ESP restarts:
* **Exception** - when code is performing [illegal operation](https://github.com/esp8266/Arduino/blob/master/doc/exception_causes.md), like trying to write to non-existent memory location.
* **Watchdog** - if code is [locked up](https://en.wikipedia.org/wiki/Watchdog_timer) staying too long in a loop or processing some task, so vital processes like Wi-Fi communication are not able to run.
Please check below how to recognize [exception](#exception) and [watchdog](#watchdog) scenarios and what to do about it.
#### Exception
Typical restart because of exception looks like follows:
![Exception cause decoding](pictures/a02-exception-cause-decoding.png)
Start with looking up exception code in the [Exception Causes (EXCCAUSE)](https://github.com/esp8266/Arduino/blob/master/doc/exception_causes.md) table to understand what kind of issue it is. If you have no clues what it's about and where it happens, then use [Arduino ESP8266/ESP32 Exception Stack Trace Decoder](https://github.com/me-no-dev/EspExceptionDecoder) to find out in which line of application it is triggered. Please refer to [Check Where the Code Crashes](#check-where-the-code-crashes) point below for a quick example how to do it.
#### Watchdog
ESP provides two watchdog timers (wdt) that observe application for lock up.
* **Software Watchdog** - provided by [SDK](http://bbs.espressif.com/viewforum.php?f=46), that is part of [esp8266 / arduino](https://github.com/esp8266/Arduino) core loaded to module together with your application.
* **Hardware Watchdog** - build in ESP8266 hardware and acting if software watchdog is disabled for too long, in case it fails, or if it is not provided at all.
Restart by particular type of watchdog is clearly identified by ESP on serial monitor.
An example of application crash triggered by software wdt is shown below.
![Example of restart by s/w watchdog](pictures/a02-sw-watchdog-example.png)
Restart by the software watchdog is generally easier to troubleshoot since log includes the stack trace. The trace can be then used to find particular line in code where wdt has been triggered.
Reset by hardware watchdog timer is shown on picture below.
![Example of restart by h/w watchdog](pictures/a02-hw-watchdog-example.png)
Hardware wdt is the last resort of ESP to tell you that application is locked up (if s/w wdt timer is disabled or not working).
Please note that for restarts initialized by h/w wdt, there is no stack trace to help you identify the place in code where the lockup has happened. In such case, to identify the place of lock up, you need to rely on debug messages like ``` Serial.print ``` distributed across the application. Then by observing what was the last debug message printed out before restart, you should be able to narrow down part of code firing the h/w wdt reset. If diagnosed application or library has debug option then switch it on to aid this troubleshooting.
### Check Where the Code Crashes
Decoding of ESP stack trace is now easy and available to everybody thanks to great [Arduino ESP8266/ESP32 Exception Stack Trace Decoder](https://github.com/me-no-dev/EspExceptionDecoder) developed by @me-no-dev.
Installation for Arduino IDE is quick and easy following the [installation](https://github.com/me-no-dev/EspExceptionDecoder#installation) instructions.
If you don't have any code for troubleshooting, use the example below:
```
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.println("Let's provoke the s/w wdt firing...");
//
// wait for s/w wdt in infinite loop below
//
while(true);
//
Serial.println("This line will not ever print out");
}
void loop(){}
```
Upload this code to your ESP (Ctrl+U) and start Serial Monitor (Ctrl+Shift+M). You should shortly see ESP restarting every couple of seconds and ``` Soft WDT reset ``` message together with stack trace showing up on each restart. Click the Autoscroll check-box on Serial Monitor to stop the messages scrolling up. Select and copy the stack trace, go to the *Tools* and open the *ESP Exception Decoder*.
![Decode the stack trace, steps 1 and 2](pictures/a02-decode-stack-tace-1-2.png)
Now paste the stack trace to Exception Decoder's window. At the bottom of this window you should see a list of decoded lines of sketch you have just uploaded to your ESP. On the top of the list, like on the top of the stack trace, there is a reference to the last line executed just before the software watchdog timer fired causing the ESP's restart. Check the number of this line and look it up on the sketch. It should be the line ``` Serial.println("Let's provoke the s/w wdt firing...") ```, that happens to be just before ``` while(true) ``` that made the watchdog fired (ignore the lines with comments, that are discarded by compiler).
![Decode the stack trace, steps 3 through 6](pictures/a02-decode-stack-tace-3-6.png)
Armed with [Arduino ESP8266/ESP32 Exception Stack Trace Decoder](https://github.com/me-no-dev/EspExceptionDecoder) you can track down where the module is crashing whenever you see the stack trace dropped. The same procedure applies to crashes caused by exceptions.
> Note: To decode the exact line of code where the application crashed, you need to use ESP Exception Decoder in context of sketch you have just loaded to the module for diagnosis. Decoder is not able to correctly decode the stack trace dropped by some other application not compiled and loaded from your Arduino IDE.
### If at the Wall, Enter an Issue Report
Using the procedure above you should be able to troubleshoot all the code you write. It may happen that ESP is crashing inside some library or code you are not familiar enough to troubleshoot. If this is the case then contact the application author by writing an issue report.
Follow the guidelines on issue reporting that may be provided by the author of code in his / her repository.
If there are no guidelines, include in your report the following:
* [ ] Exact steps by step instructions to reproduce the issue
* [ ] Your exact hardware configuration including the schematic
* [ ] If the issue concerns standard, commercially available ESP board with power supply and USB interface, without extra h/w attached, then provide just the board type or link to description
* [ ] Configuration settings in Arduino IDE used to upload the application
* [ ] Error log & messages produced by the application (enable debugging for more details)
* [ ] Decoded stack trace
* [ ] Copy of your sketch
* [ ] Copy of all the libraries used by the sketch
* [ ] If you are using standard libraries available in Library Manager, then provide just version numbers
* [ ] Version of [esp8266 / Arduino](https://github.com/esp8266/Arduino) core
* [ ] Name and version of your programming IDE and O/S
With plenty of ESP module types available, several versions of libraries or [esp8266 / Arduino](https://github.com/esp8266/Arduino) core, types and versions of O/S, you need to provide exact information what your application is about. Only then people willing to look into your issue may be able to refer it to configuration they have. If you are lucky, they may even attempt to reproduce your issue on their equipment. This will be far more difficult if you are providing only vague details, so somebody would need to ask you to find out what is really happening.
On the other hand if you flood your issue report with hundreds lines of code, you may also have difficulty to find somebody willing to analyze it. Therefore reduce your code to the bare minimum that is still causing the issue. It will help you as well to isolate the issue and pin done the root cause.
### Conclusion
Do not be afraid to troubleshoot ESP exception and watchdog restarts. [Esp8266 / Arduino](https://github.com/esp8266/Arduino) core provides detailed diagnostics that will help you pin down the issue. Before checking the s/w, get your h/w right. Use [ESP Exception Decoder](https://github.com/me-no-dev/EspExceptionDecoder) to find out where the code fails. If you do you homework and still unable to identify the root cause, enter the issue report. Provide enough details. Be specific and isolate the issue. Then ask community for support. There are plenty of people that like to work with ESP and willing to help with your problem.
[FAQ list :back:](readme.md)

292
doc/faq/a02-my-esp-crashes.rst Normal file
View File

@ -0,0 +1,292 @@
:orphan:
My ESP crashes running some code. How to troubleshoot it?
---------------------------------------------------------
- `Introduction <#introduction>`__
- `What ESP has to Say <#what-esp-has-to-say>`__
- `Get Your H/W Right <#get-your-hw-right>`__
- `What is the Cause of Restart? <#what-is-the-cause-of-restart>`__
- `Exception <#exception>`__
- `Watchdog <#watchdog>`__
- `Check Where the Code Crashes <#check-where-the-code-crashes>`__
- `If at the Wall, Enter an Issue
Report <#if-at-the-wall-enter-an-issue-report>`__
- `Conclusion <#conclusion>`__
Introduction
~~~~~~~~~~~~
Your ESP is self restarting. You don't know why and what to do about it.
Do not panic.
In most of cases ESP provides enough clues on serial monitor, that you
can interpret to pin down the root cause. The first step is then
checking what ESP is saying on serial monitor when it crashes.
What ESP has to Say
~~~~~~~~~~~~~~~~~~~
Start off by opening a Serial Monitor (Ctrl+Shift+M) to observe the
output. Typical crash log looks as follows:
.. figure:: pictures/a02-typical-crash-log.png
:alt: Typical crash log
Typical crash log
Before rushing to copy and paste displayed code to Google, reflect for a
while on the nature of observed restarts:
- Does ESP restart on random basis, or under certain conditions, like
serving a web page?
- Do you see always the same exception code and stack trace or it
changes?
- Does this issue occur with unmodified standard example code (Arduino
IDE > *File > Examples*)?
If restarts are random or the exception code differs between restarts,
then the problem may be caused by h/w. If the issue occurs for standard
examples and stable `esp8266 /
arduino <https://github.com/esp8266/Arduino>`__ core, them the issue is
almost certainly caused by h/w.
Get Your H/W Right
~~~~~~~~~~~~~~~~~~
If you suspect the h/w, before troubleshooting the s/w, make sure to get
your h/w right. There is no much sense in diagnosing the s/w if you
board is randomly crashing because of not enough power, missing boot
strapping resistors or loose connections.
If you are using generic ESP modules, please follow
`recommendations <Generic%20ESP8266%20modules>`__ on power supply and
boot strapping resistors.
For boards with integrated USB to serial converter and power supply,
usually it is enough to connect it to an USB hub that provides standard
0.5A and is not shared with other USB devices.
In any case make sure that your module is able to stable run standard
example sketches that establish Wi-Fi connection like e.g.
`HelloServer.ino <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WebServer/examples/HelloServer>`__.
What is the Cause of Restart?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You have verified that the ESP h/w is healthy but it still restarts.
This is how ESP reacts to abnormal behavior of application. If something
is wrong, it restarts itself to tell you about it.
There are two typical scenarios that trigger ESP restarts:
- **Exception** - when code is performing `illegal
operation <https://github.com/esp8266/Arduino/blob/master/doc/exception_causes.md>`__,
like trying to write to non-existent memory location.
- **Watchdog** - if code is `locked
up <https://en.wikipedia.org/wiki/Watchdog_timer>`__ staying too long
in a loop or processing some task, so vital processes like Wi-Fi
communication are not able to run.
Please check below how to recognize `exception <#exception>`__ and
`watchdog <#watchdog>`__ scenarios and what to do about it.
Exception
^^^^^^^^^
Typical restart because of exception looks like follows:
.. figure:: pictures/a02-exception-cause-decoding.png
:alt: Exception cause decoding
Exception cause decoding
Start with looking up exception code in the `Exception Causes
(EXCCAUSE) <https://github.com/esp8266/Arduino/blob/master/doc/exception_causes.md>`__
table to understand what kind of issue it is. If you have no clues what
it's about and where it happens, then use `Arduino ESP8266/ESP32
Exception Stack Trace
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ to find
out in which line of application it is triggered. Please refer to `Check
Where the Code Crashes <#check-where-the-code-crashes>`__ point below
for a quick example how to do it.
Watchdog
^^^^^^^^
ESP provides two watchdog timers (wdt) that observe application for lock
up.
- **Software Watchdog** - provided by
`SDK <http://bbs.espressif.com/viewforum.php?f=46>`__, that is part
of `esp8266 / arduino <https://github.com/esp8266/Arduino>`__ core
loaded to module together with your application.
- **Hardware Watchdog** - build in ESP8266 hardware and acting if
software watchdog is disabled for too long, in case it fails, or if
it is not provided at all.
Restart by particular type of watchdog is clearly identified by ESP on
serial monitor.
An example of application crash triggered by software wdt is shown
below.
.. figure:: pictures/a02-sw-watchdog-example.png
:alt: Example of restart by s/w watchdog
Example of restart by s/w watchdog
Restart by the software watchdog is generally easier to troubleshoot
since log includes the stack trace. The trace can be then used to find
particular line in code where wdt has been triggered.
Reset by hardware watchdog timer is shown on picture below.
.. figure:: pictures/a02-hw-watchdog-example.png
:alt: Example of restart by h/w watchdog
Example of restart by h/w watchdog
Hardware wdt is the last resort of ESP to tell you that application is
locked up (if s/w wdt timer is disabled or not working).
Please note that for restarts initialized by h/w wdt, there is no stack
trace to help you identify the place in code where the lockup has
happened. In such case, to identify the place of lock up, you need to
rely on debug messages like ``Serial.print`` distributed across the
application. Then by observing what was the last debug message printed
out before restart, you should be able to narrow down part of code
firing the h/w wdt reset. If diagnosed application or library has debug
option then switch it on to aid this troubleshooting.
Check Where the Code Crashes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Decoding of ESP stack trace is now easy and available to everybody
thanks to great `Arduino ESP8266/ESP32 Exception Stack Trace
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ developed
by @me-no-dev.
Installation for Arduino IDE is quick and easy following the
`installation <https://github.com/me-no-dev/EspExceptionDecoder#installation>`__
instructions.
If you don't have any code for troubleshooting, use the example below:
::
void setup()
{
Serial.begin(115200);
Serial.println();
Serial.println("Let's provoke the s/w wdt firing...");
//
// wait for s/w wdt in infinite loop below
//
while(true);
//
Serial.println("This line will not ever print out");
}
void loop(){}
Upload this code to your ESP (Ctrl+U) and start Serial Monitor
(Ctrl+Shift+M). You should shortly see ESP restarting every couple of
seconds and ``Soft WDT reset`` message together with stack trace showing
up on each restart. Click the Autoscroll check-box on Serial Monitor to
stop the messages scrolling up. Select and copy the stack trace, go to
the *Tools* and open the *ESP Exception Decoder*.
.. figure:: pictures/a02-decode-stack-tace-1-2.png
:alt: Decode the stack trace, steps 1 and 2
Decode the stack trace, steps 1 and 2
Now paste the stack trace to Exception Decoder's window. At the bottom
of this window you should see a list of decoded lines of sketch you have
just uploaded to your ESP. On the top of the list, like on the top of
the stack trace, there is a reference to the last line executed just
before the software watchdog timer fired causing the ESP's restart.
Check the number of this line and look it up on the sketch. It should be
the line ``Serial.println("Let's provoke the s/w wdt firing...")``, that
happens to be just before ``while(true)`` that made the watchdog fired
(ignore the lines with comments, that are discarded by compiler).
.. figure:: pictures/a02-decode-stack-tace-3-6.png
:alt: Decode the stack trace, steps 3 through 6
Decode the stack trace, steps 3 through 6
Armed with `Arduino ESP8266/ESP32 Exception Stack Trace
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ you can
track down where the module is crashing whenever you see the stack trace
dropped. The same procedure applies to crashes caused by exceptions.
Note: To decode the exact line of code where the application
crashed, you need to use ESP Exception Decoder in context of sketch
you have just loaded to the module for diagnosis. Decoder is not
able to correctly decode the stack trace dropped by some other
application not compiled and loaded from your Arduino IDE.
If at the Wall, Enter an Issue Report
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using the procedure above you should be able to troubleshoot all the
code you write. It may happen that ESP is crashing inside some library
or code you are not familiar enough to troubleshoot. If this is the case
then contact the application author by writing an issue report.
Follow the guidelines on issue reporting that may be provided by the
author of code in his / her repository.
If there are no guidelines, include in your report the following:
- [ ] Exact steps by step instructions to reproduce the issue
- [ ] Your exact hardware configuration including the schematic
- [ ] If the issue concerns standard, commercially available ESP board
with power supply and USB interface, without extra h/w attached, then
provide just the board type or link to description
- [ ] Configuration settings in Arduino IDE used to upload the
application
- [ ] Error log & messages produced by the application (enable
debugging for more details)
- [ ] Decoded stack trace
- [ ] Copy of your sketch
- [ ] Copy of all the libraries used by the sketch
- [ ] If you are using standard libraries available in Library Manager,
then provide just version numbers
- [ ] Version of `esp8266 /
Arduino <https://github.com/esp8266/Arduino>`__ core
- [ ] Name and version of your programming IDE and O/S
With plenty of ESP module types available, several versions of libraries
or `esp8266 / Arduino <https://github.com/esp8266/Arduino>`__ core,
types and versions of O/S, you need to provide exact information what
your application is about. Only then people willing to look into your
issue may be able to refer it to configuration they have. If you are
lucky, they may even attempt to reproduce your issue on their equipment.
This will be far more difficult if you are providing only vague details,
so somebody would need to ask you to find out what is really happening.
On the other hand if you flood your issue report with hundreds lines of
code, you may also have difficulty to find somebody willing to analyze
it. Therefore reduce your code to the bare minimum that is still causing
the issue. It will help you as well to isolate the issue and pin done
the root cause.
Conclusion
~~~~~~~~~~
Do not be afraid to troubleshoot ESP exception and watchdog restarts.
`Esp8266 / Arduino <https://github.com/esp8266/Arduino>`__ core provides
detailed diagnostics that will help you pin down the issue. Before
checking the s/w, get your h/w right. Use `ESP Exception
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ to find
out where the code fails. If you do you homework and still unable to
identify the root cause, enter the issue report. Provide enough details.
Be specific and isolate the issue. Then ask community for support. There
are plenty of people that like to work with ESP and willing to help with
your problem.
`FAQ list :back: <readme.md>`__

85
doc/faq/a03-library-does-not-work.md
View File

@ -1,85 +0,0 @@
---
title: Frequently Asked Questions / Troubleshooting
---
[FAQ list :back:](readme.md)
## This Arduino library doesn't work on ESP. How do I make it working?
* [Introduction](#introduction)
* [Identify the Issues](#identify-the-issues)
* [Fix it Yourself](#fix-it-yourself)
* [Compilation Errors](#compilation-errors)
* [Exceptions / Watchdog Resets](#exceptions--watchdog-resets)
* [Functionality Issues](#functionality-issues)
* [Conclusion](#conclusion)
### Introduction
You would like to use this Arduino library with ESP8266 and it doesn't perform. It is not listed among [libraries verified to work with ESP8266](../doc/libraries.md#other-libraries-not-included-with-the-ide). You couldn't find any evidence on internet that it is compatible.
What are the odds to make it working?
### Identify the Issues
Start with looking for all the symptoms that it is not compatible with ESP8266. Ideally use example sketches provided with the library. Then list all the issues you are able to identify.
You are likely to see one or more of the following:
* Compilation drops errors
* There are no issues with compilation but application restarts because of exception or watchdog (wdt)
* Application seems to work, but does not function as expected, e.g. calculation results are incorrect.
Armed with the list of issues, contact the library author asking for comments. If issues are legitimate, then ask for his / her support to implement it for ESP8266. Being specific you have bigger chances convincing the author to help you either by updating the library or guiding you how to resolve the issues.
### Fix it Yourself
If library author is unable to provide support, then assess the chances of fixing it yourself.
#### Compilation Errors
*Issue:* Compiler complains about usage of AVR registers (PORTx, PINx, TCR1A, etc).
*Solution:* Check if usage of registers is well localized in a few functions, try to replace GPIO registers usage with digitalRead / digitalWrite, timer registers usage with timerX_ functions. If usage of AVR registers happens all over the code, this library might not be worth the effort. Also may be worth checking if someone got the library working on ARM (Due/STM), PIC, etc. If this is the case, maybe there already is a version of the library which uses Arduino APIs instead of raw registers.
*Issue:* Compiler complains about ``` <avr/pgmspace.h> ```.
*Solution:* modify the library by adding conditional include of ESP's pgmspace.h.
```
#ifdef ESP8266
#include <pgmspace.h>
#else
#include <avr/pgmspace.h>
#endif
```
#### Exceptions / Watchdog Resets
To troubleshoot resets follow FAQ item [My ESP crashes running some code](a02-my-esp-crashes.md).
#### Functionality Issues
*Issue:* Application works but returns weird numerical values.
*Solution:*: Check the usage of `int` type in the library. On AVRs integers are 16 bit, and on ESPs they are 32 bit (just like on ARM).
*Issue:* Some device with time critical control like a servo drive or a strip pf LEDs does not operate smoothly and tends to randomly change position or displayed pattern.
*Solution:*: Check for usage of interrupts that may get in conflict with Wi-Fi activity of ESP8266. You may temporarily disable Wi-Fi communication ``` WiFi.mode(WIFI_OFF); ``` to check if it helps.
### Conclusion
Identify compatibility issues and ask library author for support. If left on your own, then check for usage of controller's low level access functionality. Use [Esp Exception Decoder](https://github.com/me-no-dev/EspExceptionDecoder) if confronted with exceptions / watchdogs resets.
The good news is that the number of libraries which aren't supported on the ESP8266 is shrinking. Community of ESP8266 enthusiasts is growing. If you are unable to resolve the issues yourself, there are very good odds that you will be able to find somebody else to help you.
[FAQ list :back:](readme.md)

112
doc/faq/a03-library-does-not-work.rst Normal file
View File

@ -0,0 +1,112 @@
:orphan:
This Arduino library doesn't work on ESP. How do I make it working?
-------------------------------------------------------------------
- `Introduction <#introduction>`__
- `Identify the Issues <#identify-the-issues>`__
- `Fix it Yourself <#fix-it-yourself>`__
- `Compilation Errors <#compilation-errors>`__
- `Exceptions / Watchdog Resets <#exceptions--watchdog-resets>`__
- `Functionality Issues <#functionality-issues>`__
- `Conclusion <#conclusion>`__
Introduction
~~~~~~~~~~~~
You would like to use this Arduino library with ESP8266 and it doesn't
perform. It is not listed among `libraries verified to work with
ESP8266 <../doc/libraries.md#other-libraries-not-included-with-the-ide>`__.
You couldn't find any evidence on internet that it is compatible.
What are the odds to make it working?
Identify the Issues
~~~~~~~~~~~~~~~~~~~
Start with looking for all the symptoms that it is not compatible with
ESP8266. Ideally use example sketches provided with the library. Then
list all the issues you are able to identify.
You are likely to see one or more of the following: \* Compilation drops
errors \* There are no issues with compilation but application restarts
because of exception or watchdog (wdt) \* Application seems to work, but
does not function as expected, e.g. calculation results are incorrect.
Armed with the list of issues, contact the library author asking for
comments. If issues are legitimate, then ask for his / her support to
implement it for ESP8266. Being specific you have bigger chances
convincing the author to help you either by updating the library or
guiding you how to resolve the issues.
Fix it Yourself
~~~~~~~~~~~~~~~
If library author is unable to provide support, then assess the chances
of fixing it yourself.
Compilation Errors
^^^^^^^^^^^^^^^^^^
*Issue:* Compiler complains about usage of AVR registers (PORTx, PINx,
TCR1A, etc).
*Solution:* Check if usage of registers is well localized in a few
functions, try to replace GPIO registers usage with digitalRead /
digitalWrite, timer registers usage with timerX\_ functions. If usage of
AVR registers happens all over the code, this library might not be worth
the effort. Also may be worth checking if someone got the library
working on ARM (Due/STM), PIC, etc. If this is the case, maybe there
already is a version of the library which uses Arduino APIs instead of
raw registers.
*Issue:* Compiler complains about ``<avr/pgmspace.h>``.
*Solution:* modify the library by adding conditional include of ESP's
pgmspace.h.
::
#ifdef ESP8266
#include <pgmspace.h>
#else
#include <avr/pgmspace.h>
#endif
Exceptions / Watchdog Resets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To troubleshoot resets follow FAQ item `My ESP crashes running some
code <a02-my-esp-crashes.md>`__.
Functionality Issues
^^^^^^^^^^^^^^^^^^^^
*Issue:* Application works but returns weird numerical values.
*Solution:*: Check the usage of ``int`` type in the library. On AVRs
integers are 16 bit, and on ESPs they are 32 bit (just like on ARM).
*Issue:* Some device with time critical control like a servo drive or a
strip pf LEDs does not operate smoothly and tends to randomly change
position or displayed pattern.
*Solution:*: Check for usage of interrupts that may get in conflict with
Wi-Fi activity of ESP8266. You may temporarily disable Wi-Fi
communication ``WiFi.mode(WIFI_OFF);`` to check if it helps.
Conclusion
~~~~~~~~~~
Identify compatibility issues and ask library author for support. If
left on your own, then check for usage of controller's low level access
functionality. Use `Esp Exception
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ if
confronted with exceptions / watchdogs resets.
The good news is that the number of libraries which aren't supported on
the ESP8266 is shrinking. Community of ESP8266 enthusiasts is growing.
If you are unable to resolve the issues yourself, there are very good
odds that you will be able to find somebody else to help you.
`FAQ list :back: <readme.md>`__

99
doc/faq/a04-board-generic-is-unknown.md
View File

@ -1,99 +0,0 @@
---
title: Frequently Asked Questions / Troubleshooting
---
[FAQ list :back:](readme.md)
## How to resolve "Board generic (platform esp8266, package esp8266) is unknown" error?
This error may pop up after switching between [staging](https://github.com/esp8266/Arduino#staging-version-) and [stable](https://github.com/esp8266/Arduino#stable-version-) esp8266 / Arduino package installations, or after upgrading the package version.
![alt text](pictures/a04-board-is-unknown-error.png "Board nodemcu2 (platform esp8266, package esp8266) is unknown error")
If you face this issue, you will not be able to compile any sketch for any ESP8266 module type.
Read below what is the error root cause or jump straight to the [resolution](#how-to-fix-it)
### The Root Cause
This issue is attributed to Arduino IDE Boards Manager not cleaning up previous package installation before a new one is applied. As this is not done, then it is user responsibility to remove previous package before applying a new one.
To prevent it from happening, if you are changing between **staging** and **stable**, first press *Remove* button to delete currently used installation.
![alt text](pictures/a04-remove-package-yes.png "If changing between staging and stable, remove currently installed package")
There is no need to remove the installed package if you are changing it to another version (without switching between staging and stable).
![alt text](pictures/a04-remove-package-no.png "No need to remove installed package if changing its version")
Depending on selected module the error message is slightly different. For instance, if you choose *Generic ESP8266 Module*, it will look as follows:
```
Board generic (platform esp8266, package esp8266) is unknown
Error compiling for board Generic ESP8266 Module.
```
Below is an example messages for [WeMos](https://github.com/esp8266/Arduino/blob/master/doc/boards.md#wemos-d1):
```
Board d1_mini (platform esp8266, package esp8266) is unknown
Error compiling for board WeMos D1 R2 & mini.
```
... and another one for [Adafruit HUZZAH](https://github.com/esp8266/Arduino/blob/master/doc/boards.md#adafruit-huzzah-esp8266-esp-12):
```
Board huzzah (platform esp8266, package esp8266) is unknown
Error compiling for board Adafruit HUZZAH ESP8266.
```
If the issue already happens, then uninstalling and re-installing the package with *Boards Manager* typically will not fix it.
Uninstalling and re-installing the Arduino IDE will not fix it as well.
Well, OK, fine. You will be able to fix it with Boards Manager. To do so, you need to carefully go step by step through the effort of removing new and then the old package. Once done you can install again the new package. Did I mention that in between you need to change twice [JOSN](https://github.com/esp8266/Arduino#installing-with-boards-manager) in *Additional Boards Manager URLs*?
Fortunately there is a quicker and more effective fix. See below.
### How to Fix it?
Issue resolution is as simple as deleting a folder with older esp8266 / Arduino installation.
Procedure is identical on Windows, Linux and Mac OS. The only difference is folder path. For instance, on Mac, it will be `/Users/$USER/Library/Arduino15/packages/esp8266/hardware/esp8266`. Example below shows the path for Windows.
1. Check location of installation folder by going to *File > Preferences* (Ctrl+,). The folder location is at the very bottom of the *Preferences* window.
![alt text](pictures/a04-arduino-ide-preferences.png "Checking of Arduino IDE Preferences")
2. Click provided link to open the folder. For Windows 7 it will look as follows:
![alt text](pictures/a04-contents-of-preferences-folder.png "Contents of Arduino IDE preferences folder")
3. Navigate further down to `Arduino15\packages\esp8266\hardware\esp8266` directory. Inside you will find two folders with different esp8266 / Arduino package installations.
![alt text](pictures/a04-contents-of-package-folder.png "Checking of contents of esp8266 / Arduino package folder")
4. Delete the older folder. Restart Arduino IDE, select your ESP module and the error should be gone.
Note: If you are not sure which folder to delete, then remove both of them. Restart Arduino IDE, go to *Tools > Board: > Boards Manager* and install the esp8266 / Arduino package again. Select ESP8266 module and the issue should be resolved.
### More Information
This issue has been reported quite frequently in [Issues](https://github.com/esp8266/Arduino/issues) section of esp8266 / Arduino repository. The most appreciated solution was provided by [@anhhuy0501](https://github.com/anhhuy0501) in
[#1387](https://github.com/esp8266/Arduino/issues/1387#issuecomment-204865028).
If you are interested in more details, please refer to [#2297](https://github.com/esp8266/Arduino/issues/2297),
[#2156](https://github.com/esp8266/Arduino/issues/2156),
[#2022](https://github.com/esp8266/Arduino/issues/2022),
[#1802](https://github.com/esp8266/Arduino/issues/1802),
[#1514](https://github.com/esp8266/Arduino/issues/1514),
[#1387](https://github.com/esp8266/Arduino/issues/1387),
[#1377](https://github.com/esp8266/Arduino/issues/1377),
[#1251](https://github.com/esp8266/Arduino/issues/1251),
[#1247](https://github.com/esp8266/Arduino/issues/1247),
[#948](https://github.com/esp8266/Arduino/issues/948)

151
doc/faq/a04-board-generic-is-unknown.rst Normal file
View File

@ -0,0 +1,151 @@
:orphan:
How to resolve "Board generic (platform esp8266, package esp8266) is unknown" error?
------------------------------------------------------------------------------------
This error may pop up after switching between
`staging <https://github.com/esp8266/Arduino#staging-version->`__ and
`stable <https://github.com/esp8266/Arduino#stable-version->`__ esp8266
/ Arduino package installations, or after upgrading the package version.
.. figure:: pictures/a04-board-is-unknown-error.png
:alt: Board nodemcu2 (platform esp8266, package esp8266) is unknown error
alt text
If you face this issue, you will not be able to compile any sketch for
any ESP8266 module type.
Read below what is the error root cause or jump straight to the
`resolution <#how-to-fix-it>`__
The Root Cause
~~~~~~~~~~~~~~
This issue is attributed to Arduino IDE Boards Manager not cleaning up
previous package installation before a new one is applied. As this is
not done, then it is user responsibility to remove previous package
before applying a new one.
To prevent it from happening, if you are changing between **staging**
and **stable**, first press *Remove* button to delete currently used
installation.
.. figure:: pictures/a04-remove-package-yes.png
:alt: If changing between staging and stable, remove currently installed package
alt text
There is no need to remove the installed package if you are changing it
to another version (without switching between staging and stable).
.. figure:: pictures/a04-remove-package-no.png
:alt: No need to remove installed package if changing its version
alt text
Depending on selected module the error message is slightly different.
For instance, if you choose *Generic ESP8266 Module*, it will look as
follows:
::
Board generic (platform esp8266, package esp8266) is unknown
Error compiling for board Generic ESP8266 Module.
Below is an example messages for
`WeMos <https://github.com/esp8266/Arduino/blob/master/doc/boards.md#wemos-d1>`__:
::
Board d1_mini (platform esp8266, package esp8266) is unknown
Error compiling for board WeMos D1 R2 & mini.
... and another one for `Adafruit
HUZZAH <https://github.com/esp8266/Arduino/blob/master/doc/boards.md#adafruit-huzzah-esp8266-esp-12>`__:
::
Board huzzah (platform esp8266, package esp8266) is unknown
Error compiling for board Adafruit HUZZAH ESP8266.
If the issue already happens, then uninstalling and re-installing the
package with *Boards Manager* typically will not fix it.
Uninstalling and re-installing the Arduino IDE will not fix it as well.
Well, OK, fine. You will be able to fix it with Boards Manager. To do
so, you need to carefully go step by step through the effort of removing
new and then the old package. Once done you can install again the new
package. Did I mention that in between you need to change twice
`JOSN <https://github.com/esp8266/Arduino#installing-with-boards-manager>`__
in *Additional Boards Manager URLs*?
Fortunately there is a quicker and more effective fix. See below.
How to Fix it?
~~~~~~~~~~~~~~
Issue resolution is as simple as deleting a folder with older esp8266 /
Arduino installation.
Procedure is identical on Windows, Linux and Mac OS. The only difference
is folder path. For instance, on Mac, it will be
``/Users/$USER/Library/Arduino15/packages/esp8266/hardware/esp8266``.
Example below shows the path for Windows.
1. Check location of installation folder by going to *File >
Preferences* (Ctrl+,). The folder location is at the very bottom of
the *Preferences* window.
.. figure:: pictures/a04-arduino-ide-preferences.png
:alt: Checking of Arduino IDE Preferences
alt text
2. Click provided link to open the folder. For Windows 7 it will look as
follows:
.. figure:: pictures/a04-contents-of-preferences-folder.png
:alt: Contents of Arduino IDE preferences folder
alt text
3. Navigate further down to
``Arduino15\packages\esp8266\hardware\esp8266`` directory. Inside you
will find two folders with different esp8266 / Arduino package
installations.
.. figure:: pictures/a04-contents-of-package-folder.png
:alt: Checking of contents of esp8266 / Arduino package folder
alt text
4. Delete the older folder. Restart Arduino IDE, select your ESP module
and the error should be gone.
Note: If you are not sure which folder to delete, then remove both of
them. Restart Arduino IDE, go to *Tools > Board: > Boards Manager* and
install the esp8266 / Arduino package again. Select ESP8266 module and
the issue should be resolved.
More Information
~~~~~~~~~~~~~~~~
This issue has been reported quite frequently in
`Issues <https://github.com/esp8266/Arduino/issues>`__ section of
esp8266 / Arduino repository. The most appreciated solution was provided
by [@anhhuy0501](https://github.com/anhhuy0501) in
`#1387 <https://github.com/esp8266/Arduino/issues/1387#issuecomment-204865028>`__.
If you are interested in more details, please refer to
`#2297 <https://github.com/esp8266/Arduino/issues/2297>`__,
`#2156 <https://github.com/esp8266/Arduino/issues/2156>`__,
`#2022 <https://github.com/esp8266/Arduino/issues/2022>`__,
`#1802 <https://github.com/esp8266/Arduino/issues/1802>`__,
`#1514 <https://github.com/esp8266/Arduino/issues/1514>`__,
`#1387 <https://github.com/esp8266/Arduino/issues/1387>`__,
`#1377 <https://github.com/esp8266/Arduino/issues/1377>`__,
`#1251 <https://github.com/esp8266/Arduino/issues/1251>`__,
`#1247 <https://github.com/esp8266/Arduino/issues/1247>`__,
`#948 <https://github.com/esp8266/Arduino/issues/948>`__

50
doc/faq/readme.md
View File

@ -1,50 +0,0 @@
---
title: Frequently Asked Questions / Troubleshooting
---
The purpose of this FAQ / Troubleshooting is to respond to questions commonly asked in [Issues](https://github.com/esp8266/Arduino/issues) section and on [ESP8266 Community forum](http://www.esp8266.com/).
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 :arrow_right: to more details.
Please feel free to contribute if you believe that some frequent issues are not covered below.
### I am getting "espcomm_sync failed" error when trying to upload my ESP. How to resolve this issue?
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 [:arrow_right:](a01-espcomm_sync-failed.md)
### Why esptool is not listed in "Programmer" menu? How do I upload ESP without it?
Do not worry about "Programmer" menu of Arduino IDE. It doesn't matter what is selected in it <20> upload now always defaults to using esptool.
Ref. [#138](https://github.com/esp8266/Arduino/issues/138), [#653](https://github.com/esp8266/Arduino/issues/653) and [#739](https://github.com/esp8266/Arduino/issues/739).
### My ESP crashes running some code. How to troubleshoot it?
The code may crash because of s/w bug or issue with your h/w. Before entering an issue report, please perform initial troubleshooting [:arrow_right:](a02-my-esp-crashes.md)
### This Arduino library doesn't work on ESP. How do I make it working?
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 [:arrow_right:](a03-library-does-not-work.md)
### In the IDE, for ESP-12E that has 4M flash, I can choose 4M (1M SPIFFS) or 4M (3M SPIFFS). 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 4M or 1M SPIFFS 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.
### I have observed a case when ESP.restart() doesn't work. What is the reason for that?
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](https://github.com/esp8266/Arduino/issues/1017#issuecomment-200605576). 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.
Ref. [#1017](https://github.com/esp8266/Arduino/issues/1017), [#1107](https://github.com/esp8266/Arduino/issues/1107), [#1782](https://github.com/esp8266/Arduino/issues/1782)
### How to resolve "Board generic (platform esp8266, package esp8266) is unknown" error?
This error may pop up after switching between [staging](https://github.com/esp8266/Arduino#staging-version-) and [stable](https://github.com/esp8266/Arduino#stable-version-) esp8266 / Arduino package installations, or after upgrading the package version [:arrow_right:](a04-board-generic-is-unknown.md)

90
doc/faq/readme.rst Normal file
View File

@ -0,0 +1,90 @@
FAQ
===
The purpose of this FAQ / Troubleshooting is to respond to questions
commonly asked in `Issues <https://github.com/esp8266/Arduino/issues>`__
section and on `ESP8266 Community forum <http://www.esp8266.com/>`__.
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
:arrow\_right: to more details.
Please feel free to contribute if you believe that some frequent issues
are not covered below.
I am getting "espcomm\_sync failed" error when trying to upload my ESP. How to resolve this issue?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
:doc:`Read more <a01-espcomm_sync-failed>`.
Why esptool is not listed in "Programmer" menu? How do I upload ESP without it?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
Ref. `#138 <https://github.com/esp8266/Arduino/issues/138>`__,
`#653 <https://github.com/esp8266/Arduino/issues/653>`__ and
`#739 <https://github.com/esp8266/Arduino/issues/739>`__.
My ESP crashes running some code. How to troubleshoot it?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The code may crash because of s/w bug or issue with your h/w. Before
entering an issue report, please perform initial troubleshooting.
:doc:`Read more <a02-my-esp-crashes>`.
This Arduino library doesn't work on ESP. How do I make it working?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
:doc:`Read more <a03-library-does-not-work>`.
In the IDE, for ESP-12E that has 4M flash, I can choose 4M (1M SPIFFS) or 4M (3M SPIFFS). 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 4M or 1M SPIFFS 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.
I have observed a case when ESP.restart() doesn't work. What is the reason for that?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 <https://github.com/esp8266/Arduino/issues/1017#issuecomment-200605576>`__.
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.
Ref. `#1017 <https://github.com/esp8266/Arduino/issues/1017>`__,
`#1107 <https://github.com/esp8266/Arduino/issues/1107>`__,
`#1782 <https://github.com/esp8266/Arduino/issues/1782>`__
How to resolve "Board generic (platform esp8266, package esp8266) is unknown" error?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This error may pop up after switching between
`staging <https://github.com/esp8266/Arduino#staging-version->`__ and
`stable <https://github.com/esp8266/Arduino#stable-version->`__ esp8266
/ Arduino package installations, or after upgrading the package version
:doc:`Read more <a04-board-generic-is-unknown>`.