# Next Session: Resume Sunday Demo — Phase 2.2 + Phase 3 + Hailo Ball Tracker

> **Supersedes** `docs/NEXT-SESSION-SUNDAY-DEMO-FIX-V4.md`.
> Session 54 completed Phase 2.1, keyboard fix, drive buttons, Chase Ball PID sign fix, and P-gain tuning.

## TL;DR

Session 54 (2026-04-11) shipped 8 commits (`b8b0831` → `6bc5e2c`). Chase Ball
forward/backward and left/right axes fixed (`car.translation(-dx, -dy)`),
car_x_pid P tuned 0.15→0.25, raw drive buttons added, keyboard persistence
fixed, BadRequest log noise cleaned up. Blue ball chasing verified working
(camera tracks + car follows). Red ball unreliable due to pink camera tint.

This session has two tracks:
1. **Track A** — finish Sunday demo verification (Phase 2.2 + Phase 3)
2. **Track B** — replace Hiwonder LAB detection with Hailo YOLO ball tracking

## Git state at handoff

- Branch: `main` at commit `6bc5e2c`
- Pushed to `origin/main`
- Titan: at `6bc5e2c` (pulled during session 54)
- Pi: ColorTracking.py deployed via rsync (matches repo vendor copy, md5 `81ee9eb...`)
- telegram-bot: restarted with BadRequest fix (pid 2023 on Titan)

## Pi state

- `turbopi-server`: active, idle (demo stopped at end of session 54)
- `lab_config.yaml`: session 53 calibration (red/blue/green LAB ranges)
- Power: `throttled=0x0`, stable since session 52 rewire
- **Car is on its back** — put it right-side up before testing

## Key files modified in session 54

| File | Commits | What changed |
|------|---------|-------------|
| `services/telegram-bot/car_demo_handler.py` | b8b0831, 3cbdd74, e9b7f3f, 6bc5e2c | keyboard reattach, drive buttons, BadRequest catch |
| `services/telegram-bot/tests/test_car_demo_handler.py` | b8b0831, 3cbdd74, e9b7f3f | 43→53 tests |
| `vendor/turbopi/Functions/ColorTracking.py` | dd22adf, d8771b8, a9f14d3 | `-dx,-dy` sign fix, P 0.15→0.25 |
| `scripts/deploy-turbopi.sh` | 99f17a9 | now rsyncs vendor/Functions/ to Pi |

## Track A — Sunday Demo Verification (~1 hour)

### Pre-flight (2 min)

```bash
# Put car RIGHT-SIDE UP first!
ssh pi hostname && ssh pi "systemctl is-active turbopi-server"
curl -s http://192.168.68.61:8080/health | jq '{status, demo_mode, demo_phase, safety_daemon_healthy, throttled}'
```

### Phase 2.2 — What Do I See? (5 min)

Spawn menu and tap 📸 What Do I See?. Pass = specific object description within
5s, not generic "I see a room". This exercises Pi → Titan → Gemma 4 vision.

```bash
ssh titan 'UUID=$(python3 -c "import uuid; print(uuid.uuid4().hex[:8])"); echo "{\"car_demo_menu\": true}" > ~/.her-os/annie/task_results/car-demo-menu-$UUID.json'
```

If fails: check Titan vLLM logs, `/photo/describe` endpoint.

### Phase 3 — Motor Demos (45 min, car right-side up, HIGH supervision)

**Safety:** Hailo safety daemon DISABLED during demos. Rajesh keeps finger on
🛑 Stop Demo. Read §10 safety briefing in plan before guests arrive.

Test order:
1. **🔵 Chase Blue Ball** — verified working in session 54. Quick re-confirm right-side up.
2. **🟢 Chase Green Ball** — should work (same code path, different LAB range).
3. **🔴 Chase Red Ball** — likely flaky due to pink camera tint. Test but expect failure.
4. **🚧 Obstacle Dodge** — sonar-based, no vision. Quick test.
5. **🚦 Traffic Cop** — depends on red LAB detection. May fail for same reason as red ball.
6. **📱 QR Navigator** / **🔍 Color Spotter** — 5 min each, drop if broken.

**Between every test:** verify `/health` returns idle:
```bash
curl -s http://192.168.68.61:8080/health | jq '{demo_mode, demo_phase, safety_daemon_healthy}'
```

**If car_x_pid P=0.25 still loses tracking:** try P=0.20 (more conservative).
See `~/.claude/projects/.../memory/project_turbopi_motor_mapping.md` for the
full tuning history and what was tried.

**Fallback menu (§3d):** if 2+ demos broken, use `MENU_DISABLED_DEMOS` filter
(already designed in plan §3d, zero test impact).

### Phase 3 exit criterion

At least 6 of the original 8 demos working, OR menu reduced to working subset
with a doc note explaining drops.

## Track B — Hailo YOLO Ball Tracker (new feature, ~2-3 hours)

