ria-toolkit-oss/src/ria_toolkit_oss/sdr/__init__.py

"""
This package provides a unified API for working with a variety of software-defined radios.
It streamlines tasks involving signal reception and transmission, as well as common administrative
operations such as detecting and configuring available devices.
"""

__all__ = [
    "SDR",
    "SDRError",
    "SDRParameterError",
    "SdrDisconnectedError",
    "MockSDR",
    "get_sdr_device",
    "detect_available",
]

from .mock import MockSDR
from .sdr import SDR, SDRError, SdrDisconnectedError, SDRParameterError, translate_disconnect  # noqa: F401


_DRIVER_CANDIDATES: tuple[tuple[str, str, str], ...] = (
    ("mock", "ria_toolkit_oss.sdr.mock", "MockSDR"),
    ("pluto", "ria_toolkit_oss.sdr.pluto", "Pluto"),
    ("hackrf", "ria_toolkit_oss.sdr.hackrf", "HackRF"),
    ("rtlsdr", "ria_toolkit_oss.sdr.rtlsdr", "RTLSDR"),
    ("usrp", "ria_toolkit_oss.sdr.usrp", "USRP"),
    ("blade", "ria_toolkit_oss.sdr.blade", "Blade"),
    ("thinkrf", "ria_toolkit_oss.sdr.thinkrf", "ThinkRF"),
)


def detect_available() -> dict[str, type]:
    """Return ``{device_name: driver_class}`` for every driver whose module imports cleanly.

    Importability is a proxy for "the user has installed this driver's optional dependency".
    It does not probe for physical hardware presence — that requires actually instantiating
    the driver, which can be slow and side-effectful.
    """
    import importlib

    out: dict[str, type] = {}
    for name, module_path, cls_name in _DRIVER_CANDIDATES:
        try:
            mod = importlib.import_module(module_path)
            out[name] = getattr(mod, cls_name)
        except Exception:
            continue
    return out


def get_sdr_device(device_type: str, ident: str | None = None, tx: bool = False) -> SDR:
    """Return an SDR instance for *device_type*.

    For ``"mock"`` / ``"sim"`` device types, returns a :class:`MockSDR`
    immediately (no hardware required).  For all real device types, delegates
    to ``ria_toolkit_oss_cli.ria_toolkit_oss.common.get_sdr_device`` if the
    CLI package is installed; otherwise raises ``ImportError`` with a helpful
    message.

    Args:
        device_type: Device name (``"mock"``, ``"pluto"``, ``"usrp"``, …).
        ident: Optional device identifier (IP address, serial number, …).
        tx: If True, require TX capability.
    """
    if device_type in ("mock", "sim"):
        return MockSDR()

    # Delegate real device types to the CLI package which holds the driver
    # imports behind hardware-specific optional dependencies.
    try:
        from ria_toolkit_oss_cli.ria_toolkit_oss.common import (
            get_sdr_device as _cli_get,
        )
    except ImportError as exc:
        raise ImportError(
            f"ria_toolkit_oss_cli is required to use hardware SDR device '{device_type}'. "
            "Install it with: pip install ria-toolkit-oss-cli"
        ) from exc

    return _cli_get(device_type, ident=ident, tx=tx)