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

mobius/__init__.py

@@ -26,22 +26,32 @@ from .constants import (
     Model, MODEL_MANUFACTURER, manufacturer_for_model,
     ErrorState, C2Attribute, PhysicalValueID, VisualID,
     SceneID, OperationState, FsciStatus,
-    PumpMode, RampType, PumpParam, PUMP_PARAM_SIZE, PUMP_MODE_PARAMS,
+    PumpMode, PumpOverrideMode, RampType, PumpParam, PUMP_PARAM_SIZE, PUMP_MODE_PARAMS,
+    FirmwareType, FIRMWARE_TYPE_LABELS_ETM, HardwareInfo,
 )
 from .schedule import (
     LightPrimitive, SchedulePoint, interpolate_light_schedule,
     PumpPrimitiveValue, PumpSchedulePoint, get_active_pump_block,
 )
 from .manufacturer import MOBIUS_COMPANY_ID, MobiusAdvertisement, parse_manufacturer_data
+from .modifiers import (
+    AcclimationInfo, is_night_segment,
+    julian_day_from_date, lunar_days_into_phase, lunar_percent_reduction,
+    LUNAR_CYCLE_SCALERS,
+)
+from .power import ChannelPowerInfo, channel_percent_value
+from .pump_status import PumpFlowRange, BatteryBackupInfo, BoostedBatteryInfo
+from .device_status import GroupInfo, CalibrationInfo, MaintenanceInfo
 from .device import (
-    MobiusDevice, MobiusPump,
+    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,
 )
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 
 __all__ = [
     "__version__",
@@ -61,15 +71,27 @@ __all__ = [
     "Model", "MODEL_MANUFACTURER", "manufacturer_for_model",
     "ErrorState", "C2Attribute", "PhysicalValueID", "VisualID",
     "SceneID", "OperationState", "FsciStatus",
-    "PumpMode", "RampType", "PumpParam", "PUMP_PARAM_SIZE", "PUMP_MODE_PARAMS",
+    "PumpMode", "PumpOverrideMode", "RampType", "PumpParam", "PUMP_PARAM_SIZE", "PUMP_MODE_PARAMS",
+    "FirmwareType", "FIRMWARE_TYPE_LABELS_ETM", "HardwareInfo",
     # schedule
     "LightPrimitive", "SchedulePoint", "interpolate_light_schedule",
     "PumpPrimitiveValue", "PumpSchedulePoint", "get_active_pump_block",
     # manufacturer
     "MOBIUS_COMPANY_ID", "MobiusAdvertisement", "parse_manufacturer_data",
+    # modifiers
+    "AcclimationInfo", "is_night_segment",
+    "julian_day_from_date", "lunar_days_into_phase", "lunar_percent_reduction",
+    "LUNAR_CYCLE_SCALERS",
+    # power
+    "ChannelPowerInfo", "channel_percent_value",
+    # pump_status
+    "PumpFlowRange", "BatteryBackupInfo", "BoostedBatteryInfo",
+    # device_status
+    "GroupInfo", "CalibrationInfo", "MaintenanceInfo",
     # device
-    "MobiusDevice", "MobiusPump",
+    "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",
 ]

mobius/cli.py

@@ -11,15 +11,45 @@ import argparse
 import asyncio
 
 from .device import MobiusDevice
-from .discovery import scan_for_mobius_devices_with_info, group_by_pan_id
+from .discovery import (
+    scan_for_mobius_devices_with_info, group_by_pan_id, dedupe_by_serial,
+    find_device_by_serial,
+)
 
 
 async def _run(args) -> None:
+    if args.by_serial:
+        # Focused path for testing serial-based reconnection directly --
+        # useful for confirming this actually works against real hardware
+        # whose BLE address may have changed since it was last seen. See
+        # documentation/12-device-identity-and-address-stability.md.
+        print(f"=== Resolving current address for serial {args.by_serial!r} ===")
+        found = await find_device_by_serial(args.by_serial, timeout=args.timeout, adapter=args.adapter)
+        if found is None:
+            print(f"No device currently advertising serial {args.by_serial!r} found.")
+            return
+        device, info = found
+        print(f"  currently at {device.address}  model={info.model.name if info.model else info.model_raw}")
+        try:
+            async with MobiusDevice(serial=args.by_serial, adapter=args.adapter,
+                                     connect_timeout=args.connect_timeout) as mdevice:
+                summary = await mdevice.get_device_summary()
+                for k, v in summary.items():
+                    print(f"  {k}: {v}")
+        except Exception as e:
+            print("  failed to connect/read:", e)
+        return
+
     found = await scan_for_mobius_devices_with_info(timeout=args.timeout, adapter=args.adapter)
     if not found:
         print("No Mobius devices found. Make sure BLE is on and devices are nearby.")
         return
 
+    # Guards against seeing the same device twice under two different
+    # addresses if caught mid-address-rotation during this one scan -- see
+    # 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():
         label = f"{pan_id:#06x}" if pan_id is not None else "unknown"
@@ -35,10 +65,32 @@ async def _run(args) -> None:
         return
 
     print("\n=== Full device summaries (connects to each) ===")
-    for device, _info in found:
+    for device, info in found:
         print(f"--- {device.address} ({device.name}) ---")
         try:
-            async with MobiusDevice(device, connect_timeout=args.connect_timeout) as mdevice:
+            # BUG FIX: passing both `device` (the scan-time BLEDevice) and
+            # `serial` here does NOT actually get you serial-based
+            # robustness -- MobiusDevice.connect() always uses a directly-
+            # provided BLEDevice on the FIRST connect, and this loop only
+            # ever calls connect() once per device (one `async with` block,
+            # not a reused instance), so the serial fallback path never
+            # triggered. That scan-time BLEDevice can be tens of seconds
+            # stale by the time we reach the last device in a long scan --
+            # exactly the "device disappeared" symptom reported against
+            # real hardware. Passing `serial=` ALONE (omitting `device`
+            # entirely) forces a fresh resolution right before each
+            # connect, instead of trusting a potentially-stale reference.
+            # Costs one extra short scan per device with a serial; falls
+            # back to the original (scan-time) BLEDevice only when we
+            # don't have a serial to resolve with. See documentation/
+            # 12-device-identity-and-address-stability.md.
+            serial = info.serial if info else None
+            if serial is not None:
+                mobius_device = MobiusDevice(serial=serial, adapter=args.adapter,
+                                              connect_timeout=args.connect_timeout)
+            else:
+                mobius_device = MobiusDevice(device, connect_timeout=args.connect_timeout)
+            async with mobius_device as mdevice:
                 summary = await mdevice.get_device_summary()
                 for k, v in summary.items():
                     print(f"  {k}: {v}")
@@ -60,6 +112,11 @@ def main() -> None:
                          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.")
+    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, "
+                              "regardless of its BLE address. Useful for testing serial-based "
+                              "reconnection against real hardware whose address may have changed.")
     args = parser.parse_args()
     asyncio.run(_run(args))
 

