Skip to main content

openbricks (host CLI + sim)

Host-side tooling for openbricks hubs — same UX as pybricksdev, built on commodity Python tooling (bleak, esptool, mpremote). One package, one console script: openbricks flash / list / run / upload / stop / log. The MuJoCo-backed simulator is built in too — openbricks sim … opens the sim's CLI when the [sim] extra is installed.

Website: https://openbricks.dev · Documentation: https://docs.openbricks.dev

Install

Recommended — with pipx so the CLI lands in an isolated venv and avoids the "externally managed environment" error on modern macOS / Linux distros:

pipx install openbricks            # CLI only (lightweight; bleak / esptool / mpremote)
pipx install 'openbricks[sim]'     # CLI + MuJoCo physics simulator

Plain pip works too:

pip install openbricks
pip install 'openbricks[sim]'

For development against a repo checkout (editable install):

pip install -e 'tools/openbricks[sim]'

[sim] adds mujoco (~50 MB, native OpenGL) and numpy — most users (flash + run + log) don't need it. Without [sim], openbricks sim … prints a helpful "pip install openbricks[sim]" hint instead of crashing.

Note: binary wheels (manylinux, macOS universal2, Windows AMD64; CPython 3.9–3.13) ship on PyPI since 0.10.3, so installs are toolchain-free on common platforms. On anything outside that matrix, pip falls back to the sdist and compiles the bundled native extension (openbricks_sim._native), which needs a C compiler + Python headers.

Commands

flash — program a hub

openbricks flash \
    --name RobotA \
    --port /dev/tty.usbserial-XXXX \
    --firmware native/micropython/ports/esp32/build-openbricks_esp32s3/firmware.bin

Writes the firmware image and bakes the hub's BLE advertising name into NVS. --name is mandatory: two hubs with the same name can't be individually addressed over BLE.

Port syntax: /dev/ttyUSB0 (Linux), /dev/cu.usbserial-* (macOS), COM5 (Windows).

Useful flags: --chip esp32s3, --baud 921600, --skip-erase (faster dev loop, keeps stale NVS).

list — scan for hubs

openbricks list [--timeout 5.0] [--all]

Runs a BLE scan and prints every named device found, sorted by RSSI (strongest first). --all includes unnamed devices too.

run — stage and launch; button stops it; client exits on stop

openbricks run -n RobotA examples/hello.py

Stages the script to /program.py (same target as upload) and triggers the hub's launcher to execute it immediately. Output streams back to your terminal in real time.

  • Button stop. Pressing the hub button while the program runs raises KeyboardInterrupt via the same launcher path upload+button uses. The client sees the clean "stopped by button press" line and exits.
  • Program completion. When the program finishes (or raises), the client disconnects and exits — same as pybricksdev run.
  • Script persists. Because run stages to /program.py, the hub can re-run the last program via a button press without another upload. upload and run differ only in whether the client auto-launches after upload.

Stderr (e.g. exception tracebacks) arrives after stdout and is surfaced with a blank-line separator. No paste-mode === echo — raw-paste mode is clean.

stop — interrupt the running program

openbricks stop -n RobotA

Sends a single Ctrl-C byte over the NUS REPL bridge, which MicroPython surfaces as KeyboardInterrupt. Useful when openbricks run has already exited but the hub's still chewing on a long-running user program.

upload — stage a script; hub button launches it

openbricks upload -n RobotA examples/wander.py

Writes the script to /program.py on the hub. The code does not run automatically. Place your robot, press the program button (GPIO 4), and the program starts. Press again to stop it mid-run.

