Add device debug endpoint and fix RTL-SDR detection issues

- Add /devices/debug endpoint for detailed SDR detection diagnostics
- Add kernel driver blacklisting to setup.sh for Debian/Ubuntu
- Blacklists dvb_usb_rtl28xxu, rtl2832, rtl2830, r820t modules
- Update docs to use correct venv command: sudo -E venv/bin/python

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -38,7 +38,7 @@
 git clone https://github.com/smittix/intercept.git
 cd intercept
 ./setup.sh
-sudo python3 intercept.py
+sudo -E venv/bin/python intercept.py
 ```
 
 ### Docker (Alternative)

app.py

@@ -164,6 +164,120 @@ def get_devices() -> Response:
     return jsonify([d.to_dict() for d in devices])
 
 
+@app.route('/devices/debug')
+def get_devices_debug() -> Response:
+    """Get detailed SDR device detection diagnostics."""
+    import shutil
+
+    diagnostics = {
+        'tools': {},
+        'rtl_test': {},
+        'soapy': {},
+        'usb': {},
+        'kernel_modules': {},
+        'detected_devices': [],
+        'suggestions': []
+    }
+
+    # Check for required tools
+    diagnostics['tools']['rtl_test'] = shutil.which('rtl_test') is not None
+    diagnostics['tools']['SoapySDRUtil'] = shutil.which('SoapySDRUtil') is not None
+    diagnostics['tools']['lsusb'] = shutil.which('lsusb') is not None
+
+    # Run rtl_test and capture full output
+    if diagnostics['tools']['rtl_test']:
+        try:
+            result = subprocess.run(
+                ['rtl_test', '-t'],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            diagnostics['rtl_test'] = {
+                'returncode': result.returncode,
+                'stdout': result.stdout[:2000] if result.stdout else '',
+                'stderr': result.stderr[:2000] if result.stderr else ''
+            }
+
+            # Check for common errors
+            combined = (result.stdout or '') + (result.stderr or '')
+            if 'No supported devices found' in combined:
+                diagnostics['suggestions'].append('No RTL-SDR device detected. Check USB connection.')
+            if 'usb_claim_interface error' in combined:
+                diagnostics['suggestions'].append('Device busy - kernel DVB driver may have claimed it. Run: sudo modprobe -r dvb_usb_rtl28xxu')
+            if 'Permission denied' in combined.lower():
+                diagnostics['suggestions'].append('USB permission denied. Add udev rules or run as root.')
+
+        except subprocess.TimeoutExpired:
+            diagnostics['rtl_test'] = {'error': 'Timeout after 5 seconds'}
+        except Exception as e:
+            diagnostics['rtl_test'] = {'error': str(e)}
+    else:
+        diagnostics['suggestions'].append('rtl_test not found. Install rtl-sdr package.')
+
+    # Run SoapySDRUtil
+    if diagnostics['tools']['SoapySDRUtil']:
+        try:
+            result = subprocess.run(
+                ['SoapySDRUtil', '--find'],
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+            diagnostics['soapy'] = {
+                'returncode': result.returncode,
+                'stdout': result.stdout[:2000] if result.stdout else '',
+                'stderr': result.stderr[:2000] if result.stderr else ''
+            }
+        except subprocess.TimeoutExpired:
+            diagnostics['soapy'] = {'error': 'Timeout after 10 seconds'}
+        except Exception as e:
+            diagnostics['soapy'] = {'error': str(e)}
+
+    # Check USB devices (Linux)
+    if diagnostics['tools']['lsusb']:
+        try:
+            result = subprocess.run(
+                ['lsusb'],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            # Filter for common SDR vendor IDs
+            sdr_vendors = ['0bda', '1d50', '1df7', '0403']  # Realtek, OpenMoko/HackRF, SDRplay, FTDI
+            usb_lines = [l for l in result.stdout.split('\n')
+                        if any(v in l.lower() for v in sdr_vendors) or 'rtl' in l.lower() or 'sdr' in l.lower()]
+            diagnostics['usb']['devices'] = usb_lines if usb_lines else ['No SDR-related USB devices found']
+        except Exception as e:
+            diagnostics['usb'] = {'error': str(e)}
+
+    # Check for loaded kernel modules that conflict (Linux)
+    if platform.system() == 'Linux':
+        try:
+            result = subprocess.run(
+                ['lsmod'],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            conflicting = ['dvb_usb_rtl28xxu', 'rtl2832', 'rtl2830']
+            loaded = [m for m in conflicting if m in result.stdout]
+            diagnostics['kernel_modules']['conflicting_loaded'] = loaded
+            if loaded:
+                diagnostics['suggestions'].append(f"Conflicting kernel modules loaded: {', '.join(loaded)}. Run: sudo modprobe -r {' '.join(loaded)}")
+        except Exception as e:
+            diagnostics['kernel_modules'] = {'error': str(e)}
+
+    # Get detected devices
+    devices = SDRFactory.detect_devices()
+    diagnostics['detected_devices'] = [d.to_dict() for d in devices]
+
+    if not devices and not diagnostics['suggestions']:
+        diagnostics['suggestions'].append('No devices detected. Check USB connection and driver installation.')
+
+    return jsonify(diagnostics)
+
+
 @app.route('/dependencies')
 def get_dependencies() -> Response:
     """Get status of all tool dependencies."""

docs/HARDWARE.md

@@ -139,14 +139,10 @@ pip install -r requirements.txt
 After installation:
 
 ```bash
