Merge tag 'v1.8.7' into parse-bytecode

Support for Xtensa emitter and assembler, and upgraded F4 and F7 STM HAL

This release adds support for the Xtensa architecture as a target for the
native emitter, as well as Xtensa inline assembler.  The int.from_bytes
and int.to_bytes methods now require a second argument (the byte order)
per CPython (only "little" is supported at this time).  The "readall"
method has been removed from all stream classes that used it; "read" with
no arguments should be used instead.  There is now support for importing
packages from compiled .mpy files.  Test coverage is increased to 96%.

The generic I2C driver has improvements: configurable clock stretching
timeout, "stop" argument added to readfrom/writeto methods, "nack"
argument added to readinto, and write[to] now returns num of ACKs
received.  The framebuf module now handles 16-bit depth (generic colour
format) and has hline, vline, rect, line methods.  A new utimeq module is
added for efficient queue ordering defined by modulo time (to be
compatible with time.ticks_xxx functions).  The pyboard.py script has been
modified so that the target board is not reset between scripts or commands
that are given on a single command line.

For the stmhal port the STM Cube HAL has been upgraded: Cube F4 HAL to
v1.13.1 (CMSIS 2.5.1, HAL v1.5.2) and Cube F7 HAL to v1.1.2.  There is a
more robust pyb.I2C implementation (DMA is now disabled by default, can be
enabled via an option), and there is an implementation of machine.I2C with
robust error handling and hardware acceleration on F4 MCUs.  It is now
recommended to use machine.I2C instead of pyb.I2C.  The UART class is now
more robust with better handling of errors/timeouts.  There is also more
accurate VBAT and VREFINT measurements for the ADC.  New boards that are
supported include: NUCLEO_F767ZI, STM32F769DISC and NUCLEO_L476RG.

For the esp8266 port select/poll is now supported for sockets using the
uselect module.  There is support for native and viper emitters, as well
as an inline assembler (with limited iRAM for storage of native functions,
or the option to store code to flash).  There is improved software I2C
with a slight API change: scl/sda pins can be specified as positional only
when "-1" is passed as the first argument to indicate the use of software
I2C.  It is recommended to use keyword arguments for scl/sda.  There is
very early support for over-the-air (OTA) updates using the yaota8266
project.

A detailed list of changes follows.

py core:
- emitnative: fix native import emitter when in viper mode
- remove readall() method, which is equivalent to read() w/o args
- objexcept: allow clearing traceback with 'exc.__traceback__ = None'
- runtime: mp_resume: handle exceptions in Python __next__()
- mkrules.mk: rework find command so it works on OSX
- *.mk: replace uses of 'sed' with $(SED)
- parse: move function to check for const parse node to parse.[ch]
- parse: make mp_parse_node_new_leaf an inline function
- parse: add code to fold logical constants in or/and/not operations
- factor persistent code load/save funcs into persistentcode.[ch]
- factor out persistent-code reader into separate files
- lexer: rewrite mp_lexer_new_from_str_len in terms of mp_reader_mem
- lexer: provide generic mp_lexer_new_from_file based on mp_reader
- lexer: rewrite mp_lexer_new_from_fd in terms of mp_reader
- lexer: make lexer use an mp_reader as its source
- objtype: implement __call__ handling for an instance w/o heap alloc
- factor out common code from assemblers into asmbase.[ch]
- stream: move ad-hoc ioctl constants to stream.h and rename them
- compile: simplify configuration of native emitter
- emit.h: remove long-obsolete declarations for cpython emitter
- move arch-specific assembler macros from emitnative to asmXXX.h
- asmbase: add MP_PLAT_COMMIT_EXEC option for handling exec code
- asmxtensa: add low-level Xtensa assembler
- integrate Xtensa assembler into native emitter
- allow inline-assembler emitter to be generic
- add inline Xtensa assembler
- emitinline: embed entire asm struct instead of a pointer to it
- emitinline: move inline-asm align and data methods to compiler
- emitinline: move common code for end of final pass to compiler
- asm: remove need for dummy_data when doing initial assembler passes
- objint: from_bytes, to_bytes: require byteorder arg, require "little"
- binary: do zero extension when storing a value larger than word size
- builtinimport: support importing packages from compiled .mpy files
- mpz: remove unreachable code in mpn_or_neg functions
- runtime: zero out fs_user_mount array in mp_init
- mpconfig.h: enable MICROPY_PY_SYS_EXIT by default
- add MICROPY_KBD_EXCEPTION config option to provide mp_kbd_exception
- compile: add an extra pass for Xtensa inline assembler
- modbuiltins: remove unreachable code
- objint: rename mp_obj_int_as_float to mp_obj_int_as_float_impl
- emitglue: refactor to remove assert(0), to improve coverage
- lexer: remove unreachable code in string tokeniser
- lexer: remove unnecessary check for EOF in lexer's next_char func
- lexer: permanently disable the mp_lexer_show_token function
- parsenum: simplify and generalise decoding of digit values
- mpz: fix assertion in mpz_set_from_str which checks value of base
- mpprint: add assertion for, and comment about, valid base values
- objint: simplify mp_int_format_size and remove unreachable code
- unicode: comment-out unused function unichar_isprint
- consistently update signatures of .make_new and .call methods
- mkrules.mk: add MPY_CROSS_FLAGS option to pass flags to mpy-cross
- builtinimport: fix bug when importing names from frozen packages

