Eye Remote — Pi Zero USB Gadget

SecuBox Eye Remote transforms a Raspberry Pi Zero W into a portable USB boot media controller for ARM64 SecuBox devices (ESPRESSObin, MOCHAbin).

Overview

The Eye Remote presents a multiboot storage image to the host device via USB gadget mass_storage, enabling network-less deployment and recovery.

┌─────────────────────────────────────────────────────────────────┐
│                    Eye Remote Architecture                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌──────────────┐        USB OTG         ┌─────────────────┐   │
│   │  Pi Zero W   │ ◄─────────────────────►│  ESPRESSObin    │   │
│   │              │   mass_storage +       │  or MOCHAbin    │   │
│   │  Eye Remote  │   ECM network          │                 │   │
│   └──────────────┘                        └─────────────────┘   │
│         │                                        │              │
│         │ µSD Card                               │              │
│         ▼                                        ▼              │
│   ┌──────────────┐                        ┌─────────────────┐   │
│   │ storage.img  │ ────presented as───►   │ /dev/sda        │   │
│   │ 16GB image   │    USB mass storage    │ Bootable disk   │   │
│   └──────────────┘                        └─────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Features

Feature	Description
USB Mass Storage	Pi Zero presents `storage.img` as USB disk to host
USB ECM Network	Ethernet over USB for remote management
Serial Console	USB ACM serial for debug access
Dual Boot Menu	Interactive menu: Live RAM Boot or Flash to eMMC
Web Dashboard	xterm.js serial console + status UI

Hardware Requirements

Component	Specification
Pi Zero W	Any revision (W for WiFi management)
µSD Card	32GB+ Class 10 / A1 recommended
USB Cable	USB-A to Micro-USB OTG
Target	ESPRESSObin, MOCHAbin, or compatible ARM64

Quick Start

1. Flash the Eye Remote Image

# Download the Eye Remote image
wget https://github.com/CyberMind-FR/secubox-deb/releases/download/eye-remote-v2.2.4/secubox-eye-remote.img.xz

# Flash to µSD card
xzcat secubox-eye-remote.img.xz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync
sync

2. Connect Pi Zero to Target

Insert µSD card into Pi Zero
Connect Pi Zero USB port to target's USB port
Power on target device

3. Boot Menu

The target device will see a USB mass storage device and boot from it. The U-Boot boot.scr presents:

============================================
          BOOT MENU
============================================

  [1] Live RAM Boot (default)
  [2] Flash SecuBox to eMMC

Auto-boot in 5 seconds...

Partition Layout

Partition	Label	Size	Purpose
1	SECUBOX-EFI	512MB	Boot files (kernel, DTB, GRUB, U-Boot)
2	secubox-arm64	~4GB	ARM64 rootfs (RAM-loaded)
3	secubox-amd64	~4GB	AMD64 rootfs (for x86 targets)
4	secubox-data	~7GB	Shared persistent data

USB Gadget Configuration

The Pi Zero configures multiple USB gadget functions:

# /boot/config.txt
dtoverlay=dwc2

# cmdline.txt (after rootwait)
modules-load=dwc2,g_multi

Gadget Functions

Function	Device	Purpose
`mass_storage`	Host sees USB disk	Boot media
`ecm`	usb0 network	Remote access
`acm`	ttyGS0 serial	Debug console

Building the Image

From Repository

cd secubox-deb

# Build the Eye Remote image
sudo bash image/eye-remote/build-eye-remote.sh \
    --output output/secubox-eye-remote.img \
    --storage-size 16G

# Or with multiboot integration
sudo bash image/multiboot/build-multiboot.sh \
    --output output/secubox-multiboot.img \
    --size 16G

GitHub Actions

The image is automatically built via CI:

Workflow: .github/workflows/build-eye-remote.yml
Trigger: Push to eye-remote-v* tags

Remote Management

WiFi Configuration

Edit /boot/wpa_supplicant.conf on the µSD card before first boot:

