python-mobius 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

mobius/__init__.py

@@ -43,15 +43,16 @@ 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
+from .device_status import GroupInfo, CalibrationInfo, MaintenanceInfo, DeviceTimeInfo, MeshPeer, Tank
 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,
+    mesh_local_prefix_from_own_address, mesh_local_prefix_from_mlprefix,
+    is_valid_mesh_address, build_rloc_address, extract_short_address,
+    is_short_address_derived,
 )
 from .relay import RelayedMobiusDevice
 from .device import (
@@ -61,9 +62,10 @@ from .device import (
 from .discovery import (
     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,
 )
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "__version__",
@@ -101,11 +103,11 @@ __all__ = [
     # pump_status
     "PumpFlowRange", "BatteryBackupInfo", "BoostedBatteryInfo",
     # device_status
-    "GroupInfo", "CalibrationInfo", "MaintenanceInfo", "DeviceTimeInfo", "MeshPeer",
+    "GroupInfo", "CalibrationInfo", "MaintenanceInfo", "DeviceTimeInfo", "MeshPeer", "Tank",
     "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",
+    "mesh_local_prefix_from_own_address", "mesh_local_prefix_from_mlprefix", "is_valid_mesh_address",
     "build_rloc_address", "extract_short_address", "is_short_address_derived",
     "RelayedMobiusDevice",
     # device
@@ -114,4 +116,5 @@ __all__ = [
     # discovery
     "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",
 ]

mobius/cli.py

@@ -1,8 +1,12 @@
 """
 Command-line entrypoint: `mobius-scan`.
 
-Scans for Mobius devices, groups them by pan_id (no connection required),
-then connects to each and prints a full device summary.
+By default, scans for Mobius devices, groups them into tanks by pan_id
+(read from BLE advertisements alone -- no connection needed), then
+connects to ONE of them to dump real mesh addresses for its whole
+network. `--scan-only` skips that connection step for a genuinely
+connection-free run. Everything past that (full per-device summaries,
+relay testing) is opt-in via flags -- see `mobius-scan --help`.
 """
 
 from __future__ import annotations
@@ -16,7 +20,7 @@ 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, discover_mesh_peers_via_direct_connect,
+    find_device_by_serial, discover_mesh_peers_via_direct_connect, discover_tank,
 )
 from .schedule import SchedulePoint
 
@@ -79,20 +83,86 @@ async def _dump_schedule(device: MobiusDevice, support: str) -> None:
 
 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
+    Verbose, step-by-step version of discover_mesh_peers_auto() for CLI
+    debugging. Both discover_networked_thread_devices() and
+    discover_mesh_peers() deliberately fail 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.
+    discover_mesh_peers_auto()'s return value) so callers needing the
+    actual peer list (e.g. --relay-target) don't need a second, separate
+    fetch.
+
+    Tries NetworkedThreadDevices/MLPrefix first (Step 0) -- the newer,
+    more generally-available mechanism, not gated to a Cowboy hub -- and
+    only falls through to the older, Cowboy-hub-specific
+    MeshLocalAddresses/three-parallel-arrays steps if that finds nothing,
+    matching discover_mesh_peers_auto()'s own priority order.
     """
     from .constants import C2Attribute, Model
-    from .mesh_address import is_valid_mesh_address, mesh_local_prefix_from_own_address, build_rloc_address
+    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,
+    )
     import struct
 
+    print("  Step 0: MLPrefix (2128) + NetworkedThreadDevices (1001)...")
+    try:
+        mlprefix_raw = await device.get_attribute(C2Attribute.MLPrefix)
+    except Exception as e:
+        print(f"    MLPrefix FAILED: {e!r}")
+        mlprefix_raw = None
+    if mlprefix_raw and len(mlprefix_raw[0]) == 24:
+        prefix = mesh_local_prefix_from_mlprefix(mlprefix_raw[0])
+        print(f"    MLPrefix OK. Derived mesh-local prefix: {prefix.hex()}")
+        try:
+            entries_raw = await device.get_attribute(
+                C2Attribute.NetworkedThreadDevices, index=0, count=0xFFFF,
+            )
+        except Exception as e:
+            print(f"    NetworkedThreadDevices FAILED: {e!r}")
+            entries_raw = []
+        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
+            address = prefix + entry[0:8]
+            age = struct.unpack("<i", entry[8:12])[0]
+            model_raw = struct.unpack("<h", entry[12:14])[0]
+            try:
+                serial = entry[14:28].decode("ascii").rstrip("\x00")
+            except UnicodeDecodeError:
+                continue
+            if not serial or serial == "00000000000000":
+                continue
+            try:
+                model = Model(model_raw)
+            except ValueError:
+                model = None
+            peers.append(MeshPeer(
+                serial=serial, model_raw=model_raw, model=model,
+                short_address=extract_short_address(address), address=address, age=age,
+            ))
+        if peers:
+            print(f"    Parsed {len(peers)} peer(s) via NetworkedThreadDevices -- "
+                  f"skipping the older Cowboy-hub-specific steps below.")
+            return peers
+        print("    No usable peers from NetworkedThreadDevices -- falling back to "
+              "the older, Cowboy-hub-specific mechanism below.")
+    elif mlprefix_raw is not None:
+        print(f"    MLPrefix returned an unexpected length "
+              f"({len(mlprefix_raw[0])} bytes, expected 24) -- falling back to "
+              f"the older, Cowboy-hub-specific mechanism below.")
+    else:
+        print("    Falling back to the older, Cowboy-hub-specific mechanism below.")
+
     print("  Step 1: MeshLocalAddresses (1005)...")
     try:
         own_address_raw = await device.get_attribute(C2Attribute.MeshLocalAddresses)
@@ -190,16 +260,20 @@ async def _run(args) -> None:
                         print()
                         for peer in peers:
                             model_name = peer.model.name if peer.model else f"unknown({peer.model_raw})"
+                            age_suffix = f"  age={peer.age}" if peer.age is not None else ""
                             print(f"  {peer.serial}  model={model_name}  "
-                                  f"short_address={peer.short_address:#06x}  address={peer.address.hex()}")
+                                  f"short_address={peer.short_address:#06x}  "
+                                  f"address={peer.address.hex()}{age_suffix}")
 
                 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...")
+                        print(f"  Not found via {args.by_serial!r}'s own peer-tracking "
+                              f"(neither NetworkedThreadDevices nor the older Cowboy-hub-"
+                              f"specific mechanism reported it) -- trying a brief direct "
+                              f"connection to {args.relay_target!r} instead to learn its "
+                              f"address...")
                         found_target = await find_device_by_serial(
                             args.relay_target, timeout=args.timeout, adapter=args.adapter,
                         )
@@ -254,8 +328,16 @@ async def _run(args) -> None:
     # documentation/12-device-identity-and-address-stability.md.
     found = dedupe_by_serial(found)
 
-    print("=== Pan ID groups (from advertisements, no connection needed) ===")
-    for pan_id, members in group_by_pan_id(found).items():
+    # pan_id is read straight from each device's advertisement -- no
+    # connection needed at all -- and is the fast, local approximation of
+    # "which tank is this device part of" (the same approximation
+    # discover_tank()'s own docstring documents for its own,
+    # connection-based, richer mechanism: the app's own Tank grouping is
+    # account-level and cloud-synced, with no local/BLE equivalent to
+    # read directly).
+    groups = group_by_pan_id(found)
+    print("=== Tanks (grouped by pan_id from advertisements, no connection needed) ===")
+    for pan_id, members in groups.items():
         label = f"{pan_id:#06x}" if pan_id is not None else "unknown"
         print(f"  pan_id {label}:")
         for device, info in members:
@@ -268,6 +350,72 @@ async def _run(args) -> None:
     if args.scan_only:
         return
 
+    # Part of the actual default now, not behind a flag -- connects to
+    # ONE device (any one with a parsed serial; which one doesn't
+    # matter, since the point is just "ask whatever's reachable about
+    # its own network") and runs the same verbose discovery
+    # --dump-mesh-peers uses, so a plain `mobius-scan` with zero flags
+    # still shows real mesh addresses, not just the pan_id/serial/model
+    # the advertisement alone carries. --scan-only skips this (and
+    # everything after) if a genuinely connection-free run is wanted.
+    connectable = [(d, i) for d, i in found if i and i.serial]
+    if not connectable:
+        print("\n=== Network addresses ===\n  No device with a parsed serial to connect through.")
+    else:
+        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,
+                                     connect_timeout=args.connect_timeout) as mdevice:
+                peers = await _debug_mesh_discovery(mdevice)
+        except Exception as e:
+            print(f"  failed to connect: {e}")
+            peers = []
+        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})"
+                age_suffix = f"  age={peer.age}" if peer.age is not None else ""
+                print(f"  {peer.serial}  model={model_name}  "
+                      f"short_address={peer.short_address:#06x}  "
+                      f"address={peer.address.hex()}{age_suffix}")
+
+    if not (args.dump_tanks or args.full_summaries or args.build_peer_map):
+        return
+
+    if args.dump_tanks:
+        print("\n=== Tank details (connects to one device per pan_id group) ===")
+        for pan_id, members in groups.items():
+            label = f"{pan_id:#06x}" if pan_id is not None else "unknown"
+            connectable = [(d, i) for d, i in members if i and i.serial]
+            if not connectable:
+                print(f"  pan_id {label}: no device with a parsed serial to connect through -- skipped")
+                continue
+            device, info = connectable[0]
+            print(f"  pan_id {label} (connecting through {info.serial})...")
+            try:
+                async with MobiusDevice(serial=info.serial, adapter=args.adapter,
+                                         connect_timeout=args.connect_timeout) as mdevice:
+                    tank = await discover_tank(mdevice)
+            except Exception as e:
+                print(f"    failed to connect/discover: {e}")
+                continue
+            if tank.prefix is None:
+                print(f"    {info.serial} didn't report a valid mesh address -- "
+                      f"can't map this tank's devices/addresses this way.")
+                continue
+            print(f"    prefix={tank.prefix.hex()}")
+            for peer in tank.peers:
+                model_name = peer.model.name if peer.model else f"unknown({peer.model_raw})"
+                age_suffix = f"  age={peer.age}" if peer.age is not None else ""
+                print(f"    {peer.serial}  model={model_name}  "
+                      f"short_address={peer.short_address:#06x}  "
+                      f"address={peer.address.hex()}{age_suffix}")
+
     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(
@@ -282,6 +430,8 @@ async def _run(args) -> None:
                 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 not args.full_summaries:
         return
 
     print("\n=== Full device summaries (connects to each) ===")
@@ -333,7 +483,21 @@ def main() -> None:
     parser.add_argument("--connect-timeout", type=float, default=30.0,
                          help="Per-device connect timeout in seconds (default: 30.0)")
     parser.add_argument("--scan-only", action="store_true",
-                         help="Only scan/group by pan_id; don't connect to any device.")
+                         help="Stops after the pan_id listing -- skips the network-address dump "
+                              "(which connects to one device) that otherwise runs by default, "
+                              "and everything else. The only genuinely connection-free mode.")
+    parser.add_argument("--dump-tanks", action="store_true",
+                         help="Like the network-address dump that already runs by default, but "
+                              "for EVERY pan_id group found, not just one -- useful if multiple "
+                              "genuinely separate tanks/networks are in range at once. Connects "
+                              "to one device per group and calls discover_tank() on each, "
+                              "printing the full mesh-address/age for every device in that tank. "
+                              "Skips any pan_id group with no device carrying a parsed serial to "
+                              "connect through.")
+    parser.add_argument("--full-summaries", action="store_true",
+                         help="Connects to EVERY scanned device in turn and prints a full "
+                              "get_device_summary() for each -- the most thorough option, and "
+                              "the slowest for anything beyond a couple of devices.")
     parser.add_argument("--by-serial", default=None, metavar="SERIAL",
                          help="Skip the normal scan/group flow and instead resolve + connect "
                               "to whichever device is CURRENTLY advertising this serial number, "
@@ -348,25 +512,28 @@ def main() -> None:
                               "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.")
+                              "discover_mesh_peers_auto() on it and prints every other device "
+                              "it knows about over the Thread mesh (serial/model/short "
+                              "address/IPv6/age) -- tries the newer NetworkedThreadDevices "
+                              "mechanism first (not gated to a Cowboy hub), falling back to "
+                              "the older MeshLocalAddresses/three-arrays mechanism (Cowboy-hub-"
+                              "specific) only if that finds nothing. An empty result from both "
+                              "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.")
+                              "gateway's own reported mesh peers first (via "
+                              "discover_mesh_peers_auto() -- NetworkedThreadDevices first, then "
+                              "the older Cowboy-hub-specific mechanism); if not found either "
+                              "way, falls back to a brief separate direct connection to the "
+                              "target itself to learn its address. 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 "
@@ -378,12 +545,13 @@ def main() -> None:
     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 "
+                              "(serial/model/short address/IPv6) -- the last-resort fallback "
+                              "when --dump-mesh-peers' two attribute-based mechanisms both come "
+                              "back empty (neither NetworkedThreadDevices nor the older "
+                              "three-array mechanism supported/populated on this hardware). "
+                              "This is the practical way to learn every device's mesh address "
+                              "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.")
     args = parser.parse_args()
     asyncio.run(_run(args))

mobius/coap.py

@@ -1,7 +1,6 @@
 """
-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.
+CoAP (RFC 7252) protocol primitives, confirmed via reverse engineering the
+app's own CoAP model.
 
 ## Why this exists
 
@@ -9,17 +8,14 @@ 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
-    }
+Thread mesh network and relays the response back. Confirmed directly via
+reverse engineering the app's own dispatch logic, not inferred: if the
+target device is the one already directly connected over BLE, the app
+sends the request as-is over that existing connection; otherwise, if a
+mesh IPv6 address is known for the target, it wraps the request in CoAP,
+addresses it to the target's mesh IPv6, and sends it through the
+connected gateway device; if neither applies (no known address for the
+target), the request fails.
 
 ## Wire format
 
@@ -54,16 +50,13 @@ encode_set_attribute() / decode_attribute_response(), same as a direct
 
 ## 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
+Some `Coap.ResponseCode` values are symbolic substitutions surfaced during
+reverse engineering (obfuscated numeric constants resolved back to
+unrelated Android/Google library field names) 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
+different attribute, but the same underlying constant), that
+confirmed value is used here too -- `InternalServerError` (500) and `BadGateway`/`ProxyingNotSupported`
+(502/512, via the same symbolic-substitution technique). 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
@@ -96,20 +89,21 @@ from typing import Optional
 # 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
