From 1966745689b5fe23526231e5f94096dbc82ea803 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 7 Aug 2016 16:31:09 +0300 Subject: esp8266/tutorial/intro: Reword para abou -fm dio switch. Not all NodeMCU boards require it. --- docs/esp8266/tutorial/intro.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/esp8266/tutorial/intro.rst') diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst index a2c5d1838..50b590f88 100644 --- a/docs/esp8266/tutorial/intro.rst +++ b/docs/esp8266/tutorial/intro.rst @@ -74,8 +74,9 @@ PC. You may also need to reduce the baudrate if you get errors when flashing (eg down to 115200). The filename of the firmware should also match the file that you have. -If you have a NodeMCU board, you may need to use the following command to deploy -the firmware (note the "-fm dio" option):: +For some boards with a particular FlashROM configuration (e.g. some variants of +a NodeMCU board) you may need to use the following command to deploy +the firmware (note the ``-fm dio`` option):: esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=8m -fm dio 0 esp8266-2016-05-03-v1.8.bin -- cgit v1.2.3 From 919c54f750cf3e25f2010b2d38079b9690872795 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 7 Aug 2016 16:33:52 +0300 Subject: docs/esp8266/intro: Rename to "Getting started" from "Introduction". People tend to skip introductions (everyone knows what esp8266 is, right?), so try to do A/B testing with a title inviting to read it. --- docs/esp8266/tutorial/intro.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/esp8266/tutorial/intro.rst') diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst index 50b590f88..16641a19d 100644 --- a/docs/esp8266/tutorial/intro.rst +++ b/docs/esp8266/tutorial/intro.rst @@ -1,5 +1,5 @@ -Introduction to MicroPython on the ESP8266 -========================================== +Getting started with MicroPython on the ESP8266 +=============================================== Using MicroPython is a great way to get the most of your ESP8266 board. And vice versa, the ESP8266 chip is a great platform for using MicroPython. This -- cgit v1.2.3 From a9923d190ec7b1c2f41d7042da91358fa7b8f405 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 7 Aug 2016 17:27:30 +0300 Subject: 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(+) (limited to 'docs/esp8266/tutorial/intro.rst') diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst index 16641a19d..f92dc8ab7 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. -- cgit v1.2.3 From d2cab0b7beebcc4f56f06a9748685cf05bced9a6 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 7 Aug 2016 22:16:40 +0300 Subject: docs/esp8266/tutorial/intro: Add anchor for link from quickeref. --- docs/esp8266/tutorial/intro.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/esp8266/tutorial/intro.rst') diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst index f92dc8ab7..d067ec61d 100644 --- a/docs/esp8266/tutorial/intro.rst +++ b/docs/esp8266/tutorial/intro.rst @@ -1,3 +1,5 @@ +.. _intro: + Getting started with MicroPython on the ESP8266 =============================================== -- cgit v1.2.3 From 3e5534caf75b9c7e56ebcb005109e004d466b280 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 7 Aug 2016 22:41:34 +0300 Subject: docs/esp8266/intro: Focus on hazards of unearthed power wrt electronics. --- docs/esp8266/tutorial/intro.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs/esp8266/tutorial/intro.rst') diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst index d067ec61d..8c356b913 100644 --- a/docs/esp8266/tutorial/intro.rst +++ b/docs/esp8266/tutorial/intro.rst @@ -116,12 +116,11 @@ after it, here are troubleshooting recommendations: 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.) `_ + - at the very least, and may lead to electrical devices breakdown. So, you are + advised to avoid using unearthed power connections when working with ESP8266 + and other boards. 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 -- cgit v1.2.3