Merge tag 'v1.8.1' into parse-bytecode

Many ESP8266 improvements, enhanced WebREPL, and support for STM32L4 MCUs

This release brings general improvements and bug fixes, and some new
features.  There is now a uerror module for consistent errno handling
across ports, as well as textual names of OS errors that are printed when
an OSError is raised.  There is support for frozen packages, via both
frozen scripts and frozen bytecode.  WebREPL on the ESP8266 is greatly
improved with many bug fixes and now supports an unlimited (or very large)
number of reconnects.  The os module on the ESP8266 now has rename, chdir,
getcwd and stat.  The unix port now includes the ussl module by default.
The stmhal port has support for STM32L4 MCUs including the STM32L476
Discovery board and the LimiFrog board.

README:
- add explicit note that subdirs contain more READMEs
- add "make deplibs" to quick build section
- "quick build": Use "make axtls" after all

CODECONVENTIONS.md:
- describe git commit messages conventions

py core:
- obj: add warning note about get_array return value and GC blocks
- objstr: binary type of str/bytes for buffer protocol is 'B'
- runtime: properly handle passing user mappings to ** keyword args
- repl: if there're no better alternatives, try to complete "import"
- mpz: fix bug with overflowing C-shift in division routine
- mpz: do Python style division/modulo within bignum divmod routine
- mpz: fix mpn_div so that it doesn't modify memory of denominator
- vstr: vstr_null_terminated_str(): Extend string by at most one byte
- vstr: change allocation policy, +16 to requested size, instead of *2
- add mperrno.h file with uPy defined errno constants
- add uerrno module, with errno constants and dict
- parse: add uerrno to list of modules to look for constants in
- mperrno: add EAFNOSUPPORT definition
- repl: fix handling of backslash in quotes when checking continuation
- gc: gc_dump_alloc_table(): Show byte/str and (byte)array objects
- gc: make (byte)array type dumping conditional on these types being enabled
- gc: use '=' char for tail blocks when dumping heap
- mperrno: add some more MP_Exxx constants, related to networking
- moduerrno: add more constants to the errno module
- add mp_errno_to_str() and use it to provide nicer OSError msgs
- objfloat, py/modmath: ensure M_PI and M_E defined
- emitglue: fix build on AArch64 (ARMv8, etc.) related to loading .mpy files
- objexcept: don't convert errno to str in constructor, do it in print
- moduerrno: add EACCES, pretty common error on Unix
- gc: gc_dump_alloc_table(): dump heap offset instead of actual address
- objstr: make dedicated splitlines function, supporting diff newlines
- objstringio: add TODO comment about avoiding copying on .getvalue()
- modstruct: raise ValueError on unsupported format char
- stream: support both "exact size" and "one underlying call" operations
- declare constant data as properly constant
- stream: add mp_stream_close() helper function
- mphal.h: provide default prototypes for mp_hal_delay_us/mp_hal_ticks_us
- rework frozen modules support to support packages
- objstr: implement str.center()
- allow to stat and import frozen mpy files using new frozen "VFS"
- makeqstrdata.py: allow to have double-quote characters in qstrs
- objnamedtuple: allow passing field names as a tuple
- moduerrno: add EEXIST, EISDIR, ECONNREFUSED
- modstruct: allow to have "0s" in struct format

extmod:
- modlwip: convert errno's to use MP_Exxx symbols
- modlwip: rework how Python accept callback is called
- when including extmod headers, prefix path with extmod/
- modwebsocket: add close() method
- modwebrepl: add close() method
- moduos_dupterm: dumpterm subsystem is responsible for closing stream
- modussl: make more compatible with non-default obj representations
- machine_i2c: redo mp_hal_pin macros to use open_drain and od_low
- virtpin: initial implementation of open-ended C-level Pin interface
- vfs_fat: replace text error messages by POSIX error numbers
- vfs_fat: add chdir() method
- vfs_fat: add getcwd() method
- vfs_fat: add vfs.stat() method
- add machine time_pulse_us function (at C and Python level)
- machine: add MICROPY_PY_MACHINE_PULSE config for time_pulse_us

