Merge pull request #40 from adafruit/main

Update from adafruit main

10 files changed, 31 insertions, 424 deletions

diff --git a/docs/design_guide.rst b/docs/design_guide.rst
index 75825893a..7a8c76b50 100644
--- a/docs/design_guide.rst
+++ b/docs/design_guide.rst
@@ -520,7 +520,9 @@ properties.
 +-----------------------+-----------------------+-------------------------------------------------------------------------+
 | ``temperature``       | float                 | degrees centigrade                                                      |
 +-----------------------+-----------------------+-------------------------------------------------------------------------+
-| ``eCO2``              | float                 | equivalent CO2 in ppm                                                   |
+| ``CO2``               | float                 | measured CO2 in ppm                                                     |
++-----------------------+-----------------------+-------------------------------------------------------------------------+
+| ``eCO2``              | float                 | equivalent/estimated CO2 in ppm (estimated from some other measurement) |
 +-----------------------+-----------------------+-------------------------------------------------------------------------+
 | ``TVOC``              | float                 | Total Volatile Organic Compounds in ppb                                 |
 +-----------------------+-----------------------+-------------------------------------------------------------------------+
diff --git a/docs/index.rst b/docs/index.rst
index 6dadddfc1..3ee76fdd8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -46,6 +46,7 @@ Full Table of Contents
    ../BUILDING
    ../CODE_OF_CONDUCT
    ../license.rst
+   ../WEBUSB_README
 
 Indices and tables
 ==================
diff --git a/docs/library/uerrno.rst b/docs/library/errno.rst
index 72f71f0aa..96777b205 100644
--- a/docs/library/uerrno.rst
+++ b/docs/library/errno.rst
@@ -1,9 +1,7 @@
-:mod:`uerrno` -- system error codes
+:mod:`errno` -- system error codes
 ===================================
 
-.. include:: ../templates/unsupported_in_circuitpython.inc
-
-.. module:: uerrno
+.. module:: errno
    :synopsis: system error codes
 
 |see_cpython_module| :mod:`cpython:errno`.
@@ -22,7 +20,7 @@ Constants
         try:
             os.mkdir("my_dir")
         except OSError as exc:
-            if exc.args[0] == uerrno.EEXIST:
+            if exc.args[0] == errno.EEXIST:
                 print("Directory already exists")
 
 .. data:: errorcode
@@ -30,5 +28,5 @@ Constants
     Dictionary mapping numeric error codes to strings with symbolic error
     code (see above)::
 
-        >>> print(uerrno.errorcode[uerrno.EEXIST])
+        >>> print(errno.errorcode[uerrno.EEXIST])
         EEXIST
diff --git a/docs/library/esp.rst b/docs/library/esp.rst
deleted file mode 100644
index 125aaa890..000000000
--- a/docs/library/esp.rst
+++ /dev/null
@@ -1,85 +0,0 @@
-:mod:`esp` --- functions related to the ESP8266
-===============================================
-
-.. include:: ../templates/unsupported_in_circuitpython.inc
-
-.. module:: esp
-    :synopsis: functions related to the ESP8266
-
-The ``esp`` module contains specific functions related to the ESP8266 module.
-
-
-Functions
----------
-
-.. function:: sleep_type([sleep_type])
-
-    Get or set the sleep type.
-
-    If the *sleep_type* parameter is provided, sets the sleep type to its
-    value. If the function is called without parameters, returns the current
-    sleep type.
-
-    The possible sleep types are defined as constants:
-
-        * ``SLEEP_NONE`` -- all functions enabled,
-        * ``SLEEP_MODEM`` -- modem sleep, shuts down the WiFi Modem circuit.
-        * ``SLEEP_LIGHT`` -- light sleep, shuts down the WiFi Modem circuit
-          and suspends the processor periodically.
-
-    The system enters the set sleep mode automatically when possible.
-
-.. function:: deepsleep(time=0)
-
-    Enter deep sleep.
-
-    The whole module powers down, except for the RTC clock circuit, which can
-    be used to restart the module after the specified time if the pin 16 is
-    connected to the reset pin. Otherwise the module will sleep until manually
-    reset.
-
-.. 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)
-
-.. 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 e91387242..181ff0109 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -6,35 +6,21 @@ MicroPython libraries
 Python standard libraries and micro-libraries
 ---------------------------------------------
 
-These libraries are inherited from MicroPython.
-They are similar to the standard Python libraries with the same name
-or with the "u" prefix dropped.
+The libraries below are inherited from MicroPython.
+They are similar to the standard Python libraries with the same name.
 They implement a subset of or a variant of the corresponding
 standard Python library.
 
