docs(spec): networked control surface (renderer/controller split) — session 0019
v1 hardware step: split the simulator into a laptop RENDERER and a separate touch CONTROLLER over wifi/LAN. Server-authoritative SessionState + SSE push; one /api/control contract any "control source" speaks (iPad web twin now, Arduino later). Live knobs (Left/Right/Mood) vs transitional controls (Altitude, Content) with per-knob transition state + renderer settled-ack. Reframes ROADMAP sub-project 4 and absorbs sub-project 3's serial-input slice. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
BenStullsBets
@@ -0,0 +1,311 @@
|
||||
# Networked Control Surface — design
|
||||
|
||||
**Status:** proposed
|
||||
**Date:** 2026-06-26
|
||||
**Session:** 0019
|
||||
**Supersedes/reframes:** ROADMAP sub-project 4 (Arduino Firmware / control panel) and
|
||||
the "serial input" slice of sub-project 3 (Player Runtime).
|
||||
|
||||
---
|
||||
|
||||
## 1. Goal
|
||||
|
||||
Split the existing simulator into a **renderer** (the laptop full-screen
|
||||
projection — "the experience") and a separate **controller** (a touch remote),
|
||||
talking over the local network, so the experience can be driven from a handheld
|
||||
device the way the real installation's panel drives its screen.
|
||||
|
||||
This is **v1 hardware**, deliberately simulator-friendly:
|
||||
|
||||
- The **laptop/computer renders** (no Raspberry Pi yet).
|
||||
- The controller is a **separate device** over **wifi** (LAN), not a USB-serial
|
||||
link to a Pi.
|
||||
- The controller is **prototyped as a web page** (an iPad/tablet/phone twin),
|
||||
and a **physical Arduino remote** drops in later as just another control source
|
||||
speaking the same contract.
|
||||
|
||||
Two goals, equally weighted (operator, session 0019): **decouple control from
|
||||
display cleanly**, *and* get the **handheld "stand back and drive it" feel**.
|
||||
|
||||
## 2. Core idea: one server of truth, interchangeable control sources
|
||||
|
||||
```
|
||||
┌──────────────────┐ POST /api/control ┌─────────────────────┐
|
||||
│ CONTROL SOURCE │ ───── (knob change) ────▶ │ FastAPI server │
|
||||
│ │ │ (laptop) │
|
||||
│ • iPad web remote│ ◀──── GET /api/state ──── │ ┌───────────────┐ │
|
||||
│ (v1) │ (sync on load) │ │ SessionState │ │
|
||||
│ • Arduino (later)│ │ │ controls + │ │
|
||||
└──────────────────┘ │ │ ring index + │ │
|
||||
│ │ transitions + │ │
|
||||
┌──────────────────┐ GET /api/events (SSE) │ │ seq (version) │ │
|
||||
│ RENDERER │ ◀═══ state/ring/mode ════ │ └───────┬───────┘ │
|
||||
│ laptop full- │ (live push) └──────────┼──────────┘
|
||||
│ screen │ │
|
||||
│ (the experience) │ ──── POST /api/render/event ────────▶│ (settled ack)
|
||||
└──────────────────┘ recompute RenderPlan + ring move
|
||||
```
|
||||
|
||||
- **Server** owns the single authoritative `SessionState` (current controls,
|
||||
altitude/ring index, per-field transition state, a monotonic `seq`). Every
|
||||
change recomputes the derived view and broadcasts it.
|
||||
- **Control source** = anything that `POST`s a control change. v1 has exactly
|
||||
one: the iPad web remote. A future Arduino is *another instance of the same
|
||||
role* — no new server concept.
|
||||
- **Renderer** = the laptop projection. It holds **no** input UI; it subscribes
|
||||
to the SSE stream and renders whatever state arrives. It is today's
|
||||
`simulator/static/index.html`, stripped of its sliders, given a `state`
|
||||
listener plus one small upstream ack channel.
|
||||
|
||||
The property that matters: controller and renderer are now **separate web pages
|
||||
off the same server**, decoupled exactly as a real installation's panel and
|
||||
screen are. (Chosen architecture: server-authoritative session + **Server-Sent
|
||||
Events** push. SSE fits because the directions are asymmetric — the renderer only
|
||||
*receives*, the control source only *sends* — so no bidirectional WebSocket is
|
||||
needed. Alternatives considered and rejected: renderer polling — laggy/wasteful;
|
||||
peer-to-peer WebRTC — most plumbing and it breaks the clean single-contract seam
|
||||
that makes the Arduino a drop-in.)
|
||||
|
||||
## 3. Control surface: the five controls (the faithful twin)
|
||||
|
||||
The iPad remote is a **faithful on-screen twin** of the intended physical panel —
|
||||
what you like on the iPad is the spec for the Arduino panel. The control
|
||||
inventory is exactly what the sim exposes today:
|
||||
|
||||
| Control | Sim today | Physical form (later) |
|
||||
|---|---|---|
|
||||
| **Content** | 7-way `<select>` (video / audio+video / music+video / off / white noise / music / audio track) | rotary selector switch (7 pos) |
|
||||
| **Altitude** | endless circular dial — walks the 5 scales (cosmos→abyss), wraps | rotary encoder (endless, detented) |
|
||||
| **Left** (analytical) | slider 0–4 | knob/pot, 5 detents |
|
||||
| **Right** (dreamlike) | slider 0–4 | knob/pot, 5 detents |
|
||||
| **Mood** | slider −4…+4 (dark↔light) | center-detented knob |
|
||||
|
||||
(This is the original sub-project-4 inventory, *updated*: Dark+Light collapsed
|
||||
into one **Mood** knob in session 0013, and the **Altitude** encoder added in
|
||||
session 0018.)
|
||||
|
||||
## 4. Live vs. transitional controls (per-knob transition state)
|
||||
|
||||
The five controls split into two classes by how a **human** perceives the change:
|
||||
|
||||
- **Live controls — Left, Right, Mood.** The alteration engine treats these as
|
||||
`LIVE_UPDATE` (the WebGL Kuwahara dream + HUD overlay + color grade re-tune
|
||||
within a frame). Effectively instantaneous → these are *always idle*; the
|
||||
remote just shows the value.
|
||||
- **Transitional controls — Altitude, Content/mode.** These trigger a renderer
|
||||
animation that takes real, perceptible time: Altitude plays ring-transition
|
||||
clips (zoom/warp between scales); Content/mode does fade-to-black / crossfade.
|
||||
During that window the control is **busy**, and the control source must model
|
||||
that so its feedback is honest.
|
||||
|
||||
Per-transitional-control lifecycle:
|
||||
|
||||
```
|
||||
idle ──(source sends)──▶ pending ──(renderer starts)──▶ transitioning ──(renderer settles)──▶ idle
|
||||
```
|
||||
|
||||
- **pending** — set locally by the remote the instant the knob is turned
|
||||
(immediate tactile feedback before the server replies).
|
||||
- **transitioning** — the server flags the field once the renderer actually
|
||||
begins the animation; broadcast to *all* control sources.
|
||||
- **idle** — cleared when the **renderer acks completion** (the only party that
|
||||
knows real playback timing), with a server-side max-duration timeout as a
|
||||
safety net so a dropped renderer can't wedge a knob.
|
||||
|
||||
Hardware payoff: a physical Altitude encoder can light an LED while
|
||||
`transitioning`; the iPad twin shows the matching spinner/disabled-detent.
|
||||
|
||||
`SessionState` therefore carries
|
||||
`transitions: { altitude: idle|transitioning, content: idle|transitioning }`
|
||||
alongside the controls and `seq`. (Live controls need no entry.)
|
||||
|
||||
## 5. Server contract
|
||||
|
||||
Four endpoints carry the whole thing. The existing `/api/alteration`,
|
||||
`/api/ring`, `/api/ring/advance` remain as **internal helpers the server calls**;
|
||||
control sources never hit them directly.
|
||||
|
||||
### 5.1 `GET /api/state` — snapshot (sync-on-load / polling fallback)
|
||||
|
||||
```json
|
||||
{
|
||||
"seq": 42,
|
||||
"controls": { "content": "video", "left": 3, "right": 1, "mood": -2 },
|
||||
"altitude": { "index": 2, "scale": "forest", "clip_id": "forest_07" },
|
||||
"transitions": { "altitude": "idle", "content": "idle" },
|
||||
"render": { "plan": { }, "content": { "audio_source": null, "video": true } }
|
||||
}
|
||||
```
|
||||
|
||||
A control source GETs this on load to draw its knobs in the right positions; the
|
||||
renderer can use it to cold-start or resync after a reconnect.
|
||||
|
||||
### 5.2 `POST /api/control` — the one control-source contract
|
||||
|
||||
A partial patch — only the fields that changed:
|
||||
|
||||
```json
|
||||
{ "set": { "left": 4 }, "altitude_delta": 0 } // live knob
|
||||
{ "set": { "content": "off" }, "altitude_delta": 0 } // transitional (mode)
|
||||
{ "set": {}, "altitude_delta": -1 } // one encoder tick down
|
||||
```
|
||||
|
||||
Server applies it, bumps `seq`, recomputes, and:
|
||||
|
||||
- **live field** → broadcasts a `state` event immediately;
|
||||
- **transitional field** (a `content` change, or a non-zero `altitude_delta`) →
|
||||
computes the ring move / fade, marks that field `transitioning`, broadcasts a
|
||||
`ring` (or `mode`) event for the renderer to animate.
|
||||
|
||||
Returns the new snapshot (an immediate authoritative echo for the poster).
|
||||
Absolute `set` values make retries idempotent; `altitude_delta` is relative
|
||||
(encoder ticks) and the server coalesces rapid ticks via the existing
|
||||
`advance_ring` fast-spin logic.
|
||||
|
||||
### 5.3 `GET /api/events` — SSE stream (renderer subscribes)
|
||||
|
||||
Event types:
|
||||
|
||||
- `state` — full snapshot; sent on connect and on every live change.
|
||||
- `ring` — an altitude move: the transition clip(s) to play + the landed
|
||||
scale/clip. Renderer plays them, then settles.
|
||||
- `mode` — a content/mode change: the fade the renderer should run.
|
||||
- `ping` — keepalive.
|
||||
|
||||
The SSE event payloads reuse the existing serializers
|
||||
(`ring_move_to_dict`, `render_plan_to_dict`, etc.).
|
||||
|
||||
### 5.4 `POST /api/render/event` — the renderer's one upstream ack
|
||||
|
||||
```json
|
||||
{ "type": "settled", "seq": 42, "field": "altitude" }
|
||||
```
|
||||
|
||||
Sent when the renderer finishes a transition. Server flips that field `idle` and
|
||||
broadcasts a `state` so every remote clears its spinner. A server-side timeout
|
||||
(max transition duration + margin) clears it anyway if the renderer never acks.
|
||||
|
||||
### 5.5 End-to-end flow for one altitude tick
|
||||
|
||||
```
|
||||
iPad: turn dial → field=pending locally → POST /api/control {altitude_delta:-1}
|
||||
server: apply, seq++, transitions.altitude="transitioning"
|
||||
→ SSE "ring" to renderer → SSE "state" to all remotes (altitude busy)
|
||||
renderer: play transition clip(s), settle on forest_07
|
||||
→ POST /api/render/event {type:"settled", field:"altitude"}
|
||||
server: transitions.altitude="idle" → SSE "state" to all → iPad clears spinner
|
||||
```
|
||||
|
||||
### 5.6 Decisions flagged (not assumed silently)
|
||||
|
||||
- **Concurrency = last-write-wins.** Multiple control sources are allowed;
|
||||
per-field last write wins, `seq` orders everything. No locking in v1.
|
||||
- **No auth.** v1 trusts the LAN — any device that can reach the laptop can drive
|
||||
it. A room-token is deferred until wanted.
|
||||
|
||||
## 6. The two pages
|
||||
|
||||
### 6.1 Renderer — `/` (display), refactored from today's `index.html`
|
||||
|
||||
- **Removes** the input controls (the `<select>`, the Altitude SVG, the three
|
||||
sliders) and their handlers.
|
||||
- **Keeps** everything that draws the experience: the video element, the WebGL
|
||||
Kuwahara dream shader, the HUD/annotation + affect overlay, the
|
||||
ring-transition playback, the media preload pool, the crossfade-loop logic.
|
||||
- **Adds** a thin `state` client: open `EventSource('/api/events')`; on `state`
|
||||
apply controls→render live; on `ring` play the transition clip(s) then settle
|
||||
and `POST /api/render/event {settled}`; on `mode` run the fade. On (re)connect,
|
||||
pull `GET /api/state` to resync. SSE auto-reconnects, so a flaky link
|
||||
self-heals.
|
||||
- Runs full-screen on the laptop driving the projector; no keyboard/mouse needed
|
||||
once launched.
|
||||
|
||||
### 6.2 Controller — `/remote`, a new touch-first page (the faithful twin)
|
||||
|
||||
- The five controls laid out like the intended physical panel: **Content**
|
||||
selector, **Altitude** encoder dial (reuse the existing SVG dial component),
|
||||
**Left** / **Right** / **Mood** knobs.
|
||||
- On any input → `POST /api/control` with just the changed field. Live knobs post
|
||||
on drag; Altitude posts encoder ticks; Content posts on selection.
|
||||
- Per-knob transition state (§4): a transitional control goes **pending** on
|
||||
touch, reflects **transitioning** from the SSE feed, clears on **settled**.
|
||||
Altitude shows a settling indicator and its detents soft-lock (further ticks
|
||||
queue as the next target rather than stacking); Content shows the selection as
|
||||
pending until the fade completes.
|
||||
- It **also** subscribes to `/api/events` so it stays in sync with other
|
||||
sources (turn the future Arduino's knob and the iPad reflects it, and
|
||||
vice-versa). On load it GETs `/api/state` to draw current positions.
|
||||
- Touch-sized hit targets, no hover dependence, works in mobile Safari with no
|
||||
install.
|
||||
|
||||
## 7. The future-Arduino seam (contract only in v1)
|
||||
|
||||
No firmware in this feature, but the design **proves the seam** so sub-project 4
|
||||
is a true drop-in:
|
||||
|
||||
- **ESP32 (wifi Arduino)** → posts straight to `POST /api/control` over the LAN.
|
||||
Zero server change. Recommended hardware target when the time comes.
|
||||
- **Classic USB Arduino** → emits serial frames to a tiny `bridge.py` on the
|
||||
laptop that translates each frame into a `POST /api/control`. The old roadmap
|
||||
"3⇄4 serial framing contract" shrinks to *just* the Arduino↔bridge link; the
|
||||
renderer/server never know the difference.
|
||||
- Either way the Arduino sends **absolute pot values** (`set`) + **encoder
|
||||
ticks** (`altitude_delta`) — exactly the iPad's message shape.
|
||||
|
||||
This is what makes "faithful twin" real: the iPad and the Arduino are the same
|
||||
control source speaking the same contract.
|
||||
|
||||
## 8. Error handling / resilience
|
||||
|
||||
- **Renderer drops:** SSE auto-reconnects; on reconnect it GETs `/api/state` and
|
||||
resyncs. The per-field transition timeout clears any knob left `transitioning`
|
||||
by a renderer that vanished mid-animation.
|
||||
- **Controller drops / flaky wifi:** POSTs are fire-and-retry; absolute `set`
|
||||
values are idempotent, so a retried knob value is harmless. `altitude_delta` is
|
||||
the one relative input — on a failed POST the remote keeps the tick in its
|
||||
local pending target and resends rather than double-counting.
|
||||
- **No renderer connected:** the server still accepts control changes and holds
|
||||
state; a renderer that connects later catches up from the snapshot.
|
||||
- **Stale control source:** every event carries `seq`; a source ignores events
|
||||
older than what it has applied.
|
||||
|
||||
## 9. Testing (satisfies the mandatory pipeline tiers)
|
||||
|
||||
- **Pure unit** — a `SessionState` store in Python: apply patch → live vs.
|
||||
transitional classification; `altitude_delta` → ring move via the existing
|
||||
`advance_ring`; `seq` bump; transition flag set/clear; timeout. No I/O, tested
|
||||
like the rest of `player/`.
|
||||
- **API/contract** — `GET /api/state`; `POST /api/control` (live + transitional +
|
||||
bad input → 422); `POST /api/render/event` clears the flag; the SSE
|
||||
event-builder tested as a pure function.
|
||||
- **E2E (Playwright, required for the UI surface)** — open the renderer and
|
||||
`/remote` as two pages: move a live knob → assert the renderer's render
|
||||
updates; tick Altitude → assert a transition plays, the remote shows
|
||||
`transitioning`, then clears on settle.
|
||||
|
||||
## 10. Scope
|
||||
|
||||
**In v1:**
|
||||
|
||||
- Server `SessionState` + the four endpoints (`/api/state`, `/api/control`,
|
||||
`/api/events`, `/api/render/event`).
|
||||
- Renderer refactor to display-only + SSE client + settled ack.
|
||||
- The `/remote` iPad twin: the five controls + per-knob transition state.
|
||||
- Wifi/LAN only; laptop renders.
|
||||
|
||||
**Explicitly NOT in v1 (deferred):**
|
||||
|
||||
- Any Arduino/firmware (contract defined here; hardware later).
|
||||
- Bluetooth / USB transport.
|
||||
- Auth / room-token.
|
||||
- The Pi renderer.
|
||||
- Multi-room / multi-renderer fan-out (the SSE design allows it; not a v1 goal).
|
||||
|
||||
## 11. Roadmap impact
|
||||
|
||||
- **Sub-project 4** is reframed: the panel is now "any control source over the
|
||||
`/api/control` contract," not USB-serial-to-Pi first. The iPad twin is the v1
|
||||
deliverable; the Arduino is a later drop-in.
|
||||
- **Sub-project 3's "serial input" slice** is absorbed into a transport detail
|
||||
(the Arduino↔bridge link), no longer a Pi-coupled concern.
|
||||
- `ROADMAP.md` to be updated at implementation time.
|
||||
Reference in New Issue
Block a user