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

Uploaded CPython 3.13Windows x86-64

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

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

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

Uploaded CPython 3.12Windows x86-64

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

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

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

Uploaded CPython 3.11Windows x86-64

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

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

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

Uploaded CPython 3.10Windows x86-64

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

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

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

Uploaded CPython 3.9Windows x86-64

openbricks-1.69.0-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.69.0-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.69.0.tar.gz.

File metadata

  • Download URL: openbricks-1.69.0.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.69.0.tar.gz
Algorithm Hash digest
SHA256 024aece5fae7050cf84ea685b662cc156abc6d30981b611e99dfbc73ee1ba5d6
MD5 b0b6eb448ac2aba5efd677d17f2191ef
BLAKE2b-256 b11749ebf2ed0a9b1e4726b99ef0398c9a72614d166dde4b4730e7eeb95dd6e0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.69.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 06f6d90c05a3a27b195141ecaa9fe5f564bb639de59d414ce579e8a09761e293
MD5 99d59857104c1eaf352f5eee1142563e
BLAKE2b-256 9b176e6850906bcb5ada5e554d64f12c38d72e1f62f6c668fe6095d343245d94

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.69.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.69.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.69.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 827616e061fb21cab3a2579a673b48070e12821431a2835e09930555c9276e44
MD5 0bf14bb0b5ec318221a96fb9ddb73cff
BLAKE2b-256 16362c680d1f1d8d393eeedddcd0170a2a777533c7a3f10acf1f4f8159359c65

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.69.0-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 9334e002342e7d5e7bb3acf11a7ff94dca28e3aff78ac042918506926c84918a
MD5 f478527aeea712808deac53b303338e3
BLAKE2b-256 e15f6d3ad6f44c2f721b883740383ec25db6a6634c741fa4b9942bd8ef668355

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.69.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 9240c96a65e1099e9c0158cf3ac7cb3016567cd6c32aa53f24f132bd5aa5c7ad
MD5 a5a1e134e334b51218a59df019d4c68d
BLAKE2b-256 7b87da528d9db221fa15f6c6045bab20123ad98155c74c9d5097a80c8604e013

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.69.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.69.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.69.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 3bcc4eb2d9f704014f370b8b8ba6e090d939fa371ae59baed218adb6efeaa84b
MD5 dacf8e1622ffec392c34ec32ce663d12
BLAKE2b-256 740bd5494f6ddf1668034d35ec151540fcf85511d5d3eded2a86c470817aec57

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.69.0-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 11e20dd76124d80dbd532ef2ec48f820ef8469f186bece352ab56b4a2dafc3c9
MD5 469cffaf6ab2cdd88377f3396cedb86b
BLAKE2b-256 36808962cdb574107263bc59a7707f71611ab0151df9654e2a7c5e7013c991a1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.69.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 e00366c7ab317ce10e32cb59d12766e2cba1b87500826b3ee5943065f996e158
MD5 bfff042cc0c5d7a4db111af57cbaf374
BLAKE2b-256 27f0b87ee6bf0777c528f1048f9b154c40330711cb8772abb7964a1973b633b9

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.69.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.69.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.69.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 cf11189e68a7187c7b68612a2ea92992c3bbb612fa85e9d50cdd88151ac89560
MD5 e7319dcecdc234a3c675cdcd55430b94
BLAKE2b-256 40d0ec61befdab36e038abd7d3c4f28f955383371a293db68c9e5c61b6ddaddc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.69.0-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 4b1b659a78e01e1e2b677819403349344eaa97c02f6a1572e3b4eb029c714f61
MD5 d7dae3312935e8e7957818b9cef77c06
BLAKE2b-256 7d0740f26a80656008ae091d53d9d7d9abedc63c22faa80db5283f0419989c08

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.69.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 2a98102a76a06277ffd89ed7381c59217fe1a0c0026567d207b8e60a1511c370
MD5 2aadad36c6f57bec4430c4de1711cdb6
BLAKE2b-256 66dd6c1b7e7bb8090321bd9d2227349b2b79639a87993e5fade19a0001860519

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.69.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.69.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.69.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 bc6bd24bd92e00c356291425410f30a51b95232153f7311d1df15eb70dedc551
MD5 549100723f8a621d25061f1b149278e1
BLAKE2b-256 c2605373c685cf5441a6c80520a95944dbd49b2c0f68cf6b067bfd1e35d5b837

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.69.0-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 f132c70766659cb2f172bd896656cd98c7dd4cb5fd5694c32cfcb197a99deec2
MD5 c0896432dddfca205bf1841ae10a5b24
BLAKE2b-256 165825286cee21ef5a22edd7823a7c78b8f9f0cb09e5b888785b5a38400d23be

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: openbricks-1.69.0-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.69.0-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 0a70a0ff8a57e0298625aab4ab0017569ac8b80d7d67709bd2ab6077e509a032
MD5 3210593190e96e5e6a0f56909019a50f
BLAKE2b-256 4ac19f78611c60faf69ce729a26abf7ca9e07c0622d218f46b9b906510a54d7d

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.69.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.69.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.69.0-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 bbeacd1a13b8ffe71b26018031b28b8d1075302ea4bfdb090ca443aece712ead
MD5 8d658e0da23c5513399f5c5183817ad1
BLAKE2b-256 195d5f90acf729d06caefe2861052606d3d78d1178fcdc2cf11fcfcd56e99c2f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.69.0-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 d77323d6c31264d395df0427085ea7ba04f4446041994cdc3b23743e45178813
MD5 29c3a21d162601ef921198d24e9c9e8b
BLAKE2b-256 91f5fe29edb150946ef8b42e11e0081bea249f1544311652547b138f45b8fca5

See more details on using hashes here.

Provenance

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