Better Robotics

Open a tab, pair a robot, ship code.

What this is

Open a Chrome tab. Pair a robot over BLE. Write JavaScript that drives it.

// Multi-robot is a forEach.
for (const r of robots) {
  await r.led(true);
  await r.move({ left: 30, right: 30, durationMs: 400 });
  await r.led(false);
}

• Browser is the IDE. Scripts panel + capability cards. localStorage is the file system; BLE is the runtime link.
• Models run in the browser too. Open-vocab detector runs client-side. No GPU server, no inference bill.
• Two authorable surfaces, co-equal: user code (you write JS) and Pip (a tool-using LLM with ask-human, currently Claude). Both bound by the same firmware safety floor.
• No backend, no accounts. Static-site dashboard; no data leaves the browser.

Architecture

┌──────────────────┐         BLE GATT (always on)          ┌──────────────────┐
│  Chrome browser  │ ◄────────────────────────────────────► │  Robot firmware  │
│  (Web Bluetooth) │   commands · state · ops · triggers    │  (ESP32 or Pi)   │
└──────────────────┘                                        └──────────────────┘
          ▲                                                           ▲
          ├─────────── WiFi (data plane, optional) ────────────────── ┤
          │   camera (WebRTC ↔ HTTP MJPEG, per-camera toggle)         │
          │                                                           │
          └─────── USB-C (recovery plane, last-resort, Pi only) ───── ┘
                    ECM ethernet · ACM serial console

• Control plane — BLE. Always on. Commands, telemetry, state changes, ops. ~1–3 Mbps, reliable, network-free. Pairing UI is the gatekeeper; no credentials cross the air.
• Data plane — WiFi, optional. Onboarded via BLE when needed. Carries video (per-camera toggle between WebRTC and HTTP MJPEG), large OTA, cloud LLM calls. Robots work fully without it.
• Recovery plane — USB-C, last-resort (Pi). Composite USB gadget (ECM + ACM serial) under its own systemd unit, independent of robot firmware. Dashboard exposes an xterm.js terminal over this.

Why BLE for control: classroom and demo WiFi rarely cooperates (blocked multicast, captive portals, client isolation). BLE sidesteps all three. Robot advertises on boot; laptop scans and sees every robot in the room.

Safety on disconnect. Actuator characteristics (motor, servo, pump, relay) ship with a firmware watchdog. Every write resets a timer; if no write lands in the window, firmware reverts to a safe default. Silence is the trigger, not a redundant radio.

Quickstart

Use it

1. Open better-robotics.github.io in Chrome or Edge.
2. Flash or prepare hardware:
   • ESP32 on USB: click Flash firmware — bins come from GitHub Pages, no local toolchain.
   • Pi 4 with a flashed SD card: click Customize card (or hit the URL with ?prepare) and point it at the mounted boot partition.
3. Click Scan, pair a robot, toggle LED, onboard WiFi, drive motors. Future updates go over BLE via Update firmware.

Develop locally

make setup          # one-time ESP-IDF + arduino-cli setup (macOS)
make flash          # build ESP32 firmware, upload over USB
make preview        # serve the dashboard at http://localhost:8000

Pi firmware is Python; see firmware/pi_robot/README.md for the SD-card prep flow and BLE service spec.

Commit and push. CI rebuilds firmware artifacts on firmware/** changes and commits them back; devices pick up new versions via OTA.

Repo layout

firmware/esp32_robot_idf/   ESP32 firmware (ESP-IDF)
firmware/pi_robot/          Raspberry Pi firmware (Python + bless)
docs/                     Dashboard — static ES modules, no build step
tests/                      Pure-function unit tests · make smoke
.claude/                    Agent + project context

ESP32 and Pi expose the same service UUID and characteristic UUIDs, so the dashboard talks to either without conditional logic. docs/ is the GitHub Pages publish root — the site is the directory, no build step. The dashboard is flat by convention — naming prefixes carry subsystem boundaries; see .claude/CLAUDE.md for the subsystem map.

Further reading

• Hardware guide — recommended boards, board-specific knobs, driver notes.
• Pi firmware — BLE service spec, SD-card prep details, Bookworm/Trixie troubleshooting.
• User code — how to write scripts in the browser; the robot API surface.
• Developer reference — URL flags, console handles, Chrome chrome:// diagnostic pages.

Browser support

Web Bluetooth: Chrome, Edge, Opera on desktop and Android. Not Safari. Firefox only behind a flag.

License

MIT.