lib:
- timeutils/timeutils: timeutils_mktime may accept negative time values

drivers:
- cc3000: rename timeval to cc3000_timeval, to avoid clash
- add C-level function to read DHT11 and DHT22 devices
- display/ssd1306: update SSD1306_SPI to work with new API

tools:
- make-frozen.py: properly escape hex chars when making C strings
- make-frozen.py: quick fix to support package-modules
- mpy-tool.py: add checks for critical configuration vars
- make-frozen.py: update for latest changes in frozen modules support
- mpy-tool.py: include .py extension in frozen filename
- mpy-tool.py: don't strip directories from the frozen source name
- upgrade upip to 0.7: SSL cert warning, use uerrno, better usage message

tests:
- run-tests: factor out list of supported external boards
- disable memoryview tests that overflow int conversion
- basics/string_splitlines: reinstate feature test for splitlines
- struct1: add testcase for an unknown type char
- add testcase for str.center()
- extmod/vfs_fat_ramdisk: add testcases for chdir(), getcwd()
- misc/recursive_iternext.py: increase depth N from 1000 to 2000
- misc/recursive_iternext.py: provide more fine-grained selection of N
- pyb/rtc: make RTC test on pyboard more reliable by calling init()

mpy-cross:
- add -s option to specify the embedded source filename

unix port:
- mphalport: add mp_hal_delay_us() for consistency with other ports
- enable uerrno module
- add ability to include frozen bytecode in the build
- mpconfigport_coverage.h: add dedicated config file for coverage build
- unix_mphal: implement mp_hal_ticks_us()
- support frozen packages
- Makefile: nanbox build is not compatible with modussl, disable
- enable "ussl" module
- mpconfigport.mk: document MICROPY_STANDALONE make-level option
- Makefile: "make axtls": automatically fetch submodules if missing

windows port:
- enable multi-processor compilation for msvc

stmhal port:
- l4: adapt DMA to be able to support STM32L4 MCU series
- l4: adapt startup code, clock configuration and interrupts
- l4: make CCM/DTCM RAM start-up conditional on MCU type
- l4: add support for machine.sleep on STM32L4 MCUs
- dma: make DAC DMA descriptors conditional on having a DAC
- add board files for LIMIFROG board
- for LIMIFROG board, add early-init function to get to DFU mode
- dma: fix builds for boards with an F4 or F7 but no DAC
- sdcard: fix initialisation of DMA TX so that writes work
- can: allow to get existing CAN obj if constructed without args
- fix clock configuration for STM32L476-discovery; also add I2C2
- convert to use internal errno symbols; enable uerrno module
- for network drivers, convert to use MP_Exxx errno symbols
- led: allow LEDs to be in PWM mode with TIM1 and channels 1-4
- i2c: expose I2CHandle3 for use by custom C code
- sdcard: allow to do unaligned read-from/write-to SD card
- support frozen packages using .mpy files
- moduos: getcwd(): use mp_obj_new_exception_arg1()
- dac: add DAC deinit() method
- uart: fix wrong baudrate calculation for stm32l4 series

