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.
This commit is contained in:
Timothy Hofland
2
openspec/changes/ofxpimapper-full-stack/.openspec.yaml
Normal file
2
openspec/changes/ofxpimapper-full-stack/.openspec.yaml
Normal file
@ -0,0 +1,2 @@
|
|||||||
|
schema: spec-driven
|
||||||
|
created: 2026-03-10
|
||||||
46
openspec/changes/ofxpimapper-full-stack/design.md
Normal file
46
openspec/changes/ofxpimapper-full-stack/design.md
Normal file
@ -0,0 +1,46 @@
|
|||||||
|
## 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.
|
||||||
32
openspec/changes/ofxpimapper-full-stack/proposal.md
Normal file
32
openspec/changes/ofxpimapper-full-stack/proposal.md
Normal file
@ -0,0 +1,32 @@
|
|||||||
|
## Why
|
||||||
|
|
||||||
|
Currently, setting up a Raspberry Pi for projection mapping requires manually piecing together the OS, the mapping engine (`ofxPiMapper`), and various control scripts. This is fragmented, difficult to manage headlessly, and lacks a modern "appliance" feel. `ofxpimapper-full-stack` aims to unify these into a single, polished, and professional product: the Modern PocketVJ (MPVJ). It provides an "it just works" experience for artists, from the initial setup script to the real-time web-based mapping remote.
|
||||||
|
|
||||||
|
## What Changes
|
||||||
|
|
||||||
|
- **Unified Headless Installer**: A single setup script that installs the entire stack, including the `ofxPiMapper` engine, Node.js backend, and React frontend.
|
||||||
|
- **Integrated Mapping Engine**: Automated installation of `ofxPiMapper` (pre-compiled binary or source build) with a systemd service to launch fullscreen on boot.
|
||||||
|
- **Virtual Canvas 2.0**: A responsive React/Tailwind web UI for real-time vertex/surface manipulation via WebSockets, with live feedback on the beamer.
|
||||||
|
- **Enhanced Media Vault**: Complete media management (upload/delete/preview) with the ability to assign different sources (video/image/color) to individual surfaces.
|
||||||
|
- **Appliance Dashboard**: Integrated monitoring of system health (CPU, RAM, Temp) and process status, with remote power and restart controls.
|
||||||
|
- **Hybrid Networking**: A robust networking stack that maintains a permanent Access Point while allowing connection to external venue WiFi via a web interface.
|
||||||
|
|
||||||
|
## Capabilities
|
||||||
|
|
||||||
|
### New Capabilities
|
||||||
|
- `ofxpimapper-engine`: The core C++ mapping engine, integrated into the system-wide process management.
|
||||||
|
- `web-remote-dashboard`: A modern, responsive TUI-inspired web interface for full system control.
|
||||||
|
- `media-source-assignment`: The ability to dynamically map specific files or colors to specific geometric surfaces.
|
||||||
|
- `live-logs-streaming`: Real-time streaming of system and mapper logs to the web interface.
|
||||||
|
|
||||||
|
### Modified Capabilities
|
||||||
|
- `headless-installer`: Upgraded to handle the C++ engine installation and graphics driver configuration.
|
||||||
|
- `osc-bridge-api`: Expanded to handle naming, surface selection highlighting, and source assignment.
|
||||||
|
- `hybrid-network-control`: Updated with a scan-and-connect web UI while preserving the AP.
|
||||||
|
|
||||||
|
## Impact
|
||||||
|
|
||||||
|
- **Hardware**: Strictly optimized for the Raspberry Pi 3B (1GB RAM).
|
||||||
|
- **User Experience**: Transition from a "CLI-first" or "Desktop-first" workflow to a "Web-Remote-first" workflow.
|
||||||
|
- **Performance**: Heavy reliance on WebSockets and optimized C++ binaries to ensure low-latency interaction.
|
||||||
|
- **Stability**: Automated swap management and process monitoring to prevent OOM crashes during high-resolution playback.
|
||||||
@ -0,0 +1,34 @@
|
|||||||
|
# ofxpimapper-full-stack Spec
|
||||||
|
|
||||||
|
## System Dashboard (Status Tab)
|
||||||
|
- **GIVEN** the web UI is loaded
|
||||||
|
- **THEN** it SHALL display real-time CPU Load, RAM Usage, and CPU Temperature.
|
||||||
|
- **AND** it SHALL show the status of the `ofxPiMapper` process (Running/Stopped).
|
||||||
|
- **AND** it SHALL provide "Restart Mapper", "Reboot Pi", and "Shutdown Pi" buttons.
|
||||||
|
- **AND** it SHALL display the "Throttled Logs" (max 10 lines per 500ms) from the Mapper process.
|
||||||
|
|
||||||
|
## Mapping Engine (Mapping Tab)
|
||||||
|
- **GIVEN** the Virtual Canvas
|
||||||
|
- **WHEN** a vertex is dragged in the UI
|
||||||
|
- **THEN** it SHALL send an OSC message to `localhost:9999` via WebSockets in < 50ms.
|
||||||
|
- **AND** it SHALL support adding/deleting surfaces (Quad/Triangle).
|
||||||
|
- **AND** it SHALL provide a prominent "Save Mapping" button to persist changes to disk.
|
||||||
|
- **AND** clicking a surface in the UI SHALL send a highlight OSC command to the beamer.
|
||||||
|
|
||||||
|
## Media Management (Media Tab)
|
||||||
|
- **GIVEN** the Media Vault
|
||||||
|
- **WHEN** a file is uploaded
|
||||||
|
- **THEN** it SHALL be stored in `/home/pi/media`.
|
||||||
|
- **AND** the backend SHALL validate that the file is H.264 and show a warning if resolution exceeds 1080p.
|
||||||
|
- **AND** the user SHALL be able to assign any file to any named surface, with a "Resource Warning" if total pixel throughput is too high.
|
||||||
|
|
||||||
|
## Networking (Network Tab)
|
||||||
|
- **GIVEN** the Network settings
|
||||||
|
- **THEN** the UI SHALL list available WiFi networks for client mode connection.
|
||||||
|
- **AND** it SHALL allow changing the AP SSID and Password.
|
||||||
|
- **AND** it SHALL display the current IP Address and Hostname (`.local`).
|
||||||
|
|
||||||
|
## Hardware Constraints
|
||||||
|
- **Processor**: Raspberry Pi 3B (ARMv8).
|
||||||
|
- **Memory**: 1GB LPDDR2.
|
||||||
|
- **Resolution**: Support up to 1080p hardware-accelerated H.264 video.
|
||||||
30
openspec/changes/ofxpimapper-full-stack/tasks.md
Normal file
30
openspec/changes/ofxpimapper-full-stack/tasks.md
Normal file
@ -0,0 +1,30 @@
|
|||||||
|
## 1. Setup Script Upgrades
|
||||||
|
|
||||||
|
- [ ] 1.1 Add `ofxPiMapper` installation logic (source build with 2GB swap safety).
|
||||||
|
- [ ] 1.2 Modify `ofxPiMapper` C++ source code to add `/ofxPiMapper/surface/highlight` OSC listener.
|
||||||
|
- [ ] 1.3 Implement graphics driver configuration (KMS/DRM) for headless operation.
|
||||||
|
|
||||||
|
## 2. Backend Expansion (Node.js)
|
||||||
|
|
||||||
|
- [ ] 2.1 Implement WebSocket (Socket.io) handlers for low-latency vertex updates.
|
||||||
|
- [ ] 2.2 Create the Throttled Log Streamer (max 10 lines / 500ms) for process output.
|
||||||
|
- [ ] 2.3 Implement the "Mapping Manifest" with `ffprobe` codec validation (H.264).
|
||||||
|
- [ ] 2.4 Add System Control endpoints (Shutdown, Reboot, Restart Mapper, Save Mapping).
|
||||||
|
|
||||||
|
## 3. Frontend Overhaul (React/Tailwind)
|
||||||
|
|
||||||
|
- [ ] 3.1 Implement the 5-tab navigation system (Dashboard, Mapping, Media, Network, System).
|
||||||
|
- [ ] 3.2 Build the "Responsive Dashboard" with real-time stats (CPU/RAM/Temp).
|
||||||
|
- [ ] 3.3 Create the "Media Vault" with file upload, preview, and delete.
|
||||||
|
- [ ] 3.4 Upgrade the "Virtual Canvas" with Surface Naming, Quad/Triangle adding, and drag/scale/rotate.
|
||||||
|
|
||||||
|
## 4. Hybrid Networking UI
|
||||||
|
|
||||||
|
- [ ] 4.1 Implement the WiFi scanner and client-mode connection interface.
|
||||||
|
- [ ] 4.2 Add AP configuration (SSID/Password change) with graceful reboot handling.
|
||||||
|
|
||||||
|
## 5. Integration & Stress-Testing
|
||||||
|
|
||||||
|
- [ ] 5.1 Test 1080p playback stability on Pi 3B with active mapping.
|
||||||
|
- [ ] 5.2 Validate the "LAN-Rescue" mDNS connectivity.
|
||||||
|
- [ ] 5.3 Conduct end-to-end "Clean Install" test using the setup script.
|
||||||
Reference in New Issue
Block a user