-.. warning::
-
-   Though these MicroPython-based libraries are available in CircuitPython,
-   their functionality may change in the future, perhaps significantly.
-   As CircuitPython continues to develop, new versions of these libraries will
-   be created that are more compliant with the standard Python libraries.
-   You may need to change your code later if you rely
-   on any non-standard functionality they currently provide.
-
 CircuitPython's long-term goal is that code written in CircuitPython
 using Python standard libraries will be runnable on CPython without changes.
 
-Some libraries below are not enabled on CircuitPython builds with
+These libraries are not enabled on CircuitPython builds with
 limited flash memory, usually on non-Express builds:
-``uerrno``, ``ure``.
-
-Some libraries are not currently enabled in any CircuitPython build, but may be in the future:
-``uio``, ``ujson``, ``uzlib``.
+``binascii``, ``errno``, ``json``, ``re``.
 
-Some libraries are only enabled only WiFi-capable ports (ESP8266, nRF)
-because they are typically used for network software:
-``binascii``, ``hashlib``, ``uheapq``, ``uselect``, ``ussl``.
-Not all of these are enabled on all WiFi-capable ports.
+These libraries are not currently enabled in any CircuitPython build, but may be in the future,
+with the ``u`` prefix dropped:
+``uctypes``, ``uhashlib``, ``uzlib``.
 
 .. toctree::
    :maxdepth: 1
@@ -44,13 +30,14 @@ Not all of these are enabled on all WiFi-capable ports.
    array.rst
    binascii.rst
    collections.rst
+   errno.rst
    gc.rst
    hashlib.rst
+   io.rst
+   json.rst
+   re.rst
    sys.rst
-   uerrno.rst
-   uio.rst
-   ujson.rst
-   ure.rst
+   uctypes.rst
    uselect.rst
    usocket.rst
    ussl.rst
@@ -59,8 +46,8 @@ Not all of these are enabled on all WiFi-capable ports.
 Omitted functions in the ``string`` library
 -------------------------------------------
 
-A few string operations are not enabled on CircuitPython
-M0 non-Express builds, due to limited flash memory:
+A few string operations are not enabled on small builds
+(usually non-Express), due to limited flash memory:
 ``string.center()``, ``string.partition()``, ``string.splitlines()``,
 ``string.reversed()``.
 
@@ -78,15 +65,3 @@ versions of CircuitPython.
    btree.rst
    framebuf.rst
    micropython.rst
-   network.rst
-   uctypes.rst
-
-Libraries specific to the ESP8266
----------------------------------
-
-The following libraries are specific to the ESP8266.
-
-.. toctree::
-  :maxdepth: 2
-
-  esp.rst
diff --git a/docs/library/uio.rst b/docs/library/io.rst
index d1f7c111f..37e3eb7c9 100644
--- a/docs/library/uio.rst
+++ b/docs/library/io.rst
@@ -1,9 +1,7 @@
-:mod:`uio` -- input/output streams
+:mod:`io` -- input/output streams
 ==================================
 
-.. include:: ../templates/unsupported_in_circuitpython.inc
-
-.. module:: uio
+.. module:: io
    :synopsis: input/output streams
 
 |see_cpython_module| :mod:`cpython:io`.
diff --git a/docs/library/ujson.rst b/docs/library/json.rst
index 4ed91f053..21574e556 100644
--- a/docs/library/ujson.rst
+++ b/docs/library/json.rst
@@ -1,9 +1,7 @@
-:mod:`ujson` -- JSON encoding and decoding
+:mod:`json` -- JSON encoding and decoding
 ==========================================
 
-.. include:: ../templates/unsupported_in_circuitpython.inc
-
-.. module:: ujson
+.. module:: json
    :synopsis: JSON encoding and decoding
 
 |see_cpython_module| :mod:`cpython:json`.
