Merge tag 'v1.8' into parse-bytecode

First general release of ESP8266 port, and support for frozen bytecode

This release marks the first general release of official ESP8266 support
within the MicroPython code base.  The ESP8266 port has many improvements
and additions, including: websocket and webrepl modules, deep-sleep mode,
reading on UART, enhanced I2C support, enhanced network configuration,
full sequence of start-up scripts (built-in _boot.py, boot.py and
main.py), improved filesystem support with automatic flash-size detection
as well as documentation and a tutorial.

Known issues with ESP8266 port are:
- Basic SSL support is available but it works only with relatively short
  data lengths (a few kilobytes).
- WebREPL over SSL is not supported.
- Only 5 or so WebREPL sessions in succession can be started (including
  file transfer sessions), after that the board requires a hard reset.
- File transfer over WebREPL has issues with large files (above a few
  tens of kilobytes).
- By design, only one concurrent WebREPL connection is supported.
- Soft reset doesn't reset the network stack.

In addition to ESP8266 support, this release brings frozen bytecode
which allows to compile bytecode offline and link it into the firmware,
completely eliminating the need for compilation (and the associated
RAM usage) at runtime.  Basic async/await syntax is now supported, and
qstrs are now auto-generated in the build system.

A detailed list of changes is given below.

README:
- explicitly point to required dependencies section
- promote "docs" and "tests" to "major components"
- mention support "async" keyword from Python 3.5

ACKNOWLEDGEMENTS:
- add list of 842 backers from the ESP8266 campaign

py core:
- modbuiltins: add comment about setting "_" special var
- add async/await/async for/async with syntax
- fix constant folding and inline-asm to work with new async grammar
- emitglue: move typedef of mp_raw_code_t from .c to .h file
- emitglue: make mp_raw_code_t* arguments constant pointers
- makeqstrdata: factor out some code to functions that can be reused
- add ability to have frozen persistent bytecode from .mpy files
- makeqstrdata: add more names for escaped chars and esc non-printable
- simplify "and" action within parser by making ident-rules explicit
- makeqstrdata: fix rendering of qstrs that have non-printable ASCII
- makeqstrdata: add special case to handle \n qstr
- declare help, input, open builtins in core
- map: change hash-table allocation policy to be less aggressive
- makeqstrdefs: add script to automate extraction of qstr from sources
- frozenmod: pass the source name of the frozen module to the lexer
- rework QSTR extraction to work in simple and obvious way
- divide "split" and "cat" phases of qstr extraction for better efficiency
- fix bug passing a string as a keyword arg in a dict
- move call_function_*_protected() functions to py/ for reuse
- makeqstrdefs.py: windows compatibility
- obj.h: when constructing a small-int cast to mp_uint_t for bit-shift
- emitnative: use MP_OBJ_NEW_SMALL_INT instead of manual bit shifting
- vm: "yield from" didn't handle MP_OBJ_STOP_ITERATION optimization
- modio: rename module name to "uio" for consistency with other modules
- modcollections: rename module name have "u" prefix for consistency

extmod:
- add initial framebuf module
- add generic machine.I2C class, with bit-bang I2C
- machine_i2c: fix I2C reading by sending ack/nack at end of byte
- machine_i2c: implement I2C memory reading/writing
- moduos_dupterm: don't swallow exceptions in dupterm's read()/write()
- modlwip: lwip_tcp_receive(): Properly handle EOF for non-blocking sock
- modlwip: more debug messages for various edge conditions
- fsusermount: in mount/mkfs, deregister VFS object on error
- modlwip: lwip_tcp_send(): full error handling
- modlwip: lwip_tcp_receive(): full error handling
- modlwip: add ability to run callback on "recv" and "accept" events
- machine_i2c: allow mp_hal_pin_obj_t to be any type, not a ptr
- modlwip: protect recv/accept Python callback against exceptions
- modlwip: workaround esp8266 sendto issue where 1 is returned
- modlwip: add print_pcbs() debug function
- modwebsocket: handle CLOSE control frame
- modussl: throw Python exceptions in case of errors
- modussl: support server-side SSL sockets
- modussl: SSL_OK from ssl_read() means "no user data so far"
- modwebrepl: module to handle WebREPL protocol
- modwebrepl: initial implementation of "get file" operation
- modwebrepl: keep reading data when there's something to read
- modwebrepl: GET_FILE: Send length-prefix chunk with one write()
- modwebrepl: add rate-limiting workaround for broken network drivers
- modwebrepl: set debugging by default to off
- modwebrepl: add support for password
- modlwip: implement sendall() method for TCP sockets
- fix typo of macro that detects if float is enabled

lib:
- utils/printf: rework overriding printer of DEBUG_printf()
- utils/pyexec: condition-out GC calls from pyexec
- utils/pyhelp: extract implementation of help(obj) to a library function
- axtls: update to the latest upstream, fix reported MacOSX build issue

drivers:
- add SSD1306 OLED driver, with I2C and SPI interfaces

tools:
- mpy-tool.py: new tool to work with .mpy files; currently it can freeze them
- mpy-tool.py: add support for Python 2.7

tests:
- add 6 tests for async await/for/with
- add .exp files for async tests, so they can run with Python 3.4
- fix dict1.py so it doesn't rely on the order of dict elems
- extmod: move split-on-empty-match tests to a separate test file
- add testcase for yielding from a stopped generator
- run-bench-tests: process tests in alphabetical order
- update for _io/_collections module having been renamed

minimal port:
- add example of frozen persistent bytecode (.mpy file)
- disable async/await syntax

unix port:
- build with MICROPY_PY_UHASHLIB_SHA1 if already building with axTLS
- make sure build dir exists before accessing it for freezing upip
- Makefile: make install more compatible (BSD, etc.)

windows port:
- msvc: implement automatic qstr generation using makeqstrdefs

stmhal port:
- implement basic C-level pin HAL
- use new generic I2C object in machine module
- enable framebuf module
- properly handle RTS/CTS flow control for buf/unbuf transfers
- add Makefile option FROZEN_MPY_DIR to support frozen bytecode
- for frozen bytecode generation, add dependency of qstr file
- l4: add CMSIS files to support STM32L476
- l4: add basic STM32L4xx HAL files
- l4: adapt UART HAL to avoid 64-bit integer division
- update HALCOMMITS due to change to hal
- l4: add board definition files for STM32L476DISC
- l4: add line to Makefile for building L4 series
- l4: modify adc.c to add support for STM32L4 series
- l4: modify uart.c to support L4 MCU
- l4: modify usbd_conf.c to support L4 MCU
- l4: modify rtc.c to support L4 MCU
- l4: modify timer.c to support L4 MCU
- fix machine.unique_id() function to work for all MCUs
- l4: modify mphalport to support L4 MCU
- l4: modify flash.c and storage.c to support L4 MCU
- l4: add support for external interrupts/events
- accel: raise an exception if the accel couldn't be initialised
- use pyhelp_print_obj function
- change i2c.scan() method to scan addresses 0x08-0x77
- fix typo of macro that detects if float is enabled

cc3200 port:
- use pyhelp_print_obj function
- change i2c.scan() method to scan addresses 0x08-0x77
- disable async/await syntax

