Initial commit — 2026-07-15

2026-07-15 17:32:04 -04:00
commit 55609f6e91
5 changed files with 647 additions and 0 deletions
@@ -0,0 +1,102 @@
+# Device Identification — Support Overlay
+
+## Problem
+When a customer calls support saying "my screen isn't working," we need to know WHICH of their devices we're talking to without relying on them to read a serial number off the back of a Pi.
+
+## Solution
+Hidden overlay on the player that only appears when triggered. No customer sees it in normal operation.
+
+## How it looks
+```
+┌──────────────────────────────────────┐
+│                                      │
+│         <normal content playing>      │
+│                                      │
+│                                      │
+│   ┌────────────────────────────┐     │
+│   │ 🔍 DEVICE                    │     │
+│   │ Main Lobby Pi               │     │
+│   │ Serial: 10000000a1b2c3d4    │     │
+│   │ IP: 192.168.1.50            │     │
+│   │ Playlist: Main Menu Loop    │     │
+│   │ Last sync: 30s ago          │     │
+│   │ Model: RPi 4 Model B 4GB   │     │
+│   └────────────────────────────┘     │
+└──────────────────────────────────────┘
+```
+
+## Trigger Methods (build all 3)
+
+### 1. Keyboard shortcut — Ctrl+I pressed 3 times in 2s
+On-site tech can trigger it without any tools.
+
+```javascript
+var keyCount = 0, keyTimer;
+document.addEventListener('keydown', function(e) {
+  if (e.ctrlKey && e.key === 'i') {
+    keyCount++;
+    clearTimeout(keyTimer);
+    keyTimer = setTimeout(function() { keyCount = 0; }, 2000);
+    if (keyCount >= 3) { showOverlay(); keyCount = 0; }
+  }
+});
+```
+
+### 2. Remote API trigger
+I call this from the ops portal — device polls for the flag.
+
+```javascript
+// Player polls every 10s
+setInterval(function() {
+  fetch('/api/device/' + deviceId + '/status')
+    .then(function(r) { return r.json(); })
+    .then(function(d) { if (d.identify) showOverlay(); });
+}, 10000);
+```
+
+API endpoint: `POST /api/devices/:id/identify` (returns `{identify: true}`, auto-clears after 30s)
+
+### 3. Boot-time flag
+For when support asks customer to reboot with a specific trigger:
+
+```bash
+# On the Pi
+curl -s https://signage.itpropartner.com/identify.sh | bash -s <device-id>
+# Rebooting with this arg causes the player to start in visibility mode
+./kiosk.sh --identify
+```
+
+## Overlay Behavior
+- **Auto-hides** after 30 seconds
+- Can be dismissed early with another Ctrl+I
+- **No click-away** — intentionally no close button (onsite tech might fat-finger)
+- Refresh/DST resets it back to hidden
+- **No data exfiltration** — shows only device metadata, no passwords or tokens
+
+## Overlay HTML (skeleton)
+```html
+<div id="deviceIdOverlay"
+     style="display:none;position:fixed;bottom:16px;right:16px;
+            background:rgba(0,0,0,0.88);color:#fff;padding:14px 18px;
+            border-radius:10px;font-family:monospace;font-size:13px;
+            line-height:1.5;z-index:99999;max-width:320px;
+            backdrop-filter:blur(4px);">
+  <div style="display:flex;align-items:center;gap:8px;margin-bottom:6px;
+              font-size:15px;color:#f59e0b;">
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none"
+         stroke="currentColor" stroke-width="2">
+      <circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><circle cx="12" cy="8" r="1"/>
+    </svg>
+    Device Identity
+  </div>
+  <div id="devName" style="font-weight:700;margin-bottom:4px;"></div>
+  <div id="devSerial" style="color:#94a3b8;font-size:12px;"></div>
+  <div id="devIp" style="color:#94a3b8;font-size:12px;"></div>
+  <div id="devPlaylist" style="color:#94a3b8;font-size:12px;"></div>
+  <div id="devModel" style="color:#94a3b8;font-size:12px;"></div>
+  <div id="devLastSync" style="color:#64748b;font-size:11px;margin-top:4px;"></div>
+</div>
+```
+
+## Implementation Status
+📝 **Not yet built** — queued for player code phase