extmod:
- machine_i2c: make the clock stretching timeout configurable
- machine_i2c: raise an error when clock stretching times out
- machine_i2c: release SDA on bus error
- machine_i2c: add a C-level I2C-protocol, refactoring soft I2C
- machine_i2c: add argument to C funcs to control stop generation
- machine_i2c: rewrite i2c.scan in terms of C-level protocol
- machine_i2c: rewrite mem xfer funcs in terms of C-level protocol
- machine_i2c: remove unneeded i2c_write_mem/i2c_read_mem funcs
- machine_i2c: make C-level functions return -errno on I2C error
- machine_i2c: add 'nack' argument to i2c.readinto
- machine_i2c: make i2c.write[to] methods return num of ACKs recvd
- machine_i2c: add 'stop' argument to i2c readfrom/writeto meths
- machine_i2c: remove trivial function wrappers
- machine_i2c: expose soft I2C obj and readfrom/writeto funcs
- machine_i2c: add hook to constructor to call port-specific code
- modurandom: allow to build with float disabled
- modframebuf: make FrameBuffer handle 16bit depth
- modframebuf: add back legacy FrameBuffer1 "class"
- modframebuf: optimise fill and fill_rect methods
- vfs_fat: implement POSIX behaviour of rename, allow to overwrite
- moduselect: use stream helper function instead of ad-hoc code
- moduselect: use configurable EVENT_POLL_HOOK instead of WFI
- modlwip: add ioctl method to socket, with poll implementation
- vfs_fat_file: allow file obj to respond to ioctl flush request
- modbtree: add method to sync the database
- modbtree: rename "sync" method to "flush" for consistency
- modframebuf: add hline, vline, rect and line methods
- machine_spi: provide reusable software SPI class
- modframebuf: make framebuf implement the buffer protocol
- modframebuf: store underlying buffer object to prevent GC free
- modutimeq: copy of current moduheapq with timeq support for refactoring
- modutimeq: refactor into optimized class
- modutimeq: make time_less_than be actually "less than", not less/eq

lib:
- utils/interrupt_char: use core-provided mp_kbd_exception if enabled

drivers:
- display/ssd1306.py: update to use FrameBuffer not FrameBuffer1
- onewire: enable pull up on data pin
- onewire/ds18x20: fix negative temperature calc for DS18B20

tools:
- tinytest-codegen: blacklist recently added uheapq_timeq test (qemu-arm)
- pyboard.py: refactor so target is not reset between scripts/cmd
- mpy-tool.py: add support for OPT_CACHE_MAP_LOOKUP_IN_BYTECODE