esp8266 port:
- scripts/: remove use of pin.PULL_NONE
- scripts/inisetup: don't start WebREPL on boot in master branch
- scripts/: add fill() to NeoPixel
- scripts/webrepl: add optional password argument to webrepl.start()
- scripts/webrepl: add start_foreground() method
- main: bump heap size to 28K
- mpconfigport: reduce various parser-related allocation params
- help: add "sta_if.active(True)" command
- convert to use new MP_Exxx errno symbols
- enable uerrno module, weak linked also as errno
- change to use internal errno's
- moduos.c: addition of the rename method to module uos
- scripts/port_diag: add network diagnostic output
- scripts/webrepl_setup: show password placeholder char
- scripts/webrepl_setup: add max password length check
- README: add a very first start section
- add APA102 serial individually controllable LEDs support
- enable collections.OrderedDict
- main: update _boot module loading for recent frozen modules refactors
- scripts/port_diag: dump network interface IP settings
- esp_mphal: fix NLR buffer leak in call_dupterm_read()
- esp_mphal: handle Ctrl+C from dupterm (e.g. WebREPL)
- esp_mphal: mp_uos_dupterm_deactivate() may raise exception
- add mp_hal_pin_input() and mp_hal_pin_output() functions
- modpybspi: configure pins when initialising an SPI object
- xtirq: add xtirq.h for controlling xtensa irqs
- ets_alt_task: don't run ets_loop_iter if irqs are disabled
- modmachine: add disable_irq and enable_irq functions
- enable DHT C-level driver
- add dht.py script for high-level control of DHT11/DHT22 sensor
- Makefile: document "disable" value for UART_OS
- modnetwork: scan() is only supported by STA when it's enabled
- modnetwork: protect scan() callback against memory errors
- modnetwork: allow to press ctrl-C while scan() is running
- uart: properly initialise UART0 RXD pin in uart_config
- moduos: add chdir() and getcwd() functions
- scripts/ntptime: allow to override NTP server
- modmachine: add machine.time_pulse_us function
- enable MICROPY_PY_IO_FILEIO to get compliant text/binary streams
- moduos.c: add stat() to the module uos of esp8266
- rtc: set RTC user memory length to 0 on first boot
- provide a dedicated variable to disable ets_loop_iter
- modpybrtc: handle RTC overflow

docs:
- machine.UART: filter out unimplemented UART methods from esp8266 docs
- esp8266/quickref: new way to get MAC address
- esp8266/quickstart: remove i2c examples with stop=False
- ustruct: describe supported type codes
- ussl: add basic description of axTLS-based modussl
- esp8266: Include ussl module in the docs
- machine: make disable_irq and enable_irq docs available for all
- library/machine: add documentation for machine.time_pulse_us
- math, cmath: add port availability information
- library/index: add intro paragraph regarding availability of modules
- README: add some hints for PDF docs generation
- wipy/tutorial: add note about screen key bindings on OS X
- esp8266/quickref: update WebREPL section for 1.8.1 release
- esp8266: fix ESP8266 Network tutorial
- esp8266/quickref: use local image of Adafruit Huzzah board
- esp8266/general: add note about RTC overflow

travis:
- install gcc-arm-none-eabi with --force-yes for now

5 files changed, 59 insertions, 29 deletions

diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst
index f996068d0..313e6074c 100644
--- a/docs/esp8266/general.rst
+++ b/docs/esp8266/general.rst
@@ -6,8 +6,8 @@ ESP8266 is a popular WiFi-enabled System-on-Chip (SoC) by Espressif Systems.
 Multitude of boards
 -------------------
 
-There are multitude of modules and boards from different sources which carry
-ESP8266 chip. MicroPython tries to provide a generic port which would run on
+There are a multitude of modules and boards from different sources which carry
+the ESP8266 chip. MicroPython tries to provide a generic port which would run on
 as many boards/modules as possible, but there may be limitations. Adafruit
 Feather HUZZAH board is taken as a reference board for the port (for example,
 testing is performed on it). If you have another board, please make sure you
@@ -18,13 +18,13 @@ To make a generic ESP8266 port and support as many boards as possible,
 following design and implementation decision were made:
 
 * GPIO pin numbering is based on ESP8266 chip numbering, not some "logical"
-  numbering of a particular board. Please have manual/pin diagram of your board
-  handy to find correspondce between your board pins and actual ESP8266 pins.
+  numbering of a particular board. Please have the manual/pin diagram of your board
+  at hand to find correspondence between your board pins and actual ESP8266 pins.
   We also encourage users of various boards to share this mapping via MicroPython
   forum, with the idea to collect community-maintained reference materials
   eventually.
 * All pins which make sense to support, are supported by MicroPython
