all: Bump version to 1.20.0.

Signed-off-by: Damien George <damien@micropython.org>

.git-blame-ignore-revs

@@ -1,3 +1,18 @@
+# top: Update Python formatting to black "2023 stable style".
+8b2748269244304854b3462cb8902952b4dcb892
+
+# all: Reformat remaining C code that doesn't have a space after a comma.
+5b700b0af90591d6b1a2c087bb8de6b7f1bfdd2d
+
+# ports: Reformat more C and Python source code.
+5c32111fa0e31e451b0f1666bdf926be2fdfd82c
+
+# all: Update Python formatting to latest Black version 22.1.0.
+ab2923dfa1174dc177f0a90cb00a7e4ff87958d2
+
+# all: Update Python formatting to latest Black version 21.12b0.
+3770fab33449a5dadf8eb06edfae0767e75320a6
+
 # tools/gen-cpydiff.py: Fix formatting of doc strings for new Black.
 0f78c36c5aa458a954eed39a46942209107a553e
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Report an issue
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab or raise a documentation request instead.
+
+* In your issue, please include a clear and concise description of what the bug is, the expected output, and how to replicate it.
+
+* If this issue involves external hardware, please include links to relevant datasheets and schematics.
+
+* If you are seeing code being executed incorrectly, please provide a minimal example and expected output (e.g. comparison to CPython).
+
+* For build issues, please include full details of your environment, compiler versions, command lines, and build output.
+
+* Please provide as much information as possible about the version of MicroPython you're running, such as:
+ - firmware file name
+ - git commit hash and port/board
+ - version information shown in the REPL (hit Ctrl-B to see the startup message)
+
+* Remove all placeholder text above before submitting.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: MicroPython GitHub Discussions
+    url: https://github.com/orgs/micropython/discussions
+    about: Community discussion about all things MicroPython. This is the best place to start if you have questions about using MicroPython or getting started with MicroPython development.
+  - name: MicroPython Documentation
+    url: https://docs.micropython.org/
+    about: Documentation for using and working with MicroPython and libraries.
+  - name: MicroPython Downloads
+    url: https://micropython.org/download/
+    about: Pre-built firmware and information for most supported boards.

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,16 @@
+---
+name: Documentation issue
+about: Report areas of the documentation or examples that need improvement
+title: 'docs: '
+labels: documentation
+assignees: ''
+
+---
+
+* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab instead.
+
+* Describe what was missing from the documentation and/or what was incorrect/incomplete.
+
+* If possible, please link to the relevant page on https://docs.micropython.org/
+
+* Remove all placeholder text above before submitting.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Request a feature or improvement
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab or raise a documentation request instead.
+
+* Describe the feature you'd like to see added to MicroPython. In particular, what does this feature enable and why is it useful. MicroPython aims to strike a balance between functionality and code size, so please consider whether this feature can be optionally enabled and whether it can be provided in other ways (e.g. pure-Python library).
+
+* For core Python features, where possible please include a link to the relevant PEP.
+
+* For new architectures / ports / boards, please provide links to relevant documentation, specifications, and toolchains. Any information about the popularity and unique features about this hardware would also be useful.
+
+* For features for existing ports (e.g. new peripherals or microcontroller features), please describe which port(s) it applies too, and whether this is could be an extension to the machine API or a port-specific module?
+
+* For drivers (e.g. for external hardware), please link to datasheets and/or existing drivers from other sources.
+
+* Who do you expect will implement the feature you are requesting? Would you be willing to sponsor this work?
+
+* Remove all placeholder text above before submitting.

.github/ISSUE_TEMPLATE/security.md

@@ -0,0 +1,16 @@
+---
+name: Security report
+about: Report a security issue or vunerability in MicroPython
+title: ''
+labels: security
+assignees: ''
+
+---
+
+* If you need to raise this issue privately with the MicroPython team, please email contact@micropython.org instead.
+
+* Include a clear and concise description of what the security issue is.
+
+* What does this issue allow an attacker to do?
+
+* Remove all placeholder text above before submitting.

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"

.github/workflows/code_formatting.yml

@@ -2,12 +2,16 @@ name: Check code formatting
 
 on: [push, pull_request]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v1
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
     - name: Install packages
       run: source tools/ci.sh && ci_code_formatting_setup
     - name: Run code formatting

.github/workflows/code_size.yml

@@ -12,11 +12,15 @@ on:
       - 'ports/bare-arm/**'
       - 'ports/minimal/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         fetch-depth: 100
     - name: Install packages
@@ -24,4 +28,18 @@ jobs:
     - name: Build
       run: source tools/ci.sh && ci_code_size_build
     - name: Compute code size difference
-      run: tools/metrics.py diff --error-threshold 0 ~/size0 ~/size1
+      run: tools/metrics.py diff ~/size0 ~/size1 | tee diff
+    - name: Save PR number
+      if: github.event_name == 'pull_request'
+      env:
+        PR_NUMBER: ${{ github.event.number }}
+      run: echo $PR_NUMBER > pr_number
+    - name: Upload diff
+      if: github.event_name == 'pull_request'
+      uses: actions/upload-artifact@v3
+      with:
+        name: code-size-report
+        path: |
+          diff
+          pr_number
+        retention-days: 1

.github/workflows/code_size_comment.yml

@@ -0,0 +1,105 @@
+name: Code size comment
+
+on:
+  workflow_run:
+    workflows: [Check code size]
+    types: [completed]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  comment:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: 'Download artifact'
+        id: download-artifact
+        uses: actions/github-script@v6
+        with:
+          result-encoding: string
+          script: |
+            const fs = require('fs');
+
+            const allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
+               owner: context.repo.owner,
+               repo: context.repo.repo,
+               run_id: context.payload.workflow_run.id,
+            });
+
+            const matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
+              return artifact.name == "code-size-report"
+            });
+
+            if (matchArtifact.length === 0) {
+              console.log('no matching artifact found');
+              console.log('result: "skip"');
+
+              return 'skip';
+            }
+
+            const download = await github.rest.actions.downloadArtifact({
+               owner: context.repo.owner,
+               repo: context.repo.repo,
+               artifact_id: matchArtifact[0].id,
+               archive_format: 'zip',
+            });
+
+            fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/code-size-report.zip`, Buffer.from(download.data));
+
+            console.log('artifact downloaded to `code-size-report.zip`');
+            console.log('result: "ok"');
+
+            return 'ok';
+      - name: 'Unzip artifact'
+        if: steps.download-artifact.outputs.result == 'ok'
+        run: unzip code-size-report.zip
+      - name: Post comment to pull request
+        if: steps.download-artifact.outputs.result == 'ok'
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            const fs = require('fs');
+
+            const prNumber = Number(fs.readFileSync('pr_number'));
+            const codeSizeReport = `Code size report:
+
+            \`\`\`
+            ${fs.readFileSync('diff')}
+            \`\`\`
+            `;
+
+            const comments = await github.paginate(
+              github.rest.issues.listComments,
+              {
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+              }
+            );
+
+            comments.reverse();
+
+            const previousComment = comments.find(comment =>
+              comment.user.login === 'github-actions[bot]'
+            )
+
+            // if github-actions[bot] already made a comment, update it,
+            // otherwise create a new comment.
+
+            if (previousComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: previousComment.id,
+                body: codeSizeReport,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+                body: codeSizeReport,
+              });
+            }

.github/workflows/commit_formatting.yml

@@ -2,13 +2,17 @@ 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@v2
+    - uses: actions/checkout@v3
       with:
         fetch-depth: '100'
-    - uses: actions/setup-python@v1
+    - uses: actions/setup-python@v4
     - name: Check commit message formatting
       run: source tools/ci.sh && ci_commit_formatting_run

.github/workflows/docs.yml

@@ -5,13 +5,17 @@ on:
     paths:
       - docs/**
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 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: Install Python packages
       run: pip install Sphinx
     - name: Build docs

.github/workflows/examples.yml

@@ -0,0 +1,25 @@
+name: Check examples
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'examples/**'
+      - 'ports/unix/**'
+      - 'py/**'
+      - 'shared/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  embedding:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build
+      run: make -C examples/embedding -f micropython_embed.mk && make -C examples/embedding
+    - name: Run
+      run: ./examples/embedding/embed | grep "hello world"

.github/workflows/mpremote.yml

@@ -0,0 +1,31 @@
+name: Package mpremote
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        # Version is determined from git,
+        # should be deep enough to get to latest tag
+        fetch-depth: '1000'
+    - run: |
+        git fetch --prune --unshallow --tags
+    - uses: actions/setup-python@v4
+    - name: Install build tools
+      run: pip install build
+    - name: Build mpremote wheel
+      run: cd tools/mpremote && python -m build --wheel
+    - name: Archive mpremote wheel
+      uses: actions/upload-artifact@v3
+      with:
+        name: mpremote
+        path: |
+          tools/mpremote/dist/mpremote*.whl

.github/workflows/mpy_format.yml

@@ -0,0 +1,24 @@
+name: .mpy file format and tools
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'examples/**'
+      - 'tests/**'
+      - 'tools/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-20.04 # use 20.04 to get python2
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_mpy_format_setup
+    - name: Test mpy-tool.py
+      run: source tools/ci.sh && ci_mpy_format_test

.github/workflows/ports.yml

@@ -0,0 +1,22 @@
+name: Build ports metadata
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - ports/**
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build ports download metadata
+      run: mkdir boards && ./tools/autobuild/build-downloads.py . ./boards

.github/workflows/ports_cc3200.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/cc3200/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_cc3200_setup
     - name: Build

.github/workflows/ports_esp32.yml

@@ -8,25 +8,30 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/esp32/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build_idf402:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_esp32_idf402_setup
     - name: Build
       run: source tools/ci.sh && ci_esp32_build
 
-  build_idf43:
+  build_idf44:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
-      run: source tools/ci.sh && ci_esp32_idf43_setup
+      run: source tools/ci.sh && ci_esp32_idf44_setup
     - name: Build
       run: source tools/ci.sh && ci_esp32_build

.github/workflows/ports_esp8266.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/esp8266/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_esp8266_setup && ci_esp8266_path >> $GITHUB_PATH
     - name: Build

.github/workflows/ports_mimxrt.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/mimxrt/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_mimxrt_setup
     - name: Build

.github/workflows/ports_nrf.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/nrf/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_nrf_setup
     - name: Build

.github/workflows/ports_powerpc.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/powerpc/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_powerpc_setup
     - name: Build

.github/workflows/ports_qemu-arm.yml

@@ -8,20 +8,25 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/qemu-arm/**'
       - 'tests/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build_and_test:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_qemu_arm_setup
     - name: Build and run test suite
       run: source tools/ci.sh && ci_qemu_arm_build
     - name: Print failures
       if: failure()
-      run: grep --text "FAIL" ports/qemu-arm/build/console.out
+      run: grep --before-context=100 --text "FAIL" ports/qemu-arm/build/console.out

.github/workflows/ports_renesas-ra.yml

@@ -0,0 +1,29 @@
+name: renesas-ra port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/renesas-ra/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_renesas_ra_board:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_renesas_ra_setup
+    - name: Build
+      run: source tools/ci.sh && ci_renesas_ra_board_build
+

.github/workflows/ports_rp2.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/rp2/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_rp2_setup
     - name: Build

.github/workflows/ports_samd.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/samd/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_samd_setup
     - name: Build

.github/workflows/ports_stm32.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/stm32/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build_pyb:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_stm32_setup
     - name: Build
@@ -25,7 +30,7 @@ jobs:
   build_nucleo:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_stm32_setup
     - name: Build

.github/workflows/ports_teensy.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'drivers/**'
       - 'ports/teensy/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_teensy_setup
     - name: Build

.github/workflows/ports_unix.yml

@@ -8,16 +8,22 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'examples/**'
+      - 'mpy-cross/**'
       - 'ports/unix/**'
       - 'tests/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   minimal:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build
       run: source tools/ci.sh && ci_unix_minimal_build
     - name: Run main test suite
@@ -29,24 +35,22 @@ jobs:
   reproducible:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build with reproducible date
       run: source tools/ci.sh && ci_unix_minimal_build
       env:
         SOURCE_DATE_EPOCH: 1234567890
     - name: Check reproducible build date
-      run: echo | ports/unix/micropython-minimal -i | grep 'on 2009-02-13;'
+      run: echo | ports/unix/build-minimal/micropython -i | grep 'on 2009-02-13;'
 
   standard:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build
       run: source tools/ci.sh && ci_unix_standard_build
     - name: Run main test suite
       run: source tools/ci.sh && ci_unix_standard_run_tests
-    - name: Run performance benchmarks
-      run: source tools/ci.sh && ci_unix_standard_run_perfbench
     - name: Print failures
       if: failure()
       run: tests/run-tests.py --print-failures
@@ -54,26 +58,28 @@ jobs:
   coverage:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_coverage_setup
     - name: Build
       run: source tools/ci.sh && ci_unix_coverage_build
     - name: Run main test suite
       run: source tools/ci.sh && ci_unix_coverage_run_tests
+    - name: Test merging .mpy files
+      run: source tools/ci.sh && ci_unix_coverage_run_mpy_merge_tests
     - name: Build native mpy modules
       run: source tools/ci.sh && ci_native_mpy_modules_build
     - name: Test importing .mpy generated by mpy_ld.py
       run: source tools/ci.sh && ci_unix_coverage_run_native_mpy_tests
-    - name: Run lcov coverage analysis
+    - name: Run gcov coverage analysis
       run: |
-        mkdir -p coverage
-        lcov --rc lcov_branch_coverage=1 --directory ports/unix/build-coverage --capture --output-file coverage/lcov.info.all
-        lcov --remove coverage/lcov.info.all '*/lib/*' '*/ports/unix/*' '*/utils/*' --output-file coverage/lcov.info
-    - name: Send to coveralls
-      uses: coverallsapp/github-action@master
+        (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
       with:
-        github-token: ${{ secrets.GITHUB_TOKEN }}
+        fail_ci_if_error: true
+        verbose: true
     - name: Print failures
       if: failure()
       run: tests/run-tests.py --print-failures
@@ -81,7 +87,7 @@ jobs:
   coverage_32bit:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_32bit_setup
     - name: Build
@@ -97,9 +103,9 @@ jobs:
       run: tests/run-tests.py --print-failures
 
   nanbox:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04 # use 20.04 to get python2
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_32bit_setup
     - name: Build
@@ -113,7 +119,7 @@ jobs:
   float:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build
       run: source tools/ci.sh && ci_unix_float_build
     - name: Run main test suite
@@ -125,7 +131,7 @@ jobs:
   stackless_clang:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_clang_setup
     - name: Build
@@ -139,7 +145,7 @@ jobs:
   float_clang:
     runs-on: ubuntu-20.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_clang_setup
     - name: Build
@@ -153,7 +159,7 @@ jobs:
   settrace:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build
       run: source tools/ci.sh && ci_unix_settrace_build
     - name: Run main test suite
@@ -165,7 +171,7 @@ jobs:
   settrace_stackless:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Build
       run: source tools/ci.sh && ci_unix_settrace_stackless_build
     - name: Run main test suite
@@ -177,8 +183,10 @@ jobs:
   macos:
     runs-on: macos-11.0
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-python@v1
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.8'
     - name: Build
       run: source tools/ci.sh && ci_unix_macos_build
     - name: Run tests
@@ -190,7 +198,7 @@ jobs:
   qemu_mips:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_qemu_mips_setup
     - name: Build
@@ -204,7 +212,7 @@ jobs:
   qemu_arm:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_unix_qemu_arm_setup
     - name: Build

.github/workflows/ports_webassembly.yml

@@ -0,0 +1,32 @@
+name: webassembly port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'ports/webassembly/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_webassembly_setup
+    - name: Build
+      run: source tools/ci.sh && ci_webassembly_build
+    - name: Run tests
+      run: source tools/ci.sh && ci_webassembly_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures

.github/workflows/ports_windows.yml

@@ -8,15 +8,20 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'ports/unix/**'
       - 'ports/windows/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_windows_setup
     - name: Build

.github/workflows/ports_zephyr.yml

@@ -8,14 +8,19 @@ on:
       - 'tools/**'
       - 'py/**'
       - 'extmod/**'
+      - 'shared/**'
       - 'lib/**'
       - 'ports/zephyr/**'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Install packages
       run: source tools/ci.sh && ci_zephyr_setup
     - name: Install Zephyr

.gitignore

@@ -1,48 +1,25 @@
-# Compiled Sources
-###################
-*.o
-*.a
-*.elf
-*.bin
-*.map
-*.hex
-*.dis
-*.exe
-
-# Packages
-############
-
-# Logs and Databases
-######################
-*.log
-
-# VIM Swap Files
-######################
-*.swp
+# This .gitignore file is intended to be minimal.
+#
+# If you find that you need additional rules, such as IDE temporary
+# files, please do so either via a global .gitignore file (registered
+# with core.excludesFile), or by adding private repository-specific
+# rules to .git/info/exclude.  See https://git-scm.com/docs/gitignore
+# for more information.
 
 # Build directories
-######################
 build/
 build-*/
+docs/genrst/
 
 # Test failure outputs
-######################
 tests/results/*
 
 # Python cache files
-######################
 __pycache__/
-*.pyc
 
 # Customized Makefile/project overrides
-######################
 GNUmakefile
 user.props
 
-# Generated rst files
-######################
-genrst/
-
 # MacOS desktop metadata files
-######################
 .DS_Store

.gitmodules

@@ -1,7 +1,6 @@
 [submodule "lib/axtls"]
 	path = lib/axtls
-	url = https://github.com/pfalcon/axtls
-	branch = micropython
+	url = https://github.com/micropython/axtls.git
 [submodule "lib/libffi"]
 	path = lib/libffi
 	url = https://github.com/atgreen/libffi
@@ -14,7 +13,7 @@
 [submodule "lib/stm32lib"]
 	path = lib/stm32lib
 	url = https://github.com/micropython/stm32lib
-	branch = work-F4-1.13.1+F7-1.5.0+L4-1.3.0
+	branch = work-F0-1.9.0+F4-1.16.0+F7-1.7.0+G0-1.5.1+G4-1.3.0+H7-1.6.0+L0-1.11.2+L1-1.10.3+L4-1.17.0+WB-1.10.0+WL-1.1.0
 [submodule "lib/nrfx"]
 	path = lib/nrfx
 	url = https://github.com/NordicSemiconductor/nrfx.git
@@ -24,12 +23,13 @@
 [submodule "lib/asf4"]
 	path = lib/asf4
 	url = https://github.com/adafruit/asf4
+	branch = circuitpython
 [submodule "lib/tinyusb"]
 	path = lib/tinyusb
 	url = https://github.com/hathach/tinyusb
 [submodule "lib/mynewt-nimble"]
 	path = lib/mynewt-nimble
-	url = https://github.com/apache/mynewt-nimble.git
+	url = https://github.com/micropython/mynewt-nimble.git
 [submodule "lib/btstack"]
 	path = lib/btstack
 	url = https://github.com/bluekitchen/btstack.git
@@ -42,3 +42,17 @@
 [submodule "lib/pico-sdk"]
 	path = lib/pico-sdk
 	url = https://github.com/raspberrypi/pico-sdk.git
+[submodule "lib/fsp"]
+	path = lib/fsp
+	url = https://github.com/renesas/fsp.git
+[submodule "lib/wiznet"]
+	path = lib/wiznet5k
+	url = https://github.com/andrewleech/wiznet_ioLibrary_Driver.git
+	# Requires https://github.com/Wiznet/ioLibrary_Driver/pull/120
+	# url = https://github.com/Wiznet/ioLibrary_Driver.git
+[submodule "lib/cyw43-driver"]
+	path = lib/cyw43-driver
+	url = https://github.com/georgerobotics/cyw43-driver.git
+[submodule "lib/micropython-lib"]
+	path = lib/micropython-lib
+	url = https://github.com/micropython/micropython-lib.git

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: local
+    hooks:
+      - id: codeformat
+        name: MicroPython codeformat.py for changed files
+        entry: tools/codeformat.py -v -f
+        language: python
+      - id: verifygitlog
+        name: MicroPython git commit message format checker
+        entry: tools/verifygitlog.py --check-file --ignore-rebase
+        language: python
+        verbose: true
+        stages: [commit-msg]

CODECONVENTIONS.md

@@ -65,6 +65,96 @@ changes to the correct style.  Without arguments this tool will reformat all
 source code (and may take some time to run).  Otherwise pass as arguments to
 the tool the files that changed and it will only reformat those.
 
+uncrustify
+==========
+
+Only [uncrustify](https://github.com/uncrustify/uncrustify) v0.71 or v0.72 can
+be used for MicroPython. Different uncrustify versions produce slightly
+different formatting, and the configuration file formats are often
+incompatible. v0.73 or newer *will not work*.
+
+Depending on your operating system version, it may be possible to install a pre-compiled
+uncrustify version:
+
+Ubuntu, Debian
+--------------
+
+Ubuntu versions 21.10 or 22.04LTS, and Debian versions bullseye or bookworm all
+include v0.72 so can be installed directly:
+
+```
+$ apt install uncrustify
+```
+
+Arch Linux
+----------
+
+The current Arch uncrustify version is too new. There is an [old Arch package
+for v0.72](https://archive.archlinux.org/packages/u/uncrustify/) that can be
+installed from the Arch Linux archive ([more
+information](https://wiki.archlinux.org/title/Downgrading_packages#Arch_Linux_Archive)). Use
+the [IgnorePkg feature](https://wiki.archlinux.org/title/Pacman#Skip_package_from_being_upgraded)
+to prevent it re-updating.
+
+Brew
+----
+
+This command may work, please raise a new Issue if it doesn't:
+
+```
+curl -L https://github.com/Homebrew/homebrew-core/raw/2b07d8192623365078a8b855a164ebcdf81494a6/Formula/uncrustify.rb > uncrustify.rb && brew install uncrustify.rb && rm uncrustify.rb
+```
+
+Automatic Pre-Commit Hooks
+==========================
+
+To have code formatting and commit message conventions automatically checked,
+a configuration file is provided for the [pre-commit](https://pre-commit.com/)
+tool.
+
+First install `pre-commit`, either from your system package manager or via
+`pip`. When installing `pre-commit` via pip, it is recommended to use a
+virtual environment. Other sources, such as Brew are also available, see
+[the docs](https://pre-commit.com/index.html#install) for details.
+
+```
+$ apt install pre-commit       # Ubuntu, Debian
+$ pacman -Sy python-precommit  # Arch Linux
+$ brew install pre-commit      # Brew
+$ pip install pre-commit       # PyPI
+```
+
+Next, install [uncrustify (see above)](#uncrustify). Other dependencies are managed by
+pre-commit automatically, but uncrustify needs to be installed and available on
+the PATH.
+
+Then, inside the MicroPython repository, register the git hooks for pre-commit
+by running:
+
+```
+$ pre-commit install --hook-type pre-commit --hook-type commit-msg
+```
+
+pre-commit will now automatically run during `git commit` for both code and
+commit message formatting.
+
+The same formatting checks will be run by CI for any Pull Request submitted to
+MicroPython. Pre-commit allows you to see any failure more quickly, and in many
+cases will automatically correct it in your local working copy.
+
+To unregister `pre-commit` from your MicroPython repository, run:
+
+```
+$ pre-commit uninstall --hook-type pre-commit --hook-type commit-msg
+```
+
+Tips:
+
+* To skip pre-commit checks on a single commit, use `git commit -n` (for
+  `--no-verify`).
+* To ignore the pre-commit message format check temporarily, start the commit
+  message subject line with "WIP" (for "Work In Progress").
+
 Python code conventions
 =======================
 

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013-2021 Damien P. George
+Copyright (c) 2013-2023 Damien P. George
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +19,66 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+Unless specified otherwise (see below), the above license and copyright applies
+to all files in this repository.
+
+Individual files may include additional copyright holders.
+
+The various ports of MicroPython may include third-party software that is
+licensed under different terms. These licenses are summarised in the tree
+below, please refer to these files and directories for further license and
+copyright information. Note that (L)GPL-licensed code listed below is only
+used during the build process and is not part of the compiled source code.
+
+/ (MIT)
+    /drivers
+        /cc3100 (BSD-3-clause)
+        /wiznet5k (BSD-3-clause)
+    /lib
+        /asf4 (Apache-2.0)
+        /axtls (BSD-3-clause)
+            /config
+                /scripts
+                    /config (GPL-2.0-or-later)
+                /Rules.mak (GPL-2.0)
+        /berkeley-db-1xx (BSD-4-clause)
+        /btstack (See btstack/LICENSE)
+        /cmsis (BSD-3-clause)
+        /crypto-algorithms (NONE)
+        /libhydrogen (ISC)
+        /littlefs (BSD-3-clause)
+        /lwip (BSD-3-clause)
+        /mynewt-nimble (Apache-2.0)
+        /nrfx (BSD-3-clause)
+        /nxp_driver (BSD-3-Clause)
+        /oofatfs (BSD-1-clause)
+        /pico-sdk (BSD-3-clause)
+        /re15 (BSD-3-clause)
+        /stm32lib (BSD-3-clause)
+        /tinytest (BSD-3-clause)
+        /tinyusb (MIT)
+        /uzlib (Zlib)
+    /logo (uses OFL-1.1)
+    /ports
+        /cc3200
+            /hal (BSD-3-clause)
+            /simplelink (BSD-3-clause)
+            /FreeRTOS (GPL-2.0 with FreeRTOS exception)
+        /stm32
+            /usbd*.c (MCD-ST Liberty SW License Agreement V2)
+            /stm32_it.* (MIT + BSD-3-clause)
+            /system_stm32*.c (MIT + BSD-3-clause)
+            /boards
+                /startup_stm32*.s (BSD-3-clause)
+                /*/stm32*.h (BSD-3-clause)
+            /usbdev (MCD-ST Liberty SW License Agreement V2)
+            /usbhost (MCD-ST Liberty SW License Agreement V2)
+        /teensy
+            /core (PJRC.COM)
+        /zephyr
+            /src (Apache-2.0)
+    /tools
+        /dfu.py (LGPL-3.0-only)

README.md

