rp2040py 0.1.0__tar.gz

rp2040py-0.1.0/.github/actions/setup-rp2040py/action.yml

@@ -0,0 +1,36 @@
+name: Setup rp2040py
+description: >
+  Installs rp2040py emulator globally as a standalone tool.
+  After this action, you can use rp2040py command directly
+  in subsequent steps.
+
+inputs:
+  version:
+    description: >
+      rp2040py release version to install from PyPI (e.g. "0.1.0b2"), passed as
+      `rp2040py[fs]==<version>`. If empty, installs the latest published release.
+    required: false
+    default: ""
+  python_version:
+    description: >
+      Python interpreter to install rp2040py's tool environment under (e.g. "pypy-3.10",
+      "cpython-3.12"). Defaults to PyPy for its large real-firmware-boot speedup - see
+      docs/PORTING.md#known-differences-from-rp2040js.
+    required: false
+    default: "pypy-3.10"
+
+runs:
+  using: composite
+  steps:
+    - name: Install uv
+      uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+
+    - name: Install rp2040py and verify
+      shell: bash
+      run: |
+        if [ -z "${{ inputs.version }}" ]; then
+          uv tool install --python "${{ inputs.python_version }}" rp2040py[fs]
+        else
+          uv tool install --python "${{ inputs.python_version }}" rp2040py[fs]==${{ inputs.version }}
+        fi
+        rp2040py --version

rp2040py-0.1.0/.github/dependabot.yml

@@ -0,0 +1,39 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "uv" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  # rp2040js-dependabot-tracker
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      dependencies:
+        patterns:
+          - "*"

rp2040py-0.1.0/.github/workflows/ci-kaluma.yml