tests:
- micropython: add test for import from within viper function
- use read() instead of readall()
- basics: add test for logical constant folding
- micropython: add test for creating traceback without allocation
- micropython: move alloc-less traceback test to separate test file
- extmod: improve ujson coverage
- basics: improve user class coverage
- basics: add test for dict.fromkeys where arg is a generator
- basics: add tests for if-expressions
- basics: change dict_fromkeys test so it doesn't use generators
- basics: enable tests for list slice getting with 3rd arg
- extmod/vfs_fat_fileio: add test for constructor of FileIO type
- extmod/btree1: exercise btree.flush()
- extmod/framebuf1: add basics tests for hline, vline, rect, line
- update for required byteorder arg for int.from_bytes()/to_bytes()
- extmod: improve moductypes test coverage
- extmod: improve modframebuf test coverage
- micropython: get heapalloc_traceback test running on baremetal
- struct*: make skippable
- basics: improve mpz test coverage
- float/builtin_float_round: test round() with second arg
- basics/builtin_dir: add test for dir() of a type
- basics: add test for builtin locals()
- basics/set_pop: improve coverage of set functions
- run-tests: for REPL tests make sure the REPL is exited at the end
- basics: improve test coverage for generators
- import: add a test which uses ... in from-import statement
- add tests to improve coverage of runtime.c
- add tests to improve coverage of objarray.c
- extmod: add test for utimeq module
- basics/lexer: add a test for newline-escaping within a string
- add a coverage test for printing the parse-tree
- utimeq_stable: test for partial stability of utimeq queuing
- heapalloc_inst_call: test for no alloc for simple object calls
- basics: add tests for parsing of ints with base 36
- basics: add tests to improve coverage of binary.c
- micropython: add test for micropython.stack_use() function
- extmod: improve ubinascii.c test coverage
- thread: improve modthread.c test coverage
- cmdline: improve repl.c autocomplete test coverage
- unix: improve runtime_utils.c test coverage
- pyb/uart: update test to match recent change to UART timeout_char
- run-tests: allow to skip set tests
- improve warning.c test coverage
- float: improve formatfloat.c test coverage using Python
- unix: improve formatfloat.c test coverage using C
- unix/extra_coverage: add basic tests to import frozen str and mpy
- types1: split out set type test to set_types
- array: allow to skip test if "array" is unavailable
- unix/extra_coverage: add tests for importing frozen packages

unix port:
- rename define for unix moduselect to MICROPY_PY_USELECT_POSIX
- Makefile: update freedos target for change of USELECT config name
- enable utimeq module
- main: allow to print the parse tree in coverage build
- Makefile: make "coverage_test" target mirror Travis test actions
- moduselect: if file object passed to .register(), return it in .poll()
- Makefile: split long line for coverage target, easier to modify
- enable and add basic frozen str and frozen mpy in coverage build
- Makefile: allow cache-map-lookup optimisation with frozen bytecode

windows port:
- enable READER_POSIX to get access to lexer_new_from_file

stmhal port:
- dma: de-init the DMA peripheral properly before initialising
- i2c: add option to I2C to enable/disable use of DMA transfers
- i2c: reset the I2C peripheral if there was an error on the bus
- rename mp_hal_pin_set_af to _config_alt, to simplify alt config
- upgrade to STM32CubeF4 v1.13.0 - CMSIS/Device 2.5.1
- upgrade to STM32CubeF4 v1.13.0 - HAL v1.5.1
- apply STM32CubeF4 v1.13.1 patch - upgrade HAL driver to v1.5.2
- hal/i2c: reapply HAL commit ea040a4 for f4
- hal/sd: reapply HAL commit 1d7fb82 for f4
- hal: reapply HAL commit 9db719b for f4
- hal/rcc: reapply HAL commit c568a2b for f4
- hal/sd: reapply HAL commit 09de030 for f4
- boards: configure all F4 boards to work with new HAL
- make-stmconst.py: fix regex's to work with current CMSIS
- i2c: handle I2C IRQs
- dma: precalculate register base and bitshift on handle init
- dma: mark DMA sate as READY even if HAL_DMA_Init is skipped
- can: clear FIFO flags in IRQ handler
- i2c: provide custom IRQ handlers
- hal: do not include <stdio.h> in HAL headers
- mphalport.h: use single GPIOx->BSRR register
- make-stmconst.py: add support for files with invalid utf8 bytes
- update HALCOMMITS due to change to hal
- make-stmconst.py: restore Python 2 compatibility
- update HALCOMMITS due to change to hal
- moduselect: move to extmod/ for reuse by other ports
- i2c: use the HAL's I2C IRQ handler for F7 and L4 MCUs
- updates to get F411 MCUs compiling with latest ST HAL
- i2c: remove use of legacy I2C_NOSTRETCH_DISABLED option
- add beginnings of port-specific machine.I2C implementation
- i2c: add support for I2C4 hardware block on F7 MCUs
- i2c: expose the pyb_i2c_obj_t struct and some relevant functions
- machine_i2c: provide HW implementation of I2C peripherals for F4
- add support for flash storage on STM32F415
- add back GPIO_BSRRL and GPIO_BSRRH constants to stm module
- add OpenOCD configuration for STM32L4
- add address parameters to openocd config files
- adc: add "mask" selection parameter to pyb.ADCAll constructor
- adc: provide more accurate measure of VBAT and VREFINT
- adc: make ADCAll.read_core_temp return accurate float value
- adc: add ADCAll.read_vref method, returning "3.3v" value
- adc: add support for F767 MCU
- adc: make channel "16" always map to the temperature sensor
- sdcard: clean/invalidate cache before DMA transfers with SD card
- moduos: implement POSIX behaviour of rename, allow to overwrite
- adc: use constants from new HAL version
- refactor UART configuration to use pin objects
- uart: add support for UART7 and UART8 on F7 MCUs
- uart: add check that UART id is valid for the given board
- cmsis: update STM32F7 CMSIS device include files to V1.1.2
- hal: update ST32CubeF7 HAL files to V1.1.2
- port of f4 hal commit c568a2b to updated f7 hal
- port of f4 hal commit 09de030 to updated f7 hal
- port of f4 hal commit 1d7fb82 to updated f7 hal
- declare and initialise PrescTables for F7 MCUs
- boards/STM32F7DISC: define LSE_STARTUP_TIMEOUT
- hal: update HALCOMMITS due to change in f7 hal files
- refactor to use extmod implementation of software SPI class
- cmsis: add CMSIS file stm32f767xx.h, V1.1.2
- add NUCLEO_F767ZI board, with openocd config for stm32f7
- cmsis: add CMSIS file stm32f769xx.h, V1.1.2
- add STM32F769DISC board files
- move PY_SYS_PLATFORM config from board to general config file
- mpconfigport: add weak-module links for io, collections, random
- rename mp_const_vcp_interrupt to mp_kbd_exception
- usb: always use the mp_kbd_exception object for VCP interrupt
- use core-provided keyboard exception object
- led: properly initialise timer handle to zero before using it
- mphalport.h: explicitly use HAL's GPIO constants for pull modes
- usrsw: use mp_hal_pin_config function instead of HAL_GPIO_Init
- led: use mp_hal_pin_config function instead of HAL_GPIO_Init
- sdcard: use mp_hal_pin_config function instead of HAL_GPIO_Init
- add support for STM32 Nucleo64 L476RG
- uart: provide a custom function to transmit over UART
- uart: increase inter-character timeout by 1ms
- enable utimeq module

