Merge remote-tracking branch 'upstream/master' into esp32

Author: dpgeorge

.gitattributes

@@ -17,7 +17,6 @@ tests/basics/string_cr_conversion.py -text
 tests/basics/string_crlf_conversion.py -text
 ports/stm32/pybcdc.inf_template -text
 ports/stm32/usbd_* -text
-ports/stm32/boards/*/stm32f4xx_hal_conf.h -text
 ports/stm32/usbdev/** -text
 ports/stm32/usbhost/** -text
 ports/cc3200/hal/aes.c -text

.travis.yml

@@ -19,9 +19,8 @@ before_script:
   - sudo apt-get install -y --force-yes gcc-arm-none-eabi
   # For teensy build
   - sudo apt-get install realpath
-  # For coverage testing
-  # cpp-coveralls 0.4 conflicts with urllib3 preinstalled in Travis VM
-  - sudo pip install cpp-coveralls==0.3.12
+  # For coverage testing (upgrade is used to get latest urllib3 version)
+  - sudo pip install --upgrade cpp-coveralls
   - gcc --version
   - arm-none-eabi-gcc --version
   - python3 --version
@@ -40,7 +39,7 @@ script:
   - make -C ports/bare-arm
   - make -C ports/qemu-arm test
   - make -C ports/stm32
-  - make -C ports/stm32 BOARD=PYBV11 MICROPY_PY_WIZNET5K=1 MICROPY_PY_CC3K=1
+  - make -C ports/stm32 BOARD=PYBV11 MICROPY_PY_WIZNET5K=5200 MICROPY_PY_CC3K=1
   - make -C ports/stm32 BOARD=STM32F769DISC
   - make -C ports/stm32 BOARD=STM32L476DISC
   - make -C ports/teensy

README.md

@@ -84,7 +84,7 @@ Additional components:
 The subdirectories above may include READMEs with additional info.
 
 "make" is used to build the components, or "gmake" on BSD-based systems.
-You will also need bash and Python (at least 2.7 or 3.3).
+You will also need bash, gcc, and Python (at least 2.7 or 3.3).
 
 The Unix version
 ----------------
@@ -97,6 +97,7 @@ Alternatively, fallback implementation based on setjmp/longjmp can be used.
 
 To build (see section below for required dependencies):
 
+    $ git submodule update --init
     $ cd ports/unix
     $ make axtls
     $ make
@@ -129,43 +130,48 @@ Standard library modules come from
 External dependencies
 ---------------------
 
-Building Unix version requires some dependencies installed. For
+Building MicroPython ports may require some dependencies installed.
+
+For Unix port, `libffi` library and `pkg-config` tool are required. On
 Debian/Ubuntu/Mint derivative Linux distros, install `build-essential`
 (includes toolchain and make), `libffi-dev`, and `pkg-config` packages.
 
-Other dependencies can be built together with MicroPython. Oftentimes,
-you need to do this to enable extra features or capabilities. To build
+Other dependencies can be built together with MicroPython. This may
+be required to enable extra features or capabilities, and in recent
+versions of MicroPython, these may be enabled by default. To build
 these additional dependencies, first fetch git submodules for them:
 
     $ git submodule update --init
 
-Use this same command to get the latest versions of dependencies, as
-they are updated from time to time. After that, in `ports/unix/` dir, execute:
+Use the same command to get the latest versions of dependencies, as
+they are updated from time to time. After that, in the port directory
+(e.g. `ports/unix/`), execute:
 
     $ make deplibs
 
 This will build all available dependencies (regardless whether they
 are used or not). If you intend to build MicroPython with additional
 options (like cross-compiling), the same set of options should be passed
-to `make deplibs`. To actually enabled use of dependencies, edit
+to `make deplibs`. To actually enable/disable use of dependencies, edit
 `ports/unix/mpconfigport.mk` file, which has inline descriptions of the options.
-For example, to build SSL module (required for `upip` tool described above),
-set `MICROPY_PY_USSL` to 1.
+For example, to build SSL module (required for `upip` tool described above,
+and so enabled by dfeault), `MICROPY_PY_USSL` should be set to 1.
 
-In `ports/unix/mpconfigport.mk`, you can also disable some dependencies enabled
-by default, like FFI support, which requires libffi development files to
-be installed.
+For some ports, building required dependences is transparent, and happens
+automatically. They still need to be fetched with the git submodule command
+above.
 
 The STM32 version
 -----------------
 
 The "stm32" port requires an ARM compiler, arm-none-eabi-gcc, and associated
-bin-utils.  For those using Arch Linux, you need arm-none-eabi-binutils and
-arm-none-eabi-gcc packages.  Otherwise, try here:
+bin-utils.  For those using Arch Linux, you need arm-none-eabi-binutils,
+arm-none-eabi-gcc and arm-none-eabi-newlib packages.  Otherwise, try here:
 https://launchpad.net/gcc-arm-embedded
 
 To build:
 
+    $ git submodule update --init
     $ cd ports/stm32
     $ make
 
@@ -181,3 +187,13 @@ This will use the included `tools/pydfu.py` script.  If flashing the firmware
 does not work it may be because you don't have the correct permissions, and
 need to use `sudo make deploy`.
 See the README.md file in the ports/stm32/ directory for further details.
+
+Contributing
+------------
+
+MicroPython is an open-source project and welcomes contributions. To be
+productive, please be sure to follow the
+[Contributors' Guidelines](https://github.com/micropython/micropython/wiki/ContributorGuidelines)
+and the [Code Conventions](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md).
+Note that MicroPython is licenced under the MIT license, and all contributions
+should follow this license.

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
 ---------------
 

docs/esp8266/tutorial/neopixel.rst

@@ -20,6 +20,20 @@ To set the colour of pixels use::
     >>> np[1] = (0, 128, 0) # set to green, half brightness
     >>> np[2] = (0, 0, 64)  # set to blue, quarter brightness
 
+For LEDs with more than 3 colours, such as RGBW pixels or RGBY pixels, the
+NeoPixel class takes a ``bpp`` parameter. To setup a NeoPixel object for an
+RGBW Pixel, do the following::
+
+    >>> import machine, neopixel
+    >>> np = neopixel.NeoPixel(machine.Pin(4), 8, bpp=4)
+
+In a 4-bpp mode, remember to use 4-tuples instead of 3-tuples to set the colour.
+For example to set the first three pixels use::
+
+    >>> np[0] = (255, 0, 0, 128) # Orange in an RGBY Setup
+    >>> np[1] = (0, 255, 0, 128) # Yellow-green in an RGBY Setup
+    >>> np[2] = (0, 0, 255, 128) # Green-blue in an RGBY Setup
+
 Then use the ``write()`` method to output the colours to the LEDs::
 
     >>> np.write()

docs/library/btree.rst

@@ -76,20 +76,24 @@ Example::
 Functions
 ---------
 
-.. function:: open(stream, \*, flags=0, cachesize=0, pagesize=0, minkeypage=0)
+.. function:: open(stream, \*, flags=0, pagesize=0, cachesize=0, minkeypage=0)
 
    Open a database from a random-access `stream` (like an open file). All
    other parameters are optional and keyword-only, and allow to tweak advanced
    parameters of the database operation (most users will not need them):
 
    * *flags* - Currently unused.
-   * *cachesize* - Suggested maximum memory cache size in bytes. For a
-     board with enough memory using larger values may improve performance.
-     The value is only a recommendation, the module may use more memory if
-     values set too low.
    * *pagesize* - Page size used for the nodes in BTree. Acceptable range
-     is 512-65536. If 0, underlying I/O block size will be used (the best
-     compromise between memory usage and performance).
+     is 512-65536. If 0, a port-specific default will be used, optimized for
+     port's memory usage and/or performance.
+   * *cachesize* - Suggested memory cache size in bytes. For a
+     board with enough memory using larger values may improve performance.
+     Cache policy is as follows: entire cache is not allocated at once;
+     instead, accessing a new page in database will allocate a memory buffer
+     for it, until value specified by *cachesize* is reached. Then, these
+     buffers will be managed using LRU (least recently used) policy. More
+     buffers may still be allocated if needed (e.g., if a database contains
+     big keys and/or values). Allocated cache buffers aren't reclaimed.
    * *minkeypage* - Minimum number of keys to store per page. Default value
      of 0 equivalent to 2.
 

docs/library/framebuf.rst

@@ -38,9 +38,9 @@ Constructors
         - *width* is the width of the FrameBuffer in pixels
         - *height* is the height of the FrameBuffer in pixels
         - *format* specifies the type of pixel used in the FrameBuffer;
-          valid values are ``framebuf.MVLSB``, ``framebuf.RGB565``
-          and ``framebuf.GS4_HMSB``. MVLSB is monochrome 1-bit color,
-          RGB565 is RGB 16-bit color, and GS4_HMSB is grayscale 4-bit color.
+          permissible values are listed under Constants below. These set the
+          number of bits used to encode a color value and the layout of these
+          bits in *buffer*.
           Where a color value c is passed to a method, c is a small integer
           with an encoding that is dependent on the format of the FrameBuffer.
         - *stride* is the number of pixels between each horizontal line
@@ -110,8 +110,9 @@ Other methods
     corresponding color will be considered transparent: all pixels with that
     color value will not be drawn.
 
-    This method works between FrameBuffer's utilising different formats, but the
-    resulting colors may be unexpected due to the mismatch in color formats.
+    This method works between FrameBuffer instances utilising different formats,
+    but the resulting colors may be unexpected due to the mismatch in color
+    formats.
 
 Constants
 ---------

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
+       =============  ===========
 
 
 

docs/library/pyb.Accel.rst

@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.Accel:
 
 class Accel -- accelerometer control
 ====================================

docs/library/pyb.CAN.rst

@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.CAN:
 
 class CAN -- controller area network communication bus
 ======================================================

docs/library/pyb.LCD.rst

@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.LCD:
 
 class LCD -- LCD control for the LCD touch-sensor pyskin
 ========================================================

docs/library/pyb.Switch.rst

@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.Switch:
 
 class Switch -- switch object
 =============================

docs/library/pyb.USB_HID.rst

@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.USB_HID:
 
 class USB_HID -- USB Human Interface Device (HID)
 =================================================

docs/library/pyb.USB_VCP.rst

@@ -1,4 +1,5 @@
 .. currentmodule:: pyb
+.. _pyb.USB_VCP:
 
 class USB_VCP -- USB virtual comm port
 ======================================

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