Adding the usage of the 3rd button as the Wheel in USB mouse.py

.github/workflows/build_packages.yml

@@ -2,15 +2,28 @@ name: Build all packages
 
 on: [push, pull_request]
 
+env:
+  PACKAGE_INDEX_PATH: /tmp/micropython-lib-deploy
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v1
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
     - name: Setup environment
       run: source tools/ci.sh && ci_build_packages_setup
     - name: Check manifest files
       run: source tools/ci.sh && ci_build_packages_check_manifest
     - name: Compile package index
       run: source tools/ci.sh && ci_build_packages_compile_index
+    - name: Compile package examples
+      run: source tools/ci.sh && ci_build_packages_examples
+    - name: Publish packages for branch
+      if: vars.MICROPY_PUBLISH_MIP_INDEX && github.event_name == 'push' && ! github.event.deleted
+      run: source tools/ci.sh && ci_push_package_index
+    - name: Upload packages as artifact
+      uses: actions/upload-artifact@v3
+      with:
+        name: packages-${{ github.sha }}
+        path: ${{ env.PACKAGE_INDEX_PATH }}

.github/workflows/cleanup_published_packages.yml

@@ -0,0 +1,12 @@
+name: Cleanup published packages
+
+on: delete
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    if: vars.MICROPY_PUBLISH_MIP_INDEX
+    steps:
+    - uses: actions/checkout@v3
+    - name: Clean up published files
+      run: source tools/ci.sh && ci_cleanup_package_index ${{ github.event.ref }}

.github/workflows/commit_formatting.yml

