openbricks 0.10.2__tar.gz

openbricks-0.10.2/CHANGELOG.md

@@ -0,0 +1,97 @@
+# openbricks — host-tooling changelog
+
+Versions the unified `openbricks` PyPI package (CLI + MuJoCo sim).
+Firmware versions are tracked separately on the `v*` tag namespace.
+
+## 0.10.2 — sdist-only publish (PyPI manylinux requirement)
+
+The 0.10.1 publish failed at the upload step:
+
+    400 Bad Request: Binary wheel
+    'openbricks-0.10.1-cp311-cp311-linux_x86_64.whl' has an
+    unsupported platform tag 'linux_x86_64'.
+
+PyPI requires Linux wheels to be tagged ``manylinux*``, built inside
+the ``quay.io/pypa/manylinux2014`` Docker image (or via
+``cibuildwheel``). The CI's ``python -m build`` on a stock Ubuntu
+runner produces ``linux_x86_64`` wheels, which PyPI rejects.
+
+Quick fix: publish ``--sdist`` only. Users ``pip install openbricks``
+get the source distribution and compile the native extension on
+first install (slower, but gcc + python headers are typical on
+Linux/macOS dev machines). Multi-platform manylinux wheels are a
+follow-up.
+
+No functional changes vs. 0.10.0 / 0.10.1 — same code, just shippable.
+
+## 0.10.1 — sdist build fix (no functional changes)
+
+Fixes a build failure that prevented 0.10.0 from publishing:
+`python -m build` runs `setup.py` inside an isolated environment
+that can't reach `../../native/user_c_modules/openbricks/`. The
+sdist now bundles the synced cores via `MANIFEST.in`, and
+`_sync_cores()` falls through cleanly when the upstream isn't
+available (sdist build context). Regression test in
+`tests/test_sdist_build.py` builds a fresh sdist and asserts every
+shared core is inside.
+
+If you saw a 0.10.0 install fail, install 0.10.1 instead — it's the
+same code, just shippable.
+
+## 0.10.0 — unification
+
+The host CLI (`openbricks-dev`) and the MuJoCo simulator
+(`openbricks-sim`) are now a single `openbricks` PyPI package with
+optional `[sim]` extra. One install, one console script, every
+subcommand under `openbricks`.
+
+### New install commands
+
+```
+pip install openbricks            # CLI only (lightweight)
+pip install 'openbricks[sim]'     # CLI + MuJoCo physics
+```
+
+### Breaking changes
+
+- **Console script renamed.** `openbricks-dev <subcmd>` →
+  `openbricks <subcmd>`. The old binary is gone in 0.10.0.
+- **Sim subcommand.** `openbricks-sim <subcmd>` → `openbricks sim
+  <subcmd>`. Same arguments, dispatched via passthrough to the sim's
+  CLI when the `[sim]` extra is installed.
+- **PyPI distribution names.** Users on `openbricks-dev` and
+  `openbricks-sim` should `pip uninstall openbricks-dev openbricks-sim`
+  and `pip install 'openbricks[sim]'`.
+- **Release-tag namespace.** `openbricks-dev/v*` → `openbricks/v*`.
+  Firmware tags `v*` are unchanged.
+
+### What did NOT change
+
+- The Python module names: `openbricks_dev` and `openbricks_sim`
+  stay as they are. The firmware-side `openbricks` package on the
+  hub (drivers, robotics, native cores) is also imported on the host
+  by the sim's driver shim — collapsing the host CLI's module name
+  to `openbricks` would shadow it.
+- Subcommand argument grammars: `flash` / `list` / `run` / `upload` /
+  `stop` / `log` / `sim {preview,run}` accept the same flags as before.
+- The codecov flag names (`openbricks-dev`, `openbricks-sim`) — the
+  CI workflow uploads coverage under both flags from the unified job
+  so the dashboard split stays meaningful.
+
+### Migration guide
+
+```bash
+# Uninstall the legacy split packages.
+pip uninstall openbricks-dev openbricks-sim
+
+# Install the unified package. Drop the [sim] if you only need flash + run.
+pip install 'openbricks[sim]'
+
+# Update your shell aliases / scripts:
+#   openbricks-dev flash …  →  openbricks flash …
+#   openbricks-sim run …    →  openbricks sim run …
+```
+
+The legacy `openbricks-dev` PyPI project is frozen at 0.9.x — its
+last release will carry a deprecation notice in the description. No
+new versions will be published under that name.

