feat: APRS export, USRP support, and MQTT data export (closes #222)

- GET /aprs/export?format=json|csv downloads all tracked APRS stations
- USRP (Ettus N200/B200/B210) detected via SoapyUHD and supported across
  all signal modes (FM demod, ADS-B, ISM, AIS, I/Q capture)
- Optional MQTT publisher broadcasts decoded events from every module;
  enabled by setting INTERCEPT_MQTT_BROKER, disabled by default
- paho-mqtt added to requirements.txt (optional dep)
- .gitignore: add *.kismet, aircraft_db.json/meta, SoapySDR/
- Bump version to 2.30.0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

utils/event_pipeline.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import Any
 
 from utils.alerts import get_alert_manager
+from utils.mqtt import publish as mqtt_publish
 from utils.recording import get_recording_manager
 from utils.temporal_patterns import get_pattern_detector
 
@@ -54,6 +55,12 @@ def process_event(mode: str, event: dict | Any, event_type: str | None = None) -
         # Alert failures should never break streaming
         pass
 
+    try:
+        mqtt_publish(mode, event, event_type)
+    except Exception:
+        # MQTT failures should never break streaming
+        pass
+
 
 def _extract_device_id(event: dict) -> str | None:
     for field in DEVICE_ID_FIELDS:

utils/mqtt.py

@@ -0,0 +1,107 @@
+"""
+Optional MQTT data export.
+
+Publishes decoded events from all modules to a configurable MQTT broker.
+Disabled when INTERCEPT_MQTT_BROKER is not set — no broker, no connection,
+no error.
+
+Topics follow the pattern:
+    <prefix>/<module>/<event_type>
+
+Payload is JSON, matching the SSE event structure already used by the
+frontend.  Configure via environment variables:
+
+    INTERCEPT_MQTT_BROKER        broker hostname / IP  (required to enable)
+    INTERCEPT_MQTT_PORT          port (default 1883)
+    INTERCEPT_MQTT_USER          username (optional)
+    INTERCEPT_MQTT_PASSWORD      password (optional)
+    INTERCEPT_MQTT_TOPIC_PREFIX  topic prefix (default "intercept")
+    INTERCEPT_MQTT_RETAIN        retain flag (default false)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_client = None
+_lock = threading.Lock()
+_enabled: bool | None = None  # None = not yet initialised
+
+
+def _get_config():
+    import config
+
+    return config
+
+
+def _is_enabled() -> bool:
+    global _enabled
+    if _enabled is None:
+        cfg = _get_config()
+        _enabled = bool(cfg.MQTT_BROKER)
+    return _enabled
+
+
+def _get_client():
+    """Return a connected paho MQTT client, creating it on first call."""
+    global _client
+    if _client is not None:
+        return _client
+
+    with _lock:
+        if _client is not None:
+            return _client
+
+        try:
+            import paho.mqtt.client as mqtt
+        except ImportError:
+            logger.warning("paho-mqtt not installed; MQTT export disabled. Install with: pip install paho-mqtt")
+            return None
+
+        cfg = _get_config()
+
+        client = mqtt.Client(client_id="intercept", clean_session=True)
+        if cfg.MQTT_USER:
+            client.username_pw_set(cfg.MQTT_USER, cfg.MQTT_PASSWORD or None)
+
+        try:
+            client.connect(cfg.MQTT_BROKER, cfg.MQTT_PORT, keepalive=60)
+            client.loop_start()
+            logger.info("MQTT connected to %s:%d (prefix=%s)", cfg.MQTT_BROKER, cfg.MQTT_PORT, cfg.MQTT_TOPIC_PREFIX)
+            _client = client
+        except Exception as exc:
+            logger.warning("MQTT connect failed: %s — export disabled until restart", exc)
+            return None
+
+    return _client
+
+
+def publish(mode: str, event: dict[str, Any], event_type: str | None = None) -> None:
+    """Publish a decoded event to the MQTT broker.
+
+    Args:
+        mode:       Source module name (e.g. 'aprs', 'adsb', 'pager').
+        event:      The decoded event dict.
+        event_type: Optional sub-type string (e.g. 'packet', 'aircraft').
+    """
+    if not _is_enabled():
+        return
+
+    client = _get_client()
+    if client is None:
+        return
+
+    cfg = _get_config()
+    subtopic = event_type or mode
+    topic = f"{cfg.MQTT_TOPIC_PREFIX}/{mode}/{subtopic}"
+
+    try:
+        payload = json.dumps(event, default=str)
+        client.publish(topic, payload, retain=cfg.MQTT_RETAIN)
+    except Exception as exc:
+        logger.debug("MQTT publish error on %s: %s", topic, exc)

utils/sdr/__init__.py

@@ -32,6 +32,7 @@ from .hackrf import HackRFCommandBuilder
 from .limesdr import LimeSDRCommandBuilder
 from .rtlsdr import RTLSDRCommandBuilder
 from .sdrplay import SDRPlayCommandBuilder
+from .usrp import USRPCommandBuilder
 from .validation import (
     SDRValidationError,
     get_capabilities_for_type,
@@ -53,6 +54,7 @@ class SDRFactory:
         SDRType.HACKRF: HackRFCommandBuilder,
         SDRType.AIRSPY: AirspyCommandBuilder,
         SDRType.SDRPLAY: SDRPlayCommandBuilder,
+        SDRType.USRP: USRPCommandBuilder,
     }
 
     @classmethod
@@ -211,6 +213,7 @@ __all__ = [
     "HackRFCommandBuilder",
     "AirspyCommandBuilder",
     "SDRPlayCommandBuilder",
+    "USRPCommandBuilder",
     # Validation
     "SDRValidationError",
     "validate_frequency",

utils/sdr/base.py

@@ -20,8 +20,8 @@ class SDRType(Enum):
     HACKRF = "hackrf"
     AIRSPY = "airspy"
     SDRPLAY = "sdrplay"
+    USRP = "usrp"
     # Future support
-    # USRP = "usrp"
     # BLADE_RF = "bladerf"
 
 

utils/sdr/detection.py

@@ -53,6 +53,7 @@ def _get_capabilities_for_type(sdr_type: SDRType) -> SDRCapabilities:
     from .limesdr import LimeSDRCommandBuilder
     from .rtlsdr import RTLSDRCommandBuilder
     from .sdrplay import SDRPlayCommandBuilder
+    from .usrp import USRPCommandBuilder
 
     builders = {
         SDRType.RTL_SDR: RTLSDRCommandBuilder,
@@ -60,6 +61,7 @@ def _get_capabilities_for_type(sdr_type: SDRType) -> SDRCapabilities:
         SDRType.HACKRF: HackRFCommandBuilder,
         SDRType.AIRSPY: AirspyCommandBuilder,
         SDRType.SDRPLAY: SDRPlayCommandBuilder,
+        SDRType.USRP: USRPCommandBuilder,
     }
 
     builder_class = builders.get(sdr_type)
@@ -90,8 +92,8 @@ def _driver_to_sdr_type(driver: str) -> SDRType | None:
         "airspy": SDRType.AIRSPY,
         "airspyhf": SDRType.AIRSPY,  # Airspy HF+ uses same builder
         "sdrplay": SDRType.SDRPLAY,
+        "uhd": SDRType.USRP,
         # Future support
-        # 'uhd': SDRType.USRP,
         # 'bladerf': SDRType.BLADE_RF,
     }
     return mapping.get(driver.lower())

utils/sdr/usrp.py

@@ -0,0 +1,153 @@
+"""
+USRP command builder implementation.
+
+Uses SoapySDR (via the UHD driver / SoapyUHD bridge) for all signal
+processing tasks.  The same rx_fm / rx_sdr / rtl_433 / AIS-catcher
+toolchain used by HackRF applies here because they all speak SoapySDR.
+
+Tested target: USRP N200 / B200 / B210 (UHD driver, SoapyUHD bridge).
+Requires: uhd, SoapySDR, SoapyUHD installed on the host or in Docker.
+"""
+
+from __future__ import annotations
+
+from utils.dependencies import get_tool_path
+
+from .base import CommandBuilder, SDRCapabilities, SDRDevice, SDRType
+
+
+class USRPCommandBuilder(CommandBuilder):
+    """USRP command builder using SoapySDR / UHD."""
+
+    CAPABILITIES = SDRCapabilities(
+        sdr_type=SDRType.USRP,
+        freq_min_mhz=1.0,
+        freq_max_mhz=6000.0,
+        gain_min=0.0,
+        gain_max=76.0,  # typical UHD normalised gain range
+        sample_rates=[1000000, 2000000, 4000000, 8000000, 16000000, 25000000],
+        supports_bias_t=False,
+        supports_ppm=False,
+        tx_capable=True,
+        supports_iq_capture=True,
+    )
+
+    def _build_device_string(self, device: SDRDevice) -> str:
+        """Build SoapySDR device string for USRP."""
+        if device.serial and device.serial not in ("N/A", "Unknown"):
+            return f"driver=uhd,serial={device.serial}"
+        return "driver=uhd"
+
+    def build_fm_demod_command(
+        self,
+        device: SDRDevice,
+        frequency_mhz: float,
+        sample_rate: int = 22050,
+        gain: float | None = None,
+        ppm: int | None = None,
+        modulation: str = "fm",
+        squelch: int | None = None,
+        bias_t: bool = False,
+    ) -> list[str]:
+        device_str = self._build_device_string(device)
+        rx_fm_path = get_tool_path("rx_fm") or "rx_fm"
+        cmd = [
+            rx_fm_path,
+            "-d",
+            device_str,
+            "-f",
+            f"{frequency_mhz}M",
+            "-M",
+            modulation,
+            "-s",
+            str(sample_rate),
+        ]
+        if gain is not None and gain > 0:
+            cmd.extend(["-g", str(int(gain))])
+        if squelch is not None and squelch > 0:
+            cmd.extend(["-l", str(squelch)])
+        cmd.append("-")
+        return cmd
+
+    def build_adsb_command(self, device: SDRDevice, gain: float | None = None, bias_t: bool = False) -> list[str]:
+        device_str = self._build_device_string(device)
+        cmd = ["readsb", "--net", "--device-type", "soapysdr", "--device", device_str, "--quiet"]
+        if gain is not None:
+            cmd.extend(["--gain", str(int(gain))])
+        return cmd
+
+    def build_ism_command(
+        self,
+        device: SDRDevice,
+        frequency_mhz: float = 433.92,
+        gain: float | None = None,
+        ppm: int | None = None,
+        bias_t: bool = False,
+    ) -> list[str]:
+        device_str = self._build_device_string(device)
+        cmd = ["rtl_433", "-d", device_str, "-f", f"{frequency_mhz}M", "-F", "json"]
+        if gain is not None and gain > 0:
+            cmd.extend(["-g", str(int(gain))])
+        return cmd
+
+    def build_ais_command(
+        self,
+        device: SDRDevice,
+        gain: float | None = None,
+        bias_t: bool = False,
+        tcp_port: int = 10110,
+        udp_host: str | None = None,
+        udp_port: int | None = None,
+    ) -> list[str]:
+        device_str = self._build_device_string(device)
+        cmd = [
+            "AIS-catcher",
+            "-d",
+            f"soapysdr -d {device_str}",
+            "-S",
+            str(tcp_port),
+            "-o",
+            "5",
+            "-q",
+        ]
+        if gain is not None and gain > 0:
+            cmd.extend(["-gr", "tuner", str(int(gain))])
+        if udp_host and udp_port:
+            cmd.extend(["-u", udp_host, str(udp_port)])
+        return cmd
+
+    def build_iq_capture_command(
+        self,
+        device: SDRDevice,
+        frequency_mhz: float,
+        sample_rate: int = 2048000,
+        gain: float | None = None,
+        ppm: int | None = None,
+        bias_t: bool = False,
+        output_format: str = "cu8",
+    ) -> list[str]:
+        device_str = self._build_device_string(device)
+        freq_hz = int(frequency_mhz * 1e6)
+        rx_sdr_path = get_tool_path("rx_sdr") or "rx_sdr"
+        cmd = [
+            rx_sdr_path,
+            "-d",
+            device_str,
+            "-f",
+            str(freq_hz),
+            "-s",
+            str(sample_rate),
+            "-F",
+            "CU8",
+        ]
+        if gain is not None and gain > 0:
+            cmd.extend(["-g", str(int(gain))])
+        cmd.append("-")
+        return cmd
+
+    def get_capabilities(self) -> SDRCapabilities:
+        return self.CAPABILITIES
+
+    @classmethod
+    def get_sdr_type(cls) -> SDRType:
+        return SDRType.USRP