-  (for example, we don't expose pins which are used to connect SPI flash
+  (for example, pins which are used to connect SPI flash
   are not exposed, as they're unlikely useful for anything else, and
   operating on them will lead to board lock-up). However, any particular
   board may expose only subset of pins. Consult your board reference manual.
@@ -37,10 +37,10 @@ Technical specifications and SoC datasheets
 
 The datasheets and other reference material for ESP8266 chip are available
 from the vendor site: http://bbs.espressif.com/viewtopic.php?f=67&t=225 .
-The are primary reference for the chip technical specifications, capabilities,
+They are the primary reference for the chip technical specifications, capabilities,
 operating modes, internal functioning, etc.
 
-For your convinience, some of technical specifications are provided below:
+For your convenience, some of technical specifications are provided below:
 
 * Architecture: Xtensa lx106
 * CPU frequency: 80MHz overclockable to 160MHz
@@ -64,18 +64,18 @@ Boot process
 On boot, MicroPython EPS8266 port executes ``_boot.py`` script from internal
 frozen modules. It mounts filesystem in FlashROM, or if it's not available,
 performs first-time setup of the module and creates the filesystem. This
-part of boot process is considered fixed, and not available for customization
+part of the boot process is considered fixed, and not available for customization
 for end users (even if you build from source, please refrain from changes to
 it; customization of early boot process is available only to advanced users
 and developers, who can diagnose themselves any issues arising from
 modifying the standard process).
 
-Once filesystem is mounted, ``boot.py`` is executed from it. The standard
+Once the filesystem is mounted, ``boot.py`` is executed from it. The standard
 version of this file is created during first-time module set up and by
-defaults starts up a WebREPL daemon to handle incoming connections. This
+default starts up a WebREPL daemon to handle incoming connections. This
 file is customizable by end users (for example, you may want to disable
 WebREPL for extra security, or add other services which should be run on
-module start-up). But keep in mind that incorrect modifications to boot.py
+a module start-up). But keep in mind that incorrect modifications to boot.py
 may still lead to boot loops or lock ups, requiring to reflash a module
 from scratch.
 
@@ -89,5 +89,14 @@ the following in ``main.py``::
     import my_app
     my_app.main()
 
-This will allow to keep structure of your application clear, as well as
+This will allow to keep the structure of your application clear, as well as
 allow to install multiple applications on a board, and switch among them.
+
+
+Real-time clock
+---------------
+
+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.
diff --git a/docs/esp8266/img/adafruit_products_pinoutstop.jpg b/docs/esp8266/img/adafruit_products_pinoutstop.jpg
new file mode 100644
index 000000000..655e27aee
--- /dev/null
+++ b/docs/esp8266/img/adafruit_products_pinoutstop.jpg
diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst
index bfded9bea..779248369 100644
--- a/docs/esp8266/quickref.rst
+++ b/docs/esp8266/quickref.rst
@@ -3,7 +3,7 @@
 Quick reference for the ESP8266
 ===============================
 
-.. image:: https://learn.adafruit.com/system/assets/assets/000/028/689/medium640/adafruit_products_pinoutstop.jpg
+.. image:: img/adafruit_products_pinoutstop.jpg
     :alt: Adafruit Feather HUZZAH board
     :width: 640px
 
@@ -43,7 +43,7 @@ The ``network`` module::
     wlan.scan()             # scan for access points
     wlan.isconnected()      # check if the station is connected to an AP
     wlan.connect('essid', 'password') # connect to an AP
-    wlan.mac()              # get the interface's MAC adddress
+    wlan.config('mac')      # get the interface's MAC adddress
     wlan.ifconfig()         # get the interface's IP/netmask/gw/DNS addresses
 
     ap = network.WLAN(network.AP_IF) # create access-point interface
@@ -199,9 +199,6 @@ The I2C driver is implemented in software and works on all pins::
     buf = bytearray(10)     # create a buffer with 10 bytes
     i2c.writeto(0x3a, buf)  # write the given buffer to the slave
 
