python-mobius 0.1.4__py3-none-any.whl → 0.2.0__py3-none-any.whl

mobius/__init__.py

@@ -41,17 +41,27 @@ from .modifiers import (
 )
 from .power import ChannelPowerInfo, channel_percent_value
 from .pump_status import PumpFlowRange, BatteryBackupInfo, BoostedBatteryInfo
-from .device_status import GroupInfo, CalibrationInfo, MaintenanceInfo
+from .device_status import GroupInfo, CalibrationInfo, MaintenanceInfo, DeviceTimeInfo, MeshPeer
+from .coap import (
+    CoapRequestType, CoapMethod, CoapResponseCode, CoapResponse,
+    encode_coap_request, decode_coap_response, COAP_OPCODE, COAP_INDICATION_OPCODE,
+    next_coap_token,
+)
+from .mesh_address import (
+    mesh_local_prefix_from_own_address, is_valid_mesh_address,
+    build_rloc_address, extract_short_address, is_short_address_derived,
+)
+from .relay import RelayedMobiusDevice
 from .device import (
     MobiusDevice, MobiusPump, LightIntensityResult,
     SERVICE_GENERAL, CHAR_RX_DATA, CHAR_RX_FINAL, CHAR_TX_DATA, CHAR_TX_FINAL,
 )
 from .discovery import (
     scan_for_mobius_devices, scan_for_mobius_devices_with_info, group_by_pan_id,
-    dedupe_by_serial, find_device_by_serial,
+    dedupe_by_serial, find_device_by_serial, discover_mesh_peers_via_direct_connect,
 )
 
