robopark 2.8.7 → 2.8.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robopark",
-  "version": "2.8.7",
+  "version": "2.8.9",
   "description": "RoboPark fleet control CLI — set up, watch, and drive a fleet of talking robots. The operator front-end over the infinicode mesh.",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "infinicode": "^2.8.7"
+    "infinicode": "^2.8.9"
   },
   "keywords": [
     "robopark",

package/scheduler/main.py

@@ -107,6 +107,8 @@ class Device(BaseModel):
     motor_server_url: Optional[str] = None
     character_id: Optional[str] = None
     livekit_url: Optional[str] = None
+    video_device: Optional[str] = None
+    audio_device: Optional[str] = None
     status: str = "enrolled"  # enrolled, online, offline, disabled
     last_heartbeat: Optional[datetime] = None
     enrolled_at: Optional[datetime] = None
@@ -121,6 +123,8 @@ class DeviceCreate(BaseModel):
     motor_server_url: Optional[str] = None
     character_id: Optional[str] = None
     livekit_url: Optional[str] = None
+    video_device: Optional[str] = None
+    audio_device: Optional[str] = None
     notes: Optional[str] = None
     enrollment_token: Optional[str] = None  # if omitted, one is auto-generated
 
@@ -132,6 +136,8 @@ class DeviceEnrollRequest(BaseModel):
     motor_server_url: Optional[str] = None
     livekit_url: Optional[str] = None
     character_id: Optional[str] = None
+    video_device: Optional[str] = None
+    audio_device: Optional[str] = None
 
 class DeviceEnrollResponse(BaseModel):
     device_id: str
@@ -235,6 +241,8 @@ async def init_db():
                 motor_server_url TEXT,
                 character_id TEXT,
                 livekit_url TEXT,
+                video_device TEXT,
+                audio_device TEXT,
                 token_hash TEXT,
                 enrollment_token_hash TEXT,
                 status TEXT DEFAULT 'enrolled',
@@ -258,6 +266,19 @@ async def init_db():
                 expires_at TEXT NOT NULL,
                 created_at TEXT DEFAULT CURRENT_TIMESTAMP
             );
