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.66.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.66.2-cp313-cp313-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.13Windows x86-64

openbricks-1.66.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.5 MB view details)

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

openbricks-1.66.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.66.2-cp312-cp312-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.12Windows x86-64

openbricks-1.66.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.5 MB view details)

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

openbricks-1.66.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.66.2-cp311-cp311-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.11Windows x86-64

openbricks-1.66.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.5 MB view details)

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

openbricks-1.66.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.66.2-cp310-cp310-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.10Windows x86-64

openbricks-1.66.2-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.5 MB view details)

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

openbricks-1.66.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.66.2-cp39-cp39-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.9Windows x86-64

openbricks-1.66.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.66.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.66.2.tar.gz.

File metadata

  • Download URL: openbricks-1.66.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.66.2.tar.gz
Algorithm Hash digest
SHA256 a18bce0f37ca9f6c86a774a9f3d36e1b14f9dbf63b6583a43d8a11705516fb1f
MD5 b8f5bfcc8d5e4251827edda23ae44e63
BLAKE2b-256 ba72eb00560de394b783c49de4e44646d86883e30098051e1bf3e5e14b04a598

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.2-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 3ef1de3ba1a8fb4cf1549c69e04e8337c5b53cdf35091b4f20670f2f9b64f064
MD5 f05f6c5af41a8c5bde106f3d0350d0df
BLAKE2b-256 77d5c040c5776129feae40ea672dd649e04fe36433223a125d9ae5d09d7376f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.66.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.66.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.66.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 738f7d699f191e531c10e3da43d5fff2d7047dc7f0b1f1c8da0432491ba1299b
MD5 db3b937fbe23abd348c36b61a4ab4b1a
BLAKE2b-256 ec99e1042b20382c4edf72a264873567ffa40ddc673577e320cacdd05a845165

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.2-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 4dd8c61e557734ab854c5fef7ef64b80e9da46ca146af219469da39bf12f896c
MD5 9a30044965032a509c0aaf5d19e86cec
BLAKE2b-256 a4dd42aebcf72cc924775798c7ade3ac2eb7c786b86213cba7978bf314fe18c3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.2-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 b8db742e23a8814a3f7202033882c5b60575d39537a1e0aa59b508d608f6eb69
MD5 9bcd06eea78757fb3888bcebdf04a157
BLAKE2b-256 f4e80ed57155f45fd9f13f3d480b4e59843be995641c1291e94c563adf499cca

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.66.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.66.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.66.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 a7c2e8df4df1ead7d7cbdbdaa384104cd80ab8b01de1e467c0f83c8254418e17
MD5 7db7f1f99a37378b318c9f1facc4914d
BLAKE2b-256 bb2e40ab20f375d6c7d715c7c26adbd53a14b6ed2a3c280a98e370159ff0683c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.2-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 329d1b044332e9b295f5aeca2b2adb2756712eb63f1275594dec64c5bce40058
MD5 0df3f425dec364dfac5da5daf8bde600
BLAKE2b-256 036622504cbb36fb1ae3ad0bfe136d8e0e1b793e1794b1294e237000b0e6f4c1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.2-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 cc684f2c8f482910ee48892f93fa0ac5e811b5b8421b447343efc4d8555e04f4
MD5 ee836f38c99efd6e45142aae4b753801
BLAKE2b-256 6e8427f2c3f1a3f79cf5182444fc15fe24f21c5cc453d6191092f43e27a6d474

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.66.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.66.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.66.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 87637eea912d8f1c170469c6c0cb002bfc6b1f9747cbcd04ae47dbf983d8305a
MD5 1040da06a873995cc8065b99e5c1796c
BLAKE2b-256 4d89c5170962af8027f620f2c420d098690de5bd8515d90e49b7bcdd5fd621a2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.2-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 7da18e8c25b8e2ad6039d4b5dafc39c4c54dccc8d9e4b95b57207820b4046ff3
MD5 dc5f820e121dd46b2565c80d53c7c1df
BLAKE2b-256 c11a155d7351c922c0c6eca60d290ba711ea6b620c3428bb34ff5a11dcd550c0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.2-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 162c5b6894b45cfe3d03087e0766977b4cf6a13b4ffdcec23f104ff4048c594c
MD5 56a4d964ffac2a0f8552b8c98e45418a
BLAKE2b-256 f02e7228fd3ff0cc5205372c2bab9d96d9a492bf33fe78cb8014bdd4f801882f

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.66.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.66.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.66.2-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 be10089ad836d914b366bb20a2743bf2f362d55bc5b55599439d99bcd723408b
MD5 5bb24e8472b97b3a9f1bbb1c3f21056c
BLAKE2b-256 6b928e94a20f4ea4cae34640ea6ca4dcff5d2730a16fc4dd4fbae2322db2ca02

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.2-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 b575c79c12774071bdfc28cc77aed85fb5fcb3fafb920c1bf9222b3161b1a8f8
MD5 be872280ea143533457f9f1ffa626ce2
BLAKE2b-256 773ba3bbce72a684719c0c3ad6ebdde969980e4d3e10afa42a4e0e186c9a7ded

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: openbricks-1.66.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.66.2-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 1b4c1df125919c1ae5bc7886b128679a1dd7b6a695b0b3a16e6199d61b80f137
MD5 f3ddd2f2c9b47ec4b81f76dee3b7cc26
BLAKE2b-256 74523761ce64809c2189f7674e20fb1d61a19f86953f6bfeeb1c4da900b9505c

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.66.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.66.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.66.2-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 ec0bfc6b70881896dbfb55b5f476017f346fd97fee240967ea0c074169adc698
MD5 5421a684100fbf19601ec28e41008bab
BLAKE2b-256 2463fb8ed970123a087dfa196da44ad49cf5b50cdac2b0e95954a36a352afcb8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.2-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 1a0ceee6c9bff759734b1cf0c4d97fe19e3f7280f823a81ed73fc8c3897ae982
MD5 707daca03bf5327727af23915fd3fa92
BLAKE2b-256 345df7c9c78904ab0c74978dcf8d685ebea258171555db0819823ebe76fef5cc

See more details on using hashes here.

Provenance

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