diff --git a/docs/library/network.rst b/docs/library/network.rst
deleted file mode 100644
index 3bd41150d..000000000
--- a/docs/library/network.rst
+++ /dev/null
@@ -1,278 +0,0 @@
-****************************************
-:mod:`network` --- network configuration
-****************************************
-
-.. include:: ../templates/unsupported_in_circuitpython.inc
-
-.. module:: network
-   :noindex:
-   :synopsis: network configuration
-
-This module provides network drivers and routing configuration. To use this
-module, a MicroPython variant/build with network capabilities must be installed.
-Network drivers for specific hardware are available within this module and are
-used to configure hardware network interface(s). Network services provided
-by configured interfaces are then available for use via the :mod:`usocket`
-module.
-
-For example::
-
-    # connect/ show IP config a specific network interface
-    # see below for examples of specific drivers
-    import network
-    import utime
-    nic = network.Driver(...)
-    if not nic.isconnected():
-        nic.connect()
-        print("Waiting for connection...")
-        while not nic.isconnected():
-            utime.sleep(1)
-    print(nic.ifconfig())
-
-    # now use usocket as usual
-    import usocket as socket
-    addr = socket.getaddrinfo('micropython.org', 80)[0][-1]
-    s = socket.socket()
-    s.connect(addr)
-    s.send(b'GET / HTTP/1.1\r\nHost: micropython.org\r\n\r\n')
-    data = s.recv(1000)
-    s.close()
-
-Common network adapter interface
-================================
-
-This section describes an (implied) abstract base class for all network
-interface classes implemented by ``MicroPython ports <MicroPython port>``
-for different hardware. This means that MicroPython does not actually
-provide ``AbstractNIC`` class, but any actual NIC class, as described
-in the following sections, implements methods as described here.
-
-.. class:: AbstractNIC(id=None, ...)
-
-Instantiate a network interface object. Parameters are network interface
-dependent. If there are more than one interface of the same type, the first
-parameter should be `id`.
-
-    .. method:: active([is_active])
-
-        Activate ("up") or deactivate ("down") the network interface, if
-        a boolean argument is passed. Otherwise, query current state if
-        no argument is provided. Most other methods require an active
-        interface (behavior of calling them on inactive interface is
-        undefined).
-
-    .. method:: connect([service_id, key=None, \*, ...])
-
-       Connect the interface to a network. This method is optional, and
-       available only for interfaces which are not "always connected".
-       If no parameters are given, connect to the default (or the only)
-       service. If a single parameter is given, it is the primary identifier
-       of a service to connect to. It may be accompanied by a key
-       (password) required to access said service. There can be further
-       arbitrary keyword-only parameters, depending on the networking medium
-       type and/or particular device. Parameters can be used to: a)
-       specify alternative service identifier types; b) provide additional
-       connection parameters. For various medium types, there are different
-       sets of predefined/recommended parameters, among them:
-
-       * WiFi: *bssid* keyword to connect to a specific BSSID (MAC address)
-
-    .. method:: disconnect()
-
-       Disconnect from network.
-
-    .. method:: isconnected()
-
-       Returns ``True`` if connected to network, otherwise returns ``False``.
-
-    .. method:: scan(\*, ...)
-
-       Scan for the available network services/connections. Returns a
-       list of tuples with discovered service parameters. For various
-       network media, there are different variants of predefined/
-       recommended tuple formats, among them:
-
-       * WiFi: (ssid, bssid, channel, RSSI, authmode, hidden). There
-         may be further fields, specific to a particular device.
-
-       The function may accept additional keyword arguments to filter scan
-       results (e.g. scan for a particular service, on a particular channel,
-       for services of a particular set, etc.), and to affect scan
-       duration and other parameters. Where possible, parameter names
-       should match those in connect().
-
-    .. method:: status()
-
-       Return detailed status of the interface, values are dependent
-       on the network medium/technology.
-
-    .. method:: ifconfig([(ip, subnet, gateway, dns)])
-
-       Get/set IP-level network interface parameters: 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:: config('param')
-                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
-       `ifconfig()`). These include network-specific and hardware-specific
-       parameters and status values. For setting parameters, the keyword argument
-       syntax should be used, and multiple parameters can be set at once. For
-       querying, a parameter name should be quoted as a string, and only one
-       parameter can be queried at a time::
-
-        # Set WiFi access point name (formally known as ESSID) and WiFi channel
-        ap.config(essid='My AP', channel=11)
-        # Query params one by one
-        print(ap.config('essid'))
-        print(ap.config('channel'))
-        # Extended status information also available this way
-        print(sta.config('rssi'))
-
-.. _network.WLAN:
-
-Functions
-=========
-
-.. function:: phy_mode([mode])
-
-    Get or set the PHY mode.
-
-    If the *mode* parameter is provided, sets the mode to its value. If
-    the function is called without parameters, returns the current mode.
-
-    The possible modes are defined as constants:
-        * ``MODE_11B`` -- IEEE 802.11b,
-        * ``MODE_11G`` -- IEEE 802.11g,
-        * ``MODE_11N`` -- IEEE 802.11n.
-
-class WLAN
-==========
-
-This class provides a driver for WiFi network processor in the ESP8266.  Example usage::
-
-    import network
-    # enable station interface and connect to WiFi access point
-    nic = network.WLAN(network.STA_IF)
-    nic.active(True)
-    nic.connect('your-ssid', 'your-password')
-    # now use sockets as usual
-
-Constructors
-------------
-.. class:: WLAN(interface_id)
-
-Create a WLAN network interface object. Supported interfaces are
-``network.STA_IF`` (station aka client, connects to upstream WiFi access
-points) and ``network.AP_IF`` (access point, allows other WiFi clients to
-connect). Availability of the methods below depends on interface type.
-For example, only STA interface may `connect()` to an access point.
-
-Methods
--------
-
-.. method:: wlan.active([is_active])
-
-    Activate ("up") or deactivate ("down") network interface, if boolean
-    argument is passed. Otherwise, query current state if no argument is
-    provided. Most other methods require active interface.
-
-.. 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()
-
-    Disconnect from the currently connected wireless network.
-
-.. method:: wlan.scan()
-
-    Scan for the available wireless networks.
-
-    Scanning is only possible on STA interface. Returns list of tuples with
-    the information about WiFi access points:
-
-        (ssid, bssid, channel, RSSI, authmode, hidden)
-
-    *bssid* is hardware address of an access point, in binary form, returned as
-    bytes object. You can use `binascii.hexlify()` to convert it to ASCII form.
-
-    There are five values for authmode:
-
-        * 0 -- open
-        * 1 -- WEP
-        * 2 -- WPA-PSK
-        * 3 -- WPA2-PSK
-        * 4 -- WPA/WPA2-PSK
-
-    and two for hidden:
-
-        * 0 -- visible
-        * 1 -- hidden
-
-.. method:: wlan.status()
-
-    Return the current status of the wireless connection.
-
-    The possible statuses are defined as constants:
-
-        * ``STAT_IDLE`` -- no connection and no activity,
-        * ``STAT_CONNECTING`` -- connecting in progress,
-        * ``STAT_WRONG_PASSWORD`` -- failed due to incorrect password,
-        * ``STAT_NO_AP_FOUND`` -- failed because no access point replied,
-        * ``STAT_CONNECT_FAIL`` -- failed due to other problems,
-        * ``STAT_GOT_IP`` -- connection successful.
-
-.. method:: wlan.isconnected()
-
-    In case of STA mode, returns ``True`` if connected to a WiFi access
-    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 parameters: 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')
-            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, parameters name should
-   be quoted as a string, and only one parameter can be queries at time::
-
-    # Set WiFi access point name (formally known as ESSID) and WiFi channel
-    ap.config(essid='My AP', channel=11)
-    # Query 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)
-   dhcp_hostname  The DHCP hostname to use
-   =============  ===========
diff --git a/docs/library/ure.rst b/docs/library/re.rst
index 4af182b01..bdcc9f52c 100644
--- a/docs/library/ure.rst
+++ b/docs/library/re.rst
@@ -1,9 +1,7 @@
-:mod:`ure` -- simple regular expressions
+:mod:`re` -- simple regular expressions
 ========================================
 