-__version__ = "0.1.4"
+__version__ = "0.2.0"
 
 __all__ = [
     "__version__",
@@ -87,11 +97,17 @@ __all__ = [
     # pump_status
     "PumpFlowRange", "BatteryBackupInfo", "BoostedBatteryInfo",
     # device_status
-    "GroupInfo", "CalibrationInfo", "MaintenanceInfo",
+    "GroupInfo", "CalibrationInfo", "MaintenanceInfo", "DeviceTimeInfo", "MeshPeer",
+    "CoapRequestType", "CoapMethod", "CoapResponseCode", "CoapResponse",
+    "encode_coap_request", "decode_coap_response", "COAP_OPCODE", "COAP_INDICATION_OPCODE",
+    "next_coap_token",
+    "mesh_local_prefix_from_own_address", "is_valid_mesh_address",
+    "build_rloc_address", "extract_short_address", "is_short_address_derived",
+    "RelayedMobiusDevice",
     # device
     "MobiusDevice", "MobiusPump", "LightIntensityResult",
     "SERVICE_GENERAL", "CHAR_RX_DATA", "CHAR_RX_FINAL", "CHAR_TX_DATA", "CHAR_TX_FINAL",
     # discovery
     "scan_for_mobius_devices", "scan_for_mobius_devices_with_info", "group_by_pan_id",
-    "dedupe_by_serial", "find_device_by_serial",
+    "dedupe_by_serial", "find_device_by_serial", "discover_mesh_peers_via_direct_connect",
 ]

mobius/cli.py

@@ -11,10 +11,150 @@ import argparse
 import asyncio
 
 from .device import MobiusDevice
+from .relay import RelayedMobiusDevice
+from .device_status import MeshPeer
+from .mesh_address import extract_short_address
 from .discovery import (
     scan_for_mobius_devices_with_info, group_by_pan_id, dedupe_by_serial,
-    find_device_by_serial,
+    find_device_by_serial, discover_mesh_peers_via_direct_connect,
 )
+from .schedule import SchedulePoint
+
+
+def _format_flags(point) -> str:
+    names = []
+    if point.has(SchedulePoint.FLAG_NIGHT):
+        names.append("NIGHT")
+    if point.has(SchedulePoint.FLAG_SUNRISE):
+        names.append("SUNRISE")
+    if point.has(SchedulePoint.FLAG_SUNSET):
+        names.append("SUNSET")
+    return f" [{', '.join(names)}]" if names else ""
+
+
+def _format_time(minutes: int) -> str:
+    return f"{minutes // 60:02d}:{minutes % 60:02d}"
+
+
+async def _dump_schedule(device: MobiusDevice, support: str) -> None:
+    """
+    Prints the FULL raw programmed schedule (every point, its time, its
+    flags, and its per-channel/mode values) -- not the interpolated
+    "current" value get_device_summary() already shows. Added specifically
+    so a schedule's actual point structure (needed to verify
+    is_night_segment()'s bracket-finding against real data) can be
+    inspected directly, instead of transcribed by hand from the app.
+    """
+    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):
+            channels = ", ".join(
+                f"{vid.name}={val}"
+                for vid, val in sorted(point.light.channels.items(), key=lambda x: x[0].name)
+            )
+            print(f"    {_format_time(point.time_minutes)}{_format_flags(point)}: {channels}")
+
+        lunar_enabled = await device.get_lunar_enabled()
+        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}")
+
+    elif support.startswith("pump"):
+        points = await device.get_pump_schedule(which=1)
+        for point in sorted(points, key=lambda p: p.time_minutes):
+            params = ", ".join(
+                f"{p.name}={v.hex() if isinstance(v, bytes) else (v.name if hasattr(v, 'name') else v)}"
+                for p, v in point.pump.params.items()
+            )
+            print(f"    {_format_time(point.time_minutes)}{_format_flags(point)}: "
+                  f"mode={point.pump.mode.name} {params}")
+    else:
+        print(f"    (schedule dumping not supported for support={support!r})")
+
+
+async def _debug_mesh_discovery(device) -> list:
+    """
+    Verbose, step-by-step version of discover_mesh_peers() for CLI
+    debugging. discover_mesh_peers() deliberately fails soft to an empty
+    list on ANY error -- the right behavior for production use (e.g.
+    ha-mobius shouldn't crash because a device doesn't support this), but
+    that makes it useless for diagnosing WHY no peers were found. This
+    surfaces each step's raw result or exception instead, and returns
+    whatever peers it manages to construct (same shape as
+    discover_mesh_peers()'s return value) so callers needing the actual
+    peer list (e.g. --relay-target) don't need a second, separate fetch.
+    """
+    from .constants import C2Attribute, Model
+    from .mesh_address import is_valid_mesh_address, mesh_local_prefix_from_own_address, build_rloc_address
+    import struct
+
+    print("  Step 1: MeshLocalAddresses (1005)...")
+    try:
+        own_address_raw = await device.get_attribute(C2Attribute.MeshLocalAddresses)
+    except Exception as e:
+        print(f"    FAILED: {e!r}")
+        print("    This attribute isn't supported at all by this device -- strong "
+              "evidence it doesn't run Thread (or at least doesn't expose this "
+              "attribute), which would mean relay isn't available on this hardware, "
+              "independent of anything about this implementation.")
+        return []
+    if not own_address_raw:
+        print("    Returned an EMPTY response (not an error, but no data either).")
+        return []
+    raw_addr = own_address_raw[0]
+    print(f"    Raw response: {raw_addr.hex()} ({len(raw_addr)} bytes)")
+    if not is_valid_mesh_address(raw_addr):
+        print("    This is all-zero -- the attribute IS supported, but this device "
+              "isn't currently part of an active Thread network. Different from the "
+              "case above: this suggests Thread support exists but isn't active right "
+              "now, rather than not existing at all.")
+        return []
+    prefix = mesh_local_prefix_from_own_address(raw_addr)
+    print(f"    Valid. Derived mesh-local prefix: {prefix.hex()}")
+
+    arrays = {}
+    for name, attr in [
+        ("SerialNumberArray", C2Attribute.SerialNumberArray),
+        ("DeviceModelArray", C2Attribute.DeviceModelArray),
+        ("ShortAddressArray", C2Attribute.ShortAddressArray),
+    ]:
+        print(f"  Step 2: {name} ({attr.value})...")
+        try:
+            values = await device.get_attribute(attr, index=0, count=0xFFFF)
+        except Exception as e:
+            print(f"    FAILED: {e!r}")
+            arrays[name] = []
+            continue
+        print(f"    Returned {len(values)} element(s): {[v.hex() for v in values]}")
+        arrays[name] = values
+
+    peers = []
+    for serial_bytes, model_bytes, short_bytes in zip(
+        arrays.get("SerialNumberArray", []), arrays.get("DeviceModelArray", []),
+        arrays.get("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]
+        try:
+            model = Model(model_raw)
+        except ValueError:
+            model = None
+        short_address = struct.unpack("<H", short_bytes[:2])[0]
+        peers.append(MeshPeer(
+            serial=serial, model_raw=model_raw, model=model,
+            short_address=short_address, address=build_rloc_address(prefix, short_address),
+        ))
+    return peers
 
 
 async def _run(args) -> None:
@@ -36,6 +176,70 @@ async def _run(args) -> None:
                 summary = await mdevice.get_device_summary()
                 for k, v in summary.items():
                     print(f"  {k}: {v}")
+                if args.dump_schedule:
+                    await _dump_schedule(mdevice, summary.get("support", ""))
+
+                if args.dump_mesh_peers or args.relay_target:
+                    print("\n=== Thread mesh peer discovery ===")
+                    peers = await _debug_mesh_discovery(mdevice)
+                    if not peers:
+                        print("  No peers found -- see the step-by-step output above for "
+                              "exactly which stage this failed at, rather than just that it "
+                              "failed. See documentation/09-thread-coap-relay.md.")
+                    else:
+                        print()
+                        for peer in peers:
+                            model_name = peer.model.name if peer.model else f"unknown({peer.model_raw})"
+                            print(f"  {peer.serial}  model={model_name}  "
+                                  f"short_address={peer.short_address:#06x}  address={peer.address.hex()}")
+
+                if args.relay_target:
+                    print(f"\n=== Relaying to {args.relay_target!r} through {args.by_serial!r} ===")
+                    target_peer = next((p for p in peers if p.serial == args.relay_target), None)
+                    if target_peer is None:
+                        print(f"  Not found via {args.by_serial!r}'s own peer-tracking (expected "
+                              f"without a Cowboy hub) -- trying a brief direct connection to "
+                              f"{args.relay_target!r} instead to learn its address...")
+                        found_target = await find_device_by_serial(
+                            args.relay_target, timeout=args.timeout, adapter=args.adapter,
+                        )
+                        if found_target is None:
+                            print(f"  No device currently advertising serial "
+                                  f"{args.relay_target!r} found.")
+                        else:
+                            target_device, target_info = found_target
+                            target_address = None
+                            try:
+                                async with MobiusDevice(
+                                    target_device, connect_timeout=args.connect_timeout,
+                                ) as tdevice:
+                                    target_address = await tdevice.get_own_mesh_address()
+                            except Exception as e:
+                                print(f"  Failed to connect directly to "
+                                      f"{args.relay_target!r}: {e}")
+                            if target_address is None:
+                                print(f"  {args.relay_target!r} didn't report a valid mesh "
+                                      f"address -- cannot relay to it.")
+                            else:
+                                target_peer = 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,
+                                )
+                                print(f"  Learned address directly: {target_address.hex()}")
+
+                    if target_peer is not None:
+                        relayed = RelayedMobiusDevice(mdevice, target_peer, debug=args.debug_relay)
+                        try:
+                            relayed_summary = await relayed.get_device_summary()
+                            for k, v in relayed_summary.items():
+                                print(f"  {k}: {v}")
+                            print(f"\n  Relay succeeded. Compare this against a direct "
+                                  f"`--by-serial {args.relay_target}` run to confirm they match.")
+                        except Exception as e:
+                            print(f"  relay failed: {e}")
         except Exception as e:
             print("  failed to connect/read:", e)
         return
@@ -64,6 +268,22 @@ async def _run(args) -> None:
     if args.scan_only:
         return
 
+    if args.build_peer_map:
+        print("\n=== Building mesh peer map via direct connect (no Cowboy hub needed) ===")
+        peers = await discover_mesh_peers_via_direct_connect(
+            found, adapter=args.adapter, connect_timeout=args.connect_timeout,
+        )
+        if not peers:
+            print("  No peers found -- none of the scanned devices reported a valid "
+                  "mesh address when connected to directly. See documentation/"
+                  "09-thread-coap-relay.md.")
+        else:
+            for peer in peers:
+                model_name = peer.model.name if peer.model else f"unknown({peer.model_raw})"
+                print(f"  {peer.serial}  model={model_name}  "
+                      f"short_address={peer.short_address:#06x}  address={peer.address.hex()}")
+        return
+
     print("\n=== Full device summaries (connects to each) ===")
     for device, info in found:
         print(f"--- {device.address} ({device.name}) ---")
@@ -94,6 +314,8 @@ async def _run(args) -> None:
                 summary = await mdevice.get_device_summary()
                 for k, v in summary.items():
                     print(f"  {k}: {v}")
+                if args.dump_schedule:
+                    await _dump_schedule(mdevice, summary.get("support", ""))
         except Exception as e:
             print("  failed to connect/read:", e)
 
@@ -117,6 +339,52 @@ def main() -> None:
                               "to whichever device is CURRENTLY advertising this serial number, "
                               "regardless of its BLE address. Useful for testing serial-based "
                               "reconnection against real hardware whose address may have changed.")
