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.60.0.tar.gz (3.4 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.60.0-cp313-cp313-win_amd64.whl (3.2 MB view details)

Uploaded CPython 3.13Windows x86-64

openbricks-1.60.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.3 MB view details)

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

openbricks-1.60.0-cp313-cp313-macosx_10_13_universal2.whl (3.2 MB view details)

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

openbricks-1.60.0-cp312-cp312-win_amd64.whl (3.2 MB view details)

Uploaded CPython 3.12Windows x86-64

openbricks-1.60.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.3 MB view details)

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

openbricks-1.60.0-cp312-cp312-macosx_10_13_universal2.whl (3.2 MB view details)

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

openbricks-1.60.0-cp311-cp311-win_amd64.whl (3.2 MB view details)

Uploaded CPython 3.11Windows x86-64

openbricks-1.60.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.3 MB view details)

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

openbricks-1.60.0-cp311-cp311-macosx_10_9_universal2.whl (3.2 MB view details)

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

openbricks-1.60.0-cp310-cp310-win_amd64.whl (3.2 MB view details)

Uploaded CPython 3.10Windows x86-64

openbricks-1.60.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.3 MB view details)

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

openbricks-1.60.0-cp310-cp310-macosx_10_9_universal2.whl (3.2 MB view details)

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

openbricks-1.60.0-cp39-cp39-win_amd64.whl (3.2 MB view details)

Uploaded CPython 3.9Windows x86-64

openbricks-1.60.0-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (3.3 MB view details)

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

openbricks-1.60.0-cp39-cp39-macosx_10_9_universal2.whl (3.2 MB view details)

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

File details

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

File metadata

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

File hashes

Hashes for openbricks-1.60.0.tar.gz
Algorithm Hash digest
SHA256 23290cbb4d0e8500cec6f25c647da429de63c4d8443b99e639d100336ebb59f1
MD5 45e4ffc97a2cae6aa68442bdb37f0739
BLAKE2b-256 f8a301f654d4e594062c358dfdd9cd1a6cc9fa2dbed7dc0f70c8356098057c74

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.60.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 d78d76ff551a78022b0829f3536cbd260c410853bcc01c5eb29f4b3b24985e59
MD5 c4e9e0f7e4da35e5619c7cddc236b355
BLAKE2b-256 bdd67b2cf46be27bc72eb553df308a2d26be7e11062ad85b0896cb00327ebbff

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.60.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.60.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.60.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 1c432f58689961b2a82a1704190936c31fcd84ca8189d8853322f761995cac2f
MD5 dd6626ecbd8e13d2b667cb125ca940b7
BLAKE2b-256 f9c3de91b0fec5e67c10e541a2233a365509c5df5e97a8e1d28e674b19e215cc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.60.0-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 cb459fb1ab630e9e53c1a3874e139ec6f9dd5c5a57720995000eae13ba649e97
MD5 9987c3bd4e95f994a308a9c2e80e2122
BLAKE2b-256 af118323b66b081865e29437a2f4c7aa3b78abbb2c9229fd7609aa177ad12b0b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.60.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 142cf3a0ad0c8e12a2e969a731f79cda342387f5def59aef740005fe2faada1d
MD5 f92f0d1bc0ce67d35b601706ac90998b
BLAKE2b-256 8521bcd97773d4b029737eb80a98481851a7fa6cb565d3018093045ada7e463c

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.60.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.60.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.60.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 97946f5e209ca7cf7432d12b2a9bc492479805672fd90213887498b6a5a27bc5
MD5 b59d15ecc6ca3525b9ec93927f5bd4d3
BLAKE2b-256 e6ad2cc3345c535b1b1a2c23193357b4faa770a1fd59c18bd3d1e569e67c5f3b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.60.0-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 6bce95ca76af7a48c57507c4041c16a83ab53b0d5aaba2e7d8021d41af5e7b2f
MD5 dee71b9ab95503f6f1d53172cafb9080
BLAKE2b-256 23a46ae1407849ffc57514aff995d681e6e39c33315c6f96becee215e160d755

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.60.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 a1f736d526d4bf4715c32d7bb0f591c6dddc7b6cac7bacceabf94df9f4869092
MD5 bc9ce4c111271f7616b94f7190943afd
BLAKE2b-256 1cc9e7a1b454de808f3416dbdd2014aa2f0f0f165f2df03ed99e30d024920756

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.60.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.60.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.60.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 485238c64bb701bab65f8ff702b5c6eaf0a892de4f6d32bc3b5caad8c02f0ee4
MD5 7a1d4938874ae7177631decb4e8e5d99
BLAKE2b-256 8485871273a08020415f4ca9cbbcf64007ac040a988b45b19c0d637f04bc4ce5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.60.0-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 e2f39900fd3b574fc474123df94d05983d6cc675c56efa8cb591b38016ad3cd7
MD5 288c7eb4a725ad4adfcc88b47ddceb32
BLAKE2b-256 4faf7645cf5ac35b87ce70b9cc9a734d6e136bf839c43f437a1e59f68f88675a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.60.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 16d2d9407ab427c14521ea2ef1ad8e186a529e011b0577091f679985ed0802b0
MD5 e5cbb20e4d5177404a43317c85c8f6e5
BLAKE2b-256 d3164fb5c5dc163c3dad7a98b0b1b4ac9d9410ce38bd48a59d71d621a786468f

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.60.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.60.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.60.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 7963a7c326a533401a3b46753f553f40881ac692ce770c0339c4939206366a1a
MD5 442dcff202a799072121d9b46eb3d2f8
BLAKE2b-256 3c3f8821677f6e0a8b13d5b50e4dcb3f13f87beaa03e0ab916cfbf2aa36c68ab

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.60.0-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 f482a18174a24f79c036f254be8e592ecf9ace388de69b515c7bcc4d81e0d89f
MD5 cdde7a8a70940944b8d97e8f21a80310
BLAKE2b-256 d1f99ee4e6fe134c93fbcc44ce7dc43a1f0f0c787623df61eee27ad6e7dbef32

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: openbricks-1.60.0-cp39-cp39-win_amd64.whl
  • Upload date:
  • Size: 3.2 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.60.0-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 b3810907d30349040fdaf05313f658bec86630b6017bd9308ce613c38b20fb2d
MD5 908bd45ab8df0e8a7fac03a16384eeeb
BLAKE2b-256 369109684642cedd3de0f3b6d1f4ca2d88508bbf233bbf0badc92d57bd0a8870

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.60.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.60.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.60.0-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 4bf59dd89497be53070c250ee807675c64af185f521deb317e6867a893c342fc
MD5 2ea78eaa7eb50aec08a9865151071aaf
BLAKE2b-256 3995fc3f655bac4fec00e4b77d2166ada5d744f6fbe1365a20f45835d98123c4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.60.0-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 42561de895f7fe214b7ed48ca5ad9cd63ddd67e40d764d678a5c0d5c9d633326
MD5 0111a59246f59c62afb2bf5eb4597008
BLAKE2b-256 0102ad276d96033c04364e35973cc3d1d3659562ceb04db459832f32670b1764

See more details on using hashes here.

Provenance

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