Gooseberry

Local notification and control project for the StackChan named Gooseberry.

Layout

bridge/
  Local control plane. Receives harness events and broadcasts them to robot clients.

docs/
  Design notes and prototype plan.

firmware/StackChan/
  Fork/check-out of the upstream M5Stack StackChan firmware repo.

Quickstart

Start with the source-first setup in docs/quickstart.md. Security and network exposure notes are in docs/security.md.

Prototype Loop

Run the bridge:

./scripts/gooseberry bridge

Run the fake robot in another terminal:

cd bridge
go run ./cmd/fake-robot

Send a notification:

./scripts/gooseberry notify-test "Approve the pending command?"

The fake robot should print the event. On hardware, open AGENT.MONITOR and Gooseberry should react to the same event.

Harnesses can use the agent-facing command:

./scripts/gooseberry agent --harness codex --event needs_input --message "Approve the pending command?"

The hook contract is documented in docs/harness-integration.md.

Head Tracking

Run the bridge with tracking endpoints enabled:

GOOSEBERRY_TRACKING=1 ./scripts/gooseberry bridge

Flash the firmware and open AGENT.MONITOR on Gooseberry. In normal mode, and only while bridge head tracking is enabled, the app sends low-rate JPEG frames from the robot camera to the bridge over the existing robot WebSocket.

The bridge starts the macOS Vision tracker as a managed subprocess when tracking is enabled through ./scripts/gooseberry bridge. It runs laptop-side face detection against those frames and sends normalized face coordinates back to Gooseberry.

GOOSEBERRY_TRACKING=1 ./scripts/gooseberry bridge

The firmware only streams pictures and obeys the resulting tracking commands while head tracking is active. For a quick laptop-camera demo, use ./scripts/gooseberry vision-tracker --source mac.

To inspect the camera stream, face annotation, and calibration controls, print the local live-view URL:

./scripts/gooseberry live-view

Firmware

Firmware setup and ESP-IDF environment notes are in docs/firmware-setup.md.

The Gooseberry firmware app details are in docs/firmware-agent-monitor.md.

Build and flash the firmware with the repo wrapper:

./scripts/gooseberry build
./scripts/gooseberry flash

Internal packaging notes are in docs/release.md. Public binary releases are deferred until firmware has runtime pairing/configuration.