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

  2. Service Management

  3. System Health & Diagnostics

  4. Log Management

  5. Database Operations

  6. Cloud Sync

  7. License Management

  8. Modem Band Configuration

  9. WiFi Hotspot Management

  10. Setup and Configuration

  11. Web Interfaces

  12. Troubleshooting

  13. Advanced Usage

Quick Start

After installing SurfScan, follow these steps to get started:

1. Run the Setup Guide

surfscan-setup

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

2. Start Services

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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)

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:

sudo nano /etc/surfscan/cloud_credentials.conf

Add your Supabase credentials:

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

Set proper permissions:

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

Restart the sync service:

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:

# 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

# 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

# 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:

# 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:

# 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:

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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

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:

  3. Authentication: Same credentials as local access (system username/password)

WiFi Status and Troubleshooting

Check WiFi Status:

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

# 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

# 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:

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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:

#!/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:

# 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:

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:

    # Weekly database optimization
sudo surfscan-db optimize

# Clean old logs
surfscan-logs clean

  2. Monitor resources:

    # Check system health regularly
surfscan-doctor

  3. Backup strategy:

    # 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

# 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.