esp8266 port:
- enable websocket module
- modnetwork: .config(): Check interface whose config is requested
- modnetwork: .config(): Add "authmode" param
- modnetwork: .config(): Add "password" param (W/O)
- add Python modules for initial configuration
- scripts/inisetup.py: set WPA/WPA2 AP mode with a predefined password
- protect modpyb.h header file from multiple inclusions
- implement basic C-level pin HAL
- switch from using custom I2C driver to generic extmod one
- enable framebuf module
- in callback helpers, pop nlr_buf on successful call
- esp_mphal: don't swallow exceptions in dupterm's read()/write()
- esp_mphal: call_dupterm_read(): Fix order of deactivating on EOF
- remove pin_id field from C pin object
- add dummy entries for non-existing pins to simplify pin logic
- add hard IRQ callbacks for pin change on GPIO0-15
- separate 1-wire timing funcs from Python module to save iRAM
- switch integer arith routines to BootROM
- scripts/port_diag.py: module to collect diagnostic info
- enable input() builtin
- scripts/_boot: mount block device on "" instead of "/"
- moduos: add uos.mkdir function
- modmachine: add reset_cause() function
- adapt port to use new auto-qstr generation
- moduos: add dupterm_notify() function
- esp_mphal: protect dupterm_task_handler() from recursive exec
- README.md: update feature list for current state of affairs
- modesp: allow esp.deepsleep to take 2nd arg for RF wake opt
- scripts/flashbdev: use all available space in 1MB FlashROM for FS
- modesp: add flash_size() function
- scripts: don't try to create filesystem on 512KB devices or less
- modnetwork: .config(): Add "channel" param
- scripts/flashbdev: disable debug output/checks
- scripts/_boot: print notice when initial setup is executed
- scripts/flashbdev: correct bootloader flash size to match real size
- modnetwork: .config(): Add "hidden ESSID" param
- implement basic deep-sleep capabilities
- add uart_rx_wait and uart_rx_char functions
- implement UART.read functionality
- uart: remove obsolete UART rx buffering code
- esp_mphal: remove mp_hal_feed_watchdog
- convert mp_hal_pin_obj_t from pin ptr to simple integer
- allow GPIO16 to be used as a pin in the uPy pin HAL
- change software SPI driver to use general pin HAL
- scripts/websocket_helper: module encapsulating handshake sequences
- scripts/websocket_helper: disable debug output
- scripts/webrepl: webREPL based on C-level websocket object
- scripts/webrepl: convert to persistent daemon
- scripts/webrepl: don't start on import
- scripts/webrepl: allow to override port
- scripts/webrepl: print connection address
- scripts/webrepl: print client address for incoming connections
- scripts/flashbdev: use all available Flash for filesystem
- scripts/webrepl: add "ws://" to "daemon started at" message
- Makefile: add target to build axTLS
- esp8266.ld: put axTLS to FlashROM
- Makefile: override abort() when building axtls
- axtls_helpers: helper/wrapper functions for axTLS
- tests/onewire.py: don't run test on import
- Makefile: support linking with axTLS built from source
- Makefile: enable "ussl" module; axTLS should be built first using "make axtls"
- move pyb.info() function to esp module and remove pyb module
- move onewire.py, neopixel.py drivers from tests/ to scripts/
- scripts/onewire.py: simplify and improve 1-wire driver
- scripts/neopixel.py: remove test function from neopixel driver
- set suitable values for axtls's RT_MAX_PLAIN_LENGTH & RT_EXTRA
- README: add recently required step of 'make axtls'
- modnetwork: make WLAN.ifconfig() read/write
- help: implement help() builtin
- help: add cheatsheet for basic WiFi configuration
- enable WebREPL file transfer rate limiting
- enable webrepl module
- scripts: move all of initial setup to inisetup module
- scripts/inisetup: create default boot.py in filesystem
- scripts/webrepl: connection ack prompt is now printed by modwebrepl
- scripts/webrepl: switch to using _webrepl object wrapper
- scripts/webrepl: add "first connection" mode to setup password
- README: mention WebREPL
- Makefile: be sure to pass cross-compiling AR when building axtls
- scripts/webrepl_setup: reject too short passwords
- change platform name from ESP8266 to esp8266
- modnetwork: remove deprecated wifi_mode()
- esp_mphal: add ets_esf_free_bufs(), etc. functions
- modesp: add esf_free_bufs() debugging function
- modesp: add malloc() and free() functions
- scripts/inisetup: enable WebREPL auto-start on boot
- modnetwork: remove .mac() method, move to .config("mac")
- scripts/inisetup: update for nic.mac() method being gone
- scripts/neopixel.py: swap red and green in pixel accessor
- modpybpin: use enum+array instead of struct for parsing args
- modpybpin: use None instead of PULL_NONE for no-pull config
- modpybpin: make pin.irq() methods take keyword args
- tutorial: mention that esptool is available via pip
- scripts/ntptime: add simple NTP client

docs:
- esp: enumerate flash access functions
- machine: start to update for esp8266 port
- speed_python: clarify/generalize "Buffers" subsection
- speed_python: generalize "Floating point" subsection
- speed_python: add many more details on memoryviews
- machine: reset_cause() has been implemented for esp8266
- topindex.html: esp8266: Enable quickref/general on the main page
- esp8266/general: start "General information" for esp8266
- esp8266: add info about using deep-sleep mode to quickref
- esp8266/tutorial: add tutorial placeholder page
- ustruct: there's no complete "struct" module, only "ustruct" subset
- esp8266: include usocket module reference
- library/usocket: add link to CPython's socket module
- usocket: socket-specific exceptions are for WiPy only
- usocket: socket.IPPROTO_SEC is WiPy-specific
- usocket: describe address format once at the beginning
- network: esp8266: scan(): add note that bssid is bytes object
- library: group MicroPython-specific modules under separate heading
- library/index: move WiPy "micro-libraries" under corresponding heading
- library/index: esp8266 has the same set of stdlibs as pyboard/unix
- module "time" is actually "utime"
- library/index: make single section for "micro-ified" modules
- library/index: order sections from the most to least standard modules
- Makefile: default BUILDDIR based on MICROPY_PORT
- library: "os" module is actually "uos"
- fix uos and utime heading underlines to be the correct length
- library/utime: add more time functions for unix and esp8266 ports
- utime: describe time() peculiarities in MicroPython
- utime: describe sleep() peculiarities in MicroPython
- library: consistently use admonitions for CPython differences
- ubinascii: clean up grammar
- network: esp8266: Add wlan.ifconfig() method
- network: esp8266: Describe wlan.config() method
- make the short port names in the port/version sidebar lowercase
- esp8266: update quickref to reflect changes to 1-wire and NeoPixel
- library/utime: elaborate on epochs and calendar time maintenance
- esp8266/quickref: add info about WebREPL
- ustruct: document pack_into(), unpack_from()
- sys: document sys.modules
- ustruct: fix argument formatting
- sys: remove port-specific details from description of stdin/out/err
- sys: clarify description of sys.exit()
- sys: clean up print_exception() description
- sys: describe sys.implementation
- sys: describe sys.maxsize
- sys: describe sys.platform is port-neutral manner
- add _collections module reference
- add _io module reference
- _io and _collections were renamed to have standard "u" prefix
- library/machine.I2C: update to reflect ESP8266 implementation
- esp8266/general: webREPL is described in quickref for now
- esp8266/general: add more points to "Multitude of boards" section
- esp8266/general: fix list formatting
- esp8266/general: add techspec section
- esp8266/general: add "Boot process" section
- esp8266_contents: reference general and tutorial docs
- network: esp8266: MAC address is set via .config() method
- esp8266: add ESP8266 tutorial
- machine: generalize docs from just WiPy to other ports
- machine: move WiPy-specific hardware details to its general reference
- machine: more generic description of sleep's, WiPy details to its genref
- machine: idle() description generalization
- library/machine.Pin: update pin docs to reflect ESP8266 support
- esp8266/tutorial: update pins tutorial to reflect changes in API

examples:
- http_server_ssl.py: add HTTPS server example

18 files changed, 832 insertions, 352 deletions

diff --git a/docs/library/esp.rst b/docs/library/esp.rst
index 040d62f769..34d3c278d9 100644
--- a/docs/library/esp.rst
+++ b/docs/library/esp.rst
@@ -39,3 +39,9 @@ Functions
 .. function:: flash_id()
 
     Read the device ID of the flash memory.
+
+.. function:: flash_read(byte_offset, length_or_buffer)
+
+.. function:: flash_write(byte_offset, bytes)
+
+.. function:: flash_erase(sector_no)
diff --git a/docs/library/index.rst b/docs/library/index.rst
index 47cd2eeb8e..03e6502d95 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -1,59 +1,88 @@
 MicroPython libraries
 =====================
 
-Functionality specific to the MicroPython implementation is available in
-the following library.
+The following standard Python libraries are built in to MicroPython.
 
-.. toctree::
-   :maxdepth: 1
+For additional libraries, please download them from the `micropython-lib repository
+<https://github.com/micropython/micropython-lib>`_.
 
-   micropython.rst
+Python standard libraries and micro-libraries
+---------------------------------------------
 
-Python standard libraries
--------------------------
+The following standard Python libraries have been "micro-ified" to fit in with
+the philosophy of MicroPython.  They provide the core functionality of that
+module and are intended to be a drop-in replacement for the standard Python
+library.
 
-The following standard Python libraries are built in to MicroPython.
+.. only:: not port_unix
 
-For additional libraries, please download them from the `micropython-lib repository
-<https://github.com/micropython/micropython-lib>`_.
+    The modules are available by their u-name, and also by their non-u-name.  The
+    non-u-name can be overridden by a file of that name in your package path.
+    For example, ``import json`` will first search for a file ``json.py`` or
+    directory ``json`` and load that package if it is found.  If nothing is found,
+    it will fallback to loading the built-in ``ujson`` module.
 
 .. only:: port_unix
 
     .. toctree::
        :maxdepth: 1
-    
+
        cmath.rst
        gc.rst
        math.rst
-       os.rst
-       struct.rst
+       select.rst
        sys.rst
-       time.rst
+       ubinascii.rst
+       ucollections.rst
+       uhashlib.rst
+       uheapq.rst
+       uio.rst
+       ujson.rst
+       uos.rst
+       ure.rst
+       usocket.rst
+       ustruct.rst
+       utime.rst
+       uzlib.rst
 
 .. only:: port_pyboard
 
     .. toctree::
        :maxdepth: 1
-    
+
        cmath.rst
        gc.rst
        math.rst
-       os.rst
        select.rst
-       struct.rst
        sys.rst
