Merge tag 'v1.9.3'

Introduction of ports subdirectory where all ports are moved to

The main change in this release is the introduction of a "ports/"
subdirectory at the top-level of the repository, and all of the ports are
moved here.  In the process the "stmhal" port is renamed to "stm32" to
better reflect the MCU that it targets.  In addition, the STM32 CMSIS and
HAL sources are moved to a new submodule called "stm32lib".

The bytecode has changed in this release, compared to the previous release,
and as a consequence the .mpy version number has increased to version 3.
This means that scripts compiled with the previous mpy-cross must be
recompiled to work with this new version.

There have also been various enhancements and optimisations, such as:
check for valid UTF-8 when creating str objects, support for reverse
special binary operations like __radd__, full domain checking in the math
module, support for floor-division and modulo in the viper emitter,
and addition of stack overflow checking when executing a regex.

The stm32 port sees improved support for F7 MCUs, addition of a new board
B_L475E_IOT01A based on the STM32L475, and support for the Wiznet W5500
chipset along with improved socket behaviour.

A detailed list of changes follows.

py core:
- objstr: startswith, endswith: check arg to be a string
- nlrx86,x64: replace #define of defined() with portable macro usage
- objtype: handle NotImplemented return from binary special methods
- objtype: mp_obj_class_lookup: improve debug logging
- map: remove unused new/free functions
- make m_malloc_fail() have void return type, since it doesn't return
- modstruct: in struct.pack, stop converting if there are no args left
- modstruct: check and prevent buffer-read overflow in struct unpacking
- modstruct: check and prevent buffer-write overflow in struct packing
- nlrthumb: get working again on standard Thumb arch (ie not Thumb2)
- objfloat: fix binary ops with incompatible objects
- obj: fix comparison of float/complex NaN with itself
- objtype: implement fallback for instance inplace special methods
- objtuple: properly implement comparison with incompatible types
- objstr: add check for valid UTF-8 when making a str from bytes
- objlist: properly implement comparison with incompatible types
- runtime0.h: move relational ops to the beginning of mp_binary_op_t
- runtime0.h: move MP_BINARY_OP_DIVMOD to the end of mp_binary_op_t
- objtype: make sure mp_binary_op_method_name has full size again
- runtime0.h: put inplace arith ops in front of normal operations
- builtinhelp: simplify code slightly by extracting object type
- runtime: implement dispatch for "reverse op" special methods
- nlrx86: fix building for Android/x86
- builtinhelp: change signature of help text var from pointer to array
- runtime.h: change empty mp_warning macro so var-args are non empty
- modbuiltins: implement abs() by dispatching to MP_UNARY_OP_ABS
- {objfloat,objcomplex}: optimise MP_UNARY_OP_ABS by reusing variables
- mpconfig.h: add note that using computed gotos in VM is not C99
- objstr: strip: don't strip "\0" by default
- objexcept: prevent infinite recursion when allocating exceptions
- stream: remove unnecessary checks for NULL return from vstr_add_len
- vstr: raise a RuntimeError if fixed vstr buffer overflows
- vm: use lowercase letter at start of exception message
- persistentcode: define mp_raw_code_save_file() for any unix target
- add config option to print warnings/errors to stderr
- objfloat: support raising a negative number to a fractional power
- objset: simplify set and frozenset by separating their locals dicts
- objset: check that RHS of a binary op is a set/frozenset
- objset: include the failed key in a KeyError raised from set.remove
- objtype: change type of enum-to-qstr table to uint16_t to save space
- objstr: make empty bytes object have a null-terminating byte
- mpprint: only check for null string printing when NDEBUG not defined
- objtype: clean up unary- and binary-op enum-to-qstr mapping tables
- persistentcode: bump .mpy version number to version 3
- bc: update opcode_format_table to match the bytecode
- modmath: add full checks for math domain errors
- modmath: convert log2 macro into a function
- formatfloat: don't print the negative sign of a NaN value
- formatfloat: use standard isinf, isnan funcs instead of custom ones
- modbuiltins: use existing utf8_get_char helper in builtin ord func
- emitnative: implement floor-division and modulo for viper emitter
- objtype: use CPython compatible method name for sizeof
- objtype: fit qstrs for special methods in byte type
- objtype: define all special methods if requested
- objtype: introduce MICROPY_PY_ALL_INPLACE_SPECIAL_METHODS