+# Confirmed via reverse engineering the app's own indication-handling
+# logic (a method the decompiler couldn't resolve to readable Java -- traced
+# from the 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:
+# done purely by CoAP token (confirmed via reverse engineering:
 # 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
+# Matches the app's own 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.
@@ -165,9 +159,9 @@ class CoapResponseCode(IntEnum):
     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
+    InternalServerError = 500     # CONFIRMED (cross-referenced via symbolic-substitution technique)
+    BadGateway = 502              # CONFIRMED (cross-referenced via symbolic-substitution technique)
+    ProxyingNotSupported = 512    # CONFIRMED (cross-referenced via symbolic-substitution technique) -- numerically surprising, see module docstring
 
 
 @dataclass

mobius/constants.py

@@ -61,7 +61,8 @@ PUMP_PRIMITIVES_EXPERIMENTAL = {PrimitiveType.CoffeeV1}
 
 
 class Model(IntEnum):
-    """Device model identifiers. Confirmed literal values from M.Model
+    """Device model identifiers. Confirmed literal values via reverse
+    engineering the app's own model-identifier enum
     (a curated subset -- the full enum covers ~100 models across EcoTech
     Marine, AquaIllumination, Neptune Systems, NYOS, and Hera product lines;
     add entries here as needed)."""
@@ -108,7 +109,8 @@ class Model(IntEnum):
     Coffee2 = 397            # "Quantum 220/300" (NYOS)
 
 
-# Ported from M.Model.getManufacturer(). The decompiled version branches on
+# Confirmed via reverse engineering the app's own manufacturer-lookup logic.
+# The decompiled version branches on
 # enum *ordinal* against a hardcoded position list (the full ~100-entry
 # Model enum's index 1-37 range, plus a few extras, all map to "EcoTech
 # Marine"); since this library only implements a curated subset of Model,
@@ -210,11 +212,12 @@ class ErrorState(IntEnum):
 class C2Attribute(IntEnum):
     """Attribute IDs used with Get/Set requests. Every value here is a
     directly-confirmed literal (either a plain literal in the decompile, or
-    resolved through a JADX symbolic-constant substitution back to the real
+    resolved through a symbolic-constant substitution surfaced during
+    reverse engineering back to the real
     integer -- see documentation/03-attributes-and-opcodes.md), EXCEPT
