pluto-siege 2.0.1__py3-none-any.whl

pluto_siege/__init__.py

@@ -0,0 +1,43 @@
+# PlutoSiege - RF capture and replay tool for PlutoSDR.
+# Copyright (C) 2026 SketchTurnerDev
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""PlutoSDR capture and replay tool for short ISM-band bursts.
+
+A full-screen terminal application that records brief RF transmissions - car
+remotes, doorbells, weather stations and similar OOK/ASK devices - and replays
+them. Recordings are written as SigMF pairs so they can be opened in other
+tools as well.
+
+Usage:
+    python3 -m pluto_siege
+
+Requires Python 3.9+, an interactive terminal, an ADALM-Pluto (or compatible
+AD936x device) and:
+    pip install -r requirements.txt
+
+Transmitting is regulated. Replay only signals you are licensed or permitted to
+emit, into a dummy load or at the lowest gain that does the job.
+
+Author: SketchTurnerDev
+"""
+
+from pluto_siege.constants import AUTHOR, LICENSE, VERSION
+
+__version__ = VERSION
+__author__ = AUTHOR
+__license__ = LICENSE
+
+__all__ = ["__author__", "__license__", "__version__"]

pluto_siege/__main__.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+# PlutoSiege - RF capture and replay tool for PlutoSDR.
+# Copyright (C) 2026 SketchTurnerDev
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Entry point for ``python3 -m pluto_siege``."""
+
+from pluto_siege.ui.screens.main_menu import main
+
+if __name__ == "__main__":
+    main()

pluto_siege/config.py