extmod:
- modubinascii: only include uzlib/tinf.h when it's really needed
- modussl_mbedtls: allow to compile with MBEDTLS_DEBUG_C disabled
- machine_pinbase: put PinBase singleton in ROM
- re1.5: upgrade to v0.8.2, adds hook for stack overflow checking
- modure: add stack overflow checking when executing a regex
- uos_dupterm: update uos.dupterm() and helper funcs to have index
- uos_dupterm: swallow any errors from dupterm closing the stream
- vfs: replace VLA in proxy func with small, static sized array
- modussl: add finaliser support for ussl objects
- modussl_mbedtls: allow to compile with unix coverage build

lib:
- add new submodule, stm32lib containing STM32 CMSIS and HAL source
- embed/abort_: use mp_raise_msg helper function
- libm: fix tanhf so that it correctly handles +/- infinity args
- libm: remove implementation of log2f, use MP_NEED_LOG2 instead
- axtls: update, support for SSL_EAGAIN return code
- berkeley-db-1.xx: update, allow to override MINCACHE, DEFPSIZE

drivers:
- memory/spiflash: change from hard-coded soft SPI to generic SPI
- display/ssd1306.py: improve performance of graphics methods
- nrf24l01: make nRF24L01 test script more portable
- display/ssd1306: implement SSD1306_I2C poweron method
- display/ssd1306: make poweron() work the same with SSD1306_SPI
- wiznet5k: improve the performance of socket ops with threading
- wiznet5k: get low-level W5500 driver working

tools:
- upip: upgrade to 1.2.2
- pyboard: use repr() when quoting data in error messages
- pyboard: update docstring for additional device support

tests:
- object_new: better messages, check user __new__() method
- class_new: add checks for __init__ being called and other improvements
- class_new: add another testcase for __new__/__init__ interaction
- class_inplace_op: test for inplace op fallback to normal one
- run-bench-tests: update locations of executables, now in ports/
- class_reverse_op: test for reverse arith ops special methods
- run-tests: skip class_inplace_op for minimal profile
- run-tests: fix copy-paste mistake in var name
- cpydiff: add cases for locals() discrepancies
- extmod: add test for ure regexes leading to infinite recursion
- extmod: add test for '-' in character class in regex
- run-tests: close device under test using "finally"
- net_inet: update tls test to work with CPython and incl new site

unix port:
- rename modsocket.c to modusocket.c
- modusocket: remove #if MICROPY_SOCKET_EXTRA code blocks
- enable MICROPY_PY_REVERSE_SPECIAL_METHODS

