remoterf-device-core 0.1.0__tar.gz

remoterf_device_core-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: remoterf-device-core
+Version: 0.1.0
+Summary: RemoteRF device protocol, IDL and built-in driver schemas shared by the lab Server and Host
+License: GPL-3.0-or-later
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio<2.0.0,>=1.78.1
+Requires-Dist: protobuf<7.0.0,>=6.31.1
+Requires-Dist: numpy
+Requires-Dist: prompt_toolkit
+Provides-Extra: direct
+Requires-Dist: aioice<0.11,>=0.10; extra == "direct"
+Requires-Dist: aioquic<2.0,>=1.2; extra == "direct"
+
+# remoterf-device-core
+
+The parts of RemoteRF that a lab Server (`remoteRF-server`) and a Host (`remoterf-host`) share, kept as one copy:
+
+- the gRPC protocol (`grpc.proto`, `grpc_host.proto`) and the Dynamic v2 codec;
+- the device IDL (`DeviceSchema`, `idl_expose`, `idl_register`) and the schema v2 builder;
+- the built-in driver schemas: ADALM-Pluto (incl. PoE), Pluto MIMO, HackRF, RTL-SDR, TI mmWave, USRP and USRP Phaser;
+- `schemas.json`, the built-in drivers' schema hashes, and `schema_digest()`, the one hash rule;
+- the ICE/QUIC helpers for direct device paths (install with the `direct` extra).
+
+Server and Host pin the same version, so a host running a built-in driver reports exactly the hash its lab knows.
+
+License: GPL-3.0-or-later.

remoterf_device_core-0.1.0/README.md

@@ -0,0 +1,13 @@
+# remoterf-device-core
+
+The parts of RemoteRF that a lab Server (`remoteRF-server`) and a Host (`remoterf-host`) share, kept as one copy:
+
+- the gRPC protocol (`grpc.proto`, `grpc_host.proto`) and the Dynamic v2 codec;
+- the device IDL (`DeviceSchema`, `idl_expose`, `idl_register`) and the schema v2 builder;
+- the built-in driver schemas: ADALM-Pluto (incl. PoE), Pluto MIMO, HackRF, RTL-SDR, TI mmWave, USRP and USRP Phaser;
+- `schemas.json`, the built-in drivers' schema hashes, and `schema_digest()`, the one hash rule;
+- the ICE/QUIC helpers for direct device paths (install with the `direct` extra).
+
+Server and Host pin the same version, so a host running a built-in driver reports exactly the hash its lab knows.
+
+License: GPL-3.0-or-later.

