python-mobius 0.11.0__tar.gz → 0.12.0__tar.gz

{python_mobius-0.11.0 → python_mobius-0.12.0}/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.12.0
+
+- Fixed `get_attribute()` keeping only the first block of a split reply
+  (schedules, scenes and mesh peer lists could come back incomplete).
+- `get_attribute_raw_all()` is now `get_attribute_blocks()`;
+  `get_attribute_raw()` and `get_attribute_all()` are removed.
+- Unknown PrimitiveType and OperationState values decode to `None` instead
+  of raising; `find_device_by_serial()` stops scanning once it's seen.
+- Removed the `MobiusPump` alias, `wait_for_coap_response()` and the unused
+  `which` argument of `get_lunar_enabled()`/`get_insolation_enabled()`.
+- Relay debugging uses debug logging (`mobius.relay`, `mobius.device`)
+  instead of `debug=True` prints and the `on_any_frame` hook.
+- A `MeshPeer` can be built from a serial and address alone.
+- When batching fails, the same attributes are read one at a time and
+  decoded the same way (no more double reads); an unreachable device raises.
+- `get_current_light_intensities()` uses the light poll's calculation;
+  decoders of single-value attributes take one value.
+- `get_full_poll_batch()` works without `primitive` (it's read first) and
+  for any device: only lights and pumps get their type-specific data.
+- The full poll includes Vectra settings and the main firmware version
+  (`main_firmware_version()`).
+- `mobius-scan --dump-diagnostics` prints the diagnostic attributes.
+- Model ids read from a device are unsigned, as in advertisements (the
+  development boards, 61441-61445, decoded as unknown).
+- Mesh peer lists are decoded by `decode_networked_thread_devices()` /
+  `decode_mesh_peer_arrays()`, shared with `mobius-scan`; `discover_tank()`
+  leaves out its own entry when its serial can't be read.
+- `decode_device_info()` takes the decoded PrimitiveType
+  (`decode_primitive_type()`) instead of its raw bytes.
+- `get_pump_telemetry()` is one batched read (one at a time as a fallback),
+  decoded like the full poll's (`decode_pump_telemetry_from_batch()`).
+- The poll no longer requests ErrorState twice.
+- `get_device_summary()` is the full poll plus one batch (it read each
+  attribute separately, some twice); a pump's summary has no
+  `schedule_error`. `LightPollResult` includes the acclimation ramp.
+- One attribute at a time, a schedule or scene list that can't be read no
+  longer fails the whole poll.
+- Light channel ids that aren't a `VisualID` are kept in
+  `LightPrimitive.unknown_channels` (they all became `VisualID.Unknown`, and
+  were written back as channel 0).
+- `decode_active_scene()` accepts `None`; attribute dumps decode ErrorState
+  as the device does (16-bit).
+
 ## 0.11.0
 
 - Added firmware update checks (`firmware.py`): the images the app checks

{python_mobius-0.11.0 → python_mobius-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-mobius
-Version: 0.11.0
+Version: 0.12.0
 Summary: Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)
 Project-URL: Homepage, https://code.r3pek.org/r3pek/python-mobius
 Project-URL: Documentation, https://code.r3pek.org/r3pek/python-mobius/src/branch/main/documentation

{python_mobius-0.11.0 → python_mobius-0.12.0}/documentation/16-python-library.md

@@ -43,8 +43,8 @@ async with MobiusDevice(serial="00000000000002") as device:
 
 ## Reading and writing
 
-Low level: `get_attribute()`, `get_attribute_all()` (all blocks merged),
-`get_attribute_raw_all()` (blocks with their indexes),
+Low level: `get_attribute()` (values of every block),
+`get_attribute_blocks()` (blocks with their indexes),
 `get_attributes_batch()`, `get_supported_attributes()`, `set_attribute()`,
 `set_attribute_multi()`. Every read that fails raises; the higher-level
 getters return `None` or an empty result for unsupported attributes.
@@ -83,12 +83,13 @@ fails (`used_batch` on the result says which path ran):
 |---|---|
 | `get_metadata_batch()` | Advanced features, calibration, firmware, hardware, channels, error state, clock |
 | `get_light_poll_batch()` | A light's schedule and every input of the intensity computation |
-| `get_full_poll_batch(primitive, model)` | Identity, metadata, the light or pump state (including battery settings and operation mode), and scenes |
+| `get_full_poll_batch()` | Identity, metadata, the light or pump state (including battery settings, operation mode and Vectra settings), and scenes |
 
 Pass `supported_attribute_ids` (read once with
 `get_supported_attributes()`) to skip listing attributes on every poll.
-`get_full_poll_batch()` needs the `PrimitiveType` and `Model` from a first
-`get_device_info()`; after that one request per poll is enough.
+`get_full_poll_batch()` reads the `PrimitiveType` first when it isn't
+passed; pass the result's `primitive` and `model` to later polls and one
+request per poll is enough.
 
 Pass a `ConfigurationCache` (one per device, kept between polls) as
 `get_full_poll_batch(cache=...)` to read the scenes and the schedule only
@@ -157,9 +158,10 @@ With `--by-serial SERIAL` (connects to one device):
 | Option | Does |
 |---|---|
 | `--dump-schedule`, `--dump-scenes` | Print the schedule and the scene slots |
+| `--dump-diagnostics` | Print the diagnostic attributes (clock sync, Thread, BLE, FSCI, ...) |
 | `--dump-mesh-peers` | Mesh discovery, step by step |
 | `--relay-target SERIAL` | Reach another device through this one; the options below then act on it. A Bluetooth-only device is connected directly instead ([09](./09-thread-coap-relay.md#bluetooth-only-devices)) |
-| `--debug-relay` | Print every layer of each relayed request |
+| `--debug-relay` | Log every layer of each relayed request and every received frame |
 | `--set-time-to-now`, `--reboot` | Commands |
 | `--set-local-control-enabled`, `--set-auto-dim-timeout`, `--set-max-fan-speed`, `--set-fan-shutdown-enabled` | Advanced features |
 | `--set-battery-backup-speed`, `--set-boosted-battery-power`, `--set-boosted-battery-on-time`, `--set-boosted-battery-off-time` | Pump battery settings |

{python_mobius-0.11.0 → python_mobius-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mobius"
-version = "0.11.0"
+version = "0.12.0"
 description = "Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)"
 readme = "README.md"
 license = { text = "GPL-2.0-only" }

{python_mobius-0.11.0 → python_mobius-0.12.0}/src/mobius/__init__.py

@@ -64,14 +64,14 @@ from .mesh_address import (
     is_short_address_derived, format_mesh_address,
 )
 from .relay import RelayedMobiusDevice
-from .device import firmware_label
+from .device import firmware_label, main_firmware_version
 from .firmware import (
     FIRMWARE_CLOUD_HOST, ImageId, FirmwareImage, installable_images, firmware_images,
     firmware_check_url, AvailableFirmware, FirmwareCheck, parse_firmware_check,
     ChangelogEntry, Changelog, parse_changelog, version_tuple,
 )
 from .device import (
-    MobiusDevice, MobiusPump, LightIntensityResult, LightPollResult, FullPollResult,
+    MobiusDevice, LightIntensityResult, LightPollResult, FullPollResult,
     schedule_capacity, min_schedule_capacity, tank_group,
     SERVICE_GENERAL, CHAR_RX_DATA, CHAR_RX_FINAL, CHAR_TX_DATA, CHAR_TX_FINAL,
 )
@@ -93,7 +93,7 @@ from .mob import (
     MAX_PUMP_PRIMITIVE_SIZE,
 )
 
-__version__ = "0.11.0"
+__version__ = "0.12.0"
 
 __all__ = [
     "__version__",
@@ -120,7 +120,7 @@ __all__ = [
     "get_pump_reverse",
     "FirmwareType", "FIRMWARE_TYPE_LABELS_ETM", "HardwareInfo",
     # firmware
-    "firmware_label", "FIRMWARE_CLOUD_HOST", "ImageId", "FirmwareImage", "installable_images", "firmware_images",
+    "firmware_label", "main_firmware_version", "FIRMWARE_CLOUD_HOST", "ImageId", "FirmwareImage", "installable_images", "firmware_images",
     "firmware_check_url", "AvailableFirmware", "FirmwareCheck", "parse_firmware_check",
     "ChangelogEntry", "Changelog", "parse_changelog", "version_tuple",
     "Color", "COLOR_LABELS", "RadioType", "RADIO_TYPE_LABELS",
@@ -153,7 +153,7 @@ __all__ = [
     "format_mesh_address", "posix_tz_string", "TIME_ZONE_FIELD_SIZE",
     "RelayedMobiusDevice",
     # device
-    "MobiusDevice", "MobiusPump", "LightIntensityResult", "LightPollResult", "FullPollResult",
+    "MobiusDevice", "LightIntensityResult", "LightPollResult", "FullPollResult",
     "schedule_capacity", "min_schedule_capacity", "tank_group",
     "SERVICE_GENERAL", "CHAR_RX_DATA", "CHAR_RX_FINAL", "CHAR_TX_DATA", "CHAR_TX_FINAL",
     # discovery

{python_mobius-0.11.0 → python_mobius-0.12.0}/src/mobius/cli.py

@@ -13,19 +13,22 @@ import argparse
 import asyncio
 import contextlib
 import json
+import logging
 import struct
 from typing import Optional
 
 from .checksums import configured_scenes_checksum, schedule_checksum, supported_attributes_crc
-from .device import ALL_ELEMENTS, MobiusDevice, min_schedule_capacity
+from .device import (
+    ALL_ELEMENTS, MobiusDevice, min_schedule_capacity, decode_mesh_peer_arrays, decode_networked_thread_devices,
+)
 from .relay import RelayedMobiusDevice
 from .device_status import MeshPeer
 from .mesh_address import (
     is_valid_mesh_address, mesh_local_prefix_from_own_address,
-    mesh_local_prefix_from_mlprefix, build_rloc_address, extract_short_address,
+    mesh_local_prefix_from_mlprefix,
 )
 from .constants import (
-    PrimitiveType, C2Attribute, Model, enum_or_none,
+    PrimitiveType, C2Attribute,
     primitive_type_from_name, support_tier,
 )
 from .discovery import (
@@ -82,13 +85,11 @@ async def _dump_schedule(device: MobiusDevice, support: str) -> None:
     and for lights the lunar/insolation/intensity/acclimation state."""
     print("  --- full schedule ---")
     if support == "light":
-        points = await device.get_light_schedule(which=1)
-        for point in sorted(points, key=lambda p: p.time_minutes):
+        poll = await device.get_light_poll_batch(which=1)
+        for point in sorted(poll.schedule_points, key=lambda p: p.time_minutes):
             print(f"    {_format_time(point.time_minutes)}{_format_flags(point)}: "
                   f"{_format_channels(point.light.channels)}")
-
-        lunar_enabled = await device.get_lunar_enabled()
-        print(f"  lunar_enabled: {lunar_enabled}")
+        print(f"  lunar_enabled: {poll.lunar_enabled}")
 
         # Firmware-computed lunar state, to compare with the calculated
         # "current_intensities"/"light_diagnostics" of the summary.
@@ -98,12 +99,9 @@ async def _dump_schedule(device: MobiusDevice, support: str) -> None:
         except Exception as e:
             print(f"  lunar_phase_info: read failed: {e}")
 
-        insolation_active = await device.get_insolation_enabled()
-        schedule_intensity = await device.get_schedule_intensity()
-        acclimation = await device.get_acclimation_info()
-        print(f"  insolation_active: {insolation_active}")
-        print(f"  schedule_intensity: {schedule_intensity}")
-        print(f"  acclimation: {acclimation}")
+        print(f"  insolation_active: {poll.intensities.diagnostics['insolation_active']}")
+        print(f"  schedule_intensity: {poll.schedule_intensity}")
+        print(f"  acclimation: {poll.acclimation}")
 
     elif support.startswith("pump"):
         points = await device.get_pump_schedule(which=1)
@@ -120,6 +118,18 @@ def _support_from_primitive_type(primitive_type_name: str | None) -> str:
     return support_tier(primitive_type_from_name(primitive_type_name))
 
 
+async def _target_identity(target, serial: str, fallback_support: str) -> tuple[str, Optional[int]]:
+    """(support tier, group_mask) read from `target` itself; when its device
+    info can't be read, (`fallback_support`, None) with a message."""
+    try:
+        info = await target.get_device_info()
+    except Exception as e:
+        print(f"  Could not read {serial!r}'s own device info ({e}) -- using support={fallback_support!r} "
+              f"and leaving out the rest of its schedule group.")
+        return fallback_support, None
+    return _support_from_primitive_type(info.get("primitive_type")), info.get("group_mask")
+
+
 async def _dump_schedule_to_file(device: MobiusDevice, support: str, serial: str, path: str) -> int:
     """
     Writes Schedule1 and Schedule2 to `path` as JSON
@@ -200,8 +210,7 @@ async def _dump_schedule_to_mob_file(device: MobiusDevice, support: str, path: s
         points = await device.get_light_schedule(which=1)
         mob = light_schedule_to_mob(points, template_name)
     elif support.startswith("pump"):
-        info = await device.get_device_info()
-        primitive_type = PrimitiveType[info["primitive_type"]]
+        primitive_type = await device.identify_device_type()
         points = await device.get_pump_schedule(which=1)
         mob = pump_schedule_to_mob(points, primitive_type, template_name)
     else:
@@ -235,7 +244,7 @@ async def _load_schedule_from_mob_file(device: MobiusDevice, support: str, path:
 
 async def _resolve_group_targets(
     gateway: MobiusDevice, target_serial: str, target_device, target_group_mask,
-    support: str, debug_relay: bool, pan_id: Optional[int] = None,
+    support: str, pan_id: Optional[int] = None,
     stack: Optional[contextlib.AsyncExitStack] = None, args=None,
 ) -> list[tuple[str, object]]:
     """
@@ -267,7 +276,7 @@ async def _resolve_group_targets(
     for peer in (tank.peers if tank is not None else []):
         if peer.serial == target_serial:
             continue
-        relayed = RelayedMobiusDevice(gateway, peer, debug=debug_relay)
+        relayed = RelayedMobiusDevice(gateway, peer)
         try:
             peer_info = await relayed.get_device_info()
         except Exception as e:
@@ -378,7 +387,7 @@ async def _check_checksums(target) -> None:
         if data_attr not in supported_ids:
             print(f"  {label}: not supported by this device")
             continue
-        values = await target.get_attribute_all(data_attr, 0, ALL_ELEMENTS)
+        values = await target.get_attribute(data_attr, 0, ALL_ELEMENTS)
         if data_attr == C2Attribute.ConfiguredScenes:
             computed = configured_scenes_checksum(values)
             used = sum(1 for v in values if len(v) >= 2 and struct.unpack_from("<H", v)[0] != 0)
@@ -410,7 +419,7 @@ async def _debug_mesh_discovery(device) -> list:
         print(f"    MLPrefix OK. Derived mesh-local prefix: {prefix.hex()}")
         try:
             entries_raw = await device.get_attribute(
-                C2Attribute.NetworkedThreadDevices, index=0, count=0xFFFF,
+                C2Attribute.NetworkedThreadDevices, index=0, count=ALL_ELEMENTS,
             )
         except Exception as e:
             print(f"    NetworkedThreadDevices FAILED: {e!r}")
@@ -418,25 +427,10 @@ async def _debug_mesh_discovery(device) -> list:
         print(f"    NetworkedThreadDevices returned {len(entries_raw)} element(s): "
               f"{[e.hex() for e in entries_raw]}")
 
-        peers = []
         for entry in entries_raw:
             if len(entry) != 28:
-                print(f"    Skipping malformed entry (expected 28 bytes, got "
-                      f"{len(entry)}): {entry.hex()}")
-                continue
-            try:
-                serial = entry[14:28].decode("ascii").rstrip("\x00")
-            except UnicodeDecodeError:
-                continue
-            if not serial or serial == "00000000000000":
-                continue
-            address = prefix + entry[0:8]
-            model_raw = struct.unpack("<h", entry[12:14])[0]
-            peers.append(MeshPeer(
-                serial=serial, model_raw=model_raw, model=enum_or_none(Model, model_raw),
-                short_address=extract_short_address(address), address=address,
-                age=struct.unpack("<I", entry[8:12])[0],
-            ))
+                print(f"    Skipping malformed entry (expected 28 bytes, got {len(entry)}): {entry.hex()}")
+        peers = decode_networked_thread_devices(prefix, entries_raw)
         if peers:
             print(f"    Parsed {len(peers)} peer(s) via NetworkedThreadDevices -- "
                   f"skipping the MXM-hub steps below.")
@@ -474,7 +468,7 @@ async def _debug_mesh_discovery(device) -> list:
     for attr in (C2Attribute.SerialNumberArray, C2Attribute.DeviceModelArray, C2Attribute.ShortAddressArray):
         print(f"  Step 2: {attr.name} ({attr.value})...")
         try:
-            values = await device.get_attribute(attr, index=0, count=0xFFFF)
+            values = await device.get_attribute(attr, index=0, count=ALL_ELEMENTS)
         except Exception as e:
             print(f"    FAILED: {e!r}")
             values = []
@@ -482,24 +476,10 @@ async def _debug_mesh_discovery(device) -> list:
             print(f"    Returned {len(values)} element(s): {[v.hex() for v in values]}")
         arrays[attr] = values
 
-    peers = []
-    for serial_bytes, model_bytes, short_bytes in zip(
-        arrays[C2Attribute.SerialNumberArray], arrays[C2Attribute.DeviceModelArray],
+    return decode_mesh_peer_arrays(
+        prefix, arrays[C2Attribute.SerialNumberArray], arrays[C2Attribute.DeviceModelArray],
         arrays[C2Attribute.ShortAddressArray],
-    ):
-        try:
-            serial = serial_bytes.decode("ascii").rstrip("\x00")
-        except (UnicodeDecodeError, AttributeError):
-            continue
-        if not serial or serial == "00000000000000" or len(model_bytes) < 2 or len(short_bytes) < 2:
-            continue
-        model_raw = struct.unpack("<h", model_bytes[:2])[0]
-        short_address = struct.unpack("<H", short_bytes[:2])[0]
-        peers.append(MeshPeer(
-            serial=serial, model_raw=model_raw, model=enum_or_none(Model, model_raw),
-            short_address=short_address, address=build_rloc_address(prefix, short_address),
-        ))
-    return peers
+    )
 
 
 def _print_mesh_peers_or_hint(peers: list) -> None:
@@ -511,6 +491,28 @@ def _print_mesh_peers_or_hint(peers: list) -> None:
         _print_peers(peers)
 
 
+# Diagnostic getters printed by --dump-diagnostics, in order.
+_DIAGNOSTIC_GETTERS = (
+    "get_fsci_diagnostic_info", "get_clock_sync_info", "get_thread_provisioning_info",
+    "get_thread_network_state_info", "get_ble_connection_info", "get_scene_diagnostic_info",
+    "get_calibration_extra_info", "get_legacy_device_info", "get_wifi_remnant_info",
+    "get_engineering_diagnostic_info", "get_channel_intensities", "get_insolation_tables",
+    "get_device_local_date",
+)
+
+
+async def _dump_diagnostics(device: MobiusDevice) -> None:
+    """Prints every diagnostic getter's result (each field is None when the
+    device doesn't support it)."""
+    print("  --- diagnostics ---")
+    for name in _DIAGNOSTIC_GETTERS:
+        try:
+            value = await getattr(device, name)()
+        except Exception as e:
+            value = f"read failed: {e}"
+        print(f"  {name.removeprefix('get_')}: {value}")
+
+
 async def _print_summary(mdevice: MobiusDevice, args) -> dict:
     """Prints get_device_summary() plus the optional schedule/scene dumps."""
     summary = await mdevice.get_device_summary()
@@ -520,6 +522,8 @@ async def _print_summary(mdevice: MobiusDevice, args) -> dict:
         await _dump_schedule(mdevice, summary.get("support", ""))
     if args.dump_scenes:
         await _dump_scenes(mdevice, primitive_type_from_name(summary.get("primitive_type")))
+    if args.dump_diagnostics:
+        await _dump_diagnostics(mdevice)
     return summary
 
 
@@ -538,11 +542,8 @@ async def _learn_peer_directly(args, found_target) -> Optional[MeshPeer]:
         return None
     print(f"  Learned address directly: {target_address.hex()}")
     return MeshPeer(
-        serial=args.relay_target,
-        model_raw=target_info.model_raw if target_info else 0,
-        model=target_info.model if target_info else None,
-        short_address=extract_short_address(target_address),
-        address=target_address,
+        serial=args.relay_target, address=target_address,
+        model_raw=target_info.model_raw if target_info else None,
     )
 
 
@@ -556,20 +557,14 @@ async def _write_to_group(mdevice, args, target, label: str, serial: str, summar
     exceeds the smallest capacity in the group. `write(device, support,
     serial)` performs the write for one device and returns a summary line.
     """
-    try:
-        target_info = await target.get_device_info()
-        target_group_mask = target_info.get("group_mask")
-        # Read from the actual target: the summary describes the gateway.
-        target_support = _support_from_primitive_type(target_info.get("primitive_type"))
-    except Exception as e:
-        print(f"  Could not read {serial!r}'s own device info ({e}) -- "
-              f"writing only to it, not the rest of its group.")
-        target_group_mask = None
-        target_support = summary.get("support", "") if not args.relay_target else ""
+    # Read from the actual target: the summary describes the gateway.
+    target_support, target_group_mask = await _target_identity(
+        target, serial, summary.get("support", "") if not args.relay_target else "",
+    )
 
     print(f"\n=== resolving schedule-group targets for {label} ===")
     group_targets = await _resolve_group_targets(
-        mdevice, serial, target, target_group_mask, target_support, args.debug_relay,
+        mdevice, serial, target, target_group_mask, target_support,
         pan_id=pan_id, stack=stack, args=args,
     )
     if len(group_targets) > 1:
@@ -653,7 +648,7 @@ async def _run_by_serial(args) -> None:
                           f"brief direct connection to {args.relay_target!r} to learn its address...")
                     target_peer = await _learn_peer_directly(args, found_target)
                 if target_peer is not None:
-                    relayed = RelayedMobiusDevice(mdevice, target_peer, debug=args.debug_relay)
+                    relayed = RelayedMobiusDevice(mdevice, target_peer)
                     try:
                         for k, v in (await relayed.get_device_summary()).items():
                             print(f"  {k}: {v}")
@@ -678,12 +673,10 @@ async def _run_by_serial(args) -> None:
                 return f"{args.relay_target!r} (via relay through {args.by_serial!r})", relayed, args.relay_target
 
             async def target_support(target, serial: str) -> str:
-                try:
-                    return _support_from_primitive_type((await target.get_device_info()).get("primitive_type"))
-                except Exception as e:
-                    print(f"  Could not read {serial!r}'s own device info ({e}) -- "
-                          f"falling back to {args.by_serial!r}'s own support.")
-                    return summary.get("support", "") if not args.relay_target else ""
+                support, _group_mask = await _target_identity(
+                    target, serial, summary.get("support", "") if not args.relay_target else "",
+                )
+                return support
 
             if args.reboot and (picked := pick_target("reboot()")):
                 label, target, _serial = picked
@@ -971,6 +964,11 @@ def main() -> None:
                          help="Also print every configured scene on each connected device -- "
                               "id, name, timeout and light/pump payload of every slot, including "
                               "empty ones.")
+    parser.add_argument("--dump-diagnostics", action="store_true",
+                         help="Also print each connected device's diagnostic attributes: FSCI, "
+                              "clock sync, Thread provisioning and network state, BLE connection, "
+                              "scene, calibration, legacy, Wi-Fi and engineering diagnostics, "
+                              "channel intensities, insolation tables and the device's local date.")
     parser.add_argument("--dump-mesh-peers", action="store_true",
                          help="Only usable with --by-serial. After connecting, calls "
                               "discover_mesh_peers_auto() on it and prints every other device "
@@ -988,11 +986,10 @@ def main() -> None:
                               "get_device_summary() read to it through the gateway and prints "
                               "the result. The other --by-serial actions apply to this target.")
     parser.add_argument("--debug-relay", action="store_true",
-                         help="Only usable with --relay-target. Prints raw bytes at every "
-                              "layer of each relayed request/response (outer frame, CoAP "
-                              "envelope fields, inner frame), plus every frame the gateway "
-                              "receives while waiting (the opcode-25 ack and the opcode-26 "
-                              "indication).")
+                         help="Logs the raw bytes of every layer of each relayed "
+                              "request/response (inner frame, outer frame, CoAP response) and "
+                              "every frame the gateway receives (debug logging for "
+                              "mobius.relay and mobius.device).")
     parser.add_argument("--set-time-to-now", action="store_true",
                          help="Only usable with --by-serial. A WRITE -- use on hardware you're "
                               "prepared to have its clock changed on. Calls set_time_to_now() "
@@ -1106,6 +1103,11 @@ def main() -> None:
                     print(f"\t{element['raw_hex']}{suffix}")
         return
 
+    if args.debug_relay:
+        logging.basicConfig(format="    [%(name)s] %(message)s")
+        for name in ("mobius.relay", "mobius.device"):
+            logging.getLogger(name).setLevel(logging.DEBUG)
+
     asyncio.run(_run(args))