-    Schedule1 which required tracing through Firebase's
-    ServiceStarter.ERROR_UNKNOWN=500 to resolve (also fully confirmed, just
-    via an extra hop)."""
+    Schedule1 which required tracing through an extra hop via an unrelated
+    library constant to resolve (also fully confirmed, just
+    via that extra hop)."""
     AttributeTableVersion = 0
     FirmwareVersion = 1
     HardwareRevision = 2
@@ -275,19 +278,31 @@ class C2Attribute(IntEnum):
     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]/
+    # reverse engineering the app's own connection-setup logic; the three
+    # parallel arrays confirmed via reverse engineering the app's own
+    # Cowboy-hub network-setup logic (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
+    # confirmed present (the app's own Cowboy-hub network-setup logic 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
+    # A second, better mesh-peer-discovery mechanism -- confirmed via
+    # reverse engineering the app's own tank-setup logic, NOT gated to a
+    # Cowboy hub (checked via a generic isSupported() call, unlike the
+    # three arrays above). NetworkedThreadDevices is a "get all elements"
+    # list of peer entries, each one containing that peer's model, serial,
+    # mesh address, and an "age" value in a single fetch -- see
+    # discover_networked_thread_devices()'s docstring for the confirmed
+    # byte layout of each entry, and mesh_local_prefix_from_mlprefix()
+    # for why MLPrefix's own 24-byte response only uses its first 8 bytes.
+    NetworkedThreadDevices = 1001
+    MLPrefix = 2128
     InsolationEnabled = 912
     MaxPower = 1504
     Ramp = 1505
