Merge remote-tracking branch 'upstream/master' into doc-ja

.github/workflows/code_size.yml

@@ -8,9 +8,15 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'ports/bare-arm/**'
+      - 'ports/mimxrt/**'
       - 'ports/minimal/**'
+      - 'ports/rp2/**'
+      - 'ports/samd/**'
+      - 'ports/stm32/**'
+      - 'ports/unix/**'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

.github/workflows/ports_unix.yml

@@ -88,10 +88,11 @@ jobs:
         (cd ports/unix && gcov -o build-coverage/py ../../py/*.c || true)
         (cd ports/unix && gcov -o build-coverage/extmod ../../extmod/*.c || true)
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
       with:
         fail_ci_if_error: true
         verbose: true
+        token: ${{ secrets.CODECOV_TOKEN }}
     - name: Print failures
       if: failure()
       run: tests/run-tests.py --print-failures

docs/develop/optimizations.rst

@@ -33,7 +33,7 @@ Variables
 MicroPython processes local and global variables differently. Global variables
 are stored and looked up from a global dictionary that is allocated on the heap
 (note that each module has its own separate dict, so separate namespace).
-Local variables on the other hand are are stored on the Python value stack, which may
+Local variables on the other hand are stored on the Python value stack, which may
 live on the C stack or on the heap.  They are accessed directly by their offset
 within the Python stack, which is more efficient than a global lookup in a dict.
 

docs/esp32/quickref.rst

@@ -18,6 +18,9 @@ working with this board it may be useful to get an overview of the microcontroll
    general.rst
    tutorial/index.rst
 
+Note that there are several varieties of ESP32 -- ESP32, ESP32C3, ESP32S2, ESP32S3 --
+supported by MicroPython, with some differences in functionality between them.
+
 Installing MicroPython
 ----------------------
 
@@ -58,12 +61,18 @@ The :mod:`esp32` module::
     import esp32
 
     esp32.raw_temperature() # read the internal temperature of the MCU, in Fahrenheit
-    esp32.ULP()             # access to the Ultra-Low-Power Co-processor
+    esp32.ULP()             # access to the Ultra-Low-Power Co-processor, not on ESP32C3
 
 Note that the temperature sensor in the ESP32 will typically read higher than
 ambient due to the IC getting warm while it runs.  This effect can be minimised
 by reading the temperature sensor immediately after waking up from sleep.
 
+ESP32C3, ESP32S2, and ESP32S3 also have an internal temperature sensor available.
+It is implemented a bit differently to the ESP32 and returns the temperature in
+Celsius::
+
+    esp32.mcu_temperature() # read the internal temperature of the MCU, in Celsius
+
 Networking
 ----------
 

docs/library/asyncio.rst

@@ -149,8 +149,7 @@ class ThreadSafeFlag
 
     Create a new flag which can be used to synchronise a task with code running
     outside the asyncio loop, such as other threads, IRQs, or scheduler
-    callbacks.  Flags start in the cleared state.  The class does not currently
-    work under the Unix build of MicroPython.
+    callbacks.  Flags start in the cleared state.
 
 .. method:: ThreadSafeFlag.set()
 

docs/library/machine.USBDevice.rst

@@ -8,13 +8,11 @@ class USBDevice -- USB Device driver
           ports.
 
 USBDevice provides a low-level Python API for implementing USB device functions using
-Python code. This low-level API assumes familiarity with the USB standard. It's
-not recommended to use this API directly, instead install the high-level usbd
-module from micropython-lib.
+Python code.
 
-.. warning:: This functionality is very new and the high-level usbd module is
-             not yet merged into micropython-lib. It can be found `here on
-             GitHub <https://github.com/micropython/micropython-lib/pull/558>`_.
+.. warning:: This low-level API assumes familiarity with the USB standard. There
+   are high-level `usb driver modules in micropython-lib`_ which provide a
+   simpler interface and more built-in functionality.
 
 Terminology
 -----------
@@ -186,7 +184,7 @@ Methods
     necessary if the runtime device configuration has changed, so that
     the host sees the new device.
 
-.. attribute:: USDBD.builtin_driver
+.. attribute:: USBDevice.builtin_driver
 
    This attribute holds the current built-in driver configuration, and must be
    set to one of the ``USBDevice.BUILTIN_`` named constants defined on this object.
@@ -294,3 +292,5 @@ Constants
             descriptor.
           - ``desc_cfg`` - ``bytes`` object containing the complete built-in USB
             configuration descriptor.
+
+.. _usb driver modules in micropython-lib: https://github.com/micropython/micropython-lib/tree/master/micropython/usb#readme

docs/reference/mpremote.rst

@@ -682,6 +682,13 @@ See :ref:`packages`.
 Install the package from the specified branch at org/repo on GitHub to the
 device. See :ref:`packages`.
 
+.. code-block:: bash
+
+  mpremote mip install gitlab:org/repo@branch
+
+Install the package from the specified branch at org/repo on GitLab to the
+device. See :ref:`packages`.
+
 .. code-block:: bash
 
   mpremote mip install --target /flash/third-party functools

docs/reference/packages.rst

@@ -7,7 +7,7 @@ Installing packages with ``mip``
 --------------------------------
 
 Network-capable boards include the ``mip`` module, which can install packages
-from :term:`micropython-lib` and from third-party sites (including GitHub).
+from :term:`micropython-lib` and from third-party sites (including GitHub, GitLab).
 
 ``mip`` ("mip installs packages") is similar in concept to Python's ``pip`` tool,
 however it does not use the PyPI index, rather it uses :term:`micropython-lib`
@@ -38,24 +38,28 @@ install third-party libraries. The simplest way is to download a file directly::
 When installing a file directly, the ``target`` argument is still supported to set
 the destination path, but ``mpy`` and ``version`` are ignored.
 
-The URL can also start with ``github:`` as a simple way of pointing to content
-hosted on GitHub::
+The URL can also start with ``github:`` or ``gitlab:`` as a simple way of pointing to content
+hosted on GitHub or GitLab::
 
     >>> mip.install("github:org/repo/path/foo.py")  # Uses default branch
     >>> mip.install("github:org/repo/path/foo.py", version="branch-or-tag")  # Optionally specify the branch or tag
+    >>> mip.install("gitlab:org/repo/path/foo.py")  # Uses default branch
+    >>> mip.install("gitlab:org/repo/path/foo.py", version="branch-or-tag")  # Optionally specify the branch or tag
 
 More sophisticated packages (i.e. with more than one file, or with dependencies)
 can be downloaded by specifying the path to their ``package.json``.
 
     >>> mip.install("http://example.com/x/package.json")
     >>> mip.install("github:org/user/path/package.json")
+    >>> mip.install("gitlab:org/user/path/package.json")
 
 If no json file is specified, then "package.json" is implicitly added::
 
     >>> mip.install("http://example.com/x/")
     >>> mip.install("github:org/repo")  # Uses default branch of that repo
     >>> mip.install("github:org/repo", version="branch-or-tag")
-
+    >>> mip.install("gitlab:org/repo")  # Uses default branch of that repo
+    >>> mip.install("gitlab:org/repo", version="branch-or-tag")
 
 Using ``mip`` on the Unix port
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -83,6 +87,8 @@ can be used from a host PC to install packages to a locally connected device
     $ mpremote mip install http://example.com/x/y/foo.py
     $ mpremote mip install github:org/repo
     $ mpremote mip install github:org/repo@branch-or-tag
+    $ mpremote mip install gitlab:org/repo
+    $ mpremote mip install gitlab:org/repo@branch-or-tag
 
 The ``--target=path``, ``--no-mpy``, and ``--index`` arguments can be set::
 
@@ -120,7 +126,8 @@ A typical ``package.json`` for an example ``mlx90640`` library looks like::
       "deps": [
         ["collections-defaultdict", "latest"],
         ["os-path", "latest"],
-        ["github:org/micropython-additions", "main"]
+        ["github:org/micropython-additions", "main"],
+        ["gitlab:org/micropython-otheradditions", "main"]
       ],
       "version": "0.2"
     }

examples/network/https_client_nonblocking.py

@@ -0,0 +1,75 @@
+# Example of a HTTPS client working with non-blocking sockets.
+#
+# Non-blocking SSL streams works differently in MicroPython compared to CPython.  In
+# CPython a write to an SSLSocket may raise ssl.SSLWantReadError.  In MicroPython an
+# SSLSocket behaves like a normal socket/stream and can be polled for reading/writing.
+
+from errno import EINPROGRESS
+import select
+import socket
+import ssl
+
+
+def connect_nonblocking(sock, addr):
+    sock.setblocking(False)
+    try:
+        sock.connect(addr)
+    except OSError as er:
+        if er.errno != EINPROGRESS:
+            raise er
+
+
+def write_nonblocking(poller, sock, data):
+    poller.register(sock, select.POLLOUT)
+    while data:
+        poller.poll()
+        n = sock.write(data)
+        print("Wrote:", n)
+        if n is not None:
+            data = data[n:]
+
+
+def read_nonblocking(poller, sock, n):
+    poller.register(sock, select.POLLIN)
+    poller.poll()
+    data = sock.read(n)
+    print("Read:", len(data))
+    return data
+
+
+def main(url):
+    # Split the given URL into components.
+    proto, _, host, path = url.split(b"/", 3)
+    assert proto == b"https:"
+
+    # Note: this getaddrinfo() call is blocking!
+    ai = socket.getaddrinfo(host, 443)[0]
+    addr = ai[-1]
+    print("Connect address:", addr)
+
+    # Create a TCP socket and connect to the server in non-blocking mode.
+    sock = socket.socket(ai[0], ai[1], ai[2])
+    connect_nonblocking(sock, addr)
+
+    # Wrap the TCP socket in an SSL stream in non-blocking mode.
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    sock = ctx.wrap_socket(sock, server_hostname=host, do_handshake_on_connect=False)
+    sock.setblocking(False)
+
+    # Create an object to poll the SSL stream for readability/writability.
+    poller = select.poll()
+
+    # Send the HTTP request on the SSL stream.
+    request = b"GET /%s HTTP/1.0\r\nHost: %s\r\n\r\n" % (path, host)
+    write_nonblocking(poller, sock, request)
+
+    # Receive the HTTP response from the SSL stream.
+    response = read_nonblocking(poller, sock, 1000)
+    for line in response.split(b"\n"):
+        print(line)
+
+    # Close the SSL stream.  This will also close the underlying TCP socket.
+    sock.close()
+
+
+main(b"https://micropython.org/ks/test.html")

examples/usb/README.md

@@ -0,0 +1,16 @@
+## USBDevice Examples
+
+These are examples of how to use the low-level `machine.USBDevice` class to create custom
+USB device functionality.
+
+Alternatively, there are [usb driver modules in
+micropython-lib](https://github.com/micropython/micropython-lib/tree/master/micropython/usb#readme)
+which provide a simpler interface and more built-in functionality.
+
+In this directory:
+
+* `usb_dfu_device.py` implements the USB Device Firmware Update protocol.
+* `usb_simple_device.py` implements a custom USB protocol, with a matching host
+  program to run on a PC.
+
+See comments at the top of each Python file for more details.