intercept/GSM_SPY_DEVICE_SELECTION_IMPLEMENTATION.md

GSM Spy SDR Device Selection Implementation

Summary

Successfully implemented dynamic SDR device detection, selection, and management for the GSM Spy feature, following the same pattern used in the Aircraft/ADS-B implementation.

Changes Made

Frontend Changes (templates/gsm_spy_dashboard.html)

1. Dynamic Device Selector

• Changed: Device dropdown from hardcoded options to dynamic detection
• Location: Line ~1155 (Signal Source Panel)
• Before: Static options (Device 0, Device 1, etc.)
• After: Dynamic population with "Detecting devices..." placeholder

2. Device Detection on Page Load

• Added: initDeviceSelector() function
• Location: ~Line 1395
• Functionality:
  • Fetches available SDR devices from /devices endpoint
  • Populates dropdown with detected devices
  • Shows device name, type (RTL-SDR, HackRF, etc.), and serial number
  • Handles errors gracefully with user-friendly messages
  • Logs detection results to console

3. Scanner Controls Update

• Modified: startScanner() function (~Line 1410)
• Changes:
  • Made async for better error handling
  • Reads device index from deviceSelect dropdown
  • Disables device and region selectors during active scanning
  • Enhanced error handling with device conflict detection
  • Shows user-friendly alerts for device busy errors

4. Stop Scanner Enhancements

• Modified: stopScanner() function (~Line 1494)
• Changes:
  • Re-enables device and region selectors after stopping
  • Maintains UI consistency

5. Region Selector Sync

• Modified: selectRegion() function (~Line 1882)
• Changes:
  • Capitalizes region name to match backend API expectations
  • Syncs region button selection with dropdown

6. Removed Redundant Controls

• Removed: scannerDevice dropdown from bottom controls bar
• Reason: Consolidated to single device selector in left sidebar

Backend Changes (routes/gsm_spy.py)

1. Enhanced Error Response

• Modified: /start endpoint device claiming logic (~Line 115)
• Changes:
  • Added error_type: 'DEVICE_BUSY' to 409 conflict responses
  • Enables frontend to distinguish device conflicts from other errors
  • Allows for targeted user-friendly error messages

2. Existing Device Management (Verified)

• Confirmed: Device claiming/releasing already implemented
  • claim_sdr_device() called at line 115
  • release_sdr_device() called at line 289
  • Device index stored in gsm_spy_active_device
  • Region stored in gsm_spy_region

3. Status Endpoint (Verified)

• Confirmed: /status endpoint returns device info
  • Returns device (active device index)
  • Returns region (selected region)
  • Returns all necessary status information

Features Implemented

✅ Device Detection

• Dynamically detects all available SDR devices on page load
• Supports all 5 SDR types: RTL-SDR, HackRF, LimeSDR, Airspy, SDRPlay
• Shows device name, type, and serial number in dropdown

✅ Device Registry Integration

• Properly claims devices before starting scanner
• Releases devices when stopping scanner
• Prevents conflicts with other INTERCEPT modes

✅ UI State Management

• Disables device selector during active scanning
• Re-enables selector after stopping
• Provides clear visual feedback to user

✅ Error Handling

• User-friendly error messages for device conflicts
• Graceful handling of "no devices detected" scenario
• Clear console logging for debugging

✅ Validation

• Uses existing validate_device_index() function (already in code)
• Validates region against REGIONAL_BANDS dictionary
• Checks for already running scanner

Architecture Pattern

The implementation follows the same pattern as Aircraft/ADS-B:

1. Device Detection: /devices endpoint (shared across all modes)
2. Device Claiming: claim_sdr_device() before starting
3. Device Releasing: release_sdr_device() on stop
4. UI Consistency: Dynamic dropdown, disabled during operation
5. Error Handling: Clear user messages, console logging

Testing Recommendations

1. Device Detection

# Start application
sudo -E venv/bin/python intercept.py

# Open GSM Spy dashboard in browser
# Open DevTools console
# Should see: "[GSM SPY] Detected X SDR device(s)"
# Verify dropdown shows detected devices

2. Device Claiming

# Start GSM scanner on device 0
# Try to start another mode (e.g., ADS-B) on device 0
# Should see conflict error message
# Stop GSM scanner
# Now ADS-B should be able to claim device 0

3. Multiple Devices

# Connect multiple SDR devices
# Open GSM Spy dashboard
# Verify all devices appear in dropdown
# Select different devices and verify they work independently

4. UI State

# Start GSM scanner
# Verify device selector is disabled
# Verify region selector is disabled
# Stop scanner
# Verify both selectors are re-enabled

5. Error Scenarios

# Disconnect SDR device
# Try to start scanner
# Should see graceful error message
# Reconnect device
# Refresh page - device should be detected

Known Limitations

1. gr-gsm Hardware Support: The gr-gsm tools may have limited support for non-RTL-SDR devices. This implementation handles device selection properly, but gr-gsm itself may only work with RTL-SDR.

2. Command Builder Integration: Full SDRFactory integration (using device-specific command builders) would require adding GSM-specific methods to command builders in utils/sdr/. This is a future enhancement.

3. Remote Device Support: Unlike ADS-B which supports remote dump1090 connections, GSM Spy currently only supports local SDR devices.

Future Enhancements

1. SDRFactory Integration

# In start_scanner():
from utils.sdr import SDRFactory

devices = SDRFactory.detect_devices()
sdr_device = next((d for d in devices if d.index == device_index), None)

builder = SDRFactory.get_builder(sdr_device.sdr_type)
cmd = builder.build_gsm_scanner_command(device=sdr_device, bands=REGIONAL_BANDS[region])

Note: This requires adding build_gsm_scanner_command() method to command builders.

2. Device-Specific Tuning

• Different gain settings per SDR type
• Frequency correction (PPM) based on device calibration
• Sample rate optimization per hardware

3. Multi-Device Monitoring

• Simultaneously monitor multiple towers on different devices
• Parallel scanning across multiple frequency bands

Compatibility

• Frontend: Modern browsers with ES6+ support (async/await)
• Backend: Python 3.8+
• SDR Hardware: RTL-SDR, HackRF, LimeSDR, Airspy, SDRPlay
• gr-gsm: Requires gr-gsm toolkit installed

Files Modified

1. /opt/intercept/templates/gsm_spy_dashboard.html - Frontend UI and JavaScript
2. /opt/intercept/routes/gsm_spy.py - Backend route handlers

Files Referenced (Not Modified)

1. /opt/intercept/routes/adsb.py - Reference implementation
2. /opt/intercept/utils/sdr/detection.py - Device detection
3. /opt/intercept/utils/sdr/__init__.py - SDRFactory
4. /opt/intercept/utils/validation.py - Input validation
5. /opt/intercept/app.py - Device registry functions

Verification

All changes have been implemented according to the plan. The implementation:

• ✅ Follows existing INTERCEPT patterns
• ✅ Maintains UI consistency across modes
• ✅ Includes proper error handling
• ✅ Uses centralized validation
• ✅ Integrates with device registry
• ✅ Provides clear user feedback

Implementation Date

2026-02-06