-.. include:: ../templates/unsupported_in_circuitpython.inc
-
-.. module:: ure
+.. module:: re
    :synopsis: regular expressions
 
 |see_cpython_module| :mod:`cpython:re`.
@@ -77,7 +75,7 @@ Regex objects
 -------------
 
 Compiled regular expression. Instances of this class are created using
-`ure.compile()`.
+`re.compile()`.
 
 .. method:: regex.match(string)
             regex.search(string)
diff --git a/docs/shared_bindings_matrix.py b/docs/shared_bindings_matrix.py
index f38c0b64a..e62b1d218 100644
--- a/docs/shared_bindings_matrix.py
+++ b/docs/shared_bindings_matrix.py
@@ -30,7 +30,7 @@ import sys
 
 from concurrent.futures import ThreadPoolExecutor
 
-SUPPORTED_PORTS = ['atmel-samd', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'stm']
+SUPPORTED_PORTS = ['atmel-samd', 'cxd56', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'raspberrypi', 'stm']
 
 def get_circuitpython_root_dir():
     """ The path to the root './circuitpython' directory
@@ -44,7 +44,7 @@ def get_shared_bindings():
     """ Get a list of modules in shared-bindings based on folder names
     """
     shared_bindings_dir = get_circuitpython_root_dir() / "shared-bindings"
-    return [item.name for item in shared_bindings_dir.iterdir()] + ["ulab"]
+    return [item.name for item in shared_bindings_dir.iterdir()] + ["binascii", "errno", "json", "re", "ulab"]
 
 
 def read_mpconfig():