-       time.rst
+       ubinascii.rst
+       ucollections.rst
+       uhashlib.rst
+       uheapq.rst
+       uio.rst
+       ujson.rst
+       uos.rst
+       ure.rst
+       usocket.rst
+       ustruct.rst
+       utime.rst
+       uzlib.rst
 
 .. only:: port_wipy
 
     .. toctree::
        :maxdepth: 1
-    
+
        gc.rst
-       os.rst
        select.rst
        sys.rst
-       time.rst
+       ubinascii.rst
+       ujson.rst
+       uos.rst
+       ure.rst
+       usocket.rst
+       ussl.rst
+       utime.rst
 
 .. only:: port_esp8266
 
@@ -62,52 +91,35 @@ For additional libraries, please download them from the `micropython-lib reposit
 
        gc.rst
        math.rst
-       struct.rst
        sys.rst
-       time.rst
-
-Python micro-libraries
-----------------------
+       ubinascii.rst
+       ucollections.rst
+       uhashlib.rst
+       uheapq.rst
+       uio.rst
+       ujson.rst
+       uos.rst
+       ure.rst
+       usocket.rst
+       ustruct.rst
+       utime.rst
+       uzlib.rst
+
+
+MicroPython-specific libraries
+------------------------------
 
-The following standard Python libraries have been "micro-ified" to fit in with
-the philosophy of MicroPython.  They provide the core functionality of that
-module and are intended to be a drop-in replacement for the standard Python
-library.
-
-.. only:: not port_unix
-
-    The modules are available by their u-name, and also by their non-u-name.  The
-    non-u-name can be overridden by a file of that name in your package path.
-    For example, ``import json`` will first search for a file ``json.py`` or
-    directory ``json`` and load that package if it is found.  If nothing is found,
-    it will fallback to loading the built-in ``ujson`` module.
-
-.. only:: port_pyboard or port_unix
-
-   .. toctree::
-      :maxdepth: 1
-    
-      ubinascii.rst
-      uctypes.rst
-      uhashlib.rst
-      uheapq.rst
-      ujson.rst
-      ure.rst
-      usocket.rst
-      uzlib.rst
+Functionality specific to the MicroPython implementation is available in
+the following libraries.
 
-.. only:: port_esp8266
+.. toctree::
+   :maxdepth: 1
 
-   .. toctree::
-      :maxdepth: 1
+   machine.rst
+   micropython.rst
+   network.rst
+   uctypes.rst
 
-      ubinascii.rst
-      uctypes.rst
-      uhashlib.rst
-      uheapq.rst
-      ujson.rst
-      ure.rst
-      uzlib.rst
 
 .. only:: port_pyboard
 
@@ -120,18 +132,6 @@ library.
       :maxdepth: 2
 
       pyb.rst
-      network.rst
-
-.. only:: port_wipy
-
-   .. toctree::
-      :maxdepth: 1
-
-      ubinascii.rst
-      ujson.rst
-      ure.rst
-      usocket.rst
-      ussl.rst
 
 .. only:: port_wipy
 
@@ -143,8 +143,6 @@ library.
    .. toctree::
       :maxdepth: 2
 
-      machine.rst
-      network.rst
       wipy.rst
 
 
@@ -158,6 +156,4 @@ library.
    .. toctree::
       :maxdepth: 2
 
-      network.rst
       esp.rst
-      machine.rst
diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst
index aa1caed209..a7e90ca39b 100644
--- a/docs/library/machine.I2C.rst
+++ b/docs/library/machine.I2C.rst
@@ -49,12 +49,15 @@ Constructors
        Construct an I2C object on the given bus.  `bus` can only be 0.
        If the bus is not given, the default one will be selected (0).
 
-Methods
--------
+.. only:: port_esp8266
 
-.. method:: i2c.deinit()
+    .. class:: machine.I2C(scl, sda, \*, freq=400000)
 
-   Turn off the I2C bus.
+       Construct and return a new I2C object.
+       See the init method below for a description of the arguments.
+
+General Methods
+---------------
 
 .. only:: port_wipy
 
@@ -66,48 +69,131 @@ Methods
          - ``baudrate`` is the SCL clock rate
          - ``pins`` is an optional tuple with the pins to assign to the I2C bus.
 
-    .. method:: i2c.readfrom(addr, nbytes)
+.. only:: port_esp8266
+
+    .. method:: i2c.init(scl, sda, \*, freq=400000)
+
+      Initialise the I2C bus with the given arguments:
 
-        Read ``nbytes`` from the slave specified by ``addr``.
-        Returns a ``bytes`` object with the data read.
+         - `scl` is a pin object for the SCL line
+         - `sda` is a pin object for the SDA line
+         - `freq` is the SCL clock rate
 
-    .. method:: i2c.readfrom_into(addr, buf)
+.. method:: i2c.deinit()
 
-        Read into ``buf`` from the slave specified by ``addr``.
-        Returns the number of bytes read.
+   Turn off the I2C bus.
 
-    .. method:: i2c.writeto(addr, buf, \*, stop=True)
+   Availability: WiPy.
 
-        Write ``buf`` to the slave specified by ``addr``. Set ``stop`` to ``False``
-        if the transfer should be continued.
-        Returns the number of bytes written.
+.. method:: i2c.scan()
 
-    .. method:: i2c.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
+   Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of
+   those that respond.  A device responds if it pulls the SDA line low after
+   its address (including a read bit) is sent on the bus.
 
-        Read ``nbytes`` from the slave specified by ``addr`` starting from the memory
-        address specified by ``memaddr``.
-        Param ``addrsize`` specifies the address size in bits.
-        Returns a ``bytes`` object with the data read.
+   Note: on WiPy the I2C object must be in master mode for this method to be valid.
 
-    .. method:: i2c.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
+Primitive I2C operations
+------------------------
 
-        Read into ``buf`` from the slave specified by ``addr`` starting from the memory
-        address specified by ``memaddr``.
-        Param ``addrsize`` specifies the address size in bits.
-        Returns the number of bytes read.
+The following methods implement the primitive I2C master bus operations and can
+be combined to make any I2C transaction.  They are provided if you need more
+control over the bus, otherwise the standard methods (see below) can be used.
 
-    .. method:: i2c.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
+.. method:: i2c.start()
 
-        Write ``buf`` to the slave specified by ``addr`` starting from the
-        memory address specified by ``memaddr``. Param ``addrsize`` specifies the 
-        address size in bits.
-        Set ``stop`` to ``False`` if the transfer should be continued.
-        Returns the number of bytes written.
+   Send a start bit on the bus (SDA transitions to low while SCL is high).
 
-.. method:: i2c.scan()
+   Availability: ESP8266.
+
+.. method:: i2c.stop()
+
+   Send a stop bit on the bus (SDA transitions to high while SCL is high).
+
+   Availability: ESP8266.
+
+.. method:: i2c.readinto(buf)
+
+   Reads bytes from the bus and stores them into `buf`.  The number of bytes
+   read is the length of `buf`.  An ACK will be sent on the bus after
+   receiving all but the last byte, and a NACK will be sent following the last
+   byte.
+
+   Availability: ESP8266.
+
+.. method:: i2c.write(buf)
+
+   Write all the bytes from `buf` to the bus.  Checks that an ACK is received
+   after each byte and raises an OSError if not.
+
+   Availability: ESP8266.
+
+Standard bus operations
+-----------------------
+
+The following methods implement the standard I2C master read and write
+operations that target a given slave device.
 
-   Scan all I2C addresses from 0x01 to 0x7f and return a list of those that respond.
-   Only valid when in master mode.
+.. method:: i2c.readfrom(addr, nbytes)
+
+   Read `nbytes` from the slave specified by `addr`.
+   Returns a `bytes` object with the data read.
+
+.. method:: i2c.readfrom_into(addr, buf)
+
+   Read into `buf` from the slave specified by `addr`.
+   The number of bytes read will be the length of `buf`.
+
+   On WiPy the return value is the number of bytes read.  Otherwise the
+   return value is `None`.
+
+.. method:: i2c.writeto(addr, buf, \*, stop=True)
+
+   Write the bytes from `buf` to the slave specified by `addr`.
+
+   The `stop` argument (only available on WiPy) tells if a stop bit should be
+   sent at the end of the transfer.  If `False` the transfer should be
+   continued later on.
+
+   On WiPy the return value is the number of bytes written.  Otherwise the
+   return value is `None`.
+
+Memory operations
+-----------------
+
+Some I2C devices act as a memory device (or set of registers) that can be read
+from and written to.  In this case there are two addresses associated with an
+I2C transaction: the slave address and the memory address.  The following
+methods are convenience functions to communicate with such devices.
+
+.. method:: i2c.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
+
+   Read `nbytes` from the slave specified by `addr` starting from the memory
+   address specified by `memaddr`.
+   The argument `addrsize` specifies the address size in bits (on ESP8266
+   this argument is not recognised and the address size is always 8 bits).
+   Returns a `bytes` object with the data read.
+
+.. method:: i2c.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
+
+   Read into `buf` from the slave specified by `addr` starting from the
+   memory address specified by `memaddr`.  The number of bytes read is the
+   length of `buf`.
+   The argument `addrsize` specifies the address size in bits (on ESP8266
+   this argument is not recognised and the address size is always 8 bits).
+
+   On WiPy the return value is the number of bytes read.  Otherwise the
+   return value is `None`.
+
+.. method:: i2c.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
+
+   Write `buf` to the slave specified by `addr` starting from the
+   memory address specified by `memaddr`.
+   The argument `addrsize` specifies the address size in bits (on ESP8266
+   this argument is not recognised and the address size is always 8 bits).
+
+   On WiPy the return value is the number of bytes written.  Otherwise the
+   return value is `None`.
 
 Constants
 ---------
@@ -115,3 +201,5 @@ Constants
 .. data:: I2C.MASTER
 
    for initialising the bus to master mode
+
+   Availability: WiPy.
diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst
index 6fa2b170e8..a2e97c87c2 100644
--- a/docs/library/machine.Pin.rst
+++ b/docs/library/machine.Pin.rst
@@ -39,6 +39,21 @@ Usage Model:
     All pin objects go through the pin mapper to come up with one of the
     gpio pins.
 
+.. only:: port_esp8266
+
+   ::
+
+    from machine import Pin
+
+    # create an output pin on GPIO0
+    p0 = Pin(0, Pin.OUT)
+    p0.value(0)
+    p0.value(1)
+
+    # create an input pin on GPIO2
+    p2 = Pin(2, Pin.IN, Pin.PULL_UP)
+    print(p2.value())
+
 Constructors
 ------------
 
@@ -86,6 +101,25 @@ Methods
 
        Get the pin id.
 
+.. only:: port_esp8266
+
+    .. method:: pin.init(mode, pull=None, \*, value)
+
+       Initialise the pin:
+
+         - `mode` can be one of:
+
+            - ``Pin.IN``  - input pin.
+            - ``Pin.OUT`` - output pin in push-pull mode.
+
+         - `pull` can be one of:
+
+            - ``None`` - no pull up or down resistor.
+            - ``Pin.PULL_UP`` - pull up resistor enabled.
+
+         - if `value` is given then it is the output value to set the pin
+           if it is in output mode.
+
 .. method:: pin.value([value])
 
    Get or set the digital logic level of the pin:
@@ -95,17 +129,19 @@ Methods
        anything that converts to a boolean.  If it converts to ``True``, the pin
        is set high, otherwise it is set low.
 
+.. method:: pin([value])
+
+   Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin.
+   See **pin.value** for more details.
+
 .. method:: pin.alt_list()
 
     Returns a list of the alternate functions supported by the pin. List items are
     a tuple of the form: ``('ALT_FUN_NAME', ALT_FUN_INDEX)``
 
-.. only:: port_wipy
-
-    .. method:: pin([value])
+    Availability: WiPy.
 
-       Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin.
-       See **pin.value** for more details.
+.. only:: port_wipy
 
     .. method:: pin.toggle()
 
@@ -155,6 +191,23 @@ Methods
 
             Returns a callback object.
 
+.. only:: port_esp8266
+
+    .. method:: pin.irq(\*, trigger, handler=None)
+
+        Create a callback to be triggered when the input level at the pin changes.
+
+            - ``trigger`` configures the pin level which can generate an interrupt. Possible values are:
+
+                - ``Pin.IRQ_FALLING`` interrupt on falling edge.
+                - ``Pin.IRQ_RISING`` interrupt on rising edge.
+
+              The values can be OR'ed together to trigger on multiple events.
+
+            - ``handler`` is an optional function to be called when the interrupt triggers.
+
+            Returns a callback object.
+
 Attributes
 ----------
 
@@ -166,44 +219,36 @@ Attributes
         led = Pin(Pin.board.GP25, mode=Pin.OUT)
         Pin.board.GP2.alt_list()
 
+    Availability: WiPy.
 
 Constants
 ---------
 
-.. only:: port_wipy
-
-    .. data:: Pin.IN
-
-    .. data:: Pin.OUT
-    
-    .. data:: Pin.OPEN_DRAIN
-
-    .. data:: Pin.ALT
-
-    .. data:: Pin.ALT_OPEN_DRAIN
-
-       Selects the pin mode.
-
-    .. data:: Pin.PULL_UP
-
-    .. data:: Pin.PULL_DOWN
-    
-       Selectes the wether there's pull up/down resistor.
-
-    .. data:: Pin.LOW_POWER
+The following constants are used to configure the pin objects.  Note that
+not all constants are available on all ports.
 
-    .. data:: Pin.MED_POWER
+.. data:: IN
+          OUT
+          OPEN_DRAIN
+          ALT
+          ALT_OPEN_DRAIN
 
-    .. data:: Pin.HIGH_POWER
+   Selects the pin mode.
 
-        Selects the drive strength.
+.. data:: PULL_UP
+          PULL_DOWN
 
-    .. data:: Pin.IRQ_FALLING
+   Selects the whether there is a pull up/down resistor.
 
-    .. data:: Pin.IRQ_RISING
+.. data:: LOW_POWER
+          MED_POWER
+          HIGH_POWER
 
-    .. data:: Pin.IRQ_LOW_LEVEL
+   Selects the pin drive strength.
 
-    .. data:: Pin.IRQ_HIGH_LEVEL
+.. data:: IRQ_FALLING
+          IRQ_RISING
+          IRQ_LOW_LEVEL
+          IRQ_HIGH_LEVEL
 
-        Selects the IRQ trigger type.
+   Selects the IRQ trigger type.
diff --git a/docs/library/machine.rst b/docs/library/machine.rst
index dacfe737b9..14d75cb466 100644
--- a/docs/library/machine.rst
+++ b/docs/library/machine.rst
@@ -18,76 +18,90 @@ Reset related functions
 
    Get the reset cause. See :ref:`constants <machine_constants>` for the possible return values.
 
-Interrupt related functions
----------------------------
+.. only:: port_wipy
 
-.. function:: disable_irq()
+    Interrupt related functions
+    ---------------------------
 
-   Disable interrupt requests.
-   Returns the previous IRQ state: ``False``/``True`` for disabled/enabled IRQs
-   respectively.  This return value can be passed to enable_irq to restore
-   the IRQ to its original state.
+    .. function:: disable_irq()
 
-.. function:: enable_irq(state=True)
+       Disable interrupt requests.
+       Returns the previous IRQ state: ``False``/``True`` for disabled/enabled IRQs
+       respectively.  This return value can be passed to enable_irq to restore
+       the IRQ to its original state.
 
-   Enable interrupt requests.
-   If ``state`` is ``True`` (the default value) then IRQs are enabled.
-   If ``state`` is ``False`` then IRQs are disabled.  The most common use of
-   this function is to pass it the value returned by ``disable_irq`` to
-   exit a critical section.
+    .. function:: enable_irq(state=True)
+
+       Enable interrupt requests.
+       If ``state`` is ``True`` (the default value) then IRQs are enabled.
+       If ``state`` is ``False`` then IRQs are disabled.  The most common use of
+       this function is to pass it the value returned by ``disable_irq`` to
+       exit a critical section.
 
 Power related functions
 -----------------------
 
 .. function:: freq()
 
-   Returns a tuple of clock frequencies: ``(sysclk,)``
-   These correspond to:
+    .. only:: not port_wipy
+
+        Returns CPU frequency in hertz.
+
+    .. only:: port_wipy
 
-      - sysclk: frequency of the CPU
+        Returns a tuple of clock frequencies: ``(sysclk,)``
+        These correspond to:
+
+        - sysclk: frequency of the CPU
 
 .. function:: idle()
 
    Gates the clock to the CPU, useful to reduce power consumption at any time during
    short or long periods. Peripherals continue working and execution resumes as soon
-   as any interrupt is triggered (including the systick which has a period of 1ms).
-   Current consumption is reduced to ~12mA (in WLAN STA mode)
+   as any interrupt is triggered (on many ports this includes system timer
+   interrupt occuring at regular intervals on the order of millisecond).
 
 .. function:: sleep()
 
    Stops the CPU and disables all peripherals except for WLAN. Execution is resumed from
-   the point where the sleep was requested. Wake sources are ``Pin``, ``RTC`` and ``WLAN``.
-   Current consumption is reduced to 950uA (in WLAN STA mode).
+   the point where the sleep was requested. For wake up to actually happen, wake sources
+   should be configured first.
 
 .. function:: deepsleep()
 
-   Stops the CPU and all peripherals including WLAN. Execution is resumed from main, just
-   as with a reset. The reset cause can be checked to know that we are coming from
-   from ``machine.DEEPSLEEP``. Wake sources are ``Pin`` and ``RTC``. Current consumption 
-   is reduced to ~5uA.
+   Stops the CPU and all peripherals (including networking interfaces, if any). Execution
+   is resumed from the main script, just as with a reset. The reset cause can be checked
+   to know that we are coming from ``machine.DEEPSLEEP``. For wake up to actually happen,
+   wake sources should be configured first, like ``Pin`` change or ``RTC`` timeout.
+
+.. only:: port_wipy
 
-.. function:: wake_reason()
+    .. function:: wake_reason()
 
-   Get the wake reason. See :ref:`constants <machine_constants>` for the possible return values.
+        Get the wake reason. See :ref:`constants <machine_constants>` for the possible return values.
 
 Miscellaneous functions
 -----------------------
 
-.. function:: main(filename)
+.. only:: port_wipy
+
+    .. function:: main(filename)
 
-   Set the filename of the main script to run after boot.py is finished.  If
-   this function is not called then the default file main.py will be executed.
+        Set the filename of the main script to run after boot.py is finished.  If
+        this function is not called then the default file main.py will be executed.
 
-   It only makes sense to call this function from within boot.py.
+        It only makes sense to call this function from within boot.py.
 
-.. function:: rng()
+    .. function:: rng()
 
-   Return a 24-bit software generated random number.
+        Return a 24-bit software generated random number.
 
 .. function:: unique_id()
 
-   Returns a string of 6 bytes (48 bits), which is the unique ID of the MCU.
-   This also corresponds to the network ``MAC address``.
+   Returns a byte string with a unique idenifier of a board/SoC. It will vary
+   from a board/SoC instance to another, if underlying hardware allows. Length
+   varies by hardware (so use substring of a full value if you expect a short
+   ID). In some MicroPython ports, ID corresponds to the network MAC address.
 
 .. _machine_constants:
 
diff --git a/docs/library/network.rst b/docs/library/network.rst
index 49e7e53bf8..fe4eaa7525 100644
--- a/docs/library/network.rst
+++ b/docs/library/network.rst
@@ -283,14 +283,6 @@ For example::
 
         Disconnect from the currently connected wireless network.
 
-    .. method:: wlan.mac([address])
-
-        Get or set the network interface MAC address.
-
-        If the ``address`` parameter is provided, sets the address to its
-        value, which should be bytes object of length 6. If the function
-        is called wihout parameters, returns the current address.
-
     .. method:: wlan.scan()
 
         Scan for the available wireless networks.
@@ -300,6 +292,9 @@ For example::
 
             (ssid, bssid, channel, RSSI, authmode, hidden)
 
+        `bssid` is hardware address of an access point, in binary form, returned as
+        bytes object. You can use ``ubinascii.hexlify()`` to convert it to ASCII form.
+
         There are five values for authmode:
 
             * 0 -- open
@@ -332,6 +327,46 @@ For example::
         point and has a valid IP address.  In AP mode returns ``True`` when a
         station is connected. Returns ``False`` otherwise.
 
+    .. method:: wlan.ifconfig([(ip, subnet, gateway, dns)])
+
+       Get/set IP-level network interface paremeters: IP address, subnet mask,
+       gateway and DNS server. When called with no arguments, this method returns
+       a 4-tuple with the above information. To set the above values, pass a
+       4-tuple with the required information.  For example::
+
+        nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
+
+    .. method:: wlan.config('param')
+    .. method:: wlan.config(param=value, ...)
+
+       Get or set general network interface parameters. These methods allow to work
+       with additional parameters beyond standard IP configuration (as dealt with by
+       ``wlan.ifconfig()``). These include network-specific and hardware-specific
+       parameters. For setting parameters, keyword argument syntax should be used,
+       multiple parameters can be set at once. For querying, paremeters name should
+       be quoted as a string, and only one paramter can be queries at time::
+
+        # Set WiFi access point name (formally known as ESSID) and WiFi channel
+        ap.config(essid='My AP', channel=11)
+        # Queey params one by one
+        print(ap.config('essid'))
+        print(ap.config('channel'))
+
+       Following are commonly supported parameters (availability of a specific parameter
+       depends on network technology type, driver, and MicroPython port).
+
+       =========  ===========
+       Parameter  Description
+       =========  ===========
+       mac        MAC address (bytes)
+       essid      WiFi access point name (string)
+       channel    WiFi channel (integer)
+       hidden     Whether ESSID is hidden (boolean)
+       authmode   Authentication mode supported (enumeration, see module constants)
+       password   Access password (string)
+       =========  ===========
+
+
 
 .. only:: port_wipy
 
diff --git a/docs/library/pyb.UART.rst b/docs/library/pyb.UART.rst
index 5fc5b22a5a..536b6f467d 100644
--- a/docs/library/pyb.UART.rst
+++ b/docs/library/pyb.UART.rst
@@ -40,7 +40,8 @@ using the standard stream methods::
 
     To check if there is anything to be read, use::
 
-        uart.any()               # returns True if any characters waiting
+        uart.any()          # returns the number of characters waiting
+
 
     *Note:* The stream functions ``read``, ``write``, etc. are new in MicroPython v1.3.4.
     Earlier versions use ``uart.send`` and ``uart.recv``.
@@ -57,7 +58,7 @@ Constructors
        initialised (it has the settings from the last initialisation of
        the bus, if any).  If extra arguments are given, the bus is initialised.
        See ``init`` for parameters of initialisation.
-    
+
        The physical pins of the UART busses are:
     
          - ``UART(4)`` is on ``XA``: ``(TX, RX) = (X1, X2) = (PA0, PA1)``
@@ -66,12 +67,16 @@ Constructors
          - ``UART(3)`` is on ``YB``: ``(TX, RX) = (Y9, Y10) = (PB10, PB11)``
          - ``UART(2)`` is on: ``(TX, RX) = (X3, X4) = (PA2, PA3)``
 
+       The Pyboard Lite supports UART(1), UART(2) and UART(6) only. Pins are as above except:
+
+         - ``UART(2)`` is on: ``(TX, RX) = (X1, X2) = (PA2, PA3)``
+
 Methods
 -------
 
 .. only:: port_pyboard
 
-    .. method:: uart.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=None, timeout_char=0, read_buf_len=64)
+    .. method:: uart.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=0, timeout_char=0, read_buf_len=64)
     
        Initialise the UART bus with the given parameters:
     
@@ -79,7 +84,7 @@ Methods
          - ``bits`` is the number of bits per character, 7, 8 or 9.
          - ``parity`` is the parity, ``None``, 0 (even) or 1 (odd).
          - ``stop`` is the number of stop bits, 1 or 2.
-         - ``flow`` sets the flow control type. Can be None, ``UART.RTS``, ``UART.CTS``
+         - ``flow`` sets the flow control type. Can be 0, ``UART.RTS``, ``UART.CTS``
            or ``UART.RTS | UART.CTS``.
          - ``timeout`` is the timeout in milliseconds to wait for the first character.
          - ``timeout_char`` is the timeout in milliseconds to wait between characters.
@@ -103,16 +108,18 @@ Methods
 
     .. method:: uart.any()
 
-       Returns the number of characters waiting (may be 0).
+       Returns the number of bytes waiting (may be 0).
 
     .. method:: uart.writechar(char)
 
       Write a single character on the bus.  ``char`` is an integer to write.
-      Return value: ``None``.
+      Return value: ``None``. See note below if CTS flow control is used.
 
 .. method:: uart.read([nbytes])
 
    Read characters.  If ``nbytes`` is specified then read at most that many bytes.
+   If ``nbytes`` are available in the buffer, returns immediately, otherwise returns
+   when sufficient characters arrive or the timeout elapses.
 
    .. only:: port_pyboard
 
@@ -124,9 +131,9 @@ Methods
 
 .. method:: uart.readall()
 
-   Read as much data as possible.
+   Read as much data as possible. Returns after the timeout has elapsed.
 
-   Return value: a bytes object or ``None`` on timeout.
+   Return value: a bytes object or ``None`` if timeout prevents any data being read.
 
 .. method:: uart.readchar()
 
@@ -144,9 +151,11 @@ Methods
 
 .. method:: uart.readline()
 
-   Read a line, ending in a newline character.
+   Read a line, ending in a newline character. If such a line exists, return is
+   immediate. If the timeout elapses, all available data is returned regardless
+   of whether a newline exists.
 
-   Return value: the line read or ``None`` on timeout.
+   Return value: the line read or ``None`` on timeout if no data is available.
 
 .. method:: uart.write(buf)
 
@@ -157,7 +166,8 @@ Methods
       bytes are used for each character (little endian), and ``buf`` must contain
       an even number of bytes.
 
-      Return value: number of bytes written or ``None`` on timeout.
+      Return value: number of bytes written. If a timeout occurs and no bytes
+      were written returns ``None``.
 
 .. method:: uart.sendbreak()
 
@@ -173,4 +183,63 @@ Constants
     .. data:: UART.RTS
     .. data:: UART.CTS
 
-       to select the flow control type
+       to select the flow control type.
+
+Flow Control
+------------
+
+.. only:: port_pyboard
+
+    On Pyboards V1 and V1.1 ``UART(2)`` and ``UART(3)`` support RTS/CTS hardware flow control
+    using the following pins:
+
+        - ``UART(2)`` is on: ``(TX, RX, nRTS, nCTS) = (X3, X4, X2, X1) = (PA2, PA3, PA1, PA0)``
+        - ``UART(3)`` is on :``(TX, RX, nRTS, nCTS) = (Y9, Y10, Y7, Y6) = (PB10, PB11, PB14, PB13)``
+
+    On the Pyboard Lite only ``UART(2)`` supports flow control on these pins:
+
+        ``(TX, RX, nRTS, nCTS) = (X1, X2, X4, X3) = (PA2, PA3, PA1, PA0)``
+
+    In the following paragraphs the term "target" refers to the device connected to
+    the UART.
+
+    When the UART's ``init()`` method is called with ``flow`` set to one or both of
+    ``UART.RTS`` and ``UART.CTS`` the relevant flow control pins are configured.
+    ``nRTS`` is an active low output, ``nCTS`` is an active low input with pullup
+    enabled. To achieve flow control the Pyboard's ``nCTS`` signal should be connected
+    to the target's ``nRTS`` and the Pyboard's ``nRTS`` to the target's ``nCTS``.
+
+    CTS: target controls Pyboard transmitter
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    If CTS flow control is enabled the write behaviour is as follows:
+
+    If the Pyboard's ``uart.write(buf)`` method is called, transmission will stall for
+    any periods when ``nCTS`` is ``False``. This will result in a timeout if the entire
+    buffer was not transmitted in the timeout period. The method returns the number of
+    bytes written, enabling the user to write the remainder of the data if required. In
+    the event of a timeout, a character will remain in the UART pending ``nCTS``. The
+    number of bytes composing this character will be included in the return value.
+    
+    If ``uart.writechar()`` is called when ``nCTS`` is ``False`` the method will time
+    out unless the target asserts ``nCTS`` in time. If it times out ``OSError 116``
+    will be raised. The character will be transmitted as soon as the target asserts ``nCTS``.
+
+    RTS: Pyboard controls target's transmitter
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    If RTS flow control is enabled, behaviour is as follows:
+    
+    If buffered input is used (``read_buf_len`` > 0), incoming characters are buffered.
+    If the buffer becomes full, the next character to arrive will cause ``nRTS`` to go
+    ``False``: the target should cease transmission. ``nRTS`` will go ``True`` when
+    characters are read from the buffer.
+    
+    Note that the ``any()`` method returns the number of bytes in the buffer. Assume a
+    buffer length of ``N`` bytes. If the buffer becomes full, and another character arrives,
+    ``nRTS`` will be set False, and ``any()`` will return the count ``N``. When
+    characters are read the additional character will be placed in the buffer and will
+    be included in the result of a subsequent ``any()`` call.
+    
+    If buffered input is not used (``read_buf_len`` == 0) the arrival of a character will
+    cause ``nRTS`` to go ``False`` until the character is read.
diff --git a/docs/library/struct.rst b/docs/library/struct.rst
deleted file mode 100644
index 71ee5c9b70..0000000000
--- a/docs/library/struct.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-:mod:`struct` -- pack and unpack primitive data types
-=====================================================
-
-.. module:: struct
-   :synopsis: pack and unpack primitive data types
-
-See `Python struct <https://docs.python.org/3/library/struct.html>`_ for more
-information.
-
-Functions
----------
-
-.. function:: calcsize(fmt)
-
-   Return the number of bytes needed to store the given ``fmt``.
-
-.. function:: pack(fmt, v1, v2, ...)
-
-   Pack the values ``v1``, ``v2``, ... according to the format string ``fmt``.
-   The return value is a bytes object encoding the values.
-
-.. function:: unpack(fmt, data)
-
-   Unpack from the ``data`` according to the format string ``fmt``.
-   The return value is a tuple of the unpacked values.
diff --git a/docs/library/sys.rst b/docs/library/sys.rst
index b3e52c40c4..b5a9138c07 100644
--- a/docs/library/sys.rst
+++ b/docs/library/sys.rst
@@ -7,14 +7,15 @@
 Functions
 ---------
 