stm32 port:
- modmachine: make machine.bootloader() work when MPU is enabled
- modmachine: improve support for sleep/deepsleep on F7 MCUs
- compute PLL freq table during build instead of at run time
- modmachine: for F7 MCU, save power by reducing internal volt reg
- boards/pllvalues.py: make script work with both Python 2 and 3
- Makefile: use lib/stm32lib instead of local cmsis and hal files
- remove cmsis and hal files, they are now a submodule
- Makefile: automatically fetch stm32lib submodule if needed
- update to new STM Cube HAL library
- fix clock initialisation of L4 MCUs
- rename stmhal port directory to stm32
- remove unused usbd_msc.c file
- boards: change remaining stm32f4xx_hal_conf.h to unix line ending
- boards: change linker scripts to use "K" instead of hex byte size
- boards: fix I2C1 pin mapping on NUCLEO_F401RE/F411RE boards
- i2c: when scanning for I2C devices only do 1 probe per address
- modnwwiznet5k: release the GIL on blocking network operations
- boards: add new board B_L475E_IOT01A based on STM32L475
- make-stmconst.py: make sure mpz const data lives in ROM
- timer: make pyb.Timer() instances persistent
- mpconfigport.h: add configuration for max periphs on L4 series
- usbdev: make the USBD callback struct const so it can go in ROM
- usbdev: change static function variable to non-static
- usbdev: put all CDC state in a struct
- usbdev: put all HID state in a struct
- usbdev: simplify CDC tx/rx buffer passing
- usbdev: simplify HID tx/rx buffer passing
- usbdev/core: add state parameter to all callback functions
- usbdev: put all state for the USB device driver in a struct
- usbdev: simplify pointers to MSC state and block dev operations
- usbdev: merge all global USB device state into a single struct
- usbdev: make device descriptor callbacks take a state pointer
- usbdev: move all the USB device descriptor state into its struct
- timer: enable ARPE so that timer freq can be changed smoothly
- modnwwiznet5k: get the IP address of an established socket
- boards: fix typos in stm32f767_af.csv table
- usbd_cdc_interface: don't reset CDC output buf on initialisation
- modnwwiznet5k: implement WIZNET5K.isconnected() method
- modusocket: make getaddrinfo() work when passed an IP address
- modusocket: return OSError(-2) if getaddrinfo fails
- mpconfigport.h: add MICROPY_THREAD_YIELD() macro
- modnwwiznet5k: add support for W5500 Ethernet chip
- modnwwiznet5k: increase SPI bus speed to 42MHz
- modnwwiznet5k: implement stream ioctl for the Wiznet driver
- mphalport: improve efficiency of mp_hal_stdout_tx_strn_cooked
- make uos.dupterm() conform to specs by using extmod version

cc3200 port:
- enable micropython.kbd_intr() method
- use standard implementation of keyboard interrupt

esp8266 port:
- rename axtls_helpers.c to posix_helpers.c
- posix_helpers: set ENOMEM on memory alloc failure
- set DEFPSIZE=1024, MINCACHE=3 for "btree" module
- esp_mphal: send data in chunks to mp_uos_dupterm_tx_strn
- modnetwork: add "bssid" keyword arg to WLAN.connect() method
- modules/webrepl_setup: add info about allowed password length

zephyr port:
- Makefile: revamp "test" target after ports were moved to ports/
- use CONFIG_NET_APP_SETTINGS to setup initial network addresses
- switch to interrupt-driven pull-style console

pic16bit port:
- add definition of SEEK_SET to unistd.h

docs:
- pyboard/tutorial: add "timeout=0" to UART in pass-through example
- more xrefs to "MicroPython port" in glossary
- library/network: fix ref to "socket" module (should be "usocket")
- machine.Signal: improve style/grammar and add usage example
- library: add description of "index" parameter to uos.dupterm()
- library/micropython: fix typo in RST formatting
- library/framebuf.rst: generalise constructor to all colour formats
- btree: describe page caching policy of the underlying implementation
- esp8266/tutorial: update neopixel with example of using 4 bbp
- library/network: clarify usage of "bssid" arg in connect() method
- pyboard/quickref: add info for Switch, RTC, CAN, Accel classes
- pyboard/tutorial: update now that yellow LED also supports PWM
- esp8266/quickref: add quickref info for RTC class
- library: add missing cross-ref links for classes in pyb module
- library/network: update docs to state that W5500 is supported
- uselect: document one-shot polling mode
- usocket: elaborate descriptions
- usocket: document inet_ntop(), inet_pton()
- library/network: add dhcp_hostname parameter
- reference/isr_rules: minor typo correction
- ussl: fix module name refs and use "MicroPython port" term
- esp8266/general: add section on TLS limitations
- usocket: document that settimeout() isn't supported by all ports
- ure: add "|" (alternative) to the list of supported operators
- reference/isr_rules.rst: add tutorial on use of micropython.schedule()

travis:
- use --upgrade when pip is installing cpp-coveralls
- update build command now that stm32 Wiznet config has changed

examples:
- hwconfig_console: add .on()/.off() methods