(Pybricks calls this same operation download from the hub's "download to me" perspective. We name by direction-of-data-travel — bytes flow up to the hub, hence upload.)

This works because the firmware ships a frozen main.py that:

  1. Brings BLE + REPL bridge up immediately (so openbricks run / upload / stop are always reachable, even when no program is running).
  2. Instantiates the board's Hub, which wires the BLE-toggle button (short-press on GPIO 5) with LED feedback.
  3. Watches the program button (GPIO 4) via openbricks.launcher.run() — a short-press runs /program.py, a second short-press raises KeyboardInterrupt in the running program.

Two separate pins (4 for program, 5 for BLE toggle), each handled by short-press only — no duration-based dispatch.

Pass --path /alt.py to stage at a different filename (if you've written your own main.py that reads from there).

Tests

cd tools/openbricks
PYTHONPATH=. python -m unittest discover -s tests -t .

No real hardware needed — esptool, mpremote, and bleak are mocked.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openbricks-1.83.2.tar.gz (3.8 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

openbricks-1.83.2-cp313-cp313-win_amd64.whl (3.6 MB view details)

Uploaded CPython 3.13Windows x86-64

openbricks-1.83.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

openbricks-1.83.2-cp313-cp313-macosx_10_13_universal2.whl (3.6 MB view details)

Uploaded CPython 3.13macOS 10.13+ universal2 (ARM64, x86-64)

openbricks-1.83.2-cp312-cp312-win_amd64.whl (3.6 MB view details)

Uploaded CPython 3.12Windows x86-64

openbricks-1.83.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

openbricks-1.83.2-cp312-cp312-macosx_10_13_universal2.whl (3.6 MB view details)

Uploaded CPython 3.12macOS 10.13+ universal2 (ARM64, x86-64)

openbricks-1.83.2-cp311-cp311-win_amd64.whl (3.6 MB view details)

Uploaded CPython 3.11Windows x86-64

openbricks-1.83.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

openbricks-1.83.2-cp311-cp311-macosx_10_9_universal2.whl (3.6 MB view details)

Uploaded CPython 3.11macOS 10.9+ universal2 (ARM64, x86-64)

openbricks-1.83.2-cp310-cp310-win_amd64.whl (3.6 MB view details)

Uploaded CPython 3.10Windows x86-64

openbricks-1.83.2-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

openbricks-1.83.2-cp310-cp310-macosx_10_9_universal2.whl (3.6 MB view details)

Uploaded CPython 3.10macOS 10.9+ universal2 (ARM64, x86-64)

openbricks-1.83.2-cp39-cp39-win_amd64.whl (3.6 MB view details)

Uploaded CPython 3.9Windows x86-64

openbricks-1.83.2-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.6 MB view details)

Uploaded CPython 3.9manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

openbricks-1.83.2-cp39-cp39-macosx_10_9_universal2.whl (3.6 MB view details)

Uploaded CPython 3.9macOS 10.9+ universal2 (ARM64, x86-64)

File details

Details for the file openbricks-1.83.2.tar.gz.

File metadata

  • Download URL: openbricks-1.83.2.tar.gz
  • Upload date:
  • Size: 3.8 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for openbricks-1.83.2.tar.gz
Algorithm Hash digest
SHA256 59f9a9fc44dfa100abbb52c0a639a4d7f856fce48e7b50cba573e8c0d2d45029
MD5 04ddb1f5c183fffc9483452447d6559a
BLAKE2b-256 d529a381e38b81546aaa9e3e4cf6aee9b4284554963ee8f9cd39a859b9213159

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2.tar.gz:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 607b773d8dd060e3b375cf0baeb0dbfa9134b4cd1aec9f3c9dfad711aeb53e82
MD5 b59008a83393b98e331188811338477e
BLAKE2b-256 467ce1059ccb53eb57b7e1c2862cae97a91e2fa8f45741b6e3f117f7fbca1861

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp313-cp313-win_amd64.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 eef6e695843f2508228a00c84388139fb132c71f1c97c337145f87fe6d32220c
MD5 6968504af64117dcf860fe0585e7b36c
BLAKE2b-256 c58e0b0128efcaf1a82f4b18dde2d8e747b6b4462e79000296f5ce6b04e63730

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp313-cp313-macosx_10_13_universal2.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 49f083e08d336c6c2b014aa2ef5dbaf5d7035150defa8d07e0ec407b2d3fa93f
MD5 85eb631237266c12951749fbe37481f4
BLAKE2b-256 6dc708e501e11b1b64fc8a4425d20d0b9e2b047e2ebf0fec1b78a4ed3f58fda9

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp313-cp313-macosx_10_13_universal2.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 0425abd466b96cd8974452512dfc7d0c82d4928a3012cc8eeeefa874641433fa
MD5 aaa5cec2e9fdeb57583f1e09391954a3
BLAKE2b-256 da7be7527de60d3b9ab775ab48387be9ae3bedb54da7c7a4f1b2f883fe082b34

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp312-cp312-win_amd64.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 9191394ae81edcaa51cfa3265798570a7e1161b8ab511e2ae0ebfbd3445aed9b
MD5 46591e93d71a5347b1ba1d92ec0537d9
BLAKE2b-256 a61a97aad0ccd02fa62a8ab087e825469f2375391db83bec22c0ece160205d41

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp312-cp312-macosx_10_13_universal2.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 969188b7de363d23e58bd05cd222dfd169d8dfe628436f2e4ea2bed0b8631989
MD5 0a6e4c91a64c8f6f727b9392fafff5e0
BLAKE2b-256 5d10acd77a69811e8e02dce990a1fe285236b1008d67d8e2c9581d343f9116ab

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp312-cp312-macosx_10_13_universal2.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 1ccdc29b0de2587861ac36f7ac7f5849ef42beb3644b97fda581220ebb175b92
MD5 498e1771058b4b1a7b515d35b4d3010d
BLAKE2b-256 bbb34d347977d62ca3538ce513d3dce486219a6ea78c2afd7148d6916d74353f

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp311-cp311-win_amd64.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 061a6ff3d4e75776beaf7931cbd9dad4f67bcd995ce3ad8776ab2829553b58b8
MD5 e69b6cfa72ce987c1483973112199808
BLAKE2b-256 50a460105779f93e8e48061cea28d44378964f94ed19508cb624507809383e0f

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp311-cp311-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 5dcb055dfad170ea130305c9865de5065d58e594de9b542d3894b40fcfba652f
MD5 f287a3269316fecd9bf957cfd3083cbe
BLAKE2b-256 b3ca852688ff7618ba66c61e7a1c3d2950072917df1a06fbccc5cd7edf7baa1b

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp311-cp311-macosx_10_9_universal2.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp310-cp310-win_amd64.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 0aa525cd3cb0a0cbac8056eec91c6134249e3f54de6926144bcef28a27bf1921
MD5 132a3a32dcbb0f57146613758412cb3a
BLAKE2b-256 253c5e5c29f153bb2b8801f24fe7b3930b865108e9f732d4e6a99d83691dce72

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp310-cp310-win_amd64.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 7e9d20641a8faf8d58c50b3341e3b2e682ebe5972d32c891de430a2d341f353f
MD5 863451a1a7594d783d2deeccf235498f
BLAKE2b-256 ac5b9bad342ae0a4ce6c62fa9f8e6e53c99b34254eab6c8b89e9c9d26a06eb74

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp310-cp310-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 51eebd300d8968c59ed1dd91597e93749e6307fe57fe419b73b830d37c1afc9a
MD5 6c42731af659e8328418e29472d5ac87
BLAKE2b-256 832776de0e60a9fa0381442e2a5fbc62467c4354d63ed5c297c3486dee85b7cc

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp310-cp310-macosx_10_9_universal2.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp39-cp39-win_amd64.whl.

File metadata

  • Download URL: openbricks-1.83.2-cp39-cp39-win_amd64.whl
  • Upload date:
  • Size: 3.6 MB
  • Tags: CPython 3.9, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for openbricks-1.83.2-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 2fabc248bdc8129bdce9fe942a51ae4057f56ec0743af82523d61eed8eee0a4e
MD5 970004fa6730ee7a90a568ad174804eb
BLAKE2b-256 890bc5c6ac2498201b5f1bdd6c36d32d2f2e88062d636c1d60153bbdfef5dc8d

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp39-cp39-win_amd64.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 dc60757e8a5ae0abac717d6e93a8a6f4b4c433d638f79519b417264c2be714bd
MD5 86cdda226ccbffe9efda0cecf140c495
BLAKE2b-256 71f622a0aec48b20b9bfa123e46fd99db36790ed7574f259088a82797fb17288

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openbricks-1.83.2-cp39-cp39-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for openbricks-1.83.2-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 85a35ab2e3ce0e270536610a0a0e542c09ee4edac870da62310f134f0701b1e1
MD5 c1900cadaf2a50f0483b66a3c58e6769
BLAKE2b-256 428639419213acc6a69eb154e6ab58f132f548e7e3af431b18f6781cad358c3b

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.83.2-cp39-cp39-macosx_10_9_universal2.whl:

Publisher: ci.yaml on 1e0ng/openbricks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page