From a9923d190ec7b1c2f41d7042da91358fa7b8f405 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 7 Aug 2016 17:27:30 +0300 Subject: [PATCH] docs/esp8266/intro: Add troubleshooting section. Tries to summarize most of the issues we've seen so far. --- docs/esp8266/tutorial/intro.rst | 58 +++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst index 16641a19d4..f92dc8ab70 100644 --- a/docs/esp8266/tutorial/intro.rst +++ b/docs/esp8266/tutorial/intro.rst @@ -101,3 +101,61 @@ be the same everytime, and most likely different for all ESP8266 chips). The password for the WiFi is micropythoN (note the upper-case N). Its IP address will be 192.168.4.1 once you connect to its network. WiFi configuration will be discussed in more detail later in the tutorial. + +Troubleshooting installation problems +------------------------------------- + +If you experience problems during flashing or with running firmware immediately +after it, here are troubleshooting recommendations: + +* Be aware of and try to exclude hardware problems. There are 2 common problems: + bad power source quality and worn-out/defective FlashROM. Speaking of power + source, not just raw amperage is important, but also low ripple and noise/EMI + in general. If you experience issues with self-made or wall-wart style power + supply, try USB power from a computer. Unearthed power supplies are also known + to cause problems as they source of increased EMI (electromagnetic interference) + - at the very least, as by the common safety standards they are considered + a hazard which may lead to electrical device breakdown and eletric shock to + humans. Please avoid using unearthed power connections at any time. In regard + to FlashROM hardware problems, there are independent (not related to MicroPython + in any way) reports + `(e.g.) `_ + that on some ESP8266 modules, FlashROM can be programmed as little as 20 times + before programming errors occur. This is *much* less than 100,000 programming + cycles cited for FlashROM chips of a type used with ESP8266 by reputable + vendors, which points to either production rejects, or second-hand worn-out + flash chips to be used on some (apparently cheap) modules/boards. You may want + to use your best judgement about source, price, documentation, warranty, + post-sales support for the modules/boards you purchase. + +* The flashing instructions above use flashing speed of 460800 baud, which is + good compromise between speed and stability. However, depending on your + module/board, USB-UART convertor, cables, host OS, etc., the above baud + rate may be too high and lead to errors. Try a more common 115200 baud + rate instead in such cases. + +* The ``--flash_size`` option in the commands above is mandatory. Omitting + it will lead to a corrupted firmware. + +* To catch incorrect flash content (e.g. from a defective sector on a chip), + add ``--verify`` switch to the commands above. + +* Additionally, you can check the firmware integrity from a MicroPython REPL + prompt (assuming you were able to flash it and ``--verify`` option doesn't + report errors):: + import esp + esp.check_fw() + If the last output value is True, the firmware is OK. Otherwise, it's + corrupted and need to be reflashed correctly. + +* If you experience any issues with another flashing application (not + esptool.py), try esptool.py, it is a generally accepted flashing + application in the ESP8266 community. + +* If you still experience problems with even flashing the firmware, please + refer to esptool.py project page, https://github.com/themadinventor/esptool + for additional documentation and bug tracker where you can report problems. + +* If you are able to flash firmware, but ``--verify`` option or + ``esp.check_fw()`` return errors even after multiple retries, you + may have a defective FlashROM chip, as explained above.