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

Uploaded CPython 3.13Windows x86-64

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

Uploaded CPython 3.12Windows x86-64

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

Uploaded CPython 3.11Windows x86-64

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

Uploaded CPython 3.10Windows x86-64

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

Uploaded CPython 3.9Windows x86-64

openbricks-1.66.3-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.3-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.3.tar.gz.

File metadata

  • Download URL: openbricks-1.66.3.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.3.tar.gz
Algorithm Hash digest
SHA256 7a46d9ad59fc834ad582319badebfa4860b6c36edccb36a327a82642829187c2
MD5 6daa5affc45d99d60ebced3ca121e06f
BLAKE2b-256 d6f5976c73d3a75d0edbbb9f7b56a464dc5d6dfbaa0561a97e178d8b1d2daf08

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.3-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 010371057059ca3e8b158abbbe445648a4fdaa16efec7533961341b958149b08
MD5 03fef44ba100b59cae254f4047b8f16d
BLAKE2b-256 056bbdeb985f5fedb6450922ba2e9751afd512f498f0e1b329659d67facbd41c

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.66.3-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.3-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.3-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 58a4f25e3b5e301973f50de423f5c2d5dfd1e5b1840357f5502f2e154c1f109d
MD5 92de0fb652966af3d51bdb6f117f2188
BLAKE2b-256 3c8a844f95a7fb8a7d7e8cd9be7bb1b70ea61136e5698a48dabb5b842eba0dfc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.3-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 b20dfa43d056901ae52ed5f073b65023d0533ef7eb1fee6bec929cc2ec3cd859
MD5 504128fa74e59f81fd9f8e5fdfbeb293
BLAKE2b-256 b14bbf797cd15106acdc96009c983a76473f9b8fd48aa841cdbf92a913dea26d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.3-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 f223488f9db8241fee405d1802b8e130a98f381eeb348845279a3697d79b2fc5
MD5 323cb558a2690169e191e7493377c622
BLAKE2b-256 b93f66c3637937f81261af4c74e4da207f15191845d44968f256a85cf1d20bce

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.66.3-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.3-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.3-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 4906f4c03edaeb8ce2e7820ea273ae8b1af519f029194698f67ddce4ff19f592
MD5 64431af0d9981a21500ebeaef837a3b7
BLAKE2b-256 535f5038f45bedb16a9a088f3b5f707472f8f303625bc312de3f734b3bbebb31

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.3-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 8ae99c502e362f8a05471650f3b0c98e1f4c3efa5dabea13d6097edacd5df46f
MD5 0903157af0fc46a98ff78000f7c652b1
BLAKE2b-256 9628d3488f4729dddeedc6ffb2e018d754d9bc3bcc0588ac4b252fc9c104fa67

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.3-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 037923a7fc51e17c95caf020595893cc3dcad6e4ed9d15879a975d1fee06824c
MD5 0ca9ea4ae231c9750714f0dbbc2f8a94
BLAKE2b-256 b0a0de836ce1512331e0067959f259d03536c7375f975d975fdf57b270b8720f

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.66.3-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.3-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.3-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 659bdec26def6e5a9abe310ac9f5b80307f2a59b8c6db05b943caceaa90f3327
MD5 520f71b88880372120b550df6ee8f17d
BLAKE2b-256 7a4e9a8e95bb6e41a1eeb2bf2c3a5439427606958976e04f3facd596b30c3464

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.3-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 402df487bf168b2248faf47ebb9bfa8c8384b6fd4b215781c9618862cdc09ef4
MD5 013126a2122b7a79abf4f8ef360b4508
BLAKE2b-256 ecac87af9857245a33c5da07c42043d3eef42f035f68bc65096c394b08b77879

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.3-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 f16d4dda3bdacb009274b19b3b4d89bc6c5c71e966232d42f23d70905e9f981a
MD5 dd674a73ad4bff6ca5cb88d1c6918f45
BLAKE2b-256 6a5d5351fe09a97eda2b714a48d954abe1d692f4f43ffa90bb2f5e1ca5a577c2

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.66.3-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.3-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.3-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 333f8a18e2344f3825060dada22386e696ff52ba171bece85ce52e1aaed16e50
MD5 46cfd34992f5f924d14d42ff6b9cae9f
BLAKE2b-256 62ce28d380d86e3303105eff1ef7ed02b7ab41f7045459e183e8f3261a72a1ae

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.3-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 728f4e94dc1dc1b9c9ff140f2b61fbfb954a59108f2c96e340be49a38f9030b8
MD5 b5ae6178a0210209ca3ebca96482d945
BLAKE2b-256 7b8aeb3dafe1f4cd76fe96fc3172a6db62fe9e2ca3001217d635e09f1ba7a136

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: openbricks-1.66.3-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.3-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 1fa79b212736ae61d80ff8aec5335959bb84deab0842f17e0370339f3f3b957a
MD5 4a5beb731b68a9501ba2e053480d6d06
BLAKE2b-256 ddbb4b8fb49d60c8b23c74766206b58d442c909c99fcbe06327cdf39354bbfb1

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.66.3-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.3-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.3-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 2ede499fb886ea337ab7817e047e226dc6c5be7ca17bfeb8e53ef4d1b92ee2c2
MD5 081a33838d92eed98f83f78c8fa0674c
BLAKE2b-256 3d02d8b8314d5bd681315656280863495ac800d4fa1233423fae6d0966998d0e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.66.3-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 620ac5087fba24cba2d573707b00f06c740d37c0a18c2a55f7c44b451aa85295
MD5 70d0ba887e94a3888f11cc5296498b10
BLAKE2b-256 6898d7a30318f254509c22ac891127d2e22bffa24d761cc39530f8f77f14157a

See more details on using hashes here.

Provenance

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