Installation

Two things get installed: the host tooling on your computer (a CLI that flashes firmware and talks to hubs over BLE) and the firmware on the hub itself.

1. Install the host tooling

$ pipx install 'openbricks[sim]'   # CLI + MuJoCo simulator

or, lighter:

$ pipx install openbricks          # CLI only (flash / run / log)

pip install works too; pipx is recommended on modern macOS / Linux to avoid the “externally managed environment” error. The package is on PyPI: https://pypi.org/project/openbricks/.

The [sim] extra adds mujoco (~50 MB, native OpenGL) and numpy. If you only want to flash and run code on real hardware, skip it — openbricks sim … will print an install hint instead of crashing.

2. Get a firmware image

Grab a prebuilt image from the Releases page:

  • openbricks-esp32s3-firmware-<version>.bin — ESP32-S3 boards (primary target)

  • openbricks-esp32-firmware-<version>.bin — classic ESP32 boards

(You can also build the firmware from source.)

3. Flash the hub

Connect the board over USB, then flash and name the hub in one step:

$ openbricks flash \
    --name RobotA \
    --port /dev/cu.usbserial-0001 \
    --firmware openbricks-esp32s3-firmware-latest.bin

  • --name is the BLE advertising identifier you’ll use later with openbricks run -n …; pick a unique one per hub.

  • --port depends on your OS: /dev/ttyUSB0 on Linux, /dev/cu.usbserial-* on macOS, COM5 on Windows.

  • Add --chip esp32s3 if auto-detection misses.

Skip this step entirely if you only want to run code in the simulator.

4. Run your first program

$ openbricks list                  # find your hub over BLE
$ openbricks run -n RobotA main.py # push a script and stream its output

See the CLI reference for every command, and Examples for programs to start from.

Troubleshooting

  • Hub doesn’t show up in openbricks list — BLE may be toggled off. Short-press the Bluetooth button (GPIO 5 by default); on the ESP32-S3 the onboard LED turns blue when BLE is on, yellow when off. See openbricks.hub.ESP32S3DevkitHub.

  • Serial port permission errors on Linux — add yourself to the dialout group (sudo usermod -aG dialout $USER) and re-login.

  • Flash succeeds but the program doesn’t start — check the run log with openbricks log -n RobotA for the traceback of the last run.