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.99.0.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.99.0-cp313-cp313-win_amd64.whl (3.6 MB view details)

Uploaded CPython 3.13Windows x86-64

openbricks-1.99.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.7 MB view details)

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

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

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

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

Uploaded CPython 3.12Windows x86-64

openbricks-1.99.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.7 MB view details)

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

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

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

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

Uploaded CPython 3.11Windows x86-64

openbricks-1.99.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.7 MB view details)

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

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

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

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

Uploaded CPython 3.10Windows x86-64

openbricks-1.99.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.7 MB view details)

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

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

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

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

Uploaded CPython 3.9Windows x86-64

openbricks-1.99.0-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.7 MB view details)

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

openbricks-1.99.0-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.99.0.tar.gz.

File metadata

  • Download URL: openbricks-1.99.0.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.99.0.tar.gz
Algorithm Hash digest
SHA256 9921b39493c446c1b47f4b198e872071c158078e7a122aaba7fef79d1bfdae16
MD5 0a230b1ce680f0ef9ae31ac3fcde07be
BLAKE2b-256 8431ea95266a9803e149f1e9de72e18c7bbc3f082166a20065c0848faf626234

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0.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.99.0-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 625b4fb99d2235a824e13338dd3e7835e58c3437ad33076f65a7e76756a1289c
MD5 4fed7471ccd7717870ba4997f338dc25
BLAKE2b-256 f7b4cc7ad3be91b86230a48265a7ceafaeedd5fd6ba1ee328d2601815c6b3bec

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 0d4785d03e2e1c0fbdf463dcc0d2a4b621234a568eda90d5522bd33121685320
MD5 900c84794695c98cf329fb2efa589683
BLAKE2b-256 326e697c3e00211ce4704eafba88949218075ffb721b95309d0b1e6b39fae627

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp313-cp313-macosx_10_13_universal2.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 32621d698ae870f686f6ba03ecd7ea5352251e8da41deedfdb9edd07659b61ff
MD5 bf77f13fd92f0ccfa55ca5c1913d5b75
BLAKE2b-256 121a8d083b6b354d4500df840059b34c6a79077eaac258edcac1c155ca8ea708

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 f8bf8d6816aea49c2217a2032e64d7f1d60aeff99defeeab293f92245d79cc7d
MD5 462d82e68656eeebb65eac9fb0830280
BLAKE2b-256 694967e9d15647927419e6ddb32cf8e805dd68747055cf62b99bff104b4df38f

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 9c12e762facaf6c66f191064b10a4b36e3631d3b2471d30aaab6c9dbe0cf1e30
MD5 1b9ad8000f1f77a4640abaf2e1a04c52
BLAKE2b-256 2f62ce0cc7131a2c220e5d43bd135d83512d24851822105459b242d6a4172ccf

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp312-cp312-macosx_10_13_universal2.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 30474ccdd36bd1276dd386ee7fb3040fa42cbdd1150f41daa58bfcc99ada7005
MD5 502fa1f375faf28701be7b54a3aa9444
BLAKE2b-256 7effad54a3d26a8c9c5177d5be1303dbe2b8f7f596f25e3d944a8fc0b0a7124e

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 8c85fac7a79d0ecbb32e0a1251f9fb787d99f6a5aa9cb51f9bb3cd61b8395e6f
MD5 27b3ae2cfd560705cf1616e0d0b487ed
BLAKE2b-256 070dffb390d0d62266d340801f1888582f3315c6ba4fd01f1de6be125f90e3ba

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 84bbfeb63676c1c1a678ec4cfd6505cf6ca8d6d9438f19f8076f2cc7ca7a178e
MD5 66c8ba95f1920c4ca814595bc91bff8b
BLAKE2b-256 fd4610e499362604e4723aa639000ba26e13cb1f7e868d2abf76a9cc225534bf

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp311-cp311-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 7169b8ea329975a1597096c0659e95257ce2d899269983ce1ea4e98657f1c3d8
MD5 a39db7e6170f6f2fbe0a41db3862bbbc
BLAKE2b-256 90ecccb0febe19340fb2679474907624166d5af379c6d54dd85e736eed1d1f6d

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp310-cp310-win_amd64.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 2116e8e80cdd0ce8731945e67f203045b5796ff0fb25bd2332e0476ba970e8ed
MD5 abe88e4c57e7bae87437fb81ff628dd0
BLAKE2b-256 f160220543f4d27405d2cec527f82b015d89da80b2632772cc059616aa8de042

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 d5329c59794c89c222336a746e71addd5109537d3c44638033ef9b6d8aa37f7b
MD5 9aa35bb06b78af2846a43070189af5cc
BLAKE2b-256 e69c5e6380e1c14c14673a5800ebee1f0284fe58bbd76e24e3858ea17036d2b5

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp310-cp310-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 1354d520684d31b54854adb90d0dc4ed30570a72e02d9ef3b31693592026f814
MD5 39386315898d2daf823573246e104789
BLAKE2b-256 30e5a13cc76db187f8c1d070abdfc251abe2745fc3696b9fc8dd89bca9e95ebf

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp39-cp39-win_amd64.whl.

File metadata

  • Download URL: openbricks-1.99.0-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.99.0-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 bb49d1f7b39c3ccb9d1464eabbe89b64c762e5d9bb54eea9e987866e66b11a1e
MD5 7d86abeeee368276727e761c998c413c
BLAKE2b-256 e3c577b7b41b4b15a3803cb6dcb4c483d163a10f2f5ed52903474568608ac9f2

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 e25300c6a25cfa2127d0006a1f1fdef90e942d3110ca1c5b767079fdb9fee371
MD5 d30c8804e5d2612e09a7274459958c82
BLAKE2b-256 70cf869c8c2fb4c2768d9b9fa3062d937f851d3c56dded76a66459ef86800b5a

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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.99.0-cp39-cp39-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for openbricks-1.99.0-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 e8a71e58d4b2b067271bae29407ed9ea20af9fd7c87354d1ad66831404ee1b16
MD5 1ad27cecc47397da5df26c439a4cb5cb
BLAKE2b-256 dbfdbbca4a7806677bcfd96ecbe8bd97325a6b36efc6a407e3ace523fd96c8b0

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.99.0-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