all:
- convert mp_uint_t to mp_unary_op_t/mp_binary_op_t where appropriate
- convert remaining "mp_uint_t n_args" to "size_t n_args"
- make new ports/ sub-directory and move all ports there
- update Makefiles and others to build with new ports/ dir layout
- remove inclusion of internal py header files
- use NULL instead of "" when calling mp_raise exception helpers

README:
- update "Dependencies" section
- add explicit section on contributing
- add gcc and arm-none-eabi-newlib to list of required components

.gitattributes:
- remove obsolete entries for stmhal/hal, stmhal/cmsis
- add entries for files that will move to ports/ dir

16 files changed, 207 insertions, 37 deletions

diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst
index e23acb469..96a454532 100644
--- a/docs/esp8266/general.rst
+++ b/docs/esp8266/general.rst
@@ -145,3 +145,43 @@ or by an exeption, for example using try/finally::
         # Use sock
     finally:
         sock.close()
+
+
+SSL/TLS limitations
+~~~~~~~~~~~~~~~~~~~
+
+ESP8266 uses `axTLS <http://axtls.sourceforge.net/>`_ library, which is one
+of the smallest TLS libraries with the compatible licensing. However, it
+also has some known issues/limitations:
+
+1. No support for Diffie-Hellman (DH) key exchange and Elliptic-curve
+   cryptography (ECC). This means it can't work with sites which force
+   the use of these features (it works ok with classic RSA certifactes).
+2. Half-duplex communication nature. axTLS uses a single buffer for both
+   sending and receiving, which leads to considerable memory saving and
+   works well with protocols like HTTP. But there may be problems with
+   protocols which don't follow classic request-response model.
+
+Besides axTLS own limitations, the configuration used for MicroPython is
+highly optimized for code size, which leads to additional limitations
+(these may be lifted in the future):
+
+3. Optimized RSA algorithms are not enabled, which may lead to slow
+   SSL handshakes.
+4. Stored sessions are not supported (may allow faster repeated connections
+   to the same site in some circumstances).
+
+Besides axTLS specific limitations described above, there's another generic
+limitation with usage of TLS on the low-memory devices:
+
+5. The TLS standard specifies the maximum length of the TLS record (unit
+   of TLS communication, the entire record must be buffered before it can
+   be processed) as 16KB. That's almost half of the available ESP8266 memory,
+   and inside a more or less advanced application would be hard to allocate
+   due to memory fragmentation issues. As a compromise, a smaller buffer is
+   used, with the idea that the most interesting usage for SSL would be
+   accessing various REST APIs, which usually require much smaller messages.
+   The buffers size is on the order of 5KB, and is adjusted from time to
+   time, taking as a reference being able to access https://google.com .
+   The smaller buffer hower means that some sites can't be accessed using
+   it, and it's not possible to stream large amounts of data.
diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst
index ccf6365c8..c510e4064 100644
--- a/docs/esp8266/quickref.rst
+++ b/docs/esp8266/quickref.rst
@@ -223,6 +223,17 @@ and is accessed via the :ref:`machine.I2C <machine.I2C>` class::
     buf = bytearray(10)     # create a buffer with 10 bytes
     i2c.writeto(0x3a, buf)  # write the given buffer to the slave
 
+Real time clock (RTC)
+---------------------
+
+See :ref:`machine.RTC <machine.RTC>` ::
+
+    from machine import RTC
+
+    rtc = RTC()
+    rtc.datetime((2017, 8, 23, 1, 12, 48, 0, 0)) # set a specific date and time
+    rtc.datetime() # get date and time
+
 Deep-sleep mode
 ---------------
 
diff --git a/docs/library/network.rst b/docs/library/network.rst
index def6bee74..99a7c242c 100644
--- a/docs/library/network.rst
+++ b/docs/library/network.rst
@@ -72,8 +72,7 @@ parameter should be `id`.
        connection parameters. For various medium types, there are different
        sets of predefined/recommended parameters, among them:
 