cc3200 port:
- tools/smoke.py: change readall() to read()
- pybspi: remove static mode=SPI.MASTER parameter for latest HW API
- mods/pybspi: remove SPI.MASTER constant, it's no longer needed
- update for moduselect moved to extmod/
- re-add support for UART REPL (MICROPY_STDIO_UART setting)
- enable UART REPL by default
- README: (re)add information about accessing REPL on serial
- make: rename "deploy" target to "deploy-ota"
- add targets to erase flash, deploy firmware using cc3200tool
- README: reorganize and update to the current state of affairs
- modwlan: add network.WLAN.print_ver() diagnostic function

esp8266 port:
- enable uselect module
- move websocket_helper.py from scripts to modules for frozen BC
- refactor to use extmod implementation of software SPI class
- mpconfigport_512k: disable framebuf module for 512k build
- enable native emitter for Xtensa arch
- enable inline Xtensa assembler
- add "ota" target to produce firmware binary for use with yaota8266
- use core-provided keyboard exception object
- add "erase" target to Makefile, to erase entire flash
- when doing GC be sure to trace the memory holding native code
- modesp: flash_user_start(): support configuration with yaota8266
- force relinking OTA firmware image if built after normal one
- scripts/inisetup: dump FS starting sector/size on error
- Makefile: produce OTA firmware as firmware-ota.bin
- modesp: make check_fw() work with OTA firmware
- enable utimeq module
- Makefile: put firmware-ota.bin in build/, for consistency
- modules/flashbdev: add RESERVED_SECS before the filesystem
- modules/flashbdev: remove code to patch bootloader flash size
- modules/flashbdev: remove now-unused function set_bl_flash_size
- modules/flashbdev: change RESERVED_SECS to 0

zephyr port:
- add .gitignore to ignore Zephyr's "outdir" directory
- zephyr_getchar: update to Zephyr 1.6 unified kernel API
- switch to Zephyr 1.6 unified kernel API
- support raw REPL
- implement soft reset feature
- main: initialize sys.path and sys.argv
- use core-provided keyboard exception object
- uart_core: access console UART directly instead of printk() hack
- enable slice subscription

docs:
- remove references to readall() and update stream read() docs
- library/index: elaborate on u-modules
- library/machine.I2C: refine definitions of I2C methods
- library/pyb.Accel: add hardware note about pins used by accel
- library/pyb.UART: added clarification about timeouts
- library/pyb.UART: moved writechar doc to sit with other writes
- esp8266/tutorial: update intro to add Getting the firmware section
- library/machine.I2C: fix I2C constructor docs to match impl
- esp8266/tutorial: close socket after reading page content
- esp8266/general: add "Scarcity of runtime resources" section
- library/esp: document esp.set_native_code_location() function
- library/esp: remove para and add further warning about flash
- usocket: clarify that socket timeout raises OSError exception