remoterf_device_core-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "remoterf-device-core"
+version = "0.1.0"
+description = "RemoteRF device protocol, IDL and built-in driver schemas shared by the lab Server and Host"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "GPL-3.0-or-later"}
+dependencies = [
+  "grpcio>=1.78.1,<2.0.0",
+  "protobuf>=6.31.1,<7.0.0",
+  "numpy",
+  "prompt_toolkit",
+]
+
+[project.optional-dependencies]
+direct = [
+  "aioice>=0.10,<0.11",
+  "aioquic>=1.2,<2.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+remoterf_device_core = ["schemas.json", "grpc/*.proto"]

remoterf_device_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

remoterf_device_core-0.1.0/src/remoterf_device_core/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (C) 2026 RemoteRF
+#
+# 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/>.

remoterf_device_core-0.1.0/src/remoterf_device_core/digest.py

@@ -0,0 +1,23 @@
+# Copyright (C) 2026 RemoteRF
+#
+# 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/>.
+
+import hashlib
+import json
+
+
+def schema_digest(body: dict) -> str:
+    """The one schema hash rule: sha256 of the canonical JSON body (no schema_hash in it)."""
+    canon = json.dumps(body, sort_keys=True, separators=(",", ":"))
+    return f"sha256:{hashlib.sha256(canon.encode('utf-8')).hexdigest()}"

remoterf_device_core-0.1.0/src/remoterf_device_core/direct.py

@@ -0,0 +1,180 @@
+# Copyright (C) 2026 RemoteRF
+#
+# 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/>.
+
+"""Shared ICE and QUIC primitives for RemoteRF direct paths."""
+
+from __future__ import annotations
+
+import asyncio
+import collections
+import ipaddress
+import os
+import socket
+from typing import Optional
+
+from aioice import Connection
+from aioquic.asyncio.protocol import QuicConnectionProtocol
+from aioquic.quic import events
+
+ALPN = "remoterf-direct/1"
+MAX_FRAME = 100 * 1024 * 1024
+DEFAULT_STUN = "stun.l.google.com:19302"
+STUN_SECONDS = 1.5
+
+
+async def close_ice(ice) -> None:
+    """Close an aioice Connection without its after-close retry noise."""
+    checks = [pair.task for pair in list(getattr(ice, "_check_list", [])) if pair.task is not None]
+    for task in checks:
+        task.cancel()
+    if checks:
+        await asyncio.gather(*checks, return_exceptions=True)
+    for protocol in list(getattr(ice, "_protocols", [])):
+        for transaction in list(getattr(protocol, "transactions", {}).values()):
+            handle = getattr(transaction, "_Transaction__timeout_handle", None)
+            if handle is not None:
+                handle.cancel()
+    await ice.close()
+
+
+async def cancel_tasks(tasks) -> None:
+    """Cancel these tasks and wait for them to finish."""
+    current = asyncio.current_task()
+    tasks = [task for task in tasks if task is not None and task is not current and not task.done()]
+    for task in tasks:
+        task.cancel()
+    if tasks:
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+
+def quiet_aioice_errors(loop) -> None:
+    """Suppress expected aioice retry errors after a socket is closed."""
+    default = loop.default_exception_handler
+
+    def handler(loop, context):
+        exc = context.get("exception")
+        where = repr(context.get("handle", "")) + str(context.get("message", ""))
+        if isinstance(exc, (AttributeError, OSError)) and "Transaction.__retry" in where:
+            return
+        default(context)
+
+    loop.set_exception_handler(handler)
+
+
+def frame(payload: bytes) -> bytes:
+    return len(payload).to_bytes(4, "big") + payload
+
+
+async def read_frame(reader: asyncio.StreamReader) -> bytes:
+    size = int.from_bytes(await reader.readexactly(4), "big")
+    if size > MAX_FRAME:
+        raise ValueError(f"frame of {size} bytes exceeds {MAX_FRAME}")
+    return await reader.readexactly(size)
+
+
+def default_route_address() -> Optional[str]:
+    """The IPv4 address the default route leaves from, or None without one."""
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as probe:
+            probe.connect(("8.8.8.8", 80))
+            return probe.getsockname()[0]
+    except OSError:
+        return None
+
+
+def stun_server(address: Optional[str] = None) -> Optional[tuple[str, int]]:
+    """The configured STUN endpoint, unless the server is publicly addressed."""
+    value = os.getenv("REMOTERF_STUN_SERVER", DEFAULT_STUN).strip()
+    if value.lower() in {"", "off", "none", "0"}:
+        return None
+    if address is not None and ipaddress.ip_address(address).is_global:
+        return None
+    host, _, port = value.rpartition(":")
+    return host, int(port)
+
+
+class Ice(Connection):
+    """aioice Connection restricted to the default-route interface."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.heard = asyncio.Event()
+
+    async def gather_candidates(self) -> None:
+        address = default_route_address()
+        if address is None or self._local_candidates_start:
+            return await super().gather_candidates()
+        self._local_candidates_start = True
+        self._local_candidates += await self.get_component_candidates(
+            component=1, addresses=[address], timeout=STUN_SECONDS
+        )
+        self._local_candidates_end = True
+
+    def request_received(self, *args) -> None:
+        super().request_received(*args)
+        self.heard.set()
+
+
+def peer_address(ice: Connection) -> tuple[str, int]:
+    """The remote end of aioice's nominated pair."""
+    return ice._nominated[1].remote_addr
+
+
+class _IceTransport:
+    """The sendto() surface aioquic's protocol needs on a nominated pair."""
+
+    def __init__(self, ice: Connection):
+        self._ice = ice
+        self._loop = asyncio.get_running_loop()
+        self._queue: collections.deque[bytes] = collections.deque()
+        self._pump: Optional[asyncio.Task] = None
+        self._closed = False
+
+    def sendto(self, data: bytes, addr=None) -> None:
+        if self._closed:
+            return
+        self._queue.append(data)
+        if self._pump is None:
+            self._pump = self._loop.create_task(self._drain())
+
+    def close(self) -> None:
+        self._closed = True
+        self._queue.clear()
+
+    async def _drain(self) -> None:
+        try:
+            while self._queue:
+                await self._ice.sendto(self._queue.popleft(), 1)
+        except ConnectionError:
+            self._queue.clear()
+        finally:
+            self._pump = None
+
+
+class _Protocol(QuicConnectionProtocol):
+    """aioquic protocol which remembers why the connection ended."""
+
+    terminated = ""
+
+    def quic_event_received(self, event) -> None:
+        if isinstance(event, events.ConnectionTerminated):
+            self.terminated = event.reason_phrase or (
+                f"QUIC error {event.error_code:#x}" if event.error_code else ""
+            )
+        super().quic_event_received(event)
+
+
+IceTransport = _IceTransport
+Protocol = _Protocol

remoterf_device_core-0.1.0/src/remoterf_device_core/drivers/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (C) 2026 RemoteRF
+#
+# 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/>.

remoterf_device_core-0.1.0/src/remoterf_device_core/drivers/adalm_pluto/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (C) 2026 RemoteRF
+#
+# 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/>.

remoterf_device_core-0.1.0/src/remoterf_device_core/drivers/adalm_pluto/pluto_mimo_schema.py

@@ -0,0 +1,231 @@
+# Copyright (C) 2026 RemoteRF
+#
+# 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/>.
+
+# SAMPLE schema for ADI Pluto SDR in AD9361 MIMO / 2R2T mode.
+# Place into -> ~/.config/remoterf/drivers and restart server to utilize!
+
+from remoterf_device_core.idl import idl_register, idl_expose
+from remoterf_device_core.drivers.adalm_pluto.pluto_schema import PlutoSchema
+
+import subprocess
+import re
+from pathlib import Path
+
+import adi
+
+
+def _normalize_channels(value, default):
+    if value is None:
+        return list(default)
+    if isinstance(value, str):
+        if not value.strip():
+            return list(default)
+        return [int(part.strip()) for part in value.split(",") if part.strip()]
+    return [int(ch) for ch in value]
+
+
+def _get_attr(device, *names):
+    for name in names:
+        if hasattr(device, name):
+            return getattr(device, name)
+    raise AttributeError(f"{device!r} has none of: {', '.join(names)}")
+
+
+def _set_attr(device, value, *names):
+    for name in names:
+        if hasattr(device, name):
+            setattr(device, name, value)
+            return
+    raise AttributeError(f"{device!r} has none of: {', '.join(names)}")
+
+
+def _apply_initial_settings(device, settings):
+    int_attrs = (
+        "sample_rate",
+        "rx_lo",
+        "tx_lo",
+        "rx_rf_bandwidth",
+        "tx_rf_bandwidth",
+        "rx_buffer_size",
+    )
+    for attr in int_attrs:
+        value = settings.get(attr)
+        if value is not None:
+            setattr(device, attr, int(value))
+
+
+# == PLUTO MIMO Connection Logic ==
+
+def _usb_address_for_port(port):
+    """The libiio usb address (bus.address.interface) now behind a physical
+    USB port path such as "1-2.3" (Linux sysfs)."""
+    base = Path("/sys/bus/usb/devices") / port
+    try:
+        prefix = f"{int((base / 'busnum').read_text())}.{int((base / 'devnum').read_text())}."
+    except (OSError, ValueError):
+        return ""
+    out = subprocess.check_output(["iio_info", "-s"], text=True, stderr=subprocess.STDOUT)
+    for address in re.findall(r"\[usb:([^\]]+)\]", out):
+        if address.startswith(prefix):
+            return address.strip()
+    return ""
+
+
+def connect_pluto_mimo(
+    *,
+    serial="",
+    usb="",
+    usb_port="",
+    rx_enabled_channels=None,
+    tx_enabled_channels=None,
+    initial_settings=None,
+):
+    serial = (serial or "").strip()
+    usb = (usb or "").strip()
+    usb_port = (usb_port or "").strip()
+    if not serial and not usb and not usb_port:
+        print("An adalm_pluto_mimo serial, usb bus address or usb_port must be provided")
+        return None
+
+    try:
+        if usb_port:
+            # A board without a serial keeps its port across re-enumeration;
+            # its bus address does not.
+            usb = _usb_address_for_port(usb_port)
+            if not usb:
+                print(f"No adalm_pluto_mimo device found on USB port {usb_port}")
+                return None
+
+        if not usb:
+            out = subprocess.check_output(
+                ["iio_info", "-s"],
+                text=True,
+                stderr=subprocess.STDOUT,
+            )
+
+            for line in out.splitlines():
+                if (f"serial={serial}" in line) or (f"hw_serial={serial}" in line):
+                    m = re.search(r"\[usb:([^\]]+)\]", line)
+                    if m:
+                        usb = m.group(1).strip()
+                        break
+
+            if not usb:
+                print(f"No adalm_pluto_mimo device found with serial {serial}")
+                return None
+
+        dev = adi.ad9361(f"usb:{usb}")
+        dev.rx_enabled_channels = _normalize_channels(rx_enabled_channels, [0, 1])
+        dev.tx_enabled_channels = _normalize_channels(tx_enabled_channels, [0, 1])
+        _apply_initial_settings(dev, initial_settings or {})
+        from remoterf_device_core.utils.ansi_codes import Sty, printf
+
+        printf(f"Connected to adalm_pluto_mimo serial={serial} via usb:{usb}", Sty.GRAY)
+        return dev
+
+    except Exception as e:
+        from remoterf_device_core.utils.ansi_codes import Sty, printf
+
+        printf(f"Failed to connect to adalm_pluto_mimo serial={serial}: {e}", Sty.GRAY)
+        return None
+
+
+# ========================= PLUTO MIMO Schema =========================
+
+@idl_register("adalm_pluto_mimo")
+class PlutoMIMOSchema(PlutoSchema):
+
+    device_type = "adalm_pluto_mimo"
+    client_class = "PlutoMIMO"
+    driver_version = "0.0.2"
+
+    @staticmethod
+    def make_device(**kwargs):
+        return connect_pluto_mimo(
+            serial=kwargs.get("serial"),
+            usb=kwargs.get("usb"),
+            usb_port=kwargs.get("usb_port"),
+            rx_enabled_channels=kwargs.get("rx_enabled_channels"),
+            tx_enabled_channels=kwargs.get("tx_enabled_channels"),
+            initial_settings=kwargs,
+        )
+
+    # region MIMO channel selection
+
+    @idl_expose(kind="get")
+    def get_mode(self):
+        return "mimo"
+
+    @idl_expose(kind="get")
+    def get_rx_enabled_channels(self):
+        return list(self.device.rx_enabled_channels)
+
+    @idl_expose(kind="set")
+    def set_rx_enabled_channels(self, value):
+        self.device.rx_enabled_channels = _normalize_channels(value, [0, 1])
+
+    @idl_expose(kind="get")
+    def get_tx_enabled_channels(self):
+        return list(self.device.tx_enabled_channels)
+
+    @idl_expose(kind="set")
+    def set_tx_enabled_channels(self, value):
+        self.device.tx_enabled_channels = _normalize_channels(value, [0, 1])
+
+    # endregion
+
+    # region channel 1 controls
+
+    @idl_expose(kind="get")
+    def get_gain_control_mode_chan1(self):
+        return self.device.gain_control_mode_chan1
+
+    @idl_expose(kind="set")
+    def set_gain_control_mode_chan1(self, value):
+        self.device.gain_control_mode_chan1 = value
+
+    @idl_expose(kind="get")
+    def get_rx_hardwaregain_chan1(self):
+        """RX channel 1 hardware gain (dB)."""
+        return _get_attr(self.device, "rx_hardwaregain_chan1", "hardwaregain_chan1")
+
+    @idl_expose(kind="set")
+    def set_rx_hardwaregain_chan1(self, value):
+        """RX channel 1 hardware gain (dB)."""
+        _set_attr(self.device, value, "rx_hardwaregain_chan1", "hardwaregain_chan1")
+
+    @idl_expose(kind="get")
+    def get_tx_hardwaregain_chan1(self):
+        return self.device.tx_hardwaregain_chan1
+
+    @idl_expose(kind="set")
+    def set_tx_hardwaregain_chan1(self, value):
+        self.device.tx_hardwaregain_chan1 = value
+
+    # endregion
+
+    # region AD9361 gain compatibility
+
+    @idl_expose(kind="get")
+    def get_rx_hardwaregain_chan0(self):
+        """RX channel 0 hardware gain (dB)."""
+        return _get_attr(self.device, "rx_hardwaregain_chan0", "hardwaregain_chan0")
+
+    @idl_expose(kind="set")
+    def set_rx_hardwaregain_chan0(self, value):
+        """RX channel 0 hardware gain (dB)."""
+        _set_attr(self.device, value, "rx_hardwaregain_chan0", "hardwaregain_chan0")
+
+    # endregion