Initial skills documentation — 25 categories, all SKILL.md + references + scripts
This commit is contained in:
root
@@ -0,0 +1,125 @@
|
||||
---
|
||||
name: digital-signage
|
||||
description: |-
|
||||
Build and maintain a multi-tenant digital signage CMS platform — Raspberry Pi kiosk players, customer upload portal, playlist management, device registration. Replaces OptiSigns ($15-30/mo).
|
||||
author: Sho'Nuff
|
||||
version: 1.0.0
|
||||
tags: [raspberry-pi, signage, kiosk, multi-tenant, content-management]
|
||||
platforms: [linux]
|
||||
---
|
||||
|
||||
# Digital Signage CMS
|
||||
|
||||
Multi-tenant digital signage platform. Customers upload images/video via a web portal, create playlists, and Raspberry Pi players display content in fullscreen kiosk mode.
|
||||
|
||||
## Project Directory
|
||||
|
||||
All docs live at `/root/projects/digital-signage/`. Key files:
|
||||
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
| `README.md` | Full architecture, multi-tenant hierarchy, Pi registration flow, MVP scope |
|
||||
| `optisigns-comparison.md` | Feature-by-feature comparison vs OptiSigns (what we build vs what we skip) |
|
||||
| `cms/customer-setup-guide.md` | Customer-facing 9-step quick-start guide (printable) |
|
||||
| `player/provisioning.md` | Zero-touch Pi provisioning — first-boot script, SD card imaging, recovery |
|
||||
| `player/device-identification.md` | Hidden Ctrl+I overlay for support — device name, serial, IP, playlist |
|
||||
| `mockups/` | Frontend HTML mockups (customer portal) |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Customer Web Portal Raspberry Pi Player
|
||||
┌────────────────────────┐ ┌──────────────────────┐
|
||||
│ Login (per tenant) │ │ Registration script │
|
||||
│ Upload images/video │ API │ POST /api/register │
|
||||
│ Create playlists │ ←───────→ │ Poll /api/playlist │
|
||||
│ Manage devices │ │ Chromium kiosk mode │
|
||||
│ Registration codes │ │ Fullscreen playback │
|
||||
└────────────────────────┘ └──────────────────────┘
|
||||
│
|
||||
▼
|
||||
FastAPI + SQLite + S3
|
||||
```
|
||||
|
||||
### Multi-tenant hierarchy
|
||||
```
|
||||
Platform
|
||||
├── Tenant: Joe's Diner
|
||||
│ ├── Users: admin, staff@...
|
||||
│ ├── Device: Main Lobby Pi
|
||||
│ ├── Device: Menu Board Pi
|
||||
│ └── Content: 8 items, 2 playlists
|
||||
├── Tenant: Main Street Gym
|
||||
│ └── Device: Front Desk Pi
|
||||
└── Tenant: Third Coast Dental
|
||||
├── Device: Waiting Room Pi
|
||||
├── Device: Exam Room Pi
|
||||
└── Device: Hallway Pi
|
||||
```
|
||||
|
||||
Key rule: **one customer = one tenant = unlimited devices.** Content libraries are per-tenant. Playlists assignable to one or multiple devices.
|
||||
|
||||
## OptiSigns Replication
|
||||
|
||||
| Tier | What's Included | Timeline |
|
||||
|------|----------------|----------|
|
||||
| **Phase 1 — MVP** | Upload images/video, playlists (ordered + shuffle), multi-tenant, Pi registration, fullscreen kiosk, device identification overlay | ~2 weeks |
|
||||
| **Phase 2 — Parity** | Content scheduling, multi-user per tenant, thumbnail previews, auto-update on content change | ~1 week |
|
||||
| **Phase 3 — Surpass** | Sho'Nuff text-to-broadcast integration, ops portal dark theme, no OptiSigns logo, API for remote control | ~1 week |
|
||||
|
||||
**What we skip:** Power BI dashboards, touch interactivity, video walls, background music licensing, wireless presentation.
|
||||
|
||||
## Pi Provisioning — Zero Touch
|
||||
|
||||
1. **Image SD card** with Raspberry Pi OS lite + first-boot script (auto-login, Chromium, player service)
|
||||
2. **Generate registration code** from CMS
|
||||
3. **Ship Pi** to customer (HDMI + power cable included)
|
||||
4. **Customer plugs in** — two cables: HDMI + power
|
||||
5. **Pi boots**, auto-registers, fetches playlist, plays content
|
||||
|
||||
**On power loss/reboot:** Auto-restarts and resumes. Already registered → skips to content.
|
||||
**On SD card failure:** Flash new card → 5 min fix → re-register from CMS.
|
||||
**On TV change:** Pi auto-detects resolution via HDMI EDID. No config needed.
|
||||
|
||||
## Device Registration Flow
|
||||
|
||||
```
|
||||
1. Customer portal → Devices → Register New Device → code: SIGN-4K7P-M9X2
|
||||
2. Pi boots → runs registration script → POST /api/register with code + serial
|
||||
3. Server: creates device under tenant → returns device_id + token
|
||||
4. Pi stores token locally → starts polling GET /api/playlist/:device_id every 60s
|
||||
5. CMS playlist change → Pi picks it up on next poll
|
||||
```
|
||||
|
||||
## Device Identification Overlay
|
||||
|
||||
Hidden overlay triggered by Ctrl+I pressed 3 times in 2 seconds (or remote API call). Shows device name, serial, IP, playlist, model, last sync. Auto-hides after 30s. No customer sees it in normal operation.
|
||||
|
||||
### 3 trigger methods:
|
||||
1. **Keyboard:** `Ctrl+I` × 3 within 2 seconds
|
||||
2. **Remote API:** `POST /api/devices/:id/identify` (device polls `/status` every 10s)
|
||||
3. **Boot flag:** `./kiosk.sh --identify`
|
||||
|
||||
## Resolution Handling
|
||||
|
||||
**Pi auto-detects via HDMI EDID.** Upload content at highest quality (4K if you have it). Pi scales to whatever display is connected. CMS does NOT need to know or care about output resolution — that's the Pi's job.
|
||||
|
||||
| Pi Model | Max Output | Best For |
|
||||
|----------|-----------|----------|
|
||||
| Pi 3 | 1080p @ 60fps | Stills, basic slideshows |
|
||||
| Pi 4 | 4K @ 60fps | Mixed content, smooth video |
|
||||
| Pi 5 | 4K @ 60fps HDR | Heavy video, multiple layers |
|
||||
|
||||
## Frontend Portal Mockup
|
||||
|
||||
The customer portal mockup lives at `ops.itpropartner.com/signage-mockup.html` — dark theme, 6 views (login, dashboard, content, playlists, devices, register Pi modal). Demo tenant: Joe's Diner with 3 devices.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Pi registration code expiry** — codes should auto-expire after 24h to prevent reuse/snooping
|
||||
- **Offline playback** — player should cache the current playlist locally so it keeps playing if network drops
|
||||
- **Content moderation** — uploaded files need type/size validation before storage. Allow common image formats (jpg, png, webp) and video (mp4, mov, webm). Reject executables, archives, scripts
|
||||
- **Multi-user per tenant** — Phase 2 feature but plan the DB schema for it now (users table with tenant_id FK)
|
||||
- **Scheduling complexity** — time-based playlists need a cron-like scheduler on the backend, not just the player polling interval
|
||||
- **Player self-healing** — if Chromium crashes (OOM on Pi 3), the service should auto-restart. Player script needs `Restart=always` in the systemd unit
|
||||
- **Bandwidth** — multiple Pis polling every 60s is negligible. Multiple Pis fetching 140MB video files simultaneously is not. Consider S3 signed URLs or CDN for content delivery at scale
|
||||
Reference in New Issue
Block a user