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

Uploaded CPython 3.13Windows x86-64

openbricks-2.5.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-2.5.0-cp313-cp313-macosx_10_13_universal2.whl (3.7 MB view details)

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

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

Uploaded CPython 3.12Windows x86-64

openbricks-2.5.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-2.5.0-cp312-cp312-macosx_10_13_universal2.whl (3.7 MB view details)

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

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

Uploaded CPython 3.11Windows x86-64

openbricks-2.5.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-2.5.0-cp311-cp311-macosx_10_9_universal2.whl (3.7 MB view details)

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

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

Uploaded CPython 3.10Windows x86-64

openbricks-2.5.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-2.5.0-cp310-cp310-macosx_10_9_universal2.whl (3.7 MB view details)

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

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

Uploaded CPython 3.9Windows x86-64

openbricks-2.5.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-2.5.0-cp39-cp39-macosx_10_9_universal2.whl (3.7 MB view details)

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

File details

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

File metadata

  • Download URL: openbricks-2.5.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-2.5.0.tar.gz
Algorithm Hash digest
SHA256 43f973f50489364700a6a9062c9a495e354244525bb5fd1551bd4c372020dbe5
MD5 707a1eff71b672788f53a14c7e7d7b95
BLAKE2b-256 5b0ba14467ad775f6796ea9784a2fff5cc676924366ae66e87fb0efca0e9fb8a

See more details on using hashes here.

Provenance

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

File metadata

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

File hashes

Hashes for openbricks-2.5.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 b76a999c1e162d3b4647fe2735b1a899dddd28cab880f10a64103716e14a5b04
MD5 8bd35f8fbb3787e0bd6647e40050d41a
BLAKE2b-256 67bd3dd094c192ee6cb6954315239f5aee69d01536cc8991e66e34ec46878337

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-2.5.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 c3011c41a2a220d38b5a4e8bffbed41728a65f5f01b7d3c5124c10a40004d99b
MD5 c0fc6a78fad8a52462a862579274e3f7
BLAKE2b-256 1e8b9fe3c9ec9d9db9a3c121fb2c5313d3c881fdb78482242b943efe4d4bbd99

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-2.5.0-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 fb77ab84d9e5c62a15e380017c70506177ff895f1e1587f106c85ae153dea7eb
MD5 8691f416424b4c212ae7f2dc7641a39d
BLAKE2b-256 4c37ebaaea2b24b673e23c695c7062152364f585920aab968b1b826cb29cd0b7

See more details on using hashes here.

Provenance

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

File metadata

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

File hashes

Hashes for openbricks-2.5.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 aca71a78ef8b3d3ab18bae96a784f1b21fa240f95f1786203478d10c99c58b19
MD5 6f182349180d3aa24aa83937ecd08414
BLAKE2b-256 e9eeffbe192ff6344403d92c4934658555daa0d04a00ec8a2434835f099169af

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-2.5.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 76da67e95a850a27401fff13df11a9749176c3ccad65f010d571d7bfa51b040f
MD5 43182ce8220df93231e8b9258b8da3e4
BLAKE2b-256 6df6649cc8696a1dfe35bf3d6279c2a117a77e9a5dc2fe28f86ba2914f18d04f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-2.5.0-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 46e93ba91e66eac51ad72623eddf08c2e596fab2709764016d5adce822677724
MD5 d3b3da1eefb93a78e8f9396e992626cd
BLAKE2b-256 e6f441b84545fd8cdf6fcba9d37df8b1e0874506999f69b2da12ce335be01e4a

See more details on using hashes here.

Provenance

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

File metadata

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

File hashes

Hashes for openbricks-2.5.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 0fe15cfd629ba703d8ee17a6783bcd11c8be1c9ace392c8ed1cc8b7616c081da
MD5 a2fc6802004ce3bfc30ec4570769751b
BLAKE2b-256 c3635fde6e20e1a7e77a1b600c44bfcfb0add043e25c4db03225e01ba7c8d062

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-2.5.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 e49e19ea0b800c4f40ca26d21b7873f84a5c3ae8fd44fbcf93f0c29b717a4f8c
MD5 9d7fe6abe26e2d79852d4d4f37af5ce1
BLAKE2b-256 c22270d1853ab379f8ade7279266d028c53cb3258d262001a65c9823666fa488

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-2.5.0-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 7497f98c8c52c2441a7d49ca53918f6c767aa1ce6d28041f796eb2832457f543
MD5 b28a4f50bc472fbb7c70e06aa44af7eb
BLAKE2b-256 d99ce3efadac0f5158d7335b15813bb59ed9911e7847c8d1e699163f80fc96fb

See more details on using hashes here.

Provenance

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

File metadata

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

File hashes

Hashes for openbricks-2.5.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 b2c826593bf86807cbfd58d8ea6fab0dbfe056757cc025ffa2f21b5d262f2570
MD5 9dbf2e35c5cc8a826c08a901c6f14f48
BLAKE2b-256 671f73dd72a6a8516d9d95ebd8ddb024c966c892e4153d63780593339578fa9a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-2.5.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 281e45df43ddf7bbe19c8a9b980fc7f8e0c2f84e2c4dee51f32e8044e3082710
MD5 f9c2f8a9fe23f3344704d2b8b0a86980
BLAKE2b-256 2c3df95948b45c9eeb2efc19154d8f2701ca54407d7184e291a21bdedaa418cd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-2.5.0-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 a34836d13c2742108b384eeee81cf2b9e93f98cf325cc41634c1570df678f7b0
MD5 71ae05c1df457a0178b8326621b1ffcf
BLAKE2b-256 835c2dd2577b43856f9cdfff41ae1242a7a27fe1e5179c327263d5b9d1dad033

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: openbricks-2.5.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-2.5.0-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 a67ca8e6d930ef1bced3b113e0d65796d2422cd8adb65f160a6b8ec758358953
MD5 d1e8953309350195d67188e36e64e251
BLAKE2b-256 6f0df948206e6be134bcab6718610a3f84f00c95aa0ccde029362c72b951e859

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-2.5.0-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 f42f405774ea8a8a599be6ee4bfff8e317fd3c5b48338053bb321418ceaaea9b
MD5 77a4f97c24a7fdb7485ba7ca18639b3f
BLAKE2b-256 574b43687194c054f4804d7e826ff3e87478f9ca4cb079638b46d3adf56150d2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-2.5.0-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 b83ef1efeb473c98a242d5f657495c3c308723f5ecf5760e377c5045a576d3d5
MD5 40e9bddf175b0bfce3079c7f3e5ad1b6
BLAKE2b-256 43dbac1045c33081bbcb1a007bc732bd93f98d225ffd363803f4835be5b9c9ba

See more details on using hashes here.

Provenance

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