travis:
- build STM32 F7 and L4 boards under Travis CI
- include persistent bytecode with floats in coverage tests

examples:
- hwapi: button_led: Add GPIO pin read example
- hwapi: add soft_pwm example converted to uasyncio
- http_client: use read() instead of readall()
- hwapi: add uasyncio example of fading 2 LEDs in parallel
- hwapi: add example for machine.time_pulse_us()
- hwapi: add hwconfig for console tracing of LED operations
- accellog.py: change 1: to /sd/, and update comment about FS
- hwapi/hwconfig_console: don't alloc memory in value()

13 files changed, 161 insertions, 73 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 5ff8d640b7..6026aee56a 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -99,7 +99,7 @@ copyright = '2014-2016, Damien P. George and contributors'
 # The short X.Y version.
 version = '1.8'
 # The full version, including alpha/beta/rc tags.
-release = '1.8.6'
+release = '1.8.7'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst
index 04afed46ed..cd659f80a9 100644
--- a/docs/esp8266/general.rst
+++ b/docs/esp8266/general.rst
@@ -58,6 +58,17 @@ For your convenience, some of technical specifications are provided below:
   and always-available BootROM bootloader, ESP8266 is not brickable.
 
 
+Scarcity of runtime resources
+-----------------------------
+
+ESP8266 has very modest resources (first of all, RAM memory). So, please
+avoid allocating too big container objects (lists, dictionaries) and
+buffers. There is also no full-fledged OS to keep track of resources
+and automatically clean them up, so that's the task of a user/user
+application: please be sure to close open files, sockets, etc. as soon
+as possible after use.
+
+
 Boot process
 ------------
 
diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst
index 87d4463406..fe824cffff 100644
--- a/docs/esp8266/tutorial/intro.rst
+++ b/docs/esp8266/tutorial/intro.rst
@@ -35,11 +35,30 @@ If your board has a USB connector on it then most likely it is powered through
 this when connected to your PC.  Otherwise you will need to power it directly.
 Please refer to the documentation for your board for further details.
 
+Getting the firmware
+--------------------
+
+The first thing you need to do is download the most recent MicroPython firmware 
+.bin file to load onto your ESP8266 device. You can download it from the  
+`MicroPython downloads page <http://micropython.org/download#esp8266>`_.
+From here, you have 3 main choices
+
+* Stable firmware builds for 1024kb modules and above.
+* Daily firmware builds for 1024kb modules and above.
+* Daily firmware builds for 512kb modules.
+
+The best bet is nearly always to go for the Stable firmware builds.
+An exception to this though is if you have an ESP8266 module with only 512kb
+of onboard storage. You can easily tell by trying to load a Stable firmware 
+build and if you get the error below, then you may have to use the Daily 
+firmware builds for 512kb modules.
+    WARNING: Unlikely to work as data goes beyond end of flash.
+
 Deploying the firmware
 ----------------------
 
-The very first thing you need to do is put the MicroPython firmware (compiled
-code) on your ESP8266 device.  There are two main steps to do this: first you
+Once you have the MicroPython firmware (compiled code), you need to load it onto 
+your ESP8266 device.  There are two main steps to do this: first you
 need to put your device in boot-loader mode, and second you need to copy across
 the firmware.  The exact procedure for these steps is highly dependent on the
 particular board and you will need to refer to its documentation for details.
diff --git a/docs/esp8266/tutorial/network_tcp.rst b/docs/esp8266/tutorial/network_tcp.rst
index 80a494721d..26a2f469ce 100644
--- a/docs/esp8266/tutorial/network_tcp.rst
+++ b/docs/esp8266/tutorial/network_tcp.rst
@@ -72,6 +72,7 @@ Let's define a function that can download and print a URL::
                 print(str(data, 'utf8'), end='')
             else:
                 break
+        s.close()
 
 Make sure that you import the socket module before running this function.  Then
 you can try::
diff --git a/docs/library/esp.rst b/docs/library/esp.rst
index 0836bba72e..8cafb92cd0 100644
--- a/docs/library/esp.rst
+++ b/docs/library/esp.rst
@@ -45,3 +45,39 @@ Functions
 .. function:: flash_write(byte_offset, bytes)
 
 .. function:: flash_erase(sector_no)