@@ -0,0 +1,18 @@
+name: Check commit message formatting
+
+on: [push, pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: '100'
+    - uses: actions/setup-python@v4
+    - name: Check commit message formatting
+      run: source tools/ci.sh && ci_commit_formatting_run

.github/workflows/ruff.yml

@@ -0,0 +1,11 @@
+# https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+name: Python code lint and formatting with ruff
+on: [push, pull_request]
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - run: pip install --user ruff==0.1.2
+    - run: ruff check --output-format=github .
+    - run: ruff format --diff .

.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: local
+    hooks:
+      - id: verifygitlog
+        name: MicroPython git commit message format checker
+        entry: tools/verifygitlog.py --check-file --ignore-rebase
+        language: python
+        verbose: true
+        stages: [commit-msg]
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.1.2
+    hooks:
+      - id: ruff
+        id: ruff-format

CONTRIBUTING.md

@@ -25,11 +25,21 @@ or packages from micropython-lib, please post at the
 ### Pull requests
 
 The same rules for commit messages, signing-off commits, and commit structure
-apply as for the main MicroPython repository. All Python code is formatted
-using `black`. See [`tools/codeformat.py`](tools/codeformat.py) to apply
-`black` automatically before submitting a PR.
+apply [as for the main MicroPython repository](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md).
 
-There are some specific conventions and guidelines for micropython-lib:
+All Python code is formatted using the [black](https://github.com/psf/black)
+tool. You can run [`tools/codeformat.py`](tools/codeformat.py) to apply
+`black` automatically before submitting a PR. The GitHub CI will also run the
+[ruff](https://github.com/astral-sh/ruff) tool to apply further "linting"
+checks.
+
+Similar to the main repository, a configuration is provided for the
+[pre-commit](https://pre-commit.com/) tool to apply `black` code formatting
+rules and run `ruff` automatically. See the documentation for using pre-commit
+in [the code conventions document](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md#automatic-pre-commit-hooks)
+
+In addition to the conventions from the main repository, there are some
+specific conventions and guidelines for micropython-lib:
 
 * The first line of the commit message should start with the name of the
   package, followed by a short description of the commit. Package names are
@@ -69,3 +79,49 @@ There are some specific conventions and guidelines for micropython-lib:
 
 * When porting an existing third-party package, please ensure that the source
   license is compatible.
+
+* To make it easier for others to install packages directly from your PR before
+  it is merged, consider opting-in to automatic package publishing (see
+  [Publishing packages from forks](#publishing-packages-from-forks)). If you do
+  this, consider quoting the [commands to install
+  packages](README.md#installing-packages-from-forks) in your Pull Request
+  description.
+
+### Publishing packages from forks
+
+You can easily publish the packages from your micropython-lib
+[fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks)
+by opting in to a system based on [GitHub
+Actions](https://docs.github.com/en/actions) and [GitHub
+Pages](https://docs.github.com/en/pages):
+
+1. Open your fork's repository in the GitHub web interface.
+2. Navigate to "Settings" -> "Secrets and variables" -> "Actions" -> "Variables".
+3. Click "New repository variable"
+4. Create a variable named `MICROPY_PUBLISH_MIP_INDEX` with value `true` (or any
+   "truthy" value).
+5. The settings for GitHub Actions and GitHub Pages features should not need to
+   be changed from the repository defaults, unless you've explicitly disabled
+   them.
+
+The next time you push commits to a branch in your fork, GitHub Actions will run
+an additional step in the "Build All Packages" workflow named "Publish Packages
+for branch".
+
+Anyone can then install these packages as described under [Installing packages
+from forks](README.md#installing-packages-from-forks). The exact commands are also
+quoted in the GitHub Actions log for the "Publish Packages for branch" step.
+
+#### Opting Back Out
+
+To opt-out again, delete the `MICROPY_PUBLISH_MIP_INDEX` variable and
+(optionally) delete the `gh-pages` branch from your fork.
+
+*Note*: While enabled, all micropython-lib packages will be published each time
+a change is pushed to any branch in your fork. A commit is added to the
+`gh-pages` branch each time. In a busy repository, the `gh-pages` branch may
+become quite large. The actual `.git` directory size on disk should still be
+quite small, as most of the content will be duplicated. If you're worried that
+the `gh-pages` branch has become too large then you can always delete this
+branch from GitHub. GitHub Actions will create a new `gh-pages` branch the next
+time you push a change.

README.md

@@ -84,6 +84,37 @@ Note that unlike the other three approaches based on `mip` or `manifest.py`,
 you will need to manually resolve dependencies. You can inspect the relevant
 `manifest.py` file to view the list of dependencies for a given package.
 
+## Installing packages from forks
+
+It is possible to use the `mpremote mip install` or `mip.install()` methods to
+install packages built from a
+[fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks)
+of micropython-lib, if the fork's owner has opted in.
+
+This can be useful to install packages from a pending Pull Request, for example.
+
+First, the owner of the fork must opt-in as described under
+[Publishing packages from forks](CONTRIBUTING.md#publishing-packages-from-forks).
+
+After this has happened, each time someone pushes to a branch in that fork then
+GitHub Actions will automatically publish the packages to a GitHub Pages site.
+
+To install these packages, use commands such as:
+
+```bash
+$ mpremote connect /dev/ttyUSB0 mip install --index https://USERNAME.github.io/micropython-lib/mip/BRANCH_NAME PACKAGE_NAME
+```
+
+Or from a networked device:
+
+```py
+import mip
+mip.install(PACKAGE_NAME, index="https://USERNAME.github.io/micropython-lib/mip/BRANCH_NAME")
+```
+
+(Where `USERNAME`, `BRANCH_NAME` and `PACKAGE_NAME` are replaced with the owner
+of the fork, the branch the packages were built from, and the package name.)
+
 ## Contributing
 
 We use [GitHub Discussions](https://github.com/micropython/micropython/discussions)

micropython/aioespnow/README.md

@@ -0,0 +1,91 @@
+# `aioespnow`
+
+A supplementary module which extends the micropython `espnow` module to provide
+`asyncio` support.
+
+- Asyncio support is available on all ESP32 targets as well as those ESP8266
+boards which include the `uasyncio` module (ie. ESP8266 devices with at least
+2MB flash storage).
+
+## API reference
+
+- class `AIOESPNow()`: inherits all the methods of the `ESPNow` class and
+  extends the interface with the following async methods:
+
+  - `async AIOESPNow.arecv()`
+
+      Asyncio support for ESPNow.recv(). Note that this method does not take a
+      timeout value as argument.
+
+  - `async AIOESPNow.airecv()`
+
+      Asyncio support for ESPNow.irecv(). Use this method to reduce memory
+      fragmentation, as it will reuse common storage for each new message
+      received, whereas the `arecv()` method will allocate new memory for every
+      message received.
+
+  - `async AIOESPNow.asend(mac, msg, sync=True)`
+  - `async AIOESPNow.asend(msg)`
+
+      Asyncio support for ESPNow.send().
+
+  - `__aiter__()/async __anext__()`
+
+      AIOESPNow also supports reading incoming messages by asynchronous
+      iteration using `async for`, eg:
+
+    ```python
+      e = AIOESPNow()
+      e.active(True)
+      async def recv_till_halt(e):
+          async for mac, msg in e:
+              print(mac, msg)
+              if msg == b'halt':
+                  break
+      asyncio.run(recv_till_halt(e))
+    ```
+
+## Example Usage
+
+A small async server example::
+
+```python
+    import network
+    import aioespnow
+    import uasyncio as asyncio
+
+    # A WLAN interface must be active to send()/recv()
+    network.WLAN(network.STA_IF).active(True)
+
+    e = aioespnow.AIOESPNow()  # Returns AIOESPNow enhanced with async support
+    e.active(True)
+    peer = b'\xbb\xbb\xbb\xbb\xbb\xbb'
+    e.add_peer(peer)
+
+    # Send a periodic ping to a peer
+    async def heartbeat(e, peer, period=30):
+        while True:
+            if not await e.asend(peer, b'ping'):
+                print("Heartbeat: peer not responding:", peer)
+            else:
+                print("Heartbeat: ping", peer)
+            await asyncio.sleep(period)
+
+    # Echo any received messages back to the sender
+    async def echo_server(e):
+        async for mac, msg in e:
+            print("Echo:", msg)
+            try:
+                await e.asend(mac, msg)
+            except OSError as err:
+                if len(err.args) > 1 and err.args[1] == 'ESP_ERR_ESPNOW_NOT_FOUND':
+                    e.add_peer(mac)
+                    await e.asend(mac, msg)
+
+    async def main(e, peer, timeout, period):
+        asyncio.create_task(heartbeat(e, peer, period))
+        asyncio.create_task(echo_server(e))
+        await asyncio.sleep(timeout)
+
+    asyncio.run(main(e, peer, 120, 10))
+```

micropython/aioespnow/aioespnow.py

@@ -0,0 +1,31 @@
+# aioespnow module for MicroPython on ESP32 and ESP8266
+# MIT license; Copyright (c) 2022 Glenn Moloney @glenn20
+
+import uasyncio as asyncio
+import espnow
+
+
+# Modelled on the uasyncio.Stream class (extmod/stream/stream.py)
+# NOTE: Relies on internal implementation of uasyncio.core (_io_queue)
+class AIOESPNow(espnow.ESPNow):
+    # Read one ESPNow message
+    async def arecv(self):
+        yield asyncio.core._io_queue.queue_read(self)
+        return self.recv(0)  # type: ignore[misc]
+
+    async def airecv(self):
+        yield asyncio.core._io_queue.queue_read(self)
+        return self.irecv(0)  # type: ignore[misc]
+
+    async def asend(self, mac, msg=None, sync=None):
+        if msg is None:
+            msg, mac = mac, None  # If msg is None: swap mac and msg
+        yield asyncio.core._io_queue.queue_write(self)
+        return self.send(mac, msg, sync)  # type: ignore[misc]
+
+    # "async for" support
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        return await self.airecv()

micropython/aioespnow/manifest.py

@@ -0,0 +1,6 @@
+metadata(
+    description="Extends the micropython espnow module with methods to support asyncio.",
+    version="0.1.0",
+)
+
+module("aioespnow.py")

micropython/aiorepl/README.md

@@ -21,7 +21,7 @@ To use this library, you need to import the library and then start the REPL task
 For example, in main.py:
 
 ```py
-import uasyncio as asyncio
+import asyncio
 import aiorepl
 
 async def demo():
@@ -50,11 +50,17 @@ async def main():
 asyncio.run(main())
 ```
 
-The optional globals passed to `task([globals])` allows you to specify what
-will be in scope for the REPL. By default it uses `__main__`, which is the
-same scope as the regular REPL (and `main.py`). In the example above, the
-REPL will be able to call the `demo()` function as well as get/set the
-`state` variable.
+An optional globals dictionary can be passed to `aiorepl.task()`, which allows
+you to specify what will be in scope for the REPL. By default it uses the
+globals dictionary from the `__main__` module, which is the same scope as the
+regular REPL (and `main.py`). In the example above, the REPL will be able to
+call the `demo()` function as well as get/set the `state` variable.
+
+You can also provide your own dictionary, e.g. `aiorepl.task({"obj": obj })`,
+or use the globals dict from the current module, e.g.
+`aiorepl.task(globals())`. Note that you cannot use a class instance's members
+dictionary, e.g. `aiorepl.task(obj.__dict__)`, as this is read-only in
+MicroPython.
 
 Instead of the regular `>>> ` prompt, the asyncio REPL will show `--> `.