secubox-deb/remote-ui/round

SecuBox Eye Remote — Round Edition

Remote control dashboard for HyperPixel 2.1 Round Touch (480×480 px) on Raspberry Pi Zero W or x64/amd64 live systems.

More than a simple status display — the Eye Remote transforms into a powerful debugging and security tool with multiple USB gadget modes.

Current Version

Version	Status	Features
v2.2.1	✅ Stable	3D cube + rainbow rings, real metrics, fallback display
v2.0.0	🔄 Legacy	Agent-based (broken imports, see #78)

What's New in v2.2.1

• Fallback Display: Stable 3D rotating cube with rainbow ring visualization
• Real Metrics: Direct API calls to MOCHAbin for CPU, memory, disk, temp
• Connection States: OFFLINE → CONNECTING → ONLINE → COMMUNICATING
• PIL Dependencies: libopenjp2-7, libtiff6 pre-installed
• Fast Boot: All packages pre-installed via QEMU chroot

Known Issues

• #78: eye-agent import errors (disabled)
• #79: Buildroot investigation pending

---

Roadmap

     v2.2.1 (current)          v2.3.0                    v3.0.0
         │                        │                         │
    ┌────┴────┐              ┌────┴────┐              ┌────┴────┐
    │ Fallback │              │  Agent  │              │  Multi  │
    │ Display  │──────────────│  Fixed  │──────────────│ SecuBox │
    │ 3D Cube  │              │ Radial  │              │  Mesh   │
    └──────────┘              │  Menu   │              └─────────┘
                              └─────────┘

v2.3.0 — Agent Revival

Task	Issue	Status
Fix Python imports (relative → absolute)	#78	🔄 TODO
Implement DashboardRenderer class	#78	🔄 TODO
Radial touch menu system	—	🔄 TODO
Multi-SecuBox device switching	—	💭 Planned

v2.4.0 — Performance

Task	Issue	Status
Buildroot minimal image (~100MB)	#79	💭 Research
Fast boot (<10s)	#79	💭 Planned
Reduced memory footprint	—	💭 Planned

v3.0.0 — Multi-Device Mesh

Task	Issue	Status
Multiple SecuBox discovery	—	💭 Concept
Mesh status aggregation	—	💭 Concept
Remote alert notifications	—	💭 Concept

Ideas & Proposals

Create issues to discuss these features!

• Droplet Mode: Display config QR codes for device provisioning
• Alert Mode: Flash display on security events
• Kiosk Auth: FIDO2/WebAuthn hardware key mode
• OTA Updates: Self-update via SecuBox API

AI Prompts (GPT/Gemini/Claude)

Infographic Roadmap Generator

Create a colored infographic roadmap for "SecuBox Eye Remote" project.

PRODUCT: Circular 480x480 touchscreen dashboard (Pi Zero W + HyperPixel Round)
         Connects via USB to SecuBox security appliance
         Shows real-time metrics with 3D cube + rainbow ring visualization

COLOR PALETTE (Cyberpunk/Hermetic):
- Background: #0a0a0f (cosmos black)
- Gold accent: #c9a84c (hermetic gold)
- Alert red: #e63946 (cinnabar)
- Success green: #00ff41 (matrix green)
- Info cyan: #00d4ff (cyber cyan)
- Purple: #6e40c9 (void purple)

TIMELINE (horizontal or diagonal flow):

v2.2.1 [NOW - STABLE] - Gold border
├─ 3D rotating cube display
├─ Rainbow ring metrics (CPU/MEM/DISK/TEMP)
├─ Connection states (OFFLINE→ONLINE)
└─ USB OTG composite gadget

v2.3.0 [NEXT] - Cyan border
├─ Fix agent Python imports (#78)
├─ Radial touch menu system
├─ Multi-metric dashboard
└─ Touch gesture navigation

v2.4.0 [PERFORMANCE] - Green border
├─ Buildroot minimal image (#79)
├─ <10 second boot time
├─ ~100MB image size
└─ Reduced memory footprint

v3.0.0 [FUTURE] - Purple border
├─ Multi-SecuBox mesh discovery
├─ Aggregated security status
├─ Remote alert notifications
└─ Distributed monitoring

STYLE: Tech/cyberpunk aesthetic, circuit board patterns,
       glowing edges, dark theme, minimal but informative
       Include small icon of circular display device

OUTPUT: 1920x1080 or 1200x630 (social preview size)

Product Status Image Generator

Create a product status infographic for "SecuBox Eye Remote v2.2.1"

DEVICE: Circular 480x480 touchscreen (HyperPixel 2.1 Round) mounted on Raspberry Pi Zero W
PURPOSE: External security dashboard that connects via USB to SecuBox network appliance

VISUAL LAYOUT:
Center: 3D render of circular display device showing colorful dashboard
        - Black circular bezel
        - Display showing: rotating 3D cube + rainbow concentric rings + metrics text
        - Small Pi Zero W board visible behind

Around the device, status badges:

[TOP LEFT - HARDWARE]
✅ Pi Zero W (ARMv6 512MB)
✅ HyperPixel 2.1 Round 480×480
✅ USB OTG Composite Gadget
✅ Touch input (I2C)

[TOP RIGHT - SOFTWARE]
✅ Debian armhf
✅ Python 3 + PIL/Pillow
✅ FastAPI client
✅ Systemd service

[BOTTOM LEFT - FEATURES]
✅ 3D rotating cube animation
✅ Rainbow ring metrics (6 modules)
✅ Real-time: CPU/MEM/DISK/TEMP
✅ Connection states display
✅ 30 FPS framebuffer render

[BOTTOM RIGHT - CONNECTIVITY]
✅ USB Network (10.55.0.0/30)
✅ USB Serial console
✅ WiFi fallback
✅ Direct API to SecuBox

[BOTTOM CENTER - VERSION BOX]
v2.2.1 STABLE
Released: 2026-05-11
Image: 576MB compressed
Boot: ~60 seconds

COLOR SCHEME (Cyberpunk):
- Background: #0a0a0f (deep black)
- Accent borders: #c9a84c (gold)
- Success checks: #00ff41 (matrix green)
- Info text: #00d4ff (cyber cyan)
- Highlights: #6e40c9 (purple glow)

STYLE: Dark tech aesthetic, subtle grid pattern background,
       glowing edges on device, professional product sheet look

SIZE: 1920x1080 or 1200x630

Issue Template Generator

You are creating a GitHub issue for SecuBox Eye Remote (Pi Zero W + HyperPixel 2.1 Round display).

**Project context:**
- Repo: CyberMind-FR/secubox-deb
- Subproject: remote-ui/round/
- Current version: v2.2.1 (fallback display working)
- Hardware: Pi Zero W (armhf), HyperPixel 2.1 Round 480x480
- Stack: Python 3, PIL/Pillow, FastAPI, systemd
- Connection: USB OTG composite gadget to SecuBox (10.55.0.0/30)

**Issue format:**
## Context
[Brief description of the feature/bug and why it matters]

## Current Behavior
[What happens now - for bugs only]

## Expected Behavior / Goal
[What should happen or what we want to achieve]

## Tasks
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3

## Technical Notes
- Files: `remote-ui/round/agent/...`
- Services: `secubox-fallback-display.service`
- API: `http://10.55.0.1:8000/api/v1/system/metrics`

## References
- Related: #XX
- Docs: [README](remote-ui/round/README.md)

**Labels to use:** `eye-remote`, `enhancement` or `bug`, optionally `hardware`, `ui`

References

• Wiki: Eye Remote Documentation
• Issues: eye-remote label
• Internal: .claude/WIP.md | .claude/TODO.md

---

Overview

          ┌─────────────────────┐
          │   ● SECUBOX EYE     │  ← Mode indicator (OTG/WiFi/SIM)
          │   ┌───────────────┐ │
          │  ┌┤  ╔═══════════╗├┐│
          │  │└──╢  14:32:07 ╟┘││  ← Time/Status center
          │  │   ╢ NOMINAL   ╟ ││
          │  │┌──╢ secubox-zr╟─┐│
          │  ││  ╚═══════════╝ ││
          │  ││ [AUTH]  [WALL] ││  ← Module pods (6)
          │  │└─────────────────┘│
          │  └──[TTY]  [AUTH]───┘│  ← Mode selector (touch)
          │        480×480       │
          └─────────────────────┘
              HyperPixel 2.1
           or x64 touchscreen

Key Features

Feature	Description
5 USB Modes	Normal, Flash, Debug, TTY, Auth
Eye Remote	Security key with QR auth display
U-Boot Access	Virtual keyboard for bootloader
Live Flash	Bootable USB recovery mode
x64 Support	Live boot on any touchscreen

---

Matériel requis

Composant	Référence	Notes
Raspberry Pi Zero W	RPi Zero W / Zero 2 W	WiFi intégré requis
HyperPixel 2.1 Round	Pimoroni HyperPixel 2.1 Round	Écran tactile circulaire 480×480, SPI+I2C
Carte microSD	8 Go minimum	Class 10 recommandée
Alimentation	5V 2.5A	Via micro-USB
Câble USB	Data-capable	Must be DATA port, not PWR

Spécifications HyperPixel 2.1 Round

• Résolution : 480×480 pixels (circulaire)
• Contrôleur LCD : ST7701S (SPI init)
• Contrôleur tactile : I2C bus 11, adresse 0x15, GPIO 27 (interrupt)
• Interface : DPI (Display Parallel Interface) via GPIO

---

USB Gadget Modes

The Eye Remote supports 5 operational modes via USB OTG composite gadget:

┌────────────┬────────────┬──────────────────────────────────────────┐
│ Command    │ Mode       │ Functions                                │
├────────────┼────────────┼──────────────────────────────────────────┤
│ start      │ Normal     │ Network (ECM) + Serial                   │
│ flash      │ Recovery   │ Bootable USB + Serial (U-Boot access)    │
│ debug      │ Debug      │ Network + Storage + Serial               │
│ tty        │ Keyboard   │ Virtual keyboard + Serial (automation)   │
│ auth       │ Eye Remote │ FIDO/U2F HID + QR display (security key) │
└────────────┴────────────┴──────────────────────────────────────────┘

Mode: Normal (default)

┌────────────────────────────────────┐
│         ● SECUBOX EYE             │
│           OTG MODE                 │
│                                    │
│         ╔═══════════╗              │
│         ║  14:32:07 ║              │
│         ║ NOMINAL   ║              │
│         ║ up 24h12  ║              │
│         ╚═══════════╝              │
│                                    │
│   [AUTH]  [WALL]  [BOOT]          │
│   [MIND]  [ROOT]  [MESH]          │
│                                    │
│   ═══════════════════════          │ ← 6 status rings
│     CPU 23% │ MEM 41%              │
└────────────────────────────────────┘

• ECM/RNDIS network: 10.55.0.0/30
• CDC-ACM serial: /dev/ttyGS0 @ 115200

Mode: Flash (Recovery)

┌────────────────────────────────────┐
│         ● FLASH MODE              │
│      ████████████████ 100%         │ ← Progress bar
│                                    │
│         ╔═══════════╗              │
│         ║  READY    ║              │
│         ║ Boot from ║              │
│         ║   USB     ║              │
│         ╚═══════════╝              │
│                                    │
│   💾 secubox-flash.img             │
│      256MB bootable                │
│                                    │
│   [REBOOT TARGET]  [CANCEL]        │
└────────────────────────────────────┘

• Mass Storage: Bootable recovery image
• Serial: U-Boot console access
• Use case: Flash/recover bricked SecuBox

Mode: Debug

┌────────────────────────────────────┐
│         ● DEBUG MODE              │
│                                    │
│    ┌──────────────────────────┐    │
│    │ Network: 10.55.0.2       │    │
│    │ Serial:  /dev/ttyACM0    │    │
│    │ Storage: secubox-debug   │    │
│    └──────────────────────────┘    │
│                                    │
│    📁 /var/log/secubox/            │
│    📁 /etc/secubox/                │
│    📁 /run/secubox/                │
│                                    │
│   [VIEW LOGS]  [EXPORT]  [STOP]    │
└────────────────────────────────────┘

• ECM network + Mass Storage (R/W debug partition)
• Use case: Extract logs, inspect config

Mode: TTY (Virtual Keyboard)

┌────────────────────────────────────┐
│         ● TTY MODE                │
│       Virtual HID Keyboard         │
│                                    │
│    ┌──────────────────────────┐    │
│    │ > printenv               │    │ ← Command queue
│    │ > setenv bootcmd run usb │    │
│    │ > boot                   │    │
│    └──────────────────────────┘    │
│                                    │
│    ⌨️  Sending keystroke...        │
│       [████████░░░░] 67%           │
│                                    │
│   [PAUSE]  [CLEAR]  [+CMD]         │
└────────────────────────────────────┘

• HID Keyboard: USB scan codes → target U-Boot
• Serial: Capture output
• Use case: Automated U-Boot commands, rescue boot

Mode: Auth (Eye Remote Security Key)

┌────────────────────────────────────┐
│         ● EYE REMOTE              │
│       FIDO2/U2F Security Key       │
│                                    │
│         ┌─────────────┐            │
│         │ ▄▄▄ ▀▀▀ ▄▄▄│            │
│         │ █▀█ ▄▄▄ █▀█│            │ ← QR Code
│         │ ▀▀▀ █▀█ ▀▀▀│            │
│         │ ▄▄▄ ▀▀▀ ▄▄▄│            │
│         └─────────────┘            │
│                                    │
│    🔐 Touch to authenticate        │
│       Challenge: a3f7...           │
│                                    │
│   [APPROVE]     [DENY]             │
└────────────────────────────────────┘

• FIDO2/U2F HID: Hardware security key
• QR Display: One-time challenge codes
• Use case: SSH auth, WebAuthn, 2FA

---

x64/amd64 Live Boot Support

The Eye Remote dashboard also runs on standard x64 systems for:

• Live USB boot environments
• SecuBox staging and initial setup
• Touchscreen kiosks (any resolution, scales to fit)
• VM testing during development

# Build live USB with Eye Remote
./image/build-live-usb.sh --profile x64-live --eye-remote

# Run in VM for testing
qemu-system-x86_64 -m 2G -cdrom secubox-live.iso \
    -device virtio-vga -display gtk

---

Installation rapide

1. Flasher la carte SD

# Télécharger Raspberry Pi OS Lite (32-bit armhf - REQUIS pour Zero W)
wget https://downloads.raspberrypi.com/raspios_lite_armhf/images/raspios_lite_armhf-2024-11-19/2024-11-19-raspios-bookworm-armhf-lite.img.xz

# Flasher et configurer (avec USB OTG pour accès direct)
sudo ./install_zerow.sh \
    -d /dev/mmcblk0 \
    -i 2024-11-19-raspios-bookworm-armhf-lite.img.xz \
    -s "MonWiFi" \
    -p "MotDePasseWiFi" \
    -k ~/.ssh/id_rsa.pub \
    -r  # Active USB OTG (recommandé)

Important: Utilisez l'image 32-bit armhf, pas arm64. Le Zero W est ARMv6.

2. Premier démarrage

1. Éjecter la carte SD : sudo eject /dev/mmcblk0
2. Insérer dans le RPi Zero W avec l'écran HyperPixel monté
3. Connecter le câble USB sur le port DATA (celui du milieu), pas PWR
4. Attendre ~90 secondes pour le boot initial

3. Connexion SSH (via USB OTG)

# Sur le host, configurer l'interface USB
sudo ip addr add 10.55.0.1/30 dev enxXXXXXXXXXXXX  # Remplacer par le nom réel
sudo ip link set enxXXXXXXXXXXXX up

# Connecter au Zero W (credentials par défaut: pi:raspberry)
ssh pi@10.55.0.2

4. Premier boot (si WiFi configuré)

• Attendre ~10 min (installation des drivers, redémarrage automatique)
• L'écran HyperPixel s'allume après le redémarrage

3. Déployer le dashboard

# Depuis le dépôt SecuBox-Deb
./deploy.sh -h secubox-round.local \
    --api-url http://192.168.1.1:8000 \
    --api-pass "VotreMotDePasse"

---

Scripts

secubox-otg-gadget.sh

USB OTG composite gadget controller for all modes.

# Start normal mode (ECM + Serial)
sudo ./secubox-otg-gadget.sh start

# Switch to TTY mode (HID keyboard)
sudo ./secubox-otg-gadget.sh tty

# Switch to Auth mode (Eye Remote)
sudo ./secubox-otg-gadget.sh auth

# Flash mode (bootable recovery)
sudo ./secubox-otg-gadget.sh flash

# Debug mode (network + storage)
sudo ./secubox-otg-gadget.sh debug

# Check status
./secubox-otg-gadget.sh status

secubox-hid-keyboard.sh

Virtual keyboard for TTY mode automation.

# Send a command (type + Enter)
./secubox-hid-keyboard.sh cmd 'printenv'

# Type without Enter
./secubox-hid-keyboard.sh type 'setenv bootcmd run bootusb'

# Send special keys
./secubox-hid-keyboard.sh enter
./secubox-hid-keyboard.sh ctrl-c

# Process command queue file
./secubox-hid-keyboard.sh queue /run/secubox-cmd-queue

# Interactive mode (stdin)
echo -e "printenv\nboot" | ./secubox-hid-keyboard.sh interactive

install_zerow.sh

Prépare et flashe une microSD pour RPi Zero W avec HyperPixel 2.1 Round.

Usage: install_zerow.sh [OPTIONS]

Options requises:
  -d, --device DEVICE     Périphérique SD (ex: /dev/sdb, /dev/mmcblk1)
  -i, --image IMAGE       Image Raspberry Pi OS (.img ou .img.xz)
  -s, --ssid SSID         Nom du réseau WiFi
  -p, --psk PSK           Mot de passe WiFi

Options facultatives:
  -h, --hostname NAME     Hostname (défaut: secubox-round)
  -u, --user USER         Utilisateur (défaut: secubox)
  -k, --pubkey FILE       Clé SSH publique à installer
  --no-wifi               Ne pas configurer le WiFi
  -r, --usb-otg           Activer USB OTG (mode gadget Ethernet)
  --help                  Afficher cette aide

Sécurité intégrée :

• Refuse /dev/sda, /dev/nvme0n1, /dev/mmcblk0 (disques système)
• Demande confirmation avant l'effacement

fix-pizero-otg.sh

Corrige la configuration OTG (réseau + série) d'une SD card Pi Zero.

# Insérer la SD card du Pi Zero dans le PC, puis :
sudo ./fix-pizero-otg.sh /dev/sdX

# Le script configure :
# - dtoverlay=dwc2 dans config.txt
# - /etc/modules : dwc2, libcomposite
# - /etc/network/interfaces.d/usb0 : IP 10.55.0.2/30
# - getty@ttyGS0.service : console série USB
# - secubox-otg-gadget.service : gadget composite au boot

setup_touch_pimoroni.sh

Configure le tactile HyperPixel 2r pour utiliser la bibliothèque Python Pimoroni.

# Sur le Pi Zero :
sudo ./setup_touch_pimoroni.sh

# Le script :
# - Modifie config.txt : dtoverlay=hyperpixel2r:disable-touch
# - Installe : hyperpixel2r, smbus2, evdev (Python)
# - Ajoute l'utilisateur au groupe i2c
# - Teste la connexion I2C bus 11, adresse 0x15

test_touch_i2c.py

Script de diagnostic pour tester la connexion tactile HyperPixel 2r.

python3 test_touch_i2c.py

# Tests effectués :
# 1. Accès I2C direct (smbus2, bus 11, adresse 0x15)
# 2. Scan des bus I2C disponibles
# 3. Bibliothèque Pimoroni hyperpixel2r
# 4. Fallback evdev (pilote kernel)
# 5. Vérification config.txt

deploy.sh

Déploie/met à jour le dashboard sur un RPi Zero W configuré.

Usage: deploy.sh [OPTIONS]

Options requises:
  -h, --host HOST         Adresse IP ou hostname du RPi Zero W

Options facultatives:
  -u, --user USER         Utilisateur SSH (défaut: secubox)
  -p, --port PORT         Port SSH (défaut: 22)
  --api-url URL           URL de l'API SecuBox
  --api-pass PASS         Mot de passe API
  --sim                   Activer le mode simulation
  --no-sim                Désactiver le mode simulation

---

Architecture

Round's frontend code reuses remote-ui/common/ (see ../common/README.md) for the TransportManager, JWT handling, simulation drift, module table, palette, base layout, and the 24 SecuBox module PNG icons. The shared secubox-otg-gadget.sh and secubox-otg-host-up.sh shell scripts also live there. round/ keeps its Pi-Zero-W-specific code: HyperPixel 2.1 Round display drivers, framebuffer fallback (fb_dashboard.py), and the round-shaped 480×480 layout. A sibling variant remote-ui/square/ (Pi 4B/400 + 7" 800×480) is planned for Phase 2 (issue #127) and will consume the same common/ core. Note: round/'s rendering currently uses raw colour literals in base.css; the palette.css CSS variables are forward-looking for square/'s right column.

Eye Remote as USB Gadget

┌─────────────────────────────────────────────────────────────────────┐
│                     SecuBox Target (Armada/x86)                      │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │ USB Host Port                                                │    │
│  │   ├── ECM/RNDIS Network ────────► 10.55.0.1 (usb0)          │    │
│  │   ├── CDC-ACM Serial ───────────► /dev/ttyACM0              │    │
│  │   ├── Mass Storage ─────────────► /dev/sda (debug/flash)    │    │
│  │   └── HID Keyboard ─────────────► Virtual input device      │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                              ▲ USB OTG                               │
└──────────────────────────────┼──────────────────────────────────────┘
                               │
                    ┌──────────┴──────────┐
                    │   USB Data Cable    │
                    │   (NOT power-only)  │
                    └──────────┬──────────┘
                               │
┌──────────────────────────────┼──────────────────────────────────────┐
│                              ▼                                       │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │ configfs USB Gadget (libcomposite)                          │    │
│  │   ├── ECM function ──────► usb0 (10.55.0.2)                 │    │
│  │   ├── ACM function ──────► /dev/ttyGS0 (console)            │    │
│  │   ├── Mass Storage ──────► /var/lib/secubox-*.img           │    │
│  │   └── HID function ──────► /dev/hidg0 (keyboard)            │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                      │
│                    RPi Zero W + HyperPixel 2.1 Round                 │
│                         "SecuBox Eye Remote"                         │
└─────────────────────────────────────────────────────────────────────┘

Communication Flow

SecuBox (Armada/x86)              RPi Zero W + HyperPixel
┌─────────────────────┐          ┌─────────────────────┐
│  secubox-system     │          │  nginx:8080         │
│  FastAPI:8000       │◄────────►│  ├── /api/* → proxy │
│  └── /api/v1/system │ USB OTG  │  └── /* → dashboard │
│      /metrics       │ 10.55.0  │                     │
│      /metrics/alerts│◄─WiFi───►│  Chromium kiosk     │
│      /metrics/modules│ backup  │  └── localhost:8080 │
│                     │          │                     │
│  U-Boot console     │◄────────►│  HID Keyboard       │
│  /dev/ttyACM0       │ Serial   │  secubox-hid-kbd.sh │
└─────────────────────┘          └─────────────────────┘

Endpoints API utilisés

Endpoint	Description
GET /api/v1/system/metrics	Métriques système complètes
GET /api/v1/system/metrics/health	Health check rapide
GET /api/v1/system/metrics/modules	État des 6 modules
GET /api/v1/system/metrics/alerts	Alertes actives
POST /api/v1/auth/login	Authentification JWT

Réponse /api/v1/system/metrics

{
  "timestamp": "2026-05-07T10:15:00Z",
  "hostname": "secubox-mochabin",
  "cpu_percent": 23.5,
  "mem_percent": 41.2,
  "disk_percent": 28.7,
  "cpu_temp": 44.2,
  "load_1m": 0.18,
  "load_5m": 0.12,
  "load_15m": 0.08,
  "uptime_seconds": 86400,
  "connections": 42,
  "peak_connections": 128,
  "connections_percent": 32.8
}

Champ	Description
connections	Connexions TCP établies actuelles
peak_connections	Maximum de connexions observé (persisté)
connections_percent	connections / peak_connections * 100 — pour MIND metric

Modules affichés

Code	Service	Couleur	Description
AUTH	secubox-auth	#C04E24	Authentification / SSO
WALL	secubox-crowdsec	#9A6010	WAF / IDS
BOOT	secubox-hub	#803018	Dashboard principal
MIND	secubox-ai-insights	#3D35A0	IA / Insights
ROOT	secubox-system	#0A5840	Système
MESH	secubox-p2p	#104A88	Réseau mesh

---

Configuration

secubox.conf — Section [remote_ui]

[remote_ui]
enabled       = true
api_base      = "/api/v1/system"
refresh_ms    = 5000
simulate      = false

[remote_ui.thresholds.cpu]
warn = 70
crit = 85

[remote_ui.thresholds.mem]
warn = 75
crit = 90

[remote_ui.thresholds.disk]
warn = 80
crit = 95

[remote_ui.thresholds.temp]
warn = 65
crit = 75

[remote_ui.thresholds.wifi]
warn = -70
crit = -80

Mode simulation

Pour tester le dashboard sans connexion à l'API SecuBox :

./deploy.sh -h secubox-round.local --sim

---

systemd Services

Framebuffer Dashboard (v1.11.0+)

For Pi Zero W (ARMv6, no NEON), the dashboard runs via framebuffer:

# /etc/systemd/system/secubox-fb-dashboard.service
[Unit]
Description=SecuBox Eye Remote Framebuffer Dashboard
After=hyperpixel2r-init.service
Wants=hyperpixel2r-init.service

[Service]
Type=simple
User=root
ExecStart=/usr/bin/python3 /usr/local/bin/fb_dashboard.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Dependencies:

• pigpiod.service — GPIO daemon for LCD init
• hyperpixel2r-init.service — ST7701S LCD controller init

Chromium Kiosk (ARM64/x64 only)

For systems with NEON support (Pi Zero 2 W, x64):

# /etc/systemd/system/secubox-remote-ui.service
[Service]
Type=simple
User=secubox
Environment=DISPLAY=:0
ExecStart=/usr/bin/chromium-browser --kiosk ...
Restart=always
RestartSec=10
MemoryMax=256M
CPUQuota=80%

---

Dépannage

L'écran reste noir

1. Vérifier que le KMS overlay est actif (vc4-kms-v3d + vc4-kms-dpi-hyperpixel2r) :

   ssh pi@10.55.0.2
   grep -E "vc4|hyperpixel|display_auto" /boot/firmware/config.txt
   # Doit afficher:
   # dtoverlay=vc4-kms-v3d
   # dtoverlay=vc4-kms-dpi-hyperpixel2r
   # display_auto_detect=0
   

2. Vérifier le DRM/KMS :

   ls -la /dev/dri/
   # Doit afficher: card0, renderD128
   dmesg | grep -iE "drm|vc4|dpi"
   # Doit montrer: "bound 20208000.dpi" et "vc4drmfb frame buffer"
   

3. Vérifier le framebuffer :

   ls -la /dev/fb*
   # Doit afficher: /dev/fb0
   fbset -fb /dev/fb0
   # Doit montrer: geometry 480 480
   

4. Si non-KMS (fallback), vérifier l'init :

   systemctl status hyperpixel2r-init
   # Doit être "inactive (dead)" avec status=0/SUCCESS
   

SSH via USB OTG ne fonctionne pas

1. Vérifier l'interface USB côté host :

   ip link | grep enx
   # Doit montrer une interface enxXXXXXX UP
   

2. Configurer l'IP sur le host :

   sudo ip addr add 10.55.0.1/30 dev enxXXXXXXXX
   sudo ip link set enxXXXXXXXX up
   

3. Si l'interface n'apparaît pas, vérifier le câble (doit être DATA, pas PWR)

Chromium ne se lance pas

# Vérifier le service
systemctl status secubox-remote-ui

# Logs détaillés
journalctl -u secubox-remote-ui -f

Dashboard affiche "Erreur connexion API"

1. Vérifier la connectivité réseau :

   ping 192.168.1.1  # IP de la SecuBox
   

2. Vérifier l'URL API dans nginx :

   cat /etc/nginx/sites-enabled/secubox-round | grep proxy_pass
   

3. Redéployer avec la bonne URL :

   ./deploy.sh -h secubox-round.local --api-url http://192.168.1.1:8000
   

Rafraîchir le dashboard manuellement

ssh secubox@secubox-round.local
systemctl restart secubox-remote-ui

---

FAQ / Troubleshooting

Why doesn't Chromium work on Pi Zero W?

Error: The hardware on this system lacks support for NEON SIMD extensions

Cause: Pi Zero W uses an ARMv6 CPU which lacks NEON SIMD instructions. Chromium on Debian Bookworm requires NEON.

Solution: Use the framebuffer dashboard (fb_dashboard.py) which renders directly to /dev/fb0 using Python PIL. This is enabled by default in v1.11.0+.

Display stays black (no content)

1. Check overlay name — Must be hyperpixel2r (not hyperpixel4):

   grep dtoverlay /boot/firmware/config.txt
   # Should show: dtoverlay=hyperpixel2r
   

2. Check pigpiod is running — Required for LCD initialization:

   systemctl status pigpiod
   # Should be: active (running)
   

3. Check hyperpixel2r-init — LCD controller initialization:

   systemctl status hyperpixel2r-init
   # Should be: inactive (dead) with Result: success
   

4. Check framebuffer dashboard — Rendering service:

   systemctl status secubox-fb-dashboard
   # Should be: active (running)
   

Service dependency order

The services must start in this order:

pigpiod → hyperpixel2r-init → secubox-fb-dashboard

If the display doesn't work after reboot, check that all three services succeeded:

systemctl status pigpiod hyperpixel2r-init secubox-fb-dashboard --no-pager

"GPIO not allocated" error

Cause: Using RPi.GPIO (which depends on lgpio) when DPI overlay is active. The kernel claims GPIO pins for DPI output.

Solution: Use pigpio instead of RPi.GPIO. The init script in v1.10.0+ uses pigpio which works correctly via the pigpiod daemon.

Display shows colored stripes but no dashboard

Cause: Framebuffer is initialized but no application is rendering to it.

Solution: Ensure the dashboard service is enabled:

sudo systemctl enable --now secubox-fb-dashboard

How to test framebuffer manually

# Draw random noise to confirm framebuffer works
cat /dev/urandom > /dev/fb0

# Run dashboard manually
python3 /usr/local/bin/fb_dashboard.py

Which config.txt settings are required?

Minimum required for HyperPixel 2.1 Round on Pi Zero W (v2.0.0):

# Display overlay
dtoverlay=hyperpixel2r

# Explicit DPI settings (REQUIRED for Pi Zero W - no KMS support)
enable_dpi_lcd=1
display_default_lcd=1
dpi_group=2
dpi_mode=87
dpi_output_format=0x7f216
dpi_timings=480 0 10 16 59 480 0 15 60 15 0 0 0 60 0 19200000 6
framebuffer_width=480
framebuffer_height=480

# Other settings
gpu_mem=128
display_auto_detect=0
dtoverlay=dwc2

⚠️ Do NOT add these - they conflict with DPI:

# WRONG - conflicts with DPI pins!
# dtparam=i2c_arm=on
# dtparam=spi=on

The hyperpixel2r overlay handles its own I2C (i2c10) for touch and uses pigpio software SPI for LCD init.

Pi Zero W: Display blank even with correct overlay

Cause: Pi Zero W (BCM2835) doesn't support KMS. The hyperpixel2r overlay alone may not configure DPI output properly without KMS.

Solution: Add explicit DPI timing parameters (see above). These tell the VideoCore GPU exactly how to drive the 480x480 display, bypassing KMS.

DPI fails with "pin gpio2 already requested by i2c"

Cause: dtparam=i2c_arm=on enables I2C on GPIO2/3, but the DPI display driver needs those pins.

Kernel error:

pinctrl-bcm2835: pin gpio2 already requested by i2c; cannot claim for dpi
vc4_dpi: Error applying setting, reverse things back

Solution: Remove or comment out dtparam=i2c_arm=on and dtparam=spi=on from config.txt. The HyperPixel overlay uses:

• i2c10 (software I2C on different pins) for touch controller
• pigpio software SPI (bit-banging) for LCD initialization

This is handled automatically by build-eye-remote-image.sh v2.0.0+.

Pi Zero responds to ARP but not ping/TCP

Symptoms:

• arping 10.55.0.2 returns replies (Layer 2 OK)
• ping 10.55.0.2 times out (Layer 3 blocked)
• All TCP ports (22, 80, 5000, 8000) time out
• Dashboard shows "Disconnected"

Diagnosis:

# From MOCHAbin - check Layer 2
arping -c 3 -I eye-remote 10.55.0.2
# If replies → network link OK, problem is on Pi Zero

# Check interface state
ip addr show eye-remote
cat /sys/class/net/eye-remote/carrier  # Should be 1

Possible Causes:

1. Firewall on Pi Zero — iptables/nftables blocking INPUT
2. USB network service crashed — NetworkManager or ifupdown issue
3. IP conflict — Pi Zero lost its 10.55.0.2 address

Solutions:

1. Via serial console (from MOCHAbin):

   picocom -b 115200 /dev/ttyACM0
   # Login: pi / raspberry
   sudo iptables -F INPUT
   sudo iptables -P INPUT ACCEPT
   ip addr show usb0
   # Ctrl+A then Ctrl+X to exit
   

2. Make firewall fix permanent (on Pi Zero):

   # Add to /etc/rc.local before "exit 0"
   iptables -A INPUT -i usb0 -s 10.55.0.1 -j ACCEPT
   

3. Restart USB network (on Pi Zero):

   sudo systemctl restart networking
   # or
   sudo ifdown usb0 && sudo ifup usb0
   

4. Check Pi Zero services:

   systemctl status secubox-eye-agent
   systemctl status secubox-fb-dashboard
   journalctl -u secubox-eye-agent -n 20
   

---

Roadmap v2.0.0 (Issue #31)

Planned Features

Feature	Description
Real Metrics	Connect to SecuBox API for live CPU, RAM, disk, temp data
Multi-SecuBox	One Eye Remote managing multiple SecuBox devices
Auto-Auth	Device token authentication, no manual login
Touchless Pairing	QR code pairing with SSH auto-provisioning
Control Mode	Restart services, switch OTG mode, emergency lockdown
WebUI	Manage Eye Remote from SecuBox web dashboard
Serial Console	xterm.js passthrough to /dev/ttyACM0
Screenshot	Capture Eye Remote display remotely
OTA Updates	Push firmware updates from SecuBox

Components

┌─────────────────────────────────────────────────────────────┐
│  Eye Remote (Pi Zero W)                                     │
│  ├── secubox-eye-agent    ← Multi-SecuBox connection mgr    │
│  └── fb_dashboard.py      ← Display renderer (existing)     │
├─────────────────────────────────────────────────────────────┤
│  SecuBox (ESPRESSObin)                                      │
│  └── secubox-eye-remote   ← Management module + WebUI       │
├─────────────────────────────────────────────────────────────┤
│  Dev Machine                                                │
│  └── secubox-eye-gateway  ← Emulator + fleet gateway        │
└─────────────────────────────────────────────────────────────┘

Design Spec

Full specification: docs/superpowers/specs/2026-04-21-eye-remote-integration-design.md

---

Ressources

HyperPixel 2.1 Round — Matériel & Drivers

Ressource	Lien	Description
Shop Pimoroni	HyperPixel 2.1 Round	Achat écran tactile 480×480
Driver Display	github.com/pimoroni/hyperpixel2r	Overlay DT, scripts init LCD
Touch Python	github.com/pimoroni/hyperpixel2r-python	Lib Python pour tactile I2C direct
PyPI Package	pypi.org/project/hyperpixel2r	pip install hyperpixel2r

Documentation technique

Ressource	Lien
Pimoroni Getting Started	learn.pimoroni.com/hyperpixel2r
Raspberry Pi DPI	raspberrypi.com/documentation/computers/raspberry-pi.html#dpi
USB Gadget ConfigFS	kernel.org/doc/Documentation/usb/gadget_configfs.txt

SecuBox

Ressource	Lien
Documentation	docs.secubox.in
Dépôt GitHub	github.com/CyberMind-FR/secubox-deb
APT Repository	apt.secubox.in

---

Licence

Proprietary — CyberMind / ANSSI CSPN candidate

Author: Gérald Kerma gandalf@gk2.net