python-mobius 0.4.4__py3-none-any.whl → 0.6.0__py3-none-any.whl

mobius/__init__.py

@@ -13,7 +13,7 @@ protocol writeup and confirmation evidence for every field.
 from .crc import crc16, CRC16_TABLE
 from .frame import (
     build_frame, parse_frame, ParsedFrame,
-    encode_get_attribute, encode_set_attribute, decode_attribute_response, AttributeValue,
+    encode_get_attribute, encode_get_attributes_batch, encode_set_attribute, decode_attribute_response, AttributeValue,
     OPGROUP_C2CI_REQUEST, OPGROUP_C2CI_CONFIRM,
     OPGROUP_FSCI_REQUEST, OPGROUP_FSCI_CONFIRM,
     OPGROUP_QOTAP_REQUEST, OPGROUP_QOTAP_CONFIRM,
@@ -35,7 +35,7 @@ from .schedule import (
     LightPrimitive, SchedulePoint, interpolate_light_schedule,
     PumpPrimitiveValue, PumpSchedulePoint, get_active_pump_block,
 )
-from .manufacturer import MOBIUS_COMPANY_ID, MobiusAdvertisement, parse_manufacturer_data
+from .manufacturer import MOBIUS_COMPANY_ID_ECOTECH, MOBIUS_COMPANY_ID_AQUAILLUMINATION, MOBIUS_COMPANY_IDS, MobiusAdvertisement, parse_manufacturer_data
 from .modifiers import (
     AcclimationInfo, is_night_segment,
     julian_day_from_date, lunar_days_into_phase, lunar_percent_reduction,
@@ -43,7 +43,7 @@ from .modifiers import (
 )
 from .power import ChannelPowerInfo, channel_percent_value
 from .pump_status import PumpFlowRange, BatteryBackupInfo, BoostedBatteryInfo
-from .device_status import GroupInfo, CalibrationInfo, MaintenanceInfo, DeviceTimeInfo, MeshPeer, Tank
+from .device_status import GroupInfo, CalibrationInfo, AdvancedFeatures, VectraInfo, CoffeeInfo, MaintenanceInfo, DeviceTimeInfo, MeshPeer, Tank, LunarPhaseInfo, MetadataSnapshot
 from .coap import (
     CoapRequestType, CoapMethod, CoapResponseCode, CoapResponse,
     encode_coap_request, decode_coap_response, COAP_OPCODE, COAP_INDICATION_OPCODE,
@@ -64,8 +64,14 @@ from .discovery import (
     dedupe_by_serial, find_device_by_serial, discover_mesh_peers_via_direct_connect,
     discover_tank,
 )
+from .frame import SupportedAttribute
+from .dump import (
+    dump_attributes, format_attribute_dump_json, parse_attribute_dump_json,
+    format_attribute_dump_text, parse_attribute_dump_text, parse_attribute_dump,
+    enrich_attribute_dump,
+)
 
-__version__ = "0.4.4"
+__version__ = "0.6.0"
 
 __all__ = [
     "__version__",
@@ -73,7 +79,7 @@ __all__ = [
     "crc16", "CRC16_TABLE",
     # frame
     "build_frame", "parse_frame", "ParsedFrame",
-    "encode_get_attribute", "encode_set_attribute", "decode_attribute_response", "AttributeValue",
+    "encode_get_attribute", "encode_get_attributes_batch", "encode_set_attribute", "decode_attribute_response", "AttributeValue",
     "OPGROUP_C2CI_REQUEST", "OPGROUP_C2CI_CONFIRM",
     "OPGROUP_FSCI_REQUEST", "OPGROUP_FSCI_CONFIRM",
     "OPGROUP_QOTAP_REQUEST", "OPGROUP_QOTAP_CONFIRM",
@@ -93,7 +99,7 @@ __all__ = [
     "LightPrimitive", "SchedulePoint", "interpolate_light_schedule",
     "PumpPrimitiveValue", "PumpSchedulePoint", "get_active_pump_block",
     # manufacturer
-    "MOBIUS_COMPANY_ID", "MobiusAdvertisement", "parse_manufacturer_data",
+    "MOBIUS_COMPANY_ID_ECOTECH", "MOBIUS_COMPANY_ID_AQUAILLUMINATION", "MOBIUS_COMPANY_IDS", "MobiusAdvertisement", "parse_manufacturer_data",
     # modifiers
     "AcclimationInfo", "is_night_segment",
     "julian_day_from_date", "lunar_days_into_phase", "lunar_percent_reduction",
@@ -103,7 +109,7 @@ __all__ = [
     # pump_status
     "PumpFlowRange", "BatteryBackupInfo", "BoostedBatteryInfo",
     # device_status
-    "GroupInfo", "CalibrationInfo", "MaintenanceInfo", "DeviceTimeInfo", "MeshPeer", "Tank",
+    "GroupInfo", "CalibrationInfo", "AdvancedFeatures", "VectraInfo", "CoffeeInfo", "MaintenanceInfo", "DeviceTimeInfo", "MeshPeer", "Tank", "LunarPhaseInfo", "MetadataSnapshot",
     "CoapRequestType", "CoapMethod", "CoapResponseCode", "CoapResponse",
     "encode_coap_request", "decode_coap_response", "COAP_OPCODE", "COAP_INDICATION_OPCODE",
     "next_coap_token",
@@ -117,4 +123,7 @@ __all__ = [
     "scan_for_mobius_devices", "scan_for_mobius_devices_with_info", "group_by_pan_id",
     "dedupe_by_serial", "find_device_by_serial", "discover_mesh_peers_via_direct_connect",
     "discover_tank",
+    "SupportedAttribute", "dump_attributes", "enrich_attribute_dump",
+    "format_attribute_dump_json", "parse_attribute_dump_json",
+    "format_attribute_dump_text", "parse_attribute_dump_text", "parse_attribute_dump",
 ]

mobius/cli.py

@@ -23,6 +23,7 @@ from .discovery import (
     find_device_by_serial, discover_mesh_peers_via_direct_connect, discover_tank,
 )
 from .schedule import SchedulePoint
+from .dump import dump_attributes, format_attribute_dump_json, parse_attribute_dump, enrich_attribute_dump
 
 
 def _format_flags(point) -> str:
@@ -60,10 +61,27 @@ async def _dump_schedule(device: MobiusDevice, support: str) -> None:
             print(f"    {_format_time(point.time_minutes)}{_format_flags(point)}: {channels}")
 
         lunar_enabled = await device.get_lunar_enabled()
+        print(f"  lunar_enabled: {lunar_enabled}")
+
+        # The device's own firmware-computed lunar state -- see
+        # LunarPhaseInfo's own docstring in device_status.py for the
+        # confirmation and what this is useful for. Compare against
+        # "current_intensities"/"light_diagnostics" in the summary
+        # output above (NOT re-fetched here -- get_device_summary()
+        # already called get_current_light_intensities() once; a
+        # second call here would just be a redundant device read of
+        # the exact same thing). A real failure is shown directly
+        # (get_lunar_phase_info() no longer swallows it) rather than
+        # printing an indistinguishable "None".
+        try:
+            lunar_phase_info = await device.get_lunar_phase_info()
+            print(f"  lunar_phase_info: {lunar_phase_info}")
+        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"  lunar_enabled: {lunar_enabled}")
         print(f"  insolation_active: {insolation_active}")
         print(f"  schedule_intensity: {schedule_intensity}")
         print(f"  acclimation: {acclimation}")
@@ -241,7 +259,14 @@ async def _run(args) -> None:
         device, info = found
         print(f"  currently at {device.address}  model={info.model.name if info.model else info.model_raw}")
         try:
-            async with MobiusDevice(serial=args.by_serial, adapter=args.adapter,
+            # device= is the exact BLEDevice found_device_by_serial() just
+            # located above -- passing it avoids a second, independent scan
+            # inside connect() (see MobiusDevice.__init__()'s own docstring:
+            # re-scanning per device can cause BlueZ to drop it between
+            # "found" and "connect", the exact failure this fixes). serial=
+            # is still passed alongside it, for this same instance's own
+            # reconnect logic if the connection drops later in this run.
+            async with MobiusDevice(device=device, serial=args.by_serial, adapter=args.adapter,
                                      connect_timeout=args.connect_timeout) as mdevice:
                 summary = await mdevice.get_device_summary()
                 for k, v in summary.items():
@@ -249,6 +274,7 @@ async def _run(args) -> None:
                 if args.dump_schedule:
                     await _dump_schedule(mdevice, summary.get("support", ""))
 
+                relayed = None  # set below only if --relay-target resolves successfully
                 if args.dump_mesh_peers or args.relay_target:
                     print("\n=== Thread mesh peer discovery ===")
                     peers = await _debug_mesh_discovery(mdevice)
@@ -314,6 +340,128 @@ async def _run(args) -> None:
                                   f"`--by-serial {args.relay_target}` run to confirm they match.")
                         except Exception as e:
                             print(f"  relay failed: {e}")
+
+                if args.reboot:
+                    # If --relay-target was also given, reboot THAT device
+                    # via relay through the connected one, instead of the
+                    # directly-connected device itself -- lets both the
+                    # direct and relayed write paths get tested with the
+                    # same flag, without a separate one. If relay resolution
+                    # above failed, this deliberately does NOT fall back to
+                    # rebooting the directly-connected device instead --
+                    # that would silently reboot a device the user didn't
+                    # actually ask to reboot.
+                    if args.relay_target:
+                        if relayed is None:
+                            print(f"\n=== reboot() on {args.relay_target!r} (via relay) -- "
+                                  f"SKIPPED: relay target could not be resolved above ===")
+                            reboot_target = None
+                        else:
+                            reboot_target_label = f"{args.relay_target!r} (via relay through {args.by_serial!r})"
+                            reboot_target = relayed
+                    else:
+                        reboot_target_label = f"{args.by_serial!r} (direct)"
+                        reboot_target = mdevice
+
+                    if reboot_target is not None:
+                        print(f"\n=== reboot() on {reboot_target_label} (WRITE -- Reset, soft) ===")
+                        try:
+                            await reboot_target.reboot()
+                            print(f"  reboot() on {reboot_target_label} succeeded (device "
+                                  f"acknowledged the request -- it may take a few seconds to "
+                                  f"actually finish rebooting and reconnect).")
+                        except Exception as e:
+                            print(f"  reboot() FAILED: {e}")
+
+                if args.set_time_to_now:
+                    # Same relay-aware targeting as --reboot above -- see
+                    # that block's own comment for why this deliberately
+                    # doesn't fall back to the directly-connected device
+                    # if relay resolution failed.
+                    if args.relay_target:
+                        if relayed is None:
+                            print(f"\n=== set_time_to_now() on {args.relay_target!r} (via relay) -- "
+                                  f"SKIPPED: relay target could not be resolved above ===")
+                            time_target = None
+                        else:
+                            time_target_label = f"{args.relay_target!r} (via relay through {args.by_serial!r})"
+                            time_target = relayed
+                    else:
+                        time_target_label = f"{args.by_serial!r} (direct)"
+                        time_target = mdevice
+
+                    if time_target is not None:
+                        print(f"\n=== set_time_to_now() on {time_target_label} (WRITE -- Epoch) ===")
+                        try:
+                            await time_target.set_time_to_now()
+                            print(f"  set_time_to_now() on {time_target_label} succeeded.")
+                        except Exception as e:
+                            print(f"  set_time_to_now() FAILED: {e}")
+
+                if args.dump_attributes:
+                    # Same relay-aware targeting as --reboot above.
+                    if args.relay_target:
+                        if relayed is None:
+                            print(f"\n=== dump_attributes() on {args.relay_target!r} (via relay) -- "
+                                  f"SKIPPED: relay target could not be resolved above ===")
+                            dump_target = None
+                        else:
+                            dump_target_label = f"{args.relay_target!r} (via relay through {args.by_serial!r})"
+                            dump_target = relayed
+                    else:
+                        dump_target_label = f"{args.by_serial!r} (direct)"
+                        dump_target = mdevice
+
+                    if dump_target is not None:
+                        print(f"\n=== dump_attributes() on {dump_target_label} -- "
+                              f"writing to {args.dump_attributes!r} ===")
+                        print("  Discovering supported attributes...")
+                        try:
+                            values = await dump_attributes(dump_target)
+                            text = format_attribute_dump_json(values)
+                            with open(args.dump_attributes, "w") as f:
+                                f.write(text)
+                            print(f"  Wrote {len(values)} attribute(s) to {args.dump_attributes!r}.")
+                        except Exception as e:
+                            print(f"  dump_attributes() FAILED: {e}")
+
+                requested_features = {}
+                if args.set_local_control_enabled is not None:
+                    requested_features["local_control_enabled"] = args.set_local_control_enabled == "true"
+                if args.set_auto_dim_timeout is not None:
+                    requested_features["auto_dim_timeout"] = args.set_auto_dim_timeout
+                if args.set_max_fan_speed is not None:
+                    requested_features["max_fan_speed"] = args.set_max_fan_speed
+                if args.set_fan_shutdown_enabled is not None:
+                    requested_features["fan_shutdown_enabled"] = args.set_fan_shutdown_enabled == "true"
+
+                if requested_features:
+                    # Same relay-aware targeting as --reboot above.
+                    if args.relay_target:
+                        if relayed is None:
+                            print(f"\n=== set_advanced_features() on {args.relay_target!r} (via relay) -- "
+                                  f"SKIPPED: relay target could not be resolved above ===")
+                            features_target = None
+                        else:
+                            features_target_label = f"{args.relay_target!r} (via relay through {args.by_serial!r})"
+                            features_target = relayed
+                    else:
+                        features_target_label = f"{args.by_serial!r} (direct)"
+                        features_target = mdevice
+
+                    if features_target is not None:
+                        print(f"\n=== set_advanced_features({', '.join(f'{k}={v!r}' for k, v in requested_features.items())}) "
+                              f"on {features_target_label} (WRITE) ===")
+                        try:
+                            result = await features_target.set_advanced_features(**requested_features)
+                            for field, error in result.items():
+                                if error is None:
+                                    print(f"  {field}: succeeded.")
+                                else:
+                                    print(f"  {field}: FAILED: {error}")
+                        except Exception as e:
+                            print(f"  set_advanced_features() FAILED entirely: {e}")
+
         except Exception as e:
             print("  failed to connect/read:", e)
         return
@@ -365,7 +513,10 @@ async def _run(args) -> None:
         device, info = connectable[0]
         print(f"\n=== Network addresses (connecting to {info.serial} to ask) ===")
         try:
-            async with MobiusDevice(serial=info.serial, adapter=args.adapter,
+            # device= already found above via the scan feeding `connectable`
+            # -- see the --by-serial path's own comment for why this avoids
+            # a redundant, race-prone second scan inside connect().
+            async with MobiusDevice(device=device, serial=info.serial, adapter=args.adapter,
                                      connect_timeout=args.connect_timeout) as mdevice:
                 peers = await _debug_mesh_discovery(mdevice)
         except Exception as e:
@@ -398,7 +549,10 @@ async def _run(args) -> None:
             device, info = connectable[0]
             print(f"  pan_id {label} (connecting through {info.serial})...")
             try:
-                async with MobiusDevice(serial=info.serial, adapter=args.adapter,
+                # device= already found above -- see the --by-serial path's
+                # own comment for why this avoids a redundant, race-prone
+                # second scan inside connect().
+                async with MobiusDevice(device=device, serial=info.serial, adapter=args.adapter,
                                          connect_timeout=args.connect_timeout) as mdevice:
                     tank = await discover_tank(mdevice)
             except Exception as e:
@@ -508,8 +662,11 @@ def main() -> None:
                               "(every point's time, flags, and per-channel/mode values) -- not "
                               "just the interpolated 'current' value get_device_summary() shows. "
                               "For lights, also prints lunar/insolation/schedule-intensity/"
-                              "acclimation state. Useful for diagnosing a mismatch against the "
-                              "app's own displayed value.")
+                              "acclimation state, PLUS the device's own firmware-computed lunar "
+                              "state (LunarPhasesCurrentDay/CurrentScalar, confirmed against real "
+                              "hardware -- see LunarPhaseInfo's own docstring) -- compare against "
+                              "\"current_intensities\"/\"light_diagnostics\" in the summary output "
+                              "above for this library's own calculated value.")
     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 "
@@ -542,6 +699,26 @@ def main() -> None:
                               "confirmed-meaningless opcode-25 ack and the real opcode-26 "
                               "indication, if it arrives). Useful for diagnosing a relay that "
                               "times out or returns unexpected data.")
+    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() "
+                              "on the target device (Epoch, reserved-byte group=1 "
+                              "-- required for the write to be accepted at all, confirmed "
+                              "against real hardware). If --relay-target is also given, sets "
+                              "the time on THAT device via relay through the connected one "
+                              "instead, same targeting as --reboot below. See that method's own "
+                              "docstring, and "
+                              "documentation/09-thread-coap-relay.md, for what's confirmed "
+                              "about this vs the rest of the mesh.")
+    parser.add_argument("--reboot", action="store_true",
+                         help="Only usable with --by-serial. A WRITE -- use on hardware you're "
+                              "prepared to have reboot. Soft-reboots the directly-connected "
+                              "device (Reset, ResetType.Soft) -- confirmed via the app's own "
+                              "source to be exactly its own \"Restart\" button. If "
+                              "--relay-target is also given, reboots THAT device via relay "
+                              "through the connected one instead, to test the relayed write "
+                              "path specifically -- see reboot()'s own docstring for what's "
+                              "confirmed about this vs a direct connection.")
     parser.add_argument("--build-peer-map", action="store_true",
                          help="Instead of full device summaries, scan for devices then "
                               "briefly connect to EACH one in turn to build a mesh peer map "
@@ -553,7 +730,78 @@ def main() -> None:
                               "once in that case, so you can later keep only one connection "
                               "open and relay to the rest. See "
                               "documentation/09-thread-coap-relay.md.")
+    parser.add_argument("--dump-attributes", default=None, metavar="FILE",
+                         help="Only usable with --by-serial. Discovers every attribute the "
+                              "target device reports supporting -- the relay target if "
+                              "--relay-target is also given, otherwise the directly-connected "
+                              "device itself (via "
+                              "get_supported_attributes(), confirmed against real hardware), "
+                              "reads every one, and writes the result to FILE as enriched JSON "
+                              "-- resolved attribute names and decoded values where this "
+                              "library has a confirmed decoder, generic best-effort numeric "
+                              "interpretations otherwise. NOT the app's own plain-text format "
+                              "(see format_attribute_dump_text() if you specifically need "
+                              "that, e.g. to compare against a dump shared directly from the "
+                              "app). Read-only -- doesn't write anything to the device itself.")
+    parser.add_argument("--set-local-control-enabled", default=None, choices=["true", "false"],
+                         help="Only usable with --by-serial. A WRITE -- use on hardware you're "
+                              "prepared to have this setting changed on. VorTech-relevant (the "
+                              "app's own \"Local Control\" setting) -- see set_advanced_features() "
+                              "for the confirmed wire format. Combinable with the other "
+                              "--set-*-enabled/--set-auto-dim-timeout/--set-max-fan-speed flags "
+                              "below -- all requested fields are sent in one call, whichever of "
+                              "them the target device actually supports.")
+    parser.add_argument("--set-auto-dim-timeout", default=None, type=int, metavar="SECONDS",
+                         help="Only usable with --by-serial. A WRITE. VorTech-relevant (the "
+                              "app's own \"Led Auto Dim\" setting). The app's own UI only ever "
+                              "offers 0/30/60/300/600/1800/3600 (0 = \"Always On\") as a fixed "
+                              "chooser -- this library does NOT restrict to those, since that's "
+                              "a UI-level choice, not a confirmed protocol-level one; validate "
+                              "against that list yourself first if you want to match the app's "
+                              "own restricted choices exactly.")
+    parser.add_argument("--set-max-fan-speed", default=None, type=float, metavar="PERCENT",
+                         help="Only usable with --by-serial. A WRITE. Radion-relevant (the "
+                              "app's own \"Max Fan Speed\" setting), 0-100 percent -- 100 "
+                              "encodes as the raw attribute's own -1 (0xFFFF) sentinel, "
+                              "confirmed matching the app's own \"100%%\" preset exactly (see "
+                              "set_advanced_features()'s own docstring). Same non-restriction "
+                              "note as --set-auto-dim-timeout above -- the app's own presets "
+                              "are 10/20/40/60/80/100, not enforced here.")
+    parser.add_argument("--set-fan-shutdown-enabled", default=None, choices=["true", "false"],
+                         help="Only usable with --by-serial. A WRITE. Radion-relevant (the "
+                              "app's own \"Fan Shutdown\" setting).")
+    parser.add_argument("--parse-dump", default=None, metavar="FILE",
+                         help="Standalone -- no device connection, no scanning, ignores every "
+                              "other flag. Parses an existing attribute-dump file (this "
+                              "library's own JSON from --dump-attributes above, or the app's "
+                              "own plain-text format -- auto-detected either way) and prints "
+                              "its contents enriched: resolved attribute names and decoded "
+                              "values where known, for offline inspection/debugging without "
+                              "the device present.")
     args = parser.parse_args()
+
+    if args.parse_dump:
+        # Standalone: no device, no event loop needed at all -- deliberately
+        # handled here, before asyncio.run(_run(args)), rather than as
+        # another branch inside _run(), since every other flag assumes a
+        # real connection is at least attempted.
+        with open(args.parse_dump) as f:
+            text = f.read()
+        values = parse_attribute_dump(text)
+        enriched = enrich_attribute_dump(values)
+        print(f"=== Parsed {len(enriched)} attribute(s) from {args.parse_dump!r} ===")
+        for entry in enriched:
+            label = f"{entry['attr_id']} ({entry['name']})" if entry["name"] else str(entry["attr_id"])
+            print(f"{label}: {entry['index']}")
+            for element in entry["elements"]:
+                if element["decoded"] is not None:
+                    print(f"\t{element['decoded']}  [raw: {element['raw_hex']}]")
+                else:
+                    interp = ", ".join(f"{k}={v}" for k, v in element["interpretations"].items())
+                    suffix = f"  ({interp})" if interp else ""
+                    print(f"\t{element['raw_hex']}{suffix}")
+        return
+
     asyncio.run(_run(args))
 
 

mobius/coap.py

@@ -24,14 +24,14 @@ Get/Set-attribute opcodes this library already uses. Carried inside the
 same outer FSCI frame (see mobius.frame) as everything else -- this is
 not a separate transport, just a different C2CI opcode.
 
-**Request** (`encode_coap_request()`): confirmed via `CoapRequest`'s first
-constructor --
+**Request** (`encode_coap_request()`): confirmed via reverse engineering
+the app's own equivalent request-construction logic --
 
     IPv6(16 bytes, REVERSED) + token(4) + method(2) + payload_length(2)
     + request_type(1) + payload
 
-**Response** (`decode_coap_response()`): confirmed via `CoapResponse`'s
-constructor --
+**Response** (`decode_coap_response()`): confirmed via reverse
+engineering the app's own equivalent response-construction logic --
 
     IPv6(16 bytes, NOT reversed) + token(4) + response_code(2)
     + payload_length(2) + request_type(1) + payload
@@ -41,7 +41,8 @@ doesn't) is easy to get backwards -- confirmed directly from the
 decompiled source, not a guess, so implemented exactly as traced.
 
 **The payload is just an existing FSCI request/response's raw bytes.**
-`CoapFsciRequest` in the decompile literally wraps `request.getData(true)`
+Confirmed via reverse engineering: the app's own CoAP request wraps an
+existing FSCI request's own raw data directly
 -- meaning none of this library's existing Get/Set attribute encoding
 needs reimplementing. This module only handles the CoAP envelope; the
 payload is built with mobius.frame's existing encode_get_attribute() /
@@ -70,8 +71,8 @@ lookups for these specific obscure constants). Rather than guess, this
 module only defines the CONFIRMED response codes (all literal, or
 independently cross-referenced) in CoapResponseCode -- an unrecognized
 code decodes to a plain int, not a guessed enum member, matching the real
-app's own graceful-fallback behavior (`getResponseCode()` returns
-`coap_Empty` for anything it doesn't recognize, rather than crashing).
+app's own graceful-fallback behavior for an unrecognized response code
+(falling back to `coap_Empty` rather than crashing).
 `Content` (matching the real "2.05 Content" success response to a GET,
 which we'll see constantly in practice) is the one value here confirmed
 only by strong pattern inference, not direct source confirmation -- flagged
@@ -97,9 +98,9 @@ COAP_OPCODE = 25
 # ack the app itself explicitly discards (see mobius.relay's module
 # docstring for the full trace) -- opcode 26 is a genuinely distinct
 # "indication," and matching it back to the request that triggered it is
-# done purely by CoAP token (confirmed via reverse engineering:
-# coapRequest.getToken() == coapResponse.getToken()), never by the outer
-# FSCI message ID.
+# done purely by CoAP token (confirmed via reverse engineering: the
+# request's own token must match the response's own token), never by
+# the outer FSCI message ID.
 COAP_INDICATION_OPCODE = 26
 
 
@@ -192,7 +193,8 @@ def encode_coap_request(
     `target_address` must be exactly 16 bytes (a full IPv6 address -- see
     mesh_local_address() for how to construct one for a specific device).
 
-    Confirmed wire format (CoapRequest's first constructor):
+    Confirmed wire format (via reverse engineering the app's own
+    equivalent request-construction logic):
     IPv6(16, REVERSED) + token(4) + method(2) + payload_length(2)
     + request_type(1) + payload.
     """
@@ -213,9 +215,11 @@ def decode_coap_response(data: bytes) -> Optional[CoapResponse]:
     """
     Parses a C2CI-opcode-25 response payload. Returns None if the data is
     too short to be a valid CoAP response (confirmed minimum: 25 bytes
-    before any payload, matching CoapResponse.validate()'s own check).
+    before any payload, matching the app's own equivalent validation
+    check).
 
-    Confirmed wire format (CoapResponse's constructor):
+    Confirmed wire format (via reverse engineering the app's own
+    response-parsing constructor):
     IPv6(16, NOT reversed) + token(4) + response_code(2) + payload_length(2)
     + request_type(1) + payload.
     """
@@ -234,7 +238,7 @@ def decode_coap_response(data: bytes) -> Optional[CoapResponse]:
     try:
         request_type = CoapRequestType(data[24])
     except ValueError:
-        request_type = CoapRequestType.Con  # matches Coap.RequestType.getRequestType()'s own fallback
+        request_type = CoapRequestType.Con  # matches the app's own confirmed fallback behavior
 
     payload = data[25:25 + payload_length]