40 lines
2.6 KiB
Markdown
40 lines
2.6 KiB
Markdown
## Context
|
|
|
|
The project aims to modernize the control interface for `ofxPiMapper` on the Raspberry Pi 3B. Currently, users rely on legacy PHP scripts (PocketVJ) or a local monitor/keyboard. The Pi 3B has significant resource constraints (1GB RAM, older CPU), requiring a highly efficient headless solution.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Provide a responsive, headless mapping UI accessible via browser.
|
|
- Enable real-time remote manipulation of mapping surfaces via OSC.
|
|
- Implement a robust system for media management and system monitoring.
|
|
- Ensure the system is lightweight enough to run alongside `ofxPiMapper` on a Pi 3B.
|
|
|
|
**Non-Goals:**
|
|
- **Automatic Calibration**: Computer-vision based auto-mapping is explicitly out of scope for this version.
|
|
- **Multi-Projector Sync**: Synchronizing multiple Pi units is not part of this design.
|
|
- **Advanced Video Effects**: Real-time shaders or complex video processing beyond what `ofxPiMapper` provides.
|
|
|
|
## Decisions
|
|
|
|
### 1. Technology Stack
|
|
- **Frontend**: React (using Vite for fast development and lean production builds).
|
|
- **Backend**: Node.js with Express. Node.js is chosen for its excellent asynchronous handling of WebSockets and its mature OSC libraries (`node-osc`).
|
|
- **Communication**: WebSockets (Socket.io) will be used for the frontend-to-backend real-time vertex updates to minimize latency compared to REST.
|
|
|
|
### 2. OSC Bridge Architecture
|
|
The Node.js server will act as a transparent bridge. It will listen for WebSocket events from the UI and immediately translate them into UDP OSC packets directed at `localhost:9999` where `ofxPiMapper` is listening.
|
|
|
|
### 3. Headless Networking
|
|
- **mDNS**: `avahi-daemon` will be configured to provide `mpvj.local` access.
|
|
- **Access Point**: `hostapd` and `dnsmasq` will be managed via shell scripts triggered by the Node.js API to allow the user to toggle between AP and Client modes.
|
|
|
|
### 4. Media Storage
|
|
Media will be stored in `/home/pi/media`. The Node.js API will provide a file-browser endpoint and handle `multipart/form-data` uploads.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- **[Risk] RAM Exhaustion on Pi 3B** → **Mitigation**: We will use a "lite" version of the React frontend (potentially Preact) and keep Node.js dependencies to a minimum. We will also monitor memory usage via the dashboard.
|
|
- **[Risk] WiFi Latency in AP Mode** → **Mitigation**: We will prioritize WebSocket traffic for vertex movements and use binary formats if necessary to reduce overhead.
|
|
- **[Risk] ofxPiMapper Crash** → **Mitigation**: The Node.js API will monitor the process and provide a "Restart Mapper" button in the UI.
|