@@ -0,0 +1,249 @@
+# PlutoSiege - RF capture and replay tool for PlutoSDR.
+# Copyright (C) 2026 SketchTurnerDev
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Configuration management using a validated dataclass."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import tempfile
+from dataclasses import asdict, dataclass, fields
+from typing import Any
+
+from pluto_siege.constants import (
+    AUTO_MARGIN_RANGE,
+    CONFIG_FILE,
+    FREQ_RANGE_EXTENDED,
+    FREQ_RANGE_IN_SPEC,
+    POST_TRIGGER_RANGE,
+    PRE_TRIGGER_RANGE,
+    RX_BUFFER_RANGE,
+    RX_GAIN_RANGE,
+    SAMPLE_RATE_RANGE,
+    SILENCE_RANGE,
+    THRESHOLD_RANGE,
+    TX_GAIN_RANGE,
+)
+
+
+def _ip_endpoint(uri: object) -> str | None:
+    """Extract the host/IP part from an 'ip:...' URI, or None if not an IP URI."""
+    if isinstance(uri, str) and uri.startswith("ip:"):
+        return uri[3:].strip()
+    return None
+
+
+@dataclass
+class AppConfig:
+    """Application configuration with range validation and atomic persistence."""
+
+    pluto_uri: str = "usb:"
+    pluto_ip: str = "192.168.2.1"
+    rx_freq: int = 433_920_000
+    tx_freq: int = 433_920_000
+    sample_rate: int = 2_100_000
+    rx_gain: float = 15.0
+    tx_gain: float = 0.0
+    rx_buffer_size: int = 32768
+    auto_threshold: bool = True
+    auto_trigger_margin: float = 8.0
+    manual_threshold: float = -30.0
+    pre_trigger_buffers: int = 2
+    silence_seconds: float = 0.8
+    max_post_trigger_seconds: float = 4.0
+    permit_out_of_spec_frequency: bool = False
+    enable_mouse: bool = True
+    enable_sound: bool = True
+    enable_gps: bool = False
+    gpsd_host: str = "127.0.0.1"
+    gpsd_port: int = 2947
+
+    def __post_init__(self) -> None:
+        endpoint = _ip_endpoint(self.pluto_uri)
+        if endpoint:
+            self.pluto_ip = endpoint
+
+    def update(self, new_values: dict[str, Any]) -> None:
+        """Validate and apply known configuration keys in place."""
+        if not isinstance(new_values, dict):
+            return
+        valid_keys = {f.name for f in fields(self)}
+        known = {k: v for k, v in new_values.items() if k in valid_keys}
+        if not known:
+            return
+
+        candidate = self.to_dict()
+        candidate.update(known)
+        if (
+            "pluto_ip" in known
+            and "pluto_uri" not in known
+            and self.pluto_uri.startswith("ip:")
+            and isinstance(known["pluto_ip"], str)
+            and known["pluto_ip"].strip()
+        ):
+            candidate["pluto_uri"] = f"ip:{known['pluto_ip'].strip()}"
+
+        validated = validate_config(candidate)
+        for f in fields(self):
+            setattr(self, f.name, getattr(validated, f.name))
+
+    def to_dict(self) -> dict[str, Any]:
+        values = asdict(self)
+        endpoint = _ip_endpoint(values["pluto_uri"])
+        if endpoint:
+            values["pluto_ip"] = endpoint
+        elif endpoint == "" and isinstance(values["pluto_ip"], str):
+            ip = values["pluto_ip"].strip()
+            if ip:
+                values["pluto_uri"] = f"ip:{ip}"
+        return values
+
+    @property
+    def freq_bounds(self) -> tuple[int, int]:
+        return (
+            FREQ_RANGE_EXTENDED
+            if self.permit_out_of_spec_frequency
+            else FREQ_RANGE_IN_SPEC
+        )
+
+
+def validate_config(raw: dict[str, Any]) -> AppConfig:
+    """Validate raw dictionary and return an AppConfig instance.
+
+    Invalid individual fields fall back to their defaults so a partially edited
+    settings file preserves all valid values.
+    """
+    cfg = AppConfig()
+    if not isinstance(raw, dict):
+        return cfg
+
+    uri = raw.get("pluto_uri")
+    if isinstance(uri, str) and uri.strip():
+        cfg.pluto_uri = uri.strip()
+
+    raw_ip = raw.get("pluto_ip")
+    saved_ip = raw_ip.strip() if isinstance(raw_ip, str) and raw_ip.strip() else None
+    endpoint = _ip_endpoint(cfg.pluto_uri)
+    if endpoint:
+        cfg.pluto_ip = endpoint
+    elif endpoint == "" and saved_ip:
+        cfg.pluto_ip = saved_ip
+        cfg.pluto_uri = f"ip:{saved_ip}"
+    elif saved_ip:
+        cfg.pluto_ip = saved_ip
+
+    for bool_key in (
+        "permit_out_of_spec_frequency",
+        "auto_threshold",
+        "enable_mouse",
+        "enable_sound",
+        "enable_gps",
+    ):
+        val = raw.get(bool_key)
+        if isinstance(val, bool):
+            setattr(cfg, bool_key, val)
+
+    host = raw.get("gpsd_host")
+    if isinstance(host, str) and host.strip():
+        cfg.gpsd_host = host.strip()
+
+    def check_num(key: str, limits: tuple[float, float], cast_type: type) -> None:
+        val = raw.get(key)
+        if isinstance(val, bool) or not isinstance(val, (int, float)):
+            return
+        try:
+            num = float(val)
+        except (OverflowError, ValueError):
+            return
+        if not math.isfinite(num) or not (limits[0] <= num <= limits[1]):
+            return
+        if cast_type is int:
+            if num.is_integer():
+                setattr(cfg, key, int(num))
+        else:
+            setattr(cfg, key, num)
+
+    freq_range = cfg.freq_bounds
+    check_num("rx_freq", freq_range, int)
+    check_num("tx_freq", freq_range, int)
+    check_num("sample_rate", SAMPLE_RATE_RANGE, int)
+    check_num("rx_gain", RX_GAIN_RANGE, float)
+    check_num("tx_gain", TX_GAIN_RANGE, float)
+    check_num("rx_buffer_size", RX_BUFFER_RANGE, int)
+    check_num("pre_trigger_buffers", PRE_TRIGGER_RANGE, int)
+    check_num("silence_seconds", SILENCE_RANGE, float)
+    check_num("max_post_trigger_seconds", POST_TRIGGER_RANGE, float)
+    check_num("manual_threshold", THRESHOLD_RANGE, float)
+    check_num("auto_trigger_margin", AUTO_MARGIN_RANGE, float)
+    check_num("gpsd_port", (1, 65535), int)
+
+    return cfg
+
+
+def load_settings() -> AppConfig:
+    """Load and validate settings from CONFIG_FILE, or return defaults."""
+    if os.path.exists(CONFIG_FILE):
+        try:
+            with open(CONFIG_FILE, encoding="utf-8") as f:
+                return validate_config(json.load(f))
+        except (
+            json.JSONDecodeError,
+            OSError,
+            UnicodeDecodeError,
+            ValueError,
+            RecursionError,
+        ):
+            pass
+    return AppConfig()
+
+
+def save_settings(config: AppConfig | None = None) -> bool:
+    """Atomically write configuration to CONFIG_FILE."""
+    target = CONFIG if config is None else config
+    tmp_path: str | None = None
+    try:
+        payload = json.dumps(target.to_dict(), indent=2, allow_nan=False)
+        directory = os.path.dirname(os.path.abspath(CONFIG_FILE))
+        os.makedirs(directory, exist_ok=True)
+        fd, tmp_path = tempfile.mkstemp(
+            prefix=".settings-", suffix=".tmp", dir=directory
+        )
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(payload)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_path, CONFIG_FILE)
+        tmp_path = None
+        return True
+    except (OSError, TypeError, ValueError, AttributeError):
+        return False
+    finally:
+        if tmp_path is not None:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+
+
+def freq_bounds(cfg: AppConfig | None = None) -> tuple[int, int]:
+    """Return active frequency limits for the given or global configuration."""
+    return (CONFIG if cfg is None else cfg).freq_bounds
+
+
+DEFAULT_SETTINGS = AppConfig().to_dict()
+CONFIG = load_settings()

