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.58.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.58.0-cp313-cp313-win_amd64.whl (3.2 MB view details)

Uploaded CPython 3.13Windows x86-64

openbricks-1.58.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.58.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.58.0-cp312-cp312-win_amd64.whl (3.2 MB view details)

Uploaded CPython 3.12Windows x86-64

openbricks-1.58.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.58.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.58.0-cp311-cp311-win_amd64.whl (3.2 MB view details)

Uploaded CPython 3.11Windows x86-64

openbricks-1.58.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.58.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.58.0-cp310-cp310-win_amd64.whl (3.2 MB view details)

Uploaded CPython 3.10Windows x86-64

openbricks-1.58.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.58.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.58.0-cp39-cp39-win_amd64.whl (3.2 MB view details)

Uploaded CPython 3.9Windows x86-64

openbricks-1.58.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.58.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.58.0.tar.gz.

File metadata

  • Download URL: openbricks-1.58.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.58.0.tar.gz
Algorithm Hash digest
SHA256 3f056f901b11380b7893ef856c7a92a980ad676a845220c2a5bbef4b62d53471
MD5 bbfc06dbbdaf8879c46ee6d54f7edbbc
BLAKE2b-256 f41856a60c16fedabb2f60b98f3cdcc575372ff4a7af144981245dc54dda4734

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.58.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 297f7117b669b6c1507fe15dca398983759169ddc54e87bd67e96e56805c79d2
MD5 f4ed34c3ae17490276cf9784c0e8b96e
BLAKE2b-256 50044430c243461786101d3569e4a1c301c8a1357b9ca060fd4a71e5770196db

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.58.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.58.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.58.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 5bb8ef1578486557121232939efe0ee38ef7e64893bf0d451b7d0c95ef4e81b4
MD5 3891bc67eb553b6f43b7a3b641c55c60
BLAKE2b-256 4880978193ba2ec0454cf008a103edafc4c4a5954ae03c934ad4cad282aaac58

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.58.0-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 a8d2b749f940ec8cbd8fd02a791cef157017d7c8940dda08e447c0a2d81d8fe9
MD5 d3f07eaa10d947724785472dca311178
BLAKE2b-256 c1097da11bb0fd0cb686a961aeb216289ab74e13daecc24f750951284f6e1501

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.58.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 e37841766137e27d8fccae1563371279f4c9b947c95261f9a218a7924fa3f72d
MD5 80f83f17294e3db1d8bcca3af1db22d3
BLAKE2b-256 11a9aacd1094acbb5256ff61c48da5042de7c390b29b541ec68dbc394f49b10b

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.58.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.58.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.58.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 fc6b5c90ab07ad95095f592a46428127b844f9fd871feafa9584890ac089bb41
MD5 a52f35e919561ed0bef9d3dce57c792e
BLAKE2b-256 adc42fd4175f73973199e2ea73d1edf05731e53aef85cd071a489f6191636408

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.58.0-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 7748e7f27254b510cd686d9071311a10a92eee15573e0f70b1aabca13176b7d9
MD5 293f2d5ba30e42f3c892879abf1d15ee
BLAKE2b-256 20e818b456988d4167ae408d545e0207940460799cf8c2c208f6239686c189a1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.58.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 651784e24489a67bee814829b047ca74c11c7cc86617d4b5d88f5f3d11d5efb1
MD5 a9a9980da8fe33d43551975377868bfb
BLAKE2b-256 6d0b00e7a52e34cc60b523167f5a88b6ba7f215488419a802c0ee9344ec9f68a

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.58.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.58.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.58.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 941f634acfac38186a8238dc17853ff89ebfa33239c7f2b8b1e57b6a039d144a
MD5 aec1c0032ec556695bb423760f7a4492
BLAKE2b-256 0a17107a4e5b785809b75bec5953839de3bcbc174d0193a77a8f5f44db88cd6e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.58.0-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 2d8cd3cc37d704e0e470a125cff2047c26f85be508297fd39a7501650cf4f69e
MD5 4ee84d9bb448f98386665a21c9ad2cec
BLAKE2b-256 0a28d21e6f2c543857b373e427f2ad982bf89a1720f44c3a4d012f08855cd80d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.58.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 67636211313abe2a01eb2b458f517513231d3c3bb2c8e92bc4304bfefaee4bcd
MD5 08c1255e6eeba2b27194ab127525e168
BLAKE2b-256 b7d7810d2cc348b1f8e011f7c1cbbc9eb5b197b0afdae27ecc9858df7282ee93

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.58.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.58.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.58.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 655544f99ea1fb7a8e23d2a86d276141dba43823633fece83c48cf9d927c42b9
MD5 dd02c7fec17767410b4eb3fd6b12de53
BLAKE2b-256 e0b4fd9e558af8548cb0c3669d57033b888f1083828d1d6064a15b84f1a3e8fa

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.58.0-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 26b42cf4ca741413dbe85324b66b3b4f3b62c47fdbd897f3514441962b3f5e8e
MD5 aa5ea56910fb0a4b63cbff6d552b3832
BLAKE2b-256 5c540e671388703dee45cd56016fdf087301712564301bf2977d7896c5f494fc

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: openbricks-1.58.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.58.0-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 0403afc3554e2ecd05d5fa7f59113c8cf6499e2363d587d8c8454e94af58284c
MD5 cde8cecff8650c387bac6a20470d079b
BLAKE2b-256 a48263c3a76daa23c4e2f8cce796ba210546926e30657c7e4a53996333401eec

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.58.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.58.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.58.0-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 daff8102d06c1d006e808661332fdd6b208497aa36ac99079e347b50408a646a
MD5 a9a1c89128c7724966e2b6b73f72aaa7
BLAKE2b-256 938fece776228ab32a66441bb1472014ad9cb7462bb8aa61dcfca1f689a1df51

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.58.0-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 649dfb7fbdc1655cdd5d25229b58becf796a9f514b882d070544912aef64e75f
MD5 d0b993f32c9af2f7c2287d1806e447aa
BLAKE2b-256 93d0e99e9424effa7b94ca3c488f0fef5e61d80937147a48478d610e29531481

See more details on using hashes here.

Provenance

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