@@ -318,7 +333,8 @@ class PhysicalValueID(IntEnum):
 
 
 class VisualID(IntEnum):
-    """Light channel identifiers. Confirmed literal values from M.VisualID."""
+    """Light channel identifiers. Confirmed literal values via reverse
+    engineering the app's own channel-identifier enum."""
     Unknown = 0
     Brightness = 1
     CoolWhite = 16
@@ -736,5 +752,8 @@ PUMP_MODE_PARAMS: dict[PumpMode, list[PumpParam]] = {
 }
 
 PUMP_TIME_OFFSET_PARAMS = {PumpParam.Time, PumpParam.StartTime, PumpParam.EndTime}
-# Confirmed: androidx.recyclerview.widget.ItemTouchHelper.Callback.DEFAULT_SWIPE_ANIMATION_DURATION
+# Confirmed via reverse engineering: resolved through the same
+# symbolic-substitution artifact documented in
+# documentation/03-attributes-and-opcodes.md, back to a real, unrelated
+# library constant equal to 250.
 PUMP_TIME_OFFSET = 250

mobius/crc.py

@@ -1,8 +1,8 @@
 """
 CRC16 (table-driven, seed 0xFFFF) used on every Mobius wire frame.
 
-Ported from the decompiled com.c2.comm.utilities.Crc class. The table below
-is Java's original signed-short constants converted to unsigned 16-bit for
+Confirmed via reverse engineering the app's own CRC implementation. The table below
+uses the original signed-short constants converted to unsigned 16-bit for
 Python arithmetic. Verified byte-for-byte against real captured packets --
 see documentation/02-framing-and-crc.md.
 """
@@ -41,7 +41,7 @@ CRC16_TABLE = [v & 0xFFFF for v in _CRC16_TABLE_SIGNED]
 
 
 def crc16(data: bytes, seed: int = 0xFFFF) -> int:
-    """CRC16 over `data`, matching com.c2.comm.utilities.Crc.crc16()."""
+    """CRC16 over `data`, confirmed via reverse engineering the app's own CRC implementation."""
     crc = seed & 0xFFFF
     for b in data:
         idx = (b ^ (crc >> 8)) & 0xFF