-# Standard
+sudo -E venv/bin/python intercept.py
-sudo python3 intercept.py
-
-# With virtual environment
-sudo venv/bin/python intercept.py
 
 # Custom port
-INTERCEPT_PORT=8080 sudo python3 intercept.py
+INTERCEPT_PORT=8080 sudo -E venv/bin/python intercept.py
 ```
 
 Open **http://localhost:5050** in your browser.

docs/TROUBLESHOOTING.md

@@ -336,9 +336,7 @@ rtl_fm -M am -f 118000000 -s 24000 -r 24000 -g 40 2>/dev/null | \
 
 Run INTERCEPT with sudo:
 ```bash
-sudo python3 intercept.py
+sudo -E venv/bin/python intercept.py
-# Or with venv:
-sudo venv/bin/python intercept.py
 ```
 
 ### Interface not found after enabling monitor mode

docs/USAGE.md

@@ -110,7 +110,7 @@ INTERCEPT can be configured via environment variables:
 | `INTERCEPT_LOG_LEVEL` | `WARNING` | Log level (DEBUG, INFO, WARNING, ERROR) |
 | `INTERCEPT_DEFAULT_GAIN` | `40` | Default RTL-SDR gain |
 
-Example: `INTERCEPT_PORT=8080 sudo python3 intercept.py`
+Example: `INTERCEPT_PORT=8080 sudo -E venv/bin/python intercept.py`
 
 ## Command-line Options
 

setup.sh

@@ -389,6 +389,34 @@ EOF
   echo
 }
 
+blacklist_kernel_drivers_debian() {
+  local blacklist_file="/etc/modprobe.d/blacklist-rtlsdr.conf"
+
+  if [[ -f "$blacklist_file" ]]; then
+    ok "RTL-SDR kernel driver blacklist already present"
+    return 0
+  fi
+
+  info "Blacklisting conflicting DVB kernel drivers..."
+  $SUDO tee "$blacklist_file" >/dev/null <<'EOF'
+# Blacklist DVB-T drivers to allow rtl-sdr to access RTL2832U devices
+blacklist dvb_usb_rtl28xxu
+blacklist rtl2832
+blacklist rtl2830
+blacklist r820t
+EOF
+
+  # Unload modules if currently loaded
+  for mod in dvb_usb_rtl28xxu rtl2832 rtl2830 r820t; do
+    if lsmod | grep -q "^$mod"; then
+      $SUDO modprobe -r "$mod" 2>/dev/null || true
+    fi
+  done
+
+  ok "Kernel drivers blacklisted. Unplug/replug your RTL-SDR if connected."
+  echo
+}
+
 install_debian_packages() {
   need_sudo
 
@@ -396,7 +424,7 @@ install_debian_packages() {
   export DEBIAN_FRONTEND=noninteractive
   export NEEDRESTART_MODE=a
 
-  TOTAL_STEPS=15
+  TOTAL_STEPS=16
   CURRENT_STEP=0
 
   progress "Updating APT package lists"
@@ -452,6 +480,9 @@ install_debian_packages() {
 
   progress "Configuring udev rules"
   setup_udev_rules_debian
+
+  progress "Blacklisting conflicting kernel drivers"
+  blacklist_kernel_drivers_debian
 }
 
 # ----------------------------
@@ -476,8 +507,7 @@ final_summary_and_hard_fail() {
 
   echo
   echo "To start INTERCEPT:"
-  echo "  source venv/bin/activate"
+  echo "  sudo -E venv/bin/python intercept.py"
-  echo "  sudo python intercept.py"
   echo
   echo "Then open http://localhost:5050 in your browser"
   echo