+
+            CREATE TABLE IF NOT EXISTS history_log (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                timestamp TEXT DEFAULT CURRENT_TIMESTAMP,
+                category TEXT NOT NULL,
+                entity_type TEXT,
+                entity_id TEXT,
+                action TEXT,
+                actor TEXT,
+                details TEXT
+            );
+            CREATE INDEX IF NOT EXISTS idx_history_category ON history_log(category);
+            CREATE INDEX IF NOT EXISTS idx_history_entity ON history_log(entity_type, entity_id);
         """)
         await db.commit()
 
@@ -269,6 +290,8 @@ async def init_db():
         for _table, _column, _coldef in (
             ("robots", "trigger_count", "INTEGER DEFAULT 0"),
             ("sessions", "joined_at", "TEXT"),
+            ("devices", "video_device", "TEXT"),
+            ("devices", "audio_device", "TEXT"),
         ):
             try:
                 await db.execute(f"ALTER TABLE {_table} ADD COLUMN {_column} {_coldef}")
@@ -432,6 +455,7 @@ async def robot_heartbeat(robot_id: str, ip_address: Optional[str] = None):
         )
         await db.commit()
     await broadcast("robot_heartbeat", {"robot_id": robot_id})
+    await _log_history("robot", "robot", robot_id, "heartbeat", "robot", f"ip={ip_address}")
     return {"status": "ok"}
 
 @app.post("/api/robots/{robot_id}/request-session")
@@ -446,11 +470,22 @@ async def request_session(robot_id: str,
         raise HTTPException(401, "Invalid or missing device token")
     async with aiosqlite.connect(DB_PATH) as db:
         db.row_factory = aiosqlite.Row
-        
-        # Check robot exists and is idle
+
+        # Check robot exists and is idle; auto-create a robot row for an enrolled
+        # device that has not yet appeared in the robots table.
         async with db.execute("SELECT * FROM robots WHERE id = ?", (robot_id,)) as cursor:
             robot = await cursor.fetchone()
-            if not robot:
+        if not robot:
+            async with db.execute("SELECT name FROM devices WHERE id = ?", (robot_id,)) as dc:
+                device_row = await dc.fetchone()
+            if device_row:
+                await db.execute(
+                    "INSERT OR IGNORE INTO robots (id, name, status) VALUES (?, ?, 'idle')",
+                    (robot_id, device_row["name"]),
+                )
+                await db.commit()
+                robot = {"id": robot_id, "name": device_row["name"], "status": "idle"}
+            else:
                 raise HTTPException(404, "Robot not found")
             if robot["status"] != "idle":
                 raise HTTPException(400, f"Robot is {robot['status']}, not idle")
@@ -498,6 +533,8 @@ async def request_session(robot_id: str,
         "server_id": server["id"],
         "session_id": session_id
     })
+    await _log_history("session", "robot", robot_id, "requested", "robot", f"session_id={session_id}, server={server['id']}, room={room_name}")
+
 
     # Mint a short-lived LiveKit token so the robot can join the room without
     # ever receiving the raw api_key/api_secret.
@@ -569,6 +606,7 @@ async def end_session(robot_id: str, reason: str = "silence"):
         await db.commit()
     
     await broadcast("session_ended", {"robot_id": robot_id, "reason": reason})
+    await _log_history("session", "robot", robot_id, "session_ended", "robot", f"reason={reason}, session_id={robot.get('current_session_id')}")
     return {"status": "ok"}
 
 @app.post("/api/robots/{robot_id}/trigger")
@@ -597,6 +635,7 @@ async def robot_trigger(robot_id: str,
         async with db.execute("SELECT trigger_count FROM robots WHERE id = ?", (robot_id,)) as c:
             row = await c.fetchone()
     await broadcast("robot_triggered", {"robot_id": robot_id})
+    await _log_history("robot", "robot", robot_id, "trigger", "robot", f"trigger_count={row[0] if row else None}")
     return {"status": "ok", "trigger_count": row[0] if row else None}
 
 # =============================================================================
@@ -629,6 +668,7 @@ async def add_server(server: LiveKitServer):
               server.gpu_vram_mb, server.max_sessions, server.status))
         await db.commit()
     await broadcast("server_added", {"server_id": server.id})
+    await _log_history("server", "server", server.id, "added", "operator", f"name={server.name}, url={server.url}")
     return {"status": "ok"}
 
 @app.delete("/api/servers/{server_id}")
@@ -638,6 +678,7 @@ async def remove_server(server_id: str):
         await db.execute("DELETE FROM livekit_servers WHERE id = ?", (server_id,))
         await db.commit()
     await broadcast("server_removed", {"server_id": server_id})
+    await _log_history("server", "server", server_id, "removed", "operator")
     return {"status": "ok"}
 
 @app.get("/api/servers/{server_id}/metrics")
@@ -805,6 +846,7 @@ async def end_web_session(session_id: str, reason: str = "disconnect"):
             await db.commit()
     
     await broadcast("session_ended", {"session_id": session_id, "reason": reason})
+    await _log_history("session", "session", session_id, "ended", "operator/web", f"reason={reason}, duration={duration}")
     return {"status": "ok"}
 
 def _session_latency_ms(started_at: Optional[str], joined_at: Optional[str]) -> Optional[int]:
@@ -846,6 +888,7 @@ async def session_joined(session_id: str,
         await db.commit()
     latency_ms = _session_latency_ms(session["started_at"], now)
     await broadcast("session_joined", {"session_id": session_id, "latency_ms": latency_ms})
+    await _log_history("session", "session", session_id, "joined", "robot", f"latency_ms={latency_ms}")
     return {"status": "ok", "joined_at": now, "latency_ms": latency_ms}
 
 # ── Back-compat: legacy web-client session token (ported from the deployed OLD
@@ -1089,6 +1132,7 @@ async def update_settings(payload: SettingsPayload):
     """Update scheduler settings (production mode, etc.)."""
     await set_setting("production_mode", "true" if payload.production_mode else "false")
     await broadcast("settings_changed", {"production_mode": payload.production_mode})
+    await _log_history("settings", "settings", "production_mode", "updated", "operator", f"value={payload.production_mode}")
     return {"status": "ok", "production_mode": payload.production_mode}
 
 @app.post("/api/settings/enrollment-token/rotate")
@@ -1097,8 +1141,28 @@ async def rotate_enrollment_token():
     token = secrets.token_urlsafe(24)
     await set_setting("default_enrollment_token", _hash(token))
     logger.info("Default enrollment token rotated")
+    await _log_history("settings", "settings", "default_enrollment_token", "rotated", "operator")
     return {"enrollment_token": token}
 
+@app.get("/api/history")
+async def get_history(category: Optional[str] = None, limit: int = 200):
+    """Audit / history log for devices, robots, sessions, previews and settings."""
+    async with aiosqlite.connect(DB_PATH) as db:
+        db.row_factory = aiosqlite.Row
+        if category:
+            async with db.execute(
+                "SELECT * FROM history_log WHERE category = ? ORDER BY timestamp DESC LIMIT ?",
+                (category, limit),
+            ) as c:
+                rows = await c.fetchall()
+        else:
+            async with db.execute(
+                "SELECT * FROM history_log ORDER BY timestamp DESC LIMIT ?",
+                (limit,),
+            ) as c:
+                rows = await c.fetchall()
+        return [dict(r) for r in rows]
+
 # =============================================================================
 # LIVEKIT CONFIG + TOKEN ISSUANCE
 # =============================================================================
@@ -1164,6 +1228,7 @@ async def update_livekit_config(payload: LiveKitConfig):
     # Note: there's no separate endpoint to set the secret via JSON to avoid
     # accidental overwrites; use POST /api/livekit/config/secret for that.
     await broadcast("livekit_config_changed", {})
+    await _log_history("livekit", "settings", "livekit_config", "updated", "operator", f"url_set={payload.url is not None}, key_set={payload.api_key is not None}")
     return {"status": "ok"}
 
 @app.post("/api/livekit/config/secret")
@@ -1173,6 +1238,7 @@ async def set_livekit_secret(payload: dict):
         raise HTTPException(400, "api_secret must be a string of length >= 8")
     await set_setting("livekit_api_secret", secret)
     await broadcast("livekit_config_changed", {})
+    await _log_history("livekit", "settings", "livekit_secret", "updated", "operator")
     return {"status": "ok"}
 
 @app.post("/api/livekit/token", response_model=LiveKitTokenResponse)
@@ -1376,6 +1442,7 @@ async def preview_start(robot_id: str):
         token = _mint_lk(server, room_name, identity, "operator-preview", publish=False, ttl_min=5)
     except ImportError:
         raise HTTPException(503, "livekit-api not installed on scheduler")
+    await _log_history("preview", "robot", robot_id, "start", "operator", f"room={room_name}, server={server['id']}")
     return {"active": True, "url": server["url"], "token": token, "room": room_name,
             "identity": identity, "expires_in": PREVIEW_TTL_SECONDS}
 
@@ -1388,6 +1455,7 @@ async def preview_keepalive(robot_id: str):
         await db.commit()
         if cur.rowcount == 0:
             return {"active": False}
+    await _log_history("preview", "robot", robot_id, "keepalive", "operator")
     return {"active": True, "expires_in": PREVIEW_TTL_SECONDS}
 
 @app.post("/api/robots/{robot_id}/preview/stop")
@@ -1396,6 +1464,7 @@ async def preview_stop(robot_id: str):
     async with aiosqlite.connect(DB_PATH) as db:
         await db.execute("DELETE FROM previews WHERE robot_id = ?", (robot_id,))
         await db.commit()
+    await _log_history("preview", "robot", robot_id, "stop", "operator")
     return {"stopped": True}
 
 @app.get("/api/robots/{robot_id}/preview/agent")
@@ -1425,6 +1494,7 @@ async def preview_agent(robot_id: str, authorization: Optional[str] = Header(def
         token = _mint_lk(server, row["room_name"], robot_id, robot_id, publish=True, ttl_min=2)
     except ImportError:
         raise HTTPException(503, "livekit-api not installed on scheduler")
+    await _log_history("preview", "robot", robot_id, "agent_token", "pi", f"room={row['room_name']}")
     return {"active": True, "url": server["url"], "token": token, "room": row["room_name"]}
 
 # =============================================================================
@@ -1475,6 +1545,8 @@ class DeviceUpdate(BaseModel):
     character_id: Optional[str] = None
     motor_server_url: Optional[str] = None
     livekit_url: Optional[str] = None
+    video_device: Optional[str] = None
+    audio_device: Optional[str] = None
     tailscale_ip: Optional[str] = None
     lan_ip: Optional[str] = None
     notes: Optional[str] = None
@@ -1494,6 +1566,7 @@ async def update_device(device_id: str, payload: DeviceUpdate):
         if cur.rowcount == 0:
             raise HTTPException(404, "Device not found")
     await broadcast("device_updated", {"device_id": device_id, "fields": list(fields.keys())})
+    await _log_history("device", "device", device_id, "updated", "operator", f"fields={','.join(fields.keys())}")
     return await get_device(device_id)
 
 @app.post("/api/devices", response_model=Device)
@@ -1518,11 +1591,13 @@ async def create_device(payload: DeviceCreate):
         await db.execute(
             """INSERT INTO devices
                (id, name, tailscale_ip, lan_ip, motor_server_url, character_id,
-                livekit_url, enrollment_token_hash, status, enrolled_at, notes, created_at)
-               VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'enrolled', ?, ?, ?)""",
+                livekit_url, video_device, audio_device, enrollment_token_hash,
+                status, enrolled_at, notes, created_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'enrolled', ?, ?, ?)""",
             (
                 device_id, payload.name.strip(), payload.tailscale_ip, payload.lan_ip,
                 payload.motor_server_url, payload.character_id, payload.livekit_url,
+                payload.video_device, payload.audio_device,
                 enrollment_hash, now, payload.notes, now,
             ),
         )
