RemoteRF 2.2.5__tar.gz → 2.3.0__tar.gz

{remoterf-2.2.5/src/remoterf.egg-info → remoterf-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remoterf
-Version: 2.2.5
+Version: 2.3.0
 Summary: A python API to remotely access signal centric hardware. Client-side only! Courtesy of Wireless Lab @ UCLA & Prof. Ian Roberts.
 Author-email: Ethan Ge <ethoGalaxy@gmail.com>
 License-Expression: GPL-3.0-or-later

{remoterf-2.2.5 → remoterf-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "remoterf"
-version = "2.2.5"
+version = "2.3.0"
 description = "A python API to remotely access signal centric hardware. Client-side only! Courtesy of Wireless Lab @ UCLA & Prof. Ian Roberts."
 readme = "README.md"
 license = "GPL-3.0-or-later"

{remoterf-2.2.5 → remoterf-2.3.0}/src/remoterf/core/app.py

@@ -21,6 +21,7 @@ import getpass
 import os
 import re
 import datetime
+import functools
 import time
 import ast
 from pathlib import Path
@@ -123,6 +124,73 @@ home_name = None
 # The route it was reached over (None on a bare direct profile or an HTTPS home).
 current_route = None
 
+# What each generated driver package exposes, for the usage lines after a reservation.
+DRIVER_CALLS = {"pluto": "adi.Pluto", "adalm_pluto": "adi.Pluto", "usrp": "uhd.usrp.MultiUSRP"}
+_HANDLE_TAG = re.compile(r"^(?P<name>.*) \[(?P<handle>\S+)\]$")  # handles have no whitespace
+_NO_HANDLE = "This device has no handle"
+_UNROUTABLE = "Its handle {} can't be used from here: {}"
+
+
+def _token_lab():
+    """The lab `<token>@<lab>` routes to from here: this shell's home, else the
+    direct profile's (a shell started by --register has no home yet)."""
+    from .grpc_client import _active_home_name
+
+    return home_name or _active_home_name()
+
+
+def _routable(token):
+    """The token as a driver takes it: @<this lab>, so it is never sent elsewhere."""
+    lab = _token_lab()
+    return f"{token}@{lab}" if lab else f"{token}"
+
+
+def _name_and_handle(name):
+    """A listed device name, 'Pluto SDR [PlutoA]' -> ('Pluto SDR', 'PlutoA')."""
+    m = _HANDLE_TAG.match(name)
+    return (m["name"], m["handle"]) if m else (name, None)
+
+
+def _print_reserved(where, when, token, handle, logged_in_to, install, no_handle=_NO_HANDLE):
+    """The token and, when the device has one, its handle (both @<deployment>).
+    Printed before the driver install, which can fail or stall; the usage
+    lines follow it, once the device type is known. `no_handle`: why no
+    handle is shown."""
+    printf("Reservation successful on ", (Sty.BOLD, Sty.GREEN), where, Sty.MAGENTA, " for ", Sty.DEFAULT, f"{when}.", Sty.CYAN)
+    printf("", Sty.DEFAULT)
+    width = len("Device handle") if handle else len("Token")
+    printf(f"  {'Token':<{width}}  ", Sty.BOLD, token, (Sty.BOLD, Sty.GREEN))
+    if handle:
+        printf("  Device handle  ", Sty.BOLD, handle, (Sty.BOLD, Sty.GREEN))
+    printf("", Sty.DEFAULT)
+    if handle:
+        printf("  Token   works anywhere, no login needed. Keep it safe: it can't be shown again.", Sty.DEFAULT)
+        printf(f"  Handle  works while you're logged in to {logged_in_to} and this reservation is active.", Sty.DEFAULT)
+    else:
+        printf("  Works anywhere, no login needed. Keep it safe: it can't be shown again.", Sty.DEFAULT)
+        printf(f"  ({no_handle}. Lost the token? Cancel and reserve again.)", Sty.DEFAULT)
+    printf("", Sty.DEFAULT)
+    call = DRIVER_CALLS.get(install())
+    if call:
+        printf("Use either one as the token:" if handle else "Use it as the token:", Sty.DEFAULT)
+        for text in (token, handle) if handle else (token,):
+            printf(f'  sdr = {call}(token="{text}")', Sty.CYAN)
+
+
+def _print_native_reserved(device_id, label, when, token):
+    """`label` as the server lists the device: 'Pluto SDR [PlutoA] (online)',
+    or a partner lab's 'Pluto SDR @mit (online)' (partner handles: none yet)."""
+    partner = _PARTNER_LABEL.match(label)
+    local = None if partner else _LOCAL_LABEL.match(label)
+    name, handle = (partner["name"], None) if partner else _name_and_handle(local["name"] if local else label)
+    home = _token_lab()
+    lab = partner["lab"] if partner else home
+    name = handle or name or f"device {device_id}"
+    _print_reserved(f"{name} @{lab}" if lab else name, when, _routable(token),
+                    f"{handle}@{home}" if handle and home else None, home,
+                    lambda: account.install_reserved_driver(token, int(device_id)),
+                    _UNROUTABLE.format(handle, "this lab has no saved name") if handle else _NO_HANDLE)
+
 
 def _print_connected(name, home, route):
     """One line, same voice as the banner: what we reached and how."""
@@ -450,6 +518,10 @@ def _render_destinations(entries):
         print()
 
 
+def _handle_tag(dev):
+    return f" [{dev['handle']}]" if dev.get("handle") else ""
+
+
 def _federated_devices():
     data = account.get_devices()
     _render_destinations(data["destinations"])
@@ -466,7 +538,7 @@ def _federated_devices():
             deployment = dev["deployment_name"]
             printf(f"  @{deployment}", (Sty.BOLD, Sty.MAGENTA))
         state = "online" if dev["online"] else "offline"
-        printf("    Device Name: ", Sty.GRAY, f"{dev['display_name']}", Sty.DEFAULT, f" ({dev['device_type'] or 'unknown'}, {state})", Sty.GRAY)
+        printf("    Device Name: ", Sty.GRAY, f"{dev['display_name']}{_handle_tag(dev)}", Sty.DEFAULT, f" ({dev['device_type'] or 'unknown'}, {state})", Sty.GRAY)
     if data.get("incomplete"):
         printf(f"{data['omitted_count']} more deployment(s) were not queried.", Sty.WARNING)
     return data
@@ -546,12 +618,38 @@ def _federated_reservations_for_range(start_day, end_day):
     return res_dict
 
 
-def _federated_reserve_slot(device_id, chosen_day, chosen_slot, slot_start_str, slot_end_str):
-    handle = account.reserve_device(device_id, chosen_slot[0], chosen_slot[1])
-    # Worded as a lab account's reservation; the handle goes where a token goes.
-    printf("Reservation successful on device ", (Sty.BOLD, Sty.GREEN), f"{str(device_id).rsplit(':', 1)[-1]}", Sty.MAGENTA, " for ", Sty.DEFAULT, f"{chosen_day.strftime('%Y-%m-%d')} {slot_start_str}-{slot_end_str}.", Sty.CYAN)
-    printf("Your Token -> ", Sty.BOLD, f"{handle}", (Sty.BOLD, Sty.GREEN))
-    account.install_reserved_driver(handle, device_id)
+def _global_slug(device_id, deployment_name):
+    """The lab's name when it is its own Global slug (checked by discovery),
+    else None: then the bare token, which works as is."""
+    from .grpc_client import _deployment_id
+    from ..deployment.homes import NAME_RE
+
+    name = str(deployment_name or "").lower()
+    try:
+        if NAME_RE.match(name) and _deployment_id(name) == str(device_id).split(":")[0]:
+            return name
+    except RuntimeError:
+        pass
+    return None
+
+
+def _federated_reserve_slot(device_id, chosen_day, chosen_slot, slot_start_str, slot_end_str,
+                            deployment_name=None, device_name=None, device_handle=None):
+    token = account.reserve_device(device_id, chosen_slot[0], chosen_slot[1])
+    when = f"{chosen_day.strftime('%Y-%m-%d')} {slot_start_str}-{slot_end_str}"
+    install = lambda: account.install_reserved_driver(token, device_id)
+    if not token.startswith("rfg_"):
+        # An older Global: the HOME reference goes where a token goes.
+        printf("Reservation successful on device ", (Sty.BOLD, Sty.GREEN), f"{str(device_id).rsplit(':', 1)[-1]}", Sty.MAGENTA, " for ", Sty.DEFAULT, f"{when}.", Sty.CYAN)
+        printf("Your Token -> ", Sty.BOLD, token, (Sty.BOLD, Sty.GREEN))
+        install()
+        return
+    slug = _global_slug(device_id, deployment_name)
+    name = device_handle or device_name or str(device_id).rsplit(":", 1)[-1]
+    lab = slug or deployment_name
+    _print_reserved(f"{name} @{lab}" if lab else name, when, f"{token}@{slug}" if slug else token,
+                    f"{device_handle}@{slug}" if device_handle and slug else None, "RemoteRF Global", install,
+                    _UNROUTABLE.format(device_handle, "this lab's Global name is unknown") if device_handle else _NO_HANDLE)
 
 
 def _federated_reserve():
@@ -572,7 +670,7 @@ def _federated_reserve():
         printf(
             f"{idx}.", Sty.CYAN,
             "  Name: ", Sty.DEFAULT,
-            f"{dev['display_name']}", Sty.GRAY,
+            f"{dev['display_name']}{_handle_tag(dev)}", Sty.GRAY,
             " Duration: ", Sty.DEFAULT,
             f"{dev['block_min']} min", Sty.GREEN,
         )
@@ -594,7 +692,9 @@ def _federated_reserve():
             f" is < 10 minutes (max_sec={dev['max_reservation_time_sec'] or 0}). Cannot create valid reservations.", Sty.DEFAULT,
         )
         return
-    _pick_slot_and_reserve(dev["device_id"], dev["display_name"], dev["block_min"], _federated_reservations_for_range, _federated_reserve_slot,
+    reserve_slot = functools.partial(_federated_reserve_slot, deployment_name=dev["deployment_name"],
+                                     device_name=dev["display_name"], device_handle=dev.get("handle"))
+    _pick_slot_and_reserve(dev["device_id"], dev["display_name"], dev["block_min"], _federated_reservations_for_range, reserve_slot,
                            device_label=f"{dev['display_name']} @{dev['deployment_name']}",
                            max_days=-(-int(dev.get("max_horizon_sec") or 0) // 86400) or None)
 
@@ -747,7 +847,8 @@ def cancel_my_reservation():
         print("Aborting. A non integer key was given.")
 
 _PARTNER_LABEL = re.compile(r"^(?P<name>.*) @(?P<lab>.+?) \((?P<state>[^)]*)\)$")
-_LOCAL_LABEL = re.compile(r"^(?P<name>.*) \((?P<state>[^)]*)\)$")
+# The state always starts with online/offline; a PoE fault after it can hold brackets.
+_LOCAL_LABEL = re.compile(r"^(?P<name>.*?) \((?P<state>(?:online|offline)\b.*)\)$")
 
 
 def _native_device_rows():
@@ -808,7 +909,7 @@ def _print_native_devices(rows, *, numbered=False):
         if row["lab"] != lab:
             lab = row["lab"]
             printf(f"  @{lab}", (Sty.BOLD, Sty.MAGENTA))
-        prefix = (f"{index}.", Sty.CYAN, " ") if numbered else ()
+        prefix = (f"{index}. ", Sty.CYAN) if numbered else ()
         printf(*prefix, "    Device Name: " if not numbered else "  Device Name: ", Sty.GRAY,
                row["name"], Sty.DEFAULT, f" ({row['state']})" if row["state"] else "", Sty.GRAY)
 
@@ -852,11 +953,18 @@ def reserve():
         if not pick.isdigit() or not 1 <= int(pick) <= len(rows):
             printf("Pick a number from the list.", Sty.WARNING)
             return
-        token = account.reserve_device(rows[int(pick) - 1]["id"], get_datetime("Reserve Start Time"), get_datetime("Reserve End Time"))
+        row = rows[int(pick) - 1]
+        start, end = get_datetime("Reserve Start Time"), get_datetime("Reserve End Time")
+        token = account.reserve_device(row["id"], start, end)
         if token != '':
-            printf(f"Reservation successful. Your Token -> ", Sty.BOLD, f"{token}", Sty.BG_GREEN)
-            printf(f"Please keep this token safe, as it is not saved on the server and cannot be retrieved again. If you lose it, cancel your reservation and make a new one. ", Sty.DEFAULT)
-            account.install_reserved_driver(token, rows[int(pick) - 1]["id"])
+            name, handle = (row["name"], None) if row["away"] else _name_and_handle(row["name"])
+            home = _token_lab()
+            lab = row["lab"] if row["away"] else home or row["lab"]
+            _print_reserved(f"{handle or name} @{lab}" if lab else handle or name,
+                            f"{start:%Y-%m-%d %I:%M %p}-{end:%I:%M %p}", _routable(token),
+                            f"{handle}@{home}" if handle and home else None, home,
+                            lambda: account.install_reserved_driver(token, row["id"]),
+                            _UNROUTABLE.format(handle, "this lab has no saved name") if handle else _NO_HANDLE)
     except Exception as e:
         printf(f"Error: {e}", Sty.BRIGHT_RED)
 
@@ -1293,11 +1401,9 @@ def interactive_reserve_next_days(block_minutes=60):
         # --- 6) Reserve the chosen slot on the chosen device ---
         token = account.reserve_device(int(chosen_device_id), chosen_slot[0], chosen_slot[1])
         if token:
-            printf("Reservation successful on device ", (Sty.BOLD, Sty.GREEN), f"{chosen_device_id}", Sty.MAGENTA, " for ", Sty.DEFAULT, f"{chosen_day.strftime('%Y-%m-%d')} {slot_start_str}-{slot_end_str}.", Sty.CYAN)
-            printf("Your Token -> ", Sty.BOLD, f"{token}", (Sty.BOLD, Sty.GREEN))
-            printf("Please keep this token safe, as it is not saved on the server and cannot be retrieved again. If you lose it, cancel your reservation and make a new one.", Sty.DEFAULT)
-            account.install_reserved_driver(token, int(chosen_device_id))
-        
+            _print_native_reserved(chosen_device_id, str(unmap_arg(data.results[chosen_device_id])),
+                                   f"{chosen_day.strftime('%Y-%m-%d')} {slot_start_str}-{slot_end_str}", token)
+
     except Exception as e:
         print(f"Error: {e}")
         
@@ -1413,7 +1519,7 @@ def _pick_slot_and_reserve(chosen_device_id, chosen_device_name, block_minutes,
     slot_end_str = chosen_slot[1].strftime("%I:%M %p")
 
     confirmation = session.prompt(stylize(
-        "Reservation successful on ", Sty.DEFAULT,
+        "Reserve ", Sty.DEFAULT,
         f"{chosen_day.strftime('%Y-%m-%d')}", (Sty.BOLD, Sty.BLUE),
         " from ", Sty.DEFAULT,
         f"{slot_start_str}", Sty.CYAN,
@@ -1421,7 +1527,7 @@ def _pick_slot_and_reserve(chosen_device_id, chosen_device_name, block_minutes,
         f"{slot_end_str}", Sty.CYAN,
         " for ", Sty.DEFAULT,
         f"{chosen_device_name}", Sty.GRAY,
-        ". \nConfirm reservation? (y/n): ", (Sty.BOLD, Sty.GREEN),
+        "?\nConfirm reservation? (y/n): ", (Sty.BOLD, Sty.GREEN),
     )).strip().lower()
 
     if confirmation != "y":
@@ -1434,13 +1540,11 @@ def _pick_slot_and_reserve(chosen_device_id, chosen_device_name, block_minutes,
     do_reserve(chosen_device_id, chosen_day, chosen_slot, slot_start_str, slot_end_str)
 
 
-def _native_reserve_slot(chosen_device_id, chosen_day, chosen_slot, slot_start_str, slot_end_str):
+def _native_reserve_slot(chosen_device_id, chosen_day, chosen_slot, slot_start_str, slot_end_str, device_label=""):
     token = account.reserve_device(int(chosen_device_id), chosen_slot[0], chosen_slot[1])
     if token:
-        printf("Reservation successful on device ", (Sty.BOLD, Sty.GREEN), f"{chosen_device_id}", Sty.MAGENTA, " for ", Sty.DEFAULT, f"{chosen_day.strftime('%Y-%m-%d')} {slot_start_str}-{slot_end_str}.", Sty.CYAN)
-        printf("Your Token -> ", Sty.BOLD, f"{token}", (Sty.BOLD, Sty.GREEN))
-        printf("Please keep this token safe, as it is not saved on the server and cannot be retrieved again. If you lose it, cancel your reservation and make a new one.", Sty.DEFAULT)
-        account.install_reserved_driver(token, int(chosen_device_id))
+        _print_native_reserved(chosen_device_id, device_label,
+                               f"{chosen_day.strftime('%Y-%m-%d')} {slot_start_str}-{slot_end_str}", token)
 
 
 def interactive_reserve_next_days_auto():
@@ -1578,19 +1682,23 @@ def interactive_reserve_next_days_auto():
 
         chosen_device_key = sorted_device_ids[sel_i]
         chosen_device_id = str(chosen_device_key)
-        chosen_device_name = unmap_arg(dev_resp.results[chosen_device_key])
+        chosen_device_name = str(unmap_arg(dev_resp.results[chosen_device_key]))
+        # 'Pluto SDR [PlutoA] (online)' -> 'Pluto SDR [PlutoA]', 'Pluto SDR @mit (online)' -> 'Pluto SDR @mit'
+        shown = _LOCAL_LABEL.match(chosen_device_name)
+        shown = shown["name"] if shown else chosen_device_name
         block_minutes = int(block_by_dev.get(chosen_device_id, 30))
 
         if block_minutes < 10:
             printf(
                 "Your max reservation duration for device ", Sty.DEFAULT,
-                f"{chosen_device_id}", Sty.MAGENTA,
+                shown, Sty.MAGENTA,
                 f" is < 10 minutes (max_sec={max_by_dev.get(chosen_device_id, 0)}). Cannot create valid reservations.", Sty.DEFAULT,
             )
             return
 
-        _pick_slot_and_reserve(chosen_device_id, chosen_device_name, block_minutes, fetch_reservations_for_range, _native_reserve_slot,
-                               max_days=days_by_dev.get(chosen_device_id) or None)
+        _pick_slot_and_reserve(chosen_device_id, shown, block_minutes, fetch_reservations_for_range,
+                               functools.partial(_native_reserve_slot, device_label=chosen_device_name),
+                               device_label=shown, max_days=days_by_dev.get(chosen_device_id) or None)
 
     except Exception as e:
         print(f"Error: {e}")

{remoterf-2.2.5 → remoterf-2.3.0}/src/remoterf/core/dynamic_v2_transport.py

@@ -82,8 +82,9 @@ class _DevicePlaneStub:
     call on that token (the direct path to the owner when it is up, else the
     HOME, which relays it). The owner runs it through its own servicers."""
 
-    def __init__(self, token: str):
+    def __init__(self, token: str, label: str = "partner device: "):
         self._token = str(token)
+        self._label = label
 
     def _rpc(self, operation, request, response_type):
         from ..common.utils import map_arg, unmap_arg
@@ -97,7 +98,7 @@ class _DevicePlaneStub:
         except RuntimeError as exc:
             # A refusal the HOME or the owner carried in "a": no live
             # reservation, a revoked agreement, a device no longer visible.
-            raise RemoteRFReservationError(f"partner device: {exc}") from exc
+            raise RemoteRFReservationError(f"{self._label}{exc}") from exc
         wire = unmap_arg(response.results["wire"]) if "wire" in response.results else None
         if not isinstance(wire, bytes):
             raise RemoteRFProtocolError("partner device plane returned no Dynamic v2 reply")
@@ -131,6 +132,7 @@ class DynamicV2Transport:
         *,
         control_stub=None,
         sample_stub=None,
+        token=None,
         control_timeout_sec: float = 30.0,
         open_timeout_sec: float = 120.0,
         stream_timeout_margin_sec: float = 5.0,
@@ -156,11 +158,18 @@ class DynamicV2Transport:
             )
         self._stream_poisoned = False
         self._stream_failure_details = {}
+        self._renewed = False
         if control_stub is None or sample_stub is None:
-            from .grpc_client import get_active_channel
-            channel = get_active_channel()
-            control_stub = control_stub or grpc_pb2_grpc.DynamicControlV2Stub(channel)
-            sample_stub = sample_stub or grpc_pb2_grpc.SampleDataV1Stub(channel)
+            from .grpc_client import device_route, get_active_channel
+            route = device_route(token) if token is not None else None
+            if route is not None and route.kind == "global":
+                # No device channel through Global: each request is a relayed RPC.
+                plane = _DevicePlaneStub(token, label="")
+                control_stub, sample_stub = control_stub or plane, sample_stub or plane
+            else:
+                channel = route.connection.channel if route and route.connection else get_active_channel()
+                control_stub = control_stub or grpc_pb2_grpc.DynamicControlV2Stub(channel)
+                sample_stub = sample_stub or grpc_pb2_grpc.SampleDataV1Stub(channel)
         self.control = control_stub
         self.samples = sample_stub
 
@@ -168,17 +177,26 @@ class DynamicV2Transport:
         """Carry this transport over the device plane when ``token`` drives a
         partner lab's device (named by the HOME's refusal, or already known)."""
         from . import direct_path
+        from .grpc_client import wire_token
 
         if isinstance(self.control, _DevicePlaneStub):
             return False
-        owner = owner or direct_path.partner_of(str(token))
+        owner = owner or direct_path.partner_of(wire_token(str(token)))
         if not owner:
             return False
         # Marked, the token's device calls take the direct path to the owner.
-        direct_path.mark_partner(str(token), str(owner))
+        direct_path.mark_partner(wire_token(str(token)), str(owner))
         self.control = self.samples = _DevicePlaneStub(token)
         return True
 
+    def _inner_token(self, token: str) -> str:
+        # Over the device plane the owner substitutes its own bridge token, so
+        # no bearer secret ever rides inside a frame.
+        if isinstance(self.control, _DevicePlaneStub):
+            return ""
+        from .grpc_client import wire_token
+        return wire_token(str(token))
+
     def _checked(self, response, token: str) -> bool:
         """raise_for_envelope, except for the refusal of a partner's token:
         True when the call should be repeated over the device plane."""
@@ -188,6 +206,14 @@ class DynamicV2Transport:
             if self._to_owner(token, exc.details.get("federated")):
                 return True
             raise
+        except RemoteRFReservationError as exc:
+            # A dead bridge token behind x@lab: ask the lab again, once.
+            from .grpc_client import device_route, renewed_route
+
+            if self._renewed or renewed_route(str(token), device_route(str(token)), str(exc)) is None:
+                raise
+            self._renewed = True
+            return True
         return False
 
     def _call(self, fn, request, *, timeout: float | None = None):
@@ -229,7 +255,7 @@ class DynamicV2Transport:
         response = self._call(
             self.control.GetSchema,
             grpc_pb2.GetSchemaRequest(
-                token=str(token),
+                token=self._inner_token(token),
                 schema_versions=[SCHEMA_VERSION],
             ),
         )
@@ -254,7 +280,7 @@ class DynamicV2Transport:
         response = self._call(
             self.control.OpenSession,
             grpc_pb2.OpenSessionRequest(
-                token=str(token),
+                token=self._inner_token(token),
                 requested_schema_hash=str(schema_hash),
                 control_protocol_version=CONTROL_PROTOCOL_VERSION,
                 streaming_protocol_version=STREAMING_PROTOCOL_VERSION,

{remoterf-2.2.5 → remoterf-2.3.0}/src/remoterf/core/grpc_acc.py

@@ -101,8 +101,9 @@ class RemoteRFAccount:
         if self.is_https_home:
             with _busy("Reserving…"):
                 reservation = self.backend.reserve(device_id, int(start_time.timestamp()), int(end_time.timestamp()))
-            # The HOME reference is the driver handle: adi.Pluto("<deployment>:<id>")
-            return reservation['device_id']
+            # Global's device API token (rfg_...), else (an older Global) the
+            # HOME reference, which also drives: adi.Pluto("<deployment>:<id>")
+            return reservation.get('token') or reservation['device_id']
         username, credential_secret = self._rpc_credentials()
         with _busy("Reserving…"):
             response = self._call(function_name="ACC:reserve_device", args={"un":map_arg(username), "pw":map_arg(credential_secret), "dd":map_arg(device_id), "st":map_arg(int(start_time.timestamp())), "et":map_arg(int(end_time.timestamp()))})
@@ -114,13 +115,14 @@ class RemoteRFAccount:
 
     def install_reserved_driver(self, handle, device_id):
         """Separate from reserve_device: the token is shown before this network
-        step runs, so a failed or stuck driver fetch cannot lose it."""
+        step runs, so a failed or stuck driver fetch cannot lose it. Returns
+        the installed device type, or None."""
         try:
             from ..drivers.dynamic_device import install_driver
             if self.is_https_home:
-                install_driver(device_id=handle)
-            else:
-                install_driver(token=handle, device_id=device_id)
+                # By the ref, which needs no live slot (an rfg_ token does).
+                return install_driver(device_id=device_id).name
+            return install_driver(token=handle, device_id=device_id).name
         except Exception as e:
             print(f"Warning: could not install driver for device {device_id}: {e}")