-       * WiFi: *bssid* keyword to connect by BSSID (MAC address) instead
-         of access point name
+       * WiFi: *bssid* keyword to connect to a specific BSSID (MAC address)
 
     .. method:: disconnect()
 
@@ -225,7 +224,9 @@ parameter should be `id`.
     ==============
     
     This class allows you to control WIZnet5x00 Ethernet adaptors based on
-    the W5200 and W5500 chipsets (only W5200 tested).
+    the W5200 and W5500 chipsets.  The particular chipset that is supported
+    by the firmware is selected at compile-time via the MICROPY_PY_WIZNET5K
+    option.
     
     Example usage::
     
@@ -269,6 +270,11 @@ parameter should be `id`.
     Methods
     -------
     
+    .. method:: wiznet5k.isconnected()
+
+       Returns ``True`` if the physical Ethernet link is connected and up.
+       Returns ``False`` otherwise.
+
     .. method:: wiznet5k.ifconfig([(ip, subnet, gateway, dns)])
     
        Get/set IP address, subnet mask, gateway and DNS.
@@ -333,9 +339,12 @@ parameter should be `id`.
         argument is passed. Otherwise, query current state if no argument is
         provided. Most other methods require active interface.
 
-    .. method:: wlan.connect(ssid, password)
+    .. method:: wlan.connect(ssid=None, password=None, \*, bssid=None)
 
         Connect to the specified wireless network, using the specified password.
+        If *bssid* is given then the connection will be restricted to the
+        access-point with that MAC address (the *ssid* must also be specified
+        in this case).
 
     .. method:: wlan.disconnect()
 
@@ -413,16 +422,17 @@ parameter should be `id`.
        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)
-       =========  ===========
+       =============  ===========
+       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)
+       dhcp_hostname  The DHCP hostname to use
+       =============  ===========
 
 
 
diff --git a/docs/library/pyb.Accel.rst b/docs/library/pyb.Accel.rst
index 061996485..9ade5c5c8 100644
--- a/docs/library/pyb.Accel.rst
+++ b/docs/library/pyb.Accel.rst
@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.Accel:
 
 class Accel -- accelerometer control
 ====================================
diff --git a/docs/library/pyb.CAN.rst b/docs/library/pyb.CAN.rst
index 9e71f12b0..232d04d96 100644
--- a/docs/library/pyb.CAN.rst
+++ b/docs/library/pyb.CAN.rst
@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.CAN:
 
 class CAN -- controller area network communication bus
 ======================================================
diff --git a/docs/library/pyb.LCD.rst b/docs/library/pyb.LCD.rst
index 83cf890b6..5ab127edc 100644
--- a/docs/library/pyb.LCD.rst
+++ b/docs/library/pyb.LCD.rst
@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.LCD:
 
 class LCD -- LCD control for the LCD touch-sensor pyskin
 ========================================================
diff --git a/docs/library/pyb.Switch.rst b/docs/library/pyb.Switch.rst
index 0d5dc63b7..e5ab6bd84 100644
--- a/docs/library/pyb.Switch.rst
+++ b/docs/library/pyb.Switch.rst
@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.Switch:
 
 class Switch -- switch object
 =============================
diff --git a/docs/library/pyb.USB_HID.rst b/docs/library/pyb.USB_HID.rst
index 7d17c3099..702704435 100644
--- a/docs/library/pyb.USB_HID.rst
+++ b/docs/library/pyb.USB_HID.rst
@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.USB_HID:
 
 class USB_HID -- USB Human Interface Device (HID)
 =================================================
diff --git a/docs/library/pyb.USB_VCP.rst b/docs/library/pyb.USB_VCP.rst
index 4c4fe4516..80cc40cdd 100644
--- a/docs/library/pyb.USB_VCP.rst
+++ b/docs/library/pyb.USB_VCP.rst
@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.USB_VCP:
 
 class USB_VCP -- USB virtual comm port
 ======================================