@@ -1,4 +1,4 @@
-[![CI badge](https://github.com/micropython/micropython/workflows/unix%20port/badge.svg)](https://github.com/micropython/micropython/actions?query=branch%3Amaster+event%3Apush) [![Coverage badge](https://coveralls.io/repos/micropython/micropython/badge.png?branch=master)](https://coveralls.io/r/micropython/micropython?branch=master)
+[![CI badge](https://github.com/micropython/micropython/workflows/unix%20port/badge.svg)](https://github.com/micropython/micropython/actions?query=branch%3Amaster+event%3Apush) [![codecov](https://codecov.io/gh/micropython/micropython/branch/master/graph/badge.svg?token=I92PfD05sD)](https://codecov.io/gh/micropython/micropython)
 
 The MicroPython project
 =======================
@@ -15,167 +15,43 @@ code-base, including project-wide name changes and API changes.
 
 MicroPython implements the entire Python 3.4 syntax (including exceptions,
 `with`, `yield from`, etc., and additionally `async`/`await` keywords from
-Python 3.5). The following core datatypes are provided: `str` (including
-basic Unicode support), `bytes`, `bytearray`, `tuple`, `list`, `dict`, `set`,
-`frozenset`, `array.array`, `collections.namedtuple`, classes and instances.
-Builtin modules include `sys`, `time`, and `struct`, etc. Select ports have
-support for `_thread` module (multithreading). Note that only a subset of
-Python 3 functionality is implemented for the data types and modules.
+Python 3.5 and some select features from later versions). The following core
+datatypes are provided: `str`(including basic Unicode support), `bytes`,
+`bytearray`, `tuple`, `list`, `dict`, `set`, `frozenset`, `array.array`,
+`collections.namedtuple`, classes and instances. Builtin modules include
+`os`, `sys`, `time`, `re`, and `struct`, etc. Select ports have support for
+`_thread` module (multithreading), `socket` and `ssl` for networking, and
+`asyncio`. Note that only a subset of Python 3 functionality is implemented
+for the data types and modules.
 
-MicroPython can execute scripts in textual source form or from precompiled
-bytecode, in both cases either from an on-device filesystem or "frozen" into
-the MicroPython executable.
+MicroPython can execute scripts in textual source form (.py files) or from
+precompiled bytecode (.mpy files), in both cases either from an on-device
+filesystem or "frozen" into the MicroPython executable.
 
-See the repository http://github.com/micropython/pyboard for the MicroPython
-board (PyBoard), the officially supported reference electronic circuit board.
+MicroPython also provides a set of MicroPython-specific modules to access
+hardware-specific functionality and peripherals such as GPIO, Timers, ADC,
+DAC, PWM, SPI, I2C, CAN, Bluetooth, and USB.
 
-Major components in this repository:
-- py/ -- the core Python implementation, including compiler, runtime, and
-  core library.
-- mpy-cross/ -- the MicroPython cross-compiler which is used to turn scripts
-  into precompiled bytecode.
-- ports/unix/ -- a version of MicroPython that runs on Unix.
-- ports/stm32/ -- a version of MicroPython that runs on the PyBoard and similar
-  STM32 boards (using ST's Cube HAL drivers).
-- ports/minimal/ -- a minimal MicroPython port. Start with this if you want
-  to port MicroPython to another microcontroller.
-- tests/ -- test framework and test scripts.
-- docs/ -- user documentation in Sphinx reStructuredText format. Rendered
-  HTML documentation is available at http://docs.micropython.org.
+Getting started
+---------------
 
-Additional components:
-- ports/bare-arm/ -- a bare minimum version of MicroPython for ARM MCUs. Used
-  mostly to control code size.
-- ports/teensy/ -- a version of MicroPython that runs on the Teensy 3.1
-  (preliminary but functional).
-- ports/pic16bit/ -- a version of MicroPython for 16-bit PIC microcontrollers.
-- ports/cc3200/ -- a version of MicroPython that runs on the CC3200 from TI.
-- ports/esp8266/ -- a version of MicroPython that runs on Espressif's ESP8266 SoC.
-- ports/esp32/ -- a version of MicroPython that runs on Espressif's ESP32 SoC.
-- ports/nrf/ -- a version of MicroPython that runs on Nordic's nRF51 and nRF52 MCUs.
-- extmod/ -- additional (non-core) modules implemented in C.
-- tools/ -- various tools, including the pyboard.py module.
-- examples/ -- a few example Python scripts.
+See the [online documentation](https://docs.micropython.org/) for API
+references and information about using MicroPython and information about how
+it is implemented.
 
-The subdirectories above may include READMEs with additional info.
+We use [GitHub Discussions](https://github.com/micropython/micropython/discussions)
+as our forum, and [Discord](https://discord.gg/RB8HZSAExQ) for chat. These
+are great places to ask questions and advice from the community or to discuss your
+MicroPython-based projects.
 
-"make" is used to build the components, or "gmake" on BSD-based systems.
-You will also need bash, gcc, and Python 3.3+ available as the command `python3`
-(if your system only has Python 2.7 then invoke make with the additional option
-`PYTHON=python2`).
+For bugs and feature requests, please [raise an issue](https://github.com/micropython/micropython/issues/new/choose)
+and follow the templates there.
 
-The MicroPython cross-compiler, mpy-cross
------------------------------------------
-
-Most ports require the MicroPython cross-compiler to be built first.  This
-program, called mpy-cross, is used to pre-compile Python scripts to .mpy
-files which can then be included (frozen) into the firmware/executable for
-a port.  To build mpy-cross use:
-
-    $ cd mpy-cross
-    $ make
-
-The Unix version
-----------------
-
-The "unix" port requires a standard Unix environment with gcc and GNU make.
-x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well
-as ARM and MIPS. Making full-featured port to another architecture requires
-writing some assembly code for the exception handling and garbage collection.
-Alternatively, fallback implementation based on setjmp/longjmp can be used.
-
-To build (see section below for required dependencies):
-
-    $ cd ports/unix
-    $ make submodules
-    $ make
-
-Then to give it a try:
-
-    $ ./micropython
-    >>> list(5 * x + y for x in range(10) for y in [4, 2, 1])
-
-Use `CTRL-D` (i.e. EOF) to exit the shell.
-Learn about command-line options (in particular, how to increase heap size
-which may be needed for larger applications):
-
-    $ ./micropython -h
-
-Run complete testsuite:
-
-    $ make test
-
-Unix version comes with a builtin package manager called upip, e.g.:
-
-    $ ./micropython -m upip install micropython-pystone
-    $ ./micropython -m pystone
-
-Browse available modules on
-[PyPI](https://pypi.python.org/pypi?%3Aaction=search&term=micropython).
-Standard library modules come from
-[micropython-lib](https://github.com/micropython/micropython-lib) project.
-
-External dependencies
----------------------
-
-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. 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, in the port directory you're
-interested in (e.g. `ports/unix/`) first execute:
-
-    $ make submodules
-
-This will fetch all the relevant git submodules (sub repositories) that
-the port needs.  Use the same command to get the latest versions of
-submodules as they are updated from time to time. After that 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 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,
-and so enabled by default), `MICROPY_PY_USSL` should be set to 1.
-
-For some ports, building required dependences is transparent, and happens
-automatically.  But they still need to be fetched with the `make submodules`
-command.
-
-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,
-arm-none-eabi-gcc and arm-none-eabi-newlib packages.  Otherwise, try here:
-https://launchpad.net/gcc-arm-embedded
-
-To build:
-
-    $ cd ports/stm32
-    $ make submodules
-    $ make
-
-You then need to get your board into DFU mode.  On the pyboard, connect the
-3V3 pin to the P1/DFU pin with a wire (on PYBv1.0 they are next to each other
-on the bottom left of the board, second row from the bottom).
-
-Then to flash the code via USB DFU to your device:
-
-    $ make deploy
-
-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.
+For information about the [MicroPython pyboard](https://store.micropython.org/pyb-features),
+the officially supported board from the
+[original Kickstarter campaign](https://www.kickstarter.com/projects/214379695/micro-python-python-for-microcontrollers),
+see the [schematics and pinouts](http://github.com/micropython/pyboard) and
+[documentation](https://docs.micropython.org/en/latest/pyboard/quickref.html).
 
 Contributing
 ------------
@@ -186,3 +62,87 @@ productive, please be sure to follow the
 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.
+
+About this repository
+---------------------
+
+This repository contains the following components:
+- [py/](py/) -- the core Python implementation, including compiler, runtime, and
+  core library.
+- [mpy-cross/](mpy-cross/) -- the MicroPython cross-compiler which is used to turn scripts
+  into precompiled bytecode.
+- [ports/](ports/) -- platform-specific code for the various ports and architectures that MicroPython runs on.
+- [lib/](lib/) -- submodules for external dependencies.
+- [tests/](tests/) -- test framework and test scripts.
+- [docs/](docs/) -- user documentation in Sphinx reStructuredText format. This is used to generate the [online documentation](http://docs.micropython.org).
+- [extmod/](extmod/) -- additional (non-core) modules implemented in C.
+- [tools/](tools/) -- various tools, including the pyboard.py module.
+- [examples/](examples/) -- a few example Python scripts.
+
+"make" is used to build the components, or "gmake" on BSD-based systems.
+You will also need bash, gcc, and Python 3.3+ available as the command `python3`
+(if your system only has Python 2.7 then invoke make with the additional option
+`PYTHON=python2`). Some ports (rp2 and esp32) additionally use CMake.
+
+Supported platforms & architectures
+-----------------------------------
+
+MicroPython runs on a wide range of microcontrollers, as well as on Unix-like
+(including Linux, BSD, macOS, WSL) and Windows systems.
+
+Microcontroller targets can be as small as 256kiB flash + 16kiB RAM, although
+devices with at least 512kiB flash + 128kiB RAM allow a much more
+full-featured experience.
+
+The [Unix](ports/unix) and [Windows](ports/windows) ports allow both
+development and testing of MicroPython itself, as well as providing
+lightweight alternative to CPython on these platforms (in particular on
+embedded Linux systems).
+
+The ["minimal"](ports/minimal) port provides an example of a very basic
+MicroPython port and can be compiled as both a standalone Linux binary as
+well as for ARM Cortex M4. Start with this if you want to port MicroPython to
+another microcontroller. Additionally the ["bare-arm"](ports/bare-arm) port
+is an example of the absolute minimum configuration, and is used to keep
+track of the code size of the core runtime and VM.
+
+In addition, the following ports are provided in this repository:
+ - [cc3200](ports/cc3200) -- Texas Instruments CC3200 (including PyCom WiPy).
+ - [esp32](ports/esp32) -- Espressif ESP32 SoC (including ESP32S2, ESP32S3, ESP32C3).
+ - [esp8266](ports/esp8266) -- Espressif ESP8266 SoC.
+ - [mimxrt](ports/mimxrt) -- NXP m.iMX RT (including Teensy 4.x).
+ - [nrf](ports/nrf) -- Nordic Semiconductor nRF51 and nRF52.
+ - [pic16bit](ports/pic16bit) -- Microchip PIC 16-bit.
+ - [powerpc](ports/powerpc) -- IBM PowerPC (including Microwatt)
+ - [qemu-arm](ports/qemu-arm) -- QEMU-based emulated target, for testing)
+ - [renesas-ra](ports/renesas-ra) -- Renesas RA family.
+ - [rp2](ports/rp2) -- Raspberry Pi RP2040 (including Pico and Pico W).
+ - [samd](ports/samd) -- Microchip (formerly Atmel) SAMD21 and SAMD51.
+ - [stm32](ports/stm32) -- STMicroelectronics STM32 family (including F0, F4, F7, G0, G4, H7, L0, L4, WB)
+ - [teensy](ports/teensy) -- Teensy 3.x.
+ - [webassembly](ports/webassembly) -- Emscripten port targeting browsers and NodeJS.
+ - [zephyr](ports/zephyr) -- Zephyr RTOS.
+
+The MicroPython cross-compiler, mpy-cross
+-----------------------------------------
+
+Most ports require the [MicroPython cross-compiler](mpy-cross) to be built
+first.  This program, called mpy-cross, is used to pre-compile Python scripts
+to .mpy files which can then be included (frozen) into the
+firmware/executable for a port.  To build mpy-cross use:
+
+    $ cd mpy-cross
+    $ make
+
+External dependencies
+---------------------
+
+The core MicroPython VM and runtime has no external dependencies, but a given
+port might depend on third-party drivers or vendor HALs. This repository
+includes [several submodules](lib/) linking to these external dependencies.
+Before compiling a given port, use
+
+    $ cd ports/name
+    $ make submodules
+
+to ensure that all required submodules are initialised.

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 PYTHON        = python3
-SPHINXOPTS    = -W --keep-going
+SPHINXOPTS    = -W --keep-going -j auto
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build/$(MICROPY_PORT)

docs/README.md

@@ -47,7 +47,7 @@ This can be achieved with:
 
     make latexpdf
 
-but require rather complete install of LaTeX with various extensions. On
-Debian/Ubuntu, try (500MB+ download):
+but requires a rather complete install of LaTeX with various extensions. On
+Debian/Ubuntu, try (1GB+ download):
 
-    apt-get install texlive-latex-recommended texlive-latex-extra
+    apt install texlive-latex-recommended texlive-latex-extra texlive-xetex texlive-fonts-extra cm-super xindy

docs/conf.py

@@ -33,6 +33,7 @@ html_context = {
     'downloads':[
         ('PDF', url_pattern % micropy_version + '/micropython-docs.pdf'),
     ],
+    'is_release': micropy_version != 'latest',
 }
 
 
@@ -66,7 +67,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'MicroPython'
-copyright = '2014-2021, Damien P. George, Paul Sokolovsky, and contributors'
+copyright = '- The MicroPython Documentation is Copyright © 2014-2023, Damien P. George, Paul Sokolovsky, and contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -74,7 +75,7 @@ copyright = '2014-2021, Damien P. George, Paul Sokolovsky, and contributors'
 #
 # We don't follow "The short X.Y version" vs "The full version, including alpha/beta/rc tags"
 # breakdown, so use the same version identifier for both to avoid confusion.
-version = release = '1.16'
+version = release = micropy_version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -166,6 +167,10 @@ html_favicon = 'static/favicon.ico'
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['static']
 
+# Add a custom CSS file for HTML generation
+html_css_files = [
+    'custom.css',
+]
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
@@ -259,6 +264,8 @@ latex_documents = [
 # If false, no module index is generated.
 #latex_domain_indices = True
 
+# Enable better Unicode support so that `make latexpdf` doesn't fail
+latex_engine = "xelatex"
 
 # -- Options for manual page output ---------------------------------------
 

docs/develop/cmodules.rst

@@ -49,9 +49,17 @@ A MicroPython user C module is a directory with the following files:
   in your ``micropython.mk`` to a local make variable,
   eg ``EXAMPLE_MOD_DIR := $(USERMOD_DIR)``
 
-  Your ``micropython.mk`` must add your modules source files relative to your
-  expanded copy of ``$(USERMOD_DIR)`` to ``SRC_USERMOD``, eg
-  ``SRC_USERMOD += $(EXAMPLE_MOD_DIR)/example.c``
+  Your ``micropython.mk`` must add your modules source files to the
+  ``SRC_USERMOD_C`` or ``SRC_USERMOD_LIB_C`` variables. The former will be
+  processed for ``MP_QSTR_`` and ``MP_REGISTER_MODULE`` definitions, the latter
+  will not (e.g. helpers and library code that isn't MicroPython-specific).
+  These paths should include your expaned copy of ``$(USERMOD_DIR)``, e.g.::
+
+    SRC_USERMOD_C += $(EXAMPLE_MOD_DIR)/modexample.c
+    SRC_USERMOD_LIB_C += $(EXAMPLE_MOD_DIR)/utils/algorithm.c
+
+  Similarly, use ``SRC_USERMOD_CXX`` and ``SRC_USERMOD_LIB_CXX`` for C++
+  source files.
 
   If you have custom compiler options (like ``-I`` to add directories to search
   for header files), these should be added to ``CFLAGS_USERMOD`` for C code
@@ -87,9 +95,12 @@ A MicroPython user C module is a directory with the following files:
 Basic example
 -------------
 
-This simple module named ``cexample`` provides a single function
-``cexample.add_ints(a, b)`` which adds the two integer args together and returns
-the result. It can be found in the MicroPython source tree
+The ``cexample`` module provides examples for a function and a class. The
+``cexample.add_ints(a, b)`` function adds two integer args together and returns
+the result. The ``cexample.Timer()`` type creates timers that can be used to
+measure the elapsed time since the object is instantiated.
+
+The module can be found in the MicroPython source tree
 `in the examples directory <https://github.com/micropython/micropython/tree/master/examples/usercmodule/cexample>`_
 and has a source file and a Makefile fragment with content as described above::
 
@@ -221,23 +232,25 @@ as described above.
 If a module is not enabled by default then the corresponding C preprocessor macro
 must be enabled.  This macro name can be found by searching for the ``MP_REGISTER_MODULE``
 line in the module's source code (it usually appears at the end of the main source file).
-The third argument to ``MP_REGISTER_MODULE`` is the macro name, and this must be set
-to 1 using ``CFLAGS_EXTRA`` to make the module available.  If the third argument is just
-the number 1 then the module is enabled by default.
+This macro should be surrounded by a ``#if X`` / ``#endif`` pair, and the configuration
+option ``X`` must be set to 1 using ``CFLAGS_EXTRA`` to make the module available.  If
+there is no ``#if X`` / ``#endif`` pair then the module is enabled by default.
 
 For example, the ``examples/usercmodule/cexample`` module is enabled by default so
 has the following line in its source code:
 
   .. code-block:: c
 
-      MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, 1);
+      MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule);
 
 Alternatively, to make this module disabled by default but selectable through
 a preprocessor configuration option, it would be:
 
   .. code-block:: c
 
-      MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, MODULE_CEXAMPLE_ENABLED);
+      #if MODULE_CEXAMPLE_ENABLED
+      MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule);
+      #endif
 
 In this case the module is enabled by adding ``CFLAGS_EXTRA=-DMODULE_CEXAMPLE_ENABLED=1``
 to the ``make`` command, or editing ``mpconfigport.h`` or ``mpconfigboard.h`` to add
@@ -262,3 +275,13 @@ can now be accessed in Python just like any other builtin module, e.g.
     import cexample
     print(cexample.add_ints(1, 3))
     # should display 4
+
+.. code-block:: python
+
+    from cexample import Timer
+    from time import sleep_ms
+
+    watch = Timer()
+    sleep_ms(1000)
+    print(watch.time())
+    # should display approximately 1000

docs/develop/compiler.rst

@@ -147,10 +147,17 @@ The most relevant method you should know about is this:
 .. code-block:: c
 
    mp_obj_t mp_compile(mp_parse_tree_t *parse_tree, qstr source_file, bool is_repl) {
+       // Create a context for this module, and set its globals dict.
+       mp_module_context_t *context = m_new_obj(mp_module_context_t);
+       context->module.globals = mp_globals_get();
+
        // Compile the input parse_tree to a raw-code structure.
-       mp_raw_code_t *rc = mp_compile_to_raw_code(parse_tree, source_file, is_repl);
+       mp_compiled_module_t cm;
+       cm.context = context;
+       mp_compile_to_raw_code(parse_tree, source_file, is_repl, &cm);
+
        // Create and return a function object that executes the outer module.
-       return mp_make_function_from_raw_code(rc, MP_OBJ_NULL, MP_OBJ_NULL);
+       return mp_make_function_from_raw_code(cm.rc, cm.context, NULL);
    }
 
 The compiler compiles the code in four passes: scope, stack size, code size and emit.

docs/develop/extendingmicropython.rst

@@ -16,4 +16,3 @@ live in the main MicroPython repository.
 
    cmodules.rst
    natmod.rst
-   

docs/develop/gettingstarted.rst

@@ -4,7 +4,7 @@ Getting Started
 ===============
 
 This guide covers a step-by-step process on setting up version control, obtaining and building
-a copy of the source code for a port, building the documentation, running tests, and a description of the 
+a copy of the source code for a port, building the documentation, running tests, and a description of the
 directory structure of the MicroPython code base.
 
 Source control with git
@@ -16,7 +16,7 @@ code is pulled and pushed to and from the main repository. Install the respectiv
 of Git for your operating system to follow through the rest of the steps.
 
 .. note::
-   For a reference on the installation instructions, please refer to 
+   For a reference on the installation instructions, please refer to
    the `Git installation instructions <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_.
    Learn about the basic git commands in this `Git Handbook <https://guides.github.com/introduction/git-handbook/>`_
    or any other sources on the internet.
@@ -58,12 +58,12 @@ MicroPython repository.
 After the above configuration, your setup should be similar to this:
 
 .. code-block:: bash
-   
+
    $ git remote -v
-   origin	https://github.com/<your-user-name>/micropython (fetch)
-   origin	https://github.com/<your-user-name>/micropython (push)
-   upstream	https://github.com/micropython/micropython (fetch)
-   upstream	https://github.com/micropython/micropython (push)
+   origin       https://github.com/<your-user-name>/micropython (fetch)
+   origin       https://github.com/<your-user-name>/micropython (push)
+   upstream     https://github.com/micropython/micropython (fetch)
+   upstream     https://github.com/micropython/micropython (push)
 
 You should now have a copy of the source code. By default, you are pointing
 to the master branch. To prepare for further development, it is recommended
@@ -73,7 +73,7 @@ to work on a development branch.
 
     $ git checkout -b dev-branch
 
-You can give it any name. You will have to compile MicroPython whenever you change 
+You can give it any name. You will have to compile MicroPython whenever you change
 to a different branch.
 
 Compile and build the code
@@ -103,7 +103,7 @@ For the stm32 port, the ARM cross-compiler is required:
    $ sudo apt-get install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
 
 See the `ARM GCC
-toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
+toolchain <https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads>`_
 for the latest details.
 
 Python is also required. Python 2 is supported for now, but we recommend using Python 3.
@@ -140,8 +140,8 @@ If it built successfully, you should see a message similar to this:
 .. code-block:: bash
 
    LINK mpy-cross
-      text	   data	    bss	    dec	    hex	filename
-    279328	    776	    880	 280984	  44998	mpy-cross
+      text          data    bss     dec     hex filename
+    279328          776     880  280984   44998 mpy-cross
 
 .. note::
 
@@ -181,8 +181,8 @@ If MicroPython built correctly, you should see the following:
 .. code-block:: bash
 
    LINK micropython
-      text	   data	    bss	    dec	    hex	filename
-    412033	   5680	   2496	 420209	  66971	micropython
+      text         data     bss     dec     hex filename
+    412033         5680    2496  420209   66971 micropython
 
 Now run it:
 
@@ -215,7 +215,7 @@ as detailed in the :ref:`required_dependencies` section, then build:
    $ make submodules
    $ make
 
-Please refer to the `stm32 documentation <https://github.com/micropython/micropython/tree/master/ports/stm32>`_ 
+Please refer to the `stm32 documentation <https://github.com/micropython/micropython/tree/master/ports/stm32>`_
 for more details on flashing the firmware.
 
 .. note::
@@ -259,7 +259,7 @@ Build the docs:
 
    $ make html
 
-Open ``docs/build/html/index.html`` in your browser to view the docs locally. Refer to the 
+Open ``docs/build/html/index.html`` in your browser to view the docs locally. Refer to the
 documentation on `importing your documentation
 <https://docs.readthedocs.io/en/stable/intro/import-guide.html>`_ to use Read the Docs.
 
@@ -322,7 +322,8 @@ tests
 
 tools
 
-  Contains helper tools including the ``upip`` and the ``pyboard.py`` module.
+  Contains scripts used by the build and CI process, as well as user tools such
+  as ``pyboard.py`` and ``mpremote``.
 
 examples
 

docs/develop/index.rst

@@ -5,7 +5,7 @@ This chapter covers a tour of MicroPython from the perspective of a developer, c
 to MicroPython. It acts as a comprehensive resource on the implementation details of MicroPython
 for both novice and expert contributors.
 
-Development around MicroPython usually involves modifying the core runtime, porting or 
+Development around MicroPython usually involves modifying the core runtime, porting or
 maintaining a new library. This guide describes at great depth, the implementation
 details of MicroPython including a getting started guide, compiler internals, porting
 MicroPython to a new platform and implementing a core MicroPython library.
@@ -24,4 +24,3 @@ MicroPython to a new platform and implementing a core MicroPython library.
    publiccapi.rst
    extendingmicropython.rst
    porting.rst
-   

docs/develop/library.rst

@@ -34,7 +34,7 @@ An example is the ``gc`` module discussed in :ref:`memorymanagement`.
    >>> gc.enable()
    >>>
 
-MicroPython has several other builtin standard/core modules like ``io``, ``uarray`` etc.
+MicroPython has several other builtin standard/core modules like ``io``, ``array`` etc.
 Adding a new core module involves several modifications.
 
 First, create the ``C`` file in the ``py/`` directory. In this example we are adding a
@@ -64,7 +64,7 @@ hypothetical new module ``subsystem`` in the file ``modsubsystem.c``:
        .globals = (mp_obj_dict_t *)&mp_module_subsystem_globals,
    };
 
-   MP_REGISTER_MODULE(MP_QSTR_subsystem, mp_module_subsystem, MICROPY_PY_SUBSYSTEM);
+   MP_REGISTER_MODULE(MP_QSTR_subsystem, mp_module_subsystem);
 
    #endif
 

docs/develop/natmod.rst

@@ -34,6 +34,7 @@ options for the ``ARCH`` variable, see below):
 
 * ``x86`` (32 bit)
 * ``x64`` (64 bit x86)
+* ``armv6m`` (ARM Thumb, eg Cortex-M0)
 * ``armv7m`` (ARM Thumb 2, eg Cortex-M3)
 * ``armv7emsp`` (ARM Thumb 2, single precision float, eg Cortex-M4F, Cortex-M7)
 * ``armv7emdp`` (ARM Thumb 2, double precision float, eg Cortex-M7)
@@ -171,7 +172,7 @@ The file ``Makefile`` contains:
     # Source files (.c or .py)
     SRC = factorial.c
 
-    # Architecture to build for (x86, x64, armv7m, xtensa, xtensawin)
+    # Architecture to build for (x86, x64, armv6m, armv7m, xtensa, xtensawin)
     ARCH = x64
 
     # Include to get the rules for compiling and linking the module

docs/develop/optimizations.rst

@@ -25,6 +25,8 @@ into the firmware image as part of the main firmware compilation process, which
 the bytecode will be executed from ROM. This can lead to a significant memory saving, and
 reduce heap fragmentation.
 
+See :ref:`manifest` for more information.
+
 Variables
 ---------
 

docs/develop/porting.rst

@@ -42,8 +42,8 @@ The basic MicroPython firmware is implemented in the main port file, e.g ``main.
    #include "py/gc.h"
    #include "py/mperrno.h"
    #include "py/stackctrl.h"
-   #include "lib/utils/gchelper.h"
-   #include "lib/utils/pyexec.h"
+   #include "shared/runtime/gchelper.h"
+   #include "shared/runtime/pyexec.h"
 
    // Allocate memory for the MicroPython GC heap.
    static char heap[4096];
@@ -53,8 +53,6 @@ The basic MicroPython firmware is implemented in the main port file, e.g ``main.
        mp_stack_ctrl_init();
        gc_init(heap, heap + sizeof(heap));
        mp_init();
-       mp_obj_list_init(MP_OBJ_TO_PTR(mp_sys_path), 0);
-       mp_obj_list_init(MP_OBJ_TO_PTR(mp_sys_argv), 0);
 
        // Start a normal REPL; will exit when ctrl-D is entered on a blank line.
        pyexec_friendly_repl();
@@ -97,19 +95,20 @@ We also need a Makefile at this point for the port:
 
    # Include py core make definitions.
    include $(TOP)/py/py.mk
+   include $(TOP)/extmod/extmod.mk
 
    # Set CFLAGS and libraries.
-   CFLAGS = -I. -I$(BUILD) -I$(TOP)
-   LIBS = -lm
+   CFLAGS += -I. -I$(BUILD) -I$(TOP)
+   LIBS += -lm
 
    # Define the required source files.
    SRC_C = \
        main.c \
        mphalport.c \
-       lib/mp-readline/readline.c \
-       lib/utils/gchelper_generic.c \
-       lib/utils/pyexec.c \
-       lib/utils/stdout_helpers.c \
+       shared/readline/readline.c \
+       shared/runtime/gchelper_generic.c \
+       shared/runtime/pyexec.c \
+       shared/runtime/stdout_helpers.c \
 
    # Define the required object files.
    OBJ = $(PY_CORE_O) $(addprefix $(BUILD)/, $(SRC_C:.c=.o))
@@ -148,6 +147,9 @@ The following is an example of an ``mpconfigport.h`` file:
    #define MICROPY_ERROR_REPORTING                 (MICROPY_ERROR_REPORTING_TERSE)
    #define MICROPY_FLOAT_IMPL                      (MICROPY_FLOAT_IMPL_FLOAT)
 
+   // Enable u-modules to be imported with their standard name, like sys.
+   #define MICROPY_MODULE_WEAK_LINKS               (1)
+
    // Fine control over Python builtins, classes, modules, etc.
    #define MICROPY_PY_ASYNC_AWAIT                  (0)
    #define MICROPY_PY_BUILTINS_SET                 (0)
@@ -172,9 +174,6 @@ The following is an example of an ``mpconfigport.h`` file:
 
    #define MP_STATE_PORT MP_STATE_VM
 
-   #define MICROPY_PORT_ROOT_POINTERS \
-       const char *readline_hist[8];
-
 This configuration file contains machine-specific configurations including aspects like if different
 MicroPython features should be enabled e.g. ``#define MICROPY_ENABLE_GC (1)``. Making this Setting
 ``(0)`` disables the feature.
@@ -245,8 +244,8 @@ That should give a MicroPython REPL.  You can then run commands like:
 .. code-block:: bash
 
    MicroPython v1.13 on 2021-01-01; example-board with unknown-cpu
-   >>> import usys
-   >>> usys.implementation
+   >>> import sys
+   >>> sys.implementation
    ('micropython', (1, 13, 0))
    >>>
 
@@ -279,12 +278,7 @@ To add a custom module like ``myport``, first add the module definition in a fil
        .globals = (mp_obj_dict_t *)&myport_module_globals,
    };
 
-   MP_REGISTER_MODULE(MP_QSTR_myport, myport_module, 1);
-
-Note: the "1" as the third argument in ``MP_REGISTER_MODULE`` enables this new module
-unconditionally. To allow it to be conditionally enabled, replace the "1" by
-``MICROPY_PY_MYPORT`` and then add ``#define MICROPY_PY_MYPORT (1)`` in ``mpconfigport.h``
-accordingly.
+   MP_REGISTER_MODULE(MP_QSTR_myport, myport_module);
 
 You will also need to edit the Makefile to add ``modmyport.c`` to the ``SRC_C`` list, and
 a new line adding the same file to ``SRC_QSTR`` (so qstrs are searched for in this new file),
@@ -298,7 +292,7 @@ like this:
        mphalport.c \
        ...
 
-   SRC_QSTR += modport.c
+   SRC_QSTR += modmyport.c
 
 If all went correctly then, after rebuilding, you should be able to import the new module:
 

docs/develop/qstr.rst

@@ -59,7 +59,7 @@ Processing happens in the following stages:
    information.  Note that this step only uses files that have changed, which
    means that ``qstr.i.last`` will only contain data from files that have
    changed since the last compile.
-   
+
 2. ``qstr.split`` is an empty file created after running ``makeqstrdefs.py split``
    on qstr.i.last. It's just used as a dependency to indicate that the step ran.
    This script outputs one file per input C file,  ``genhdr/qstr/...file.c.qstr``,

docs/differences/index_template.txt

@@ -3,8 +3,22 @@
 MicroPython differences from CPython
 ====================================
 
-The operations listed in this section produce conflicting results in MicroPython when compared to standard Python.
-MicroPython implements Python 3.4 and some select features of Python 3.5.
+MicroPython implements Python 3.4 and some select features of Python 3.5 and
+above.  The sections below describe the current status of these features.
+
+.. toctree::
+
+    ../differences/python_35.rst
+    ../differences/python_36.rst
+    ../differences/python_37.rst
+    ../differences/python_38.rst
+    ../differences/python_39.rst
+    ../differences/python_310.rst
+
+For the features of Python that are implemented by MicroPython, there are
+sometimes differences in their behaviour compared to standard Python.  The
+operations listed in the sections below produce conflicting results in
+MicroPython when compared to standard Python.
 
 .. toctree::
     :maxdepth: 2

docs/differences/python_310.rst

@@ -0,0 +1,238 @@
+.. _python_310:
+
+Python 3.10
+===========
+
+Python 3.10.0 (final) was released on the 4 October 2021. The Features for 3.10 are
+defined in `PEP 619 <https://www.python.org/dev/peps/pep-0619/#features-for-3-10>`_
+and a detailed description of the changes can be found in
+`What's New in Python 3.10 <https://docs.python.org/3/whatsnew/3.10.html>`_.
+
+.. table::
+  :widths: 20 60 20
+
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | **New syntax features**                                                                                     | **Status**   |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 634 <https://www.python.org/dev/peps/pep-0634/>`_ | Structural Pattern Matching: Specification         | [#spm]_      |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 635 <https://www.python.org/dev/peps/pep-0635/>`_ | Structural Pattern Matching: Motivation and        | [#spm]_      |
+  |                                                        | Rationale                                          |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 636 <https://www.python.org/dev/peps/pep-0636/>`_ | Structural Pattern Matching: Tutorial              | [#spm]_      |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `bpo-12782                                             | Parenthesized context managers are now officially  |              |
+  | <https://github.com/python/cpython/issues/56991>`_     | allowed                                            |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | **New features in the standard library**                                                                                   |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 618 <https://www.python.org/dev/peps/pep-0618/>`_ | Add Optional Length-Checking To zip                |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | **Interpreter improvements**                                                                                               |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 626 <https://www.python.org/dev/peps/pep-0626/>`_ | Precise line numbers for debugging and other tools |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | **New typing features**                                                                                                    |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 604 <https://www.python.org/dev/peps/pep-0604/>`_ | Allow writing union types as X | Y                 |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 613 <https://www.python.org/dev/peps/pep-0613/>`_ | Explicit Type Aliases                              |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 612 <https://www.python.org/dev/peps/pep-0612/>`_ | Parameter Specification Variables                  |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | **Important deprecations, removals or restrictions**                                                                       |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 644 <https://www.python.org/dev/peps/pep-0644/>`_ | Require OpenSSL 1.1.1 or newer                     |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 632 <https://www.python.org/dev/peps/pep-0632/>`_ | Deprecate distutils module.                        | Not relevant |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 623 <https://www.python.org/dev/peps/pep-0623/>`_ | Deprecate and prepare for the removal of the wstr  | Not relevant |
+  |                                                        | member in PyUnicodeObject.                         |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 624 <https://www.python.org/dev/peps/pep-0624/>`_ | Remove Py_UNICODE encoder APIs                     | Not relevant |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+  | `PEP 597 <https://www.python.org/dev/peps/pep-0597/>`_ | Add optional EncodingWarning                       |              |
+  +--------------------------------------------------------+----------------------------------------------------+--------------+
+
+
+Other Language Changes:
+
+.. table::
+  :widths: 90 10
+
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | The :class:`int` type has a new method :meth:`int.bit_count`, returning the                                 |               |
+  | number of ones in the binary expansion of a given integer, also known                                       |               |
+  | as the population count.                                                                                    |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | The views returned by :meth:`dict.keys`, :meth:`dict.values` and                                            |               |
+  | :meth:`dict.items` now all have a ``mapping`` attribute that gives a                                        |               |
+  | :class:`types.MappingProxyType` object wrapping the original                                                |               |
+  | dictionary.                                                                                                 |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | :pep:`618`: The :func:`zip` function now has an optional ``strict`` flag, used                              |               |
+  | to require that all the iterables have an equal length.                                                     |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Builtin and extension functions that take integer arguments no longer accept                                |               |
+  | :class:`~decimal.Decimal`\ s, :class:`~fractions.Fraction`\ s and other                                     |               |
+  | objects that can be converted to integers only with a loss (e.g. that have                                  |               |
+  | the :meth:`~object.__int__` method but do not have the                                                      |               |
+  | :meth:`~object.__index__` method).                                                                          |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | If :func:`object.__ipow__` returns :const:`NotImplemented`, the operator will                               |               |
+  | correctly fall back to :func:`object.__pow__` and :func:`object.__rpow__` as expected.                      |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Assignment expressions can now be used unparenthesized within set literals                                  |               |
+  | and set comprehensions, as well as in sequence indexes (but not slices).                                    |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Functions have a new ``__builtins__`` attribute which is used to look for                                   |               |
+  | builtin symbols when a function is executed, instead of looking into                                        |               |
+  | ``__globals__['__builtins__']``. The attribute is initialized from                                          |               |
+  | ``__globals__["__builtins__"]`` if it exists, else from the current builtins.                               |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Two new builtin functions -- :func:`aiter` and :func:`anext` have been added                                |               |
+  | to provide asynchronous counterparts to :func:`iter` and :func:`next`,                                      |               |
+  | respectively.                                                                                               |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Static methods (:func:`@staticmethod <staticmethod>`) and class methods                                     |               |
+  | (:func:`@classmethod <classmethod>`) now inherit the method attributes                                      |               |
+  | (``__module__``, ``__name__``, ``__qualname__``, ``__doc__``,                                               |               |
+  | ``__annotations__``) and have a new ``__wrapped__`` attribute.                                              |               |
+  | Moreover, static methods are now callable as regular functions.                                             |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Annotations for complex targets (everything beside ``simple name`` targets                                  |               |
+  | defined by :pep:`526`) no longer cause any runtime effects with ``from __future__ import annotations``.     |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Class and module objects now lazy-create empty annotations dicts on demand.                                 |               |
+  | The annotations dicts are stored in the object’s ``__dict__`` for                                           |               |
+  | backwards compatibility.  This improves the best practices for working                                      |               |
+  | with ``__annotations__``.                                                                                   |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Annotations consist of ``yield``, ``yield from``, ``await`` or named expressions                            |               |
+  | are now forbidden under ``from __future__ import annotations`` due to their side                            |               |
+  | effects.                                                                                                    |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Usage of unbound variables, ``super()`` and other expressions that might                                    |               |
+  | alter the processing of symbol table as annotations are now rendered                                        |               |
+  | effectless under ``from __future__ import annotations``.                                                    |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Hashes of NaN values of both :class:`float` type and                                                        |               |
+  | :class:`decimal.Decimal` type now depend on object identity. Formerly, they                                 |               |
+  | always hashed to ``0`` even though NaN values are not equal to one another.                                 |               |
+  | This caused potentially quadratic runtime behavior due to excessive hash                                    |               |
+  | collisions when creating dictionaries and sets containing multiple NaNs.                                    |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | A :exc:`SyntaxError` (instead of a :exc:`NameError`) will be raised when deleting                           |               |
+  | the :const:`__debug__` constant.                                                                            |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | :exc:`SyntaxError` exceptions now have ``end_lineno`` and                                                   |               |
+  | ``end_offset`` attributes.  They will be ``None`` if not determined.                                        |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+
+Changes to built-in modules:
+
+.. table::
+  :widths: 90 10
+
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `asyncio <https://docs.python.org/3/whatsnew/3.10.html#asyncio>`_                                                             |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add missing :meth:`~asyncio.events.AbstractEventLoop.connect_accepted_socket`                                 |               |
+  | method.                                                                                                       |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `array <https://docs.python.org/3/whatsnew/3.10.html#array>`_                                                                 |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The :meth:`~array.array.index` method of :class:`array.array` now has                                         |               |
+  | optional *start* and *stop* parameters.                                                                       |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `gc <https://docs.python.org/3/whatsnew/3.10.html#gc>`_                                                                       |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add audit hooks for :func:`gc.get_objects`, :func:`gc.get_referrers` and                                      |               |
+  | :func:`gc.get_referents`.                                                                                     |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `hashlib <https://docs.python.org/3/whatsnew/3.10.html#hashlib>`_                                                             |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The hashlib module requires OpenSSL 1.1.1 or newer.                                                           |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The hashlib module has preliminary support for OpenSSL 3.0.0.                                                 |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The pure-Python fallback of :func:`~hashlib.pbkdf2_hmac` is deprecated. In                                    |               |
+  | the future PBKDF2-HMAC will only be available when Python has been built with                                 |               |
+  | OpenSSL support.                                                                                              |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `os <https://docs.python.org/3/whatsnew/3.10.html#os>`_                                                                       |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :func:`os.cpu_count()` support for VxWorks RTOS.                                                          |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add a new function :func:`os.eventfd` and related helpers to wrap the                                         |               |
+  | ``eventfd2`` syscall on Linux.                                                                                |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :func:`os.splice()` that allows to move data between two file                                             |               |
+  | descriptors without copying between kernel address space and user                                             |               |
+  | address space, where one of the file descriptors must refer to a                                              |               |
+  | pipe.                                                                                                         |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :data:`~os.O_EVTONLY`, :data:`~os.O_FSYNC`, :data:`~os.O_SYMLINK`                                         |               |
+  | and :data:`~os.O_NOFOLLOW_ANY` for macOS.                                                                     |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `platform <https://docs.python.org/3/whatsnew/3.10.html#platform>`_                                                           |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :func:`platform.freedesktop_os_release()` to retrieve operation system                                    |               |
+  | identification from `freedesktop.org os-release                                                               |               |
+  | <https://www.freedesktop.org/software/systemd/man/os-release.html>`_ standard file.                           |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `socket <https://docs.python.org/3/whatsnew/3.10.html#socket>`_                                                               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The exception :exc:`socket.timeout` is now an alias of :exc:`TimeoutError`.                                   |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add option to create MPTCP sockets with ``IPPROTO_MPTCP``.                                                    |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add ``IP_RECVTOS`` option to receive the type of service (ToS) or DSCP/ECN fields.                            |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `ssl <https://docs.python.org/3/whatsnew/3.10.html#ssl>`_                                                                     |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The ssl module requires OpenSSL 1.1.1 or newer.                                                               |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The ssl module has preliminary support for OpenSSL 3.0.0 and new option                                       |               |
+  | :data:`~ssl.OP_IGNORE_UNEXPECTED_EOF`.                                                                        |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Deprecated function and use of deprecated constants now result in                                             |               |
+  | a :exc:`DeprecationWarning`. :attr:`ssl.SSLContext.options` has                                               |               |
+  | :data:`~ssl.OP_NO_SSLv2` and :data:`~ssl.OP_NO_SSLv3` set by default and                                      |               |
+  | therefore cannot warn about setting the flag again.                                                           |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The ssl module now has more secure default settings. Ciphers without forward                                  |               |
+  | secrecy or SHA-1 MAC are disabled by default. Security level 2 prohibits                                      |               |
+  | weak RSA, DH, and ECC keys with less than 112 bits of security.                                               |               |
+  | :class:`~ssl.SSLContext` defaults to minimum protocol version TLS 1.2.                                        |               |
+  | Settings are based on Hynek Schlawack's research.                                                             |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The deprecated protocols SSL 3.0, TLS 1.0, and TLS 1.1 are no longer                                          |               |
+  | officially supported. Python does not block them actively. However                                            |               |
+  | OpenSSL build options, distro configurations, vendor patches, and cipher                                      |               |
+  | suites may prevent a successful handshake.                                                                    |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add a *timeout* parameter to the :func:`ssl.get_server_certificate` function.                                 |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The ssl module uses heap-types and multi-phase initialization.                                                |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | A new verify flag :data:`~ssl.VERIFY_X509_PARTIAL_CHAIN` has been added.                                      |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `sys <https://docs.python.org/3/whatsnew/3.10.html#sys>`_                                                                     |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :data:`sys.orig_argv` attribute: the list of the original command line                                    |               |
+  | arguments passed to the Python executable.                                                                    |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Add :data:`sys.stdlib_module_names`, containing the list of the standard library                              |               |
+  | module names.                                                                                                 |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `_thread <https://docs.python.org/3/whatsnew/3.10.html#_thread>`_                                                             |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | :func:`_thread.interrupt_main` now takes an optional signal number to                                         |               |
+  | simulate (the default is still :data:`signal.SIGINT`).                                                        |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+
+.. rubric:: Notes
+
+.. [#spm] The structural pattern matching feature is discussed in `issue #7847 <https://github.com/micropython/micropython/issues/7847>`_.
+

docs/differences/python_35.rst

@@ -0,0 +1,193 @@
+.. _python_35:
+
+Python 3.5
+==========
+
+Below is a list of finalised/accepted PEPs for Python 3.5 grouped into their impact to MicroPython.
+
+.. table::
+  :widths: 30 50 20
+
+  +--------------------------------------------------------------------------------------------------------------+--------------------+
+  | **Extensions to the syntax**                                                                                 | **Status**         |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 448 <https://www.python.org/dev/peps/pep-0448/>`_ | Additional unpacking generalizations                | Partial            |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 465 <https://www.python.org/dev/peps/pep-0465/>`_ | A new matrix multiplication operator                | Complete           |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 492 <https://www.python.org/dev/peps/pep-0492/>`_ | Coroutines with ``async`` and ``await`` syntax      | Complete           |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | **Extensions and changes to runtime**                                                                                             |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 461 <https://www.python.org/dev/peps/pep-0461/>`_ | % formatting for binary strings                     | Complete           |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 475 <https://www.python.org/dev/peps/pep-0475/>`_ | Retrying system calls that fail with ``EINTR``      | Complete           |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 479 <https://www.python.org/dev/peps/pep-0479/>`_ | Change ``StopIteration`` handling inside generators | Complete           |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | **Standard library changes**                                                                                                      |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 471 <https://www.python.org/dev/peps/pep-0471/>`_ | ``os.scandir()``                                    |                    |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 485 <https://www.python.org/dev/peps/pep-0485/>`_ | ``math.isclose()``, a function for testing          | Complete           |
+  |                                                        | approximate equality                                |                    |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | **Miscellaneous changes**                                                                                                         |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 441 <https://www.python.org/dev/peps/pep-0441/>`_ | Improved Python zip application support             |                    |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 486 <https://www.python.org/dev/peps/pep-0486/>`_ | Make the Python Launcher aware of virtual           | Not relevant       |
+  |                                                        | environments                                        |                    |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ | Type hints (advisory only)                          | Complete [#fth]_   |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 488 <https://www.python.org/dev/peps/pep-0488/>`_ | Elimination of PYO files                            | Not relevant       |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+  | `PEP 489 <https://www.python.org/dev/peps/pep-0489/>`_ | Redesigning extension module loading                |                    |
+  +--------------------------------------------------------+-----------------------------------------------------+--------------------+
+
+Other Language Changes:
+
+.. table::
+  :widths: 90 10
+
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Added the *namereplace* error handlers. The *backslashreplace* error handlers now work with decoding and  |               |
+  | translating.                                                                                              |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Property docstrings are now writable. This is especially useful for collections.namedtuple() docstrings   |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Circular imports involving relative imports are now supported.                                            |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+
+
+New Modules:
+
+* `typing <https://docs.python.org/3/whatsnew/3.5.html#typing>`_
+
+* `zipzap <https://docs.python.org/3/whatsnew/3.5.html#zipapp>`_
+
+
+Changes to built-in modules:
+
+.. table::
+  :widths: 90 10
+
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `collections <https://docs.python.org/3/whatsnew/3.5.html#collections>`_                                                  |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *OrderedDict* class is now implemented in C, which makes it 4 to 100 times faster.                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | *OrderedDict.items()* , *OrderedDict.keys()* , *OrderedDict.values()* views now support reversed()        |               |
+  | iteration.                                                                                                |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The deque class now defines *index()*, *insert()*, and *copy()*, and supports the + and * operators.      |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Docstrings produced by namedtuple() can now be updated.                                                   |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The UserString class now implements the *__getnewargs__()*, *__rmod__()*, *casefold()*, *format_map()*,   |               |
+  | *isprintable()*, and *maketrans()* methods to match the corresponding methods of str.                     |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `heapq <https://docs.python.org/3/whatsnew/3.5.html#heapq>`_                                                              |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Element comparison in *merge()* can now be customized by passing a key function in a new optional key     |               |
+  | keyword argument, and a new optional *reverse* keyword argument can be used to reverse element comparison |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `io <https://docs.python.org/3/whatsnew/3.5.html#io>`_                                                                    |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new *BufferedIOBase.readinto1()* method, that uses at most one call to the underlying raw stream's      |               |
+  | *RawIOBase.read()* or *RawIOBase.readinto()* methods                                                      |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `json <https://docs.python.org/3/whatsnew/3.5.html#json>`_                                                |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | JSON decoder now raises JSONDecodeError instead of ValueError to provide better context information about |               |
+  | the error.                                                                                                |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `math <https://docs.python.org/3/whatsnew/3.5.html#math>`_                                                                |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Two new constants have been added to the math module: *inf* and *nan*.                                    | Complete      |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new function *isclose()* provides a way to test for approximate equality.                               |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new *gcd()* function has been added. The *fractions.gcd()* function is now deprecated.                  |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `os <https://docs.python.org/3/whatsnew/3.5.html#os>`_                                                                    |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The new *scandir()* function returning an iterator of DirEntry objects has been added.                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *urandom()* function now uses the *getrandom()* syscall on Linux 3.17 or newer, and *getentropy()* on |               |
+  | OpenBSD 5.6 and newer, removing the need to use /dev/urandom and avoiding failures due to potential file  |               |
+  | descriptor exhaustion.                                                                                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | New *get_blocking()* and *set_blocking()* functions allow getting and setting a file descriptor's blocking|               |
+  | mode (O_NONBLOCK.)                                                                                        |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | There is a new *os.path.commonpath()* function returning the longest common sub-path of each passed       |               |
+  | pathname                                                                                                  |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `re <https://docs.python.org/3/whatsnew/3.5.html#re>`_                                                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | References and conditional references to groups with fixed length are now allowed in lookbehind assertions|               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The number of capturing groups in regular expressions is no longer limited to 100.                        |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *sub()* and *subn()* functions now replace unmatched groups with empty strings instead of raising an  |               |
+  | exception.                                                                                                |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *re.error* exceptions have new attributes, msg, pattern, pos, lineno, and colno, that provide better  |               |
+  | context information about the error                                                                       |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `socket <https://docs.python.org/3/whatsnew/3.5.html#socket>`_                                                            |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Functions with timeouts now use a monotonic clock, instead of a system clock.                             |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new *socket.sendfile()* method allows sending a file over a socket by using the high-performance        |               |
+  | *os.sendfile()* function on UNIX, resulting in uploads being from 2 to 3 times faster than when using     |               |
+  | plain *socket.send()*                                                                                     |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *socket.sendall()* method no longer resets the socket timeout every time bytes are received or sent.  |               |
+  | The socket timeout is now the maximum total duration to send all data.                                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The backlog argument of the *socket.listen()* method is now optional. By default it is set to SOMAXCONN or| Complete      |
+  | to 128, whichever is less.                                                                                |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `ssl <https://docs.python.org/3/whatsnew/3.5.html#ssl>`_                                                                  |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Memory BIO Support                                                                                        |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | Application-Layer Protocol Negotiation Support                                                            |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | There is a new *SSLSocket.version()* method to query the actual protocol version in use.                  |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The SSLSocket class now implements a *SSLSocket.sendfile()* method.                                       |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *SSLSocket.send()* method now raises either the *ssl.SSLWantReadError* or *ssl.SSLWantWriteError*     |               |
+  | exception on a non-blocking socket if the operation would block. Previously, it would return 0.           |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *cert_time_to_seconds()* function now interprets the input time as UTC and not as local time, per RFC |               |
+  | 5280. Additionally, the return value is always an int.                                                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | New *SSLObject.shared_ciphers()* and *SSLSocket.shared_ciphers()* methods return the list of ciphers sent |               |
+  | by the client during the handshake.                                                                       |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *SSLSocket.do_handshake()*, *SSLSocket.read()*, *SSLSocket.shutdown()*, and *SSLSocket.write()*       |               |
+  | methods of the SSLSocket class no longer reset the socket timeout every time bytes are received or sent.  |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *match_hostname()* function now supports matching of IP addresses.                                    |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `sys <https://docs.python.org/3/whatsnew/3.5.html#sys>`_                                                                  |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new *set_coroutine_wrapper()* function allows setting a global hook that will be called whenever a      |               |
+  | coroutine object is created by an async def function. A corresponding *get_coroutine_wrapper()* can be    |               |
+  | used to obtain a currently set wrapper.                                                                   |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | A new *is_finalizing()* function can be used to check if the Python interpreter is shutting down.         |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | `time <https://docs.python.org/3/whatsnew/3.5.html#time>`_                                                                |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+  | The *monotonic()* function is now always available                                                        |               |
+  +-----------------------------------------------------------------------------------------------------------+---------------+
+
+.. rubric:: Notes
+
+.. [#fth] The MicroPython parser correct ignores all type hints. However, the ``typing`` module is not built-in.

docs/differences/python_36.rst

@@ -0,0 +1,200 @@
+.. _python_36:
+
+Python 3.6
+==========
+
+Python 3.6 beta 1 was released on 12 Sep 2016, and a summary of the new features can be found here:
+
+.. table::
+  :widths: 30 50 20
+
+  +-----------------------------------------------------------------------------------------------------------+-----------------+
+  | **New Syntax Features**                                                                                   | **Status**      |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 498 <https://www.python.org/dev/peps/pep-0498/>`_ | Literal String Formatting                        | Complete        |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 515 <https://www.python.org/dev/peps/pep-0515/>`_ | Underscores in Numeric Literals                  | Complete        |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 525 <https://www.python.org/dev/peps/pep-0525/>`_ | Asynchronous Generators                          |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ | Syntax for Variable Annotations (provisional)    | Complete        |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 530 <https://www.python.org/dev/peps/pep-0530/>`_ | Asynchronous Comprehensions                      |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | **New Built-in Features**                                                                                                   |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 468 <https://www.python.org/dev/peps/pep-0468/>`_ | Preserving the order of *kwargs* in a function   |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 487 <https://www.python.org/dev/peps/pep-0487/>`_ | Simpler customization of class creation          |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 520 <https://www.python.org/dev/peps/pep-0520/>`_ | Preserving Class Attribute Definition Order      |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | **Standard Library Changes**                                                                                                |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 495 <https://www.python.org/dev/peps/pep-0495/>`_ | Local Time Disambiguation                        |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 506 <https://www.python.org/dev/peps/pep-0506/>`_ | Adding A Secrets Module To The Standard Library  |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 519 <https://www.python.org/dev/peps/pep-0519/>`_ | Adding a file system path protocol               |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | **CPython Internals**                                                                                                       |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 509 <https://www.python.org/dev/peps/pep-0509/>`_ | Add a private version to dict                    | Won't do        |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 523 <https://www.python.org/dev/peps/pep-0523/>`_ | Adding a frame evaluation API to CPython         |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | **Linux/Window Changes**                                                                                                    |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 524 <https://www.python.org/dev/peps/pep-0524/>`_ | Make ``os.urandom()`` blocking on Linux          |                 |
+  |                                                        | (during system startup)                          |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 528 <https://www.python.org/dev/peps/pep-0528/>`_ | Change Windows console encoding to UTF-8         |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+  | `PEP 529 <https://www.python.org/dev/peps/pep-0529/>`_ | Change Windows filesystem encoding to UTF-8      |                 |
+  +--------------------------------------------------------+--------------------------------------------------+-----------------+
+
+Other Language Changes:
+
+.. table::
+  :widths: 90 10
+
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | A *global* or *nonlocal* statement must now textually appear before the first use of the affected name in   |               |
+  | the same scope. Previously this was a SyntaxWarning.                                                        |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | It is now possible to set a special method to None to indicate that the corresponding operation is not      |               |
+  | available. For example, if a class sets *__iter__()* to *None* , the class is not iterable.                 |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Long sequences of repeated traceback lines are now abbreviated as *[Previous line repeated {count} more     |               |
+  | times]*                                                                                                     |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Import now raises the new exception *ModuleNotFoundError* when it cannot find a module. Code that currently |               |
+  | checks for ImportError (in try-except) will still work.                                                     |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Class methods relying on zero-argument *super()* will now work correctly when called from metaclass methods |               |
+  | during class creation.                                                                                      |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+
+Changes to built-in modules:
+
+.. table::
+  :widths: 90 10
+
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `array <https://docs.python.org/3.6/whatsnew/3.6.html#array>`_                                               |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | Exhausted iterators of *array.array* will now stay exhausted even if the iterated array is extended.         |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `binascii <https://docs.python.org/3.6/whatsnew/3.6.html#binascii>`_                                         |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The b2a_base64() function now accepts an optional newline keyword argument to control whether the newline    | Complete       |
+  | character is appended to the return value                                                                    |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `cmath <https://docs.python.org/3.6/whatsnew/3.6.html#cmath>`_                                               |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The new cmath.tau (τ) constant has been added                                                                |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | New constants: *cmath.inf* and *cmath.nan* to match *math.inf* and *math.nan* , and also *cmath.infj* and    |                |
+  | *cmath.nanj* to match the format used by complex repr                                                        |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `collections <https://docs.python.org/3.6/whatsnew/3.6.html#collections>`_                                                    |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The new Collection abstract base class has been added to represent sized iterable container classes          |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The new *Reversible* abstract base class represents iterable classes that also provide the *__reversed__()*  |                |
+  | method.                                                                                                      |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The new *AsyncGenerator* abstract base class represents asynchronous generators.                             |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The *namedtuple()* function now accepts an optional keyword argument module, which, when specified, is used  |                |
+  | for the *__module__* attribute of the returned named tuple class.                                            |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The verbose and rename arguments for *namedtuple()* are now keyword-only.                                    |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | Recursive *collections.deque* instances can now be pickled.                                                  |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `hashlib <https://docs.python.org/3.6/whatsnew/3.6.html#hashlib>`_                                                            |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | BLAKE2 hash functions were added to the module. *blake2b()* and *blake2s()* are always available and support |                |
+  | the full feature set of BLAKE2.                                                                              |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The SHA-3 hash functions *sha3_224()*, *sha3_256()*, *sha3_384()*, *sha3_512()*, and *SHAKE* hash functions  |                |
+  | *shake_128()* and *shake_256()* were added.                                                                  |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The password-based key derivation function *scrypt()* is now available with OpenSSL 1.1.0 and newer.         |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `json <https://docs.python.org/3.6/whatsnew/3.6.html#json>`_                                                                  |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | *json.load()* and *json.loads()* now support binary input. Encoded JSON should be represented using either   |                |
+  | UTF-8, UTF-16, or UTF-32.                                                                                    |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `math <https://docs.python.org/3.6/whatsnew/3.6.html#math>`_                                                                  |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The new math.tau (τ) constant has been added                                                                 | Complete       |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `os <https://docs.python.org/3.6/whatsnew/3.6.html#os>`_                                                                      |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | A new *close()* method allows explicitly closing a *scandir()* iterator. The *scandir()* iterator now        |                |
+  | supports the context manager protocol.                                                                       |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | On Linux, *os.urandom()* now blocks until the system urandom entropy pool is initialized to increase the     |                |
+  | security.                                                                                                    |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The Linux *getrandom()* syscall (get random bytes) is now exposed as the new *os.getrandom()* function.      |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `re <https://docs.python.org/3.6/whatsnew/3.6.html#re>`_                                                                      |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | Added support of modifier spans in regular expressions. Examples: *'(?i:p)ython'* matches 'python' and       |                |
+  | 'Python', but not 'PYTHON'; *'(?i)g(?-i:v)r'* matches *'GvR'* and *'gvr'*, but not *'GVR'*.                  |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | Match object groups can be accessed by *__getitem__*, which is equivalent to *group()*. So *mo['name']* is   |                |
+  | now equivalent to *mo.group('name')*.                                                                        |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | Match objects now support index-like objects as group indices.                                               |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `socket <https://docs.python.org/3.6/whatsnew/3.6.html#socket>`_                                                              |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The *ioctl()* function now supports the *SIO_LOOPBACK_FAST_PATH* control code.                               |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The *getsockopt()* constants *SO_DOMAIN* , *SO_PROTOCOL*, *SO_PEERSEC* , and *SO_PASSSEC* are now supported. |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The *setsockopt()* now supports the *setsockopt(level, optname, None, optlen: int)* form.                    |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The socket module now supports the address family *AF_ALG* to interface with Linux Kernel crypto API.        |                |
+  | *ALG_*, *SOL_ALG* and *sendmsg_afalg()* were added.                                                          |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | New Linux constants *TCP_USER_TIMEOUT* and *TCP_CONGESTION* were added.                                      |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `ssl <https://docs.python.org/3.6/whatsnew/3.6.html#ssl>`_                                                                    |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | ssl supports OpenSSL 1.1.0. The minimum recommend version is 1.0.2.                                          |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | 3DES has been removed from the default cipher suites and ChaCha20 Poly1305 cipher suites have been added.    |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | *SSLContext* has better default configuration for options and ciphers.                                       |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | SSL session can be copied from one client-side connection to another with the new *SSLSession* class. TLS    |                |
+  | session resumption can speed up the initial handshake, reduce latency and improve performance.               |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The new *get_ciphers()* method can be used to get a list of enabled ciphers in order of cipher priority.     |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | All constants and flags have been converted to *IntEnum* and *IntFlags*.                                     |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | Server and client-side specific TLS protocols for *SSLContext* were added.                                   |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | Added *SSLContext.post_handshake_auth* to enable and *ssl.SSLSocket.verify_client_post_handshake()* to       |                |
+  | initiate TLS 1.3 post-handshake authentication.                                                              |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `struct <https://docs.python.org/3.6/whatsnew/3.6.html#struct>`_                                             |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | now supports IEEE 754 half-precision floats via the 'e' format specifier.                                    |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `sys <https://docs.python.org/3.6/whatsnew/3.6.html#sys>`_                                                   |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The new *getfilesystemencodeerrors()* function returns the name of the error mode used to convert between    |                |
+  | Unicode filenames and bytes filenames.                                                                       |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | `zlib <https://docs.python.org/3.6/whatsnew/3.6.html#zlib>`_                                                 |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+
+  | The *compress()* and *decompress()* functions now accept keyword arguments                                   |                |
+  +--------------------------------------------------------------------------------------------------------------+----------------+

docs/differences/python_37.rst

@@ -0,0 +1,108 @@
+.. _python_37:
+
+Python 3.7
+==========
+
+New Features:
+
+.. table::
+  :widths: 20 60 20
+
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | **Feature**                                                                                               | **Status**                           |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 538 <https://www.python.org/dev/peps/pep-0538/>`_ | Coercing the legacy C locale to a UTF-8 based    |                                      |
+  |                                                        | locale                                           |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 539 <https://www.python.org/dev/peps/pep-0539/>`_ | A New C-API for Thread-Local Storage in CPython  |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 540 <https://www.python.org/dev/peps/pep-0540/>`_ | UTF-8 mode                                       |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 552 <https://www.python.org/dev/peps/pep-0552/>`_ | Deterministic pyc                                |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 553 <https://www.python.org/dev/peps/pep-0553/>`_ | Built-in ``breakpoint()``                        |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 557 <https://www.python.org/dev/peps/pep-0557/>`_ | Data Classes                                     |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 560 <https://www.python.org/dev/peps/pep-0560/>`_ | Core support for typing module and generic types |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 562 <https://www.python.org/dev/peps/pep-0562/>`_ | Module ``__getattr__`` and ``__dir__``           | Partial                              |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 563 <https://www.python.org/dev/peps/pep-0563/>`_ | Postponed Evaluation of Annotations              |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 564 <https://www.python.org/dev/peps/pep-0564/>`_ | Time functions with nanosecond resolution        | Partial [#ftimenanosec]_             |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 565 <https://www.python.org/dev/peps/pep-0565/>`_ | Show DeprecationWarning in ``__main__``          |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+  | `PEP 567 <https://www.python.org/dev/peps/pep-0567/>`_ | Context Variables                                |                                      |
+  +--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
+
+Other Language Changes:
+
+.. table::
+  :widths: 90 10
+
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``async`` and ``await`` are now reserved keywords                                                               | Complete       |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``dict`` objects must preserve insertion-order                                                                  |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | More than 255 arguments can now be passed to a function; a function can now have more than 255 parameters       |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``bytes.fromhex()`` and ``bytearray.fromhex()`` now ignore all ASCII whitespace, not only spaces                |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``str``, ``bytes``, and ``bytearray`` gained support for the new ``isascii()`` method, which can be used to     |                |
+  | test if a string or bytes contain only the ASCII characters                                                     |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``ImportError`` now displays module name and module ``__file__`` path when ``from ... import ...`` fails        |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | Circular imports involving absolute imports with binding a submodule to a name are now supported                |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | ``object.__format__(x, '')`` is now equivalent to ``str(x)`` rather than ``format(str(self), '')``              |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | In order to better support dynamic creation of stack traces, ``types.TracebackType`` can now be                 |                |
+  | instantiated from Python code, and the ``tb_next`` attribute on tracebacks is now writable                      |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | When using the ``-m`` switch, ``sys.path[0]`` is now eagerly expanded to the full starting directory path,      |                |
+  | rather than being left as the empty directory (which allows imports from the current working directory          |                |
+  | at the time when an import occurs)                                                                              |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+  | The new ``-X importtime`` option or the ``PYTHONPROFILEIMPORTTIME`` environment variable can be used to         |                |
+  | show the timing of each module import                                                                           |                |
+  +-----------------------------------------------------------------------------------------------------------------+----------------+
+
+Changes to built-in modules:
+
+.. table::
+  :widths: 90 10
+
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | `asyncio <https://docs.python.org/3/whatsnew/3.7.html#asyncio>`_                                           |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | Too many to list                                                                                           |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | `gc <https://docs.python.org/3/whatsnew/3.7.html#gc>`_                                                     |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | New features include *gc.freeze()*, *gc.unfreeze()*, *gc-get_freeze_count*                                 |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | `math <https://docs.python.org/3/whatsnew/3.7.html#math>`_                                                 |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | math.remainder() added to implement IEEE 754-style remainder                                               |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | `re <https://docs.python.org/3/whatsnew/3.7.html#re>`_                                                     |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | A number of tidy up features including better support for splitting on empty strings and copy support for  |                |
+  | compiled expressions and match objects                                                                     |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | `sys <https://docs.python.org/3/whatsnew/3.7.html#sys>`_                                                   |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | sys.breakpointhook() added. sys.get(/set)_coroutine_origin_tracking_depth() added                          |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | `time <https://docs.python.org/3/whatsnew/3.7.html#time>`_                                                 |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+  | Mostly updates to support nanosecond resolution in PEP564, see above                                       |                |
+  +------------------------------------------------------------------------------------------------------------+----------------+
+
+.. rubric:: Notes
+
+.. [#ftimenanosec] Only :func:`time.time_ns` is implemented. 

docs/differences/python_38.rst

@@ -0,0 +1,127 @@
+.. _python_38:
+
+Python 3.8
+==========
+
+Python 3.8.0 (final) was released on the 14 October 2019. The Features for 3.8
+are defined in `PEP 569 <https://www.python.org/dev/peps/pep-0569/#id9>`_ and
+a detailed description of the changes can be found in `What's New in Python
+3.8. <https://docs.python.org/3/whatsnew/3.8.html>`_
+
+.. table::
+  :widths: 20 60 20
+
+  +--------------------------------------------------------+---------------------------------------------------+---------------+
+  | **Features**                                                                                               | **Status**    |
+  +--------------------------------------------------------+---------------------------------------------------+---------------+
+  | `PEP 570 <https://www.python.org/dev/peps/pep-0570/>`_ | Positional-only arguments                         |               |
+  +--------------------------------------------------------+---------------------------------------------------+---------------+
+  | `PEP 572 <https://www.python.org/dev/peps/pep-0572/>`_ | Assignment Expressions                            | Complete      |
+  +--------------------------------------------------------+---------------------------------------------------+---------------+
+  | `PEP 574 <https://www.python.org/dev/peps/pep-0574/>`_ | Pickle protocol 5 with out-of-band data           |               |
+  +--------------------------------------------------------+---------------------------------------------------+---------------+
+  | `PEP 578 <https://www.python.org/dev/peps/pep-0578/>`_ | Runtime audit hooks                               |               |
+  +--------------------------------------------------------+---------------------------------------------------+---------------+
+  | `PEP 587 <https://www.python.org/dev/peps/pep-0587/>`_ | Python Initialization Configuration               |               |
+  +--------------------------------------------------------+---------------------------------------------------+---------------+
+  | `PEP 590 <https://www.python.org/dev/peps/pep-0590/>`_ | Vectorcall: a fast calling protocol for CPython   |               |
+  +--------------------------------------------------------+---------------------------------------------------+---------------+
+  | **Miscellaneous**                                                                                                          |
+  +------------------------------------------------------------------------------------------------------------+---------------+
+  |  f-strings support = for self-documenting expressions and debugging                                        | Complete      |
+  +------------------------------------------------------------------------------------------------------------+---------------+
+
+Other Language Changes:
+
+.. table::
+  :widths: 90 10
+
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | A *continue* statement was illegal in the *finally* clause due to a problem with the implementation. In    | Complete    |
+  | Python 3.8 this restriction was lifted                                                                     |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | The *bool*, *int* , and *fractions.Fraction* types now have an *as_integer_ratio()* method like that found |             |
+  | in *float* and *decimal.Decimal*                                                                           |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Constructors of *int*, *float* and *complex* will now use the *__index__()* special method, if available   |             |
+  | and the corresponding method *__int__()*, *__float__()* or *__complex__()* is not available                |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Added support of *\N{name}* escapes in regular expressions                                                 |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Dict and dictviews are now iterable in reversed insertion order using *reversed()*                         |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | The syntax allowed for keyword names in function calls was further restricted. In particular,              |             |
+  | f((keyword)=arg) is no longer allowed                                                                      |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Generalized iterable unpacking in yield and return statements no longer requires enclosing parentheses     |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | When a comma is missed in code such as [(10, 20) (30, 40)], the compiler displays a SyntaxWarning with a   |             |
+  | helpful suggestion                                                                                         |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Arithmetic operations between subclasses of *datetime.date* or *datetime.datetime* and *datetime.timedelta*|             |
+  | objects now return an instance of the subclass, rather than the base class                                 |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | When the Python interpreter is interrupted by *Ctrl-C (SIGINT)* and the resulting *KeyboardInterrupt*      |             |
+  | exception is not caught, the Python process now exits via a SIGINT signal or with the correct exit code    |             |
+  | such that the calling process can detect that it died due to  a *Ctrl-C*                                   |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Some advanced styles of programming require updating the *types.CodeType* object for an existing function  |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | For integers, the three-argument form of the pow() function now permits the exponent to be negative in the |             |
+  | case where the base is relatively prime to the modulus                                                     |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Dict comprehensions have been synced-up with dict literals so that the key is computed first and the value |             |
+  | second                                                                                                     |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | The *object.__reduce__()* method can now return a tuple from two to six elements long                      |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+
+Changes to built-in modules:
+
+.. table::
+  :widths: 90 10
+
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | `asyncio <https://docs.python.org/3/whatsnew/3.8.html#asyncio>`_                                                         |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | *asyncio.run()* has graduated from the provisional to stable API                                           | Complete    |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Running *python -m asyncio* launches a natively async REPL                                                 |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | The exception *asyncio.CancelledError* now inherits from *BaseException* rather than *Exception* and no    | Complete    |
+  | longer inherits from *concurrent.futures.CancelledError*                                                   |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Added *asyncio.Task.get_coro()* for getting the wrapped coroutine within an *asyncio.Task*                 |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Asyncio tasks can now be named, either by passing the name keyword argument to *asyncio.create_task()* or  |             |
+  | the *create_task()* event loop method, or by calling the *set_name()* method on the task object            |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Added support for Happy Eyeballs to *asyncio.loop.create_connection()*. To specify the behavior, two new   |             |
+  | parameters have been added: *happy_eyeballs_delay* and interleave.                                         |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | `gc <https://docs.python.org/3/whatsnew/3.8.html#gc>`_                                                                   |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | *get_objects()* can now receive an optional generation parameter indicating a generation to get objects    |             |
+  | from. (Note, though, that while *gc* is a built-in, *get_objects()* is not implemented for MicroPython)    |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | `math <https://docs.python.org/3/whatsnew/3.8.html#math>`_                                                               |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Added new function *math.dist()* for computing Euclidean distance between two points                       |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Expanded the *math.hypot()* function to handle multiple dimensions                                         |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Added new function, *math.prod()*, as analogous function to *sum()* that returns the product of a "start"  |             |
+  | value (default: 1) times an iterable of numbers                                                            |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Added two new combinatoric functions *math.perm()* and *math.comb()*                                       |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Added a new function *math.isqrt()* for computing accurate integer square roots without conversion to      |             |
+  | floating point                                                                                             |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | The function *math.factorial()* no longer accepts arguments that are not int-like                          | Complete    |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | `sys <https://docs.python.org/3/whatsnew/3.8.html#sys>`_                                                                 |
+  +------------------------------------------------------------------------------------------------------------+-------------+
+  | Add new *sys.unraisablehook()* function which can be overridden to control how "unraisable exceptions"     |             |
+  | are handled                                                                                                |             |
+  +------------------------------------------------------------------------------------------------------------+-------------+

docs/differences/python_39.rst

@@ -0,0 +1,134 @@
+.. _python_39:
+
+Python 3.9
+==========
+
+Python 3.9.0 (final) was released on the 5th October 2020. The Features for 3.9 are
+defined in `PEP 596 <https://www.python.org/dev/peps/pep-0596/#features-for-3-9>`_
+and a detailed description of the changes can be found in
+`What's New in Python 3.9 <https://docs.python.org/3/whatsnew/3.9.html>`_
+
+.. table::
+  :widths: 20 60 20
+
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | **Features**                                           |                                                    | **Status**           |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 573 <https://www.python.org/dev/peps/pep-0573/>`_ | Fast access to module state from methods of C      | Not relevant         |
+  |                                                        | extension types                                    |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 584 <https://www.python.org/dev/peps/pep-0584/>`_ | Union operators added to dict                      | Complete [#pep584]_  |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 585 <https://www.python.org/dev/peps/pep-0584/>`_ | Type hinting generics in standard collections      |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 593 <https://www.python.org/dev/peps/pep-0593/>`_ | Flexible function and variable annotations         |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 602 <https://www.python.org/dev/peps/pep-0602/>`_ | CPython adopts an annual release cycle. Instead of | Not relevant         |
+  |                                                        | annual, aiming for two month release cycle         |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 614 <https://www.python.org/dev/peps/pep-0614/>`_ | Relaxed grammar restrictions on decorators         |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 615 <https://www.python.org/dev/peps/pep-0615/>`_ | The IANA Time Zone Database is now present in the  |                      |
+  |                                                        | standard library in the zoneinfo module            |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 616 <https://www.python.org/dev/peps/pep-0616/>`_ | String methods to remove prefixes and suffixes     |                      |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+  | `PEP 617 <https://www.python.org/dev/peps/pep-0617/>`_ | CPython now uses a new parser based on PEG         | Not relevant         |
+  +--------------------------------------------------------+----------------------------------------------------+----------------------+
+
+Other Language Changes:
+
+.. table::
+  :widths: 90 10
+
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | *__import__()* now raises *ImportError* instead of *ValueError*                                             | Complete      |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Python now gets the absolute path of the script filename specified on the command line (ex: *python3*       |               |
+  | *script.py*): the *__file__* attribute of the *__main__* module became an absolute path, rather than a      |               |
+  | relative path                                                                                               |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | By default, for best performance, the errors argument is only checked at the first encoding/decoding error  |               |
+  | and the encoding argument is sometimes ignored for empty strings                                            |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | *"".replace("", s, n)* now returns *s* instead of an empty string for all non-zero n. It is now consistent  |               |
+  | with *"".replace("", s)*                                                                                    |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Any valid expression can now be used as a decorator. Previously, the grammar was much more restrictive      |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Parallel running of *aclose()* / *asend()* / *athrow()* is now prohibited, and *ag_running* now reflects    |               |
+  | the actual running status of the async generator                                                            |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Unexpected errors in calling the *__iter__* method are no longer masked by TypeError in the in operator and |               |
+  | functions contains(), indexOf() and countOf() of the operator module                                        |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+  | Unparenthesized lambda expressions can no longer be the expression part in an if clause in comprehensions   |               |
+  | and generator expressions                                                                                   |               |
+  +-------------------------------------------------------------------------------------------------------------+---------------+
+
+Changes to built-in modules:
+
+.. table::
+  :widths: 90 10
+
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `asyncio <https://docs.python.org/3/whatsnew/3.9.html#asyncio>`_                                                              |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Due to significant security concerns, the reuse_address parameter of *asyncio.loop.create_datagram_endpoint()*|               |
+  | is no longer supported                                                                                        |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Added a new coroutine *shutdown_default_executor()* that schedules a shutdown for the default executor that   |               |
+  | waits on the *ThreadPoolExecutor* to finish closing. Also, *asyncio.run()* has been updated to use the new    |               |
+  | coroutine.                                                                                                    |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Added *asyncio.PidfdChildWatcher*, a Linux-specific child watcher implementation that polls process file      |               |
+  | descriptors                                                                                                   |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | added a new *coroutine asyncio.to_thread()*                                                                   |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | When cancelling the task due to a timeout, *asyncio.wait_for()* will now wait until the cancellation is       |               |
+  | complete also in the case when timeout is <= 0, like it does with positive timeouts                           |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | *asyncio* now raises *TyperError* when calling incompatible methods with an *ssl.SSLSocket* socket            |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `gc <https://docs.python.org/3/whatsnew/3.9.html#gc>`_                                                                        |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Garbage collection does not block on resurrected objects                                                      |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Added a new function *gc.is_finalized()* to check if an object has been finalized by the garbage collector    |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `math <https://docs.python.org/3/whatsnew/3.9.html#math>`_                                                                    |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Expanded the *math.gcd()* function to handle multiple arguments. Formerly, it only supported two arguments    |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Added *math.lcm()*: return the least common multiple of specified arguments                                   |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Added *math.nextafter()*: return the next floating-point value after x towards y                              |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Added *math.ulp()*: return the value of the least significant bit of a float                                  |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `os <https://docs.python.org/3/whatsnew/3.9.html#os>`_                                                                        |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Exposed the Linux-specific *os.pidfd_open()* and *os.P_PIDFD*                                                 |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The *os.unsetenv()* function is now also available on Windows                                                 | Complete      |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | The *os.putenv()* and *os.unsetenv()* functions are now always available                                      | Complete      |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  |  Added *os.waitstatus_to_exitcode()* function: convert a wait status to an exit code                          |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `random <https://docs.python.org/3/whatsnew/3.9.html#random>`_                                                                |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Added a new *random.Random.randbytes* method: generate random bytes                                           |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | `sys <https://docs.python.org/3/whatsnew/3.9.html#sys>`_                                                                      |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Added a new *sys.platlibdir* attribute: name of the platform-specific library directory                       |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+  | Previously, *sys.stderr* was block-buffered when non-interactive. Now stderr defaults to always being         |               |
+  | line-buffered                                                                                                 |               |
+  +---------------------------------------------------------------------------------------------------------------+---------------+
+
+.. rubric:: Notes
+
+.. [#pep584] PEP 584 ``dict`` union operator is only available on MicroPython builds with ``MICROPY_CPYTHON_COMPAT`` enabled.

docs/esp32/quickref.rst

@@ -16,7 +16,7 @@ working with this board it may be useful to get an overview of the microcontroll
    :maxdepth: 1
 
    general.rst
-   tutorial/intro.rst
+   tutorial/index.rst
 
 Installing MicroPython
 ----------------------
@@ -68,6 +68,9 @@ by reading the temperature sensor immediately after waking up from sleep.
 Networking
 ----------
 
+WLAN
+^^^^
+
 The :mod:`network` module::
 
     import network
@@ -76,12 +79,12 @@ The :mod:`network` module::
     wlan.active(True)       # activate the interface
     wlan.scan()             # scan for access points
     wlan.isconnected()      # check if the station is connected to an AP
-    wlan.connect('essid', 'password') # connect to an AP
+    wlan.connect('ssid', 'key') # connect to an AP
     wlan.config('mac')      # get the interface's MAC address
     wlan.ifconfig()         # get the interface's IP/netmask/gw/DNS addresses
 
     ap = network.WLAN(network.AP_IF) # create access-point interface
-    ap.config(essid='ESP-AP') # set the ESSID of the access point
+    ap.config(ssid='ESP-AP') # set the SSID of the access point
     ap.config(max_clients=10) # set how many clients can connect to the network
     ap.active(True)         # activate the interface
 
@@ -93,12 +96,12 @@ A useful function for connecting to your local WiFi network is::
         wlan.active(True)
         if not wlan.isconnected():
             print('connecting to network...')
-            wlan.connect('essid', 'password')
+            wlan.connect('ssid', 'key')
             while not wlan.isconnected():
                 pass
         print('network config:', wlan.ifconfig())
 
-Once the network is established the :mod:`socket <usocket>` module can be used
+Once the network is established the :mod:`socket <socket>` module can be used
 to create and use TCP/UDP sockets as usual, and the ``urequests`` module for
 convenient HTTP requests.
 
@@ -110,10 +113,71 @@ calling ``wlan.config(reconnects=n)``, where n are the number of desired reconne
 attempts (0 means it won't retry, -1 will restore the default behaviour of trying
 to reconnect forever).
 
+LAN
+^^^
+
+To use the wired interfaces one has to specify the pins and mode ::
+
+    import network
+
+    lan = network.LAN(mdc=PIN_MDC, ...)   # Set the pin and mode configuration
+    lan.active(True)                      # activate the interface
+    lan.ifconfig()                        # get the interface's IP/netmask/gw/DNS addresses
+
+
+The keyword arguments for the constructor defining the PHY type and interface are:
+
+- mdc=pin-object    # set the mdc and mdio pins.
+- mdio=pin-object
+- power=pin-object  # set the pin which switches the power of the PHY device.
+- phy_type=<type>   # Select the PHY device type. Supported devices are PHY_LAN8710,
+  PHY_LAN8720, PH_IP101, PHY_RTL8201, PHY_DP83848 and PHY_KSZ8041
+- phy_addr=number   # The address number of the PHY device.
+- ref_clk_mode=mode # Defines, whether the ref_clk at the ESP32 is an input
+  or output. Suitable values are Pin.IN and Pin.OUT.
+- ref_clk=pin-object  # defines the Pin used for ref_clk.
+
+The options ref_clk_mode and ref_clk require at least esp-idf version 4.4. For
+earlier esp-idf versions, these parameters must be defined by kconfig board options.
+
+These are working configurations for LAN interfaces of popular boards::
+
+    # Olimex ESP32-GATEWAY: power controlled by Pin(5)
+    # Olimex ESP32 PoE and ESP32-PoE ISO: power controlled by Pin(12)
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5),
+                      phy_type=network.PHY_LAN8720, phy_addr=0)
+
+    # or with dynamic ref_clk pin configuration
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5), 
+                      phy_type=network.PHY_LAN8720, phy_addr=0,
+                      ref_clk=machine.Pin(17), ref_clk_mode=machine.Pin.OUT)
+
+    # Wireless-Tag's WT32-ETH01
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18),
+                      phy_type=network.PHY_LAN8720, phy_addr=1, power=None)
+
+    # Espressif ESP32-Ethernet-Kit_A_V1.2
+
+    lan = network.LAN(id=0, mdc=Pin(23), mdio=Pin(18), power=Pin(5),
+                      phy_type=network.PHY_IP101, phy_addr=1)
+
+A suitable definition of the PHY interface in a sdkconfig.board file is::
+
+    CONFIG_ETH_PHY_INTERFACE_RMII=y
+    CONFIG_ETH_RMII_CLK_OUTPUT=y
+    CONFIG_ETH_RMII_CLK_OUT_GPIO=17
+    CONFIG_LWIP_LOCAL_HOSTNAME="ESP32_POE"
+
+The value assigned to CONFIG_ETH_RMII_CLK_OUT_GPIO may vary depending on the
+board's wiring.
+
 Delay and timing
 ----------------
 
-Use the :mod:`time <utime>` module::
+Use the :mod:`time <time>` module::
 
     import time
 
@@ -160,6 +224,7 @@ Use the :ref:`machine.Pin <machine.Pin>` class::
 
     p4 = Pin(4, Pin.IN, Pin.PULL_UP) # enable internal pull-up resistor
     p5 = Pin(5, Pin.OUT, value=1) # set pin high on creation
+    p6 = Pin(6, Pin.OUT, drive=Pin.DRIVE_3) # set maximum drive strength
 
 Available Pins are from the following ranges (inclusive): 0-19, 21-23, 25-27, 32-39.
 These correspond to the actual GPIO pin numbers of ESP32 chip.  Note that many
@@ -167,6 +232,23 @@ end-user boards use their own adhoc pin numbering (marked e.g. D0, D1, ...).
 For mapping between board logical pins and physical chip pins consult your board
 documentation.
 
+Four drive strengths are supported, using the ``drive`` keyword argument to the
+``Pin()`` constructor or ``Pin.init()`` method, with different corresponding
+safe maximum source/sink currents and approximate internal driver resistances:
+
+ - ``Pin.DRIVE_0``: 5mA / 130 ohm
+ - ``Pin.DRIVE_1``: 10mA / 60 ohm
+ - ``Pin.DRIVE_2``: 20mA / 30 ohm (default strength if not configured)
+ - ``Pin.DRIVE_3``: 40mA / 15 ohm
+
+The ``hold=`` keyword argument to ``Pin()`` and ``Pin.init()`` will enable the
+ESP32 "pad hold" feature. When set to ``True``, the pin configuration
+(direction, pull resistors and output value) will be held and any further
+changes (including changing the output level) will not be applied. Setting
+``hold=False`` will immediately apply any outstanding pin configuration changes
+and release the pin. Using ``hold=True`` while a pin is already held will apply
+any configuration changes and then immediately reapply the hold.
+
 Notes:
 
 * Pins 1 and 3 are REPL UART TX and RX respectively
@@ -176,8 +258,7 @@ Notes:
 
 * Pins 34-39 are input only, and also do not have internal pull-up resistors
 
-* The pull value of some pins can be set to ``Pin.PULL_HOLD`` to reduce power
-  consumption during deepsleep.
+* See :ref:`Deep_sleep_Mode` for a discussion of pin behaviour during sleep
 
 There's a higher-level abstraction :ref:`machine.Signal <machine.Signal>`
 which can be used to invert a pin. Useful for illuminating active-low LEDs
@@ -199,9 +280,10 @@ They each have default GPIO assigned to them, however depending on your
 ESP32 variant and board, these pins may conflict with embedded flash,
 onboard PSRAM or peripherals.
 
-Any GPIO can be used for hardware UARTs using the GPIO matrix, so to avoid
-conflicts simply provide ``tx`` and ``rx`` pins when constructing. The default
-pins listed below.
+Any GPIO can be used for hardware UARTs using the GPIO matrix, except for
+input-only pins 34-39 that can be used as ``rx``. To avoid conflicts simply
+provide ``tx`` and ``rx`` pins when constructing. The default pins listed
+below.
 
 =====  =====  =====  =====
 \      UART0  UART1  UART2
@@ -218,72 +300,145 @@ range from 1Hz to 40MHz but there is a tradeoff; as the base frequency
 *increases* the duty resolution *decreases*. See
 `LED Control <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/ledc.html>`_
 for more details.
-Currently the duty cycle has to be in the range of 0-1023.
 
-Use the ``machine.PWM`` class::
+Use the :ref:`machine.PWM <machine.PWM>` class::
 
     from machine import Pin, PWM
 
-    pwm0 = PWM(Pin(0))      # create PWM object from a pin
-    pwm0.freq()             # get current frequency
-    pwm0.freq(1000)         # set frequency
-    pwm0.duty()             # get current duty cycle
-    pwm0.duty(200)          # set duty cycle
-    pwm0.deinit()           # turn off PWM on the pin
+    pwm0 = PWM(Pin(0))         # create PWM object from a pin
+    freq = pwm0.freq()         # get current frequency (default 5kHz)
+    pwm0.freq(1000)            # set PWM frequency from 1Hz to 40MHz
 
-    pwm2 = PWM(Pin(2), freq=20000, duty=512) # create and configure in one go
+    duty = pwm0.duty()         # get current duty cycle, range 0-1023 (default 512, 50%)
+    pwm0.duty(256)             # set duty cycle from 0 to 1023 as a ratio duty/1023, (now 25%)
+
+    duty_u16 = pwm0.duty_u16() # get current duty cycle, range 0-65535
+    pwm0.duty_u16(2**16*3//4)  # set duty cycle from 0 to 65535 as a ratio duty_u16/65535, (now 75%)
+
+    duty_ns = pwm0.duty_ns()   # get current pulse width in ns
+    pwm0.duty_ns(250_000)      # set pulse width in nanoseconds from 0 to 1_000_000_000/freq, (now 25%)
+
+    pwm0.deinit()              # turn off PWM on the pin
+
+    pwm2 = PWM(Pin(2), freq=20000, duty=512)  # create and configure in one go
+    print(pwm2)                               # view PWM settings
+
+ESP chips have different hardware peripherals:
+
+=====================================================  ========  ========  ========
+Hardware specification                                    ESP32  ESP32-S2  ESP32-C3
+-----------------------------------------------------  --------  --------  --------
+Number of groups (speed modes)                                2         1         1
+Number of timers per group                                    4         4         4
+Number of channels per group                                  8         8         6
+-----------------------------------------------------  --------  --------  --------
+Different PWM frequencies (groups * timers)                   8         4         4
+Total PWM channels (Pins, duties) (groups * channels)        16         8         6
+=====================================================  ========  ========  ========
+
+A maximum number of PWM channels (Pins) are available on the ESP32 - 16 channels,
+but only 8 different PWM frequencies are available, the remaining 8 channels must
+have the same frequency.  On the other hand, 16 independent PWM duty cycles are
+possible at the same frequency.
+
+See more examples in the :ref:`esp32_pwm` tutorial.
 
 ADC (analog to digital conversion)
 ----------------------------------
 
-On the ESP32 ADC functionality is available on Pins 32-39. Note that, when
-using the default configuration, input voltages on the ADC pin must be between
-0.0v and 1.0v (anything above 1.0v will just read as 4095).  Attenuation must
-be applied in order to increase this usable voltage range.
+On the ESP32, ADC functionality is available on pins 32-39 (ADC block 1) and
+pins 0, 2, 4, 12-15 and 25-27 (ADC block 2).
 
 Use the :ref:`machine.ADC <machine.ADC>` class::
 
     from machine import ADC
 
-    adc = ADC(Pin(32))          # create ADC object on ADC pin
-    adc.read()                  # read value, 0-4095 across voltage range 0.0v - 1.0v
+    adc = ADC(pin)        # create an ADC object acting on a pin
+    val = adc.read_u16()  # read a raw analog value in the range 0-65535
+    val = adc.read_uv()   # read an analog value in microvolts
 
-    adc.atten(ADC.ATTN_11DB)    # set 11dB input attenuation (voltage range roughly 0.0v - 3.6v)
-    adc.width(ADC.WIDTH_9BIT)   # set 9 bit return values (returned range 0-511)
-    adc.read()                  # read value using the newly configured attenuation and width
+ADC block 2 is also used by WiFi and so attempting to read analog values from
+block 2 pins when WiFi is active will raise an exception.
 
-ESP32 specific ADC class method reference:
+The internal ADC reference voltage is typically 1.1V, but varies slightly from
+package to package. The ADC is less linear close to the reference voltage
+(particularly at higher attenuations) and has a minimum measurement voltage
+around 100mV, voltages at or below this will read as 0. To read voltages
+accurately, it is recommended to use the ``read_uv()`` method (see below).
 
-.. method:: ADC.atten(attenuation)
+ESP32-specific ADC class method reference:
 
-    This method allows for the setting of the amount of attenuation on the
-    input of the ADC. This allows for a wider possible input voltage range,
-    at the cost of accuracy (the same number of bits now represents a wider
-    range). The possible attenuation options are:
+.. class:: ADC(pin, *, atten)
 
-      - ``ADC.ATTN_0DB``: 0dB attenuation, gives a maximum input voltage
-        of 1.00v - this is the default configuration
-      - ``ADC.ATTN_2_5DB``: 2.5dB attenuation, gives a maximum input voltage
-        of approximately 1.34v
-      - ``ADC.ATTN_6DB``: 6dB attenuation, gives a maximum input voltage
-        of approximately 2.00v
-      - ``ADC.ATTN_11DB``: 11dB attenuation, gives a maximum input voltage
-        of approximately 3.6v
+    Return the ADC object for the specified pin. ESP32 does not support
+    different timings for ADC sampling and so the ``sample_ns`` keyword argument
+    is not supported.
+
+    To read voltages above the reference voltage, apply input attenuation with
+    the ``atten`` keyword argument. Valid values (and approximate linear
+    measurement ranges) are:
+
+      - ``ADC.ATTN_0DB``: No attenuation (100mV - 950mV)
+      - ``ADC.ATTN_2_5DB``: 2.5dB attenuation (100mV - 1250mV)
+      - ``ADC.ATTN_6DB``: 6dB attenuation (150mV - 1750mV)
+      - ``ADC.ATTN_11DB``: 11dB attenuation (150mV - 2450mV)
 
 .. Warning::
-   Despite 11dB attenuation allowing for up to a 3.6v range, note that the
-   absolute maximum voltage rating for the input pins is 3.6v, and so going
-   near this boundary may be damaging to the IC!
+   Note that the absolute maximum voltage rating for input pins is 3.6V. Going
+   near to this boundary risks damage to the IC!
 
-.. method:: ADC.width(width)
+.. method:: ADC.read_uv()
 
-    This method allows for the setting of the number of bits to be utilised
-    and returned during ADC reads. Possible width options are:
+    This method uses the known characteristics of the ADC and per-package eFuse
+    values - set during manufacture - to return a calibrated input voltage
+    (before attenuation) in microvolts. The returned value has only millivolt
+    resolution (i.e., will always be a multiple of 1000 microvolts).
+
+    The calibration is only valid across the linear range of the ADC. In
+    particular, an input tied to ground will read as a value above 0 microvolts.
+    Within the linear range, however, more accurate and consistent results will
+    be obtained than using `read_u16()` and scaling the result with a constant.
+
+The ESP32 port also supports the :ref:`machine.ADC <machine.ADCBlock>` API:
+
+.. class:: ADCBlock(id, *, bits)
+
+    Return the ADC block object with the given ``id`` (1 or 2) and initialize
+    it to the specified resolution (9 to 12-bits depending on the ESP32 series)
+    or the highest supported resolution if not specified.
+
+.. method:: ADCBlock.connect(pin)
+            ADCBlock.connect(channel)
+            ADCBlock.connect(channel, pin)
+
+    Return the ``ADC`` object for the specified ADC pin or channel number.
+    Arbitrary connection of ADC channels to GPIO is not supported and so
+    specifying a pin that is not connected to this block, or specifying a
+    mismatched channel and pin, will raise an exception.
+
+Legacy methods:
+
+.. method:: ADC.read()
+
+    This method returns the raw ADC value ranged according to the resolution of
+    the block, e.g., 0-4095 for 12-bit resolution.
+
+.. method:: ADC.atten(atten)
+
+    Equivalent to ``ADC.init(atten=atten)``.
+
+.. method:: ADC.width(bits)
+
+    Equivalent to ``ADC.block().init(bits=bits)``.
+
+For compatibility, the ``ADC`` object also provides constants matching the
+supported ADC resolutions:
+
+  - ``ADC.WIDTH_9BIT`` = 9
+  - ``ADC.WIDTH_10BIT`` = 10
+  - ``ADC.WIDTH_11BIT`` = 11
+  - ``ADC.WIDTH_12BIT`` = 12
 
-      - ``ADC.WIDTH_9BIT``: 9 bit data
-      - ``ADC.WIDTH_10BIT``: 10 bit data
-      - ``ADC.WIDTH_11BIT``: 11 bit data
-      - ``ADC.WIDTH_12BIT``: 12 bit data - this is the default configuration
 
 Software SPI bus
 ----------------
@@ -361,7 +516,7 @@ accessed via the :ref:`machine.SoftI2C <machine.SoftI2C>` class::
     i2c.writeto(0x3a, '12') # write '12' to device with address 0x3a
 
     buf = bytearray(10)     # create a buffer with 10 bytes
-    i2c.writeto(0x3a, buf)  # write the given buffer to the slave
+    i2c.writeto(0x3a, buf)  # write the given buffer to the peripheral
 
 Hardware I2C bus
 ----------------
@@ -385,6 +540,24 @@ has the same methods as software I2C above::
     i2c = I2C(0)
     i2c = I2C(1, scl=Pin(5), sda=Pin(4), freq=400000)
 
+I2S bus
+-------
+
+See :ref:`machine.I2S <machine.I2S>`. ::
+
+    from machine import I2S, Pin
+
+    i2s = I2S(0, sck=Pin(13), ws=Pin(14), sd=Pin(34), mode=I2S.TX, bits=16, format=I2S.STEREO, rate=44100, ibuf=40000) # create I2S object
+    i2s.write(buf)             # write buffer of audio samples to I2S device
+
+    i2s = I2S(1, sck=Pin(33), ws=Pin(25), sd=Pin(32), mode=I2S.RX, bits=16, format=I2S.MONO, rate=22050, ibuf=40000) # create I2S object
+    i2s.readinto(buf)          # fill buffer with audio samples from I2S device
+
+The I2S class is currently available as a Technical Preview.  During the preview period, feedback from
+users is encouraged.  Based on this feedback, the I2S class API and implementation may be changed.
+
+ESP32 has two I2S buses with id=0 and id=1
+
 Real time clock (RTC)
 ---------------------
 
@@ -407,6 +580,8 @@ See :ref:`machine.WDT <machine.WDT>`. ::
     wdt = WDT(timeout=5000)
     wdt.feed()
 
+.. _Deep_sleep_mode:
+
 Deep-sleep mode
 ---------------
 
@@ -426,30 +601,64 @@ Notes:
 * Calling ``deepsleep()`` without an argument will put the device to sleep
   indefinitely
 * A software reset does not change the reset cause
-* There may be some leakage current flowing through enabled internal pullups.
-  To further reduce power consumption it is possible to disable the internal pullups::
 
-    p1 = Pin(4, Pin.IN, Pin.PULL_HOLD)
+Some ESP32 pins (0, 2, 4, 12-15, 25-27, 32-39) are connected to the RTC during
+deep-sleep and can be used to wake the device with the ``wake_on_`` functions in
+the :mod:`esp32` module. The output-capable RTC pins (all except 34-39) will
+also retain their pull-up or pull-down resistor configuration when entering
+deep-sleep.
 
-  After leaving deepsleep it may be necessary to un-hold the pin explicitly (e.g. if
-  it is an output pin) via::
+If the pull resistors are not actively required during deep-sleep and are likely
+to cause current leakage (for example a pull-up resistor is connected to ground
+through a switch), then they should be disabled to save power before entering
+deep-sleep mode::
 
-    p1 = Pin(4, Pin.OUT, None)
+    from machine import Pin, deepsleep
+
+    # configure input RTC pin with pull-up on boot
+    pin = Pin(2, Pin.IN, Pin.PULL_UP)
+
+    # disable pull-up and put the device to sleep for 10 seconds
+    pin.init(pull=None)
+    machine.deepsleep(10000)
+
+Output-configured RTC pins will also retain their output direction and level in
+deep-sleep if pad hold is enabled with the ``hold=True`` argument to
+``Pin.init()``.
+
+Non-RTC GPIO pins will be disconnected by default on entering deep-sleep.
+Configuration of non-RTC pins - including output level - can be retained by
+enabling pad hold on the pin and enabling GPIO pad hold during deep-sleep::
+
+    from machine import Pin, deepsleep
+    import esp32
+
+    opin = Pin(19, Pin.OUT, value=1, hold=True) # hold output level
+    ipin = Pin(21, Pin.IN, Pin.PULL_UP, hold=True) # hold pull-up
+
+    # enable pad hold in deep-sleep for non-RTC GPIO
+    esp32.gpio_deep_sleep_hold(True)
+
+    # put the device to sleep for 10 seconds
+    deepsleep(10000)
+
+The pin configuration - including the pad hold - will be retained on wake from
+sleep. See :ref:`Pins_and_GPIO` above for a further discussion of pad holding.
 
 SD card
 -------
 
 See :ref:`machine.SDCard <machine.SDCard>`. ::
 
-    import machine, uos
+    import machine, os
 
     # Slot 2 uses pins sck=18, cs=5, miso=19, mosi=23
     sd = machine.SDCard(slot=2)
-    uos.mount(sd, "/sd")  # mount
+    os.mount(sd, '/sd')  # mount
 
-    uos.listdir('/sd')    # list directory contents
+    os.listdir('/sd')    # list directory contents
 
-    uos.umount('/sd')     # eject
+    os.umount('/sd')     # eject
 
 RMT
 ---
@@ -463,7 +672,7 @@ The RMT is ESP32-specific and allows generation of accurate digital pulses with
     r = esp32.RMT(0, pin=Pin(18), clock_div=8)
     r   # RMT(channel=0, pin=18, source_freq=80000000, clock_div=8)
     # The channel resolution is 100ns (1/(source_freq/clock_div)).
-    r.write_pulses((1, 20, 2, 40), start=0) # Send 0 for 100ns, 1 for 2000ns, 0 for 200ns, 1 for 4000ns
+    r.write_pulses((1, 20, 2, 40), 0) # Send 0 for 100ns, 1 for 2000ns, 0 for 200ns, 1 for 4000ns
 
 OneWire driver
 --------------
@@ -516,17 +725,16 @@ The APA106 driver extends NeoPixel, but internally uses a different colour order
     ap = APA106(pin, 8)
     r, g, b = ap[0]
 
-For low-level driving of a NeoPixel::
-
-    import esp
-    esp.neopixel_write(pin, grb_buf, is800khz)
-
 .. Warning::
    By default ``NeoPixel`` is configured to control the more popular *800kHz*
    units. It is possible to use alternative timing to control other (typically
    400kHz) devices by passing ``timing=0`` when constructing the
    ``NeoPixel`` object.
 
+For low-level driving of a NeoPixel see `machine.bitstream`.
+This low-level driver uses an RMT channel by default.  To configure this see
+`RMT.bitstream_channel`.
+
 APA102 (DotStar) uses a different driver as it has an additional clock pin.
 
 Capacitive touch

docs/esp32/tutorial/index.rst

@@ -0,0 +1,23 @@
+.. _esp32_tutorial:
+
+MicroPython tutorial for ESP32
+==============================
+
+This tutorial is intended to get you started using MicroPython on the ESP32
+system-on-a-chip.  If it is your first time it is recommended to follow the
+tutorial through in the order below.  Otherwise the sections are mostly self
+contained, so feel free to skip to those that interest you.
+
+The tutorial does not assume that you know Python, but it also does not attempt
+to explain any of the details of the Python language.  Instead it provides you
+with commands that are ready to run, and hopes that you will gain a bit of
+Python knowledge along the way.  To learn more about Python itself please refer
+to `<https://www.python.org>`__.
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   intro.rst
+   pwm.rst
+   peripheral_access.rst

docs/esp32/tutorial/intro.rst

@@ -34,8 +34,8 @@ Please refer to the documentation for your board for further details.
 Getting the firmware
 --------------------
 
-The first thing you need to do is download the most recent MicroPython firmware 
-.bin file to load onto your ESP32 device. You can download it from the  
+The first thing you need to do is download the most recent MicroPython firmware
+.bin file to load onto your ESP32 device. You can download it from the
 `MicroPython downloads page <https://micropython.org/download#esp32>`_.
 From here, you have 3 main choices:
 

docs/esp32/tutorial/peripheral_access.rst

@@ -0,0 +1,44 @@
+Accessing peripherals directly via registers
+============================================
+
+The ESP32's peripherals can be controlled via direct register reads and writes.
+This requires reading the datasheet to know what registers to use and what
+values to write to them.  The following example shows how to turn on and change
+the prescaler of the MCPWM0 peripheral.
+
+.. code-block:: python3
+
+    from micropython import const
+    from machine import mem32
+
+    # Define the register addresses that will be used.
+    DR_REG_DPORT_BASE = const(0x3FF00000)
+    DPORT_PERIP_CLK_EN_REG = const(DR_REG_DPORT_BASE + 0x0C0)
+    DPORT_PERIP_RST_EN_REG = const(DR_REG_DPORT_BASE + 0x0C4)
+    DPORT_PWM0_CLK_EN = const(1 << 17)
+    MCPWM0 = const(0x3FF5E000)
+    MCPWM1 = const(0x3FF6C000)
+
+    # Enable CLK and disable RST.
+    print(hex(mem32[DPORT_PERIP_CLK_EN_REG] & 0xffffffff))
+    print(hex(mem32[DPORT_PERIP_RST_EN_REG] & 0xffffffff))
+    mem32[DPORT_PERIP_CLK_EN_REG] |= DPORT_PWM0_CLK_EN
+    mem32[DPORT_PERIP_RST_EN_REG] &= ~DPORT_PWM0_CLK_EN
+    print(hex(mem32[DPORT_PERIP_CLK_EN_REG] & 0xffffffff))
+    print(hex(mem32[DPORT_PERIP_RST_EN_REG] & 0xffffffff))
+
+    # Change the MCPWM0 prescaler.
+    print(hex(mem32[MCPWM0])) # read PWM_CLK_CFG_REG (reset value = 0)
+    mem32[MCPWM0] = 0x55      # change PWM_CLK_PRESCALE
+    print(hex(mem32[MCPWM0])) # read PWM_CLK_CFG_REG
+
+Note that before a peripheral can be used its clock must be enabled and it must
+be taken out of reset.  In the above example the following registers are used
+for this:
+
+- ``DPORT_PERI_CLK_EN_REG``: used to enable a peripheral clock
+
+- ``DPORT_PERI_RST_EN_REG``: used to reset (or take out of reset) a peripheral
+
+The MCPWM0 peripheral is in bit position 17 of the above two registers, hence
+the value of ``DPORT_PWM0_CLK_EN``.

docs/esp32/tutorial/pwm.rst

@@ -0,0 +1,115 @@
+.. _esp32_pwm:
+
+Pulse Width Modulation
+======================
+
+Pulse width modulation (PWM) is a way to get an artificial analog output on a
+digital pin.  It achieves this by rapidly toggling the pin from low to high.
+There are two parameters associated with this: the frequency of the toggling,
+and the duty cycle.  The duty cycle is defined to be how long the pin is high
+compared with the length of a single period (low plus high time).  Maximum
+duty cycle is when the pin is high all of the time, and minimum is when it is
+low all of the time.
+
+* More comprehensive example with all 16 PWM channels and 8 timers::
+
+    from machine import Pin, PWM
+    try:
+        f = 100  # Hz
+        d = 1024 // 16  # 6.25%
+        pins = (15, 2, 4, 16, 18, 19, 22, 23, 25, 26, 27, 14 , 12, 13, 32, 33)
+        pwms = []
+        for i, pin in enumerate(pins):
+            pwms.append(PWM(Pin(pin), freq=f * (i // 2 + 1), duty= 1023 if i==15 else d * (i + 1)))
+            print(pwms[i])
+    finally:
+        for pwm in pwms:
+            try:
+                pwm.deinit()
+            except:
+                pass
+
+  Output is::
+
+    PWM(Pin(15), freq=100, duty=64, resolution=10, mode=0, channel=0, timer=0)
+    PWM(Pin(2), freq=100, duty=128, resolution=10, mode=0, channel=1, timer=0)
+    PWM(Pin(4), freq=200, duty=192, resolution=10, mode=0, channel=2, timer=1)
+    PWM(Pin(16), freq=200, duty=256, resolution=10, mode=0, channel=3, timer=1)
+    PWM(Pin(18), freq=300, duty=320, resolution=10, mode=0, channel=4, timer=2)
+    PWM(Pin(19), freq=300, duty=384, resolution=10, mode=0, channel=5, timer=2)
+    PWM(Pin(22), freq=400, duty=448, resolution=10, mode=0, channel=6, timer=3)
+    PWM(Pin(23), freq=400, duty=512, resolution=10, mode=0, channel=7, timer=3)
+    PWM(Pin(25), freq=500, duty=576, resolution=10, mode=1, channel=0, timer=0)
+    PWM(Pin(26), freq=500, duty=640, resolution=10, mode=1, channel=1, timer=0)
+    PWM(Pin(27), freq=600, duty=704, resolution=10, mode=1, channel=2, timer=1)
+    PWM(Pin(14), freq=600, duty=768, resolution=10, mode=1, channel=3, timer=1)
+    PWM(Pin(12), freq=700, duty=832, resolution=10, mode=1, channel=4, timer=2)
+    PWM(Pin(13), freq=700, duty=896, resolution=10, mode=1, channel=5, timer=2)
+    PWM(Pin(32), freq=800, duty=960, resolution=10, mode=1, channel=6, timer=3)
+    PWM(Pin(33), freq=800, duty=1023, resolution=10, mode=1, channel=7, timer=3)
+
+* Example of a smooth frequency change::
+
+    from utime import sleep
+    from machine import Pin, PWM
+
+    F_MIN = 500
+    F_MAX = 1000
+
+    f = F_MIN
+    delta_f = 1
+
+    p = PWM(Pin(5), f)
+    print(p)
+
+    while True:
+        p.freq(f)
+
+        sleep(10 / F_MIN)
+
+        f += delta_f
+        if f >= F_MAX or f <= F_MIN:
+            delta_f = -delta_f
+
+  See PWM wave at Pin(5) with an oscilloscope.
+
+* Example of a smooth duty change::
+
+    from utime import sleep
+    from machine import Pin, PWM
+
+    DUTY_MAX = 2**16 - 1
+
+    duty_u16 = 0
+    delta_d = 16
+
+    p = PWM(Pin(5), 1000, duty_u16=duty_u16)
+    print(p)
+
+    while True:
+        p.duty_u16(duty_u16)
+
+        sleep(1 / 1000)
+
+        duty_u16 += delta_d
+        if duty_u16 >= DUTY_MAX:
+            duty_u16 = DUTY_MAX
+            delta_d = -delta_d
+        elif duty_u16 <= 0:
+            duty_u16 = 0
+            delta_d = -delta_d
+
+  See PWM wave at Pin(5) with an oscilloscope.
+
+Note: the Pin.OUT mode does not need to be specified.  The channel is initialized
+to PWM mode internally once for each Pin that is passed to the PWM constructor.
+
+The following code is wrong::
+
+    pwm = PWM(Pin(5, Pin.OUT), freq=1000, duty=512)  # Pin(5) in PWM mode here
+    pwm = PWM(Pin(5, Pin.OUT), freq=500, duty=256)  # Pin(5) in OUT mode here, PWM is off
+
+Use this code instead::
+
+    pwm = PWM(Pin(5), freq=1000, duty=512)
+    pwm.init(freq=500, duty=256)

docs/esp8266/general.rst

@@ -117,7 +117,7 @@ Real-time clock
 
 RTC in ESP8266 has very bad accuracy, drift may be seconds per minute. As
 a workaround, to measure short enough intervals you can use
-``utime.time()``, etc. functions, and for wall clock time, synchronize from
+``time.time()``, etc. functions, and for wall clock time, synchronize from
 the net using included ``ntptime.py`` module.
 
 Due to limitations of the ESP8266 chip the internal real-time clock (RTC)
@@ -203,7 +203,7 @@ limitation with usage of TLS on the low-memory devices:
    communication with other devices.
 
 There are also some not implemented features specifically in MicroPython's
-``ussl`` module based on axTLS:
+``ssl`` module based on axTLS:
 
 6. Certificates are not validated (this makes connections susceptible
    to man-in-the-middle attacks).

docs/esp8266/quickref.rst

@@ -57,13 +57,13 @@ The :mod:`network` module::
     wlan.active(True)       # activate the interface
     wlan.scan()             # scan for access points
     wlan.isconnected()      # check if the station is connected to an AP
-    wlan.connect('essid', 'password') # connect to an AP
+    wlan.connect('ssid', 'key') # connect to an AP
     wlan.config('mac')      # get the interface's MAC address
     wlan.ifconfig()         # get the interface's IP/netmask/gw/DNS addresses
 
     ap = network.WLAN(network.AP_IF) # create access-point interface
     ap.active(True)         # activate the interface
-    ap.config(essid='ESP-AP') # set the ESSID of the access point
+    ap.config(ssid='ESP-AP') # set the SSID of the access point
 
 A useful function for connecting to your local WiFi network is::
 
@@ -73,18 +73,18 @@ A useful function for connecting to your local WiFi network is::
         wlan.active(True)
         if not wlan.isconnected():
             print('connecting to network...')
-            wlan.connect('essid', 'password')
+            wlan.connect('ssid', 'key')
             while not wlan.isconnected():
                 pass
         print('network config:', wlan.ifconfig())
 
-Once the network is established the :mod:`socket <usocket>` module can be used
+Once the network is established the :mod:`socket <socket>` module can be used
 to create and use TCP/UDP sockets as usual.
 
 Delay and timing
 ----------------
 
-Use the :mod:`time <utime>` module::
+Use the :mod:`time <time>` module::
 
     import time
 
@@ -171,15 +171,15 @@ attaches the REPL).
 
 To detach the REPL from UART0, use::
 
-    import uos
-    uos.dupterm(None, 1)
+    import os
+    os.dupterm(None, 1)
 
 The REPL is attached by default. If you have detached it, to reattach
 it use::
 
-    import uos, machine
+    import os, machine
     uart = machine.UART(0, 115200)
-    uos.dupterm(uart, 1)
+    os.dupterm(uart, 1)
 
 PWM (pulse width modulation)
 ----------------------------
@@ -270,11 +270,11 @@ alias of :ref:`machine.SoftI2C <machine.SoftI2C>`)::
     # construct an I2C bus
     i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000)
 
-    i2c.readfrom(0x3a, 4)   # read 4 bytes from slave device with address 0x3a
-    i2c.writeto(0x3a, '12') # write '12' to slave device with address 0x3a
+    i2c.readfrom(0x3a, 4)   # read 4 bytes from peripheral device with address 0x3a
+    i2c.writeto(0x3a, '12') # write '12' to peripheral device with address 0x3a
 
     buf = bytearray(10)     # create a buffer with 10 bytes
-    i2c.writeto(0x3a, buf)  # write the given buffer to the slave
+    i2c.writeto(0x3a, buf)  # write the given buffer to the peripheral
 
 Real time clock (RTC)
 ---------------------
@@ -374,17 +374,13 @@ Use the ``neopixel`` module::
     np.write()              # write data to all pixels
     r, g, b = np[0]         # get first pixel colour
 
-For low-level driving of a NeoPixel::
-
-    import esp
-    esp.neopixel_write(pin, grb_buf, is800khz)
-
 .. Warning::
    By default ``NeoPixel`` is configured to control the more popular *800kHz*
    units. It is possible to use alternative timing to control other (typically
    400kHz) devices by passing ``timing=0`` when constructing the
    ``NeoPixel`` object.
 
+For low-level driving of a NeoPixel see `machine.bitstream`.
 
 APA102 driver
 -------------

docs/esp8266/tutorial/intro.rst

@@ -23,7 +23,7 @@ convertor to make the UART available to your PC.
 The minimum requirement for flash size is 1Mbyte. There is also a special
 build for boards with 512KB, but it is highly limited comparing to the
 normal build: there is no support for filesystem, and thus features which
-depend on it won't work (WebREPL, upip, etc.). As such, 512KB build will
+depend on it won't work (WebREPL, mip, etc.). As such, 512KB build will
 be more interesting for users who build from source and fine-tune parameters
 for their particular application.
 
@@ -41,8 +41,8 @@ Please refer to the documentation for your board for further details.
 Getting the firmware
 --------------------
 
-The first thing you need to do is download the most recent MicroPython firmware 
-.bin file to load onto your ESP8266 device. You can download it from the  
+The first thing you need to do is download the most recent MicroPython firmware
+.bin file to load onto your ESP8266 device. You can download it from the
 `MicroPython downloads page <http://micropython.org/download#esp8266>`_.
 From here, you have 3 main choices
 
@@ -64,7 +64,7 @@ such, only daily builds for 512kb modules are provided.
 Deploying the firmware
 ----------------------
 
-Once you have the MicroPython firmware (compiled code), you need to load it onto 
+Once you have the MicroPython firmware (compiled code), you need to load it onto
 your ESP8266 device.  There are two main steps to do this: first you
 need to put your device in boot-loader mode, and second you need to copy across
 the firmware.  The exact procedure for these steps is highly dependent on the
@@ -109,10 +109,12 @@ PC.  You may also need to reduce the baudrate if you get errors when flashing
 that you have.
 
 For some boards with a particular FlashROM configuration (e.g. some variants of
-a NodeMCU board) you may need to use the following command to deploy
-the firmware (note the ``-fm dio`` option)::
+a NodeMCU board) you may need to manually set a compatible
+`SPI Flash Mode <https://github.com/espressif/esptool/wiki/SPI-Flash-Modes>`_.
+You'd usually pick the fastest option that is compatible with your device, but
+the ``-fm dout`` option (the slowest option) should have the best compatibility::
 
-    esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect -fm dio 0 esp8266-20170108-v1.8.7.bin
+    esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect -fm dout 0 esp8266-20170108-v1.8.7.bin
 
 If the above commands run without error then MicroPython should be installed on
 your board!

docs/esp8266/tutorial/network_basics.rst

@@ -37,7 +37,7 @@ First activate the station interface::
 
 Then connect to your WiFi network::
 
-    >>> sta_if.connect('<your ESSID>', '<your password>')
+    >>> sta_if.connect('<your SSID>', '<your key>')
 
 To check if the connection is established use::
 
@@ -61,7 +61,7 @@ connect to your WiFi network::
         if not sta_if.isconnected():
             print('connecting to network...')
             sta_if.active(True)
-            sta_if.connect('<essid>', '<password>')
+            sta_if.connect('<ssid>', '<key>')
             while not sta_if.isconnected():
                 pass
         print('network config:', sta_if.ifconfig())

docs/esp8266/tutorial/repl.rst

@@ -18,9 +18,9 @@ the REPL directly from your PC.  Otherwise you will need to have a way of
 communicating with the UART.
 
 To access the prompt over USB-serial you need to use a terminal emulator program.
-On Windows TeraTerm is a good choice, on Mac you can use the built-in screen
-program, and Linux has picocom and minicom.  Of course, there are many other
-terminal programs that will work, so pick your favourite!
+On Windows TeraTerm is a good choice, on Mac you can use the built-in ``screen``
+program, and Linux has ``picocom`` and ``minicom``.  Of course, there are many
+other terminal programs that will work, so pick your favourite!
 
 For example, on Linux you can try running::
 
@@ -37,9 +37,9 @@ WebREPL allows you to use the Python prompt over WiFi, connecting through a
 browser. The latest versions of Firefox and Chrome are supported.
 
 For your convenience, WebREPL client is hosted at
-`<http://micropython.org/webrepl>`__ . Alternatively, you can install it
+`<http://micropython.org/webrepl>`__. Alternatively, you can install it
 locally from the the GitHub repository
-`<https://github.com/micropython/webrepl>`__ .
+`<https://github.com/micropython/webrepl>`__.
 
 Before connecting to WebREPL, you should set a password and enable it via
 a normal serial connection. Initial versions of MicroPython for ESP8266

docs/esp8266/tutorial/ssd1306.rst

@@ -66,8 +66,8 @@ Subclassing FrameBuffer provides support for graphics primitives::
     display.hline(0, 8, 4, 1)               # draw horizontal line x=0, y=8, width=4, colour=1
     display.vline(0, 8, 4, 1)               # draw vertical line x=0, y=8, height=4, colour=1
     display.line(0, 0, 127, 63, 1)          # draw a line from 0,0 to 127,63
-    display.rect(10, 10, 107, 43, 1)        # draw a rectangle outline 10,10 to 107,43, colour=1
-    display.fill_rect(10, 10, 107, 43, 1)   # draw a solid rectangle 10,10 to 107,43, colour=1
+    display.rect(10, 10, 107, 43, 1)        # draw a rectangle outline 10,10 to 117,53, colour=1
+    display.fill_rect(10, 10, 107, 43, 1)   # draw a solid rectangle 10,10 to 117,53, colour=1
     display.text('Hello World', 0, 0, 1)    # draw some text at x=0, y=0, colour=1
     display.scroll(20, 0)                   # scroll 20 pixels to the right
 

docs/index.rst

@@ -12,5 +12,9 @@ MicroPython documentation and references
     esp8266/quickref.rst
     esp32/quickref.rst
     rp2/quickref.rst
+    mimxrt/quickref.rst
     wipy/quickref.rst
     unix/quickref.rst
+    zephyr/quickref.rst
+    renesas-ra/quickref.rst
+    samd/quickref.rst

docs/library/array.rst

@@ -0,0 +1,81 @@
+:mod:`array` -- arrays of numeric data
+======================================
+
+.. module:: array
+   :synopsis: efficient arrays of numeric data
+
+|see_cpython_module| :mod:`python:array`.
+
+Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``,
+``L``, ``q``, ``Q``, ``f``, ``d`` (the latter 2 depending on the
+floating-point support).
+
+Classes
+-------
+
+.. class:: array(typecode, [iterable])
+
+    Create array with elements of given type. Initial contents of the
+    array are given by *iterable*. If it is not provided, an empty
+    array is created.
+
+    .. method:: append(val)
+
+        Append new element *val* to the end of array, growing it.
+
+    .. method:: extend(iterable)
+
+        Append new elements as contained in *iterable* to the end of
+        array, growing it.
+
+    .. method:: __getitem__(index)
+
+        Indexed read of the array, called as ``a[index]`` (where ``a`` is an ``array``).
+        Returns a value if *index* is an ``int`` and an ``array`` if *index* is a slice.
+        Negative indices count from the end and ``IndexError`` is thrown if the index is
+        out of range.
+
+        **Note:** ``__getitem__`` cannot be called directly (``a.__getitem__(index)`` fails) and
+        is not present in ``__dict__``, however ``a[index]`` does work.
+
+    .. method:: __setitem__(index, value)
+
+        Indexed write into the array, called as ``a[index] = value`` (where ``a`` is an ``array``).
+        ``value`` is a single value if *index* is an ``int`` and an ``array`` if *index* is a slice.
+        Negative indices count from the end and ``IndexError`` is thrown if the index is out of range.
+
+        **Note:** ``__setitem__`` cannot be called directly (``a.__setitem__(index, value)`` fails) and
+        is not present in ``__dict__``, however ``a[index] = value`` does work.
+
+    .. method:: __len__()
+
+        Returns the number of items in the array, called as ``len(a)`` (where ``a`` is an ``array``).
+
+        **Note:** ``__len__`` cannot be called directly (``a.__len__()`` fails) and the
+        method is not present in ``__dict__``, however ``len(a)`` does work.
+
+    .. method:: __add__(other)
+
+        Return a new ``array`` that is the concatenation of the array with *other*, called as
+        ``a + other`` (where ``a`` and *other* are both ``arrays``).
+
+        **Note:** ``__add__`` cannot be called directly (``a.__add__(other)`` fails) and
+        is not present in ``__dict__``, however ``a + other`` does work.
+
+    .. method:: __iadd__(other)
+
+        Concatenates the array with *other* in-place, called as ``a += other`` (where ``a`` and *other*
+        are both ``arrays``).  Equivalent to ``extend(other)``.
+
+        **Note:** ``__iadd__`` cannot be called directly (``a.__iadd__(other)`` fails) and
+        is not present in ``__dict__``, however ``a += other`` does work.
+
+    .. method:: __repr__()
+
+        Returns the string representation of the array, called as ``str(a)`` or ``repr(a)```
+        (where ``a`` is an ``array``).  Returns the string ``"array(<type>, [<elements>])"``,
+        where ``<type>`` is the type code letter for the array and ``<elements>`` is a comma
+        seperated list of the elements of the array.
+
+        **Note:** ``__repr__`` cannot be called directly (``a.__repr__()`` fails) and
+        is not present in ``__dict__``, however ``str(a)`` and ``repr(a)`` both work.

docs/library/binascii.rst

@@ -1,7 +1,7 @@
-:mod:`ubinascii` -- binary/ASCII conversions
-============================================
+:mod:`binascii` -- binary/ASCII conversions
+===========================================
 
-.. module:: ubinascii
+.. module:: binascii
    :synopsis: binary/ASCII conversions
 
 |see_cpython_module| :mod:`python:binascii`.
@@ -31,8 +31,8 @@ Functions
    Conforms to `RFC 2045 s.6.8 <https://tools.ietf.org/html/rfc2045#section-6.8>`_.
    Returns a bytes object.
 
-.. function:: b2a_base64(data)
+.. function:: b2a_base64(data, *, newline=True)
 
    Encode binary data in base64 format, as in `RFC 3548
    <https://tools.ietf.org/html/rfc3548.html>`_. Returns the encoded data
-   followed by a newline character, as a bytes object.
+   followed by a newline character if newline is true, as a bytes object.

docs/library/bluetooth.rst

@@ -1,7 +1,7 @@
-:mod:`ubluetooth` --- low-level Bluetooth
-=========================================
+:mod:`bluetooth` --- low-level Bluetooth
+========================================
 
-.. module:: ubluetooth
+.. module:: bluetooth
    :synopsis: Low-level Bluetooth radio functionality
 
 This module provides an interface to a Bluetooth controller on a board.
@@ -13,6 +13,9 @@ concurrently. Pairing (and bonding) is supported on some ports.
 This API is intended to match the low-level Bluetooth protocol and provide
 building-blocks for higher-level abstractions such as specific device types.
 
+.. note:: For most applications, we recommend using the higher-level
+          `aioble library <https://github.com/micropython/micropython-lib/tree/master/micropython/bluetooth/aioble>`_.
+
 .. note:: This module is still under development and its classes, functions,
           methods and constants are subject to change.
 
@@ -49,7 +52,7 @@ Configuration
     - ``'mac'``: The current address in use, depending on the current address mode.
       This returns a tuple of ``(addr_type, addr)``.
 
-      See :meth:`gatts_write <BLE.gap_scan>` for details about address type.
+      See :meth:`gatts_write <BLE.gatts_write>` for details about address type.
 
       This may only be queried while the interface is currently active.
 
@@ -110,7 +113,7 @@ Event Handling
 
     **Note:** As an optimisation to prevent unnecessary allocations, the ``addr``,
     ``adv_data``, ``char_data``, ``notify_data``, and ``uuid`` entries in the
-    tuples are read-only memoryview instances pointing to ubluetooth's internal
+    tuples are read-only memoryview instances pointing to :mod:`bluetooth`'s internal
     ringbuffer, and are only valid during the invocation of the IRQ handler
     function.  If your program needs to save one of these values to access after
     the IRQ handler has returned (e.g. by saving it in a class instance or global
@@ -163,7 +166,7 @@ Event Handling
                 conn_handle, status = data
             elif event == _IRQ_GATTC_CHARACTERISTIC_RESULT:
                 # Called for each characteristic found by gattc_discover_services().
-                conn_handle, def_handle, value_handle, properties, uuid = data
+                conn_handle, end_handle, value_handle, properties, uuid = data
             elif event == _IRQ_GATTC_CHARACTERISTIC_DONE:
                 # Called once service discovery is complete.
                 # Note: Status will be zero on success, implementation-specific value otherwise.
@@ -180,12 +183,10 @@ Event Handling
                 conn_handle, value_handle, char_data = data
             elif event == _IRQ_GATTC_READ_DONE:
                 # A gattc_read() has completed.
-                # Note: The value_handle will be zero on btstack (but present on NimBLE).
                 # Note: Status will be zero on success, implementation-specific value otherwise.
                 conn_handle, value_handle, status = data
             elif event == _IRQ_GATTC_WRITE_DONE:
                 # A gattc_write() has completed.
-                # Note: The value_handle will be zero on btstack (but present on NimBLE).
                 # Note: Status will be zero on success, implementation-specific value otherwise.
                 conn_handle, value_handle, status = data
             elif event == _IRQ_GATTC_NOTIFY:
@@ -293,7 +294,7 @@ For the ``_IRQ_PASSKEY_ACTION`` event, the available actions are::
     _PASSKEY_ACTION_NUMERIC_COMPARISON = const(4)
 
 In order to save space in the firmware, these constants are not included on the
-:mod:`ubluetooth` module. Add the ones that you need from the list above to your
+:mod:`bluetooth` module. Add the ones that you need from the list above to your
 program.
 
 
@@ -359,13 +360,27 @@ Central Role
 
 A central device can connect to peripherals that it has discovered using the observer role (see :meth:`gap_scan<BLE.gap_scan>`) or with a known address.
 
-.. method:: BLE.gap_connect(addr_type, addr, scan_duration_ms=2000, /)
+.. method:: BLE.gap_connect(addr_type, addr, scan_duration_ms=2000, min_conn_interval_us=None, max_conn_interval_us=None, /)
 
     Connect to a peripheral.
 
     See :meth:`gap_scan <BLE.gap_scan>` for details about address types.
 
-    On success, the ``_IRQ_PERIPHERAL_CONNECT`` event will be raised.
+    To cancel an outstanding connection attempt early, call
+    ``gap_connect(None)``.
+
+    On success, the ``_IRQ_PERIPHERAL_CONNECT`` event will be raised. If
+    cancelling a connection attempt, the ``_IRQ_PERIPHERAL_DISCONNECT`` event
+    will be raised.
+
+    The device will wait up to *scan_duration_ms* to receive an advertising
+    payload from the device.
+
+    The connection interval can be configured in **micro**\ seconds using either
+    or both of *min_conn_interval_us* and *max_conn_interval_us*. Otherwise a
+    default interval will be chosen, typically between 30000 and 50000
+    microseconds. A shorter interval will increase throughput, at the expense
+    of power usage.
 
 
 Peripheral Role
@@ -485,31 +500,43 @@ writes from a client to a given characteristic, use
     Reads the local value for this handle (which has either been written by
     :meth:`gatts_write <BLE.gatts_write>` or by a remote client).
 
-.. method:: BLE.gatts_write(value_handle, data, /)
+.. method:: BLE.gatts_write(value_handle, data, send_update=False, /)
 
     Writes the local value for this handle, which can be read by a client.
 
+    If *send_update* is ``True``, then any subscribed clients will be notified
+    (or indicated, depending on what they're subscribed to and which operations
+    the characteristic supports) about this write.
+
 .. method:: BLE.gatts_notify(conn_handle, value_handle, data=None, /)
 
     Sends a notification request to a connected client.
 
-    If *data* is not ``None``, then that value is sent to the client as part of
-    the notification. The local value will not be modified.
+    If *data* is ``None`` (the default), then the current local value (as set
+    with :meth:`gatts_write <BLE.gatts_write>`) will be sent.
 
-    Otherwise, if *data* is ``None``, then the current local value (as
-    set with :meth:`gatts_write <BLE.gatts_write>`) will be sent.
+    Otherwise, if *data* is not ``None``, then that value is sent to the client
+    as part of the notification. The local value will not be modified.
 
-.. method:: BLE.gatts_indicate(conn_handle, value_handle, /)
+    **Note:** The notification will be sent regardless of the subscription
+    status of the client to this characteristic.
 
-    Sends an indication request to a connected client.
+.. method:: BLE.gatts_indicate(conn_handle, value_handle, data=None, /)
 
-    **Note:** This does not currently support sending a custom value, it will
-    always send the current local value (as set with :meth:`gatts_write
-    <BLE.gatts_write>`).
+    Sends a indication request to a connected client.
+
+    If *data* is ``None`` (the default), then the current local value (as set
+    with :meth:`gatts_write <BLE.gatts_write>`) will be sent.
+
+    Otherwise, if *data* is not ``None``, then that value is sent to the client
+    as part of the indication. The local value will not be modified.
 
     On acknowledgment (or failure, e.g. timeout), the
     ``_IRQ_GATTS_INDICATE_DONE`` event will be raised.
 
+    **Note:** The indication will be sent regardless of the subscription
+    status of the client to this characteristic.
+
 .. method:: BLE.gatts_set_buffer(value_handle, len, append=False, /)
 
     Sets the internal buffer size for a value in bytes. This will limit the

docs/library/btree.rst

@@ -11,8 +11,9 @@ value, a database also supports efficient ordered range scans (retrieval
 of values with the keys in a given range). On the application interface
 side, BTree database work as close a possible to a way standard `dict`
 type works, one notable difference is that both keys and values must
-be `bytes` objects (so, if you want to store objects of other types, you
-need to serialize them to `bytes` first).
+be `bytes`-like objects (so, if you want to store objects of other types, you
+need to first serialize them to `str` or `bytes` or another type that supports
+the buffer protocol).
 
 The module is based on the well-known BerkelyDB library, version 1.xx.
 
@@ -22,7 +23,7 @@ Example::
 
     # First, we need to open a stream which holds a database
     # This is usually a file, but can be in-memory database
-    # using uio.BytesIO, a raw flash partition, etc.
+    # using io.BytesIO, a raw flash partition, etc.
     # Oftentimes, you want to create a database file if it doesn't
     # exist and open if it exists. Idiom below takes care of this.
     # DO NOT open database with "a+b" access mode.

docs/library/builtins.rst

@@ -1,5 +1,5 @@
-Builtin functions and exceptions
-================================
+:mod:`builtins` -- builtin functions and exceptions
+===================================================
 
 All builtin functions and exceptions are described here. They are also
 available via ``builtins`` module.

docs/library/collections.rst

@@ -1,7 +1,7 @@
-:mod:`ucollections` -- collection and container types
-=====================================================
+:mod:`collections` -- collection and container types
+====================================================
 
-.. module:: ucollections
+.. module:: collections
    :synopsis: collection and container types
 
 |see_cpython_module| :mod:`python:collections`.
@@ -12,7 +12,7 @@ hold/accumulate various objects.
 Classes
 -------
 
-.. function:: deque(iterable, maxlen[, flags])
+.. class:: deque(iterable, maxlen[, flags])
 
     Deques (double-ended queues) are a list-like container that support O(1)
     appends and pops from either side of the deque.  New deques are created
@@ -49,7 +49,7 @@ Classes
     a string with space-separated field named (but this is less efficient).
     Example of use::
 
-        from ucollections import namedtuple
+        from collections import namedtuple
 
         MyTuple = namedtuple("MyTuple", ("id", "name"))
         t1 = MyTuple(1, "foo")
@@ -57,13 +57,13 @@ Classes
         print(t1.name)
         assert t2.name == t2[1]
 
-.. function:: OrderedDict(...)
+.. class:: OrderedDict(...)
 
     ``dict`` type subclass which remembers and preserves the order of keys
     added. When ordered dict is iterated over, keys/items are returned in
     the order they were added::
 
-        from ucollections import OrderedDict
+        from collections import OrderedDict
 
         # To make benefit of ordered keys, OrderedDict should be initialized
         # from sequence of (key, value) pairs.

docs/library/cryptolib.rst

@@ -1,7 +1,7 @@
-:mod:`ucryptolib` -- cryptographic ciphers
-==========================================
+:mod:`cryptolib` -- cryptographic ciphers
+=========================================
 
-.. module:: ucryptolib
+.. module:: cryptolib
    :synopsis: cryptographic ciphers
 
 Classes
@@ -21,9 +21,9 @@ Classes
             * *key* is an encryption/decryption key (bytes-like).
             * *mode* is:
 
-                * ``1`` (or ``ucryptolib.MODE_ECB`` if it exists) for Electronic Code Book (ECB).
-                * ``2`` (or ``ucryptolib.MODE_CBC`` if it exists) for Cipher Block Chaining (CBC).
-                * ``6`` (or ``ucryptolib.MODE_CTR`` if it exists) for Counter mode (CTR).
+                * ``1`` (or ``cryptolib.MODE_ECB`` if it exists) for Electronic Code Book (ECB).
+                * ``2`` (or ``cryptolib.MODE_CBC`` if it exists) for Cipher Block Chaining (CBC).
+                * ``6`` (or ``cryptolib.MODE_CTR`` if it exists) for Counter mode (CTR).
 
             * *IV* is an initialization vector for CBC mode.
             * For Counter mode, *IV* is the initial value for the counter.

docs/library/errno.rst

@@ -1,7 +1,7 @@
-:mod:`uerrno` -- system error codes
-===================================
+:mod:`errno` -- system error codes
+==================================
 
-.. module:: uerrno
+.. module:: errno
    :synopsis: system error codes
 
 |see_cpython_module| :mod:`python:errno`.
@@ -20,9 +20,9 @@ Constants
     where ``exc`` is an instance of `OSError`. Usage example::
 
         try:
-            uos.mkdir("my_dir")
+            os.mkdir("my_dir")
         except OSError as exc:
-            if exc.errno == uerrno.EEXIST:
+            if exc.errno == errno.EEXIST:
                 print("Directory already exists")
 
 .. data:: errorcode
@@ -30,5 +30,5 @@ Constants
     Dictionary mapping numeric error codes to strings with symbolic error
     code (see above)::
 
-        >>> print(uerrno.errorcode[uerrno.EEXIST])
+        >>> print(errno.errorcode[errno.EEXIST])
         EEXIST

docs/library/esp.rst

@@ -4,7 +4,7 @@
 .. module:: esp
     :synopsis: functions related to the ESP8266 and ESP32
 
-The ``esp`` module contains specific functions related to both the ESP8266 and 
+The ``esp`` module contains specific functions related to both the ESP8266 and
 ESP32 modules.  Some functions are only available on one or the other of these
 ports.
 
@@ -62,6 +62,21 @@ Functions
 
 .. function:: flash_erase(sector_no)
 
+.. function:: osdebug(level)
+
+    Turn esp os debugging messages on or off.
+
+    The *level* parameter sets the threshold for the log messages for all esp components.
+    The log levels are defined as constants:
+
+        * ``LOG_NONE`` -- No log output
+        * ``LOG_ERROR`` -- Critical errors, software module can not recover on its own
+        * ``LOG_WARN`` -- Error conditions from which recovery measures have been taken
+        * ``LOG_INFO`` -- Information messages which describe normal flow of events
+        * ``LOG_DEBUG`` -- Extra information which is not necessary for normal use (values, pointers, sizes, etc)
+        * ``LOG_VERBOSE`` -- Bigger chunks of debugging information, or frequent messages
+          which can potentially flood the output
+
 .. function:: set_native_code_location(start, length)
 
     **Note**: ESP8266 only

docs/library/esp32.rst

@@ -18,6 +18,11 @@ Functions
     Configure whether or not a touch will wake the device from sleep.
     *wake* should be a boolean value.
 
+.. function:: wake_on_ulp(wake)
+
+    Configure whether or not the Ultra-Low-Power co-processor can wake the
+    device from sleep. *wake* should be a boolean value.
+
 .. function:: wake_on_ext0(pin, level)
 
     Configure how EXT0 wakes the device from sleep.  *pin* can be ``None``
@@ -30,6 +35,11 @@ Functions
     or a tuple/list of valid Pin objects.  *level* should be ``esp32.WAKEUP_ALL_LOW``
     or ``esp32.WAKEUP_ANY_HIGH``.
 
+.. function:: gpio_deep_sleep_hold(enable)
+
+    Configure whether non-RTC GPIO pin configuration is retained during
+    deep-sleep mode for held pads. *enable* should be a boolean value.
+
 .. function:: raw_temperature()
 
     Read the raw value of the internal temperature sensor, returning an integer.
@@ -68,17 +78,21 @@ Flash partitions
 This class gives access to the partitions in the device's flash memory and includes
 methods to enable over-the-air (OTA) updates.
 
-.. class:: Partition(id)
+.. class:: Partition(id, block_size=4096, /)
 
     Create an object representing a partition.  *id* can be a string which is the label
     of the partition to retrieve, or one of the constants: ``BOOT`` or ``RUNNING``.
+    *block_size* specifies the byte size of an individual block.
 
-.. classmethod:: Partition.find(type=TYPE_APP, subtype=0xff, label=None)
+.. classmethod:: Partition.find(type=TYPE_APP, subtype=0xff, label=None, block_size=4096)
 
     Find a partition specified by *type*, *subtype* and *label*.  Returns a
     (possibly empty) list of Partition objects. Note: ``subtype=0xff`` matches any subtype
     and ``label=None`` matches any label.
 
+    *block_size* specifies the byte size of an individual block used by the returned
+    objects.
+
 .. method:: Partition.info()
 
     Returns a 6-tuple ``(type, subtype, addr, size, label, encrypted)``.
@@ -91,7 +105,7 @@ methods to enable over-the-air (OTA) updates.
 
     These methods implement the simple and :ref:`extended
     <block-device-interface>` block protocol defined by
-    :class:`uos.AbstractBlockDev`.
+    :class:`os.AbstractBlockDev`.
 
 .. method:: Partition.set_boot()
 
@@ -150,14 +164,13 @@ used to transmit or receive many other types of digital signals::
     from machine import Pin
 
     r = esp32.RMT(0, pin=Pin(18), clock_div=8)
-    r  # RMT(channel=0, pin=18, source_freq=80000000, clock_div=8)
+    r  # RMT(channel=0, pin=18, source_freq=80000000, clock_div=8, idle_level=0)
 
-    # To use carrier frequency
-    r = esp32.RMT(0, pin=Pin(18), clock_div=8, carrier_freq=38000)
-    r  # RMT(channel=0, pin=18, source_freq=80000000, clock_div=8, carrier_freq=38000, carrier_duty_percent=50)
+    # To apply a carrier frequency to the high output
+    r = esp32.RMT(0, pin=Pin(18), clock_div=8, tx_carrier=(38000, 50, 1))
 
     # The channel resolution is 100ns (1/(source_freq/clock_div)).
-    r.write_pulses((1, 20, 2, 40), start=0)  # Send 0 for 100ns, 1 for 2000ns, 0 for 200ns, 1 for 4000ns
+    r.write_pulses((1, 20, 2, 40), 0)  # Send 0 for 100ns, 1 for 2000ns, 0 for 200ns, 1 for 4000ns
 
 The input to the RMT module is an 80MHz clock (in the future it may be able to
 configure the input clock but, for now, it's fixed). ``clock_div`` *divides*
@@ -169,9 +182,6 @@ define the pulses.
 multiplying the resolution by a 15-bit (0-32,768) number. There are eight
 channels (0-7) and each can have a different clock divider.
 
-To enable the carrier frequency feature of the esp32 hardware, specify the
-``carrier_freq`` as something like 38000, a typical IR carrier frequency.
-
 So, in the example above, the 80MHz clock is divided by 8. Thus the
 resolution is (1/(80Mhz/8)) 100ns. Since the ``start`` level is 0 and toggles
 with each number, the bitstream is ``0101`` with durations of [100ns, 2000ns,
@@ -186,16 +196,21 @@ For more details see Espressif's `ESP-IDF RMT documentation.
    *beta feature* and the interface may change in the future.
 
 
-.. class:: RMT(channel, *, pin=None, clock_div=8, carrier_freq=0, carrier_duty_percent=50)
+.. class:: RMT(channel, *, pin=None, clock_div=8, idle_level=False, tx_carrier=None)
 
     This class provides access to one of the eight RMT channels. *channel* is
     required and identifies which RMT channel (0-7) will be configured. *pin*,
     also required, configures which Pin is bound to the RMT channel. *clock_div*
     is an 8-bit clock divider that divides the source clock (80MHz) to the RMT
-    channel allowing the resolution to be specified. *carrier_freq* is used to
-    enable the carrier feature and specify its frequency, default value is ``0``
-    (not enabled).  To enable, specify a positive integer.  *carrier_duty_percent*
-    defaults to 50.
+    channel allowing the resolution to be specified. *idle_level* specifies
+    what level the output will be when no transmission is in progress and can
+    be any value that converts to a boolean, with ``True`` representing high
+    voltage and ``False`` representing low.
+
+    To enable the transmission carrier feature, *tx_carrier* should be a tuple
+    of three positive integers: carrier frequency, duty percent (``0`` to
+    ``100``) and the output level to apply the carrier to (a boolean as per
+    *idle_level*).
 
 .. method:: RMT.source_freq()
 
@@ -207,40 +222,59 @@ For more details see Espressif's `ESP-IDF RMT documentation.
     Return the clock divider. Note that the channel resolution is
     ``1 / (source_freq / clock_div)``.
 
-.. method:: RMT.wait_done(timeout=0)
+.. method:: RMT.wait_done(*, timeout=0)
 
-    Returns ``True`` if the channel is currently transmitting a stream of pulses
-    started with a call to `RMT.write_pulses`.
-
-    If *timeout* (defined in ticks of ``source_freq / clock_div``) is specified
-    the method will wait for *timeout* or until transmission is complete,
-    returning ``False`` if the channel continues to transmit. If looping is
-    enabled with `RMT.loop` and a stream has started, then this method will
-    always (wait and) return ``False``.
+    Returns ``True`` if the channel is idle or ``False`` if a sequence of
+    pulses started with `RMT.write_pulses` is being transmitted. If the
+    *timeout* keyword argument is given then block for up to this many
+    milliseconds for transmission to complete.
 
 .. method:: RMT.loop(enable_loop)
 
     Configure looping on the channel. *enable_loop* is bool, set to ``True`` to
     enable looping on the *next* call to `RMT.write_pulses`. If called with
-    ``False`` while a looping stream is currently being transmitted then the
-    current set of pulses will be completed before transmission stops.
+    ``False`` while a looping sequence is currently being transmitted then the
+    current loop iteration will be completed and then transmission will stop.
 
-.. method:: RMT.write_pulses(pulses, start)
+.. method:: RMT.write_pulses(duration, data=True)
 
-    Begin sending *pulses*, a list or tuple defining the stream of pulses. The
-    length of each pulse is defined by a number to be multiplied by the channel
-    resolution ``(1 / (source_freq / clock_div))``. *start* defines whether the
-    stream starts at 0 or 1.
+    Begin transmitting a sequence. There are three ways to specify this:
 
-    If transmission of a stream is currently in progress then this method will
-    block until transmission of that stream has ended before beginning sending
-    *pulses*.
+    **Mode 1:** *duration* is a list or tuple of durations. The optional *data*
+    argument specifies the initial output level. The output level will toggle
+    after each duration.
 
-    If looping is enabled with `RMT.loop`, the stream of pulses will be repeated
-    indefinitely. Further calls to `RMT.write_pulses` will end the previous
-    stream - blocking until the last set of pulses has been transmitted -
-    before starting the next stream.
+    **Mode 2:** *duration* is a positive integer and *data* is a list or tuple
+    of output levels. *duration* specifies a fixed duration for each.
 
+    **Mode 3:** *duration* and *data* are lists or tuples of equal length,
+    specifying individual durations and the output level for each.
+
+    Durations are in integer units of the channel resolution (as described
+    above), between 1 and 32767 units. Output levels are any value that can
+    be converted to a boolean, with ``True`` representing high voltage and
+    ``False`` representing low.
+
+    If transmission of an earlier sequence is in progress then this method will
+    block until that transmission is complete before beginning the new sequence.
+
+    If looping has been enabled with `RMT.loop`, the sequence will be
+    repeated indefinitely. Further calls to this method will block until the
+    end of the current loop iteration before immediately beginning to loop the
+    new sequence of pulses. Looping sequences longer than 126 pulses is not
+    supported by the hardware.
+
+.. staticmethod:: RMT.bitstream_channel([value])
+
+    Select which RMT channel is used by the `machine.bitstream` implementation.
+    *value* can be ``None`` or a valid RMT channel number.  The default RMT
+    channel is the highest numbered one.
+
+    Passing in ``None`` disables the use of RMT and instead selects a bit-banging
+    implementation for `machine.bitstream`.
+
+    Passing in no argument will not change the channel.  This function returns
+    the current channel number.
 
 Ultra-Low-Power co-processor
 ----------------------------

docs/library/framebuf.rst

@@ -11,19 +11,19 @@ class FrameBuffer
 -----------------
 
 The FrameBuffer class provides a pixel buffer which can be drawn upon with
-pixels, lines, rectangles, text and even other FrameBuffer's. It is useful
-when generating output for displays.
+pixels, lines, rectangles, ellipses, polygons, text and even other
+FrameBuffers. It is useful when generating output for displays.
 
 For example::
 
     import framebuf
 
     # FrameBuffer needs 2 bytes for every RGB565 pixel
-    fbuf = framebuf.FrameBuffer(bytearray(10 * 100 * 2), 10, 100, framebuf.RGB565)
+    fbuf = framebuf.FrameBuffer(bytearray(100 * 10 * 2), 100, 10, framebuf.RGB565)
 
     fbuf.fill(0)
     fbuf.text('MicroPython!', 0, 0, 0xffff)
-    fbuf.hline(0, 10, 96, 0xffff)
+    fbuf.hline(0, 9, 96, 0xffff)
 
 Constructors
 ------------
@@ -77,12 +77,37 @@ The following methods draw shapes onto the FrameBuffer.
     methods draw horizontal and vertical lines respectively up to
     a given length.
 
-.. method:: FrameBuffer.rect(x, y, w, h, c)
-.. method:: FrameBuffer.fill_rect(x, y, w, h, c)
+.. method:: FrameBuffer.rect(x, y, w, h, c[, f])
 
-    Draw a rectangle at the given location, size and color. The `rect`
-    method draws only a 1 pixel outline whereas the `fill_rect` method
-    draws both the outline and interior.
+    Draw a rectangle at the given location, size and color.
+
+    The optional *f* parameter can be set to ``True`` to fill the rectangle.
+    Otherwise just a one pixel outline is drawn.
+
+.. method:: FrameBuffer.ellipse(x, y, xr, yr, c[, f, m])
+
+    Draw an ellipse at the given location. Radii *xr* and *yr* define the
+    geometry; equal values cause a circle to be drawn. The *c* parameter
+    defines the color.
+
+    The optional *f* parameter can be set to ``True`` to fill the ellipse.
+    Otherwise just a one pixel outline is drawn.
+
+    The optional *m* parameter enables drawing to be restricted to certain
+    quadrants of the ellipse. The LS four bits determine which quadrants are
+    to be drawn, with bit 0 specifying Q1, b1 Q2, b2 Q3 and b3 Q4. Quadrants
+    are numbered counterclockwise with Q1 being top right.
+
+.. method:: FrameBuffer.poly(x, y, coords, c[, f])
+
+    Given a list of coordinates, draw an arbitrary (convex or concave) closed
+    polygon at the given x, y location using the given color.
+
+    The *coords* must be specified as a :mod:`array` of integers, e.g.
+    ``array('h', [x0, y0, x1, y1, ... xn, yn])``.
+
+    The optional *f* parameter can be set to ``True`` to fill the polygon.
+    Otherwise just a one pixel outline is drawn.
 
 Drawing text
 ------------
@@ -103,16 +128,25 @@ Other methods
     Shift the contents of the FrameBuffer by the given vector. This may
     leave a footprint of the previous colors in the FrameBuffer.
 
-.. method:: FrameBuffer.blit(fbuf, x, y[, key])
+.. method:: FrameBuffer.blit(fbuf, x, y, key=-1, palette=None)
 
     Draw another FrameBuffer on top of the current one at the given coordinates.
     If *key* is specified then it should be a color integer and the
     corresponding color will be considered transparent: all pixels with that
-    color value will not be drawn.
+    color value will not be drawn. (If the *palette* is specified then the *key*
+    is compared to the value from *palette*, not to the value directly from
+    *fbuf*.)
 
-    This method works between FrameBuffer instances utilising different formats,
-    but the resulting colors may be unexpected due to the mismatch in color
-    formats.
+    The *palette* argument enables blitting between FrameBuffers with differing
+    formats. Typical usage is to render a monochrome or grayscale glyph/icon to
+    a color display. The *palette* is a FrameBuffer instance whose format is
+    that of the current FrameBuffer. The *palette* height is one pixel and its
+    pixel width is the number of colors in the source FrameBuffer. The *palette*
+    for an N-bit source needs 2**N pixels; the *palette* for a monochrome source
+    would have 2 pixels representing background and foreground colors. The
+    application assigns a color to each pixel in the *palette*. The color of the
+    current pixel will be that of that *palette* pixel whose x position is the
+    color of the corresponding source pixel.
 
 Constants
 ---------

docs/library/hashlib.rst

@@ -1,7 +1,7 @@
-:mod:`uhashlib` -- hashing algorithms
-=====================================
+:mod:`hashlib` -- hashing algorithms
+====================================
 
-.. module:: uhashlib
+.. module:: hashlib
    :synopsis: hashing algorithms
 
 |see_cpython_module| :mod:`python:hashlib`.
@@ -27,15 +27,15 @@ be implemented:
 Constructors
 ------------
 
-.. class:: uhashlib.sha256([data])
+.. class:: hashlib.sha256([data])
 
     Create an SHA256 hasher object and optionally feed ``data`` into it.
 
-.. class:: uhashlib.sha1([data])
+.. class:: hashlib.sha1([data])
 
     Create an SHA1 hasher object and optionally feed ``data`` into it.
 
-.. class:: uhashlib.md5([data])
+.. class:: hashlib.md5([data])
 
     Create an MD5 hasher object and optionally feed ``data`` into it.
 
@@ -53,5 +53,5 @@ Methods
 
 .. method:: hash.hexdigest()
 
-   This method is NOT implemented. Use ``ubinascii.hexlify(hash.digest())``
+   This method is NOT implemented. Use ``binascii.hexlify(hash.digest())``
    to achieve a similar effect.

docs/library/heapq.rst

@@ -1,7 +1,7 @@
-:mod:`uheapq` -- heap queue algorithm
-=====================================
+:mod:`heapq` -- heap queue algorithm
+====================================
 
-.. module:: uheapq
+.. module:: heapq
    :synopsis: heap queue algorithm
 
 |see_cpython_module| :mod:`python:heapq`.
@@ -23,7 +23,7 @@ Functions
 
    Pop the first item from the ``heap``, and return it.  Raise ``IndexError`` if
    ``heap`` is empty.
-   
+
    The returned item will be the smallest item in the ``heap``.
 
 .. function:: heapify(x)

docs/library/index.rst

@@ -7,47 +7,39 @@ MicroPython libraries
 
    Important summary of this section
 
-   * MicroPython implements a subset of Python functionality for each module.
-   * To ease extensibility, MicroPython versions of standard Python modules
-     usually have ``u`` ("micro") prefix.
-   * Any particular MicroPython variant or port may miss any feature/function
-     described in this general documentation (due to resource constraints or
-     other limitations).
-
+   * MicroPython provides built-in modules that mirror the functionality of the
+     Python standard library (e.g. :mod:`os`, :mod:`time`), as well as
+     MicroPython-specific modules (e.g. :mod:`bluetooth`, :mod:`machine`).
+   * Most standard library modules implement a subset of the functionality of
+     the equivalent Python module, and in a few cases provide some
+     MicroPython-specific extensions (e.g. :mod:`array`, :mod:`os`)
+   * Due to resource constraints or other limitations, some ports or firmware
+     versions may not include all the functionality documented here.
+   * To allow for extensibility, the built-in modules can be extended from
+     Python code loaded onto the device.
 
 This chapter describes modules (function and class libraries) which are built
-into MicroPython. There are a few categories of such modules:
+into MicroPython. This documentation in general aspires to describe all modules
+and functions/classes which are implemented in the MicroPython project.
+However, MicroPython is highly configurable, and each port to a particular
+board/embedded system may include only a subset of the available MicroPython
+libraries.
 
-* Modules which implement a subset of standard Python functionality and are not
-  intended to be extended by the user.
-* Modules which implement a subset of Python functionality, with a provision
-  for extension by the user (via Python code).
-* Modules which implement MicroPython extensions to the Python standard libraries.
-* Modules specific to a particular :term:`MicroPython port` and thus not portable.
-
-Note about the availability of the modules and their contents: This documentation
-in general aspires to describe all modules and functions/classes which are
-implemented in MicroPython project. However, MicroPython is highly configurable, and
-each port to a particular board/embedded system makes available only a subset
-of MicroPython libraries. For officially supported ports, there is an effort
-to either filter out non-applicable items, or mark individual descriptions
-with "Availability:" clauses describing which ports provide a given feature.
-
-With that in mind, please still be warned that some functions/classes
-in a module (or even the entire module) described in this documentation **may be
-unavailable** in a particular build of MicroPython on a particular system. The
-best place to find general information of the availability/non-availability
-of a particular feature is the "General Information" section which contains
-information pertaining to a specific :term:`MicroPython port`.
+With that in mind, please be warned that some functions/classes in a module (or
+even the entire module) described in this documentation **may be unavailable**
+in a particular build of MicroPython on a particular system. The best place to
+find general information of the availability/non-availability of a particular
+feature is the "General Information" section which contains information
+pertaining to a specific :term:`MicroPython port`.
 
 On some ports you are able to discover the available, built-in libraries that
-can be imported by entering the following at the REPL::
+can be imported by entering the following at the :term:`REPL`::
 
     help('modules')
 
 Beyond the built-in libraries described in this documentation, many more
 modules from the Python standard library, as well as further MicroPython
-extensions to it, can be found in `micropython-lib`.
+extensions to it, can be found in :term:`micropython-lib`.
 
 Python standard libraries and micro-libraries
 ---------------------------------------------
@@ -55,46 +47,34 @@ Python standard libraries and micro-libraries
 The following standard Python libraries have been "micro-ified" to fit in with
 the philosophy of MicroPython.  They provide the core functionality of that
 module and are intended to be a drop-in replacement for the standard Python
-library.  Some modules below use a standard Python name, but prefixed with "u",
-e.g. ``ujson`` instead of ``json``. This is to signify that such a module is
-micro-library, i.e. implements only a subset of CPython module functionality.
-By naming them differently, a user has a choice to write a Python-level module
-to extend functionality for better compatibility with CPython (indeed, this is
-what done by the `micropython-lib` project mentioned above).
-
-On some embedded platforms, where it may be cumbersome to add Python-level
-wrapper modules to achieve naming compatibility with CPython, micro-modules
-are available both by their u-name, and also by their non-u-name.  The
-non-u-name can be overridden by a file of that name in your library path (``sys.path``).
-For example, ``import json`` will first search for a file ``json.py`` (or package
-directory ``json``) and load that module if it is found.  If nothing is found,
-it will fallback to loading the built-in ``ujson`` module.
+library.
 
 .. toctree::
    :maxdepth: 1
 
+   array.rst
+   binascii.rst
    builtins.rst
    cmath.rst
+   collections.rst
+   errno.rst
    gc.rst
+   hashlib.rst
+   heapq.rst
+   io.rst
+   json.rst
    math.rst
-   uarray.rst
+   os.rst
+   random.rst
+   re.rst
+   select.rst
+   socket.rst
+   ssl.rst
+   struct.rst
+   sys.rst
+   time.rst
    uasyncio.rst
-   ubinascii.rst
-   ucollections.rst
-   uerrno.rst
-   uhashlib.rst
-   uheapq.rst
-   uio.rst
-   ujson.rst
-   uos.rst
-   ure.rst
-   uselect.rst
-   usocket.rst
-   ussl.rst
-   ustruct.rst
-   usys.rst
-   utime.rst
-   uzlib.rst
+   zlib.rst
    _thread.rst
 
 
@@ -107,15 +87,23 @@ the following libraries.
 .. toctree::
    :maxdepth: 1
 
+   bluetooth.rst
    btree.rst
+   cryptolib.rst
    framebuf.rst
    machine.rst
    micropython.rst
+   neopixel.rst
    network.rst
-   ubluetooth.rst
-   ucryptolib.rst
    uctypes.rst
 
+The following libraries provide drivers for hardware components.
+
+.. toctree::
+  :maxdepth: 1
+
+  wm8960.rst
+
 
 Port-specific libraries
 -----------------------
@@ -131,7 +119,7 @@ To access platform-specific hardware use the appropriate library, e.g.
 
 
 Libraries specific to the pyboard
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following libraries are specific to the pyboard.
 
@@ -139,11 +127,12 @@ The following libraries are specific to the pyboard.
   :maxdepth: 2
 
   pyb.rst
+  stm.rst
   lcd160cr.rst
 
 
 Libraries specific to the WiPy
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following libraries and classes are specific to the WiPy.
 
@@ -156,7 +145,7 @@ The following libraries and classes are specific to the WiPy.
 
 
 Libraries specific to the ESP8266 and ESP32
--------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following libraries are specific to the ESP8266 and ESP32.
 
@@ -168,7 +157,7 @@ The following libraries are specific to the ESP8266 and ESP32.
 
 
 Libraries specific to the RP2040
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following libraries are specific to the RP2040, as used in the Raspberry Pi Pico.
 
@@ -176,3 +165,34 @@ The following libraries are specific to the RP2040, as used in the Raspberry Pi
   :maxdepth: 2
 
   rp2.rst
+
+Libraries specific to Zephyr
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following libraries are specific to the Zephyr port.
+
+.. toctree::
+  :maxdepth: 2
+
+  zephyr.rst
+
+Extending built-in libraries from Python
+----------------------------------------
+
+In most cases, the above modules are actually named ``umodule`` rather than
+``module``, but MicroPython will alias any module prefixed with a ``u`` to the
+non-``u`` version. However a file (or :term:`frozen module`) named
+``module.py`` will take precedence over this alias.
+
+This allows the user to provide an extended implementation of a built-in library
+(perhaps to provide additional CPython compatibility). The user-provided module
+(in ``module.py``) can still use the built-in functionality by importing
+``umodule`` directly. This is used extensively in :term:`micropython-lib`. See
+:ref:`packages` for more information.
+
+This applies to both the Python standard libraries (e.g. ``os``, ``time``, etc),
+but also the MicroPython libraries too (e.g. ``machine``, ``bluetooth``, etc).
+The main exception is the port-specific libraries (``pyb``, ``esp``, etc).
+
+*Other than when you specifically want to force the use of the built-in module,
+we recommend always using* ``import module`` *rather than* ``import umodule``.

docs/library/io.rst

@@ -1,7 +1,7 @@
-:mod:`uio` -- input/output streams
-==================================
+:mod:`io` -- input/output streams
+=================================
 
-.. module:: uio
+.. module:: io
    :synopsis: input/output streams
 
 |see_cpython_module| :mod:`python:io`.

docs/library/json.rst

@@ -1,7 +1,7 @@
-:mod:`ujson` -- JSON encoding and decoding
-==========================================
+:mod:`json` -- JSON encoding and decoding
+=========================================
 
-.. module:: ujson
+.. module:: json
    :synopsis: JSON encoding and decoding
 
 |see_cpython_module| :mod:`python:json`.
@@ -12,14 +12,20 @@ data format.
 Functions
 ---------
 
-.. function:: dump(obj, stream)
+.. function:: dump(obj, stream, separators=None)
 
    Serialise *obj* to a JSON string, writing it to the given *stream*.
 
-.. function:: dumps(obj)
+   If specified, separators should be an ``(item_separator, key_separator)``
+   tuple. The default is ``(', ', ': ')``. To get the most compact JSON
+   representation, you should specify ``(',', ':')`` to eliminate whitespace.
+
+.. function:: dumps(obj, separators=None)
 
    Return *obj* represented as a JSON string.
 
+   The arguments have the same meaning as in `dump`.
+
 .. function:: load(stream)
 
    Parse the given *stream*, interpreting it as a JSON string and

docs/library/lcd160cr.rst

@@ -313,7 +313,7 @@ Advanced commands
     specified by :meth:`LCD160CR.set_spi_win`, starting from the top-left corner.
 
     The `framebuf <framebuf.html>`_ module can be used to construct frame buffers
-    and provides drawing primitives. Using a frame buffer will improve 
+    and provides drawing primitives. Using a frame buffer will improve
     performance of animations when compared to drawing directly to the screen.
 
 .. method:: LCD160CR.set_scroll(on)

docs/library/machine.ADC.rst

@@ -8,28 +8,59 @@ The ADC class provides an interface to analog-to-digital convertors, and
 represents a single endpoint that can sample a continuous voltage and
 convert it to a discretised value.
 
+For extra control over ADC sampling see :ref:`machine.ADCBlock <machine.ADCBlock>`.
+
 Example usage::
 
-   import machine
+   from machine import ADC
 
-   adc = machine.ADC(pin)   # create an ADC object acting on a pin
-   val = adc.read_u16()     # read a raw analog value in the range 0-65535
+   adc = ADC(pin)        # create an ADC object acting on a pin
+   val = adc.read_u16()  # read a raw analog value in the range 0-65535
+   val = adc.read_uv()   # read an analog value in microvolts
 
 Constructors
 ------------
 
-.. class:: ADC(id)
+.. class:: ADC(id, *, sample_ns, atten)
 
    Access the ADC associated with a source identified by *id*.  This
    *id* may be an integer (usually specifying a channel number), a
    :ref:`Pin <machine.Pin>` object, or other value supported by the
    underlying machine.
 
+   If additional keyword-arguments are given then they will configure
+   various aspects of the ADC.  If not given, these settings will take
+   previous or default values.  The settings are:
+
+     - *sample_ns* is the sampling time in nanoseconds.
+
+     - *atten* specifies the input attenuation.
+
 Methods
 -------
 
+.. method:: ADC.init(*, sample_ns, atten)
+
+   Apply the given settings to the ADC.  Only those arguments that are
+   specified will be changed.  See the ADC constructor above for what the
+   arguments are.
+
+.. method:: ADC.block()
+
+   Return the :ref:`ADCBlock <machine.ADCBlock>` instance associated with
+   this ADC object.
+
+   This method only exists if the port supports the
+   :ref:`ADCBlock <machine.ADCBlock>` class.
+
 .. method:: ADC.read_u16()
 
    Take an analog reading and return an integer in the range 0-65535.
    The return value represents the raw reading taken by the ADC, scaled
    such that the minimum value is 0 and the maximum value is 65535.
+
+.. method:: ADC.read_uv()
+
+   Take an analog reading and return an integer value with units of
+   microvolts.  It is up to the particular port whether or not this value
+   is calibrated, and how calibration is done.

docs/library/machine.ADCBlock.rst

@@ -0,0 +1,58 @@
+.. currentmodule:: machine
+.. _machine.ADCBlock:
+
+class ADCBlock -- control ADC peripherals
+=========================================
+
+The ADCBlock class provides access to an ADC peripheral which has a
+number of channels that can be used to sample analog values.  It allows
+finer control over configuration of :ref:`machine.ADC <machine.ADC>`
+objects, which do the actual sampling.
+
+This class is not always available.
+
+Example usage::
+
+   from machine import ADCBlock
+
+   block = ADCBlock(id, bits=12)  # create an ADCBlock with 12-bit resolution
+   adc = block.connect(4, pin)    # connect channel 4 to the given pin
+   val = adc.read_uv()            # read an analog value
+
+Constructors
+------------
+
+.. class:: ADCBlock(id, *, bits)
+
+   Access the ADC peripheral identified by *id*, which may be an integer
+   or string.
+   
+   The *bits* argument, if given, sets the resolution in bits of the
+   conversion process.  If not specified then the previous or default
+   resolution is used.
+
+Methods
+-------
+
+.. method:: ADCBlock.init(*, bits)
+
+   Configure the ADC peripheral.  *bits* will set the resolution of the
+   conversion process.
+
+.. method:: ADCBlock.connect(channel)
+            ADCBlock.connect(source)
+            ADCBlock.connect(channel, source)
+
+   Connect up a channel on the ADC peripheral so it is ready for sampling,
+   and return an :ref:`ADC <machine.ADC>` object that represents that connection.
+
+   The *channel* argument must be an integer, and *source* must be an object
+   (for example a :ref:`Pin <machine.Pin>`) which can be connected up for sampling.
+
+   If only *channel* is given then it is configured for sampling.
+
+   If only *source* is given then that object is connected to a default
+   channel ready for sampling.
+
+   If both *channel* and *source* are given then they are connected together
+   and made ready for sampling.

docs/library/machine.ADCWiPy.rst

@@ -27,13 +27,13 @@ Constructors
    Create an ADC object associated with the given pin.
    This allows you to then read analog values on that pin.
    For more info check the `pinout and alternate functions
-   table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ 
+   table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_
 
-   .. warning:: 
+   .. warning::
 
-      ADC pin input range is 0-1.4V (being 1.8V the absolute maximum that it 
-      can withstand). When GP2, GP3, GP4 or GP5 are remapped to the 
-      ADC block, 1.8 V is the maximum. If these pins are used in digital mode, 
+      ADC pin input range is 0-1.4V (being 1.8V the absolute maximum that it
+      can withstand). When GP2, GP3, GP4 or GP5 are remapped to the
+      ADC block, 1.8 V is the maximum. If these pins are used in digital mode,
       then the maximum allowed input is 3.6V.
 
 Methods

docs/library/machine.I2C.rst

@@ -20,6 +20,17 @@ Software I2C is implemented by bit-banging and can be used on any pin but is not
 as efficient.  These classes have the same methods available and differ primarily
 in the way they are constructed.
 
+.. Note::
+
+   The I2C bus requires pull-up circuitry on both SDA and SCL for it's operation.
+   Usually these are resistors in the range of 1 - 10 kOhm, connected from each SDA/SCL
+   to Vcc. Without these, the behaviour is undefined and may range from blocking,
+   unexpected watchdog reset to just wrong values. Often, this pull-up circuitry
+   is built-in already to the MCU board or sensor breakout boards, but there is
+   no rule for that. So please check in case of trouble. See also this excellent
+   `learning guide <https://learn.adafruit.com/working-with-i2c-devices/pull-up-resistors>`_
+   by Adafruit about I2C wiring.
+
 Example usage::
 
     from machine import I2C
@@ -28,20 +39,20 @@ Example usage::
                                     # depending on the port, extra parameters may be required
                                     # to select the peripheral and/or pins to use
 
-    i2c.scan()                      # scan for slaves, returning a list of 7-bit addresses
+    i2c.scan()                      # scan for peripherals, returning a list of 7-bit addresses
 
-    i2c.writeto(42, b'123')         # write 3 bytes to slave with 7-bit address 42
-    i2c.readfrom(42, 4)             # read 4 bytes from slave with 7-bit address 42
+    i2c.writeto(42, b'123')         # write 3 bytes to peripheral with 7-bit address 42
+    i2c.readfrom(42, 4)             # read 4 bytes from peripheral with 7-bit address 42
 
-    i2c.readfrom_mem(42, 8, 3)      # read 3 bytes from memory of slave 42,
-                                    #   starting at memory-address 8 in the slave
-    i2c.writeto_mem(42, 2, b'\x10') # write 1 byte to memory of slave 42
-                                    #   starting at address 2 in the slave
+    i2c.readfrom_mem(42, 8, 3)      # read 3 bytes from memory of peripheral 42,
+                                    #   starting at memory-address 8 in the peripheral
+    i2c.writeto_mem(42, 2, b'\x10') # write 1 byte to memory of peripheral 42
+                                    #   starting at address 2 in the peripheral
 
 Constructors
 ------------
 
-.. class:: I2C(id, *, scl, sda, freq=400000)
+.. class:: I2C(id, *, scl, sda, freq=400000, timeout=50000)
 
    Construct and return a new I2C object using the following parameters:
 
@@ -51,13 +62,15 @@ Constructors
       - *sda* should be a pin object specifying the pin to use for SDA.
       - *freq* should be an integer which sets the maximum frequency
         for SCL.
+      - *timeout* is the maximum time in microseconds to allow for I2C
+        transactions.  This parameter is not allowed on some ports.
 
    Note that some ports/boards will have default values of *scl* and *sda*
    that can be changed in this constructor.  Others will have fixed values
    of *scl* and *sda* that cannot be changed.
 
 .. _machine.SoftI2C:
-.. class:: SoftI2C(scl, sda, *, freq=400000, timeout=255)
+.. class:: SoftI2C(scl, sda, *, freq=400000, timeout=50000)
 
    Construct a new software I2C object.  The parameters are:
 
@@ -80,6 +93,10 @@ General Methods
      - *sda* is a pin object for the SDA line
      - *freq* is the SCL clock rate
 
+   In the case of hardware I2C the actual clock frequency may be lower than the
+   requested frequency. This is dependant on the platform hardware. The actual
+   rate may be determined by printing the I2C object.
+
 .. method:: I2C.deinit()
 
    Turn off the I2C bus.
@@ -95,7 +112,7 @@ General Methods
 Primitive I2C operations
 ------------------------
 
-The following methods implement the primitive I2C master bus operations and can
+The following methods implement the primitive I2C controller bus operations and can
 be combined to make any I2C transaction.  They are provided if you need more
 control over the bus, otherwise the standard methods (see below) can be used.
 
@@ -115,7 +132,7 @@ These methods are only available on the `machine.SoftI2C` class.
    read is the length of *buf*.  An ACK will be sent on the bus after
    receiving all but the last byte.  After the last byte is received, if *nack*
    is true then a NACK will be sent, otherwise an ACK will be sent (and in this
-   case the slave assumes more bytes are going to be read in a later call).
+   case the peripheral assumes more bytes are going to be read in a later call).
 
 .. method:: I2C.write(buf)
 
@@ -126,18 +143,18 @@ These methods are only available on the `machine.SoftI2C` class.
 Standard bus operations
 -----------------------
 
-The following methods implement the standard I2C master read and write
-operations that target a given slave device.
+The following methods implement the standard I2C controller read and write
+operations that target a given peripheral device.
 
 .. method:: I2C.readfrom(addr, nbytes, stop=True, /)
 
-   Read *nbytes* from the slave specified by *addr*.
+   Read *nbytes* from the peripheral specified by *addr*.
    If *stop* is true then a STOP condition is generated at the end of the transfer.
    Returns a `bytes` object with the data read.
 
 .. method:: I2C.readfrom_into(addr, buf, stop=True, /)
 
-   Read into *buf* from the slave specified by *addr*.
+   Read into *buf* from the peripheral specified by *addr*.
    The number of bytes read will be the length of *buf*.
    If *stop* is true then a STOP condition is generated at the end of the transfer.
 
@@ -145,7 +162,7 @@ operations that target a given slave device.
 
 .. method:: I2C.writeto(addr, buf, stop=True, /)
 
-   Write the bytes from *buf* to the slave specified by *addr*.  If a
+   Write the bytes from *buf* to the peripheral specified by *addr*.  If a
    NACK is received following the write of a byte from *buf* then the
    remaining bytes are not sent.  If *stop* is true then a STOP condition is
    generated at the end of the transfer, even if a NACK is received.
@@ -153,7 +170,7 @@ operations that target a given slave device.
 
 .. method:: I2C.writevto(addr, vector, stop=True, /)
 
-   Write the bytes contained in *vector* to the slave specified by *addr*.
+   Write the bytes contained in *vector* to the peripheral specified by *addr*.
    *vector* should be a tuple or list of objects with the buffer protocol.
    The *addr* is sent once and then the bytes from each object in *vector*
    are written out sequentially.  The objects in *vector* may be zero bytes
@@ -170,19 +187,19 @@ Memory operations
 
 Some I2C devices act as a memory device (or set of registers) that can be read
 from and written to.  In this case there are two addresses associated with an
-I2C transaction: the slave address and the memory address.  The following
+I2C transaction: the peripheral address and the memory address.  The following
 methods are convenience functions to communicate with such devices.
 
 .. method:: I2C.readfrom_mem(addr, memaddr, nbytes, *, addrsize=8)
 
-   Read *nbytes* from the slave specified by *addr* starting from the memory
+   Read *nbytes* from the peripheral specified by *addr* starting from the memory
    address specified by *memaddr*.
    The argument *addrsize* specifies the address size in bits.
    Returns a `bytes` object with the data read.
 
 .. method:: I2C.readfrom_mem_into(addr, memaddr, buf, *, addrsize=8)
 
-   Read into *buf* from the slave specified by *addr* starting from the
+   Read into *buf* from the peripheral specified by *addr* starting from the
    memory address specified by *memaddr*.  The number of bytes read is the
    length of *buf*.
    The argument *addrsize* specifies the address size in bits (on ESP8266
@@ -192,7 +209,7 @@ methods are convenience functions to communicate with such devices.
 
 .. method:: I2C.writeto_mem(addr, memaddr, buf, *, addrsize=8)
 
-   Write *buf* to the slave specified by *addr* starting from the
+   Write *buf* to the peripheral specified by *addr* starting from the
    memory address specified by *memaddr*.
    The argument *addrsize* specifies the address size in bits (on ESP8266
    this argument is not recognised and the address size is always 8 bits).

docs/library/machine.I2S.rst

@@ -0,0 +1,166 @@
+.. currentmodule:: machine
+.. _machine.I2S:
+
+class I2S -- Inter-IC Sound bus protocol
+========================================
+
+I2S is a synchronous serial protocol used to connect digital audio devices.
+At the physical level, a bus consists of 3 lines: SCK, WS, SD.
+The I2S class supports controller operation.  Peripheral operation is not supported.
+
+The I2S class is currently available as a Technical Preview.  During the preview period, feedback from
+users is encouraged.  Based on this feedback, the I2S class API and implementation may be changed.
+
+I2S objects can be created and initialized using::
+
+    from machine import I2S
+    from machine import Pin
+
+    # ESP32
+    sck_pin = Pin(14)   # Serial clock output
+    ws_pin = Pin(13)    # Word clock output
+    sd_pin = Pin(12)    # Serial data output
+
+    or
+
+    # PyBoards
+    sck_pin = Pin("Y6")   # Serial clock output
+    ws_pin = Pin("Y5")    # Word clock output
+    sd_pin = Pin("Y8")    # Serial data output
+
+    audio_out = I2S(2,
+                    sck=sck_pin, ws=ws_pin, sd=sd_pin,
+                    mode=I2S.TX,
+                    bits=16,
+                    format=I2S.MONO,
+                    rate=44100,
+                    ibuf=20000)
+
+    audio_in = I2S(2,
+                   sck=sck_pin, ws=ws_pin, sd=sd_pin,
+                   mode=I2S.RX,
+                   bits=32,
+                   format=I2S.STEREO,
+                   rate=22050,
+                   ibuf=20000)
+
+3 modes of operation are supported:
+ - blocking
+ - non-blocking
+ - uasyncio
+
+blocking::
+
+   num_written = audio_out.write(buf) # blocks until buf emptied
+
+   num_read = audio_in.readinto(buf) # blocks until buf filled
+
+non-blocking::
+
+   audio_out.irq(i2s_callback)         # i2s_callback is called when buf is emptied
+   num_written = audio_out.write(buf)  # returns immediately
+
+   audio_in.irq(i2s_callback)          # i2s_callback is called when buf is filled
+   num_read = audio_in.readinto(buf)   # returns immediately
+
+uasyncio::
+
+   swriter = uasyncio.StreamWriter(audio_out)
+   swriter.write(buf)
+   await swriter.drain()
+
+   sreader = uasyncio.StreamReader(audio_in)
+   num_read = await sreader.readinto(buf)
+
+Some codec devices like the WM8960 or SGTL5000 require separate initialization
+before they can operate with the I2S class.  For these, separate drivers are
+supplied, which also offer methods for controlling volume, audio processing and
+other things.  For these drivers see:
+
+- :ref:`wm8960`
+
+Constructor
+-----------
+
+.. class:: I2S(id, *, sck, ws, sd, mck=None, mode, bits, format, rate, ibuf)
+
+   Construct an I2S object of the given id:
+
+   - ``id`` identifies a particular I2S bus; it is board and port specific
+
+   Keyword-only parameters that are supported on all ports:
+
+     - ``sck`` is a pin object for the serial clock line
+     - ``ws`` is a pin object for the word select line
+     - ``sd`` is a pin object for the serial data line
+     - ``mck`` is a pin object for the master clock line;
+       master clock frequency is sampling rate * 256
+     - ``mode`` specifies receive or transmit
+     - ``bits`` specifies sample size (bits), 16 or 32
+     - ``format`` specifies channel format, STEREO or MONO
+     - ``rate`` specifies audio sampling rate (Hz);
+       this is the frequency of the ``ws`` signal
+     - ``ibuf`` specifies internal buffer length (bytes)
+
+   For all ports, DMA runs continuously in the background and allows user applications to perform other operations while
+   sample data is transfered between the internal buffer and the I2S peripheral unit.
+   Increasing the size of the internal buffer has the potential to increase the time that user applications can perform non-I2S operations
+   before underflow (e.g. ``write`` method) or overflow (e.g. ``readinto`` method).
+
+Methods
+-------
+
+.. method:: I2S.init(sck, ...)
+
+  see Constructor for argument descriptions
+
+.. method:: I2S.deinit()
+
+  Deinitialize the I2S bus
+
+.. method::  I2S.readinto(buf)
+
+  Read audio samples into the buffer specified by ``buf``.  ``buf`` must support the buffer protocol, such as bytearray or array.
+  "buf" byte ordering is little-endian.  For Stereo format, left channel sample precedes right channel sample. For Mono format,
+  the left channel sample data is used.
+  Returns number of bytes read
+
+.. method::  I2S.write(buf)
+
+  Write audio samples contained in ``buf``. ``buf`` must support the buffer protocol, such as bytearray or array.
+  "buf" byte ordering is little-endian.  For Stereo format, left channel sample precedes right channel sample. For Mono format,
+  the sample data is written to both the right and left channels.
+  Returns number of bytes written
+
+.. method::  I2S.irq(handler)
+
+  Set a callback. ``handler`` is called when ``buf`` is emptied (``write`` method) or becomes full (``readinto`` method).
+  Setting a callback changes the ``write`` and ``readinto`` methods to non-blocking operation.
+  ``handler`` is called in the context of the MicroPython scheduler.
+
+.. staticmethod::  I2S.shift(*, buf, bits, shift)
+
+  bitwise shift of all samples contained in ``buf``. ``bits`` specifies sample size in bits. ``shift`` specifies the number of bits to shift each sample.
+  Positive for left shift, negative for right shift.
+  Typically used for volume control.  Each bit shift changes sample volume by 6dB.
+
+Constants
+---------
+
+.. data:: I2S.RX
+
+   for initialising the I2S bus ``mode`` to receive
+
+.. data:: I2S.TX
+
+   for initialising the I2S bus ``mode`` to transmit
+
+.. data:: I2S.STEREO
+
+   for initialising the I2S bus ``format`` to stereo
+
+.. data:: I2S.MONO
+
+   for initialising the I2S bus ``format`` to mono
+
+

docs/library/machine.PWM.rst

@@ -23,7 +23,7 @@ Example usage::
 Constructors
 ------------
 
-.. class:: PWM(dest, \*, freq, duty_u16, duty_ns)
+.. class:: PWM(dest, *, freq, duty_u16, duty_ns)
 
    Construct and return a new PWM object using the following parameters:
 
@@ -42,7 +42,7 @@ Constructors
 Methods
 -------
 
-.. method:: PWM.init(\*, freq, duty_u16, duty_ns)
+.. method:: PWM.init(*, freq, duty_u16, duty_ns)
 
    Modify settings for the PWM object.  See the above constructor for details
    about the parameters.
@@ -77,3 +77,46 @@ Methods
    With no arguments the pulse width in nanoseconds is returned.
 
    With a single *value* argument the pulse width is set to that value.
+
+Specific PWM class implementations
+----------------------------------
+
+The following concrete class(es) implement enhancements to the PWM class.
+
+   | :ref:`pyb.Timer for PyBoard <pyb.Timer>`  
+
+Limitations of PWM
+------------------
+
+* Not all frequencies can be generated with absolute accuracy due to
+  the discrete nature of the computing hardware.  Typically the PWM frequency
+  is obtained by dividing some integer base frequency by an integer divider.
+  For example, if the base frequency is 80MHz and the required PWM frequency is
+  300kHz the divider must be a non-integer number 80000000 / 300000 = 266.67.
+  After rounding the divider is set to 267 and the PWM frequency will be
+  80000000 / 267 = 299625.5 Hz, not 300kHz.  If the divider is set to 266 then
+  the PWM frequency will be 80000000 / 266 = 300751.9 Hz, but again not 300kHz.
+
+  Some ports like the RP2040 one use a fractional divider, which allow a finer
+  granularity of the frequency at higher frequencies by switching the PWM
+  pulse duration between two adjacent values, such that the resulting average
+  frequency is more close to the intended one, at the cost of spectral purity. 
+
+* The duty cycle has the same discrete nature and its absolute accuracy is not
+  achievable.  On most hardware platforms the duty will be applied at the next
+  frequency period.  Therefore, you should wait more than "1/frequency" before
+  measuring the duty.
+
+* The frequency and the duty cycle resolution are usually interdependent.
+  The higher the PWM frequency the lower the duty resolution which is available,
+  and vice versa. For example, a 300kHz PWM frequency can have a duty cycle
+  resolution of 8 bit, not 16-bit as may be expected.  In this case, the lowest
+  8 bits of *duty_u16* are insignificant. So::
+
+    pwm=PWM(Pin(13), freq=300_000, duty_u16=2**16//2)
+
+  and::
+
+    pwm=PWM(Pin(13), freq=300_000, duty_u16=2**16//2 + 255)
+
+  will generate PWM with the same 50% duty cycle.

docs/library/machine.Pin.rst

@@ -42,7 +42,7 @@ Usage Model::
 Constructors
 ------------
 
-.. class:: Pin(id, mode=-1, pull=-1, *, value, drive, alt)
+.. class:: Pin(id, mode=-1, pull=-1, *, value=None, drive=0, alt=-1)
 
    Access the pin peripheral (GPIO pin) associated with the given ``id``.  If
    additional arguments are given in the constructor then they are used to initialise
@@ -74,6 +74,8 @@ Constructors
        - ``Pin.ALT_OPEN_DRAIN`` - The Same as ``Pin.ALT``, but the pin is configured as
          open-drain.  Not all ports implement this mode.
 
+       - ``Pin.ANALOG`` - Pin is configured for analog input, see the :class:`ADC` class.
+
      - ``pull`` specifies if the pin has a (weak) pull resistor attached, and can be
        one of:
 
@@ -85,9 +87,9 @@ Constructors
        output pin value if given, otherwise the state of the pin peripheral remains
        unchanged.
 
-     - ``drive`` specifies the output power of the pin and can be one of: ``Pin.LOW_POWER``,
-       ``Pin.MED_POWER`` or ``Pin.HIGH_POWER``.  The actual current driving capabilities
-       are port dependent.  Not all ports implement this argument.
+     - ``drive`` specifies the output power of the pin and can be one of: ``Pin.DRIVE_0``,
+       ``Pin.DRIVE_1``, etc., increasing in drive strength.  The actual current driving
+       capabilities are port dependent.  Not all ports implement this argument.
 
      - ``alt`` specifies an alternate function for the pin and the values it can take are
        port dependent.  This argument is valid only for ``Pin.ALT`` and ``Pin.ALT_OPEN_DRAIN``
@@ -106,7 +108,7 @@ Constructors
 Methods
 -------
 
-.. method:: Pin.init(mode=-1, pull=-1, *, value, drive, alt)
+.. method:: Pin.init(mode=-1, pull=-1, *, value=None, drive=0, alt=-1)
 
    Re-initialise the pin using the given parameters.  Only those arguments that
    are specified will be set.  The rest of the pin peripheral state will remain
@@ -247,6 +249,7 @@ not all constants are available on all ports.
           Pin.OPEN_DRAIN
           Pin.ALT
           Pin.ALT_OPEN_DRAIN
+          Pin.ANALOG
 
    Selects the pin mode.
 
@@ -257,11 +260,13 @@ not all constants are available on all ports.
    Selects whether there is a pull up/down resistor.  Use the value
    ``None`` for no pull.
 
-.. data:: Pin.LOW_POWER
-          Pin.MED_POWER
-          Pin.HIGH_POWER
+.. data:: Pin.DRIVE_0
+          Pin.DRIVE_1
+          Pin.DRIVE_2
 
-   Selects the pin drive strength.
+   Selects the pin drive strength.  A port may define additional drive
+   constants with increasing number corresponding to increasing drive
+   strength.
 
 .. data:: Pin.IRQ_FALLING
           Pin.IRQ_RISING

docs/library/machine.SD.rst

@@ -32,7 +32,7 @@ Constructors
 
 .. class:: SD(id,... )
 
-   Create a SD card object. See ``init()`` for parameters if initialization. 
+   Create a SD card object. See ``init()`` for parameters if initialization.
 
 Methods
 -------

docs/library/machine.SDCard.rst

@@ -27,10 +27,10 @@ vary from platform to platform.
 
     This class provides access to SD or MMC storage cards using either
     a dedicated SD/MMC interface hardware or through an SPI channel.
-    The class implements the block protocol defined by :class:`uos.AbstractBlockDev`.
+    The class implements the block protocol defined by :class:`os.AbstractBlockDev`.
     This allows the mounting of an SD card to be as simple as::
 
-      uos.mount(machine.SDCard(), "/sd")
+      os.mount(machine.SDCard(), "/sd")
 
     The constructor takes the following parameters:
 
@@ -50,7 +50,7 @@ vary from platform to platform.
      - *mosi* can be used to specify an SPI mosi pin.
 
      - *cs* can be used to specify an SPI chip select pin.
-     
+
      - *freq* selects the SD/MMC interface frequency in Hz (only supported on the ESP32).
 
 Implementation-specific details
@@ -122,3 +122,46 @@ You can set the pins used for SPI access by passing a tuple as the
 
 *Note:* The current cc3200 SD card implementation names the this class
 :class:`machine.SD` rather than :class:`machine.SDCard` .
+
+mimxrt
+``````
+
+The SDCard module for the mimxrt port only supports access via dedicated SD/MMC
+peripheral (USDHC) in 4-bit mode with 50MHz clock frequency exclusively.
+Unfortunately the MIMXRT1011 controller does not support the USDHC peripheral.
+Hence this controller does not feature the ``machine.SDCard`` module.
+
+Due to the decision to only support 4-bit mode with 50MHz clock frequency the
+interface has been simplified, and the constructor signature is:
+
+.. class:: SDCard(slot=1)
+  :noindex:
+
+The pins used for the USDHC peripheral have to be configured in ``mpconfigboard.h``.
+Most of the controllers supported by the mimxrt port provide up to two USDHC
+peripherals.  Therefore the pin configuration is performed using the macro
+``MICROPY_USDHCx`` with x being 1 or 2 respectively.
+
+The following shows an example configuration for USDHC1::
+
+  #define MICROPY_USDHC1 \
+    { \
+          .cmd   = { GPIO_SD_B0_02_USDHC1_CMD}, \
+          .clk   = { GPIO_SD_B0_03_USDHC1_CLK }, \
+          .cd_b  = { GPIO_SD_B0_06_USDHC1_CD_B },\
+          .data0 = { GPIO_SD_B0_04_USDHC1_DATA0 },\
+          .data1 = { GPIO_SD_B0_05_USDHC1_DATA1 },\
+          .data2 = { GPIO_SD_B0_00_USDHC1_DATA2 },\
+          .data3 = { GPIO_SD_B0_01_USDHC1_DATA3 },\
+    }
+
+If the card detect pin is not used (cb_b pin) then the respective entry has to be
+filled with the following dummy value::
+
+  #define USDHC_DUMMY_PIN NULL , 0
+
+Based on the definition of macro ``MICROPY_USDHC1`` and/or ``MICROPY_USDHC2``
+the ``machine.SDCard`` module either supports one or two slots.  If only one of
+the defines is provided, calling ``machine.SDCard()`` or ``machine.SDCard(1)``
+will return an instance using the respective USDHC peripheral.  When both macros
+are defined, calling ``machine.SDCard(2)`` returns an instance using USDHC2.

docs/library/machine.SPI.rst

@@ -1,14 +1,14 @@
 .. currentmodule:: machine
 .. _machine.SPI:
 
-class SPI -- a Serial Peripheral Interface bus protocol (master side)
-=====================================================================
+class SPI -- a Serial Peripheral Interface bus protocol (controller side)
+=========================================================================
 
-SPI is a synchronous serial protocol that is driven by a master. At the
+SPI is a synchronous serial protocol that is driven by a controller. At the
 physical level, a bus consists of 3 lines: SCK, MOSI, MISO. Multiple devices
 can share the same bus. Each device should have a separate, 4th signal,
-SS (Slave Select), to select a particular device on a bus with which
-communication takes place. Management of an SS signal should happen in
+CS (Chip Select), to select a particular device on a bus with which
+communication takes place. Management of a CS signal should happen in
 user code (via machine.Pin class).
 
 Both hardware and software SPI implementations exist via the
@@ -19,6 +19,42 @@ Software SPI is implemented by bit-banging and can be used on any pin but
 is not as efficient.  These classes have the same methods available and
 differ primarily in the way they are constructed.
 
+Example usage::
+
+    from machine import SPI, Pin
+
+    spi = SPI(0, baudrate=400000)           # Create SPI peripheral 0 at frequency of 400kHz.
+                                            # Depending on the use case, extra parameters may be required
+                                            # to select the bus characteristics and/or pins to use.
+    cs = Pin(4, mode=Pin.OUT, value=1)      # Create chip-select on pin 4.
+
+    try:
+        cs(0)                               # Select peripheral.
+        spi.write(b"12345678")              # Write 8 bytes, and don't care about received data.
+    finally:
+        cs(1)                               # Deselect peripheral.
+
+    try:
+        cs(0)                               # Select peripheral.
+        rxdata = spi.read(8, 0x42)          # Read 8 bytes while writing 0x42 for each byte.
+    finally:
+        cs(1)                               # Deselect peripheral.
+
+    rxdata = bytearray(8)
+    try:
+        cs(0)                               # Select peripheral.
+        spi.readinto(rxdata, 0x42)          # Read 8 bytes inplace while writing 0x42 for each byte.
+    finally:
+        cs(1)                               # Deselect peripheral.
+
+    txdata = b"12345678"
+    rxdata = bytearray(len(txdata))
+    try:
+        cs(0)                               # Select peripheral.
+        spi.write_readinto(txdata, rxdata)  # Simultaneously write and read bytes.
+    finally:
+        cs(1)                               # Deselect peripheral.
+
 Constructors
 ------------
 
@@ -102,14 +138,16 @@ Methods
 Constants
 ---------
 
-.. data:: SPI.MASTER
+.. data:: SPI.CONTROLLER
 
-   for initialising the SPI bus to master; this is only used for the WiPy
+   for initialising the SPI bus to controller; this is only used for the WiPy
 
 .. data:: SPI.MSB
+          SoftSPI.MSB
 
    set the first bit to be the most significant bit
 
 .. data:: SPI.LSB
+          SoftSPI.LSB
 
    set the first bit to be the least significant bit

docs/library/machine.Timer.rst

@@ -27,22 +27,32 @@ instead of this class.
 Constructors
 ------------
 
-.. class:: Timer(id, ...)
+.. class:: Timer(id, /, ...)
 
-   Construct a new timer object of the given id. Id of -1 constructs a
+   Construct a new timer object of the given ``id``. ``id`` of -1 constructs a
    virtual timer (if supported by a board).
-   
+   ``id`` shall not be passed as a keyword argument.
+
    See ``init`` for parameters of initialisation.
 
 Methods
 -------
 
-.. method:: Timer.init(*, mode=Timer.PERIODIC, period=-1, callback=None)
+.. method:: Timer.init(*, mode=Timer.PERIODIC, freq=-1, period=-1, callback=None)
 
    Initialise the timer. Example::
 
-       tim.init(period=100)                         # periodic with 100ms period
-       tim.init(mode=Timer.ONE_SHOT, period=1000)   # one shot firing after 1000ms
+       def mycallback(t):
+           pass
+
+       # periodic at 1kHz
+       tim.init(mode=Timer.PERIODIC, freq=1000, callback=mycallback)
+
+       # periodic with 100ms period
+       tim.init(period=100, callback=mycallback)
+
+       # one shot firing after 1000ms
+       tim.init(mode=Timer.ONE_SHOT, period=1000, callback=mycallback)
 
    Keyword arguments:
 
@@ -53,6 +63,19 @@ Methods
        - ``Timer.PERIODIC`` - The timer runs periodically at the configured
          frequency of the channel.
 
+     - ``freq`` - The timer frequency, in units of Hz.  The upper bound of
+       the frequency is dependent on the port.  When both the ``freq`` and
+       ``period`` arguments are given, ``freq`` has a higher priority and
+       ``period`` is ignored.
+
+     - ``period`` - The timer period, in milliseconds.
+
+     - ``callback`` - The callable to call upon expiration of the timer period.
+       The callback must take one argument, which is passed the Timer object.
+       The ``callback`` argument shall be specified. Otherwise an exception
+       will occurr upon timer expiration:
+       ``TypeError: 'NoneType' object isn't callable``
+
 .. method:: Timer.deinit()
 
    Deinitialises the timer. Stops the timer, and disables the timer peripheral.

docs/library/machine.TimerWiPy.rst

@@ -50,9 +50,9 @@ Methods
 
      - ``mode`` can be one of:
 
-       - ``TimerWiPy.ONE_SHOT`` - The timer runs once until the configured 
+       - ``TimerWiPy.ONE_SHOT`` - The timer runs once until the configured
          period of the channel expires.
-       - ``TimerWiPy.PERIODIC`` - The timer runs periodically at the configured 
+       - ``TimerWiPy.PERIODIC`` - The timer runs periodically at the configured
          frequency of the channel.
        - ``TimerWiPy.PWM``      - Output a PWM signal on a pin.
 
@@ -74,7 +74,7 @@ Methods
    The operating mode is is the one configured to the Timer object that was used to
    create the channel.
 
-   - ``channel`` if the width of the timer is 16-bit, then must be either ``TIMER.A``, ``TIMER.B``. 
+   - ``channel`` if the width of the timer is 16-bit, then must be either ``TIMER.A``, ``TIMER.B``.
      If the width is 32-bit then it **must be** ``TIMER.A | TIMER.B``.
 
    Keyword only arguments:

docs/library/machine.UART.rst

@@ -56,12 +56,29 @@ Methods
 
      - *tx* specifies the TX pin to use.
      - *rx* specifies the RX pin to use.
+     - *rts* specifies the RTS (output) pin to use for hardware receive flow control.
+     - *cts* specifies the CTS (input) pin to use for hardware transmit flow control.
      - *txbuf* specifies the length in characters of the TX buffer.
      - *rxbuf* specifies the length in characters of the RX buffer.
      - *timeout* specifies the time to wait for the first character (in ms).
      - *timeout_char* specifies the time to wait between characters (in ms).
      - *invert* specifies which lines to invert.
 
+         - ``0`` will not invert lines (idle state of both lines is logic high).
+         - ``UART.INV_TX`` will invert TX line (idle state of TX line now logic low).
+         - ``UART.INV_RX`` will invert RX line (idle state of RX line now logic low).
+         - ``UART.INV_TX | UART.INV_RX`` will invert both lines (idle state at logic low).
+
+     - *flow* specifies which hardware flow control signals to use. The value
+       is a bitmask.
+
+         - ``0`` will ignore hardware flow control signals.
+         - ``UART.RTS`` will enable receive flow control by using the RTS output pin to
+           signal if the receive FIFO has sufficient space to accept more data.
+         - ``UART.CTS`` will enable transmit flow control by pausing transmission when the
+           CTS input pin signals that the receiver is running low on buffer space.
+         - ``UART.RTS | UART.CTS`` will enable both, for full hardware flow control.
+
    On the WiPy only the following keyword-only parameter is supported:
 
      - *pins* is a 4 or 2 item list indicating the TX, RX, RTS and CTS pins (in that order).
@@ -70,10 +87,22 @@ Methods
        When no pins are given, then the default set of TX and RX pins is taken, and hardware
        flow control will be disabled. If *pins* is ``None``, no pin assignment will be made.
 
+   .. note::
+     It is possible to call ``init()`` multiple times on the same object in
+     order to reconfigure  UART on the fly. That allows using single UART
+     peripheral to serve different devices attached to different GPIO pins.
+     Only one device can be served at a time in that case.
+     Also do not call ``deinit()`` as it will prevent calling ``init()``
+     again.
+
 .. method:: UART.deinit()
 
    Turn off the UART bus.
 
+   .. note::
+     You will not be able to call ``init()`` on the object after ``deinit()``.
+     A new instance needs to be created in that case.
+
 .. method:: UART.any()
 
    Returns an integer counting the number of characters that can be read without
@@ -148,6 +177,32 @@ Methods
 
    Availability: WiPy.
 
+.. method:: UART.flush()
+
+   Waits until all data has been sent. In case of a timeout, an exception is raised. The timeout
+   duration depends on the tx buffer size and the baud rate. Unless flow control is enabled, a timeout
+   should not occur.
+
+   .. note::
+
+       For the rp2, esp8266 and nrf ports the call returns while the last byte is sent.
+       If required, a one character wait time has to be added in the calling script.
+
+   Availability: rp2, esp32, esp8266, mimxrt, cc3200, stm32, nrf ports, renesas-ra
+
+.. method:: UART.txdone()
+
+   Tells whether all data has been sent or no data transfer is happening. In this case,
+   it returns ``True``. If a data transmission is ongoing it returns ``False``.
+
+   .. note::
+
+       For the rp2, esp8266 and nrf ports the call may return ``True`` even if the last byte
+       of a transfer is still being sent. If required, a one character wait time has to be
+       added in the calling script.
+
+   Availability: rp2, esp32, esp8266, mimxrt, cc3200, stm32, nrf ports, renesas-ra
+
 Constants
 ---------