country=FR
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
    ssid="YourWiFi"
    psk="YourPassword"
}

SSH Access

# Via WiFi (if configured)
ssh secubox@<pi-zero-ip>

# Via USB ECM network
ssh [email protected]

Web Dashboard

Access at http://10.55.0.1:8080:

Serial console via xterm.js
Boot media status
Storage swap controls

HyperPixel Round Display (v2.1.1+)

The Eye Remote supports the Pimoroni HyperPixel 2.1 Round (480×480) for a dedicated dashboard:

┌────────────────────────────────┐
│     🔴 🟠 🟡 🟢 🔵 🟣          │  ← Rainbow icon ring
│         ╭─────╮                │
│      ╭──│TIME │──╮             │  ← Center clock
│     ╭───│DATE │───╮            │
│    ╭────│HOST │────╮           │  ← Concentric metric rings
│   ╭─────│ UP  │─────╮          │    (red→purple outer→inner)
│   ╰─────╰─────╯─────╯          │
│         RADAR ⟳                │  ← Rotating radar sweep
└────────────────────────────────┘

Features:

6 module icons in rainbow order (BOOT, AUTH, WALL, ROOT, MESH, MIND)
Radar sweep syncs with targeted module glow
Metric arcs aligned with corresponding icon colors
Concentric rings: red (outer) → purple (inner)

API Reference

Method	Endpoint	Description
GET	`/api/v1/eye-remote/status`	System status
GET	`/api/v1/eye-remote/boot-media/state`	Boot media state
POST	`/api/v1/eye-remote/boot-media/upload`	Upload to shadow
POST	`/api/v1/eye-remote/boot-media/swap`	Swap active/shadow
POST	`/api/v1/eye-remote/boot-media/rollback`	Rollback swap

Troubleshooting

Pi Zero Not Booting

Check µSD card is properly seated
Verify config.txt contains dtoverlay=dwc2
Check power LED (solid red = powered)
Check activity LED (flashing green = reading SD)

Target Not Seeing USB Storage

Ensure USB cable supports data (not charge-only)
Check Pi Zero is fully booted (activity LED stops flashing)
On target, run lsusb to check USB detection
Check dmesg for mass_storage errors

Boot Menu Not Appearing

Target U-Boot must support usb start
Check boot order in U-Boot: printenv boot_targets
Manually try: usb start; fatload usb 0:1 $kernel_addr_r Image

Support

Issues: https://github.com/CyberMind-FR/secubox-deb/issues
Wiki: https://github.com/CyberMind-FR/secubox-deb/wiki

Eye Remote - CyberMind-FR/secubox-deb GitHub Wiki

Eye Remote — Pi Zero USB Gadget

Overview

Features

Hardware Requirements

Quick Start

1. Flash the Eye Remote Image

2. Connect Pi Zero to Target

3. Boot Menu

Partition Layout

USB Gadget Configuration

Gadget Functions

Building the Image

From Repository

GitHub Actions

Remote Management

WiFi Configuration

SSH Access

Web Dashboard

HyperPixel Round Display (v2.1.1+)

API Reference

Troubleshooting

Pi Zero Not Booting

Target Not Seeing USB Storage

Boot Menu Not Appearing

See Also

Support

⚠️ GitHub.com Fallback ⚠️

Eye Remote - CyberMind-FR/secubox-deb GitHub Wiki

Eye Remote — Pi Zero USB Gadget

Overview

Features

Hardware Requirements

Quick Start

1. Flash the Eye Remote Image

2. Connect Pi Zero to Target

3. Boot Menu

Partition Layout

USB Gadget Configuration

Gadget Functions

Building the Image

From Repository

GitHub Actions

Remote Management

WiFi Configuration

SSH Access

Web Dashboard

HyperPixel Round Display (v2.1.1+)

API Reference

Troubleshooting

Pi Zero Not Booting

Target Not Seeing USB Storage

Boot Menu Not Appearing

See Also

Support

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️