Firmware updates: find, download, assemble, flash

README.md

@@ -40,7 +40,7 @@ The following radios should work with this library:
 
 - BTech UV-Pro
 - RadioOddity GA-5WB
-- Vero VR-N76 (untested)
+- Vero VR-N76
 - Vero VR-N7500 (untested)
 - BTech GMRS-Pro (untested)
 
@@ -93,7 +93,8 @@ Benlink has already begun to inspire other projects! Here are some that I know
 of so far:
 
 - [HTCommander](https://github.com/Ylianst/HTCommander)
-- [flutter\_benlink](https://github.com/SarahRoseLives/flutter_benlink)
+- [flutter_benlink](https://github.com/SarahRoseLives/flutter_benlink)
+- [OpenHT](https://github.com/repins267/repins267-OpenHT)
 
 If you've found benlink's documentation of the Benshi protocol helpful, or use
 benlink in your own project, please let me know so I can add it to this list.
@@ -113,9 +114,6 @@ Things to do:
 - [ ] Make a higher-level interface for sending / receiving TNC data (auto
       retry, queue message fragments)
       ([issue](https://github.com/khusmann/benlink/issues/1))
-- [ ] Figure out firmware flashing process / protocol (this is key for long-term
-      independence from the HT app)
-      ([issue](https://github.com/khusmann/benlink/issues/10))
 - [ ] Implement more commands and settings
 - [ ] Find more radios that use this protocol and test them with this library
 
@@ -126,6 +124,13 @@ receive
 
 [@na7q](https://github.com/na7q) for early testing and feedback
 
+[@Ylianst](https://github.com/Ylianst) for a steady stream of protocol findings
+and sharp questions along the way
+
+[@repins267](https://github.com/repins267) for turning my notes on the firmware
+protocol into a complete proof of concept for flashing, working out the gRPC
+update check, and having the guts to do the first flash.
+
 ## Disclaimer
 
 This project is an independent grassroots effort, and is **not** affiliated with

pyproject.toml

@@ -25,9 +25,18 @@ classifiers = [
 ]
 requires-python = ">=3.10"
 
+[project.optional-dependencies]
+firmware = [
+    "bsdiff4 >=1.2.0",
+    "grpcio >=1.60.0",
+]
+
 [project.urls]
 "Homepage" = "https://github.com/khusmann/benlink"
 "Bug Tracker" = "https://github.com/khusmann/benlink/issues"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

src/benlink/__init__.py

@@ -33,7 +33,7 @@
 
 - BTech UV-Pro
 - RadioOddity GA-5WB
-- Vero VR-N76 (untested)
+- Vero VR-N76
 - Vero VR-N7500 (untested)
 - BTech GMRS-Pro (untested)
 
@@ -86,7 +86,8 @@ async def main():
 of so far:
 
 - [HTCommander](https://github.com/Ylianst/HTCommander)
-- [flutter\_benlink](https://github.com/SarahRoseLives/flutter_benlink)
+- [flutter_benlink](https://github.com/SarahRoseLives/flutter_benlink)
+- [OpenHT](https://github.com/repins267/repins267-OpenHT)
 
 If you've found benlink's documentation of the Benshi protocol helpful, or use
 benlink in your own project, please let me know so I can add it to this list.
@@ -106,9 +107,6 @@ async def main():
 - [ ] Make a higher-level interface for sending / receiving TNC data (auto
       retry, queue message fragments)
       ([issue](https://github.com/khusmann/benlink/issues/1))
-- [ ] Figure out firmware flashing process / protocol (this is key for long-term
-      independence from the HT app)
-      ([issue](https://github.com/khusmann/benlink/issues/10))
 - [ ] Implement more commands and settings
 - [ ] Find more radios that use this protocol and test them with this library
 
@@ -119,6 +117,13 @@ async def main():
 
 [@na7q](https://github.com/na7q) for early testing and feedback
 
+[@Ylianst](https://github.com/Ylianst) for a steady stream of protocol findings
+and sharp questions along the way
+
+[@repins267](https://github.com/repins267) for turning my notes on the firmware
+protocol into a complete proof of concept for flashing, working out the gRPC
+update check, and having the guts to do the first flash.
+
 # Disclaimer
 
 This project is an independent grassroots effort, and is **not** affiliated with
@@ -131,5 +136,6 @@ async def main():
 from . import controller
 from . import command
 from . import audio
+from . import firmware
 
-__all__ = ['controller', 'command', 'audio']
+__all__ = ['controller', 'command', 'audio', 'firmware']

src/benlink/command.py

@@ -35,8 +35,9 @@
 from __future__ import annotations
 import typing as t
 import asyncio
-from pydantic import BaseModel, ConfigDict
+import contextlib
 from . import protocol as p
+from .common import ImmutableBaseModel
 from .link import CommandLink, BleCommandLink, RfcommCommandLink
 from datetime import datetime
 
@@ -82,6 +83,36 @@ async def send_bytes(self, data: bytes) -> None:
     async def send_message(self, command: CommandMessage) -> None:
         await self._link.send(command_message_to_protocol(command))
 
+    async def send_protocol_message(self, msg: p.Message) -> None:
+        """Send a raw protocol message.
+
+        For messages with no `CommandMessage` equivalent. Not the same as
+        `send_bytes`: the Rfcomm link wraps what it sends in a `GaiaFrame`.
+        """
+        await self._link.send(msg)
+
+    @contextlib.asynccontextmanager
+    async def subscribe(
+        self,
+        match: t.Callable[[RadioMessage], bool] | None = None,
+    ) -> t.AsyncGenerator[asyncio.Queue[RadioMessage], None]:
+        """Collect matching messages into a queue while the context is held.
+
+        Enter this before sending whatever provokes the replies, so that a reply
+        arriving faster than the next `await` isn't dropped.
+        """
+        queue: asyncio.Queue[RadioMessage] = asyncio.Queue()
+
+        def handler(msg: RadioMessage) -> None:
+            if match is None or match(msg):
+                queue.put_nowait(msg)
+
+        remove_handler = self._add_message_handler(handler)
+        try:
+            yield queue
+        finally:
+            remove_handler()
+
     async def send_message_expect_reply(self, command: CommandMessage, expect: t.Type[RadioMessageT]) -> RadioMessageT | MessageReplyError:
         queue: asyncio.Queue[RadioMessageT |
                              MessageReplyError] = asyncio.Queue()
@@ -241,13 +272,6 @@ async def __aexit__(
         await self.disconnect()
 
 
-class ImmutableBaseModel(BaseModel):
-    """@private (A base class for immutable data objects)"""
-
-    model_config = ConfigDict(frozen=True)
-    """@private"""
-
-
 def command_message_to_protocol(m: CommandMessage) -> p.Message:
     """@private (Protocol helper)"""
     match m:

src/benlink/common.py

@@ -0,0 +1,16 @@
+"""
+Shared building blocks for benlink's data objects.
+
+Kept separate from `benlink.command` so that modules which don't talk to a radio
+(e.g. `benlink.firmware`) can use them without pulling in the Bluetooth stack.
+"""
+
+from __future__ import annotations
+from pydantic import BaseModel, ConfigDict
+
+
+class ImmutableBaseModel(BaseModel):
+    """@private (A base class for immutable data objects)"""
+
+    model_config = ConfigDict(frozen=True)
+    """@private"""

src/benlink/firmware/__init__.py

@@ -0,0 +1,140 @@
+"""Finding, downloading, assembling and flashing Benshi radio firmware.
+
+# THIS CAN BREAK YOUR RADIO
+
+**Flashing firmware can leave your radio unusable, and nothing in this library can
+undo it.**
+
+# Disclaimer
+
+**Use this at your own risk. I am not responsible for bricking your radio, or for
+any other damage to your equipment.** This module is not endorsed by or affiliated
+with Benshi, Vero, RadioOddity, BTech, or any other company.
+
+# The intended flow
+
+Firmware ships as a shared **base image** plus a per-release **patch** in BSDIFF40
+format; assembling the two yields the image the radio expects. benlink
+redistributes neither, and fetches both on request.
+
+One command walks the whole upgrade, prompting as it goes:
+
+```bash
+python -m benlink.firmware update XX:XX:XX:XX:XX:XX
+```
+
+It reads the product id and installed version from the radio, asks the update
+server for the latest release, downloads the patch and base, assembles them, and
+checks the result against the server's md5. Because the server names both
+artifacts, this path cannot pair a patch with the wrong base.
+
+Add `--rfcomm CHANNEL` for RFCOMM instead of BLE, `--keep DIR` to write somewhere
+durable, `-y` to accept prompts.
+
+Ctrl+C safely aborts a transfer.
+
+# The pieces
+
+Each step is also available alone, for archiving old releases or working away from
+the radio. Everything but `info`, `flash` and `abort` avoids the Bluetooth stack.
+
+```bash
+# which radio is this?
+python -m benlink.firmware info XX:XX:XX:XX:XX:XX
+
+# what is the latest release?
+python -m benlink.firmware check --product UV_PRO
+
+# that release, downloaded and assembled, without a radio
+python -m benlink.firmware fetch --product UV_PRO -o fw.bin
+
+# one artifact at a time, for any version
+python -m benlink.firmware download-patch --version 128 --product UV_PRO -o patch.bin
+python -m benlink.firmware download-base --version original -o base.zip
+
+# combine them offline
+python -m benlink.firmware assemble --base base.zip --patch patch.bin -o fw.bin
+
+# put an image you already have onto the radio
+python -m benlink.firmware flash XX:XX:XX:XX:XX:XX --image fw.bin
+
+# clear an update the radio was left partway through (if you didn't exit cleanly)
+python -m benlink.firmware abort XX:XX:XX:XX:XX:XX
+```
+
+`--product` is a shorthand for the radios in `PRODUCTS`; `--product-id` works for
+any radio, and `info` tells you yours. If yours isn't listed, please
+[open an issue](https://github.com/khusmann/benlink/issues) with what `info`
+reports so it can be added.
+
+# Verification
+
+A BSDIFF40 patch carries no checksum of the base it was built against, so pairing
+a patch with the wrong base **succeeds silently** and produces a corrupt image of
+plausible length. See `BASE_IMAGES` for the known pairings.
+
+The server publishes an md5 of the *assembled* image for the current release, so
+`update` and `fetch` are checked end to end. Older releases have none; for those,
+`assemble --expect-md5` accepts one from elsewhere, such as the `md5sum_tail` in a
+packet capture of an official flash. Every command that writes an image says
+whether it could be verified.
+
+# Notes
+
+The product id comes from `GET_DEV_INFO` (`DeviceInfo.product_id`) and is not
+unique across vendors: the VR-N76 and GA-5WB both report 259.
+`DeviceInfo.firmware_version` shares the update server's numbering, so installed
+and available versions compare directly.
+"""
+
+from ._fetch import (
+    BASE_IMAGES,
+    PRODUCTS,
+    FirmwareBundle,
+    FirmwareInfo,
+    ProgressCallback,
+    UpdateInfo,
+    assemble,
+    check_update,
+    download,
+    download_firmware,
+    extract_base,
+    fetch_firmware,
+    oss_base_url,
+    oss_patch_url,
+    oss_update_info,
+)
+from ._flash import FlashError, FlashResult, abort_update, flash
+
+# Grouped by what you reach for, in the order you reach for it, rather than
+# alphabetically: pdoc lays the documentation page out in exactly this order.
+__all__ = [
+    # Which radios and base images exist
+    "PRODUCTS",
+    "BASE_IMAGES",
+
+    # What a release looks like
+    "FirmwareInfo",
+    "UpdateInfo",
+    "FirmwareBundle",
+    "ProgressCallback",
+
+    # Finding one
+    "check_update",
+    "oss_update_info",
+    "oss_patch_url",
+    "oss_base_url",
+
+    # Downloading and assembling it
+    "fetch_firmware",
+    "download_firmware",
+    "download",
+    "extract_base",
+    "assemble",
+
+    # Putting it on the radio
+    "flash",
+    "abort_update",
+    "FlashResult",
+    "FlashError",
+]