chumicro-deploy

Push code onto a CircuitPython or MicroPython board, probe its identity, and flash firmware — from your laptop.

Programmatic Python API + a chumicro-deploy CLI. Pluggable file sources (in-memory, directory walk, AST-driven import graph), pluggable transport modes (RAM mode for fast iteration, flash mode for persistence), and an interactive recovery layer that classifies failures (port busy, drive ejected, raw REPL stuck, macOS FSKit wedge, source traceback) and walks you through the fix.

Part of the ChuMicro family — small, focused Python libraries for microcontrollers and laptops. Browse all workbench tools. This is a workbench tool — runs on your laptop, not on the board.

Install

pip install chumicro-deploy-experimental

pyserial (CircuitPython transport) and mpremote (MicroPython transport) come along as dependencies. On macOS and Linux you'll also need rsync available on $PATH for flash-mode deploys to the CIRCUITPY USB drive — install via brew install rsync (macOS Homebrew if not already shipped), apt-get install rsync (Debian/Ubuntu), dnf install rsync (Fedora), pacman -S rsync (Arch), apk add rsync (Alpine), or zypper install rsync (openSUSE). Native Windows isn't currently supported (raises WindowsNotSupportedError on import); WSL2 works.

pip install chumicro-deploy-experimental

Quick example

Deploy a one-liner to a connected MicroPython board and read its output back:

from chumicro_deploy import Device, Deployer, FileMapSource

device = Device(
    transport="micropython",
    address="/dev/cu.usbmodem14101",  # see `chumicro-deploy probe --address ...` to identify
    deploy_mode="ram",                # no flash wear, no CIRCUITPY drive needed
)
source = FileMapSource(
    {"/main.py": "import sys\nprint(f'hello from {sys.implementation.name}')"},
    entrypoint="/main.py",
)

result = Deployer(device).deploy_diff(source)
print(result.execute_output)  # → "hello from micropython"

For a workspace project that already has a devices.yml, swap the Device(...) constructor for chumicro_deploy.config.default.load_devices_yml("devices.yml", device_id="my-board").

What's included

Programmatic API

devices.yml writer surface

chumicro_deploy.config.devices_yaml (separate submodule) — round-trip read/write of the device registry with comments and key order preserved, three-zone classification (user-owned / hardware-once / probed-always). This is what chumicro-workspace add-device and friends sit on; consumers building their own onboarding flow against devices.yml use this surface directly.

CLI subcommands

python -m chumicro_deploy <subcommand> (or just chumicro-deploy-experimental <subcommand> after pip install). Each accepts --devices-file devices.yml --device <id> instead of --transport + --address for workspace-style invocations.

Testing fakes

Where this fits

Leaf — no upstream ChuMicro deps (uses third-party pyserial and mpremote for transport). Sister of chumicro-repl, substrate for chumicro-workspace and chumicro-pytest-device.

Companion: chumicro-repl

chumicro-repl is the sister workbench tool for opening interactive serial sessions and tailing the friendly REPL after a deploy. Both packages consume the same devices.yml schema (owned here in chumicro_deploy.config.default), so a single workspace file points both at the same boards. Use chumicro_repl.tail(device, seconds) to follow a deploy and fail-fast on a traceback; use chumicro_repl.ReplSession(device) for headless test fixtures over raw REPL.

Examples

Contributing

Working on chumicro-deploy itself? Clone the mono-repo if you haven't already — the rest of the workflow assumes you're inside that workspace.

pip install -e .[test]
pytest tests/                  # host-side tests
pytest functional_tests/       # on-device tests (needs a board registered in devices.yml)

Register a board before running functional tests: chumicro-workspace add-device <id> --address <port> (or hand-write a devices.yml entry).

Docs

📖 Stable docs · Experimental docs

Find this library

• PyPI: chumicro-deploy
• Source: workbench/deploy

License

MIT