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

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

  1. Insert Β΅SD card into Pi Zero
  2. Connect Pi Zero USB port to target's USB port
  3. 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

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

  1. Check Β΅SD card is properly seated
  2. Verify config.txt contains dtoverlay=dwc2
  3. Check power LED (solid red = powered)
  4. Check activity LED (flashing green = reading SD)

Target Not Seeing USB Storage

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

Boot Menu Not Appearing

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

See Also

Support

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