diff --git a/docs/library/ure.rst b/docs/library/ure.rst
index 67f4f54a1..ebae1db5f 100644
--- a/docs/library/ure.rst
+++ b/docs/library/ure.rst
@@ -34,6 +34,8 @@ Supported operators are:
 
 ``'+?'``
 
+``'|'``
+
 ``'()'``
    Grouping. Each group is capturing (a substring it captures can be accessed
    with `match.group()` method).
diff --git a/docs/library/uselect.rst b/docs/library/uselect.rst
index e330207db..beffce69a 100644
--- a/docs/library/uselect.rst
+++ b/docs/library/uselect.rst
@@ -66,12 +66,18 @@ Methods
 
       Tuples returned may contain more than 2 elements as described above.
 
-.. method:: poll.ipoll([timeout])
+.. method:: poll.ipoll(timeout=-1, flags=0)
 
    Like :meth:`poll.poll`, but instead returns an iterator which yields
-   callee-owned tuples. This function provides efficient, allocation-free
+   `callee-owned tuples`. This function provides efficient, allocation-free
    way to poll on streams.
 
+   If *flags* is 1, one-shot behavior for events is employed: streams for
+   which events happened, event mask will be automatically reset (equivalent
+   to ``poll.modify(obj, 0)``), so new events for such a stream won't be
+   processed until new mask is set with `poll.modify()`. This behavior is
+   useful for asynchronous I/O schedulers.
+
    .. admonition:: Difference to CPython
       :class: attention
 
diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst
index dfdcd68bc..fab05b652 100644
--- a/docs/library/usocket.rst
+++ b/docs/library/usocket.rst
@@ -68,7 +68,16 @@ Functions
 
 .. function:: socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP)
 
-   Create a new socket using the given address family, socket type and protocol number.
+   Create a new socket using the given address family, socket type and
+   protocol number. Note that specifying *proto* in most cases is not
+   required (and not recommended, as some MicroPython ports may omit
+   ``IPPROTO_*`` constants). Instead, *type* argument will select needed
+   protocol automatically::
+
+        # Create STREAM TCP socket
+        socket(AF_INET, SOCK_STREAM)
+        # Create DGRAM UDP socket
+        socket(AF_INET, SOCK_DGRAM)
 
 .. function:: getaddrinfo(host, port)
 
@@ -80,8 +89,8 @@ Functions
 
    The following example shows how to connect to a given url::
 
-      s = socket.socket()
-      s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1])
+      s = usocket.socket()
+      s.connect(usocket.getaddrinfo('www.micropython.org', 80)[0][-1])
 
    .. admonition:: Difference to CPython
       :class: attention
@@ -96,13 +105,29 @@ Functions
       from an exception object). The use of negative values is a provisional
       detail which may change in the future.
 
+.. function:: inet_ntop(af, bin_addr)
+
+   Convert a binary network address *bin_addr* of the given address family *af*
+   to a textual representation::
+
+        >>> usocket.inet_ntop(usocket.AF_INET, b"\x7f\0\0\1")
+        '127.0.0.1'
+
+.. function:: inet_pton(af, txt_addr)
+
+   Convert a textual network address *txt_addr* of the given address family *af*
+   to a binary representation::
+
+        >>> usocket.inet_pton(usocket.AF_INET, "1.2.3.4")
+        b'\x01\x02\x03\x04'
+
 Constants
 ---------
 
 .. data:: AF_INET
           AF_INET6
 
-   Address family types. Availability depends on a particular board.
+   Address family types. Availability depends on a particular `MicroPython port`.
 
 .. data:: SOCK_STREAM
           SOCK_DGRAM
@@ -112,7 +137,11 @@ Constants
 .. data:: IPPROTO_UDP
           IPPROTO_TCP
 
-   IP protocol numbers.
+   IP protocol numbers. Availability depends on a particular `MicroPython port`.
+   Note that you don't need to specify these in a call to `usocket.socket()`,
+   because `SOCK_STREAM` socket type automatically selects `IPPROTO_TCP`, and
+   `SOCK_DGRAM` - `IPPROTO_UDP`. Thus, the only real use of these constants
+   is as an argument to `setsockopt()`.
 
 .. data:: usocket.SOL_*
 