@@ -0,0 +1,120 @@
+name: Test Kaluma Releases
+
+on:
+  push:
+    paths-ignore: &non-code-paths
+      - "**.md"
+      - "docs/**"
+      - "LICENSE"
+  pull_request:
+    branches: [main]
+    paths-ignore: *non-code-paths
+
+concurrency:
+  group: ci-kaluma-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # This image doesn't depend on kaluma_version or python_runtime (always the same freshly
+  # formatted, empty image) - built once here and shared via artifact instead of rebuilt
+  # redundantly in every matrix job below.
+  build-littlefs:
+    name: Build littlefs test image
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: uv sync
+
+      # Kaluma's littlefs filesystem has no auto-run semantics of its own (unlike MicroPython's
+      # main.py) - it's plain storage the staged script below writes into at runtime, so this just
+      # needs a freshly formatted, empty image sized to Kaluma's own board.js block layout.
+      - name: Create flash read/write test filesystem
+        run: uv run rp2040py mklittlefs --target kaluma -o kaluma-littlefs-flash-rw.img
+
+      - name: Upload littlefs image
+        uses: actions/upload-artifact@v7
+        with:
+          name: kaluma-littlefs-image
+          path: kaluma-littlefs-flash-rw.img
+          retention-days: 1
+
+  test-kaluma:
+    needs: build-littlefs
+    name: Kaluma ${{ matrix.kaluma_version }} / ${{ matrix.python_runtime }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Only the one version manually verified end-to-end (see demo/kaluma_run.py's docstring).
+        # 1.0.0/1.1.0/1.2.0 also ship a plain (non-`-w`) RP2040 `pico` build and could be added,
+        # but their exact boot-banner wording (matched below via --expect-text) wasn't checked
+        # against this older firmware, unlike 1.2.1 - 1.3.0+ dropped the plain `pico` build
+        # entirely (see rp2040py.cli.firmware_specs.json's "kaluma" entry).
+        kaluma_version:
+          - "1.2.1"
+        python_runtime:
+          - pypy-3.10
+          - cpython-3.10
+          - cpython-3.14
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Download littlefs image
+        uses: actions/download-artifact@v8
+        with:
+          name: kaluma-littlefs-image
+
+      - name: Setup Python ${{ matrix.python_runtime }}
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          python-version: ${{ matrix.python_runtime }}
+
+      # Downloads (and caches) this version's UF2 outside the timed test steps below, so a slow
+      # kaluma-project/kaluma GitHub-release fetch doesn't get counted as (or blow the budget of)
+      # actual boot/run time. Stages tests/kaluma/index.js (same as the real test step below) and
+      # matches its own console.log() output rather than Kaluma's boot banner - the banner is racy
+      # (see the Kaluma test step's comment below), a staged script's own output isn't.
+      # continue-on-error: a hiccup here shouldn't fail the job on its own - the real test step
+      # right after will fail with a clearer signal if genuinely broken.
+      - name: Warm up Kaluma ${{ matrix.kaluma_version }} download cache
+        continue-on-error: true
+        run: timeout 1m uv run --python ${{ matrix.python_runtime }} --no-dev -- rp2040py kaluma --image ${{ matrix.kaluma_version }} tests/kaluma/index.js --expect-text "Hello, Kaluma!"
+
+      # Real code-execution test: stages tests/kaluma/index.js into Kaluma's "user program" flash
+      # region (same one `kaluma flash index.js` writes to on real hardware), which Kaluma
+      # auto-executes on every boot. This needed the GPIO pull-up/pull-down resolution fix in
+      # gpio_pin.py to actually work (km_running_script_check() in Kaluma's system.c reads GP22
+      # with a pull-up enabled to decide whether to skip auto-run - an undriven pin used to always
+      # read low regardless of the pull, which looked identical to GP22 being pulled to GND, i.e.
+      # "skip loading"). No mklittlefs step needed - the program stages directly from the file.
+      - name: Test Kaluma ${{matrix.python_runtime}}-${{ matrix.kaluma_version }}
+        run: timeout 10m uv run --python ${{ matrix.python_runtime }} --no-dev -- rp2040py kaluma --image ${{ matrix.kaluma_version }} tests/kaluma/index.js --expect-text "Hello, Kaluma!"
+        env:
+          PYTHON_JIT: ${{ matrix.python_runtime == 'cpython-3.14' && '1' || '' }}
+
+      # Exercises the SSI flash-write path (see docs/BACKLOG.md) from Kaluma's side: mounts a
+      # littlefs image sized to Kaluma's own board.js layout (--target kaluma - a different
+      # block-size/count than MicroPython's), stages tests/kaluma/index-flash-rw.js as the
+      # auto-run user program (a separate flash region from the littlefs filesystem itself - see
+      # README's Kaluma section), and matches its own printed result rather than the racy
+      # boot-time "Welcome to Kaluma" banner.
+      - name: Test Kaluma flash read/write ${{matrix.python_runtime}}-${{ matrix.kaluma_version }}
+        run: timeout 10m uv run --python ${{ matrix.python_runtime }} --no-dev -- rp2040py kaluma --image ${{ matrix.kaluma_version }} --littlefs kaluma-littlefs-flash-rw.img tests/kaluma/index-flash-rw.js --expect-text "FLASH RW OK"
+        env:
+          PYTHON_JIT: ${{ matrix.python_runtime == 'cpython-3.14' && '1' || '' }}

rp2040py-0.1.0/.github/workflows/ci-micropython.yml

@@ -0,0 +1,117 @@
+name: Test MicroPython Releases
+
+on:
+  push:
+    paths-ignore: &non-code-paths
+      - "**.md"
+      - "docs/**"
+      - "LICENSE"
+  pull_request:
+    branches: [main]
+    paths-ignore: *non-code-paths
+
+concurrency:
+  group: ci-micropython-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # The three littlefs images below don't depend on micropython_version or python_runtime at all
+  # (same source .py files every time) - built once here and shared via artifact instead of
+  # rebuilt redundantly in all 24 matrix jobs below.
+  build-littlefs:
+    name: Build littlefs test images
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Create filesystem
+        run: uv run rp2040py mklittlefs -o littlefs.img tests/micropython/main.py --main main.py
+
+      - name: Create SPI test filesystem
+        run: uv run rp2040py mklittlefs -o littlefs-spi.img tests/micropython/main-spi.py --main main-spi.py
+
+      - name: Create flash read/write test filesystem
+        run: uv run rp2040py mklittlefs -o littlefs-flash-rw.img tests/micropython/main-flash-rw.py --main main-flash-rw.py
+
+      - name: Upload littlefs images
+        uses: actions/upload-artifact@v7
+        with:
+          name: littlefs-images
+          path: |
+            littlefs.img
+            littlefs-spi.img
+            littlefs-flash-rw.img
+          retention-days: 1
+
+  test-micropython:
+    needs: build-littlefs
+    name: Micropython ${{ matrix.micropython_version }} / ${{ matrix.python_runtime }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        micropython_version:
+          - "1.16"
+          - "1.17"
+          - "1.18"
+          - "1.19.1"
+          - "1.20.0"
+          - "1.21.0"
+          - "1.28.0"
+          - "1.29.0-preview"
+        python_runtime:
+          - pypy-3.10
+          - cpython-3.10
+          - cpython-3.14
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Download littlefs images
+        uses: actions/download-artifact@v8
+        with:
+          name: littlefs-images
+
+      - name: Setup Python ${{ matrix.python_runtime }}
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          python-version: ${{ matrix.python_runtime }}
+
+      # Downloads (and caches) this version's UF2 outside the timed test steps below, so a slow
+      # micropython.org fetch doesn't get counted as (or blow the budget of) actual boot/run time.
+      # continue-on-error: a hiccup here shouldn't fail the job on its own - the real test step
+      # right after will fail with a clearer signal if the download is genuinely broken.
+      - name: Warm up MicroPython ${{ matrix.micropython_version }} download cache
+        continue-on-error: true
+        run: timeout 1m uv run --python ${{ matrix.python_runtime }} --no-dev -- rp2040py micropython --image ${{ matrix.micropython_version }} -c "import sys; sys.implementation"
+
+      - name: Test MicroPython ${{matrix.python_runtime}}-${{ matrix.micropython_version }}
+        run: timeout 10m uv run --python ${{ matrix.python_runtime }} --no-dev -- rp2040py micropython --image ${{ matrix.micropython_version }} --expect-text "Hello, MicroPython!"
+        env:
+          PYTHON_JIT: ${{ matrix.python_runtime == 'cpython-3.14' && '1' || '' }}
+
+      - name: Test MicroPython SPI ${{matrix.python_runtime}}-${{ matrix.micropython_version }}
+        run: timeout 10m uv run --python ${{ matrix.python_runtime }} --no-dev -- python tests/micropython_spi_run.py --image ${{ matrix.micropython_version }} "hello world" "h" "0123456789abcdef0123456789abcdef0123456789abcdef"
+        env:
+          PYTHON_JIT: ${{ matrix.python_runtime == 'cpython-3.14' && '1' || '' }}
+
+      - name: Test MicroPython flash read/write ${{matrix.python_runtime}}-${{ matrix.micropython_version }}
+        run: timeout 10m uv run --python ${{ matrix.python_runtime }} --no-dev -- rp2040py micropython --image ${{ matrix.micropython_version }} --littlefs littlefs-flash-rw.img --expect-text "FLASH RW OK"
+        env:
+          PYTHON_JIT: ${{ matrix.python_runtime == 'cpython-3.14' && '1' || '' }}

rp2040py-0.1.0/.github/workflows/ci-pico-sdk.yml

@@ -0,0 +1,84 @@
+name: Test Pi Pico SDK
+
+on:
+  push:
+    paths-ignore: &non-code-paths
+      - "**.md"
+      - "docs/**"
+      - "LICENSE"
+  pull_request:
+    branches: [main]
+    paths-ignore: *non-code-paths
+
+concurrency:
+  group: ci-pico-sdk-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test-pico-sdk:
+    name: Pico SDK ${{ matrix.sdk_version }} / ${{ matrix.python_runtime }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk_version:
+          - 1.2.0
+          - 1.3.1
+          - 1.4.0
+          - 1.5.1
+          - 2.0.0
+          - 2.1.1
+          - 2.2.0
+          - 2.3.0
+        python_runtime:
+          - pypy-3.10
+          - cpython-3.10
+          - cpython-3.14
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Cache Pico SDK
+        id: cache-pico-sdk
+        uses: actions/cache@v6
+        with:
+          path: ~/pico
+          key: ${{ runner.os }}-pico-sdk-${{ matrix.sdk_version }}
+
+      - name: Set up the toolchain
+        if: steps.cache-pico-sdk.outputs.cache-hit != 'true'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential
+
+      - name: Set up the Pi Pico SDK and examples
+        if: steps.cache-pico-sdk.outputs.cache-hit != 'true'
+        run: |
+          mkdir ~/pico
+          cd ~/pico
+          git clone https://github.com/raspberrypi/pico-sdk.git --depth 1 --branch ${SDK_VERSION}
+          cd pico-sdk && git submodule update --init && cd ..
+          git clone https://github.com/raspberrypi/pico-examples.git --depth 1 --branch "sdk-${SDK_VERSION}"
+          cd pico-examples && mkdir build && cd build && cmake .. && make -C hello_world/usb -j4
+        env:
+          SDK_VERSION: ${{ matrix.sdk_version }}
+          PICO_SDK_PATH: ~/pico/pico-sdk
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          python-version: "3.10"
+
+      - name: Setup Python ${{ matrix.python_runtime }}
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          python-version: ${{ matrix.python_runtime }}
+
+      # CortexM0Core.execute_instruction() is a pure-Python instruction interpreter; CPython is
+      # much slower here than V8 JIT-compiling the equivalent JS in rp2040js, hence the generous
+      # 10-minute timeout - and why this also runs under PyPy and CPython 3.14's experimental JIT
+      # (see docs/PORTING.md#known-differences-from-rp2040js). demo/micropython_run.py has zero
+      # runtime dependencies, so no `uv sync` is needed here.
+      - name: Test "Hello World" example ${{ matrix.python_runtime }}
+        run: timeout 10m uv run --python ${{ matrix.python_runtime }} --no-dev -- python demo/micropython_run.py --image ~/pico/pico-examples/build/hello_world/usb/hello_usb.uf2 --expect-text "Hello, world!"
+        env:
+          PYTHON_JIT: ${{ matrix.python_runtime == 'cpython-3.14' && '1' || '' }}

rp2040py-0.1.0/.github/workflows/pre-commit.yml

@@ -0,0 +1,48 @@
+name: Pre-commit
+
+on:
+  push:
+    paths-ignore: &non-code-paths
+      - "**.md"
+      - "docs/**"
+      - "LICENSE"
+  pull_request:
+    paths-ignore: *non-code-paths
+  workflow_dispatch:
+  workflow_call:
+
+concurrency:
+  group: pre-commit-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pre-commit:
+    name: pre-commit run --all-files
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+        with:
+          python-version: "3.10"
+
+      - name: Install pre-commit
+        run: uv tool install pre-commit
+
+      - name: Run pre-commit
+        run: |
+          pre-commit run --all-files --show-diff-on-failure
+
+      - name: Run tests with coverage
+        run: uv run --group dev pytest --cov=rp2040py --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        if: github.actor != 'dependabot[bot]'
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          fail_ci_if_error: false

rp2040py-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Upload Python Package
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to build and publish (e.g. v0.11.0b1)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    # Specifying a GitHub environment is optional, but strongly encouraged
+    environment: pypi
+    permissions:
+      # job-level permissions replace (not merge with) the workflow-level block above,
+      # so everything this job needs must be listed here explicitly.
+      contents: write # required to create the GitHub Release
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
+
+      - name: Build package
+        run: uv build
+
+      - name: Resolve tag and version
+        id: meta
+        run: |
+          TAG="${{ inputs.tag || github.ref_name }}"
+          VERSION="${TAG#v}"
+          if [[ "$VERSION" =~ (alpha|beta|pre|rc) ]]; then
+            PRERELEASE=true
+          else
+            PRERELEASE=false
+          fi
+          echo "tag=$TAG"               >> $GITHUB_OUTPUT
+          echo "version=$VERSION"       >> $GITHUB_OUTPUT
+          echo "prerelease=$PRERELEASE" >> $GITHUB_OUTPUT
+
+      - name: Extract changelog section
+        id: changelog
+        run: |
+          VERSION=${{ steps.meta.outputs.version }}
+          BODY=$(awk "/^## \[${VERSION}\]/{found=1; next} /^## \[/{found=0} found" CHANGELOG.md | sed '/^[[:space:]]*$/d' | head -50)
+          if [ -z "$BODY" ]; then
+            BODY="See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details."
+          fi
+          echo "body<<EOF" >> $GITHUB_OUTPUT
+          echo "$BODY" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          tag_name: ${{ steps.meta.outputs.tag }}
+          name: ${{ steps.meta.outputs.tag }}
+          body: ${{ steps.changelog.outputs.body }}
+          prerelease: ${{ steps.meta.outputs.prerelease }}
+
+      - name: Publish package to PyPI
+        run: uv publish --check-url https://pypi.org/simple/

rp2040py-0.1.0/.gitignore

@@ -0,0 +1,98 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# pyright
+pyrightconfig.json
+
+# claude
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db
+
+**/target
+**/mips*.tar
+**/mips*--glibc*
+**/mips*--musl*
+**/lib.rs:*
+
+# images
+**/*.img
+**/*.uf2
+**/*.elf
+**/*.bin
+tmp/

rp2040py-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+default_install_hook_types: [pre-commit]
+default_language_version:
+  python: python3
+
+repos:
+  - repo: local
+    hooks:
+      - id: uv-lock
+        name: uv lock
+        entry: uv
+        args: ["lock", "--upgrade"]
+        language: system
+        pass_filenames: false
+
+      - id: uv-sync
+        name: uv sync before hooks
+        entry: uv
+        args: ["sync", "--python", "cpython-3.10"]
+        language: system
+        pass_filenames: false
+
+      - id: uv-mypy
+        name: mypy
+        entry: uv
+        args: ["run", "mypy"]
+        language: system
+        pass_filenames: false
+
+      - id: uv-ruff-check
+        name: ruff lint & fix
+        entry: uv
+        args: ["run", "ruff", "check", "--fix"]
+        language: system
+        pass_filenames: false
+
+      - id: uv-ruff-format
+        name: ruff format
+        entry: uv
+        args: ["run", "ruff", "format"]
+        language: system
+        pass_filenames: false
+
+      - id: uv-pytest
+        name: uv run pytest
+        entry: uv
+        args: ["run", "pytest"]
+        language: system
+        pass_filenames: false

rp2040py-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10