3 files changed, 39 insertions, 8 deletions
diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst
index 47df80d7ba..e23acb469b 100644
--- a/docs/esp8266/general.rst
+++ b/docs/esp8266/general.rst
@@ -116,9 +116,32 @@ Real-time clock
 RTC in ESP8266 has very bad accuracy, drift may be seconds per minute. As
 a workaround, to measure short enough intervals you can use
 ``utime.time()``, etc. functions, and for wall clock time, synchronize from
-the net using included ``ntpdate.py`` module.
+the net using included ``ntptime.py`` module.
 
 Due to limitations of the ESP8266 chip the internal real-time clock (RTC)
 will overflow every 7:45h.  If a long-term working RTC time is required then
 ``time()`` or ``localtime()`` must be called at least once within 7 hours.
 MicroPython will then handle the overflow.
+
+Sockets and WiFi buffers overflow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Socket instances remain active until they are explicitly closed. This has two
+consequences. Firstly they occupy RAM, so an application which opens sockets
+without closing them may eventually run out of memory. Secondly not properly
+closed socket can cause the low-level part of the vendor WiFi stack to emit
+``Lmac`` errors. This occurs if data comes in for a socket and is not
+processed in a timely manner. This can overflow the WiFi stack input queue
+and lead to a deadlock. The only recovery is by a hard reset.
+
+The above may also happen after an application terminates and quits to the REPL
+for any reason including an exception. Subsequent arrival of data provokes the
+failure with the above error message repeatedly issued. So, sockets should be
+closed in any case, regardless whether an application terminates successfully
+or by an exeption, for example using try/finally::
+
+    sock = socket(...)
+    try:
+        # Use sock
+    finally:
+        sock.close()
diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst
index 67ed0ba67c..711db3fceb 100644
--- a/docs/esp8266/tutorial/intro.rst
+++ b/docs/esp8266/tutorial/intro.rst
@@ -50,12 +50,16 @@ From here, you have 3 main choices
 * Daily firmware builds for 1024kb modules and above.
 * Daily firmware builds for 512kb modules.
 
-The best bet is nearly always to go for the Stable firmware builds.
-An exception to this though is if you have an ESP8266 module with only 512kb
-of onboard storage. You can easily tell by trying to load a Stable firmware 
-build and if you get the error below, then you may have to use the Daily 
-firmware builds for 512kb modules.
-    WARNING: Unlikely to work as data goes beyond end of flash.
+If you are just starting with MicroPython, the best bet is to go for the Stable
+firmware builds. If you are an advanced, experienced MicroPython ESP8266 user
+who would like to follow development closely and help with testing new
+features, there are daily builds (note: you actually may need some
+development experience, e.g. being ready to follow git history to know
+what new changes and features were introduced).
+
+Support for 512kb modules is provided on a feature preview basis. For end
+users, it's recommended to use modules with flash of 1024kb or more. As
+such, only daily builds for 512kb modules are provided.
 
 Deploying the firmware
 ----------------------
@@ -161,7 +165,9 @@ after it, here are troubleshooting recommendations:
 
 * If lower baud rate didn't help, you may want to try older version of
   esptool.py, which had a different programming algorithm::
+
     pip install esptool==1.0.1
+
   This version doesn't support ``--flash_size=detect`` option, so you will
   need to specify FlashROM size explicitly (in megabits). It also requires
   Python 2.7, so you may need to use ``pip2`` instead of ``pip`` in the
@@ -176,8 +182,10 @@ after it, here are troubleshooting recommendations:
 * 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.
 
diff --git a/docs/esp8266/tutorial/powerctrl.rst b/docs/esp8266/tutorial/powerctrl.rst
index 9e44339c86..3502624ab5 100644
--- a/docs/esp8266/tutorial/powerctrl.rst
+++ b/docs/esp8266/tutorial/powerctrl.rst
@@ -22,7 +22,7 @@ processing power, at the expense of current consumption::
     160000000
 
 You can change to the higher frequency just while your code does the heavy
-processing and then change back when its finished.
+processing and then change back when it's finished.
 
 Deep-sleep mode
 ---------------