From 2143c091b511c31280178c81c417f7d03d4175c5 Mon Sep 17 00:00:00 2001 From: Maxim Prokhorov Date: Thu, 29 May 2025 04:24:45 +0300 Subject: [PATCH 1/2] Doc - mention esptool.FatalError & syntax corrections --- ..._sync-failed.rst => a01-upload-failed.rst} | 122 ++++++++++++++++-- doc/faq/readme.rst | 6 +- 2 files changed, 112 insertions(+), 16 deletions(-) rename doc/faq/{a01-espcomm_sync-failed.rst => a01-upload-failed.rst} (78%) diff --git a/doc/faq/a01-espcomm_sync-failed.rst b/doc/faq/a01-upload-failed.rst similarity index 78% rename from doc/faq/a01-espcomm_sync-failed.rst rename to doc/faq/a01-upload-failed.rst index d47a5d2eeb..8472aa3b12 100644 --- a/doc/faq/a01-espcomm_sync-failed.rst +++ b/doc/faq/a01-upload-failed.rst @@ -1,7 +1,7 @@ :orphan: -I am getting "espcomm\_sync failed" error when trying to upload my ESP. How to resolve this issue? --------------------------------------------------------------------------------------------------- +Why I am getting errors when trying to upload to my ESP? +-------------------------------------------------------- - `Introduction <#introduction>`__ - `Initial Checks <#initial-checks>`__ @@ -15,14 +15,24 @@ I am getting "espcomm\_sync failed" error when trying to upload my ESP. How to r Introduction ~~~~~~~~~~~~ -This message indicates issue with uploading ESP module over a serial +Messages like + +* ``espcomm_sync failed`` + +* ``esptool.FatalError: Failed to connect to ESP8266: Invalid head of packet (0xF0)`` + +* ``esptool.FatalError: Failed to connect to ESP8266: Timed out waiting for packet header`` + +indicate issue with 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 +.. 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. @@ -167,7 +177,93 @@ loading <../boards.rst#minimal-hardware-setup-for-bootloading-only>`__ 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 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`` + For example, uploading using esptool.py and esptool + +.. code-block:: console + + $ esptool.py --after no_reset --chip esp8266 --baud 460800 write_flash 0x0 d1-mini-firmware.bin + esptool.py v4.5.1 + Found 1 serial ports + Serial port /dev/ttyUSB0 + Connecting.... + Chip is ESP8266EX + Features: WiFi + Crystal is 26MHz + MAC: 11:22:33:44:55:66 + Uploading stub... + Running stub... + Stub running... + Changing baud rate to 460800 + Changed. + Configuring flash size... + Flash will be erased from 0x00000000 to 0x0004efff... + Compressed 321440 bytes to 221714... + Wrote 321440 bytes (221714 compressed) at 0x00000000 in 5.0 seconds (effective 511.4 kbit/s)... + Hash of data verified. + + Leaving... + Staying in bootloader. + + +.. code-block:: console + + > 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 + 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 @@ -177,7 +273,7 @@ rate, etc. Resolve all noted differences. Reset Methods ~~~~~~~~~~~~~ -If you got to this point and still see ``espcomm_sync failed``, then now +If you got to this point and still see uploading error, 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 @@ -238,13 +334,13 @@ 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 + 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 diff --git a/doc/faq/readme.rst b/doc/faq/readme.rst index cfd65eca90..08a5621972 100644 --- a/doc/faq/readme.rst +++ b/doc/faq/readme.rst @@ -13,14 +13,14 @@ 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? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +I am getting "espcomm\_sync failed", "esptool.FatalError", etc. 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. -`Read more `__. +`Read more `__. Why esptool is not listed in "Programmer" menu? How do I upload ESP without it? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 39935b1430efd54154316ae672492b4a21c99bc9 Mon Sep 17 00:00:00 2001 From: Maxim Prokhorov Date: Thu, 29 May 2025 04:40:22 +0300 Subject: [PATCH 2/2] Doc - un-orphan FAQ and toctree inclusion --- doc/{faq/readme.rst => faq.rst} | 14 +++++++------- doc/faq/a01-upload-failed.rst | 2 -- doc/faq/a02-my-esp-crashes.rst | 2 -- doc/faq/a03-library-does-not-work.rst | 2 -- doc/faq/a04-board-generic-is-unknown.rst | 2 -- doc/faq/a05-board-generator.rst | 2 -- doc/faq/a06-global-build-options.rst | 2 -- doc/index.rst | 23 ++++++++++++++++++++--- 8 files changed, 27 insertions(+), 22 deletions(-) rename doc/{faq/readme.rst => faq.rst} (96%) diff --git a/doc/faq/readme.rst b/doc/faq.rst similarity index 96% rename from doc/faq/readme.rst rename to doc/faq.rst index 08a5621972..869db97bc2 100644 --- a/doc/faq/readme.rst +++ b/doc/faq.rst @@ -20,7 +20,7 @@ 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. -`Read more `__. +`Read more `__. Why esptool is not listed in "Programmer" menu? How do I upload ESP without it? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -38,7 +38,7 @@ 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. -`Read more `__. +`Read more `__. How can I get some extra KBs in flash ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -50,7 +50,7 @@ How can I get some extra KBs in flash ? * Use the debug level option ``NoAssert-NDEBUG`` (in the Tools menu) -`Read more `__. +`Read more `__. About WPS ~~~~~~~~~ @@ -63,7 +63,7 @@ required to enable it: ``./tools/boards.txt.py --allowWPS --boardsgen`` -`Read more `__. +`Read more `__. For platformIO (and maybe other build environments), you will also need to add the build flag: -D NO_EXTRA_4K_HEAP @@ -77,7 +77,7 @@ This Arduino library doesn't work on ESP. How do I make it work? 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. -`Read more `__. +`Read more `__. 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? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -118,7 +118,7 @@ This error may pop up after switching between `staging `__ and `stable `__ esp8266 / Arduino package installations, or after upgrading the package version -`Read more `__. +`Read more `__. How to clear TCP PCBs in time-wait state ? @@ -199,4 +199,4 @@ 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. -`Read more `__. +`Read more `__. diff --git a/doc/faq/a01-upload-failed.rst b/doc/faq/a01-upload-failed.rst index 8472aa3b12..cefda15829 100644 --- a/doc/faq/a01-upload-failed.rst +++ b/doc/faq/a01-upload-failed.rst @@ -1,5 +1,3 @@ -:orphan: - Why I am getting errors when trying to upload to my ESP? -------------------------------------------------------- diff --git a/doc/faq/a02-my-esp-crashes.rst b/doc/faq/a02-my-esp-crashes.rst index ec6340e8c7..c480a825e7 100644 --- a/doc/faq/a02-my-esp-crashes.rst +++ b/doc/faq/a02-my-esp-crashes.rst @@ -1,5 +1,3 @@ -:orphan: - My ESP crashes running some code. How to troubleshoot it? --------------------------------------------------------- diff --git a/doc/faq/a03-library-does-not-work.rst b/doc/faq/a03-library-does-not-work.rst index 6597c1a1dc..e34ad050b1 100644 --- a/doc/faq/a03-library-does-not-work.rst +++ b/doc/faq/a03-library-does-not-work.rst @@ -1,5 +1,3 @@ -:orphan: - This Arduino library doesn't work on ESP. How do I make it working? ------------------------------------------------------------------- diff --git a/doc/faq/a04-board-generic-is-unknown.rst b/doc/faq/a04-board-generic-is-unknown.rst index 88e2f3e7be..ada9a7eec2 100644 --- a/doc/faq/a04-board-generic-is-unknown.rst +++ b/doc/faq/a04-board-generic-is-unknown.rst @@ -1,5 +1,3 @@ -:orphan: - How to resolve "Board generic (platform esp8266, package esp8266) is unknown" error? ------------------------------------------------------------------------------------ diff --git a/doc/faq/a05-board-generator.rst b/doc/faq/a05-board-generator.rst index 279491355e..4f31fce996 100644 --- a/doc/faq/a05-board-generator.rst +++ b/doc/faq/a05-board-generator.rst @@ -1,5 +1,3 @@ -:orphan: - Board generator --------------- diff --git a/doc/faq/a06-global-build-options.rst b/doc/faq/a06-global-build-options.rst index 3e86b88a58..231dbc6baf 100644 --- a/doc/faq/a06-global-build-options.rst +++ b/doc/faq/a06-global-build-options.rst @@ -1,5 +1,3 @@ -:orphan: - How to specify global build defines and options =============================================== diff --git a/doc/index.rst b/doc/index.rst index 5f3ec247c6..afe976348e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,9 +1,11 @@ Welcome to ESP8266 Arduino Core's documentation! ================================================ +Using ESP8266 Core +================== + .. toctree:: :maxdepth: 2 - :caption: Contents: Installing Arduino IDE options @@ -15,11 +17,26 @@ Welcome to ESP8266 Arduino Core's documentation! PROGMEM Using GDB to debug MMU - Boards - FAQ +Troubleshooting +=============== +.. toctree:: + :caption: Troubleshooting + :maxdepth: 2 + + FAQ Exception causes Debugging Stack Dump Using with Eclipse + +FAQ +=== +.. toctree:: + :caption: FAQ + :maxdepth: 2 + :titlesonly: + :glob: + + faq/*