@@ -1530,6 +1605,7 @@ async def create_device(payload: DeviceCreate):
 
     logger.info(f"Device {device_id} ({payload.name}) created")
     await broadcast("device_added", {"device_id": device_id, "name": payload.name})
+    await _log_history("device", "device", device_id, "created", "operator", f"name={payload.name.strip()}")
 
     device = await get_device(device_id)
     return {
@@ -1540,13 +1616,16 @@ async def create_device(payload: DeviceCreate):
 @app.delete("/api/devices/{device_id}")
 async def delete_device(device_id: str):
     async with aiosqlite.connect(DB_PATH) as db:
-        async with db.execute("SELECT id FROM devices WHERE id = ?", (device_id,)) as c:
+        db.row_factory = aiosqlite.Row
+        async with db.execute("SELECT name FROM devices WHERE id = ?", (device_id,)) as c:
             row = await c.fetchone()
         if not row:
             raise HTTPException(404, "Device not found")
+        name = row["name"]
         await db.execute("DELETE FROM devices WHERE id = ?", (device_id,))
         await db.commit()
     await broadcast("device_removed", {"device_id": device_id})
+    await _log_history("device", "device", device_id, "deleted", "operator", f"name={name}")
     return {"status": "deleted", "device_id": device_id}
 
 @app.post("/api/devices/{device_id}/token/rotate")
@@ -1560,6 +1639,7 @@ async def rotate_device_token(device_id: str):
         if cur.rowcount == 0:
             raise HTTPException(404, "Device not found")
     await broadcast("device_token_rotated", {"device_id": device_id})
+    await _log_history("device", "device", device_id, "token_rotated", "operator")
     return {"device_id": device_id, "device_token": new_token}
 
 async def _authorize_device(device_id: str, authorization: Optional[str]) -> bool:
@@ -1574,6 +1654,20 @@ async def _authorize_device(device_id: str, authorization: Optional[str]) -> boo
         return False
     return hmac.compare_digest(row[0], _hash(token))
 
+async def _log_history(category: str, entity_type: Optional[str] = None, entity_id: Optional[str] = None,
+                       action: Optional[str] = None, actor: Optional[str] = None, details: Optional[str] = None):
+    """Append an immutable audit/history record."""
+    try:
+        async with aiosqlite.connect(DB_PATH) as db:
+            await db.execute(
+                """INSERT INTO history_log (timestamp, category, entity_type, entity_id, action, actor, details)
+                   VALUES (?, ?, ?, ?, ?, ?, ?)""",
+                (datetime.utcnow().isoformat(), category, entity_type, entity_id, action, actor, details),
+            )
+            await db.commit()
+    except Exception as e:
+        logger.warning(f"history log failed: {e}")
+
 async def _authorize_fleet(authorization: Optional[str]) -> bool:
     """Verify a Bearer token matches ANY enrolled device token (fleet auth).
 
@@ -1632,14 +1726,21 @@ async def enroll_device(payload: DeviceEnrollRequest):
                        motor_server_url = COALESCE(?, motor_server_url),
                        livekit_url = COALESCE(?, livekit_url),
                        character_id = COALESCE(?, character_id),
+                       video_device = COALESCE(?, video_device),
+                       audio_device = COALESCE(?, audio_device),
                        name = COALESCE(?, name)
                    WHERE id = ?""",
                 (
                     new_hash, now, payload.tailscale_ip, payload.lan_ip,
                     payload.motor_server_url, payload.livekit_url, payload.character_id,
+                    payload.video_device, payload.audio_device,
                     payload.name, device_id,
                 ),
             )
+            await db.execute(
+                "INSERT OR IGNORE INTO robots (id, name, character_id, status) VALUES (?, ?, ?, 'idle')",
+                (device_id, existing["name"] or payload.name or device_id, existing["character_id"]),
+            )
         else:
             # First-boot enroll via the global default token -> create a new device.
             device_id = f"dev_{secrets.token_hex(4)}"
