# SurfScan: (llm) User Guide

# SurfScan User Guide

This guide covers everything you need to know to use SurfScan effectively, from initial setup to advanced operations.

## Table of Contents


 1. [Quick Start](#quick-start)
 2. [Service Management](#service-management)
 3. [System Health & Diagnostics](#system-health--diagnostics)
 4. [Log Management](#log-management)
 5. [Database Operations](#database-operations)
 6. [Cloud Sync](#cloud-sync)
 7. [License Management](#license-management)
 8. [Modem Band Configuration](#modem-band-configuration)
 9. [WiFi Hotspot Management](#wifi-hotspot-management)
10. [Setup and Configuration](#setup-and-configuration)
11. [Web Interfaces](#web-interfaces)
12. [Troubleshooting](#troubleshooting)
13. [Advanced Usage](#advanced-usage)

## Quick Start

After installing SurfScan, follow these steps to get started:

### 1. Run the Setup Guide

```bash
surfscan-setup
```

This interactive guide will walk you through initial configuration and verify your installation.

### 2. Start Services

```bash
sudo surfscan-ctl start
```

This starts all SurfScan services required for operation.

### 3. Access the Web Interface

Open your browser and navigate to:

* **Scanner App**: `https://[your-rpi-ip]/` (Main scanning interface with custom reports)
* **System Admin**: `https://[your-rpi-ip]/admin/` (Cockpit with SurfScan admin plugin)
* **API Documentation**: `https://[your-rpi-ip]/api/admin/docs`

**Authentication**: Use your system username/password (PAM authentication - any system user works)

**Direct Access** (bypass nginx proxy):

* **Scanner Interface**: `http://[your-rpi-ip]:8000`
* **Admin API**: `http://[your-rpi-ip]:8090/api/admin/docs`

### 4. Perform Your First Scan


1. Open the Scanner App at `https://[your-rpi-ip]/`
2. Login with your system username and password
3. In the **Scanner** tab:
   * GPS coordinates auto-detect when available
   * If no GPS, use "Use My Location" button or enter coordinates manually
   * Select scan duration (1-30 minutes)
   * Add optional session notes
4. Click **START SCAN** and watch the circular progress dial
5. When complete, view the LTE/5G summary or click **View Reports**
6. Generate reports in the Reports tab (GoRout, CBRS, FirstNet, Bonded LTE)

### 5. Generate Custom Reports


1. Complete a scan and collect cellular data
2. Click the Reports tab, then select a report type from the dropdown:
   * **GoRout Report**: Band 2 vs Band 5 LTE optimization for wearable devices
   * **CBRS Report**: Citizens Broadband Radio Service (Band 48 LTE/5G) analysis
   * **FirstNet Report**: FirstNet emergency services network (PLMN 313-100) analysis
   * **Bonded LTE Report**: LTE band recommendations for multi-WAN uplink bonding (2-8 connections)
3. Select a session with scan data
4. For Bonded LTE Report: Select number of bonded connections (2-8 modems) using the dropdown
5. Review network analysis and recommendations
6. Download PDF report for detailed analysis (GoRout only, others coming in Phase 2)

## Service Management

SurfScan includes a comprehensive service management tool called `surfscan-ctl`.

### Basic Commands

```bash
# Start all services
sudo surfscan-ctl start

# Stop all services
sudo surfscan-ctl stop

# Restart all services
sudo surfscan-ctl restart

# Check service status
surfscan-ctl status

# Enable auto-start on boot
sudo surfscan-ctl enable

# Disable auto-start on boot
sudo surfscan-ctl disable
```

### Viewing Logs

```bash
# View recent logs from all services
sudo surfscan-ctl logs

# Follow logs for a specific service
sudo surfscan-ctl logs dashboard
sudo surfscan-ctl logs api
sudo surfscan-ctl logs gps
```

Available services: `api`, `gps`, `dashboard`, `web`, `cellular-api`

### Service Status Output

When you run `surfscan-ctl status`, you'll see:

* ✅ **Green**: Service is running normally
* ⚠️  **Yellow**: Service is stopped or has warnings
* ❌ **Red**: Service has failed

If all services are running, you'll also see the access URLs for the web interfaces.

## System Health & Diagnostics

The `surfscan-doctor` tool provides comprehensive system health checks and diagnostics.

### Running Health Checks

```bash
# Run complete health check
surfscan-doctor
```

### What Gets Checked

* **System Information**: OS, architecture, memory, uptime
* **Installation**: Directories, files, permissions, virtual environment
* **Services**: Status of all SurfScan services
* **Hardware**: Serial ports, ModemManager conflicts, user permissions
* **Network**: Port availability, API responses
* **Database**: File existence, schema, integrity
* **Resources**: Disk space, memory usage

### Understanding Results

* ✅ **Pass**: Component is working correctly
* ⚠️  **Warning**: Component works but has minor issues
* ❌ **Fail**: Component has problems that need attention

The tool provides suggested fixes for any issues found.

## Log Management

The `surfscan-logs` tool provides easy access to service logs and log management.

### Viewing Logs

```bash
# List available log files and services
surfscan-logs list

# Follow live logs from all services
surfscan-logs follow

# Follow logs from a specific service
surfscan-logs follow dashboard

# Show recent logs (default: 50 lines)
surfscan-logs recent

# Show recent logs from specific service
surfscan-logs recent api 100

# Check tool version
surfscan-logs --version
```

### Searching and Filtering

```bash
# Search for patterns in all logs
surfscan-logs search "error"

# Search in specific service logs
surfscan-logs search "connection" api

# Show only error messages
surfscan-logs errors

# Show errors from specific service
surfscan-logs errors dashboard
```

### Log Maintenance

```bash
# Clean old logs (>7 days systemd, >30 days files)
surfscan-logs clean

# Export logs for support
surfscan-logs export

# Export to specific directory
surfscan-logs export /tmp/my-logs

# Show log statistics
surfscan-logs stats

# Check tool version (available on all CLI tools)
surfscan-ctl --version
surfscan-doctor --version
surfscan-setup --version
surfscan-db --version
surfscan-logs --version
surfscan-band-config --version
```

## Database Operations

The `surfscan-db` tool handles all database operations including backup, restore, and maintenance.

⚠️ **Note**: Most database operations require sudo or running as the surfscan user.

### Database Information

```bash
# Show database information and statistics
sudo surfscan-db info
```

This displays:

* Database file location and size
* Table information and record counts
* Recent scan sessions
* Database integrity status

### Backup Operations

```bash
# Create automatic backup
sudo surfscan-db backup

# Create named backup
sudo surfscan-db backup weekly-backup

# List available backups
sudo surfscan-db list

# Restore from backup
sudo surfscan-db restore weekly-backup
```

**Important**:

* Services are automatically stopped during backup/restore operations
* A backup of the current database is created before any restore operation
* All operations include integrity verification

### Data Management

```bash
# Delete data older than 30 days
sudo surfscan-db clean 30

# Export data in various formats
sudo surfscan-db export csv /tmp/scan-data
sudo surfscan-db export sql /tmp/database-dump
sudo surfscan-db export json /tmp/scan-data

# Optimize database performance
sudo surfscan-db optimize
```

### Data Export Formats

* **CSV**: Spreadsheet-compatible format with all scan data
* **SQL**: Complete database dump for backup/migration
* **JSON**: Structured data format for programmatic access

## Cloud Sync

SurfScan v1.4.0-alpha introduces cloud synchronization, allowing scan data to be automatically synced to Supabase for centralized storage, multi-device aggregation, and remote access.

### Overview

**Key Features**:

* **Automatic Background Sync**: Data syncs automatically at configurable intervals (default: 15 minutes)
* **Incremental Sync**: Only new data is synced, minimizing bandwidth usage
* **Offline Support**: Data accumulates locally when offline and syncs when connectivity returns
* **Multi-Device**: Multiple SurfScan devices can sync to the same cloud project
* **Secure**: Uses Supabase service keys with encrypted credential storage

### Cloud Sync Status

Check sync status via the Cockpit admin interface:


1. Navigate to `https://[your-rpi-ip]/admin/`
2. Login with your system credentials
3. Click **SurfScan** in the left menu
4. Go to the **Cloud** tab to view:
   * Connection status (Connected/Disconnected/Offline)
   * Last sync timestamp
   * Records synced vs pending
   * Next scheduled sync time

### Configuring Cloud Sync

#### Method 1: CLI Setup (Recommended)

```bash
surfscan-setup

# Navigate to: Setup services → Configure Cloud Sync
# Options available:
# 1) Configure Supabase credentials
# 2) Test cloud connection
# 3) View sync status
# 4) Restart sync service
# 5) Back to Services Menu
```

#### Method 2: Manual Configuration

Create credentials file manually:

```bash
sudo nano /etc/surfscan/cloud_credentials.conf
```

Add your Supabase credentials:

```ini
[supabase]
url = https://your-project.supabase.co
key = your-service-role-key
```

Set proper permissions:

```bash
sudo chown surfscan:surfscan /etc/surfscan/cloud_credentials.conf
sudo chmod 600 /etc/surfscan/cloud_credentials.conf
```

Restart the sync service:

```bash
sudo systemctl restart surfscan-sync
```

### Managing Cloud Sync

**View Sync History**:

* Cockpit → SurfScan → Cloud tab → View sync history
* Shows recent sync operations with success/failure status

**Trigger Manual Sync**:

* Cockpit → SurfScan → Cloud tab → Click "Sync Now"
* Immediately syncs pending data to cloud

**Check Sync Service**:

```bash
# View sync service status
surfscan-ctl status

# View sync service logs
surfscan-logs follow sync

# Restart sync service
sudo systemctl restart surfscan-sync
```

### Sync Data Details

**What Gets Synced**:

* **Scan Sessions**: Session metadata, timestamps, GPS coordinates
* **Cellular Scans**: All network measurements with signal data
* **GPS Data**: Location points recorded during scans

**Data Retention**:

* Local data remains on device regardless of sync status
* Cloud data persists in Supabase according to your project settings
* Sync status tracked per-record to prevent duplicates

### Troubleshooting Cloud Sync

#### Connection Issues

```bash
# Check internet connectivity
ping -c 3 google.com

# Test Supabase connection via setup tool
surfscan-setup
# → Setup services → Configure Cloud Sync → Test cloud connection

# Check credentials file
sudo cat /etc/surfscan/cloud_credentials.conf
```

#### Sync Not Running

```bash
# Check sync service status
systemctl status surfscan-sync

# View sync service logs
sudo journalctl -u surfscan-sync -f

# Restart sync service
sudo systemctl restart surfscan-sync
```

#### Data Not Appearing in Cloud

* Verify credentials are correct (test connection via setup tool)
* Check for pending data in Admin Dashboard
* Review sync history for error messages
* Ensure Supabase project has correct schema tables

### Obtaining Supabase Credentials

Contact your administrator or Waveriders support to obtain:


1. **Supabase Project URL**: `https://[project-id].supabase.co`
2. **Service Role Key**: Secret key for server-side access

**Important**: Keep your service role key secure. Never share it or commit it to version control.

## License Management

SurfScan includes a fully functional license management system with trial mode and hardware-bound licensing. This system has been tested and validated in production.

### License States

**Trial Mode** (48 hours):

* Automatically activated on first installation
* Full functionality available
* Countdown display shows remaining time
* No restrictions during trial period

**Licensed Mode**:

* Full functionality with extended usage period
* Hardware-bound to your specific device
* Shows license expiration date
* Renewable before expiration

### Getting Your Device ID

When you need to request a license, you'll need your device's unique ID:

```bash
# Run the setup tool
surfscan-setup

# Navigate to: License Management → View Device Information
# Copy the displayed Device ID (32 characters)
```

The device ID is a unique identifier based on your hardware and cannot be transferred to other devices.

### Requesting a License


1. **Get Device ID**: Run `surfscan-setup` and copy your device ID
2. **Email Support**: Send your device ID to `support@waveriders.live`
3. **Include Information**:
   * Your device ID (32-character string)
   * Your name and organization
   * Intended use case for testing
4. **Wait for Response**: Support will generate and email your license key

### Email Template for License Request

```
Subject: SurfScan Alpha License Request

Hi SurfScan Team,

I would like to request an alpha test license for SurfScan.

Device ID: [paste your 32-character device ID here]
Name: [your name]
Organization: [your organization] 
Use Case: [brief description of intended testing]

Thank you!
```

### Applying Your License

Once you receive your license key via email:

```bash
# Run the setup tool  
surfscan-setup

# Navigate to: License Management → Apply License
# Choose one of these options:

# Option 1: Paste license key directly
# - Select "Enter license key"
# - Paste the entire license key from your email
# - Click Apply

# Option 2: Use license file
# - Save the license key to a file (e.g., license.dat)
# - Select "Load from file"  
# - Browse to your license file
# - Click Apply
```

### Verifying License Status

After applying your license:

```bash
# Check license status
surfscan-setup

# Navigate to: License Management → View License Status
# You should see:
# - Status: Licensed
# - Expiration date
# - License type (usually "alpha_test")
# - Features available
```

### License Troubleshooting

#### Invalid License Error

```bash
# If you get "Invalid license" error:
# 1. Verify you copied the complete license key
# 2. Check that the license was generated for your device ID
# 3. Ensure no extra spaces or line breaks in the license key
# 4. Contact support if the issue persists
```

#### License Not Persistent

```bash
# If license doesn't persist after reboot:
# 1. Check file permissions
sudo ls -la /etc/surfscan/license.dat

# 2. Verify services can read the license
surfscan-doctor

# 3. Re-apply license if needed
surfscan-setup
```

#### Trial Mode Won't Start

```bash
# If trial mode doesn't activate:
# 1. Check trial file exists
ls -la /var/lib/surfscan/.trial_started

# 2. Restart services
sudo surfscan-ctl restart

# 3. Run diagnostics
surfscan-doctor
```

### License Renewal

Licenses have expiration dates. To renew:


1. **Check Expiration**: `surfscan-setup` shows expiration date
2. **Request Renewal**: Email support with your device ID 2-3 days before expiration
3. **Apply New License**: Follow the same application process
4. **No Downtime**: Services continue running during renewal

### Important Notes

* **Hardware Binding**: Licenses are tied to your specific device and cannot be transferred
* **Trial Period**: 48 hours of full functionality from first installation
* **Backup License**: Save your license key email in case you need to re-apply
* **Support Contact**: For all license issues, email `support@waveriders.live`

## Modem Band Configuration

SurfScan v1.3.0-alpha introduces **International Modem Band Configuration** for optimizing cellular frequency bands based on your deployment region. This feature enables optimal scanning performance by configuring country-specific LTE, 5G NSA, and 5G SA frequency bands on supported hardware (Quectel RM520N-GL modem).

### Supported Configurations

**USA Configuration:**

* Optimized for North American carriers (AT&T, Verizon, T-Mobile)
* **LTE Bands**: 2, 4, 5, 12, 13, 14, 17, 25, 26, 30, 41, 48, 66, 71
* **5G NSA Bands**: n2, n5, n25, n41, n48, n66, n71, n77, n260, n261
* **5G SA Bands**: n2, n5, n25, n41, n48, n66, n71, n77, n260, n261

**UK Configuration:**

* Optimized for UK carriers (EE, O2, Vodafone, Three)
* **LTE Bands**: 1, 3, 7, 8, 20, 28, 32, 38, 40
* **5G NSA Bands**: n1, n3, n7, n8, n20, n28, n38, n40, n77, n78
* **5G SA Bands**: n1, n3, n7, n8, n20, n28, n77, n78

**Global Configuration (Default):**

* Comprehensive worldwide frequency support
* All available LTE and 5G bands for maximum compatibility
* Recommended for international deployments and testing scenarios

### Configuration Methods

#### Interactive Setup via surfscan-setup

Access the band configuration through the main setup wizard:

```bash
# Launch interactive setup
surfscan-setup

# Navigate to: Hardware Configuration → Modem Band Configuration
```

**Menu Options:**


1. **Query current configuration** - Shows current band settings and detected country
2. **Configure for USA** - Apply USA-specific frequency bands
3. **Configure for UK** - Apply UK-specific frequency bands
4. **Configure for Global (default)** - Apply worldwide frequency bands
5. **Return to main menu** - Exit band configuration

**Query Display Example:**

```
📡 Current Modem Band Configuration

Country: GLOBAL
LTE Bands: 1,2,3,4,5,7,8,12,13,17,18,19,20,21,25,26,28,34,38,39,40,41,42,43,48,66,71
5G NSA Bands: n1,n2,n3,n5,n7,n8,n12,n20,n25,n28,n38,n40,n41,n48,n66,n71,n77,n78,n79,n260,n261
5G SA Bands: n1,n2,n3,n5,n7,n8,n20,n25,n28,n38,n40,n41,n48,n66,n71,n77,n78,n79,n260,n261
```

#### Command Line Interface

Use the dedicated CLI tool for automated configuration:

```bash
# Query current band configuration
surfscan-band-config --query

# Configure for specific country/region
surfscan-band-config --country USA
surfscan-band-config --country UK  
surfscan-band-config --country GLOBAL

# Show help and version information
surfscan-band-config --help
surfscan-band-config --version
```

### Configuration Workflow


1. **Query Current Settings**: Check existing band configuration to understand current state
2. **Select Target Configuration**: Choose USA, UK, or Global based on deployment location
3. **Apply Configuration**: Tool automatically configures modem with appropriate bands
4. **System Reboot**: Reboot required due to modem port reassignment (ttyUSB2 → ttyUSB3)
5. **Validation**: Verify new configuration with query command after reboot

### Important Notes

**System Requirements:**

* **Hardware**: Requires Quectel RM520N-GL modem (SurfScanGo hardware platform)
* **Reboot Required**: Band configuration changes require system reboot due to modem port reassignment
* **Persistence**: Band settings are maintained across reboots and firmware updates

**Country Detection:**

* Tool automatically detects current band configuration
* Displays country ID (USA/UK/GLOBAL) based on exact band pattern matching
* Shows "UNKNOWN" for custom configurations not matching predefined patterns

**Deployment Considerations:**

* **USA**: Optimized for CDMA and GSM carriers with mmWave 5G support
* **UK**: Optimized for European frequency allocations and regulatory requirements
* **Global**: Maximum compatibility for international roaming and testing scenarios

### Troubleshooting Band Configuration

**Configuration Not Applied:**

```bash
# Verify modem is detected
ls -la /dev/ttyUSB*

# Check for port conflicts
sudo lsof /dev/ttyUSB*

# Restart services after configuration
sudo surfscan-ctl restart
```

**Port Assignment Changed:**

* Normal behavior after band configuration
* Modem port typically changes from ttyUSB2 to ttyUSB3
* Services automatically adapt after reboot

**Country Detection Issues:**

* Use exact band matching for country identification
* Custom configurations show as "UNKNOWN"
* Query command shows detailed band lists for verification

## WiFi Hotspot Management

SurfScan v1.2.5-alpha includes built-in WiFi hotspot functionality, allowing wireless access to all SurfScan interfaces from mobile devices and laptops. WiFi management is handled exclusively through the command line interface for enhanced stability.

### WiFi Configuration Details

**Network Information:**

* **SSID**: `surfscan-<last4>` (device-specific, e.g., surfscan-f3d7)
* **Password**: `surfscango!!` (fixed for all devices)
* **Gateway**: `172.16.48.1`
* **Network**: `172.16.48.0/24`
* **DHCP Range**: `172.16.48.100-172.16.48.200`

### WiFi Management Commands

All WiFi hotspot operations are performed via the `surfscan-setup` command:

```bash
# Access WiFi management
surfscan-setup

# Navigate to: WiFi Hotspot Management
# Available options:
# → Enable WiFi Hotspot
# → Disable WiFi Hotspot  
# → View WiFi Status
# → Configure WiFi Settings
```

### Enabling WiFi Hotspot

```bash
surfscan-setup
# → WiFi Hotspot Management
# → Enable WiFi Hotspot

# The system will:
# 1. Configure NetworkManager connection profile
# 2. Enable WiFi radio if needed
# 3. Start the access point
# 4. Configure automatic startup on boot
```

### Accessing SurfScan via WiFi

Once the WiFi hotspot is enabled:


1. **Connect to WiFi Network**:
   * SSID: `surfscan-<last4>` (shown in setup output)
   * Password: `surfscango!!`
2. **Access Web Interfaces**:
   * **Scanner App**: <https://172.16.48.1/>
   * **System Admin**: <https://172.16.48.1/admin/>
   * **API Documentation**: <https://172.16.48.1/api/admin/docs>
3. **Authentication**: Same credentials as local access (system username/password)

### WiFi Status and Troubleshooting

**Check WiFi Status:**

```bash
surfscan-setup
# → WiFi Hotspot Management
# → View WiFi Status
```

**Common WiFi Issues:**

**WiFi Not Broadcasting:**

* Check if WiFi radio is enabled: Run `surfscan-setup` → WiFi Status
* Verify network interface: `ip addr show wlan0`
* Check NetworkManager service: `systemctl status NetworkManager`

**Cannot Connect to WiFi:**

* Verify SSID and password
* Check signal strength (move closer to device)
* Restart WiFi hotspot via surfscan-setup

**No Internet Access via WiFi:**

* Check if ethernet or cellular uplink is available
* WiFi provides internet sharing when uplinks are connected
* SurfScan services accessible regardless of internet connection

### Important Notes

* **CLI-Only Management**: WiFi functionality removed from admin dashboard in v1.2.5 for stability
* **NetworkManager Based**: Uses modern NetworkManager instead of legacy hostapd/dnsmasq
* **Auto-Start**: WiFi hotspot automatically starts on boot when enabled
* **Internet Sharing**: Automatically shares internet when ethernet/cellular available
* **Device Specific**: Each device has unique SSID based on hardware MAC address

## Setup and Configuration

The `surfscan-setup` tool provides guided setup and configuration assistance.

### Interactive Setup

```bash
# Run interactive setup wizard
surfscan-setup
```

The setup wizard includes:


1. System requirements check
2. Installation verification
3. Hardware configuration
4. Service setup
5. Access information
6. Tool overview
7. First scan guide

### Automated Setup

```bash
# Run all checks automatically
surfscan-setup all
```

### When to Use Setup

* After initial installation
* When experiencing problems
* To learn about SurfScan features
* To verify system configuration
* Before performing scans

## Web Interfaces

SurfScan v1.3.0+ uses a hybrid architecture with Cockpit for system administration and a dedicated Scanner App for scanning operations:

### Scanner App (HTTPS - Main Interface)

**Purpose**: Primary interface for cellular network scanning and analysis

**Access**: `https://[rpi-ip]/` (root URL)

**Features**:

* Complete scan configuration and control
* GPS status monitoring with satellite info
* Real-time scan progress and results
* Custom reports (GoRout, CBRS, FirstNet, Bonded LTE)
* Session management and data viewing
* Mobile-responsive design
* PAM authentication using system users

**Tabs**:

* **Configure Scan**: Set scan mode, duration, and notes
* **Manage Scan**: Start/stop scans, view progress
* **Reports**: Generate custom analysis reports

**Authentication**: Use your system username/password (PAM - any system user)

### Cockpit System Admin (HTTPS)

**Purpose**: System administration with SurfScan-specific plugin

**Access**: `https://[rpi-ip]/admin/`

**Native Cockpit Features**:

* Service management (start/stop/restart surfscan-\* services)
* System monitoring (CPU, RAM, disk, network)
* Log viewing via journalctl integration
* Network configuration
* Terminal access

**SurfScan Admin Plugin** (click "SurfScan" in left menu):

* **Database Tab**: Backup, restore, export operations
* **Sensor Tab**: Configure autonomous scheduled scanning
* **Cloud Tab**: Supabase sync status and configuration

**Authentication**: Same system credentials as Scanner App

### Direct Access (Bypass nginx)

**Scanner Interface**: `http://[rpi-ip]:8000`

* No authentication required on direct port
* Useful for development/debugging

**Admin API**: `http://[rpi-ip]:8090/api/admin/docs`

* Interactive API documentation
* Requires HTTP Basic Auth

### API Endpoints

**Purpose**: Programmatic access to SurfScan functionality

**Scanner API**: `https://[rpi-ip]/api/` (via nginx proxy) **Admin API**: `https://[rpi-ip]/api/admin/docs` (port 8090 proxied) **Direct Scanner API**: `http://[rpi-ip]:8080/docs` **Direct Admin API**: `http://[rpi-ip]:8090/api/admin/docs`

**Common Endpoints**:

* `GET /api/status` - Service status
* `GET /api/sessions` - List scan sessions
* `GET /api/data` - Scan data
* `POST /api/scan/start` - Start scan
* `GET /api/scan/status` - Scan progress

**Usage Example**:

```bash
# Check API status
curl http://[rpi-ip]:8080/api/status

# Get recent sessions
curl http://[rpi-ip]:8080/api/sessions

# Start a manual scan
curl -X POST http://[rpi-ip]:8080/api/scan/start \
  -H "Content-Type: application/json" \
  -d '{"mode": "manual", "latitude": 40.7128, "longitude": -74.0060}'
```

## Troubleshooting

### Common Issues and Solutions

#### Services Won't Start

```bash
# Check what's wrong
surfscan-doctor

# Restart services
sudo surfscan-ctl restart

# Check logs for errors
surfscan-logs errors

# Verify version consistency across tools
surfscan-ctl --version
surfscan-doctor --version
```

#### No GPS Signal (gpsd GPS System - v1.2.8)

* Move to outdoor location with clear sky view
* Use Manual mode for indoor testing
* Check GPS hardware connection
* **gpsd Service Status:**
  * Verify gpsd service is running: `systemctl status gpsd`
  * Check gpsd configuration: `cat /etc/default/gpsd`
  * View gpsd logs: `sudo journalctl -u gpsd -f`
* **GPS Hardware Detection:**
  * Monitor GPS status: `cgps -s` (press Ctrl+C to exit)
  * Check GPS devices: `gpsctl -l`
  * Test GPS data stream: `gpspipe -w -n 5 | jq .`
* **GPS API Testing:**
  * Check real-time GPS: `curl http://localhost:8080/api/gps/current | jq .`
  * Verify API status includes GPS: `curl http://localhost:8080/api/status | jq .gps`

#### No Cellular Data

* Check modem hardware connection
* Verify antenna connections
* Ensure ModemManager is disabled: `sudo systemctl status ModemManager`
* Check cellular service logs: `surfscan-logs follow cellular-api`

#### Web Interface Not Accessible

```bash
# Check if services are running
surfscan-ctl status

# Verify ports are available
sudo netstat -tlnp | grep -E ":(8000|8080|8090)"

# Check firewall settings
sudo ufw status
```

#### Database Issues

```bash
# Check database status
sudo surfscan-db info

# Create backup before fixing
sudo surfscan-db backup emergency-backup

# Optimize database
sudo surfscan-db optimize
```

### Getting Help


1. **Run diagnostics**: `surfscan-doctor`
2. **Check logs**: `surfscan-logs errors`
3. **Export logs for support**: `surfscan-logs export`
4. **Check service status**: `surfscan-ctl status`
5. **Verify version information**: `surfscan-ctl --version` (consistent across all tools)
6. **Restart services**: `sudo surfscan-ctl restart`

### Log Export for Support

If you need to contact support, export your logs:

```bash
# Export all logs and system information
surfscan-logs export

# This creates a timestamped archive like:
# /tmp/surfscan-logs-20250627-162300.tar.gz
```

The archive includes:

* All service logs
* System information
* Service status
* Configuration files (sanitized)

## GoRout Band Optimization Reports

SurfScan includes specialized band optimization reports designed for GoRout's wearable sports devices, focusing on Band 2 and Band 5 LTE optimization for real-time coaching message delivery.

### Understanding GoRout Reports

**Target Bands**:

* **Band 2 (1900 MHz)**: Primary band for high-capacity urban coverage
* **Band 5 (850 MHz)**: Extended range band for rural and indoor coverage
* **FirstNet Exclusion**: Emergency services bands are automatically excluded from analysis

**Optimization Focus**:

* **Real-time Communication**: Optimized for low-latency coaching message delivery
* **Wearable Device Requirements**: Prioritizes consistent signal strength and quality
* **Multi-band Analysis**: Compares Band 2 vs Band 5 performance characteristics

### Using the GoRout Interface

#### Accessing GoRout Reports


1. **Navigate to Scanner App**:
   * Open `https://[your-rpi-ip]/`
   * Login with your system credentials
2. **Select GoRout Report**:
   * Click the "Reports" tab
   * Select "GoRout" from the report mode dropdown
   * Interface loads with orange/black GoRout branding
3. **Select Session for Analysis**:
   * Click "Refresh Sessions" to load available data
   * Select session from dropdown menu
   * Only sessions with cellular data will be available

#### Interpreting GoRout Reports

**Band Analysis Sections**:

* **Availability**: Whether the band was detected during scanning
* **RSRP (Signal Strength)**: Average received signal power in dBm
* **RSRQ (Signal Quality)**: Average signal quality in dB
* **GoRout Score**: Weighted score (60% RSRP, 40% RSRQ) out of 100
* **Carriers**: Network operators detected on this band

**Recommendation System**:

* **Primary Band**: Best performing band for device deployment
* **Secondary Band**: Backup band recommendation
* **Confidence Level**: System confidence in recommendations (High/Medium/Low)
* **Rationale**: Explanation of recommendation reasoning

#### Downloading PDF Reports


1. **Generate Report**:
   * Select session and wait for analysis to complete
   * Report displays Band 2 vs Band 5 comparison
2. **Download PDF**:
   * Click "Download PDF Report" button
   * PDF generates with GoRout branding and detailed analysis
   * File saves as `gorout-report-[session-id].pdf`

**PDF Report Contents**:

* GoRout corporate branding with orange/black theme
* Executive summary of band recommendations
* Detailed technical metrics for both bands
* Visual comparison charts and signal strength analysis
* Deployment recommendations for optimal performance

### GoRout Report Troubleshooting

#### No Sessions Available

* **Cause**: No scan sessions with cellular data found
* **Solution**: Complete at least one scan with detected cellular networks
* **Check**: Ensure scans were successful and data was recorded

#### Report Generation Fails

* **Cause**: Session may lack Band 2 or Band 5 data
* **Solution**: Select session with LTE data on target bands
* **Check**: Review original scan results for band coverage

#### PDF Download Issues

* **Cause**: Browser blocking downloads or PDF generation failure
* **Solution**: Check browser permissions and try again
* **Fallback**: Use JSON report data from API directly

#### Empty Analysis Results

* **Cause**: Selected session contains no Band 2/5 LTE data
* **Solution**: Choose different session or perform new scan in area with target bands
* **Note**: GoRout reports require specific band data to generate recommendations

### GoRout API Integration

For programmatic access to GoRout reports:

```bash
# Generate JSON report
curl http://[rpi-ip]:8080/api/gorout-report/[session-id]

# Download PDF report
curl http://[rpi-ip]:8080/api/gorout-report/[session-id]/pdf -o report.pdf
```

## CBRS Band 48 Reports

SurfScan includes specialized CBRS (Citizens Broadband Radio Service) reports for analyzing Band 48 LTE and 5G NR networks in the 3.5 GHz spectrum.

### Understanding CBRS Reports

**Target Networks**:

* **Band 48 LTE (b48)**: LTE networks on 3550-3700 MHz spectrum
* **Band 48 5G NR (n48)**: 5G networks on 3550-3700 MHz spectrum
* **Operator Analysis**: Groups networks by operator with PLMN ID fallback

**Use Cases**:

* **Private Networks**: Analyze private LTE/5G CBRS deployments
* **Neutral Host Networks**: Identify shared infrastructure operators
* **Spectrum Planning**: Understand CBRS utilization in your area
* **Network Selection**: Compare CBRS network performance by operator

### Using the CBRS Interface

#### Accessing CBRS Reports


1. **Navigate to Scanner App**:
   * Open `https://[your-rpi-ip]/`
   * Login with your system credentials
2. **Select CBRS Report**:
   * Click the "Reports" tab
   * Select "CBRS" from the report mode dropdown
   * Interface loads with Waveriders green branding
3. **Select Session for Analysis**:
   * Click "Refresh Sessions" to load available data
   * Select session from dropdown menu
   * Only sessions with Band 48 data will show results

#### Interpreting CBRS Reports

**Session Information**:

* **Date/Time**: When the scan was performed
* **GPS Location**: OpenStreetMap link to scan location
* **Session Notes**: Any notes recorded during scanning

**Network List Displays**:

* **Operator**: Network operator name (or MCC-MNC if unknown)
* **Technology**: LTE or 5G
* **SurfScore**: Weighted performance score (60% RSRP, 40% RSRQ)
* **RSRP (Signal Strength)**: Average received signal power in dBm
* **Bandwidth**: Channel bandwidth in MHz
* **Frequency**: Center frequency in MHz

**Data Organization**:

* Networks grouped by operator and technology
* Sorted alphabetically by operator name
* Separate entries for LTE vs 5G networks from same operator

### CBRS Report Troubleshooting

#### No Networks Detected

* **Cause**: No Band 48 CBRS networks in scan area
* **Solution**: CBRS is limited to specific locations (primarily USA)
* **Note**: Check if CBRS networks are deployed in your area

#### Session Shows "No Data"

* **Cause**: Selected session contains no Band 48 networks
* **Solution**: Choose different session or scan in CBRS coverage area
* **Check**: Verify modem supports Band 48 LTE/5G scanning

### CBRS API Integration

For programmatic access to CBRS reports:

```bash
# Generate JSON report
curl http://[rpi-ip]:8080/api/cbrs-report/[session-id]

# Example response includes:
# - session_info (date, notes, GPS coordinates, OSM link)
# - networks array (operator, technology, metrics)
# - total_networks count
```

## FirstNet Reports

SurfScan includes specialized FirstNet reports for analyzing AT&T's FirstNet emergency services network (PLMN 313-100).

### Understanding FirstNet Reports

**Target Network**:

* **PLMN 313-100**: FirstNet dedicated network infrastructure
* **Emergency Services**: Priority network for first responders
* **Band Analysis**: Shows all bands used by FirstNet in your area

**Use Cases**:

* **Public Safety**: Verify FirstNet coverage for emergency services
* **Network Planning**: Understand FirstNet deployment patterns
* **Band Identification**: Identify which bands FirstNet uses locally
* **Coverage Validation**: Confirm FirstNet availability at specific locations

### Using the FirstNet Interface

#### Accessing FirstNet Reports


1. **Navigate to Scanner App**:
   * Open `https://[your-rpi-ip]/`
   * Login with your system credentials
2. **Select FirstNet Report**:
   * Click the "Reports" tab
   * Select "Public Safety" from the report mode dropdown
   * Interface loads with black/white FirstNet branding
3. **Select Session for Analysis**:
   * Click "Refresh Sessions" to load available data
   * Select session from dropdown menu
   * Only sessions with PLMN 313-100 data will show results

#### Interpreting FirstNet Reports

**Session Information**:

* **Date/Time**: When the scan was performed
* **GPS Location**: OpenStreetMap link to scan location
* **Session Notes**: Any notes recorded during scanning

**Network List Displays**:

* **Band**: Frequency band (e.g., b14, b12, n14)
* **RSRP (Signal Strength)**: Average received signal power in dBm (sorted strongest first)
* **SurfScore**: Weighted performance score (60% RSRP, 40% RSRQ)
* **Bandwidth**: Channel bandwidth in MHz
* **Frequency**: Center frequency in MHz

**Data Organization**:

* Networks grouped by band
* Sorted by RSRP (strongest signal first)
* Shows FirstNet deployment characteristics in your area

### FirstNet Report Troubleshooting

#### No Networks Detected

* **Cause**: No FirstNet (313-100) networks in scan area
* **Solution**: FirstNet coverage varies by location
* **Note**: FirstNet primarily operates on Band 14 (700 MHz) but may use other bands

#### Session Shows "No Data"

* **Cause**: Selected session contains no PLMN 313-100 networks
* **Solution**: Choose different session or scan in FirstNet coverage area
* **Check**: Verify scan location has FirstNet deployment

### FirstNet API Integration

For programmatic access to FirstNet reports:

```bash
# Generate JSON report
curl http://[rpi-ip]:8080/api/firstnet-report/[session-id]

# Example response includes:
# - session_info (date, notes, GPS coordinates, OSM link)
# - networks array (band, rsrp, surfscore, metrics)
# - total_networks count
```

**Scan Mode**: Sessions are tagged with their scan mode (`manual` or `sensor`). Manual scans are performed through the Scanner App interface, while sensor scans are automated scans performed by the Sensor Mode service.

## Bonded LTE Reports

SurfScan includes specialized Bonded LTE reports for multi-WAN uplink bonding use cases. This report recommends the best LTE bands for bonded connections based on signal quality and bandwidth.

### Understanding Bonded LTE Reports

**Purpose**:

* **LTE-Only Analysis**: Recommends LTE bands only (not 5G SA) since US modems primarily use LTE anchors
* **Uplink Optimization**: Prioritizes bands with better uplink capacity for bonded streaming
* **Multi-Connection Support**: Supports 2-8 bonded modem configurations

**Scoring System** (100 points total):

* **RSRP (25%)**: Signal strength - stronger is better
* **RSRQ (20%)**: Signal quality - cleaner signal preferred
* **Bandwidth (30%)**: Higher bandwidth prioritized for throughput
* **Band Type (25%)**: Mid-band (1-2.5 GHz) preferred over low-band for uplink performance

**5G Reference Section**:

* Shows available 5G/NR bands by operator
* Helps understand what 5G bands may aggregate when anchoring on recommended LTE bands

### Using the Bonded LTE Interface

#### Accessing Bonded LTE Reports


1. **Navigate to Scanner App**:
   * Open `https://[your-rpi-ip]/`
   * Login with your system credentials
2. **Select Bonded LTE Report**:
   * Click the "Reports" tab
   * Select "Bonded LTE" from the report mode dropdown (default)
   * Wait for session list to load
3. **Select Scan Session**:
   * Choose a completed scan session from the dropdown
   * Sessions show date/time and notes
4. **Select Number of Connections**:
   * Use the "Connections" dropdown to select 2-8 modems
   * Report automatically updates to show top N recommendations

#### Interpreting Bonded LTE Reports

**Recommendation Cards**: Each card displays:

* **Rank**: Position (1-8) based on SurfScore
* **Carrier/Operator**: Network provider name
* **Band**: LTE band identifier (e.g., b2, b4, b66)
* **SurfScore**: Overall score (0-100, higher is better)
* **RSRP**: Signal strength in dBm
* **RSRQ**: Signal quality in dB
* **Bandwidth**: Channel width in MHz
* **Frequency**: Center frequency in MHz

**5G Bands Section**:

* Lists available 5G bands by operator
* Useful for understanding carrier aggregation potential

### Bonded LTE Report Troubleshooting

#### No Recommendations Shown

* **Cause**: No LTE networks in scan data
* **Solution**: Ensure scan was completed with cellular data
* **Check**: Verify modem is connected and scanning properly

#### FirstNet Networks Excluded

* **Expected Behavior**: FirstNet (PLMN 313-100) is automatically excluded
* **Reason**: FirstNet is reserved for public safety and not available to general users

### Bonded LTE API Integration

For programmatic access to Bonded LTE reports:

```bash
# Generate JSON report with default 8 connections
curl http://[rpi-ip]:8080/api/bonded-lte-report/[session-id]

# Specify number of connections (2-8)
curl http://[rpi-ip]:8080/api/bonded-lte-report/[session-id]?connections=4

# Example response includes:
# - session_info (date, notes, GPS coordinates, OSM link)
# - recommendations array (operator, band, surfscore, rsrp, rsrq, bandwidth, frequency)
# - total_recommendations count
# - nr_bands_by_operator (5G bands reference)
```

## Expert Report

SurfScan includes an Expert Report for comprehensive network analysis with advanced sorting and filtering capabilities.

### Understanding Expert Reports

**Purpose**:

* **Comprehensive Analysis**: View all detected networks with detailed metrics
* **Sortable Columns**: Click any column header to sort ascending/descending
* **Operator Filtering**: Filter by specific carrier/operator
* **SurfScore Ranking**: Uplink-focused performance scoring for all networks

**SurfScore Algorithm** (Expert Report): The Expert Report uses an uplink-optimized scoring algorithm:

* **RSRP (20%)**: Signal strength contribution
* **RSRQ (25%)**: Signal quality contribution
* **Bandwidth (30%)**: Higher bandwidth prioritized
* **Band Type (25%)**: Mid-band (1-2.5 GHz) preferred for uplink performance

### Using the Expert Interface

#### Accessing Expert Reports


1. **Navigate to Scanner App**:
   * Open `https://[your-rpi-ip]/`
   * Login with your system credentials
2. **Select Expert Report**:
   * Click the "Reports" tab
   * Select "Expert" from the report mode dropdown
3. **Select Session for Analysis**:
   * Click "Refresh Sessions" to load available data
   * Select session from dropdown menu

#### Interpreting Expert Reports

**Table Columns**:

* **SurfScore**: Uplink-optimized performance score (bold, sorted descending by default)
* **Operator**: Network carrier name
* **Band**: Frequency band identifier
* **Protocol**: LTE or 5G NR
* **RSRP**: Signal strength in dBm
* **RSRQ**: Signal quality in dB
* **Bandwidth**: Channel width in MHz
* **Frequency**: Center frequency in MHz

**Sorting**: Click any column header to sort. Click again to reverse sort direction.

**Operator Filter**: Use the "All Operators" dropdown to filter by specific carrier.

**Text Search**: Use the search box to filter by any text in the table.

### Expert Report API Integration

```bash
# Generate Expert report
curl http://[rpi-ip]:8080/api/reports/expert/[session-id]

# Download CSV export
curl http://[rpi-ip]:8080/api/reports/expert/[session-id]?format=csv -o expert_report.csv
```

## Custom Report Development

The GoRout, CBRS, FirstNet, and Bonded LTE reports follow a consistent architecture that can be used as a template for creating custom reports:

### Custom Report Template Architecture

**Backend Components** (Python):


1. Analysis function in `dashboard/utils/scoring.py` - filters and processes scan data
2. API endpoint in `controller/scripts/surfscan_api.py` - serves report data as JSON
3. Optional PDF generator in `controller/utils/pdf_generator.py` - creates branded PDFs

**Frontend Components** (HTML/CSS/JS):


1. Theme CSS file - defines color scheme and branding
2. Tab section in `index.html` - displays report UI
3. JavaScript functions in `app.js` - handles data loading and display

### Phase 1 vs Phase 2 Reports

**Phase 1 (Current - CBRS & FirstNet)**:

* Simple list-based data display
* Accurate filtering and metrics
* Basic themed UI
* Session-based historical analysis

**Phase 2 (Planned)**:

* Enhanced UI specific to use case
* PDF report generation with branding
* Advanced filtering options
* Additional visualizations

For technical details on implementing custom reports, see development documentation in `CLAUDE.md`.

## Advanced Usage

### Automated Scanning

Create a script for regular automated scans:

```bash
#!/bin/bash
# automated-scan.sh

# Start scan via API
curl -X POST http://localhost:8080/api/scan/start \
  -H "Content-Type: application/json" \
  -d '{"mode": "gps"}'

# Wait for completion
sleep 60

# Export results
sudo surfscan-db export csv /data/scans/scan-$(date +%Y%m%d-%H%M%S).csv
```

### Custom Monitoring

Monitor SurfScan health with cron:

```bash
# Add to crontab (crontab -e)
# Run health check every hour
0 * * * * /usr/local/bin/surfscan-doctor > /var/log/surfscan-health.log 2>&1

# Backup database daily
0 2 * * * /usr/local/bin/surfscan-db backup daily-$(date +%Y%m%d) > /dev/null 2>&1
```

### Integration with Other Tools

SurfScan's API makes it easy to integrate with other tools:

**Python Example**:

```python
import requests
import json

# Start a scan
response = requests.post('http://localhost:8080/api/scan/start', 
                        json={'mode': 'gps'})

# Check status
status = requests.get('http://localhost:8080/api/scan/status')

# Get data when complete
if status.json()['status'] == 'completed':
    data = requests.get('http://localhost:8080/api/data')
    print(json.dumps(data.json(), indent=2))
```

### Performance Optimization

For optimal performance:


1. **Regular maintenance**:

   ```bash
   # Weekly database optimization
   sudo surfscan-db optimize
   
   # Clean old logs
   surfscan-logs clean
   ```
2. **Monitor resources**:

   ```bash
   # Check system health regularly
   surfscan-doctor
   ```
3. **Backup strategy**:

   ```bash
   # Automated daily backups
   sudo surfscan-db backup daily-$(date +%Y%m%d)
   
   # Clean old backups (keep 30 days)
   find /var/lib/surfscan/data/backups -name "*.db" -mtime +30 -delete
   ```

## Quick Reference

### Essential Commands

```bash
# Start SurfScan
sudo surfscan-ctl start

# Check health
surfscan-doctor

# View logs
surfscan-logs follow

# Backup database
sudo surfscan-db backup

# Configure modem bands
surfscan-band-config --query

# Check version (consistent across all tools)
surfscan-ctl --version

# Get help
surfscan-setup
```

### Access URLs

* **Scanner App**: `https://[rpi-ip]/` (Main scanning interface)
* **System Admin**: `https://[rpi-ip]/admin/` (Cockpit + SurfScan plugin)
* **API Docs**: `https://[rpi-ip]/api/admin/docs`

**Direct Access URLs** (bypass nginx proxy):

* **Scanner**: `http://[rpi-ip]:8000`
* **Scanner API**: `http://[rpi-ip]:8080`
* **Admin API**: `http://[rpi-ip]:8090`

### File Locations

* **Database**: `/var/lib/surfscan/data/surfscan.db`
* **Logs**: `/var/lib/surfscan/logs/`
* **Config**: `/etc/surfscan/surfscan.conf`
* **Tools**: `/usr/local/bin/surfscan-*`


---

For additional help, run any tool with `help` or `-h` to see detailed usage information.