@@ -208,12 +237,30 @@ Methods
 
 .. method:: socket.settimeout(value)
 
+   **Note**: Not every port supports this method, see below.
+
    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 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.
 
+   Not every `MicroPython port` supports this method. A more portable and
+   generic solution is to use `uselect.poll` object. This allows to wait on
+   multiple objects at the same time (and not just on sockets, but on generic
+   stream objects which support polling). Example::
+
+        # Instead of:
+        s.settimeout(1.0)  # time in seconds
+        s.read(10)  # may timeout
+
+        # Use:
+        poller = uselect.poll()
+        poller.register(s, uselect.POLLIN)
+        res = poller.poll(1000)  # time in milliseconds
+        if not res:
+            # s is still not ready for input, i.e. operation timed out
+
    .. admonition:: Difference to CPython
       :class: attention
 
@@ -281,7 +328,7 @@ Methods
 
    Return value: number of bytes written.
 
-.. exception:: socket.error
+.. exception:: usocket.error
 
    MicroPython does NOT have this exception.
 
diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst
index c71b283cc..3ec609f67 100644
--- a/docs/library/ussl.rst
+++ b/docs/library/ussl.rst
@@ -13,7 +13,7 @@ facilities for network sockets, both client-side and server-side.
 Functions
 ---------
 
-.. function:: ssl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None)
+.. function:: ussl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None)
 
    Takes a stream *sock* (usually usocket.socket instance of ``SOCK_STREAM`` type),
    and returns an instance of ssl.SSLSocket, which wraps the underlying stream in
@@ -23,12 +23,12 @@ Functions
    server-side SSL socket should be created from a normal socket returned from
    `accept()` on a non-SSL listening server socket.
 
-   Depending on the underlying module implementation for a particular board,
-   some or all keyword arguments above may be not supported.
+   Depending on the underlying module implementation in a particular
+   `MicroPython port`, some or all keyword arguments above may be not supported.
 
 .. warning::
 
-   Some implementations of ``ssl`` module do NOT validate server certificates,
+   Some implementations of ``ussl`` module do NOT validate server certificates,
    which makes an SSL connection established prone to man-in-the-middle attacks.
 
 Exceptions
@@ -41,8 +41,8 @@ Exceptions
 Constants
 ---------
 
-.. data:: ssl.CERT_NONE
-          ssl.CERT_OPTIONAL
-          ssl.CERT_REQUIRED
+.. data:: ussl.CERT_NONE
+          ussl.CERT_OPTIONAL
+          ussl.CERT_REQUIRED
 
     Supported values for *cert_reqs* parameter.
diff --git a/docs/pyboard/quickref.rst b/docs/pyboard/quickref.rst
index 5690dddb0..48798aad3 100644
--- a/docs/pyboard/quickref.rst
+++ b/docs/pyboard/quickref.rst
@@ -39,17 +39,32 @@ Use the :mod:`time <utime>` module::
     start = time.ticks_ms() # get value of millisecond counter
     delta = time.ticks_diff(time.ticks_ms(), start) # compute time difference
 
-LEDs
-----
+Internal LEDs
+-------------
 
 See :ref:`pyb.LED <pyb.LED>`. ::
 
     from pyb import LED
 
-    led = LED(1) # red led
+    led = LED(1) # 1=red, 2=green, 3=yellow, 4=blue
     led.toggle()
     led.on()
     led.off()
+    
+    # LEDs 3 and 4 support PWM intensity (0-255)
+    LED(4).intensity()    # get intensity
+    LED(4).intensity(128) # set intensity to half
+
+Internal switch
+---------------
+
+See :ref:`pyb.Switch <pyb.Switch>`. ::
+
+    from pyb import Switch
+
+    sw = Switch()
+    sw.value() # returns True or False
+    sw.callback(lambda: pyb.LED(1).toggle())
 
 Pins and GPIO
 -------------