+
+.. function:: set_native_code_location(start, length)
+
+    Set the location that native code will be placed for execution after it is
+    compiled.  Native code is emitted when the ``@micropython.native``,
+    ``@micropython.viper`` and ``@micropython.asm_xtensa`` decorators are applied
+    to a function.  The ESP8266 must execute code from either iRAM or the lower
+    1MByte of flash (which is memory mapped), and this function controls the
+    location.
+
+    If `start` and `length` are both `None` then the native code location is
+    set to the unused portion of memory at the end of the iRAM1 region.  The
+    size of this unused portion depends on the firmware and is typically quite
+    small (around 500 bytes), and is enough to store a few very small
+    functions.  The advantage of using this iRAM1 region is that it does not
+    get worn out by writing to it.
+
+    If neither `start` nor `length` are `None` then they should be integers.
+    `start` should specify the byte offset from the beginning of the flash at
+    which native code should be stored.  `length` specifies how many bytes of
+    flash from `start` can be used to store native code.  `start` and `length`
+    should be multiples of the sector size (being 4096 bytes).  The flash will
+    be automatically erased before writing to it so be sure to use a region of
+    flash that is not otherwise used, for example by the firmware or the
+    filesystem.
+
+    When using the flash to store native code `start+length` must be less
+    than or equal to 1MByte.  Note that the flash can be worn out if repeated
+    erasures (and writes) are made so use this feature sparingly.
+    In particular, native code needs to be recompiled and rewritten to flash
+    on each boot (including wake from deepsleep).
+
+    In both cases above, using iRAM1 or flash, if there is no more room left
+    in the specified region then the use of a native decorator on a function
+    will lead to `MemoryError` exception being raised during compilation of
+    that function.
diff --git a/docs/library/index.rst b/docs/library/index.rst
index b06c806f73..3621f9d880 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -36,15 +36,20 @@ Python standard libraries and micro-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.
+library.  Some modules below use a standard Python name, but prefixed with "u",
+e.g. ``ujson`` instead of ``json``. This is to signify that such a module is
+micro-library, i.e. implements only a subset of CPython module functionality.
+By naming them differently, a user has a choice to write a Python-level module
+to extend functionality for better compatibility with CPython (indeed, this is
+what done by micropython-lib project mentioned above).
+
+On some embedded platforms, where it may be cumbersome to add Python-level
+wrapper modules to achieve naming compatibility with CPython, micro-modules
+are available both 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
 
diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst
index f5820f103e..cdeb246ebb 100644
--- a/docs/library/machine.I2C.rst
+++ b/docs/library/machine.I2C.rst
@@ -49,12 +49,23 @@ 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).
 
-.. only:: port_esp8266
+.. only:: not port_wipy
+
+    .. class:: I2C(id=-1, \*, scl, sda, freq=400000)
 
-    .. class:: I2C(scl, sda, \*, freq=400000)
+       Construct and return a new I2C object using the following parameters:
 
-       Construct and return a new I2C object.
-       See the init method below for a description of the arguments.
+          - `id` identifies the particular I2C peripheral.  The default
+            value of -1 selects a software implementation of I2C which can
+            work (in most cases) with arbitrary pins for SCL and SDA.
+            If `id` is -1 then `scl` and `sda` must be specified.  Other
+            allowed values for `id` depend on the particular port/board,
+            and specifying `scl` and `sda` may or may not be required or
+            allowed in this case.
+          - `scl` should be a pin object specifying the pin to use for SCL.
+          - `sda` should be a pin object specifying the pin to use for SDA.
+          - `freq` should be an integer which sets the maximum frequency
+            for SCL.
 
 General Methods
 ---------------
@@ -102,29 +113,31 @@ control over the bus, otherwise the standard methods (see below) can be used.
 
 .. method:: I2C.start()
 
-   Send a start bit on the bus (SDA transitions to low while SCL is high).
+   Generate a START condition on the bus (SDA transitions to low while SCL is high).
 
    Availability: ESP8266.
 
 .. method:: I2C.stop()
 
-   Send a stop bit on the bus (SDA transitions to high while SCL is high).
+   Generate a STOP condition on the bus (SDA transitions to high while SCL is high).
 
    Availability: ESP8266.
 
-.. method:: I2C.readinto(buf)
+.. method:: I2C.readinto(buf, nack=True)
 
    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.
+   receiving all but the last byte.  After the last byte is received, if `nack`
+   is true then a NACK will be sent, otherwise an ACK will be sent (and in this
+   case the slave assumes more bytes are going to be read in a later call).
 
    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.
+   Write the bytes from `buf` to the bus.  Checks that an ACK is received
+   after each byte and stops transmitting the remaining bytes if a NACK is
+   received.  The function returns the number of ACKs that were received.
 
    Availability: ESP8266.
 