### Motivation

Hiwonder's LAB-based detection (ColorTracking.py) is fragile:
- Pink camera tint from ultrasonic LED makes red ball undetectable
- LAB ranges need per-scene calibration
- No robustness to lighting changes

The Pi already has Hailo8L accelerator + `yolov8s_h8.hef` model loaded for
the safety daemon. YOLO detects "sports ball" (COCO class 32) regardless of
color, lighting, or white balance.

### Architecture

Replace the LAB detection in the `run(img)` function with a Hailo inference
path. Keep everything else: PID loops, servo tracking, chassis translation,
`-dx,-dy` sign fix, `wheel_en` gating.

```
Current:  run(img) → LAB threshold → contour → center_x, center_y, radius
Proposed: run(img) → Hailo YOLO → bbox → center_x, center_y, radius
```

### Key questions to resolve

1. **Can Hailo run alongside the demo subprocess?** The safety daemon uses Hailo
   during normal operation but is DISABLED during demos. So the HEF device is
   free. The demo subprocess just needs to load the model.
2. **Latency budget:** LAB detection is ~2ms per frame. Hailo YOLOv8s inference
   is ~8-12ms on Hailo8L. Still well within the 33ms frame budget (30 fps).
3. **Color discrimination:** YOLO detects "sports ball" generically. To chase a
   SPECIFIC color (red/blue/green), we'd need a post-detection color check:
   crop the bbox, compute mean LAB, compare to target color range. Hybrid
   approach: YOLO for robust detection + LAB for color ID on the detected region.
4. **Where does the Hailo inference code live?** Options:
   - Patch ColorTracking.py directly (vendor file, messy)
   - New file `HailoTracking.py` in vendor/turbopi/Functions/ (cleaner)
   - New script registered in `_headless_runner.py`

### Suggested approach

Create `vendor/turbopi/Functions/HailoTracking.py` that:
- Imports hailo_platform SDK (already installed on Pi for safety daemon)
- Loads `yolov8s_h8.hef` at init
- `run(img)` → Hailo inference → filter for "sports ball" class → bbox → compute
  center_x, center_y, radius (from bbox diagonal)
- Optional color filter: crop bbox, mean LAB, check against `lab_config.yaml`
- Same PID/servo/translation interface as ColorTracking.py

Register in `_headless_runner.py` as a new script name, and add new demo
buttons to `car_demo_handler.py` (or replace existing Chase Ball buttons).

### Research needed

- Read the safety daemon code (`services/turbopi-server/safety_daemon.py`) to
  understand how it loads and runs Hailo inference — reuse the same pattern
- Check `hailo_platform` Python API on Pi: `ssh pi "python3 -c 'import hailo_platform; print(hailo_platform.__version__)'"` 
- Check if the HEF model file is accessible during demos: `ssh pi "ls -la /usr/share/hailo-models/yolov8s_h8.hef"`

### Files to create/modify

| File | Action | What |
|------|--------|------|
| `vendor/turbopi/Functions/HailoTracking.py` | CREATE | New ball tracker using Hailo YOLO |
| `services/turbopi-server/pi-files/_headless_runner.py` | MODIFY | Add HailoTracking init sequence |
| `services/telegram-bot/car_demo_handler.py` | MODIFY | Add Hailo Chase Ball button(s) |
| `services/telegram-bot/tests/test_car_demo_handler.py` | MODIFY | Tests for new buttons |

## Known issues carrying forward

1. **§5 guard-loop `jq -e` predicate** uses wrong field names (`.phase` vs `.demo_phase`,
   `.frame_grabber_healthy` doesn't exist). Correct predicate:
   `.demo_mode==false and .demo_phase=="idle" and .safety_daemon_healthy==true`
2. **Red ball LAB detection unreliable** due to pink camera tint from ultrasonic LED.
   Post-Sunday fix: black electrical tape over the LED.
3. **Cosmetic:** Telegram BadRequest on no-op edits — now at DEBUG level (commit 6bc5e2c).

## Prompt for next session

```
Resume Sunday demo fix. Read docs/NEXT-SESSION-SUNDAY-DEMO-FIX-V5.md.

Session 54 shipped 8 commits (keyboard fix, drive buttons, Chase Ball
PID sign fix, P-gain tuning, BadRequest fix). Blue ball chasing works.
Car is on its back — put it right-side up first.

Two tracks:
A) Finish demo verification: Phase 2.2 (What Do I See?), Phase 3
   (motor demos right-side up). ~1 hour.
B) Replace Hiwonder LAB detection with Hailo YOLO ball tracker.
   Robust to lighting/color tint. ~2-3 hours.

Plan: ~/.claude/plans/polymorphic-riding-turtle.md
Motor mapping: memory/project_turbopi_motor_mapping.md
Camera gotchas: memory/project_turbopi_camera_gotchas.md
```