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
KeyboardInterruptvia the same launcher pathupload+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
runstages to/program.py, the hub can re-run the last program via a button press without another upload.uploadandrundiffer 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:
- Brings BLE + REPL bridge up immediately (so
openbricks run/upload/stopare always reachable, even when no program is running). - Instantiates the board's Hub, which wires the BLE-toggle button (short-press on GPIO 5) with LED feedback.
- Watches the program button (GPIO 4) via
openbricks.launcher.run()— a short-press runs/program.py, a second short-press raisesKeyboardInterruptin 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.
1 maintainer
Release files for openbricks 2.8.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| openbricks-2.8.1.tar.gz | 3.8 MB | Details |
Built distributions (wheels)
Total release size: 58.7 MB
Release files / openbricks-2.8.1.tar.gz
| Download URL | openbricks-2.8.1.tar.gz |
|---|---|
| Size | 3.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
31277149db26b171d6047be89bba94ffec84b116a8dec4eaf03a7fc20ee33b27
|
|
BLAKE2b-256 checksum How to use checksums |
a32775e77f58756e05b9b2e4bf57b5db22208787be38c2b1177cf2f6655167dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp313-cp313-win_amd64.whl
| Download URL | openbricks-2.8.1-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
39e98c3c77e2607f5307850f8e3c70d013098ea5e3a3c8b1bc01ace720b30a60
|
|
BLAKE2b-256 checksum How to use checksums |
f66c84f9decbcbf12b7696b7a17348f9d3de9c28339e222e9fd74cfc08377660
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | openbricks-2.8.1-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
ffe1fa3c5f3bddc6d0a0fca308fd92353645b722a19630f4b05873a22e4bfe23
|
|
BLAKE2b-256 checksum How to use checksums |
90f3f831966fbe8226a674222fbc3a5bdd75fe267445c5c3ed4c40038269d92e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp313-cp313-macosx_10_13_universal2.whl
| Download URL | openbricks-2.8.1-cp313-cp313-macosx_10_13_universal2.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.13 macOS 10.13+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
a9470cc8f868b4701111e1d7f4cd031c90d4183ac206269803adf00f30bad6b3
|
|
BLAKE2b-256 checksum How to use checksums |
dd7c86474a6195491dd8195c69978b8bfa7c543dffa373975d6f609cae0334be
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp312-cp312-win_amd64.whl
| Download URL | openbricks-2.8.1-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
8a577709da1763e31f90d057bd9ea58e8c3591b79491b42fd4467087633d68cd
|
|
BLAKE2b-256 checksum How to use checksums |
dcd9b1fca026ab9a79f8cbdeae1a558807a3a6bbecdbd292b7fed23ebb7f129d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | openbricks-2.8.1-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
63f0af42a436e94104ecf5ffc53756b32a9ce0dec68de3b606e1f41159d06409
|
|
BLAKE2b-256 checksum How to use checksums |
756fae6b48edb94051735d228e5231f49b5afd2b304d5abd6952f983e41c97be
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp312-cp312-macosx_10_13_universal2.whl
| Download URL | openbricks-2.8.1-cp312-cp312-macosx_10_13_universal2.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.12 macOS 10.13+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
c4f51ef2b92d4dbdc2ae3a09c768c6b8d974015499d5e2497759d0b80a697ebd
|
|
BLAKE2b-256 checksum How to use checksums |
bd2e06cd484cf33c594e3d644d71f0755c14a3ab821c455ae7eb26dd8f73cd3a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp311-cp311-win_amd64.whl
| Download URL | openbricks-2.8.1-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
889d57117e5431958204cd08fa348ae3c6809b987131bb6a75024ebcb6fbf490
|
|
BLAKE2b-256 checksum How to use checksums |
9ed437d068a2fb3fec3e3da8ceb62149fc7113a691dbd957dc22323820857504
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | openbricks-2.8.1-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
fa7c2df6f56d4c25ffd3c01a2d3b7c7583d872b78710e32e4d64243673f17c37
|
|
BLAKE2b-256 checksum How to use checksums |
e0d0d3fe310829aeb0a985e8398306402b56afcd78253a353380c4cf1b742e28
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp311-cp311-macosx_10_9_universal2.whl
| Download URL | openbricks-2.8.1-cp311-cp311-macosx_10_9_universal2.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.11 macOS 10.9+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
bdaad66d59ae85c9f3df558e03cd551945035c7e2b400fb3708daa97a754ed0e
|
|
BLAKE2b-256 checksum How to use checksums |
d5d506a5d0cceb34139e8198c51e0483110aa037cf47583c5a22edff0d59e48b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp310-cp310-win_amd64.whl
| Download URL | openbricks-2.8.1-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
df4d30c55af8e1dea58d37b0dfb7136f3b4026dea47414406f6264fc933af76d
|
|
BLAKE2b-256 checksum How to use checksums |
e0ef9499e853602a43f8c6dbdc837297f2a2c8577986a7c3ef1c5f68c9b7359f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | openbricks-2.8.1-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
7e844ac90c5a50d8ad48de5073e8c6f382ddddc4fd869766986a36961fe09696
|
|
BLAKE2b-256 checksum How to use checksums |
711cc828d3f5db55a8ea036c8a7af3bb100a15066f5a6756268b9287c55c4435
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp310-cp310-macosx_10_9_universal2.whl
| Download URL | openbricks-2.8.1-cp310-cp310-macosx_10_9_universal2.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.10 macOS 10.9+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
7f418e0f7281cafa81e4d7e2370cb24fb3b7555696f2481d07d0d63a1fa6b1c9
|
|
BLAKE2b-256 checksum How to use checksums |
1ca676b9f8ae180506f54224d4166a675fbc7a8afae36f8a9afc81875146221e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp39-cp39-win_amd64.whl
| Download URL | openbricks-2.8.1-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
d844b5cc207dc79b1047c6c644743b3a30749aad2e915d2911ed3ddab202c323
|
|
BLAKE2b-256 checksum How to use checksums |
94d721106391582d2c94421f4dda31c71e94fe5de437ef25edd5c66c78a28be7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
| Download URL | openbricks-2.8.1-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64 |
|
SHA-256 checksum How to use checksums |
d10a92f4863e8a1d02b9ce1dd4cbb33baebd8e5eede1837db8f6814ba88d7eb9
|
|
BLAKE2b-256 checksum How to use checksums |
3ff81d80c06bb1383b30a5b56afdd02df42a6749f64073cd1dad5c4391490811
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency logRelease files / openbricks-2.8.1-cp39-cp39-macosx_10_9_universal2.whl
| Download URL | openbricks-2.8.1-cp39-cp39-macosx_10_9_universal2.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.9 macOS 10.9+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
0bea36bccb66e88e0aaabfaacf70461a40e8a6070602b406b4db700f414b1cc3
|
|
BLAKE2b-256 checksum How to use checksums |
a59a264749cdd93f2bad3809d711798d79b852f81474a05f1c2be2937ab36f23
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 17, 2026.
Transparency log