+    parser.add_argument("--dump-schedule", action="store_true",
+                         help="Also print each connected device's FULL raw programmed schedule "
+                              "(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.")
+    parser.add_argument("--dump-mesh-peers", action="store_true",
+                         help="Only usable with --by-serial. After connecting, calls "
+                              "discover_mesh_peers() on it and prints every other device it "
+                              "knows about over the Thread mesh (serial/model/short address/"
+                              "IPv6) -- an empty result here is itself informative (this device "
+                              "may not support Thread mesh at all, or isn't currently part of "
+                              "an active one). See documentation/09-thread-coap-relay.md.")
+    parser.add_argument("--relay-target", default=None, metavar="SERIAL",
+                         help="Only usable with --by-serial (the device you connect to becomes "
+                              "the relay gateway). Tries to find this serial among the "
+                              "gateway's own reported mesh peers first (requires a Cowboy hub); "
+                              "if not found there, falls back to a brief separate direct "
+                              "connection to the target itself to learn its address (no "
+                              "Cowboy hub needed for this path -- confirmed via real hardware "
+                              "testing to be necessary, since the peer-tracking attributes "
+                              "are Cowboy-hub-specific). Either way, once an address is known, "
+                              "relays a full get_device_summary() read to it via CoAP through "
+                              "the gateway and prints the result -- run a separate direct "
+                              "`--by-serial <this serial>` command to confirm the two match. "
+                              "This is the actual validation this whole relay implementation "
+                              "needs against real hardware.")
+    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, decoded attribute status/values), "
+                              "plus every frame the gateway receives during the wait (both the "
+                              "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("--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 "
+                              "(serial/model/short address/IPv6) -- the alternative to "
+                              "--dump-mesh-peers when there's no dedicated Cowboy hub device "
+                              "(confirmed via real hardware testing to be required for that "
+                              "attribute-array-based approach). This is the practical way to "
+                              "learn every device's mesh address once, so you can later keep "
+                              "only one connection open and relay to the rest. See "
+                              "documentation/09-thread-coap-relay.md.")
     args = parser.parse_args()
     asyncio.run(_run(args))
 

