Add read-only account diagnostic script

Every bitfield in enums.py is inherited from someone else's reverse
engineering and so far tested only against a fake hub built from the same
assumptions. This checks those inferences against real hardware: it prints
the decoded view of each valve beside its raw payload, flags mode bits the
library does not recognize, and lists unmapped fields.

Never sends a command, and redacts anything token-shaped so the output is
safe to share when reporting a mismatch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: pfeffed

examples/diagnose.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Connect to a real FloLogic account and report what the cloud actually sends.
+
+Everything this library knows about FloLogic's wire format was inferred from
+someone else's reverse engineering. This script checks those inferences against
+real hardware: it prints the decoded view of each valve next to the raw fields,
+and calls out any field the library does not map.
+
+    export FLOLOGIC_EMAIL=you@example.com
+    export FLOLOGIC_PASSWORD=...
+    uv run python examples/diagnose.py
+
+Read-only: it never sends a command. Pass --watch to keep the connection open
+and print pushed updates as they arrive, which is the way to confirm that
+keepalive pings hold the session up.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+import sys
+from typing import Any
+
+from pyflologic import (
+    Account,
+    DeviceIdentity,
+    FloLogicClient,
+    FloLogicError,
+    NotificationSetting,
+)
+
+# Raw valve fields this library exposes through a typed property. Anything else
+# the cloud sends is worth a look -- it may be something worth modeling.
+MAPPED_FIELDS = {
+    "id",
+    "uuid",
+    "valveFriendlyName",
+    "combinedName",
+    "name",
+    "mode",
+    "flowState",
+    "online",
+    "isZGateway",
+    "deviceTypeName",
+    "softwareVersion",
+    "valveAndCpFirmwareVersionString",
+    "currentFlow",
+    "temperature",
+    "batteryLevel",
+    "signalStrength",
+    "dripRate",
+    "homeIntervalTime",
+    "awayIntervalTime",
+    "bypassTime",
+    "autoAwayTime",
+    "lowTemperatureAlert",
+    "lowTemperatureLimit",
+    "preAlertNoticeInterval",
+    "noFlowNoticeInterval",
+    "lastNewFlow",
+}
+
+SECRET_HINTS = ("password", "token", "secret", "apikey")
+
+
+def redact(key: str, value: Any) -> Any:
+    """Hide anything that looks like a credential, so output is shareable."""
+    if any(hint in key.lower() for hint in SECRET_HINTS):
+        return "<redacted>"
+    return value
+
+
+def describe_valve(valve: Any) -> None:
+    """Print the decoded view of one valve, then its unmapped raw fields."""
+    print(f"\n{'=' * 70}")
+    print(f"{valve.name}  [{valve.valve_id}]")
+    print("=" * 70)
+    print(f"  model            : {valve.model}")
+    print(f"  firmware         : {valve.firmware_version}")
+    print(f"  controllable     : {valve.is_controllable} (gateway={valve.is_gateway})")
+    print(f"  online           : {valve.is_online}")
+    print(f"  raw mode         : {int(valve.mode)}")
+    print(f"  decoded flags    : {valve.mode.flag_names}")
+    if valve.mode.unknown_bits:
+        print(f"  !! UNKNOWN BITS  : {valve.mode.unknown_bits:#x} <-- unmapped")
+    print(f"  control mode     : {valve.control_mode}")
+    print(f"  status           : {valve.status}")
+    print(f"  flow state       : {valve.flow_state}")
+    print(f"  water flowing    : {valve.is_water_flowing}")
+    print(f"  current flow     : {valve.current_flow_oz_per_min} oz/min")
+    print(f"  temperature      : {valve.temperature_f} F")
+    print(f"  battery          : {valve.battery_percent} %")
+    print(f"  signal           : {valve.signal_strength_dbm} dBm")
+    print("  --- settings ---")
+    print(f"  flow sensitivity : {valve.flow_sensitivity_oz_per_min} oz/min")
+    print(f"  home limit       : {valve.home_limit_minutes} min")
+    print(f"  away limit       : {valve.away_limit_minutes} min")
+    print(f"  bypass time      : {valve.bypass_minutes} min")
+    print(f"  auto away        : {valve.auto_away_hours} h")
+    print(f"  low temp alert   : {valve.low_temp_alert_f} F")
+    print(f"  low temp shutoff : {valve.low_temp_shutoff_f} F")
+    print(f"  pre-alert        : {valve.pre_alert_minutes} min")
+    print("  --- derived ---")
+    print(f"  flow started     : {valve.flow_started_at}")
+    print(f"  elapsed          : {valve.flow_elapsed_seconds()} s")
+    print(f"  shutoff in       : {valve.shutoff_countdown_seconds()} s")
+    print(f"  pre-alert window : {valve.is_in_pre_alert_window()}")
+
+    extra = {
+        key: redact(key, value)
+        for key, value in sorted(valve.raw.items())
+        if key not in MAPPED_FIELDS and value not in (None, "", [], {})
+    }
+    if extra:
+        print(f"\n  unmapped fields ({len(extra)}):")
+        for key, value in extra.items():
+            rendered = str(value)
+            if len(rendered) > 60:
+                rendered = f"{rendered[:57]}..."
+            print(f"    {key:<38} = {rendered}")
+
+
+async def main() -> int:
+    """Connect, describe the account, and optionally watch for pushes."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--watch",
+        type=float,
+        metavar="SECONDS",
+        help="stay connected this long and print pushed updates",
+    )
+    parser.add_argument("--debug", action="store_true", help="log protocol frames")
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.debug else logging.INFO,
+        format="%(asctime)s %(levelname)-7s %(name)s: %(message)s",
+    )
+
+    email = os.environ.get("FLOLOGIC_EMAIL")
+    password = os.environ.get("FLOLOGIC_PASSWORD")
+    if not email or not password:
+        print("Set FLOLOGIC_EMAIL and FLOLOGIC_PASSWORD first.", file=sys.stderr)
+        return 2
+
+    client = FloLogicClient(
+        email=email,
+        password=password,
+        device=DeviceIdentity.generate("pyflologic-diagnose"),
+    )
+
+    try:
+        await client.async_connect()
+    except FloLogicError as err:
+        print(f"Could not connect: {err}", file=sys.stderr)
+        return 1
+
+    try:
+        account = client.account
+        print(f"\nAccount: {account.user.email} [{account.user.user_id}]")
+        print(
+            f"Devices: {len(account.valves)} "
+            f"({len(account.controllable_valves)} controllable)"
+        )
+
+        for valve in account.valves.values():
+            describe_valve(valve)
+
+        print(f"\n{'=' * 70}\nNotification preferences\n{'=' * 70}")
+        accesses = await client.async_refresh_accesses()
+        for valve_id, access in accesses.items():
+            name = account.valves[valve_id].name if valve_id in account.valves else "?"
+            enabled = [
+                setting.name
+                for setting in NotificationSetting
+                if setting.name and access.wants(setting)
+            ]
+            print(f"  {name} [{valve_id}]: {enabled or 'none'}")
+            print(
+                f"    advance shutoff alerts: "
+                f"{access.wants(NotificationSetting.ADVANCE_SHUTOFF)}"
+            )
+
+        print(f"\n{'=' * 70}\nScheduler\n{'=' * 70}")
+        for valve_id, valve in account.controllable_valves.items():
+            events = await client.async_fetch_scheduler(valve_id)
+            active = [event for event in events if event.is_active]
+            print(f"  {valve.name}: {len(active)} active / {len(events)} rows")
+
+        print(f"\n{'=' * 70}\nRecent notifications\n{'=' * 70}")
+        for notification in (await client.async_fetch_notifications())[:10]:
+            print(f"  {notification.created_at}  {notification.message}")
+
+        if args.watch:
+            print(f"\nWatching for {args.watch:g}s -- run water to see a push...")
+
+            def on_update(updated: Account) -> None:
+                for valve in updated.controllable_valves.values():
+                    print(
+                        f"  [push] {valve.name}: {valve.status} "
+                        f"flowing={valve.is_water_flowing} "
+                        f"rate={valve.current_flow_oz_per_min}"
+                    )
+
+            client.add_listener(on_update)
+            await asyncio.sleep(args.watch)
+            print("Done. If the session survived, keepalive is working.")
+    finally:
+        await client.async_disconnect()
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(main()))