From 158e6a204fad14b429812ad273bea5f840881293 Mon Sep 17 00:00:00 2001 From: Timothy Hofland Date: Tue, 10 Mar 2026 22:34:02 +0100 Subject: [PATCH] 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. --- .../ofxpimapper-full-stack/.openspec.yaml | 2 + .../changes/ofxpimapper-full-stack/design.md | 46 +++++++++++++++++++ .../ofxpimapper-full-stack/proposal.md | 32 +++++++++++++ .../specs/ofxpimapper-full-stack/spec.md | 34 ++++++++++++++ .../changes/ofxpimapper-full-stack/tasks.md | 30 ++++++++++++ 5 files changed, 144 insertions(+) create mode 100644 openspec/changes/ofxpimapper-full-stack/.openspec.yaml create mode 100644 openspec/changes/ofxpimapper-full-stack/design.md create mode 100644 openspec/changes/ofxpimapper-full-stack/proposal.md create mode 100644 openspec/changes/ofxpimapper-full-stack/specs/ofxpimapper-full-stack/spec.md create mode 100644 openspec/changes/ofxpimapper-full-stack/tasks.md diff --git a/openspec/changes/ofxpimapper-full-stack/.openspec.yaml b/openspec/changes/ofxpimapper-full-stack/.openspec.yaml new file mode 100644 index 0000000..f34a385 --- /dev/null +++ b/openspec/changes/ofxpimapper-full-stack/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-10 diff --git a/openspec/changes/ofxpimapper-full-stack/design.md b/openspec/changes/ofxpimapper-full-stack/design.md new file mode 100644 index 0000000..12b887e --- /dev/null +++ b/openspec/changes/ofxpimapper-full-stack/design.md @@ -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. diff --git a/openspec/changes/ofxpimapper-full-stack/proposal.md b/openspec/changes/ofxpimapper-full-stack/proposal.md new file mode 100644 index 0000000..ec3688f --- /dev/null +++ b/openspec/changes/ofxpimapper-full-stack/proposal.md @@ -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. diff --git a/openspec/changes/ofxpimapper-full-stack/specs/ofxpimapper-full-stack/spec.md b/openspec/changes/ofxpimapper-full-stack/specs/ofxpimapper-full-stack/spec.md new file mode 100644 index 0000000..edb01cd --- /dev/null +++ b/openspec/changes/ofxpimapper-full-stack/specs/ofxpimapper-full-stack/spec.md @@ -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. diff --git a/openspec/changes/ofxpimapper-full-stack/tasks.md b/openspec/changes/ofxpimapper-full-stack/tasks.md new file mode 100644 index 0000000..81506d9 --- /dev/null +++ b/openspec/changes/ofxpimapper-full-stack/tasks.md @@ -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.