-    i2c.readfrom(0x3a, 4, stop=False) # don't send a stop bit after reading
-    i2c.writeto(0x3a, buf, stop=False) # don't send a stop bit after writing
-
 Deep-sleep mode
 ---------------
 
@@ -274,31 +271,55 @@ For low-level driving of a NeoPixel::
     import esp
     esp.neopixel_write(pin, grb_buf, is800khz)
 
+APA102 driver
+-------------
+
+Use the ``apa102`` module::
+
+    from machine import Pin
+    from apa102 import APA102
+
+    clock = Pin(14, Pin.OUT)     # set GPIO14 to output to drive the clock
+    data = Pin(13, Pin.OUT)      # set GPIO13 to output to drive the data
+    apa = APA102(clock, data, 8) # create APA102 driver on the clock and the data pin for 8 pixels
+    apa[0] = (255, 255, 255, 31) # set the first pixel to white with a maximum brightness of 31
+    apa.write()                  # write data to all pixels
+    r, g, b, brightness = apa[0] # get first pixel colour
+
+For low-level driving of an APA102::
+
+    import esp
+    esp.apa102_write(clock_pin, data_pin, rgbi_buf)
+
 WebREPL (web browser interactive prompt)
 ----------------------------------------
 
 WebREPL (REPL over WebSockets, accessible via a web browser) is an
 experimental feature available in ESP8266 port. Download web client
-from https://github.com/micropython/webrepl , and start daemon using::
+from https://github.com/micropython/webrepl (hosted version available
+at http://micropython.org/webrepl), and start the daemon on a device
+using::
 
     import webrepl
     webrepl.start()
 
-(Release version will have it started on boot by default.)
+(Release versions have it started on boot by default.)
 
 On a first connection, you will be prompted to set password for future
 sessions to use.
 
 The supported way to use WebREPL is by connecting to ESP8266 access point,
 but the daemon is also started on STA interface if it is active, so if your
-routers is set up and works correctly, you may also use it while connecting
-to your normal Internet access point (use ESP8266 AP connection method if
-face any issues).
+router is set up and works correctly, you may also use WebREPL while connected
+to your normal Internet access point (use the ESP8266 AP connection method
+if you face any issues).
 
 WebREPL is an experimental feature and a work in progress, and has known
-issues. There's also provision to transfer (both upload and download)
-files over WebREPL connection, but it has unstable status (be ready to
-reboot a module in case of issues). It still may be a practical way to
+issues.
+
+There's also provision to transfer (both upload and download)
+files over WebREPL connection, but it has even more experimental status
+than the WebREPL terminal mode. It is still a practical way to
 get script files onto ESP8266, so give it a try using ``webrepl_cli.py``
-from the repository above. See forum for other community-supported
-alternatives to transfer files to ESP8266.
+from the repository above. See the MicroPython forum for other
+community-supported alternatives to transfer files to ESP8266.
diff --git a/docs/esp8266/tutorial/network_basics.rst b/docs/esp8266/tutorial/network_basics.rst
index 02a705485..42aed5664 100644
--- a/docs/esp8266/tutorial/network_basics.rst
+++ b/docs/esp8266/tutorial/network_basics.rst
@@ -62,7 +62,7 @@ connect to your WiFi network::
             print('connecting to network...')
             sta_if.active(True)
             sta_if.connect('<essid>', '<password>')
-            while not network.isconnected():
+            while not sta_if.isconnected():
                 pass
         print('network config:', sta_if.ifconfig())
 
diff --git a/docs/esp8266/tutorial/network_tcp.rst b/docs/esp8266/tutorial/network_tcp.rst
index 0a1cca445..80a494721 100644
--- a/docs/esp8266/tutorial/network_tcp.rst
+++ b/docs/esp8266/tutorial/network_tcp.rst
@@ -36,7 +36,7 @@ information they hold.
 Using the IP address we can make a socket and connect to the server::
 
     >>> s = socket.socket()
-    >>> s.connect(addr[0][-1])
+    >>> s.connect(addr)
 
 Now that we are connected we can download and display the data::