Dev Loop
Developing on the Mac, running on the Pi. Goal: a loop where you never stand up. Standing in front of a camera 200 times to test a state transition is how projects die.
MacBook (dev) Raspberry Pi 4 (terminal) AI server (RTX 4000 Ada)
├ Cursor / editor ├ camera, mic, speaker, screen ├ agentic-orchestration
├ bridge (dev mode) ◄──► ├ comstar-audio ├ CodeProject.AI :32168
├ kiosk / Chrome ◄──► ├ Chromium kiosk ├ speech sidecars :8090/91
├ local STT/TTS ├ optional comstar-stt/tts └ (AO hello.speech)
└ test runners └ comstar-bridge (prod)
/etc/hosts (example):
192.168.89.34 comstar.lan comstar
10.0.10.16 ai-server.lan ai-server
~/.ssh/config:
Host comstar
HostName comstar.lan
User md-admin
IdentityFile ~/.ssh/id_comstar
ControlMaster auto
ControlPath ~/.ssh/cm-%r@%h:%p
ControlPersist 10m
LocalForward 9222 127.0.0.1:9222 # Chromium DevTools
LocalForward 8181 127.0.0.1:8181 # Dart VM service
LocalForward 5678 127.0.0.1:5678 # Python debugpy
LocalForward 8781 127.0.0.1:8781 # COMSTAR admin + Google OAuth
ControlPersist makes every make target ~15 ms instead of a full SSH handshake.
| Changing | Loop | Turnaround |
|---|---|---|
| Avatar / kiosk JS | Loop A — Mac Chrome → kiosk-dev | instant |
| Bridge / state machine | Loop B — bridge on Mac | ~2 s |
| Full Mac voice | Loop B+ — no Pi | seconds |
| Audio / wake on Pi | Loop C — audio-sync | ~8 s |
| Final check | Loop D — full deploy | ~40 s |
make kiosk-dev # :5173
# Pi Chromium → http://comstar-dev.lan:5173/?bridge=ws://comstar-dev.lan:8777make bridge-dev
# Pi: stop local bridge; point audio at ws://comstar-dev.lan:8778Security gate: LAN bind requires COMSTAR_ENV=dev + comstar.dev.yaml + dev.lan_token. See Security.
make stt-dev
COMSTAR_ENV=dev make bridge-dev
make kiosk-devmake audio-sync
make wake-sweep FILE=fixtures/room_60min.wav # offline ROC on Macmake deployHighest-leverage tool. Full page: Admin Console.
The bridge always serves http://127.0.0.1:8781/admin/ (production and
dev). Google OAuth shares :8781 at /oauth/google/*. Open on the Mac:
make admin # via LocalForward 8781
# LAN: http://<pi-ip>:8781/admin/?token=<COMSTAR_ADMIN_TOKEN>Status / health: attention state, identity, session/Reach, kiosk/audio WS, sleep, CPU/mem, AO/CPAI probes. Live emblem matches the hallway panel.
Actions: restart bridge / audio / kiosk / stt / health / all; sleep / wake; reboot (typed confirm).
Logs: SSE journalctl --user tail (fetch + X-Comstar-Lan-Token).
Dev inject (only when COMSTAR_ENV=dev): synthetic events into the same
handle(Event) entry point as hardware, tagged src: "injected".
| Button | Injects |
|---|---|
| Person enters / leaves |
PersonDetected / PersonAbsent
|
| Recognise as… | FaceRecognized |
| Unknown face | FaceUnknown |
| Fire wake word | WakeWord |
| Speak… (text box) |
TranscriptReady — skips mic and STT |
| Playback ended | PlaybackEnded |
See Runbook § Dev event injection.
- Chromium:
chrome://inspect→localhost:9222 - Dart VM:
make bridge-pi-debug→ DevTools URL - Python:
make audio-debug→ attachlocalhost:5678
make logs # everything
make logs F=attention # evt prefix
make logs TURN=t_01J8XYZ # one turn
make logs-export SINCE="1 hour ago" > /tmp/run.jsonl
python scripts/latency_report.py /tmp/run.jsonlmake test # T0-T2 local
make test-integ # T3 real AI server
make test-hw # T4 on Pi via ssh
make soak # T5 24hmake dev-full # bridge + fake camera + fake mic + fake kioskmake doctorChecks SSH, Pi disk/temp, toolchain versions, CPAI CUDA, AO flags, STT/TTS, camera/mic, ports, clock skew < 1 s.
doctor · dev-full · bridge-dev · kiosk-dev · audio-sync · stt-dev · deploy · rollback · logs · logs-export · admin · test · test-integ · test-hw · soak · wake-sweep · latency · enroll · pi-shell
/opt/comstar/
├── releases/<timestamp>/
├── current -> releases/...
├── config/comstar.yaml
└── models/
make deploy flips current, restarts units, auto-rolls back if any unit fails within 30 s.
