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.67.2.tar.gz (3.7 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.67.2-cp313-cp313-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.13Windows x86-64

openbricks-1.67.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.67.2-cp313-cp313-macosx_10_13_universal2.whl (3.5 MB view details)

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

openbricks-1.67.2-cp312-cp312-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.12Windows x86-64

openbricks-1.67.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.67.2-cp312-cp312-macosx_10_13_universal2.whl (3.5 MB view details)

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

openbricks-1.67.2-cp311-cp311-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.11Windows x86-64

openbricks-1.67.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.67.2-cp311-cp311-macosx_10_9_universal2.whl (3.5 MB view details)

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

openbricks-1.67.2-cp310-cp310-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.10Windows x86-64

openbricks-1.67.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.67.2-cp310-cp310-macosx_10_9_universal2.whl (3.5 MB view details)

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

openbricks-1.67.2-cp39-cp39-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.9Windows x86-64

openbricks-1.67.2-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.5 MB view details)

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

openbricks-1.67.2-cp39-cp39-macosx_10_9_universal2.whl (3.5 MB view details)

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

File details

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

File metadata

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

File hashes

Hashes for openbricks-1.67.2.tar.gz
Algorithm Hash digest
SHA256 14d90d5aff283ec695bc062990fa5764e7d079f24f7c80b8e6bf21d23df40759
MD5 fc8703d0840250c155f7b82db20000c3
BLAKE2b-256 5f6de37b89796b4771a0162abc8ea722da347102c2765608d539628cea3eb79d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.67.2-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 d83edd2cd405206f93a46e65a5966d59dd46ed3d48bfce3ef881b5d5fd4a5d82
MD5 8fe16cf36ffff2b24018c90fc7846826
BLAKE2b-256 f2f60f065ad034b6a225d3296fb75a89f4ad6328cc322b58fb4bcb758714c274

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.67.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.67.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.67.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 e322a6fa173456deccede7aa6bed8b98770f022f12040fca9dd8c636a3d753ad
MD5 30155bd7bfba3744735ce9cc0005b4be
BLAKE2b-256 b5e475fd2b699c1974d15d681a1a47e065b608158ba45393e9ed8f82180fdf55

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.67.2-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 eda90f4285dd868a2826075294575a5683a4ec2c0bce661ea29cbd28de41457a
MD5 ac059cb6d8b0098c851d9ed32e03bac2
BLAKE2b-256 ab66d6a3116c2748ecf43eac6a594f3545926ae2f16464f48dd827d87e43b081

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.67.2-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 aa0da3cd43e4acb54ec0aa36bb6f698ce3f5f62de8aa333f2a289eaec16dc5e0
MD5 bcf754666b5f04e31c0e5fb5e218bfe0
BLAKE2b-256 9bb725162a032836815502934aee6a0795f9102cfb3b9b8583066c3d2e871872

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.67.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.67.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.67.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 0a9f7102740c7013caa2ca673668c993f08b5ab4b044b52641025a640045d38e
MD5 4b7d70603497150286860354a43ec74b
BLAKE2b-256 eca37522720bfc5d7ebf45d5e390770abd43da500f77e638dbc073bd2ae67620

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.67.2-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 f7a6d4359d88063e4daa67c0e4742b0c7a2abb612f640e56c7a7fa7781c0e432
MD5 6a511604c3502b20161c5fd5a6b47a9e
BLAKE2b-256 3d33f475ef41b9e9b84280072dfeeb5a5a0a2c69b8cb57d48e66378e256e6791

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.67.2-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 11c63fb6262fdbe0c155d349934e3bb7ca25e49ced504a4184b85ca331d3f76e
MD5 50f44aa8bbb9bba7af247ef40880b57d
BLAKE2b-256 db895c672bd45e7d2eac79d2e7b51168db57d9dfdae4b7b3fceb65215b3fe28d

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.67.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.67.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.67.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 3b6c568836a63290897be91500e8fdd66c08609f09c1b4ccc4bac035c108cf7e
MD5 52e1899dd719b9e5513e2b4a125d1fcd
BLAKE2b-256 729dfeaadf52d1f86dcd9bc769bdd24002c462c044a7f3648e247a9c98585817

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.67.2-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 96dd9bb8937427c9abd8b394cca4ea6442d0193fcafcb5fddeeec756ffbf9c19
MD5 f80b4964e5d66b2db278d2ff285e3fa8
BLAKE2b-256 c03b60f6383888f8abae69c4f7d9e5e83a1da9976dce142825ff35ce7bb70107

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.67.2-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 aa25497d3903d92a8790ab0736472c1b15a3112f1c58fa7c4c87adecd2c35335
MD5 2c5a451fa506cc1ca622d62987360313
BLAKE2b-256 c736d80e96c4240739f290b90ebcde99f49a602f2711b2412d2c8a2addef48e5

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.67.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.67.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.67.2-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 9d0932b8906a80fe078163a4a68e103e22a38fd8ac352da0847ea30f6e73edab
MD5 db62cefbac5a4838d0c863e98b4bfa51
BLAKE2b-256 8b3d669ec836d9c35cb1e401d8c5a4d554b5068bade9a3977ea59eab625a5a0b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.67.2-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 73ce26d400bf4cd136016fc9c49d2bdc2b6e0699aa1c12190bd70998ffb725a0
MD5 e4b3e565d23a551b91828f69ce485eb0
BLAKE2b-256 010fc6452e92a603874eb8f1c3c71f8e982b4fecf53253f23dd1399a3f929985

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: openbricks-1.67.2-cp39-cp39-win_amd64.whl
  • Upload date:
  • Size: 3.5 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.67.2-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 b56ba02024ef8acf6e328318f95b190cdde7f229111c8beb0ee6e361d143530d
MD5 ffeea5106795e843f8e74f2945ceeaac
BLAKE2b-256 a4979d482e907ad9ecd8503dd66a6d67b9f8e874fa9e7d1121c417ff5512e961

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.67.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.67.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.67.2-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 fd62359dea52c00374e634189e9e35dc066bd180fe531730e77f00316667c49d
MD5 1089dfaacf764829aec1a7ebe31b7255
BLAKE2b-256 a71720f5589f19d8ba6ffb7612b248c90fbc2d050e87cbbe0adb789fd83223cf

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.67.2-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 ab184c7cf8ee5db4659904d02d46962301bd944dca423254dac0894d561bd9d6
MD5 bf25e5fd93ea8a855ec3e3f61e098f8a
BLAKE2b-256 107c57de50ed7345a3a14172652c1879e50cf57d758f2d09a164ce2ab73b21d1

See more details on using hashes here.

Provenance

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