-.. function:: exit([retval])
+.. function:: exit(retval=0)
 
-   Raise a ``SystemExit`` exception.  If an argument is given, it is the
-   value given to ``SystemExit``.
+   Terminate current program with a given exit code. Underlyingly, this
+   function raise as ``SystemExit`` exception. If an argument is given, its
+   value given as an argument to ``SystemExit``.
 
-.. function:: print_exception(exc, [file])
+.. function:: print_exception(exc, file=sys.stdout)
 
-   Print exception with a traceback to a file-like object ``file`` (or
+   Print exception with a traceback to a file-like object `file` (or
    ``sys.stdout`` by default).
 
    .. admonition:: Difference to CPython
@@ -27,38 +28,89 @@ Constants
 
 .. data:: argv
 
-   a mutable list of arguments this program started with
+   A mutable list of arguments the current program was started with.
 
 .. data:: byteorder
 
-   the byte order of the system ("little" or "big")
+   The byte order of the system ("little" or "big").
+
+.. data:: implementation
+
+   Object with information about the current Python implementation. For
+   MicroPython, it has following attributes:
+
+   * `name` - string "micropython"
+   * `version` - tuple (major, minor, micro), e.g. (1, 7, 0)
+
+   This object is the recommended way to distinguish MicroPython from other
+   Python implementations (note that it still may not exist in the very
+   minimal ports).
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      CPython mandates more attributes for this object, but the actual useful
+      bare minimum is implemented in MicroPython.
+
+.. data:: maxsize
+
+   Maximum value which a native integer type can hold on the current platform,
+   or maximum value representable by MicroPython integer type, if it's smaller
+   than platform max value (that is the case for MicroPython ports without
+   long int support).
+
+   This attribute is useful for detecting "bitness" of a platform (32-bit vs
+   64-bit, etc.). It's recommended to not compare this attribute to some
+   value directly, but instead count number of bits in it::
+
+    bits = 0
+    v = sys.maxsize
+    while v:
+        bits += 1
+        v >>= 1
+    if bits > 32:
+        # 64-bit (or more) platform
+        ...
+    else:
+        # 32-bit (or less) platform
+        # Note that on 32-bit platform, value of bits may be less than 32
+        # (e.g. 31) due to peculiarities described above, so use "> 16",
+        # "> 32", "> 64" style of comparisons.
+
+.. data:: modules
+
+   Dictionary of loaded modules. On some ports, it may not include builtin
+   modules.
 
 .. data:: path
 
-   a mutable list of directories to search for imported modules
+   A mutable list of directories to search for imported modules.
 
 .. data:: platform
 
-   The platform that MicroPython is running on.  This is "pyboard" on the
-   pyboard and provides a robust way of determining if a script is running
-   on the pyboard or not.
+   The platform that MicroPython is running on. For OS/RTOS ports, this is
+   usually an identifier of the OS, e.g. ``"linux"``. For baremetal ports it
+   is an identifier of a board, e.g. "pyboard" for the original MicroPython
+   reference board. It thus can be used to distinguish one board from another.
+   If you need to check whether your program runs on MicroPython (vs other
+   Python implementation), use ``sys.implementation`` instead.
 
 .. data:: stderr
 
-   standard error (connected to USB VCP, and optional UART object)
+   Standard error stream.
 
 .. data:: stdin
 
-   standard input (connected to USB VCP, and optional UART object)
+   Standard input stream.
 
 .. data:: stdout
 
-   standard output (connected to USB VCP, and optional UART object)
+   Standard output stream.
 
 .. data:: version
 
-   Python language version that this implementation conforms to, as a string
+   Python language version that this implementation conforms to, as a string.
 
 .. data:: version_info
 
-   Python language version that this implementation conforms to, as a tuple of ints
+   Python language version that this implementation conforms to, as a tuple of ints.
diff --git a/docs/library/time.rst b/docs/library/time.rst
deleted file mode 100644
index 9a35f4f66a..0000000000
--- a/docs/library/time.rst
+++ /dev/null
@@ -1,89 +0,0 @@
-:mod:`time` -- time related functions
-=====================================
-
-.. module:: time
-   :synopsis: time related functions
-
-The ``time`` module provides functions for getting the current time and date,
-and for sleeping.
-
-Functions
----------
-
-.. function:: localtime([secs])
-
-   Convert a time expressed in seconds since Jan 1, 2000 into an 8-tuple which
-   contains: (year, month, mday, hour, minute, second, weekday, yearday)
-   If secs is not provided or None, then the current time from the RTC is used.
-   year includes the century (for example 2014).
-
-   * month   is 1-12
-   * mday    is 1-31
-   * hour    is 0-23
-   * minute  is 0-59
-   * second  is 0-59
-   * weekday is 0-6 for Mon-Sun
-   * yearday is 1-366
-
-.. function:: mktime()
-
-   This is inverse function of localtime. It's argument is a full 8-tuple
-   which expresses a time as per localtime. It returns an integer which is
-   the number of seconds since Jan 1, 2000.
-
-.. only:: port_pyboard
-
-    .. function:: sleep(seconds)
-    
-       Sleep for the given number of seconds.  Seconds can be a floating-point number to
-       sleep for a fractional number of seconds.
-
-.. only:: port_esp8266 or port_wipy
-
-    .. function:: sleep(seconds)
-    
-       Sleep for the given number of seconds.
-
-.. only:: port_wipy or port_pyboard
-
-    .. function::  sleep_ms(ms)
-
-       Delay for given number of milliseconds, should be positive or 0.
-
-    .. function::  sleep_us(us)
-
-       Delay for given number of microseconds, should be positive or 0
-
-    .. function::  ticks_ms()
-
-        Returns an increasing millisecond counter with arbitrary reference point, 
-        that wraps after some (unspecified) value. The value should be treated as 
-        opaque, suitable for use only with ticks_diff().
-
-    .. function::  ticks_us()
-
-       Just like ``ticks_ms`` above, but in microseconds.
-
-    .. function::  ticks_cpu()
-
-       Similar to ``ticks_ms`` and ``ticks_us``, but with higher resolution (usually CPU clocks).
-
-    .. function::  ticks_diff(old, new)
-
-       Measure period between consecutive calls to ticks_ms(), ticks_us(), or ticks_cpu(). 
-       The value returned by these functions may wrap around at any time, so directly 
-       subtracting them is not supported. ticks_diff() should be used instead. "old" value should 
-       actually precede "new" value in time, or result is undefined. This function should not be
-       used to measure arbitrarily long periods of time (because ticks_*() functions wrap around 
-       and usually would have short period). The expected usage pattern is implementing event 
-       polling with timeout::
-
-            # Wait for GPIO pin to be asserted, but at most 500us
-            start = time.ticks_us()
-            while pin.value() == 0:
-                if time.ticks_diff(start, time.ticks_us()) > 500:
-                    raise TimeoutError
-
-.. function:: time()
-
-   Returns the number of seconds, as an integer, since 1/1/2000.
diff --git a/docs/library/ubinascii.rst b/docs/library/ubinascii.rst
index e7967c5113..0a9adb50d4 100644
--- a/docs/library/ubinascii.rst
+++ b/docs/library/ubinascii.rst
@@ -12,7 +12,7 @@ Functions
 
 .. function:: hexlify(data, [sep])
 
-   Convert binary data to hexadecimal representation. Return bytes string.
+   Convert binary data to hexadecimal representation. Returns bytes string.
 
    .. admonition:: Difference to CPython
       :class: attention
@@ -22,13 +22,13 @@ Functions
 
 .. function:: unhexlify(data)
 
-   Convert hexadecimal data to binary representation. Return bytes string.
+   Convert hexadecimal data to binary representation. Returns bytes string.
    (i.e. inverse of hexlify)
 
 .. function:: a2b_base64(data)
 
-   Convert Base64-encoded data to binary representation. Return bytes string.
+   Convert Base64-encoded data to binary representation. Returns bytes string.
 
 .. function:: b2a_base64(data)
 
-   Encode binary data in Base64 format. Return string.
+   Encode binary data in Base64 format. Returns string.
diff --git a/docs/library/ucollections.rst b/docs/library/ucollections.rst
new file mode 100644
index 0000000000..c7ed068c7e
--- /dev/null
+++ b/docs/library/ucollections.rst
@@ -0,0 +1,53 @@
+:mod:`ucollections` -- collection and container types
+=====================================================
+
+.. module:: ucollections
+   :synopsis: collection and container types
+
+This module implements advanced collection and container types to
+hold/accumulate various objects.
+
+Classes
+-------
+
+.. function:: namedtuple(name, fields)
+
+    This is factory function to create a new namedtuple type with a specific
+    name and set of fields. A namedtyple is a subclass of tuple which allows
+    to access its fields not just by numeric index, but also with an attribute
+    access syntax using symbolic field names. Fields is a sequence of strings
+    specifying field names. For compatibily with CPython it can also be a
+    a string with space-separated field named (but this is less efficient).
+    Example of use::
+
+        from ucollections import namedtuple
+
+        MyTuple = namedtuple("MyTuple", ("id", "name"))
+        t1 = MyTuple(1, "foo")
+        t2 = MyTuple(2, "bar")
+        print(t1.name)
+        assert t2.name == t2[1]
+
+.. function:: OrderedDict(...)
+
+    ``dict`` type subclass which remembers and preserves the order of keys
+    added. When ordered dict is iterated over, keys/items are returned in
+    the order they were added::
+
+        from ucollections import OrderedDict
+
+        # To make benefit of ordered keys, OrderedDict should be initialized
+        # from sequence of (key, value) pairs.
+        d = OrderedDict([("z", 1), ("a", 2)])
+        # More items can be added as usual
+        d["w"] = 5
+        d["b"] = 3
+        for k, v in d.items():
+            print(k, v)
+
+    Output::
+
+        z 1
+        a 2
+        w 5
+        b 3
diff --git a/docs/library/uio.rst b/docs/library/uio.rst
new file mode 100644
index 0000000000..1b3e2a0822
--- /dev/null
+++ b/docs/library/uio.rst
@@ -0,0 +1,46 @@
+:mod:`uio` -- input/output streams
+==================================
+
+.. module:: uio
+   :synopsis: input/output streams
+
+This module contains additional types of stream (file-like) objects
+and helper functions.
+
+Functions
+---------
+
+.. function:: open(name, mode='r', **kwargs)
+
+    Open a file. Builtin ``open()`` function is alised to this function.
+    All ports (which provide access to file system) are required to support
+    `mode` parameter, but support for other arguments vary by port.
+
+Classes
+-------
+
+.. class:: FileIO(...)
+
+    This is type of a file open in binary mode, e.g. using ``open(name, "rb")``.
+    You should not instantiate this class directly.
+
+.. class:: TextIOWrapper(...)
+
+    This is type of a file open in text mode, e.g. using ``open(name, "rt")``.
+    You should not instantiate this class directly.
+
+.. class:: StringIO([string])
+.. class:: BytesIO([string])
+
+    In-memory file-like objects for input/output. `StringIO` is used for
+    text-mode I/O (similar to a normal file opened with "t" modifier).
+    `BytesIO` is used for binary-mode I/O (similar to a normal file
+    opened with "b" modifier). Initial contents of file-like objects
+    can be specified with `string` parameter (should be normal string
+    for `StringIO` or bytes object for `BytesIO`). All the usual file
+    methods like ``read()``, ``write()``, ``close()`` are available on
+    these objects, and additionally, following method:
+
+    .. method:: getvalue()
+
+        Get the current contents of the underlying buffer which holds data.
diff --git a/docs/library/os.rst b/docs/library/uos.rst
index e6777147ac..bb95107c04 100644
--- a/docs/library/os.rst
+++ b/docs/library/uos.rst
@@ -1,7 +1,7 @@
-:mod:`os` -- basic "operating system" services
-==============================================
+:mod:`uos` -- basic "operating system" services
+===============================================
 
-.. module:: os
+.. module:: uos
    :synopsis: basic "operating system" services
 
 The ``os`` module contains functions for filesystem access and ``urandom``
diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst
index a83a87d2e0..d31e4d2fc9 100644
--- a/docs/library/usocket.rst
+++ b/docs/library/usocket.rst
@@ -7,6 +7,18 @@
 
 This module provides access to the BSD socket interface.
 
+See corresponding `CPython module <https://docs.python.org/3/library/socket.html>`_ for
+comparison.
+
+Socket address format(s)
+------------------------
+
+Functions below which expect a network address, accept it in the format of
+`(ipv4_address, port)`, where `ipv4_address` is a string with dot-notation numeric
+IPv4 address, e.g. ``"8.8.8.8"``, and port is integer port number in the range
+1-65535. Note the domain names are not accepted as `ipv4_address`, they should be
+resolved first using ``socket.getaddrinfo()``.
+
 Functions
 ---------
 
@@ -37,13 +49,15 @@ Functions
    The following example shows how to connect to a given url::
 
       s = socket.socket()
-      s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][4])
+      s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1])
+
+.. only:: port_wipy
 