openbricks-0.10.2/MANIFEST.in

@@ -0,0 +1,22 @@
+# Files that need to land in the sdist tarball but aren't covered by
+# ``setuptools.packages.find`` (which only catches ``*.py`` inside
+# the package directories).
+
+# The CPython extension's C source (sibling to the package).
+include native/openbricks_sim_native.c
+
+# Shared cores synced from the firmware's user_c_modules. Without
+# these in the sdist, ``setup.py``'s isolated build environment
+# can't find them (the firmware tree is two levels up, outside the
+# sdist root). ``_sync_cores()`` populates this directory before
+# the sdist is built; including it here lets the wheel-build step
+# (which runs from the unpacked sdist) compile cleanly.
+recursive-include native/_shared *.c *.h
+
+# WRO worlds + small examples — useful for users who want to load a
+# world without a repo checkout.
+recursive-include worlds *.xml *.png README.md
+recursive-include examples *.py
+
+# CHANGELOG so the migration guide ships with the wheel.
+include CHANGELOG.md

openbricks-0.10.2/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: openbricks
+Version: 0.10.2
+Summary: openbricks — host-side CLI + MuJoCo-backed simulator for the openbricks MicroPython firmware. Flash, list, run, upload, log; ``openbricks sim`` for the physics simulator.
+Author: openbricks contributors
+License: MIT
+Project-URL: Homepage, https://github.com/1e0ng/openbricks
+Project-URL: Source, https://github.com/1e0ng/openbricks
+Project-URL: Issues, https://github.com/1e0ng/openbricks/issues
+Project-URL: Releases, https://github.com/1e0ng/openbricks/releases
+Keywords: openbricks,micropython,robotics,esp32,ble,bluetooth,pybricks,lego,firmware,simulation,mujoco,wro
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: bleak>=0.22
+Requires-Dist: esptool>=4.7
+Requires-Dist: mpremote>=1.23
+Provides-Extra: sim
+Requires-Dist: mujoco>=3.2; extra == "sim"
+Requires-Dist: numpy>=1.24; extra == "sim"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: build; extra == "dev"
+
+# 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.
+
+## Install
+
+Recommended — with [`pipx`](https://pipx.pypa.io/) 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.
+
+## 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 `pybricks-dev 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-dev
+PYTHONPATH=. python -m unittest discover -s tests -t .
+```
+
+No real hardware needed — `esptool`, `mpremote`, and `bleak` are mocked.

openbricks-0.10.2/README.md

@@ -0,0 +1,103 @@
+# 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.
+
+## Install
+
+Recommended — with [`pipx`](https://pipx.pypa.io/) 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.
+
+## 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 `pybricks-dev 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-dev
+PYTHONPATH=. python -m unittest discover -s tests -t .
+```
+
+No real hardware needed — `esptool`, `mpremote`, and `bleak` are mocked.

openbricks-0.10.2/examples/color_drive.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MIT
+"""
+Drive forward and stop on a coloured zone — using the firmware
+``TCS34725`` driver unmodified.
+
+Run with::
+
+    openbricks-sim run examples/color_drive.py \\
+        --world wro-2026-elementary --viewer
+
+The driver shim replaces ``openbricks.drivers.tcs34725.TCS34725``
+with a sim-aware class that raycasts down from the chassis camera
+and returns the floor's material colour. From the script's point
+of view, the same ``rgb()`` / ``ambient()`` API is in use.
+
+Drive forward in 5 mm increments (open-loop wheel speed); poll the
+sensor each chunk; stop when ``ambient()`` drops below 30 — typical
+threshold for "we're over a dark zone".
+"""
+
+from openbricks.drivers.tcs34725 import TCS34725
+from openbricks.drivers.jgb37_520 import JGB37Motor
+from openbricks.robotics.drivebase import DriveBase
+from machine import I2C
+
+
+i2c    = I2C(0, scl=22, sda=21, freq=400_000)
+sensor = TCS34725(i2c=i2c, address=0x29)
+
+m_left  = JGB37Motor(in1=12, in2=14, pwm=27,
+                     encoder_a=18, encoder_b=19)
+m_right = JGB37Motor(in1=13, in2=15, pwm=26,
+                     encoder_a=20, encoder_b=21)
+db = DriveBase(m_left, m_right,
+               wheel_diameter_mm=60,
+               axle_track_mm=150)
+db.settings(straight_speed=120)
+
+print("starting RGB / ambient:", sensor.rgb(), sensor.ambient())
+
+# Up to 30 hops × 5 mm = 150 mm forward, stopping if we hit a dark
+# zone. On the empty / standalone world there's nothing dark to find,
+# so the loop runs to completion; on the WRO mat it stops when the
+# camera passes over a coloured mission area.
+for hop in range(30):
+    db.straight(5)
+    r, g, b = sensor.rgb()
+    a = sensor.ambient()
+    print(f"  hop {hop}: rgb=({r}, {g}, {b}) ambient={a}")
+    if a < 30:
+        print("  dark zone detected — stopping.")
+        break
+
+print("ending pose:", robot.chassis_pose())  # noqa: F821

openbricks-0.10.2/examples/repeat_mission.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: MIT
+"""
+Reset + retry — demonstrate ``robot.reset()`` for iterating on a
+mission script in one sim process.
+
+Run with::
+
+    openbricks-sim run examples/repeat_mission.py --no-shim --world empty
+
+Drives the chassis forward 200 mm five times in a row, resetting
+between attempts and printing the final position each time. Useful
+template for tuning a mission: adjust your code, re-run the same
+script — no need to relaunch the sim.
+"""
+
+# noqa: F821 — ``robot``, ``drivebase``, ``left``, ``right`` come
+# from openbricks-sim's ``run`` command (see cli.cmd_run).
+
+NUM_ATTEMPTS = 5
+DISTANCE_MM  = 200.0
+SPEED_MM_S   = 100.0
+
+
+for attempt in range(NUM_ATTEMPTS):
+    robot.reset()                                          # noqa: F821
+    drivebase.straight(distance_mm=DISTANCE_MM,            # noqa: F821
+                       speed_mm_s=SPEED_MM_S)
+    robot.run_until(drivebase.is_done, timeout_s=5.0)      # noqa: F821
+    x, y, yaw = robot.chassis_pose()                       # noqa: F821
+    print(f"attempt {attempt}: pose=({x:.0f}, {y:.0f}, {yaw:.1f})")
+
+print("done.")

openbricks-0.10.2/examples/scored_mission.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: MIT
+"""
+Drive into a target zone — scored.
+
+Run with::
+
+    openbricks-sim run examples/scored_mission.py --no-shim --world empty
+
+Demonstrates the mission-scoring helpers:
+
+  * ``robot.chassis_in_box(...)`` — axis-aligned membership.
+  * ``robot.chassis_in_circle(...)`` — circular membership.
+  * ``robot.distance_to(...)`` — Euclidean distance.
+  * ``robot.heading_aligned_with(...)`` — yaw within tolerance.
+
+Sweeps over a few cruise speeds, scoring each attempt. Useful as a
+template for tuning a real WRO mission against a stable rubric.
+"""
+
+# noqa: F821 — ``robot``, ``drivebase`` come from openbricks-sim's
+# ``run`` command (see cli.cmd_run).
+
+
+# Target: a 100 mm × 100 mm box centred at (200, 0) — i.e. the
+# robot should end up between 150 and 250 mm forward of spawn.
+TARGET_X_MIN = 150.0
+TARGET_X_MAX = 250.0
+TARGET_Y_MIN = -50.0
+TARGET_Y_MAX =  50.0
+TARGET_CX    = (TARGET_X_MIN + TARGET_X_MAX) / 2.0
+TARGET_CY    = (TARGET_Y_MIN + TARGET_Y_MAX) / 2.0
+
+
+def score(robot):
+    """Combined score: 100 if in the box AND aligned, otherwise
+    a falloff based on distance from the target centre."""
+    in_zone = robot.chassis_in_box(
+        TARGET_X_MIN, TARGET_Y_MIN, TARGET_X_MAX, TARGET_Y_MAX)
+    aligned = robot.heading_aligned_with(0.0, tolerance_deg=15.0)
+    if in_zone and aligned:
+        return 100
+    d = robot.distance_to(TARGET_CX, TARGET_CY)
+    return max(0, int(100 - d / 5))   # rough falloff: lose 1 point / 5 mm
+
+
+for speed in (60.0, 80.0, 100.0, 120.0, 150.0):
+    robot.reset()                                                # noqa: F821
+    drivebase.straight(distance_mm=200.0, speed_mm_s=speed)      # noqa: F821
+    robot.run_until(drivebase.is_done, timeout_s=5.0)            # noqa: F821
+    s = score(robot)                                             # noqa: F821
+    x, y, yaw = robot.chassis_pose()                             # noqa: F821
+    print(f"speed={speed:5.0f} mm/s -> score={s:3d}, "
+          f"pose=({x:6.1f}, {y:5.1f}, {yaw:5.1f}°)")

openbricks-0.10.2/examples/wall_avoid.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: MIT
+"""
+Drive forward; stop on a wall — using the firmware HCSR04 driver.
+
+Run with::
+
+    openbricks-sim run examples/wall_avoid.py \\
+        --world wro-2026-elementary --viewer
+
+The driver shim replaces ``openbricks.drivers.hcsr04.HCSR04`` with a
+sim-aware class that raycasts forward from the chassis ``chassis_dist``
+site. From the script's POV the same firmware ``distance_mm()`` is
+in use.
+
+Polls the sensor every 50 ms (sim time, via ``time.sleep_ms`` which
+the shim patches to step the runtime). Stops when distance drops
+below 200 mm — typical "robot is about to hit a wall" threshold.
+"""
+
+import time
+
+from openbricks.drivers.hcsr04 import HCSR04
+from openbricks.drivers.jgb37_520 import JGB37Motor
+from openbricks.robotics.drivebase import DriveBase
+from machine import Pin
+
+
+sensor = HCSR04(trig=18, echo=19, timeout_us=30_000)
+
+m_left  = JGB37Motor(in1=12, in2=14, pwm=27,
+                     encoder_a=20, encoder_b=21)
+m_right = JGB37Motor(in1=13, in2=15, pwm=26,
+                     encoder_a=22, encoder_b=23)
+db = DriveBase(m_left, m_right,
+               wheel_diameter_mm=60,
+               axle_track_mm=150)
+
+print("starting distance:", sensor.distance_mm())
+
+# Drive forward at 100 mm/s open-loop; poll the sensor; stop when
+# anything inside 200 mm shows up. The ``-1`` "no echo" result
+# means we keep going.
+m_left.run_speed(180.0)
+m_right.run_speed(180.0)
+
+for tick in range(200):    # up to 10 s of sim time
+    time.sleep_ms(50)
+    d = sensor.distance_mm()
+    if d != -1 and d < 200:
+        print(f"wall at {d} mm — stopping.")
+        break
+    if tick % 5 == 0:
+        print(f"  {tick * 50} ms: distance = {d}")
+
+m_left.brake()
+m_right.brake()
+print("ending pose:", robot.chassis_pose())  # noqa: F821

openbricks-0.10.2/examples/wander.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT
+"""
+Tiny example: drive a square with the default chassis.
+
+Run with::
+
+    openbricks-sim run examples/wander.py --world wro-2026-elementary --viewer
+
+The CLI pre-builds a ``SimRobot`` and exposes ``robot``, ``drivebase``,
+``left``, ``right`` in this script's globals — same names you'd use
+on real hardware after::
+
+    from openbricks.robotics.drivebase import DriveBase
+    drivebase = DriveBase(left, right, wheel_diameter_mm=60, axle_track_mm=150)
+
+A driver-shim layer that lets a single script target *both* targets
+unmodified lands in Phase C3.
+"""
+
+# noqa: F821 — ``robot``, ``drivebase``, ``left``, ``right`` come
+# from openbricks-sim's ``run`` command (see cli.cmd_run).
+
+# Sanity-print the starting pose so a user running with --viewer can
+# see the script ran.
+print("starting at:", robot.chassis_pose())  # noqa: F821
+
+# Drive a 200×200 mm square, pausing briefly at each corner.
+SIDE_MM   = 200.0
+TURN_DEG  = 90.0
+SPEED     = 100.0
+TURN_RATE = 90.0
+
+for i in range(4):
+    drivebase.straight(distance_mm=SIDE_MM, speed_mm_s=SPEED)        # noqa: F821
+    robot.run_until(drivebase.is_done, timeout_s=5.0)                # noqa: F821
+    drivebase.turn(angle_deg=TURN_DEG, rate_dps=TURN_RATE)           # noqa: F821
+    robot.run_until(drivebase.is_done, timeout_s=5.0)                # noqa: F821
+
+print("ended at:  ", robot.chassis_pose())  # noqa: F821

openbricks-0.10.2/examples/wander_hardware_style.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: MIT
+"""
+Drive a square — using the *firmware* APIs.
+
+Run with::
+
+    openbricks-sim run examples/wander_hardware_style.py \\
+        --world wro-2026-elementary --viewer
+
+This script imports from ``openbricks.drivers.*`` and
+``openbricks.robotics.*`` exactly as a real-hardware ``main.py``
+would. The driver-shim layer (``openbricks_sim.shim``, installed by
+the ``run`` command) routes those imports through to MuJoCo:
+
+  * ``machine.Pin`` / ``machine.PWM`` are no-op fakes — the wiring
+    arguments below are ignored, but the imports succeed.
+  * ``openbricks._native.Servo`` + ``DriveBase`` bind to the default
+    chassis's MuJoCo motor / encoder slots (chassis_motor_l/r).
+  * ``time.sleep_ms`` is patched to step the sim, so the firmware
+    drivers' busy-wait loops on ``is_done`` advance physics each
+    iteration without changes.
+
+Same source on hardware and in the sim — that's the point.
+"""
+
+from openbricks.drivers.jgb37_520 import JGB37Motor
+from openbricks.robotics.drivebase import DriveBase
+
+
+m_left  = JGB37Motor(in1=12, in2=14, pwm=27,
+                     encoder_a=18, encoder_b=19,
+                     counts_per_output_rev=1320)
+m_right = JGB37Motor(in1=13, in2=15, pwm=26,
+                     encoder_a=20, encoder_b=21,
+                     counts_per_output_rev=1320)
+
+db = DriveBase(m_left, m_right,
+               wheel_diameter_mm=60,
+               axle_track_mm=150)
+db.settings(straight_speed=180, turn_rate=120)
+
+for _ in range(4):
+    db.straight(150)   # mm
+    db.turn(90)        # body degrees, positive = left
+
+print("done. chassis pose (mm, mm, deg):", robot.chassis_pose())  # noqa: F821