timothy/mapper
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6cc9d88842297f6d9c37b9685ab1843638a8ebc7
mapper/openspec/changes/ofxpimapper-full-stack/design.md
Timothy Hofland 158e6a204f feat: add ofxpimapper-full-stack OpenSpec artifacts 
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.
2026-03-10 22:34:02 +01:00

3.0 KiB
Raw Blame History

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.