-Exceptions
-----------
+    Exceptions
+    ----------
 
-.. data:: socket.error
-.. data:: socket.timeout
+    .. data:: socket.error
+    .. data:: socket.timeout
 
 Constants
 ---------
@@ -59,9 +73,10 @@ Constants
 
 .. data:: socket.IPPROTO_UDP
 .. data:: socket.IPPROTO_TCP
-.. data:: socket.IPPROTO_SEC
+.. only:: port_wipy
+   .. data:: socket.IPPROTO_SEC
 
-   protocol numbers
+      protocol numbers
 
 class socket
 ============
@@ -79,8 +94,7 @@ Methods
 
     .. method:: socket.bind(address)
 
-       Bind the socket to address. The socket must not already be bound. The format of ``address``
-       is: ``(ipv4 address, port)``
+       Bind the socket to address. The socket must not already be bound.
 
     .. method:: socket.listen([backlog])
 
@@ -98,7 +112,7 @@ Methods
 
     .. method:: socket.connect(address)
 
-       Connect to a remote socket at address. The format of address is: ``(ipv4 address, port)``
+       Connect to a remote socket at address.
 
     .. method:: socket.send(bytes)
 
@@ -116,8 +130,7 @@ Methods
     .. method:: socket.sendto(bytes, address)
 
        Send data to the socket. The socket should not be connected to a remote socket, since the
