secubox-deb/docs/wiki/Eye-Remote-Gateway.md

Eye Remote Gateway & Emulator

Overview

The secubox-eye-gateway tool provides development and testing capabilities for the Eye Remote dashboard without requiring physical SecuBox hardware.

Installation

# From source
cd tools/secubox-eye-gateway
pip install -e .

# Verify installation
secubox-eye-gateway --help

Usage Modes

Emulator Mode (Default)

Simulates a SecuBox with configurable metrics profiles:

# Run with default profile (normal)
secubox-eye-gateway

# Run with specific profile
secubox-eye-gateway --profile stressed --port 8765

# Available profiles:
#   idle     - Low activity system
#   normal   - Typical workload
#   busy     - Heavy utilization
#   stressed - Near-critical levels

Gateway Mode (Future)

Proxy to real SecuBox hardware:

# Proxy to real SecuBox
secubox-eye-gateway --mode gateway --target 192.168.1.100:8000

Fleet Mode (Future)

Aggregate multiple SecuBox devices:

# Fleet aggregation
secubox-eye-gateway --mode fleet \
    --device secubox-1:192.168.1.101:8000 \
    --device secubox-2:192.168.1.102:8000

API Endpoints

Health Check

GET /api/v1/health

Response:

{
    "status": "healthy",
    "version": "1.0.0",
    "mode": "emulator",
    "profile": "stressed"
}

System Metrics

GET /api/v1/system/metrics

Response:

{
    "cpu_percent": 85.3,
    "memory_percent": 72.1,
    "disk_percent": 45.8,
    "cpu_temp": 68.5,
    "load_avg_1": 2.34,
    "uptime_seconds": 345600,
    "hostname": "secubox-emulated",
    "timestamp": "2026-04-21T22:00:00Z"
}

Device Discovery

GET /api/v1/eye-remote/discover

Response:

{
    "device_id": "9a0f3d1f",
    "device_name": "Test SecuBox",
    "device_type": "emulator",
    "profile": "stressed",
    "api_version": "1.0.0",
    "capabilities": ["metrics", "pairing", "commands"]
}

Metrics Profiles

idle

Low-activity system at rest.

Metric	Range
CPU	2-8%
Memory	20-30%
Disk	15-25%
Temperature	38-45°C
Load	0.05-0.15

normal

Typical production workload.

Metric	Range
CPU	15-35%
Memory	40-55%
Disk	25-40%
Temperature	48-55°C
Load	0.3-0.8

busy

Heavy processing load.

Metric	Range
CPU	55-75%
Memory	65-80%
Disk	35-55%
Temperature	58-68°C
Load	1.5-2.5

stressed

Near-critical system state.

Metric	Range
CPU	80-95%
Memory	85-95%
Disk	60-85%
Temperature	70-80°C
Load	3.0-5.0

Dashboard Integration

Configure Dashboard to Use Emulator

Edit the Eye Remote dashboard configuration:

// In dashboard config
const CFG = {
    API_OTG_BASE: 'http://localhost:8765',  // Gateway emulator
    API_WIFI_BASE: 'http://localhost:8765',
    SIMULATE: false,  // Use real API
    // ...
};

Test Sequence

1. Start the gateway emulator:

   secubox-eye-gateway --profile busy --port 8765
   

2. Open dashboard in browser:

   firefox http://localhost:8080
   

3. Dashboard fetches metrics from emulator every 2 seconds

4. Switch profiles to test different states:

   # Stop and restart with different profile
   secubox-eye-gateway --profile stressed --port 8765
   

Development

Project Structure

tools/secubox-eye-gateway/
├── gateway/
│   ├── __init__.py
│   ├── cli.py          # Click CLI interface
│   ├── emulator.py     # Metrics emulation logic
│   └── server.py       # FastAPI server
├── pyproject.toml      # Package configuration
└── README.md

Adding Custom Profiles

Edit gateway/emulator.py:

PROFILES = {
    # ... existing profiles ...
    "custom": {
        "cpu_base": 50,
        "cpu_variance": 10,
        "mem_base": 60,
        "mem_variance": 5,
        # ...
    }
}

Running Tests

cd tools/secubox-eye-gateway
pytest tests/ -v

Troubleshooting

Port Already in Use

# Find process using port
lsof -i :8765

# Kill it
kill -9 <PID>

# Or use different port
secubox-eye-gateway --port 8766

Connection Refused

Check that the gateway is running and accessible:

curl http://localhost:8765/api/v1/health

CORS Issues

The gateway includes CORS headers for all origins. If issues persist, check browser console for specific errors.

Related Documentation

• Eye Remote Implementation
• Eye Remote Hardware
• SecuBox API Reference

---

CyberMind · SecuBox Eye Remote Gateway · April 2026