@@ -1649,21 +1750,28 @@ async def enroll_device(payload: DeviceEnrollRequest):
             await db.execute(
                 """INSERT INTO devices
                    (id, name, tailscale_ip, lan_ip, motor_server_url, character_id,
-                    livekit_url, token_hash, enrollment_token_hash, status, enrolled_at, created_at)
-                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'enrolled', ?, ?)""",
+                    livekit_url, video_device, audio_device, token_hash,
+                    enrollment_token_hash, status, enrolled_at, created_at)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'enrolled', ?, ?)""",
                 (
                     device_id,
                     (payload.name or f"Pi-{device_id[-4:]}").strip(),
                     payload.tailscale_ip, payload.lan_ip,
                     payload.motor_server_url, payload.character_id,
-                    payload.livekit_url, new_hash, token_hash, now, now,
+                    payload.livekit_url, payload.video_device, payload.audio_device,
+                    new_hash, token_hash, now, now,
                 ),
             )
+            await db.execute(
+                "INSERT OR IGNORE INTO robots (id, name, character_id, status) VALUES (?, ?, ?, 'idle')",
+                (device_id, (payload.name or f"Pi-{device_id[-4:]}").strip(), payload.character_id),
+            )
 
         await db.commit()
 
     await broadcast("device_enrolled", {"device_id": device_id})
     logger.info(f"Device {device_id} enrolled")
+    await _log_history("device", "device", device_id, "enrolled", "pi", f"name={(payload.name or device_id).strip()}")
 
     # Discover our own scheduler URL (best effort)
     scheduler_url = os.getenv("SCHEDULER_PUBLIC_URL", f"http://localhost:{os.getenv('SCHEDULER_PORT', '8080')}")
@@ -1690,6 +1798,7 @@ async def device_heartbeat(device_id: str, payload: DeviceHeartbeat,
             if cur.rowcount == 0:
                 raise HTTPException(404, "Device not found")
     await broadcast("device_heartbeat", {"device_id": device_id, "status": payload.status})
+    await _log_history("device", "device", device_id, "heartbeat", "pi", f"status={payload.status or 'online'}, ip={payload.ip}")
     # Tell the Pi whether production mode is on (so it can decide to join LiveKit or stand by)
     return {
         "status": "ok",
@@ -2058,6 +2167,7 @@ async def dashboard():
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <script src="https://cdn.tailwindcss.com"></script>
         <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
+        <script src="https://cdn.jsdelivr.net/npm/livekit-client@1/dist/livekit-client.umd.min.js"></script>
     </head>
     <body class="bg-gray-900 text-white">
         <div id="app"></div>
@@ -2077,8 +2187,10 @@ async def dashboard():
                     const livekit = ref({ url: null, api_key: null, has_secret: false });
                     const showAddDevice = ref(false);
                     const showDevices = ref(true);
-                    const newDevice = ref({ name: '', tailscale_ip: '', lan_ip: '', motor_server_url: '', character_id: '', livekit_url: '', notes: '' });
+                    const newDevice = ref({ name: '', tailscale_ip: '', lan_ip: '', motor_server_url: '', character_id: '', livekit_url: '', video_device: 'auto', audio_device: 'default', notes: '' });
                     const rotatedToken = ref(null);
+                    const preview = ref({ robot: null, active: false, url: null, token: null, room: null, keepalive: null });
+                    const deviceInventory = ref({});
                     const showLiveKitConfig = ref(false);
                     const livekitForm = ref({ url: '', api_key: '', api_secret: '' });
                     let ws = null;
@@ -2108,11 +2220,30 @@ async def dashboard():
                                     serverMetrics.value[server.id] = metrics;
                                 } catch (e) {}
                             }
+                            buildDeviceInventory();
                         } catch (e) {
                             console.error('Failed to fetch data:', e);
                         }
                     };
 
+                    const buildDeviceInventory = () => {
+                        const map = {};
+                        for (const robot of robots.value) {
+                            const device = devices.value.find(d => d.name === robot.name || d.id === robot.id);
+                            const savedVideo = device?.video_device || 'auto';
+                            const savedAudio = device?.audio_device || 'default';
+                            map[robot.id] = {
+                                deviceId: device?.id || null,
+                                robotName: robot.name,
+                                selectedVideo: savedVideo,
+                                selectedAudio: savedAudio,
+                                videoOptions: ['auto', 'none', 'picamera', '/dev/video0', '/dev/video1', '/dev/video2'],
+                                audioOptions: ['default', 'none'],
+                            };
+                        }
+                        deviceInventory.value = map;
+                    };
+
                     const connectWebSocket = () => {
                         const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
                         ws = new WebSocket(`${protocol}//${window.location.host}/ws`);
@@ -2198,13 +2329,75 @@ async def dashboard():
                                 rotatedToken.value = { device_id: r.id, name: r.name, token: r.enrollment_token };
                             }
                             showAddDevice.value = false;
-                            newDevice.value = { name: '', tailscale_ip: '', lan_ip: '', motor_server_url: '', character_id: '', livekit_url: '', notes: '' };
+                            newDevice.value = { name: '', tailscale_ip: '', lan_ip: '', motor_server_url: '', character_id: '', livekit_url: '', video_device: 'auto', audio_device: 'default', notes: '' };
                             fetchData();
                         } catch (e) {
                             alert('Failed to add device: ' + e.message);
                         }
                     };
 
+                    const updateDeviceMedia = async (robotId) => {
+                        const inv = deviceInventory.value[robotId];
+                        if (!inv || !inv.deviceId) return;
+                        try {
+                            await fetch(`/api/devices/${inv.deviceId}`, {
+                                method: 'PATCH',
+                                headers: {'Content-Type': 'application/json'},
+                                body: JSON.stringify({
+                                    video_device: inv.selectedVideo,
+                                    audio_device: inv.selectedAudio,
+                                }),
+                            });
+                            fetchData();
+                        } catch (e) {
+                            alert('Failed to update device media: ' + e.message);
+                        }
+                    };
+
+                    const startPreview = async (robot) => {
+                        stopPreview();
+                        try {
+                            const r = await fetch(`/api/robots/${robot.id}/preview/start`, { method: 'POST' }).then(r => r.json());
+                            if (!r.active) {
+                                alert('Preview not active: ' + (r.reason || 'unknown'));
+                                return;
+                            }
+                            preview.value = { robot, active: true, url: r.url, token: r.token, room: r.room, keepalive: null };
+                            await connectLiveKitPreview(r.url, r.token);
+                            preview.value.keepalive = setInterval(async () => {
+                                if (!preview.value.active) return;
+                                try {
+                                    await fetch(`/api/robots/${robot.id}/preview/keepalive`, { method: 'POST' });
+                                } catch (e) { console.warn('keepalive failed', e); }
+                            }, 15000);
+                        } catch (e) {
+                            alert('Failed to start preview: ' + e.message);
+                        }
+                    };
+
+                    const stopPreview = () => {
+                        if (preview.value.keepalive) clearInterval(preview.value.keepalive);
+                        if (preview.value.room) {
+                            try { window.__lkPreviewRoom?.disconnect(); } catch (e) {}
+                        }
+                        preview.value = { robot: null, active: false, url: null, token: null, room: null, keepalive: null };
+                    };
+
+                    const connectLiveKitPreview = async (url, token) => {
+                        const { Room } = LiveKitClient;
+                        const room = new Room({ adaptiveStream: true });
+                        window.__lkPreviewRoom = room;
+                        room.on('trackSubscribed', (track, publication, participant) => {
+                            if (track.kind === 'video') {
+                                track.attach(document.getElementById('preview-video'));
+                            }
+                            if (track.kind === 'audio') {
+                                track.attach(document.createElement('audio'));
+                            }
+                        });
+                        await room.connect(url, token);
+                    };
+
                     const deleteDevice = async (id, name) => {
                         if (!confirm(`Delete device "${name}"?`)) return;
                         try {
@@ -2335,11 +2528,12 @@ async def dashboard():
                     return {
                         robots, servers, sessions, stats, connected, serverMetrics,
                         devices, settings, livekit, showAddDevice, showDevices, newDevice, rotatedToken,
-                        showLiveKitConfig, livekitForm,
+                        showLiveKitConfig, livekitForm, preview, deviceInventory,
                         loadModel, unloadModel, statusColor, formatDuration, formatTime,
                         toggleProductionMode, rotateEnrollmentToken,
                         submitNewDevice, deleteDevice, rotateDeviceToken, dismissRotatedToken,
                         joinConversation, saveLiveKitConfig, openLiveKitConfig,
+                        startPreview, stopPreview, updateDeviceMedia,
                     };
                 },
                 template: `
@@ -2492,6 +2686,25 @@ async def dashboard():
                                         <label class="block text-gray-400 mb-1">LiveKit URL (for this device)</label>
                                         <input v-model="newDevice.livekit_url" class="w-full bg-gray-700 rounded px-3 py-2" placeholder="ws://100.64.1.5:7880" />
                                     </div>
+                                    <div class="grid grid-cols-2 gap-3">
+                                        <div>
+                                            <label class="block text-gray-400 mb-1">Default Camera</label>
+                                            <select v-model="newDevice.video_device" class="w-full bg-gray-700 rounded px-3 py-2">
+                                                <option value="auto">auto</option>
+                                                <option value="none">none</option>
+                                                <option value="picamera">picamera</option>
+                                                <option value="/dev/video0">/dev/video0</option>
+                                                <option value="/dev/video1">/dev/video1</option>
+                                            </select>
+                                        </div>
+                                        <div>
+                                            <label class="block text-gray-400 mb-1">Default Mic</label>
+                                            <select v-model="newDevice.audio_device" class="w-full bg-gray-700 rounded px-3 py-2">
+                                                <option value="default">default</option>
+                                                <option value="none">none</option>
+                                            </select>
+                                        </div>
+                                    </div>
                                     <div>
                                         <label class="block text-gray-400 mb-1">Character ID</label>
                                         <input v-model="newDevice.character_id" class="w-full bg-gray-700 rounded px-3 py-2" placeholder="panda-character" />
@@ -2550,28 +2763,66 @@ async def dashboard():
                         <!-- Main Grid -->
                         <div class="grid grid-cols-12 gap-6">
 
-                            <!-- Robots Panel -->
+                                     <!-- Robots Panel -->
                             <div class="col-span-4 bg-gray-800 rounded-lg p-4">
                                 <h2 class="text-xl font-semibold mb-4">🤖 Robot Fleet</h2>
                                 <div class="space-y-3">
                                     <div v-for="robot in robots" :key="robot.id"
-                                         class="bg-gray-700 rounded-lg p-3 flex items-center gap-3">
-                                        <div class="w-3 h-3 rounded-full" :class="statusColor(robot.status)"></div>
-                                        <div class="flex-1">
-                                            <div class="font-medium">{{ robot.name }}</div>
-                                            <div class="text-sm text-gray-400">
-                                                {{ robot.status }}
-                                                <span v-if="robot.connected_server_id" class="ml-1">
-                                                    → {{ robot.connected_server_id }}
-                                                </span>
+                                         class="bg-gray-700 rounded-lg p-3">
+                                        <div class="flex items-center gap-3 mb-2">
+                                            <div class="w-3 h-3 rounded-full" :class="statusColor(robot.status)"></div>
+                                            <div class="flex-1">
+                                                <div class="font-medium">{{ robot.name }}</div>
+                                                <div class="text-sm text-gray-400">
+                                                    {{ robot.status }}
+                                                    <span v-if="robot.connected_server_id" class="ml-1">
+                                                        → {{ robot.connected_server_id }}
+                                                    </span>
+                                                </div>
+                                            </div>
+                                            <div class="text-right text-sm text-gray-400">
+                                                {{ robot.total_sessions }} sessions
                                             </div>
                                         </div>
-                                        <div class="text-right text-sm text-gray-400">
-                                            {{ robot.total_sessions }} sessions
+                                        <div v-if="deviceInventory[robot.id]" class="space-y-2 text-sm">
+                                            <div class="grid grid-cols-2 gap-2">
+                                                <div>
+                                                    <label class="text-xs text-gray-500">Camera</label>
+                                                    <select v-model="deviceInventory[robot.id].selectedVideo"
+                                                            @change="updateDeviceMedia(robot.id)"
+                                                            class="w-full bg-gray-800 rounded px-2 py-1 text-xs">
+                                                        <option v-for="opt in deviceInventory[robot.id].videoOptions" :key="opt" :value="opt">{{ opt }}</option>
+                                                    </select>
+                                                </div>
+                                                <div>
+                                                    <label class="text-xs text-gray-500">Microphone</label>
+                                                    <select v-model="deviceInventory[robot.id].selectedAudio"
+                                                            @change="updateDeviceMedia(robot.id)"
+                                                            class="w-full bg-gray-800 rounded px-2 py-1 text-xs">
+                                                        <option v-for="opt in deviceInventory[robot.id].audioOptions" :key="opt" :value="opt">{{ opt }}</option>
+                                                    </select>
+                                                </div>
+                                            </div>
+                                            <button @click="startPreview(robot)"
+                                                    :disabled="!settings.production_mode || !livekit.url || !livekit.has_secret || preview.active"
+                                                    :class="(settings.production_mode && livekit.url && livekit.has_secret && !preview.active) ? 'bg-cyan-600 hover:bg-cyan-700' : 'bg-gray-700 cursor-not-allowed'"
+                                                    class="w-full px-2 py-1 rounded text-xs">
+                                                {{ preview.active && preview.robot?.id === robot.id ? 'Preview Active' : 'Start Preview' }}
+                                            </button>
+                                            <button v-if="preview.active && preview.robot?.id === robot.id"
+                                                    @click="stopPreview"
+                                                    class="w-full px-2 py-1 bg-red-600 hover:bg-red-700 rounded text-xs">
+                                                Stop Preview
+                                            </button>
                                         </div>
                                     </div>
                                 </div>
-                            </div>
+                                <!-- Live preview panel -->
+                                <div v-if="preview.active" class="mt-4 bg-black rounded-lg overflow-hidden">
+                                    <video id="preview-video" class="w-full" autoplay playsinline muted></video>
+                                    <div class="text-xs text-gray-400 px-2 py-1">{{ preview.room }}</div>
+                                </div>
+                            </div>
                             
                             <!-- Servers Panel -->
                             <div class="col-span-5 space-y-4">

package/scheduler/preview_agent.py

@@ -0,0 +1,639 @@
+#!/usr/bin/env python3
+"""
+RoboPark Preview Agent — runs on each robot/satellite Pi.
+
+Polls the scheduler for an active operator preview request. When active,
+opens the selected camera + microphone and publishes them to the returned
+LiveKit room. When the preview expires or is stopped, the agent leaves the
+room and releases the hardware.
+
+Configuration (env / ~/.robopark/preview_agent.json):
+  SCHEDULER_URL          base URL of the RoboPark scheduler
+  ROBOT_ID               robot identity in the scheduler (defaults to hostname)
+  DEVICE_TOKEN           long-lived device token (after enrollment)
+  ENROLLMENT_TOKEN       one-time enrollment token (device token will be saved)
+  VIDEO_DEVICE           camera path/index/name (e.g. /dev/video0, 0, "PiCamera")
+  AUDIO_DEVICE           microphone name/index or "default"
+  VIDEO_WIDTH / HEIGHT   capture resolution (default 640x480)
+  VIDEO_FPS              capture fps (default 15)
+  POLL_INTERVAL          seconds between scheduler polls (default 3)
+  HEARTBEAT_INTERVAL     seconds between device heartbeats (default 30)
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import signal
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger("robopark.preview_agent")
+
+CONFIG_DIR = Path.home() / ".robopark"
+CONFIG_FILE = CONFIG_DIR / "preview_agent.json"
+TOKEN_FILE = CONFIG_DIR / "device_token"
+
+DEFAULT_VIDEO_WIDTH = 640
+DEFAULT_VIDEO_HEIGHT = 480
+DEFAULT_FPS = 15
+DEFAULT_POLL_INTERVAL = 3.0
+DEFAULT_HEARTBEAT_INTERVAL = 30.0
+
+
+def _load_config() -> dict:
+    cfg: dict = {}
+    if CONFIG_FILE.exists():
+        try:
+            cfg = json.loads(CONFIG_FILE.read_text(encoding="utf8"))
+        except Exception as e:
+            logger.warning(f"failed to read {CONFIG_FILE}: {e}")
+    return cfg
+
+
+def _save_config(cfg: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(cfg, indent=2), encoding="utf8")
+
+
+def _load_token() -> Optional[str]:
+    if TOKEN_FILE.exists():
+        return TOKEN_FILE.read_text(encoding="utf8").strip() or None
+    return None
+
+
+def _save_token(token: str) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    TOKEN_FILE.write_text(token, encoding="utf8")
+    os.chmod(TOKEN_FILE, 0o600)
+
+
+async def _enroll(scheduler_url: str, enrollment_token: str, robot_id: str) -> str:
+    """Enroll this Pi with the scheduler and return the device token."""
+    import socket
+    payload = {
+        "enrollment_token": enrollment_token,
+        "name": robot_id,
+        "lan_ip": _get_lan_ip(),
+    }
+    async with httpx.AsyncClient() as client:
+        r = await client.post(
+            f"{scheduler_url.rstrip('/')}/api/devices/enroll",
+            json=payload,
+            timeout=30.0,
+        )
+        r.raise_for_status()
+        data = r.json()
+    device_token = data.get("device_token")
+    if not device_token:
+        raise RuntimeError("enrollment did not return a device_token")
+    _save_token(device_token)
+    cfg = _load_config()
+    cfg["device_id"] = data.get("device_id")
+    cfg["scheduler_url"] = data.get("scheduler_url", scheduler_url)
+    _save_config(cfg)
+    logger.info(f"enrolled as device {data.get('device_id')}")
+    return device_token
+
+
+def _get_lan_ip() -> Optional[str]:
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.settimeout(0.5)
+        s.connect(("10.255.255.255", 1))
+        ip = s.getsockname()[0]
+        s.close()
+        return ip
+    except Exception:
+        return None
+
+
+async def _send_heartbeat(scheduler_url: str, device_id: str, token: str) -> None:
+    try:
+        async with httpx.AsyncClient() as client:
+            await client.post(
+                f"{scheduler_url.rstrip('/')}/api/devices/{device_id}/heartbeat",
+                json={"status": "online"},
+                headers={"Authorization": f"Bearer {token}"},
+                timeout=10.0,
+            )
+    except Exception as e:
+        logger.debug(f"heartbeat failed: {e}")
+
+
+@dataclass
+class PreviewState:
+    active: bool = False
+    url: Optional[str] = None
+    token: Optional[str] = None
+    room: Optional[str] = None
+
+
+class PreviewAgent:
+    def __init__(self, cfg: dict):
+        self.scheduler_url = cfg.get("scheduler_url", os.getenv("SCHEDULER_URL", "http://localhost:8080"))
+        self.robot_id = cfg.get("robot_id", os.getenv("ROBOT_ID", _hostname()))
+        self.device_token: Optional[str] = cfg.get("device_token") or os.getenv("DEVICE_TOKEN") or _load_token()
+        self.device_id: Optional[str] = cfg.get("device_id")
+        self.video_device = cfg.get("video_device", os.getenv("VIDEO_DEVICE", "auto"))
+        self.audio_device = cfg.get("audio_device", os.getenv("AUDIO_DEVICE", "default"))
+        self.width = int(cfg.get("video_width", os.getenv("VIDEO_WIDTH", DEFAULT_VIDEO_WIDTH)))
+        self.height = int(cfg.get("video_height", os.getenv("VIDEO_HEIGHT", DEFAULT_VIDEO_HEIGHT)))
+        self.fps = int(cfg.get("video_fps", os.getenv("VIDEO_FPS", DEFAULT_FPS)))
+        self.poll_interval = float(cfg.get("poll_interval", os.getenv("POLL_INTERVAL", DEFAULT_POLL_INTERVAL)))
+        self.heartbeat_interval = float(cfg.get("heartbeat_interval", os.getenv("HEARTBEAT_INTERVAL", DEFAULT_HEARTBEAT_INTERVAL)))
+
+        self._shutdown = asyncio.Event()
+        self._task: Optional[asyncio.Task] = None
+        self._session: Optional[httpx.AsyncClient] = None
+        self._current_state: PreviewState = PreviewState()
+        self._publisher: Optional["LiveKitPublisher"] = None
+
+    async def run(self) -> None:
+        enrollment_token = os.getenv("ENROLLMENT_TOKEN") or cfg.get("enrollment_token")
+        if not self.device_token and enrollment_token:
+            self.device_token = await _enroll(self.scheduler_url, enrollment_token, self.robot_id)
+
+        if not self.device_token:
+            logger.error("no DEVICE_TOKEN and no ENROLLMENT_TOKEN; cannot poll scheduler")
+            sys.exit(1)
+
+        if not self.device_id:
+            await self._resolve_device_id()
+
+        self._session = httpx.AsyncClient()
+
+        tasks = [
+            asyncio.create_task(self._poll_loop()),
+            asyncio.create_task(self._heartbeat_loop()),
+        ]
+        await self._shutdown.wait()
+        for t in tasks:
+            t.cancel()
+            try:
+                await t
+            except asyncio.CancelledError:
+                pass
+        await self._stop_publisher()
+        await self._session.aclose()
+
+    async def _resolve_device_id(self) -> None:
+        """Look up our device_id from the scheduler using the token."""
+        if not self._session or not self.device_token:
+            return
+        try:
+            r = await self._session.get(
+                f"{self.scheduler_url.rstrip('/')}/api/devices",
+                headers={"Authorization": f"Bearer {self.device_token}"},
+                timeout=10.0,
+            )
+            r.raise_for_status()
+            for d in r.json():
+                if d.get("name") == self.robot_id:
+                    self.device_id = d.get("id")
+                    cfg = _load_config()
+                    cfg["device_id"] = self.device_id
+                    _save_config(cfg)
+                    return
+        except Exception as e:
+            logger.warning(f"could not resolve device_id: {e}")
+
+    async def _poll_loop(self) -> None:
+        while not self._shutdown.is_set():
+            try:
+                state = await self._fetch_preview_state()
+                await self._apply_state(state)
+            except Exception as e:
+                logger.warning(f"poll error: {e}")
+            try:
+                await asyncio.wait_for(self._shutdown.wait(), timeout=self.poll_interval)
+            except asyncio.TimeoutError:
+                pass
+
+    async def _heartbeat_loop(self) -> None:
+        while not self._shutdown.is_set():
+            if self.device_id and self.device_token:
+                await _send_heartbeat(self.scheduler_url, self.device_id, self.device_token)
+            try:
+                await asyncio.wait_for(self._shutdown.wait(), timeout=self.heartbeat_interval)
+            except asyncio.TimeoutError:
+                pass
+
+    async def _fetch_preview_state(self) -> PreviewState:
+        if not self._session or not self.device_token:
+            return PreviewState()
+        r = await self._session.get(
+            f"{self.scheduler_url.rstrip('/')}/api/robots/{self.robot_id}/preview/agent",
+            headers={"Authorization": f"Bearer {self.device_token}"},
+            timeout=10.0,
+        )
+        r.raise_for_status()
+        data = r.json()
+        if not data.get("active"):
+            return PreviewState()
+        return PreviewState(
+            active=True,
+            url=data.get("url"),
+            token=data.get("token"),
+            room=data.get("room"),
+        )
+
+    async def _apply_state(self, state: PreviewState) -> None:
+        same = (
+            state.active == self._current_state.active
+            and state.room == self._current_state.room
+            and state.token == self._current_state.token
+            and state.url == self._current_state.url
+        )
+        if same:
+            return
+        self._current_state = state
+        if not state.active:
+            await self._stop_publisher()
+            return
+        await self._start_publisher(state)
+
+    async def _start_publisher(self, state: PreviewState) -> None:
+        await self._stop_publisher()
+        if not state.url or not state.token or not state.room:
+            return
+        try:
+            pub = LiveKitPublisher(state.url, state.token, state.room, self)
+            await pub.start()
+            self._publisher = pub
+            logger.info(f"joined preview room {state.room}")
+        except Exception as e:
+            logger.error(f"failed to start publisher: {e}")
+
+    async def _stop_publisher(self) -> None:
+        if self._publisher:
+            try:
+                await self._publisher.stop()
+            except Exception as e:
+                logger.warning(f"publisher stop error: {e}")
+            self._publisher = None
+
+    def shutdown(self) -> None:
+        self._shutdown.set()
+
+
+class LiveKitPublisher:
+    """Encapsulates LiveKit room connection, camera capture and mic capture."""
+
+    def __init__(self, url: str, token: str, room_name: str, agent: PreviewAgent):
+        from livekit import rtc
+        self.url = url
+        self.token = token
+        self.room_name = room_name
+        self.agent = agent
+        self.rtc = rtc
+        self.room: Optional[rtc.Room] = None
+        self.video_source: Optional[rtc.VideoSource] = None
+        self.video_track: Optional[rtc.LocalVideoTrack] = None
+        self.audio_source: Optional[rtc.AudioSource] = None
+        self.audio_track: Optional[rtc.LocalAudioTrack] = None
+        self._stop_event = asyncio.Event()
+        self._tasks: list[asyncio.Task] = []
+        self._capture: Optional["VideoCapture"] = None
+
+    async def start(self) -> None:
+        self.room = self.rtc.Room()
+        await self.room.connect(self.url, self.token)
+
+        # Video
+        self.video_source = self.rtc.VideoSource(self.agent.width, self.agent.height)
+        self.video_track = self.rtc.LocalVideoTrack.create_video_track("camera", self.video_source)
+        vopts = self.rtc.TrackPublishOptions()
+        vopts.source = self.rtc.TrackSource.SOURCE_CAMERA
+        await self.room.local_participant.publish_track(self.video_track, vopts)
+
+        # Audio
+        self.audio_source = self.rtc.AudioSource(48000, 1)
+        self.audio_track = self.rtc.LocalAudioTrack.create_audio_track("microphone", self.audio_source)
+        aopts = self.rtc.TrackPublishOptions()
+        aopts.source = self.rtc.TrackSource.SOURCE_MICROPHONE
+        await self.room.local_participant.publish_track(self.audio_track, aopts)
+
+        self._capture = create_video_capture(self.agent.video_device, self.agent.width, self.agent.height, self.agent.fps)
+        if self._capture:
+            self._tasks.append(asyncio.create_task(self._video_loop()))
+        if has_audio():
+            self._tasks.append(asyncio.create_task(self._audio_loop()))
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+        for t in self._tasks:
+            t.cancel()
+            try:
+                await t
+            except asyncio.CancelledError:
+                pass
+        self._tasks.clear()
+        if self._capture:
+            self._capture.stop()
+            self._capture = None
+        if self.room:
+            await self.room.disconnect()
+            self.room = None
+
+    async def _video_loop(self) -> None:
+        assert self._capture is not None and self.video_source is not None
+        frame_interval = 1.0 / self.agent.fps
+        while not self._stop_event.is_set():
+            start = time.monotonic()
+            frame = self._capture.read()
+            if frame is not None:
+                self.video_source.capture_frame(frame)
+            elapsed = time.monotonic() - start
+            sleep_for = frame_interval - elapsed
+            if sleep_for > 0:
+                try:
+                    await asyncio.wait_for(self._stop_event.wait(), timeout=sleep_for)
+                except asyncio.TimeoutError:
+                    pass
+
+    async def _audio_loop(self) -> None:
+        assert self.audio_source is not None
+        mic = create_audio_capture(self.agent.audio_device)
+        if mic is None:
+            return
+        frame_duration = 0.02  # 20ms
+        samples_per_frame = int(48000 * frame_duration)
+        while not self._stop_event.is_set():
+            frame = mic.read(samples_per_frame)
+            if frame is not None:
+                self.audio_source.capture_frame(frame)
+            try:
+                await asyncio.wait_for(self._stop_event.wait(), timeout=frame_duration)
+            except asyncio.TimeoutError:
+                pass
+
+
+# -----------------------------------------------------------------------------
+# Video capture abstraction: V4L2/USB via OpenCV, or picamera2 on Pi.
+# -----------------------------------------------------------------------------
+
+class VideoCapture:
+    def read(self) -> Optional["rtc.VideoFrame"]:
+        raise NotImplementedError
+
+    def stop(self) -> None:
+        raise NotImplementedError
+
+
+class OpencvVideoCapture(VideoCapture):
+    def __init__(self, device: int | str, width: int, height: int, fps: int):
+        import cv2
+        self.cv2 = cv2
+        if isinstance(device, str) and device.startswith("/dev/video"):
+            device = int(device.replace("/dev/video", ""))
+        self.cap = cv2.VideoCapture(device)
+        self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, width)
+        self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, height)
+        self.cap.set(cv2.CAP_PROP_FPS, fps)
+        self._ensure_frame()
+
+    def _ensure_frame(self):
+        ok, _ = self.cap.read()
+        if not ok:
+            raise RuntimeError("cannot read from camera")
+
+    def read(self):
+        from livekit import rtc
+        ok, bgr = self.cap.read()
+        if not ok or bgr is None:
+            return None
+        return rtc.VideoFrame(
+            width=bgr.shape[1],
+            height=bgr.shape[0],
+            type=rtc.VideoBufferType.BGR,
+            data=bgr.tobytes(),
+        )
+
+    def stop(self):
+        self.cap.release()
+
+
+class Picamera2Capture(VideoCapture):
+    def __init__(self, width: int, height: int, fps: int):
+        from picamera2 import Picamera2
+        self.picam = Picamera2()
+        config = self.picam.create_video_configuration(
+            main={"format": "RGB888", "size": (width, height)},
+            controls={"FrameRate": fps},
+        )
+        self.picam.configure(config)
+        self.picam.start()
+        self.width = width
+        self.height = height
+
+    def read(self):
+        from livekit import rtc
+        arr = self.picam.capture_array()
+        if arr is None:
+            return None
+        return rtc.VideoFrame(
+            width=self.width,
+            height=self.height,
+            type=rtc.VideoBufferType.RGB,
+            data=arr.tobytes(),
+        )
+
+    def stop(self):
+        try:
+            self.picam.stop()
+        except Exception:
+            pass
+
+
+def create_video_capture(device: str, width: int, height: int, fps: int) -> Optional[VideoCapture]:
+    if device.lower() in ("none", "", "false", "null"):
+        return None
+    try:
+        from livekit import rtc
+        _ = rtc.VideoSource
+    except Exception as e:
+        logger.error(f"livekit python sdk not installed: {e}")
+        return None
+
+    # Auto-detect: prefer first V4L2 device, fall back to picamera2 if available.
+    if device.lower() in ("auto", "default", "first"):
+        for i in range(4):
+            try:
+                cap = OpencvVideoCapture(i, width, height, fps)
+                logger.info(f"auto-selected USB camera /dev/video{i}")
+                return cap
+            except Exception:
+                continue
+        try:
+            cap = Picamera2Capture(width, height, fps)
+            logger.info("auto-selected Pi Camera")
+            return cap
+        except Exception:
+            pass
+        logger.error("no camera found (tried V4L2 and picamera2)")
+        return None
+
+    if device.lower() in ("picamera", "picamera2", "pi", "rpi"):
+        return Picamera2Capture(width, height, fps)
+
+    # Treat as V4L2 index or path
+    return OpencvVideoCapture(device, width, height, fps)
+
+
+# -----------------------------------------------------------------------------
+# Audio capture abstraction: PyAudio or sounddevice -> LiveKit AudioFrame.
+# -----------------------------------------------------------------------------
+
+class AudioCapture:
+    def read(self, samples_per_frame: int) -> Optional["rtc.AudioFrame"]:
+        raise NotImplementedError
+
+    def stop(self) -> None:
+        raise NotImplementedError
+
+
+class PyAudioCapture(AudioCapture):
+    def __init__(self, device: str | int | None):
+        import pyaudio
+        self.pa = pyaudio.PyAudio()
+        self.device_index = self._resolve_device(device)
+        self.buffer = bytearray()
+        self.stream = self.pa.open(
+            format=pyaudio.paInt16,
+            channels=1,
+            rate=48000,
+            input=True,
+            input_device_index=self.device_index,
+            frames_per_buffer=960,
+            stream_callback=self._callback,
+        )
+        self.stream.start_stream()
+
+    def _resolve_device(self, device: str | int | None) -> Optional[int]:
+        if device is None or device == "default":
+            return None
+        if isinstance(device, int):
+            return device
+        # Try exact name match
+        for i in range(self.pa.get_device_count()):
+            info = self.pa.get_device_info_by_index(i)
+            if info.get("maxInputChannels", 0) > 0 and device.lower() in str(info.get("name", "")).lower():
+                return i
+        return None
+
+    def _callback(self, in_data, frame_count, time_info, status):
+        self.buffer.extend(in_data)
+        return (None, pyaudio.paContinue)
+
+    def read(self, samples_per_frame: int):
+        from livekit import rtc
+        bytes_needed = samples_per_frame * 2  # int16 mono
+        while len(self.buffer) < bytes_needed:
+            time.sleep(0.005)
+        chunk = bytes(self.buffer[:bytes_needed])
+        self.buffer = self.buffer[bytes_needed:]
+        return rtc.AudioFrame(
+            data=chunk,
+            sample_rate=48000,
+            num_channels=1,
+            samples_per_channel=samples_per_frame,
+        )
+
+    def stop(self):
+        if self.stream:
+            self.stream.stop_stream()
+            self.stream.close()
+        self.pa.terminate()
+
+
+def has_audio() -> bool:
+    try:
+        import pyaudio  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def create_audio_capture(device: str) -> Optional[AudioCapture]:
+    if device.lower() in ("none", "", "false", "null"):
+        return None
+    try:
+        import pyaudio  # noqa: F401
+        return PyAudioCapture(device if device != "default" else None)
+    except Exception as e:
+        logger.warning(f"pyaudio not available: {e}")
+        return None
+
+
+def _hostname() -> str:
+    import socket
+    return socket.gethostname().split(".")[0]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="RoboPark preview agent")
+    parser.add_argument("--scheduler-url", default=os.getenv("SCHEDULER_URL", "http://localhost:8080"))
+    parser.add_argument("--robot-id", default=os.getenv("ROBOT_ID", _hostname()))
+    parser.add_argument("--device-token", default=os.getenv("DEVICE_TOKEN"))
+    parser.add_argument("--enrollment-token", default=os.getenv("ENROLLMENT_TOKEN"))
+    parser.add_argument("--video-device", default=os.getenv("VIDEO_DEVICE", "auto"))
+    parser.add_argument("--audio-device", default=os.getenv("AUDIO_DEVICE", "default"))
+    parser.add_argument("--width", type=int, default=int(os.getenv("VIDEO_WIDTH", DEFAULT_VIDEO_WIDTH)))
+    parser.add_argument("--height", type=int, default=int(os.getenv("VIDEO_HEIGHT", DEFAULT_VIDEO_HEIGHT)))
+    parser.add_argument("--fps", type=int, default=int(os.getenv("VIDEO_FPS", DEFAULT_FPS)))
+    parser.add_argument("--poll-interval", type=float, default=float(os.getenv("POLL_INTERVAL", DEFAULT_POLL_INTERVAL)))
+    parser.add_argument("--heartbeat-interval", type=float, default=float(os.getenv("HEARTBEAT_INTERVAL", DEFAULT_HEARTBEAT_INTERVAL)))
+    parser.add_argument("--save-config", action="store_true", help="write CLI args to ~/.robopark/preview_agent.json")
+    parser.add_argument("-v", "--verbose", action="store_true")
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+    cfg = _load_config()
+    cfg.update({
+        "scheduler_url": args.scheduler_url,
+        "robot_id": args.robot_id,
+        "video_device": args.video_device,
+        "audio_device": args.audio_device,
+        "video_width": args.width,
+        "video_height": args.height,
+        "video_fps": args.fps,
+        "poll_interval": args.poll_interval,
+        "heartbeat_interval": args.heartbeat_interval,
+    })
+    if args.device_token:
+        cfg["device_token"] = args.device_token
+        _save_token(args.device_token)
+    if args.enrollment_token:
+        cfg["enrollment_token"] = args.enrollment_token
+
+    if args.save_config:
+        _save_config(cfg)
+        logger.info(f"saved config to {CONFIG_FILE}")
+
+    agent = PreviewAgent(cfg)
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, agent.shutdown)
+
+    try:
+        loop.run_until_complete(agent.run())
+    finally:
+        loop.close()
+
+
+if __name__ == "__main__":
+    main()

package/scheduler/requirements.txt

@@ -5,4 +5,8 @@ httpx==0.27.2
 pydantic==2.9.2
 python-multipart==0.0.12
 livekit-api>=0.10
+livekit>=0.18
+opencv-python>=4.8
+pyaudio>=0.2
+picamera2>=0.3; platform_machine == 'aarch64' or platform_machine == 'arm64'
 PyJWT==2.9.0