hackrf-proxy-client 0.1.0__tar.gz

hackrf_proxy_client-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+target/
+*.iq
+*.cs8
+captures/
+__pycache__/
+.venv/
+dist/
+*.egg-info/
+uv.lock

hackrf_proxy_client-0.1.0/COPYRIGHT

@@ -0,0 +1,7 @@
+Licensed under the Apache License, Version 2.0
+<LICENSE-APACHE or
+http://www.apache.org/licenses/LICENSE-2.0> or the MIT
+license <LICENSE-MIT or http://opensource.org/licenses/MIT>,
+at your option. All files in the project carrying such
+notice may not be copied, modified, or distributed except
+according to those terms.

hackrf_proxy_client-0.1.0/LICENSE-APACHE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

hackrf_proxy_client-0.1.0/LICENSE-MIT

@@ -0,0 +1,25 @@
+Copyright (c) 2026 Aetf <aetf at unlimited-code dot works>
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

hackrf_proxy_client-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.5
+Name: hackrf-proxy-client
+Version: 0.1.0
+Summary: Async WebSocket client for the hackrf-proxyd network-attached OOK transceiver daemon
+Project-URL: Homepage, https://github.com/Aetf/hackrf-proxy
+Project-URL: Repository, https://github.com/Aetf/hackrf-proxy
+Project-URL: Issues, https://github.com/Aetf/hackrf-proxy/issues
+Project-URL: Changelog, https://github.com/Aetf/hackrf-proxy/blob/main/CHANGELOG.md
+Author-email: Aetf <aetf@unlimited-code.works>
+License-Expression: MIT OR Apache-2.0
+License-File: COPYRIGHT
+License-File: LICENSE-APACHE
+License-File: LICENSE-MIT
+Keywords: hackrf,home-assistant,ook,sdr,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Description-Content-Type: text/markdown
+
+# hackrf-proxy-client
+
+Async Python client for the
+[hackrf-proxyd](https://github.com/Aetf/hackrf-proxy) daemon's WebSocket
+protocol: a reconnecting connection with id-matched replies, `rx_frame` event
+delivery, and availability that follows the radio rather than the socket.
+
+Released in lockstep with the daemon from the same repository; a client is
+compatible with any daemon of the same semver major version, and
+`ProxyClient.is_compatible` reports the check.
+
+```python
+import aiohttp
+from hackrf_proxy_client import ProxyClient
+
+async with aiohttp.ClientSession() as session:
+    client = ProxyClient(session, "radio-host", 8765)
+    await client.async_start()
+    await client.async_wait_connected(timeout=10)
+    await client.async_transmit(frequency=315_000_000, timings=[450, -450, 900])
+    await client.async_stop()
+```
+
+## License
+
+MIT OR Apache-2.0, at your option.

hackrf_proxy_client-0.1.0/README.md

@@ -0,0 +1,26 @@
+# hackrf-proxy-client
+
+Async Python client for the
+[hackrf-proxyd](https://github.com/Aetf/hackrf-proxy) daemon's WebSocket
+protocol: a reconnecting connection with id-matched replies, `rx_frame` event
+delivery, and availability that follows the radio rather than the socket.
+
+Released in lockstep with the daemon from the same repository; a client is
+compatible with any daemon of the same semver major version, and
+`ProxyClient.is_compatible` reports the check.
+
+```python
+import aiohttp
+from hackrf_proxy_client import ProxyClient
+
+async with aiohttp.ClientSession() as session:
+    client = ProxyClient(session, "radio-host", 8765)
+    await client.async_start()
+    await client.async_wait_connected(timeout=10)
+    await client.async_transmit(frequency=315_000_000, timings=[450, -450, 900])
+    await client.async_stop()
+```
+
+## License
+
+MIT OR Apache-2.0, at your option.

hackrf_proxy_client-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hackrf-proxy-client"
+dynamic = ["version"]
+description = "Async WebSocket client for the hackrf-proxyd network-attached OOK transceiver daemon"
+readme = "README.md"
+license = "MIT OR Apache-2.0"
+# Copies of the repository-root files: wheel metadata forbids parent paths.
+license-files = ["LICENSE-MIT", "LICENSE-APACHE", "COPYRIGHT"]
+requires-python = ">=3.12"
+authors = [{ name = "Aetf", email = "aetf@unlimited-code.works" }]
+keywords = ["hackrf", "sdr", "ook", "websocket", "home-assistant"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Framework :: AsyncIO",
+    "Topic :: Home Automation",
+]
+dependencies = ["aiohttp>=3.9"]
+
+[project.urls]
+Homepage = "https://github.com/Aetf/hackrf-proxy"
+Repository = "https://github.com/Aetf/hackrf-proxy"
+Issues = "https://github.com/Aetf/hackrf-proxy/issues"
+Changelog = "https://github.com/Aetf/hackrf-proxy/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-aiohttp>=1.0", "basedpyright>=1.29"]
+
+# The client is versioned in lockstep with the daemon: both come from the
+# repository's vX.Y.Z tag, which release-plz derives from Cargo.toml. The
+# compatibility contract is same-major.
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../.." }
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "D"]
+# D203/D213: incompatible pairs. D401: descriptive-prose docstrings by design.
+ignore = ["D203", "D213", "D401"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.basedpyright]
+typeCheckingMode = "strict"
+# basedpyright's opinions beyond pyright strict; prose-typed code keeps Any at
+# the JSON boundary on purpose.
+reportAny = false
+reportExplicitAny = false
+reportUnusedCallResult = false