mobius/constants.py

@@ -252,10 +252,26 @@ class C2Attribute(IntEnum):
     BatteryBackupSpeed = 706
     MinimumGallonsPerHour = 707
     MaximumGallonsPerHour = 708
+    GroupMaster = 900
+    IsGroupMaster = 911
+    IsCalibrated = 1300
+    LastCalibrationTime = 1304
+    MinCalibratedSpeed = 1308
+    MaxCalibratedSpeed = 1309
+    RecommendedMaintenanceInterval = 1400
+    MaintenanceTimer = 1401
+    LastMaintenanceTime = 1402
+    MaintenanceDue = 1403
     BoostedBatteryPower = 803
     BoostedBatteryPowerOnTime = 804
     BoostedBatteryPowerOffTime = 805
     SupportedColorChannels = 901
+    AcclimationEnabled = 902
+    AcclimationPeriod = 903
+    AcclimationStartIntensity = 904
+    AcclimationStartTime = 905
+    LunarPhasesEnabled = 907
+    InsolationEnabled = 912
     MaxPower = 1504
     Ramp = 1505
     NormalPower = 1513
@@ -402,6 +418,93 @@ class RampType(IntEnum):
     Linear = 3
 
 
+class FirmwareType(IntEnum):
+    """
+    Confirmed literal values from M.FirmwareType -- the sub-index used
+    with C2Attribute.FirmwareVersion (a Get with index=0, count=0xFFFF
+    returns one entry per firmware component the device has, same "get
+    all elements" pattern as MaxPower/NormalPower/SupportedColorChannels).
+    """
+    Unknown = 0
+    OS = 1
+    Bootloader = 2
+    MainMicroOS = 3
+    MainMicroBootloader = 4
+    QCA4020Firmware = 5
+    QCA4020FileSystem = 6
+    QCA4020M4F = 7
+    QCA4020M0 = 8
+    QCA4020WLAN = 9
+    XMC1402Firmware = 10
+    LEDClusterMicro = 11
+    Esp32C3Firmware = 12
+    Esp32H2Firmware = 13
+    CoffeeMotorDriverFirmware = 14
+    Esp32S3Firmware = 15
+    Esp32C6Firmware = 16
+
+
+# Ported directly from M.FirmwareType.name(Model) -- the EcoTech Marine
+# (isEtm()) branch specifically, confirmed via real hardware to exactly
+# match the app's own displayed labels (a VorTech pump showed Radio/Radio
+# Bootloader/Product OS/Product Bootloader; a Radion light showed Product
+# OS/Product Bootloader/Radio Firmware/Filesystem/Radio OS/Radio/WLAN/
+# Firmware). AquaIllumination (non-ETM) models use a different mapping in
+# the same Java method, not ported here since it's outside what's been
+# verified against real hardware.
+FIRMWARE_TYPE_LABELS_ETM: dict = {
+    FirmwareType.Unknown: "Firmware",
+    FirmwareType.LEDClusterMicro: "Firmware",
+    FirmwareType.Esp32C3Firmware: "Firmware",
+    FirmwareType.Esp32H2Firmware: "Firmware",
+    FirmwareType.Esp32S3Firmware: "Firmware",
+    FirmwareType.Esp32C6Firmware: "Firmware",
+    FirmwareType.OS: "Radio",
+    FirmwareType.Bootloader: "Radio Bootloader",
+    FirmwareType.MainMicroOS: "Product OS",
+    FirmwareType.MainMicroBootloader: "Product Bootloader",
+    FirmwareType.QCA4020Firmware: "Radio Firmware",
+    FirmwareType.QCA4020FileSystem: "Filesystem",
+    FirmwareType.QCA4020M4F: "Radio OS",
+    FirmwareType.QCA4020M0: "Radio",
+    FirmwareType.QCA4020WLAN: "WLAN",
+}
+
+
+class HardwareInfo(IntEnum):
+    """
+    Confirmed literal values from M.HardwareInfo -- the sub-index used
+    with C2Attribute.HardwareRevision, same "get all elements" pattern as
+    FirmwareVersion above. Unlike FirmwareVersion, no dot-joined-string
+    display convention is confirmed for these fields (Color/Revision/
+    ProductType/RadioType/MotorType/Segments read more like small
+    integer/enum codes than version numbers) -- returned as raw bytes,
+    not formatted, until that's confirmed.
+    """
+    Unknown = 0
+    Color = 1
+    Revision = 2
+    ProductType = 3
+    RadioType = 4
+    MotorType = 5
+    Segments = 6
+
+
+class PumpOverrideMode(IntEnum):
+    """
+    Confirmed literal values from M.PumpOverrideMode. Confirmed only as a
+    SET target in the decompile (writing None to exit override mode after
+    the pump-side calibration flow) -- never actually read anywhere in the
+    app. The wire format for reading it (plain byte enum) is a reasonable
+    inference from the enum's own definition and how every other
+    byte-backed enum attribute in this protocol works, not something
+    directly observed being read.
+    """
+    None_ = 0   # trailing underscore: "None" is a Python keyword
+    AllOff = 1
+    Manual = 2
+
+
 class PumpParam(IntEnum):
     """Named fields that can appear in a PumpPrimitive, per pump mode.
     Not a wire-format enum itself -- just internal bookkeeping for