@@ -99,6 +114,17 @@ See :ref:`pyb.Timer <pyb.Timer>`. ::
     tim.freq(0.5) # 0.5 Hz
     tim.callback(lambda t: pyb.LED(1).toggle())
 
+RTC (real time clock)
+---------------------
+
+See :ref:`pyb.RTC <pyb.RTC>` ::
+
+    from pyb import RTC
+
+    rtc = RTC()
+    rtc.datetime((2017, 8, 23, 1, 12, 48, 0, 0)) # set a specific date and time
+    rtc.datetime() # get date and time
+
 PWM (pulse width modulation)
 ----------------------------
 
@@ -167,3 +193,25 @@ See :ref:`pyb.I2C <pyb.I2C>`. ::
     i2c.recv(5, 0x42) # receive 5 bytes from slave
     i2c.mem_read(2, 0x42, 0x10) # read 2 bytes from slave 0x42, slave memory 0x10
     i2c.mem_write('xy', 0x42, 0x10) # write 2 bytes to slave 0x42, slave memory 0x10
+
+CAN bus (controller area network)
+---------------------------------
+
+See :ref:`pyb.CAN <pyb.CAN>`. ::
+
+    from pyb import CAN
+
+    can = CAN(1, CAN.LOOPBACK)
+    can.setfilter(0, CAN.LIST16, 0, (123, 124, 125, 126))
+    can.send('message!', 123)   # send a message with id 123
+    can.recv(0)                 # receive message on FIFO 0
+
+Internal accelerometer
+----------------------
+
+See :ref:`pyb.Accel <pyb.Accel>`. ::
+
+    from pyb import Accel
+
+    accel = Accel()
+    print(accel.x(), accel.y(), accel.z(), accel.tilt())
diff --git a/docs/pyboard/tutorial/leds.rst b/docs/pyboard/tutorial/leds.rst
index 763eedf01..6b05f5db0 100644
--- a/docs/pyboard/tutorial/leds.rst
+++ b/docs/pyboard/tutorial/leds.rst
@@ -60,10 +60,10 @@ One problem you might find is that if you stop the script and then start it agai
         for l in leds:
             l.off()
 
-The Fourth Special LED
-----------------------
+The Special LEDs
+----------------
 
-The blue LED is special. As well as turning it on and off, you can control the intensity using the intensity() method. This takes a number between 0 and 255 that determines how bright it is. The following script makes the blue LED gradually brighter then turns it off again. ::
+The yellow and blue LEDs are special. As well as turning them on and off, you can control their intensity using the intensity() method. This takes a number between 0 and 255 that determines how bright it is. The following script makes the blue LED gradually brighter then turns it off again. ::
 
     led = pyb.LED(4)
     intensity = 0
@@ -72,4 +72,4 @@ The blue LED is special. As well as turning it on and off, you can control the i
         led.intensity(intensity)
         pyb.delay(20)
 
-You can call intensity() on the other LEDs but they can only be off or on. 0 sets them off and any other number up to 255 turns them on.
+You can call intensity() on LEDs 1 and 2 but they can only be off or on. 0 sets them off and any other number up to 255 turns them on.
diff --git a/docs/reference/isr_rules.rst b/docs/reference/isr_rules.rst
index 5009f30f7..2db261c09 100644
--- a/docs/reference/isr_rules.rst
+++ b/docs/reference/isr_rules.rst
@@ -80,7 +80,7 @@ example causes two LED's to flash at different rates.
             self.led.toggle()
 
     red = Foo(pyb.Timer(4, freq=1), pyb.LED(1))
-    greeen = Foo(pyb.Timer(2, freq=0.8), pyb.LED(2))
+    green = Foo(pyb.Timer(2, freq=0.8), pyb.LED(2))
 
 In this example the ``red`` instance associates timer 4 with LED 1: when a timer 4 interrupt occurs ``red.cb()``
 is called causing LED 1 to change state. The ``green`` instance operates similarly: a timer 2 interrupt