158e6a204f
Comprehensive blueprint for a headless Raspberry Pi 3B projection mapping appliance: - Unified installer with 2GB swap safety for C++ source builds. - WebSocket-driven real-time vertex/surface manipulation. - 5-tab responsive dashboard (Dashboard, Mapping, Media, Network, System). - Media validation with ffprobe (H.264 check) and resource warnings. - Throttled log streaming and explicit mapping persistence.
47 lines
3.0 KiB
Markdown
47 lines
3.0 KiB
Markdown
## Context
|
|
|
|
Unifying the Raspberry Pi 3B (1GB RAM) into a dedicated projection mapping appliance. The system must be entirely headless, controllable via any browser-enabled device on the same network.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Provide a "one-liner" setup script that installs the entire stack.
|
|
- Enable real-time remote manipulation of mapping surfaces via WebSockets.
|
|
- Implement a robust system for media management and system monitoring.
|
|
- Maintain a permanent WiFi AP while allowing connection to external networks (Hybrid Mode).
|
|
|
|
**Non-Goals:**
|
|
- **Audio Support**: Explicitly out of scope for the Pi 3B in this version.
|
|
- **Pi 4/5 Support**: Target hardware is strictly Pi 3B for this design.
|
|
- **Multi-Projector Sync**: Synchronizing multiple Pi units is not part of this version.
|
|
|
|
## Decisions
|
|
|
|
### 1. Real-Time Communication (WebSockets)
|
|
We will use **Socket.io** for all vertex and surface updates. This bypasses the overhead of HTTP and allows the browser to feel like a direct remote for the `ofxPiMapper` engine.
|
|
|
|
### 2. Networking Architecture (Permanent AP)
|
|
- **Primary**: The Pi acts as an Access Point (`MPVJ-AP`) on `wlan0`.
|
|
- **Secondary**: A virtual interface or shared `wlan0` configuration will allow connecting to venue WiFi.
|
|
- **Safety**: The AP never turns off, ensuring you can always reach the UI even if the venue WiFi fails.
|
|
|
|
### 3. Media Assignment & Validation
|
|
The Node.js backend will maintain a JSON manifest of mapping surfaces and their assigned sources.
|
|
- **Validation**: On upload, the backend will use `ffprobe` to verify the codec (H.264 required) and resolution (Warn if > 1080p).
|
|
- **Resource Warning**: The UI will display a "High Load" warning if multiple 1080p videos are assigned, recommending 720p for stable multi-surface playback.
|
|
|
|
### 4. Graphics & Build Strategy (The "Source-First" Build)
|
|
To handle the "Highlight Surface" functionality, we will modify the `ofxPiMapper` C++ source code to include a `/ofxPiMapper/surface/highlight` OSC listener.
|
|
- **Build Safety**: The setup script will increase the swap file to 2GB during the ~1 hour compilation to prevent OOM panics on the Pi 3B.
|
|
- **Binary Fallback**: The script will accept an optional argument to point to a pre-compiled binary if available.
|
|
|
|
### 5. Log & Data Streaming
|
|
- **Log Throttling**: The backend will buffer and throttle the `stdout` stream (max 10 lines per 500ms) to prevent WebSocket congestion.
|
|
- **State Persistence**: A explicit "Save Mapping" button in the UI will trigger the `/ofxPiMapper/save` OSC command to persist changes to the `settings.xml` file.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- **[Risk] RAM Exhaustion** → **Mitigation**: Use Preact/Vite for a lightweight frontend, set `NODE_OPTIONS="--max-old-space-size=512"`, and force `npm jobs=1`.
|
|
- **[Risk] WiFi Interference** → **Mitigation**: Prioritize the WebSocket channel for vertex movements.
|
|
- **[Risk] ofxPiMapper Build Time** → **Mitigation**: Attempt to pull pre-compiled binaries first; if building from source, notify the user of the 1-hour duration.
|