pluto_siege/constants.py

@@ -0,0 +1,132 @@
+# PlutoSiege - RF capture and replay tool for PlutoSDR.
+# Copyright (C) 2026 SketchTurnerDev
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Hardware limits, detection tuning, and application-wide constants."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+AUTHOR = "SketchTurnerDev"  # recorded in SigMF metadata as core:author
+VERSION = "2.0.1"
+LICENSE = "GPL-3.0-or-later"
+LICENSE_SHORT = "GNU GPLv3"
+
+_REPO_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if os.path.exists(os.path.join(_REPO_DIR, "pyproject.toml")):
+    BASE_DIR = _REPO_DIR
+else:
+    BASE_DIR = os.path.join(os.path.expanduser("~"), ".pluto_siege")
+
+CONFIG_FILE = os.path.join(BASE_DIR, "settings.json")
+RECORDS_DIR = os.path.join(BASE_DIR, "recordings")
+
+# ---------------------------------------------------------------------------
+# Hardware limits and sample accounting
+# ---------------------------------------------------------------------------
+
+# AD9363 datasheet range, and the wider range the silicon usually tunes to.
+FREQ_RANGE_IN_SPEC = (325_000_000, 3_800_000_000)
+FREQ_RANGE_EXTENDED = (70_000_000, 6_000_000_000)
+
+# Lower bound is pyadi-iio's hard limit: its sample_rate setter raises below
+# 521 kSPS and loads a matching FIR decimation filter below ~2.083 MSPS.
+SAMPLE_RATE_RANGE = (521_000, 61_440_000)
+RX_GAIN_RANGE = (0.0, 74.5)
+TX_GAIN_RANGE = (-89.75, 0.0)
+RX_BUFFER_RANGE = (1024, 32768)
+MAX_RF_BW = 20_000_000
+
+# AD936x fractional-N PLL and BBPLL divider rounding tolerances on readback.
+LO_TOLERANCE_HZ = 10_000
+SR_TOLERANCE_HZ = 1_000
+
+# Stock Pluto delivers 12-bit samples sign-extended into 16-bit words (2**11).
+RX_FULL_SCALE = 2048.0
+
+# TX samples are handed to the DAC as int16; ADI caps amplitude at 2**14 - 1
+# with backoff to leave headroom in the interpolating TX filter chain.
+TX_DAC_MAX = 2**14 - 1
+TX_BACKOFF = 0.8
+
+# Samples are held as complex64 (SigMF "cf32_le"): 2 x float32.
+BYTES_PER_SAMPLE = 8
+RAM_SAFETY_FACTOR = 2
+MAX_RAM_BYTES = 512 * 1024 * 1024
+MAX_TX_BURST_SAMPLES = 16 * 1024 * 1024
+TX_DRAIN_MARGIN_SECONDS = 0.30
+
+# Bound blocking libiio transfers so a stalled link fails instead of hanging.
+IO_TIMEOUT_MIN_MS = 5_000
+IO_TIMEOUT_FACTOR = 10
+IO_TIMEOUT_UNAVAILABLE = "No I/O timeout: a stalled link cannot be interrupted."
+
+# ---------------------------------------------------------------------------
+# Detection tuning
+# ---------------------------------------------------------------------------
+
+DETECT_SUB_WINDOW = 512
+NF_PERCENTILE = 25
+NF_PROBE_BUFFERS = 10
+TRIGGER_MARGIN_DB = 8.0
+RELEASE_MARGIN_DB = 3.0
+MANUAL_RELEASE_DROP_DB = 5.0
+MIN_TRIGGER_SUB_WINDOWS = 2
+RX_FLUSH_BUFFERS = 3
+SATURATION_MARGIN = 0.98
+DB_EPSILON = 1e-12
+
+# ---------------------------------------------------------------------------
+# Settings ranges
+# ---------------------------------------------------------------------------
+
+PRE_TRIGGER_RANGE = (1, 20)
+SILENCE_RANGE = (0.1, 5.0)
+POST_TRIGGER_RANGE = (0.5, 10.0)
+THRESHOLD_RANGE = (-120.0, 0.0)
+AUTO_MARGIN_RANGE = (1.0, 30.0)
+
+# ---------------------------------------------------------------------------
+# Loopback test
+# ---------------------------------------------------------------------------
+
+LOOPBACK_TONE_HZ = 100_000.0
+LOOPBACK_TONE_BINS = 10
+LOOPBACK_TX_AMPLITUDE = 0.6
+LOOPBACK_MIN_SNR_DB = 10.0
+
+# ---------------------------------------------------------------------------
+# Logo
+# ---------------------------------------------------------------------------
+
+LOGO_LINES = [
+    r"     ____  __      __       _____ _                ",
+    r"    / __ \/ /_  __/ /_____ / ___/(_)__  ____ ____  ",
+    r"   / /_/ / / / / / __/ __ \\__ \/ / _ \/ __ `/ _ \ ",
+    r"  / ____/ / /_/ / /_/ /_/ /__/ / /  __/ /_/ /  __/ ",
+    r" /_/   /_/\__,_/\__/\____/____/_/\___/\__, /\___/  ",
+    r"                                     /____/        ",
+    f" {AUTHOR} v{VERSION} ({LICENSE_SHORT})",
+]
+
+
+def brief(text: Any, limit: int = 18) -> str:
+    """Shorten a variable fragment so the line it lands in fits error displays."""
+    limit = max(1, limit)
+    cleaned = "".join(ch if ch.isprintable() else " " for ch in str(text))
+    flat = " ".join(cleaned.split())
+    return flat if len(flat) <= limit else flat[: limit - 1] + "~"