Dev Loop

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.

---

Three machines

  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)

---

0. Names and keys (once)

/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 8779 127.0.0.1:8779   # COMSTAR dev console / inject

ControlPersist makes every make target ~15 ms instead of a full SSH handshake.

---

1. The four loops

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

Loop A — kiosk

make kiosk-dev   # :5173
# Pi Chromium → http://comstar-dev.lan:5173/?bridge=ws://comstar-dev.lan:8777

Loop B — bridge on the Mac

make bridge-dev
# Pi: stop local bridge; point audio at ws://comstar-dev.lan:8778

Security gate: LAN bind requires COMSTAR_ENV=dev + comstar.dev.yaml + dev.lan_token. See Security.

Loop B+ — Mac browser voice

make stt-dev
COMSTAR_ENV=dev make bridge-dev
make kiosk-dev

Loop C — audio

make audio-sync
make wake-sweep FILE=fixtures/room_60min.wav   # offline ROC on Mac

Loop D — full deploy

make deploy

---

2. The dev console

Highest-leverage tool. Bridge serves control on :8779 (dev mode). Open on the Mac.

Left: live state ladder, identity/confidence/votes/TTL, camera thumbnail + YOLO box, mic meter, last transitions, latency spans.

Right: event injection 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

Minimal harness today: POST /inject — see Runbook. Full UI is M3.7.

---

3. Remote debugging

• Chromium: chrome://inspect → localhost:9222
• Dart VM: make bridge-pi-debug → DevTools URL
• Python: make audio-debug → attach localhost:5678

---

4. Logs

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.jsonl

---

5. Tests from the Mac

make test          # T0-T2 local
make test-integ    # T3 real AI server
make test-hw       # T4 on Pi via ssh
make soak          # T5 24h

---

6. Fake hardware

make dev-full   # bridge + fake camera + fake mic + fake kiosk

---

7. Preflight

make doctor

Checks SSH, Pi disk/temp, toolchain versions, CPAI CUDA, AO flags, STT/TTS, camera/mic, ports, clock skew < 1 s.

---

8. Makefile targets

doctor · dev-full · bridge-dev · kiosk-dev · audio-sync · stt-dev · deploy · rollback · logs · logs-export · console · test · test-integ · test-hw · soak · wake-sweep · latency · enroll · pi-shell

---

9. Deploy layout on the Pi

/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.

---

Related pages

• Runbook
• Security
• Getting Started
• Installation