hackrf_proxy_client-0.1.0/src/hackrf_proxy_client/__init__.py

@@ -0,0 +1,17 @@
+"""Async WebSocket client for the hackrf-proxyd daemon."""
+
+from .client import (
+    PROTOCOL_VERSION,
+    REQUEST_TIMEOUT,
+    ProxyClient,
+    ProxyError,
+    __version__,
+)
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "REQUEST_TIMEOUT",
+    "ProxyClient",
+    "ProxyError",
+    "__version__",
+]

hackrf_proxy_client-0.1.0/src/hackrf_proxy_client/client.py

@@ -0,0 +1,370 @@
+"""WebSocket client for the hackrf-proxyd daemon.
+
+Thin on purpose: it moves raw OOK timings and knows nothing about any
+appliance. The daemon's protocol is documented in `proxyd/README.md`.
+
+Client and daemon are released from the same repository under one version
+number, and the compatibility contract is semver: a client works with any
+daemon of the same major version. The wire-level `v` field is the daemon's
+own last-resort gate; `is_compatible` is this side's check, from the version
+the daemon reports in its status reply.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import Callable
+from datetime import UTC, datetime
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _package_version
+from typing import Any
+
+import aiohttp
+
+_LOGGER = logging.getLogger(__name__)
+
+try:
+    # `or "0.0.0"` covers a damaged install whose metadata lacks a version.
+    __version__ = _package_version("hackrf-proxy-client") or "0.0.0"
+except PackageNotFoundError:  # running from a checkout, not an install
+    __version__ = "0.0.0"
+
+#: Protocol version this client speaks. The daemon refuses anything else by
+#: name rather than misreading it.
+PROTOCOL_VERSION = 1
+
+
+def _semver_major(version_string: str) -> int | None:
+    """The major component, or None when the string is not a version."""
+    head = version_string.split(".", 1)[0]
+    return int(head) if head.isdigit() else None
+
+
+#: How long to wait for a reply. Generous because a reply arrives when the
+#: transmission is *over*, and the daemon allows up to 30 seconds of air time
+#: per request, plus whatever is queued ahead of it on a shared radio.
+REQUEST_TIMEOUT = 60.0
+
+_INITIAL_BACKOFF = 1.0
+_MAX_BACKOFF = 60.0
+
+
+class ProxyError(Exception):
+    """The daemon refused a request, or could not be reached."""
+
+
+class ProxyClient:
+    """A reconnecting client for one daemon.
+
+    Holds a single connection and multiplexes requests over it. Replies are
+    matched by id, which is not optional: the daemon pushes events at any time,
+    and a transmission's own `device_state` event overtakes its reply.
+    """
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        host: str,
+        port: int,
+        *,
+        on_rx_frame: Callable[[dict[str, Any]], None] | None = None,
+    ) -> None:
+        """Initialize the client."""
+        self._session = session
+        self._url = f"ws://{host}:{port}"
+        self._on_rx_frame = on_rx_frame
+        self._availability_listeners: list[Callable[[bool], None]] = []
+        #: Told about anything the diagnostics show, not only availability.
+        #: The radio moving between idle, receiving and transmitting does not
+        #: change availability at all, so a listener on that alone would show a
+        #: state that only ever updated when something broke.
+        self._update_listeners: list[Callable[[], None]] = []
+
+        self._socket: aiohttp.ClientWebSocketResponse | None = None
+        self._task: asyncio.Task[None] | None = None
+        self._pending: dict[str, asyncio.Future[dict[str, Any]]] = {}
+        self._next_id = 0
+        self._connected = asyncio.Event()
+        self._closing = False
+        #: Board and firmware of the radio, once the daemon has reported them.
+        self.device: str | None = None
+        #: The daemon's own version.
+        self.daemon_version: str | None = None
+
+        #: What the radio was last seen doing: `receiving`, `transmitting`,
+        #: `idle` or `faulted`, and `None` while there is no connection to ask.
+        #: This is the refinement `available` cannot carry — a transmitter that
+        #: is unavailable is either unreachable or broken, and which of the two
+        #: is the entire question when something stops working.
+        self.state: str | None = None
+        #: When the current connection was established, and how many previous
+        #: ones ended. Kept because an intermittent link is invisible from a
+        #: connected socket: the only trace it leaves is how recently this one
+        #: started.
+        self.connected_since: datetime | None = None
+        self.disconnects = 0
+        #: When the receiver last heard anything at all. The one reading that
+        #: says whether the receive path works, rather than whether the daemon
+        #: is answering.
+        self.last_rx_frame: datetime | None = None
+
+    def add_availability_listener(
+        self, listener: Callable[[bool], None]
+    ) -> Callable[[], None]:
+        """Subscribe to availability changes, returning an unsubscribe."""
+        self._availability_listeners.append(listener)
+
+        def unsubscribe() -> None:
+            with contextlib.suppress(ValueError):
+                self._availability_listeners.remove(listener)
+
+        return unsubscribe
+
+    def add_update_listener(self, listener: Callable[[], None]) -> Callable[[], None]:
+        """Subscribe to any observable change, returning an unsubscribe."""
+        self._update_listeners.append(listener)
+
+        def unsubscribe() -> None:
+            with contextlib.suppress(ValueError):
+                self._update_listeners.remove(listener)
+
+        return unsubscribe
+
+    def _notify(self) -> None:
+        for listener in list(self._update_listeners):
+            listener()
+
+    @property
+    def available(self) -> bool:
+        """Whether the daemon is currently connected."""
+        return self._connected.is_set()
+
+    @property
+    def is_compatible(self) -> bool | None:
+        """Whether the daemon's major version matches this client's.
+
+        None while no daemon version has been seen, or when either side's
+        version cannot be parsed — unknown is not the same as incompatible.
+        """
+        if self.daemon_version is None:
+            return None
+        ours = _semver_major(__version__)
+        theirs = _semver_major(self.daemon_version)
+        if ours is None or theirs is None:
+            return None
+        return ours == theirs
+
+    @property
+    def url(self) -> str:
+        """The daemon's WebSocket URL."""
+        return self._url
+
+    async def async_start(self) -> None:
+        """Begin connecting, and keep the connection up."""
+        self._closing = False
+        self._task = asyncio.create_task(self._run())
+
+    async def async_stop(self) -> None:
+        """Disconnect and stop reconnecting."""
+        self._closing = True
+        if self._task is not None:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+            self._task = None
+        if self._socket is not None:
+            await self._socket.close()
+
+    async def async_wait_connected(self, timeout: float) -> None:
+        """Wait for the first successful connection."""
+        async with asyncio.timeout(timeout):
+            await self._connected.wait()
+
+    async def async_status(self) -> dict[str, Any]:
+        """Ask the daemon what state it is in."""
+        return await self._request({"type": "status"})
+
+    async def async_transmit(
+        self,
+        *,
+        frequency: int,
+        timings: list[int],
+        repeat: int = 0,
+        gap_us: int | None = None,
+        output_power: float | None = None,
+    ) -> int:
+        """Transmit OOK timings, returning the air time in microseconds.
+
+        Returns when the transmission is over, not when it is queued.
+        """
+        request: dict[str, Any] = {
+            "type": "transmit",
+            "frequency": frequency,
+            "timings": timings,
+            "repeat": repeat,
+        }
+        if gap_us is not None:
+            request["gap_us"] = gap_us
+        if output_power is not None:
+            # The platform expresses power as a 0..1 fraction; the daemon takes
+            # the radio's own 0..47 dB TX VGA setting.
+            request["txvga_db"] = max(0, min(47, round(output_power * 47)))
+
+        reply = await self._request(request)
+        return int(reply.get("duration_us", 0))
+
+    async def _request(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """Send a request and await the reply that carries its id."""
+        socket = self._socket
+        if socket is None or not self._connected.is_set():
+            raise ProxyError(f"not connected to {self._url}")
+
+        self._next_id += 1
+        request_id = str(self._next_id)
+        message = {"v": PROTOCOL_VERSION, "id": request_id, **payload}
+
+        future: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
+        self._pending[request_id] = future
+        try:
+            await socket.send_json(message)
+            async with asyncio.timeout(REQUEST_TIMEOUT):
+                reply = await future
+        except TimeoutError as err:
+            raise ProxyError(f"{self._url} did not answer in time") from err
+        except aiohttp.ClientError as err:
+            raise ProxyError(f"failed to reach {self._url}: {err}") from err
+        finally:
+            self._pending.pop(request_id, None)
+
+        if reply.get("type") == "error":
+            raise ProxyError(str(reply.get("message", "unspecified error")))
+        return reply
+
+    async def _run(self) -> None:
+        """Keep a connection up, reconnecting with a widening backoff."""
+        backoff = _INITIAL_BACKOFF
+        while not self._closing:
+            try:
+                async with self._session.ws_connect(self._url, heartbeat=30) as socket:
+                    _LOGGER.debug("connected to %s", self._url)
+                    self._socket = socket
+                    backoff = _INITIAL_BACKOFF
+                    await self._read_until_closed(socket)
+            except asyncio.CancelledError:
+                raise
+            except (aiohttp.ClientError, OSError) as err:
+                _LOGGER.debug("connection to %s failed: %s", self._url, err)
+            finally:
+                self._socket = None
+                # Only a connection that was actually established counts as a
+                # drop. Otherwise a daemon that is simply not running yet would
+                # add one per backoff interval and read as a flapping link.
+                if self.connected_since is not None:
+                    self.disconnects += 1
+                self.connected_since = None
+                self.state = None
+                self._set_available(False)
+                self._notify()
+                self._fail_pending(ProxyError(f"disconnected from {self._url}"))
+
+            if self._closing:
+                return
+            await asyncio.sleep(backoff)
+            backoff = min(backoff * 2, _MAX_BACKOFF)
+
+    async def _read_until_closed(self, socket: aiohttp.ClientWebSocketResponse) -> None:
+        """Dispatch messages until the connection ends."""
+        # Only report available once the daemon has actually answered, rather
+        # than when the socket opens: a TCP connection to a wedged daemon would
+        # otherwise look healthy.
+        try:
+            status = await asyncio.wait_for(_first_status(socket), timeout=10)
+        except (TimeoutError, aiohttp.ClientError):
+            _LOGGER.debug("%s did not answer a status request", self._url)
+            return
+        self.device = status.get("device")
+        self.daemon_version = status.get("daemon_version")
+        if self.is_compatible is False:
+            _LOGGER.warning(
+                "%s runs daemon %s, which is a different major version than "
+                "client %s; same-major is the supported pairing",
+                self._url,
+                self.daemon_version,
+                __version__,
+            )
+        self.state = status.get("state")
+        self.connected_since = datetime.now(UTC)
+        self._set_available(True)
+        self._notify()
+
+        async for message in socket:
+            if message.type is not aiohttp.WSMsgType.TEXT:
+                continue
+            try:
+                payload = message.json()
+            except ValueError:
+                _LOGGER.warning("%s sent malformed JSON", self._url)
+                continue
+            self._dispatch(payload)
+
+    def _dispatch(self, payload: dict[str, Any]) -> None:
+        """Route a message to whoever is waiting for it."""
+        request_id = payload.get("id")
+        if request_id is not None and (future := self._pending.get(str(request_id))):
+            if not future.done():
+                future.set_result(payload)
+            return
+
+        kind = payload.get("type")
+        if kind == "rx_frame":
+            self.last_rx_frame = datetime.now(UTC)
+            self._notify()
+            if self._on_rx_frame is not None:
+                self._on_rx_frame(payload)
+        elif kind == "device_state":
+            # The radio can fault while the connection stays up. Availability
+            # follows the radio, because a transmitter that cannot transmit is
+            # not available in any sense a consumer cares about.
+            self.state = payload.get("state")
+            self._set_available(self.state != "faulted")
+            self._notify()
+        elif kind == "error":
+            _LOGGER.warning("%s reported: %s", self._url, payload.get("message"))
+
+    def _set_available(self, available: bool) -> None:
+        if available == self._connected.is_set():
+            return
+        if available:
+            self._connected.set()
+        else:
+            self._connected.clear()
+        for listener in list(self._availability_listeners):
+            listener(available)
+
+    def _fail_pending(self, error: Exception) -> None:
+        for future in self._pending.values():
+            if not future.done():
+                future.set_exception(error)
+        self._pending.clear()
+
+
+async def _first_status(socket: aiohttp.ClientWebSocketResponse) -> dict[str, Any]:
+    """Send one status request and read until its reply arrives.
+
+    Used only during connection setup, where nothing else is in flight yet;
+    events that arrive meanwhile are dropped rather than dispatched, which is
+    harmless because the entity has not been told it is available.
+    """
+    await socket.send_json({"v": PROTOCOL_VERSION, "id": "hello", "type": "status"})
+    async for message in socket:
+        if message.type is not aiohttp.WSMsgType.TEXT:
+            continue
+        try:
+            payload = message.json()
+        except ValueError:
+            continue
+        if payload.get("id") == "hello":
+            return payload
+    raise aiohttp.ClientError("connection closed during handshake")

hackrf_proxy_client-0.1.0/tests/test_client.py

@@ -0,0 +1,167 @@
+"""The client against a scripted daemon, and the cross-language protocol pin."""
+
+# The tests exercise the module's internals on purpose.
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, cast
+
+import aiohttp
+import pytest
+from aiohttp import web
+from aiohttp.pytest_plugin import AiohttpServer
+
+from hackrf_proxy_client import PROTOCOL_VERSION, ProxyClient, ProxyError
+from hackrf_proxy_client.client import _semver_major
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+
+
+def test_protocol_version_matches_the_daemon() -> None:
+    """The Rust and Python ends of the wire declare the same version.
+
+    Same repository, one wire protocol, two declarations — this is the test
+    that keeps them from drifting apart.
+    """
+    wire = (REPO_ROOT / "proxyd" / "src" / "wire.rs").read_text()
+    match = re.search(r"pub const PROTOCOL_VERSION: u32 = (\d+);", wire)
+    assert match is not None, "wire.rs no longer declares PROTOCOL_VERSION"
+    assert int(match.group(1)) == PROTOCOL_VERSION
+
+
+def test_semver_major_parsing() -> None:
+    assert _semver_major("1.2.3") == 1
+    assert _semver_major("0.1.0") == 0
+    assert _semver_major("10.0.0-rc.1") == 10
+    assert _semver_major("unknown") is None
+
+
+class ScriptedDaemon:
+    """Just enough of hackrf-proxyd's WebSocket protocol to exercise the client."""
+
+    def __init__(self, daemon_version: str = "0.0.0") -> None:
+        self.daemon_version = daemon_version
+        self.transmits: list[dict[str, Any]] = []
+        self._socket: web.WebSocketResponse | None = None
+
+    async def handler(self, request: web.Request) -> web.WebSocketResponse:
+        socket = web.WebSocketResponse()
+        await socket.prepare(request)
+        self._socket = socket
+        async for message in socket:
+            if message.type is not aiohttp.WSMsgType.TEXT:
+                continue
+            payload: dict[str, Any] = json.loads(message.data)
+            reply: dict[str, Any] = {"id": payload["id"]}
+            if payload["type"] == "status":
+                reply |= {
+                    "type": "status",
+                    "state": "receiving",
+                    "device": "HackRF One r9",
+                    "daemon_version": self.daemon_version,
+                }
+            elif payload["type"] == "transmit":
+                self.transmits.append(payload)
+                # A transmission's own device_state events overtake its reply
+                # on the real wire; reproduce that so id matching is what the
+                # test exercises, not luck.
+                await socket.send_json({"type": "device_state", "state": "transmitting"})
+                await socket.send_json({"type": "device_state", "state": "receiving"})
+                reply |= {"type": "transmitted", "duration_us": 81_100}
+            await socket.send_json(reply)
+        return socket
+
+    async def push(self, payload: dict[str, Any]) -> None:
+        assert self._socket is not None
+        await self._socket.send_json(payload)
+
+
+async def _connected_client(
+    aiohttp_server: AiohttpServer,
+    daemon: ScriptedDaemon,
+    *,
+    on_rx_frame: Callable[[dict[str, Any]], None] | None = None,
+) -> tuple[ProxyClient, aiohttp.ClientSession]:
+    app = web.Application()
+    app.router.add_get("/", daemon.handler)
+    server = await aiohttp_server(app)
+    # TestServer.port is only partially typed upstream; it is an int once the
+    # server has started, and it has.
+    port = cast(int, server.port)
+    session = aiohttp.ClientSession()
+    client = ProxyClient(session, server.host, port, on_rx_frame=on_rx_frame)
+    await client.async_start()
+    await client.async_wait_connected(timeout=5)
+    return client, session
+
+
+async def test_connects_and_reports_the_daemon(aiohttp_server: AiohttpServer) -> None:
+    daemon = ScriptedDaemon()
+    client, session = await _connected_client(aiohttp_server, daemon)
+    try:
+        assert client.available
+        assert client.state == "receiving"
+        assert client.device == "HackRF One r9"
+        assert client.daemon_version == "0.0.0"
+        assert client.is_compatible is True  # both majors are 0
+    finally:
+        await client.async_stop()
+        await session.close()
+
+
+async def test_transmit_returns_air_time_despite_overtaking_events(
+    aiohttp_server: AiohttpServer,
+) -> None:
+    daemon = ScriptedDaemon()
+    client, session = await _connected_client(aiohttp_server, daemon)
+    try:
+        duration = await client.async_transmit(
+            frequency=315_000_000, timings=[450, -450, 1350], repeat=9
+        )
+        assert duration == 81_100
+        (request,) = daemon.transmits
+        assert request["v"] == PROTOCOL_VERSION
+        assert request["frequency"] == 315_000_000
+        assert request["repeat"] == 9
+    finally:
+        await client.async_stop()
+        await session.close()
+
+
+async def test_rx_frames_reach_the_callback(aiohttp_server: AiohttpServer) -> None:
+    daemon = ScriptedDaemon()
+    heard: list[dict[str, Any]] = []
+    client, session = await _connected_client(aiohttp_server, daemon, on_rx_frame=heard.append)
+    try:
+        await daemon.push({"type": "rx_frame", "frequency": 315_000_000, "timings": [450, -450]})
+        async with asyncio.timeout(5):
+            while not heard:
+                await asyncio.sleep(0.01)
+        assert heard[0]["timings"] == [450, -450]
+        assert client.last_rx_frame is not None
+    finally:
+        await client.async_stop()
+        await session.close()
+
+
+async def test_a_different_major_reads_as_incompatible(aiohttp_server: AiohttpServer) -> None:
+    daemon = ScriptedDaemon(daemon_version="99.0.0")
+    client, session = await _connected_client(aiohttp_server, daemon)
+    try:
+        assert client.is_compatible is False
+    finally:
+        await client.async_stop()
+        await session.close()
+
+
+async def test_requests_fail_cleanly_when_disconnected() -> None:
+    async with aiohttp.ClientSession() as session:
+        client = ProxyClient(session, "localhost", 1)
+        with pytest.raises(ProxyError):
+            await client.async_status()