-       destination socket is specified by address. The ``address`` has the same format as the
-       rest of the methods, see above.
+       destination socket is specified by `address`.
 
     .. method:: socket.recvfrom(bufsize)
 
@@ -158,9 +171,10 @@ Methods
        The socket must be in blocking mode; it can have a timeout, but the file object’s internal buffer
        may end up in a inconsistent state if a timeout occurs.
 
-       .. note::
+       .. admonition:: Difference to CPython
+          :class: attention
 
-          **CPython difference:** closing the file object returned by makefile() WILL close the 
+          Closing the file object returned by makefile() WILL close the
           original socket as well.
 
     .. method:: socket.read(size)
diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst
index 60be894107..b66e23b2c8 100644
--- a/docs/library/ussl.rst
+++ b/docs/library/ussl.rst
@@ -21,7 +21,7 @@ Functions
       import ssl
       s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC)
       ss = ssl.wrap_socket(s)
-      ss.connect(socket.getaddrinfo('www.google.com', 443)[0][4])
+      ss.connect(socket.getaddrinfo('www.google.com', 443)[0][-1])
 
    Certificates must be used in order to validate the other side of the connection, and also to
    authenticate ourselves with the other end. Such certificates must be stored as files using the
@@ -44,7 +44,7 @@ Functions
       import ssl
       s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC)
       ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem')