mobius/coap.py

@@ -0,0 +1,253 @@
+"""
+CoAP (RFC 7252) protocol primitives, ported from com.c2.comm.Coap and
+com.c2.comm.requests.coap.{CoapRequest,CoapFsciRequest} /
+com.c2.comm.responses.coap.CoapResponse in the decompiled app.
+
+## Why this exists
+
+The official app doesn't maintain a direct BLE connection to every device
+in a tank. When it needs to talk to a device it isn't directly connected
+to, it wraps the request in CoAP and sends it through whichever device it
+*is* connected to (the "gateway"), which forwards it over the underlying
+Thread mesh network and relays the response back. Confirmed directly in
+the decompiled source (`Comm.java`), not inferred:
+
+    if (commDevice.equals(request.getTarget())) {
+        // direct: send over the existing BLE connection as-is
+    } else if (iPv6 != null) {
+        // relay: wrap in CoAP, address it to the target's mesh IPv6,
+        // send through commDevice (the connected gateway)
+    } else {
+        // no known address for the target -- fail
+    }
+
+## Wire format
+
+A new C2CI opcode (confirmed literal: **25**), alongside the `0x17`/`0x18`
+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 --
+
+    IPv6(16 bytes, REVERSED) + token(4) + method(2) + payload_length(2)
+    + request_type(1) + payload
+
+**Response** (`decode_coap_response()`): confirmed via `CoapResponse`'s
+constructor --
+
+    IPv6(16 bytes, NOT reversed) + token(4) + response_code(2)
+    + payload_length(2) + request_type(1) + payload
+
+The asymmetric byte-reversal (request reverses the address, response
+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)`
+-- 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() /
+encode_set_attribute() / decode_attribute_response(), same as a direct
+(non-relayed) request.
+
+## Confidence notes on enum values
+
+Some `Coap.ResponseCode` values in the decompile are JADX symbolic
+substitutions (obfuscated numeric constants resolved back to unrelated
+Android/Google library field names, e.g. `TypedValues.PositionType.
+TYPE_SIZE_PERCENT`) rather than plain literals. Where a value was already
+independently confirmed elsewhere in this project (for a completely
+different attribute, but the same underlying Java constant), that
+confirmed value is used here too -- `InternalServerError` (500, via
+`ServiceStarter.ERROR_UNKNOWN`) and `BadGateway`/`ProxyingNotSupported`
+(502/512, via `TypedValues.PositionType.TYPE_DRAWPATH`/`TYPE_SIZE_PERCENT`).
+Note `ProxyingNotSupported=512` does NOT fit the otherwise-clean RFC 7252
+`class*100+detail` pattern every other value in this enum follows (5.05
+would predict 505) -- confirmed via cross-reference, not just pattern
+completion, but flagged as numerically surprising and worth treating with
+some caution until seen on real hardware.
+
+The remaining symbolic values (`Content`, `Unauthorized`, `BadOption`,
+`Forbidden`, `NotImplemented`, `ServiceUnavailable`, `GatewayTimeout`)
+could NOT be independently confirmed (third-party library classes not
+present in this project's decompile, and not findable via public source
+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).
+`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
+explicitly below, and worth confirming against real hardware traffic.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Optional
+
+# Confirmed literal: the C2CI opcode used for CoAP-wrapped requests/responses,
+# alongside the existing Get(0x17)/Set(0x18) attribute opcodes.
+COAP_OPCODE = 25
+
+# Confirmed from BaseConnection.smali's handleIndication() (a method JADX
+# couldn't decompile to Java -- traced from raw bytecode instead): the
+# REAL CoAP relay response arrives as a completely separate message on
+# THIS opcode, not COAP_OPCODE (25). Opcode 25's confirm is a bare 1-byte
+# 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 (lambda$getSentRequest$6:
+# coapRequest.getToken() == coapResponse.getToken()), never by the outer
+# FSCI message ID.
+COAP_INDICATION_OPCODE = 26
+
+
+# Matches Coap.currentToken's confirmed starting value in the decompile
+# (a simple static int starting at 100) -- the exact starting value
+# doesn't matter functionally (any value unique per outstanding request
+# works), matched here purely for closest fidelity to the real app.
+_next_coap_token = 100
+
+
+def next_coap_token() -> int:
+    """Simple monotonically-increasing CoAP token generator (module-global),
+    matching the pattern already used for FSCI message IDs
+    (mobius.frame.next_message_id)."""
+    global _next_coap_token
+    _next_coap_token += 1
+    return _next_coap_token
+
+
+class CoapRequestType(IntEnum):
+    """Confirmed literal values from Coap.RequestType."""
+    Con = 0   # Confirmable
+    Non = 1   # Non-confirmable
+    Ack = 2   # Acknowledgement
+    Rst = 3   # Reset
+
+
+class CoapMethod(IntEnum):
+    """Confirmed literal values from Request.Method (plain literals in the
+    decompile, no symbolic substitution)."""
+    GET = 1
+    POST = 2
+    PUT = 3
+    DELETE = 4
+
+
+class CoapResponseCode(IntEnum):
+    """
+    Confirmed response codes only -- see this module's docstring for which
+    values are plain literals, which are independently cross-referenced
+    from elsewhere in this project, and which (Content) is confirmed only
+    by strong pattern inference rather than direct source confirmation.
+    Deliberately does NOT include every RFC 7252 code -- unrecognized
+    codes decode to a plain int via decode_coap_response(), not a guessed
+    enum member.
+    """
+    Empty = 0                    # literal
+    Created = 201                # literal
+    Deleted = 202                # literal
+    Valid = 203                  # literal
+    Changed = 204                # literal
+    Content = 205                # INFERRED (pattern match only, not source-confirmed -- see module docstring)
+    BadRequest = 400             # literal
+    NotFound = 404                # literal
+    MethodNotAllowed = 405        # literal
+    NotAcceptable = 406           # literal
+    PreconditionFailed = 412      # literal
+    RequestEntityTooLarge = 413   # literal
+    UnsupportedContentFormat = 415  # literal
+    InternalServerError = 500     # CONFIRMED (cross-referenced via ServiceStarter.ERROR_UNKNOWN)
+    BadGateway = 502              # CONFIRMED (cross-referenced via TypedValues.PositionType.TYPE_DRAWPATH)
+    ProxyingNotSupported = 512    # CONFIRMED (cross-referenced via TypedValues.PositionType.TYPE_SIZE_PERCENT) -- numerically surprising, see module docstring
+
+
+@dataclass
+class CoapResponse:
+    """A decoded CoAP-wrapped response, as parsed by decode_coap_response()."""
+    address: bytes           # 16-byte IPv6, as received (NOT reversed -- see module docstring)
+    token: int
+    response_code: "CoapResponseCode | int"  # int if the code isn't a recognized CoapResponseCode member
+    request_type: CoapRequestType
+    payload: bytes           # the inner FSCI response bytes -- decode with mobius.frame as usual
+
+
+def encode_coap_request(
+    target_address: bytes,
+    token: int,
+    method: CoapMethod,
+    payload: bytes,
+    request_type: CoapRequestType = CoapRequestType.Con,
+) -> bytes:
+    """
+    Builds the C2CI-opcode-25 payload for a CoAP-wrapped request, to be
+    sent through a connected gateway device addressed to a device
+    elsewhere in the mesh. `payload` is the raw bytes of an ordinary
+    (non-CoAP) FSCI request -- e.g. the output of
+    mobius.frame.encode_get_attribute() -- exactly as it would be sent
+    directly, just wrapped in this envelope instead of sent as-is.
+
+    `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):
+    IPv6(16, REVERSED) + token(4) + method(2) + payload_length(2)
+    + request_type(1) + payload.
+    """
+    if len(target_address) != 16:
+        raise ValueError(f"target_address must be exactly 16 bytes, got {len(target_address)}")
+    reversed_address = target_address[::-1]
+    return (
+        reversed_address
+        + struct.pack("<i", token)
+        + struct.pack("<h", method.value)
+        + struct.pack("<h", len(payload))
+        + bytes([request_type.value])
+        + payload
+    )
+
+
+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).
+
+    Confirmed wire format (CoapResponse's constructor):
+    IPv6(16, NOT reversed) + token(4) + response_code(2) + payload_length(2)
+    + request_type(1) + payload.
+    """
+    if len(data) < 25:
+        return None
+
+    address = data[0:16]
+    token = struct.unpack("<i", data[16:20])[0]
+    code_raw = struct.unpack("<h", data[20:22])[0]
+    try:
+        response_code: "CoapResponseCode | int" = CoapResponseCode(code_raw)
+    except ValueError:
+        response_code = code_raw  # unrecognized code -- matches the app's own graceful fallback
+
+    payload_length = struct.unpack("<h", data[22:24])[0]
+    try:
+        request_type = CoapRequestType(data[24])
+    except ValueError:
+        request_type = CoapRequestType.Con  # matches Coap.RequestType.getRequestType()'s own fallback
+
+    payload = data[25:25 + payload_length]
+
+    return CoapResponse(
+        address=address,
+        token=token,
+        response_code=response_code,
+        request_type=request_type,
+        payload=payload,
+    )

mobius/constants.py

@@ -271,6 +271,23 @@ class C2Attribute(IntEnum):
     AcclimationStartIntensity = 904
     AcclimationStartTime = 905
     LunarPhasesEnabled = 907
+    Epoch = 201
+    RTCTime = 219
+    # Thread mesh peer discovery -- see documentation/09-thread-coap-relay.md
+    # for the full protocol trace. MeshLocalAddresses confirmed via
+    # PeripheralConnection.java; the three parallel arrays confirmed via
+    # CowboyNetworkProcess.java (index-matched: serialArray[i]/
+    # modelArray[i]/shortArray[i] all refer to the same peer).
+    MeshLocalAddresses = 1005
+    ShortAddressArray = 3700
+    SerialNumberArray = 3701
+    DeviceModelArray = 3702
+    # A fourth parallel array giving each peer's real BLE MAC address --
+    # confirmed present (CowboyNetworkProcess.java references it
+    # alongside the three above) but not used by discover_mesh_peers()
+    # (not needed for CoAP relay, which addresses peers by Thread IPv6,
+    # not BLE address). Included for completeness/future use.
+    BladeBleAddressArray = 3714
     InsolationEnabled = 912
     MaxPower = 1504
     Ramp = 1505