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

Uploaded CPython 3.13Windows x86-64

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

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

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

Uploaded CPython 3.12Windows x86-64

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

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

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

Uploaded CPython 3.11Windows x86-64

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

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

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

Uploaded CPython 3.10Windows x86-64

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

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

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

Uploaded CPython 3.9Windows x86-64

openbricks-1.64.1-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.64.1-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.64.1.tar.gz.

File metadata

  • Download URL: openbricks-1.64.1.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.64.1.tar.gz
Algorithm Hash digest
SHA256 3f552caa63dca34cf5ddc5a0bff159976e90fbc4d789c8454c2d0b0249fab435
MD5 47401f9cb7ca787629eb0b91c550f8a3
BLAKE2b-256 1297ccb304ca6e34e5192a0bbcf029f94830090558c1eeb541479d933c33b827

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.64.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 c16b3b2900083a57b952e7b350849ddd56cdf9eadb4f0946a14d0d931330ff70
MD5 02bd3b6acbee703b23a6f642242df2f3
BLAKE2b-256 4ab70001f0f6a4b0ba96e08dcc5b809048ba4ebec39965fc0d958556f3c57393

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.64.1-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.64.1-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.64.1-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 74fcad0d7d743a7926be2b2bfd3bd4d570f492077b899f9c277c41d39f6d279a
MD5 4b1193b00c38864ceb3c3112002a7ef8
BLAKE2b-256 5767ff6d92d838417dc01b2690b6cba07aca0f958a4ec04641463b26b8bed12c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.64.1-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 33d59a5903d0620f46683fab1de7ef520ae77fa2eaf50661d321900df637399c
MD5 38008a6d590f615ebdbc0b4035956bdb
BLAKE2b-256 9b91471da4d6287efc919b503317a6c0cf745a309797c3ece90cfe92d6aaaaef

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.64.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 01d91f1eb681a8189121a67e4a30de28e4c2d26624fef68583f007fee0e7095d
MD5 61ea3ad0d3efa46aa538e839688e0d27
BLAKE2b-256 e296a9e5203a0c117a5a1ae9212c7a70d93c0fa27711437e90d63090272866c9

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.64.1-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.64.1-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.64.1-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 dc62ee6b1d0064b6bc4694043ec159e601484a6d7c4989f6c3e1b2c6ab37b444
MD5 d89685d746cadb8cc9d3c2459b746019
BLAKE2b-256 b26ce9e7facf6102a07feb43ceb598ee0c62e1bcc822e548b915e807808b3be8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.64.1-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 407e8c96761a32c4adafd560f101c09342d768d5f6ef2a960fd34fa7f469fb50
MD5 b4948e62769b89a91a41fd6ff087e26f
BLAKE2b-256 bf3bb9de4d094799d3d6670affb341731b74222bbf6cb7b93e5948b2ee578ac5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.64.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 7e2bfbb193675b535971c64855f932b21e808ae466b3897102ab23ad09eb41fa
MD5 f39d6e702682dcdaae1f84facdc69584
BLAKE2b-256 5b3a8d5a71a29aa6c8bc0b87c3cdf2e19d0ccd144466467054d10da523a7cf72

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.64.1-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.64.1-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.64.1-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 349a82270c7fb5255747a81e7f4abaeb1863a6d62bfd1f59da1b60662d533d20
MD5 1c942acd160cb241353130e0541266d0
BLAKE2b-256 f4fdeb8ab5d506dde2a974f39835f2ec0da1b8c55128f7c7dddf713939ec8ccd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.64.1-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 42ba8b77be529e30d83d2282ddcce7ee23285fd97f8e590a57610e50e60bb419
MD5 0275163bb3ef6b7846b110dd158100f5
BLAKE2b-256 8ec9cca2563b925725b65b704ba798fa31cee86e32ced8a87499aba28b7d6c78

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.64.1-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 2cb36097f7afa4e6d84c69e76be10a8f3e80bcf18a37eaf937ed3640cfcc1700
MD5 2c566142084ef068a14e1347b5aef627
BLAKE2b-256 a579878420a5c4776ade67a6171c9a34046cd5bff566ffd2f7410ffaf44e3a66

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.64.1-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.64.1-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.64.1-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 0330a6d956636fd0a5adf47eebf85208cecd3e8c19a4894ee223a6187e5b257f
MD5 f47f644944dbef835a041b04ad4cdead
BLAKE2b-256 dc102cb57613b8ef4572e18fa76401ab26bb4e8c191f4e072b845a76a3abe68f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.64.1-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 e8028c15d1572e33b94713e73e3d1f9ef8c6c9750843a936a402ade8392261a1
MD5 6d2d85fcf1bcd4377462ebda675277b2
BLAKE2b-256 91bf4cdc3ebd1e0b36c1b312bb9d925f4ba92aaaa0a342209052b37cd5b0d347

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: openbricks-1.64.1-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.64.1-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 c71782b35c27264d0fe5c316273023889e62c27f6136040154d16988b5dcb293
MD5 f12c33b22479966b3cdd2e0b0da13067
BLAKE2b-256 57ebcd37bdcc10b651fc12210644722c56cffbf123919592ec75852c76f9e72a

See more details on using hashes here.

Provenance

The following attestation bundles were made for openbricks-1.64.1-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.64.1-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for openbricks-1.64.1-cp39-cp39-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 a89785da33e7b7d35e0922e13a0b648d274026afc3516712bec00653f4e10110
MD5 e67d2d2a81c7c5fb07dd9e190bc44ef2
BLAKE2b-256 0e25b65f25193522210820e669dc04fdb8cb323bf93e85ed4a31bc8797efac62

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for openbricks-1.64.1-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 b019f9d4cc72351daaf394f0927d1848788a430d6252c6472fef97f142940161
MD5 2625eef4b31a729da93bf7570e031b7d
BLAKE2b-256 3540d82a1c7d6657b57a0af08cfd013e18302cd90051805556b8b1bb67339834

See more details on using hashes here.

Provenance

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