@@ -134,29 +147,27 @@ Standard bus operations
 The following methods implement the standard I2C master read and write
 operations that target a given slave device.
 
-.. method:: I2C.readfrom(addr, nbytes)
+.. method:: I2C.readfrom(addr, nbytes, stop=True)
 
    Read `nbytes` from the slave specified by `addr`.
+   If `stop` is true then a STOP condition is generated at the end of the transfer.
    Returns a `bytes` object with the data read.
 
-.. method:: I2C.readfrom_into(addr, buf)
+.. method:: I2C.readfrom_into(addr, buf, stop=True)
 
    Read into `buf` from the slave specified by `addr`.
    The number of bytes read will be the length of `buf`.
+   If `stop` is true then a STOP condition is generated at the end of the transfer.
 
-   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 method returns `None`.
 
-   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.
+.. method:: I2C.writeto(addr, buf, stop=True)
 
-   On WiPy the return value is the number of bytes written.  Otherwise the
-   return value is `None`.
+   Write the bytes from `buf` to the slave specified by `addr`.  If a
+   NACK is received following the write of a byte from `buf` then the
+   remaining bytes are not sent.  If `stop` is true then a STOP condition is
+   generated at the end of the transfer, even if a NACK is received.
+   The function returns the number of ACKs that were received.
 
 Memory operations
 -----------------
diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst
index f832cf4664..0b6b24e894 100644
--- a/docs/library/machine.UART.rst
+++ b/docs/library/machine.UART.rst
@@ -31,7 +31,7 @@ A UART object acts like a stream object and reading and writing is done
 using the standard stream methods::
 
     uart.read(10)       # read 10 characters, returns a bytes object
-    uart.readall()      # read all available characters
+    uart.read()         # read all available characters
     uart.readline()     # read a line
     uart.readinto(buf)  # read and store into the given buffer
     uart.write('abc')   # write the 3 characters
@@ -95,17 +95,12 @@ Methods
 
 .. method:: UART.read([nbytes])
 
-   Read characters.  If ``nbytes`` is specified then read at most that many bytes.
+   Read characters.  If ``nbytes`` is specified then read at most that many bytes,
+   otherwise read as much data as possible.
 
    Return value: a bytes object containing the bytes read in.  Returns ``None``
    on timeout.
 
-.. method:: UART.readall()
-
-   Read as much data as possible.
-
-   Return value: a bytes object or ``None`` on timeout.
-
 .. method:: UART.readinto(buf[, nbytes])
 
    Read bytes into the ``buf``.  If ``nbytes`` is specified then read at most
diff --git a/docs/library/pyb.Accel.rst b/docs/library/pyb.Accel.rst
index 2ae357fe70..061996485f 100644
--- a/docs/library/pyb.Accel.rst
+++ b/docs/library/pyb.Accel.rst
@@ -46,3 +46,11 @@ Methods
 .. method:: Accel.z()
 
    Get the z-axis value.
+
+Hardware Note
+-------------
+
+The accelerometer uses I2C bus 1 to communicate with the processor. Consequently
+when readings are being taken pins X9 and X10 should be unused (other than for
+I2C). Other devices using those pins, and which therefore cannot be used
+concurrently, are UART 1 and Timer 4 channels 1 and 2.
diff --git a/docs/library/pyb.I2C.rst b/docs/library/pyb.I2C.rst
index 67131feec0..7400318902 100644
--- a/docs/library/pyb.I2C.rst
+++ b/docs/library/pyb.I2C.rst
@@ -92,7 +92,7 @@ Methods
 
 .. only:: port_pyboard
 
-    .. method:: I2C.init(mode, \*, addr=0x12, baudrate=400000, gencall=False)
+    .. method:: I2C.init(mode, \*, addr=0x12, baudrate=400000, gencall=False, dma=False)
 
       Initialise the I2C bus with the given parameters:
 
@@ -100,6 +100,9 @@ Methods
          - ``addr`` is the 7-bit address (only sensible for a slave)
          - ``baudrate`` is the SCL clock rate (only sensible for a master)
          - ``gencall`` is whether to support general call mode
+         - ``dma`` is whether to allow the use of DMA for the I2C transfers (note
+           that DMA transfers have more precise timing but currently do not handle bus
+           errors properly)
 
     .. method:: I2C.is_ready(addr)
 
diff --git a/docs/library/pyb.UART.rst b/docs/library/pyb.UART.rst
index 4a692469f8..76f347ffa8 100644
--- a/docs/library/pyb.UART.rst
+++ b/docs/library/pyb.UART.rst
@@ -27,7 +27,7 @@ A UART object acts like a stream object and reading and writing is done
 using the standard stream methods::
 
     uart.read(10)       # read 10 characters, returns a bytes object