-      ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][4])
+      ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1])
 
    SSL sockets inherit all methods and from the standard sockets, see the :mod:`usocket` module.
 
diff --git a/docs/library/ustruct.rst b/docs/library/ustruct.rst
new file mode 100644
index 0000000000..ae5b1be003
--- /dev/null
+++ b/docs/library/ustruct.rst
@@ -0,0 +1,37 @@
+:mod:`ustruct` -- pack and unpack primitive data types
+======================================================
+
+.. module:: ustruct
+   :synopsis: pack and unpack primitive data types
+
+See `Python struct <https://docs.python.org/3/library/struct.html>`_ for more
+information.
+
+Functions
+---------
+
+.. function:: calcsize(fmt)
+
+   Return the number of bytes needed to store the given `fmt`.
+
+.. function:: pack(fmt, v1, v2, ...)
+
+   Pack the values `v1`, `v2`, ... according to the format string `fmt`.
+   The return value is a bytes object encoding the values.
+
+.. function:: pack_into(fmt, buffer, offset, v1, v2, ...)
+
+   Pack the values `v1`, `v2`, ... according to the format string `fmt`
+   into a `buffer` starting at `offset`. `offset` may be negative to count
+   from the end of `buffer`.
+
+.. function:: unpack(fmt, data)
+
+   Unpack from the `data` according to the format string `fmt`.
+   The return value is a tuple of the unpacked values.
+
+.. function:: unpack_from(fmt, data, offset=0)
+
+   Unpack from the `data` starting at `offset` according to the format string
+   `fmt`. `offset` may be negative to count from the end of `buffer`. The return
+   value is a tuple of the unpacked values.
diff --git a/docs/library/utime.rst b/docs/library/utime.rst
new file mode 100644
index 0000000000..0bca4692ac
--- /dev/null
+++ b/docs/library/utime.rst
@@ -0,0 +1,139 @@
+:mod:`utime` -- time related functions
+======================================
+
+.. module:: utime
+   :synopsis: time related functions
+
+The ``utime`` module provides functions for getting the current time and date,
+measuring time intervals, and for delays.
+
+**Time Epoch**: Unix port uses standard for POSIX systems epoch of
+1970-01-01 00:00:00 UTC. However, embedded ports use epoch of
+2000-01-01 00:00:00 UTC.
+
+**Maintaining actual calendar date/time**: This requires a
+Real Time Clock (RTC). On systems with underlying OS (including some
+RTOS), an RTC may be implicit. Setting and maintaining actual calendar
+time is responsibility of OS/RTOS and is done outside of MicroPython,
+it just uses OS API to query date/time. On baremetal ports however
+system time depends on ``machine.RTC()`` object. The current calendar time
+may be set using ``machine.RTC().datetime(tuple)`` function, and maintained
+by following means:
+
+* By a backup battery (which may be an additional, optional component for
+  a particular board).
+* Using networked time protocol (requires setup by a port/user).
+* Set manually by a user on each power-up (many boards then maintain
+  RTC time across hard resets, though some may require setting it again
+  in such case).
+
+If actual calendar time is not maintained with a system/MicroPython RTC,
+functions below which require reference to current absolute time may
+behave not as expected.
+
+Functions
+---------
+
+.. function:: localtime([secs])
+
+   Convert a time expressed in seconds since the Epoch (see above) into an 8-tuple which
+   contains: (year, month, mday, hour, minute, second, weekday, yearday)
+   If secs is not provided or None, then the current time from the RTC is used.
+
+   * year includes the century (for example 2014).
+   * month   is 1-12
+   * mday    is 1-31
+   * hour    is 0-23
+   * minute  is 0-59
+   * second  is 0-59
+   * weekday is 0-6 for Mon-Sun
+   * yearday is 1-366
+
+.. function:: mktime()
+
+   This is inverse function of localtime. It's argument is a full 8-tuple
+   which expresses a time as per localtime. It returns an integer which is
+   the number of seconds since Jan 1, 2000.
+
+.. only:: port_unix or port_pyboard or port_esp8266
+
+    .. function:: sleep(seconds)
+    
+       Sleep for the given number of seconds.  Seconds can be a floating-point number to
+       sleep for a fractional number of seconds. Note that other MicroPython ports may
+       not accept floating-point argument, for compatibility with them use ``sleep_ms()``
+       and ``sleep_us()`` functions.
+
+.. only:: port_wipy
+
+    .. function:: sleep(seconds)
+    
+       Sleep for the given number of seconds.
+
+.. only:: port_unix or port_pyboard or port_wipy or port_esp8266
+
+    .. function::  sleep_ms(ms)
+
+       Delay for given number of milliseconds, should be positive or 0.
+
+    .. function::  sleep_us(us)
+
+       Delay for given number of microseconds, should be positive or 0
+
+    .. function::  ticks_ms()
+
+        Returns an increasing millisecond counter with arbitrary reference point, 
+        that wraps after some (unspecified) value. The value should be treated as 
+        opaque, suitable for use only with ticks_diff().
+
+    .. function::  ticks_us()
+
+       Just like ``ticks_ms`` above, but in microseconds.
+
+.. only:: port_wipy or port_pyboard
+
+    .. function::  ticks_cpu()
+
+       Similar to ``ticks_ms`` and ``ticks_us``, but with higher resolution (usually CPU clocks).
+
+.. only:: port_unix or port_pyboard or port_wipy or port_esp8266
+
+    .. function::  ticks_diff(old, new)
+
+       Measure period between consecutive calls to ticks_ms(), ticks_us(), or ticks_cpu(). 
+       The value returned by these functions may wrap around at any time, so directly 
+       subtracting them is not supported. ticks_diff() should be used instead. "old" value should 
+       actually precede "new" value in time, or result is undefined. This function should not be
+       used to measure arbitrarily long periods of time (because ticks_*() functions wrap around 
+       and usually would have short period). The expected usage pattern is implementing event 
+       polling with timeout::
+
+            # Wait for GPIO pin to be asserted, but at most 500us
+            start = time.ticks_us()
+            while pin.value() == 0:
+                if time.ticks_diff(start, time.ticks_us()) > 500:
+                    raise TimeoutError
+
+.. function:: time()
+
+   Returns the number of seconds, as an integer, since the Epoch, assuming that underlying
+   RTC is set and maintained as decsribed above. If an RTC is not set, this function returns
+   number of seconds since a port-specific reference point in time (for embedded boards without
+   a battery-backed RTC, usually since power up or reset). If you want to develop portable
+   MicroPython application, you should not rely on this function to provide higher than second
+   precision. If you need higher precision, use ``ticks_ms()`` and ``ticks_us()`` functions,
+   if you need calendar time, ``localtime()`` without an argument is a better choice.
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      In CPython, this function returns number of
+      seconds since Unix epoch, 1970-01-01 00:00 UTC, as a floating-point,
+      usually having microsecond precision. With MicroPython, only Unix port
+      uses the same Epoch, and if floating-point precision allows,
+      returns sub-second precision. Embedded hardware usually doesn't have
+      floating-point precision to represent both long time ranges and subsecond
+      precision, so they use integer value with second precision. Some embedded
+      hardware also lacks battery-powered RTC, so returns number of seconds
+      since last power-up or from other relative, hardware-specific point
+      (e.g. reset).