python-mobius 0.5.0__py3-none-any.whl → 0.7.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,
@@ -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, AdvancedFeatures, VectraInfo, CoffeeInfo, MaintenanceInfo, DeviceTimeInfo, MeshPeer, Tank, LunarPhaseInfo
+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,
@@ -56,7 +56,7 @@ from .mesh_address import (
 )
 from .relay import RelayedMobiusDevice
 from .device import (
-    MobiusDevice, MobiusPump, LightIntensityResult,
+    MobiusDevice, MobiusPump, LightIntensityResult, LightPollResult, FullPollResult,
     SERVICE_GENERAL, CHAR_RX_DATA, CHAR_RX_FINAL, CHAR_TX_DATA, CHAR_TX_FINAL,
 )
 from .discovery import (
@@ -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.5.0"
+__version__ = "0.7.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",
@@ -103,7 +109,7 @@ __all__ = [
     # pump_status
     "PumpFlowRange", "BatteryBackupInfo", "BoostedBatteryInfo",
     # device_status
-    "GroupInfo", "CalibrationInfo", "AdvancedFeatures", "VectraInfo", "CoffeeInfo", "MaintenanceInfo", "DeviceTimeInfo", "MeshPeer", "Tank", "LunarPhaseInfo",
+    "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",
@@ -111,10 +117,13 @@ __all__ = [
     "build_rloc_address", "extract_short_address", "is_short_address_derived",
     "RelayedMobiusDevice",
     # device
-    "MobiusDevice", "MobiusPump", "LightIntensityResult",
+    "MobiusDevice", "MobiusPump", "LightIntensityResult", "LightPollResult", "FullPollResult",
     "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", "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:
@@ -373,12 +374,93 @@ async def _run(args) -> None:
                             print(f"  reboot() FAILED: {e}")
 
                 if args.set_time_to_now:
-                    print(f"\n=== set_time_to_now() on {args.by_serial!r} (WRITE -- Epoch) ===")
-                    try:
-                        await mdevice.set_time_to_now()
-                        print(f"  set_time_to_now() on {args.by_serial!r} succeeded.")
-                    except Exception as e:
-                        print(f"  set_time_to_now() FAILED: {e}")
+                    # 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)
@@ -620,9 +702,12 @@ def main() -> None:
     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 directly-connected device (Epoch, reserved-byte group=1 "
+                              "on the target device (Epoch, reserved-byte group=1 "
                               "-- required for the write to be accepted at all, confirmed "
-                              "against real hardware). See that method's own docstring, and "
+                              "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",
@@ -645,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]