-    uart.readall()      # read all available characters
+    uart.read()         # read all available characters
     uart.readline()     # read a line
     uart.readinto(buf)  # read and store into the given buffer
     uart.write('abc')   # write the 3 characters
@@ -87,8 +87,8 @@ Methods
          - ``stop`` is the number of stop bits, 1 or 2.
          - ``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.
+         - ``timeout`` is the timeout in milliseconds to wait for writing/reading the first character.
+         - ``timeout_char`` is the timeout in milliseconds to wait between characters while writing or reading.
          - ``read_buf_len`` is the character length of the read buffer (0 to disable).
     
        This method will raise an exception if the baudrate could not be set within
@@ -111,17 +111,15 @@ Methods
 
        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``. 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.
 
+   If ``nbytes`` is not given then the method reads as much data as possible.  It
+   returns after the timeout has elapsed.
+
    .. only:: port_pyboard
 
       *Note:* for 9 bit characters each character takes two bytes, ``nbytes`` must
@@ -130,12 +128,6 @@ Methods
       Return value: a bytes object containing the bytes read in.  Returns ``None``
       on timeout.
 
-.. method:: UART.readall()
-
-   Read as much data as possible. Returns after the timeout has elapsed.
-
-   Return value: a bytes object or ``None`` if timeout prevents any data being read.
-
 .. method:: UART.readchar()
 
    Receive a single character on the bus.
@@ -170,6 +162,13 @@ Methods
       Return value: number of bytes written. If a timeout occurs and no bytes
       were written returns ``None``.
 
+.. only:: port_pyboard
+
+    .. method:: UART.writechar(char)
+
+      Write a single character on the bus.  ``char`` is an integer to write.
+      Return value: ``None``. See note below if CTS flow control is used.
+
 .. method:: UART.sendbreak()
 
    Send a break condition on the bus.  This drives the bus low for a duration
diff --git a/docs/library/pyb.USB_VCP.rst b/docs/library/pyb.USB_VCP.rst
index 4e34af2586..4c4fe45168 100644
--- a/docs/library/pyb.USB_VCP.rst
+++ b/docs/library/pyb.USB_VCP.rst
@@ -44,16 +44,12 @@ Methods
 .. method:: USB_VCP.read([nbytes])
 
    Read at most ``nbytes`` from the serial device and return them as a
-   bytes object.  If ``nbytes`` is not specified then the method acts as
-   ``readall()``. USB_VCP stream implicitly works in non-blocking mode,
+   bytes object.  If ``nbytes`` is not specified then the method reads
+   all available bytes from the serial device.
+   USB_VCP stream implicitly works in non-blocking mode,
    so if no pending data available, this method will return immediately
    with ``None`` value.
 
-.. method:: USB_VCP.readall()
-
-   Read all available bytes from the serial device and return them as
-   a bytes object, or ``None`` if no pending data available.
-
 .. method:: USB_VCP.readinto(buf, [maxlen])
 
    Read bytes from the serial device and store them into ``buf``, which
diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst
index 9b279e5ba7..c46e8f4c53 100644
--- a/docs/library/usocket.rst
+++ b/docs/library/usocket.rst
@@ -149,10 +149,18 @@ Methods
 
        Set a timeout on blocking socket operations. The value argument can be a nonnegative floating
        point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations
-       will raise a timeout exception if the timeout period value has elapsed before the operation has
+       will raise an ``OSError`` exception if the timeout period value has elapsed before the operation has
        completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket
        is put in blocking mode.
 
+       .. admonition:: Difference to CPython
+          :class: attention
+
+          CPython raises a ``socket.timeout`` exception in case of timeout,
+          which is an ``OSError`` subclass. MicroPython raises an OSError directly
+          instead. If you use ``except OSError:`` to catch the exception,
+          your code will work both in MicroPython and CPython.
+
     .. method:: socket.setblocking(flag)
 
        Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking,
@@ -178,14 +186,10 @@ Methods
           Closing the file object returned by makefile() WILL close the
           original socket as well.
 
-    .. method:: socket.read(size)
+    .. method:: socket.read([size])
 
        Read up to size bytes from the socket. Return a bytes object. If ``size`` is not given, it
-       behaves just like ``socket.readall()``, see below.
-
-    .. method:: socket.readall()
-
-       Read all data available from the socket until ``EOF``. This function will not return until
+       reads all data available from the socket until ``EOF``; as such the method will not return until
        the socket is closed.
 
     .. method:: socket.readinto(buf[, nbytes])