zcc-helper 3.8.1.dev1__tar.gz → 3.9.dev1__tar.gz

{zcc_helper-3.8.1.dev1/zcc_helper.egg-info → zcc_helper-3.9.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zcc_helper
-Version: 3.8.1.dev1
+Version: 3.9.dev1
 Summary: ZIMI ZCC helper module
 Author: Mark Hannon
 Author-email: mark.hannon@gmail.com

zcc_helper-3.9.dev1/tests/test_controller.py

@@ -0,0 +1,171 @@
+import asyncio
+import unittest
+
+from zcc.controller import ControlPoint
+from zcc.description import ControlPointDescription
+from zcc.device import ControlPointDevice
+from zcc.manufacture_info import ControlPointManufactureInfo
+
+
+class ControllerFirmwareTest(unittest.TestCase):
+
+    def setUp(self):
+        self.loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self.loop)
+        description = ControlPointDescription(host="127.0.0.1", port=12121)
+        self.controller = ControlPoint(description)
+
+    def tearDown(self):
+        self.controller.disconnect()
+        self.loop.close()
+
+    def test_flags_devices_behind_same_model_and_hwversion(self):
+        older = self._add_device(
+            "old_1",
+            ControlPointManufactureInfo(
+                identifier="old",
+                model="2GV Switch",
+                hwVersion="4",
+                firmwareVersion="1.20.50",
+            ),
+        )
+        self._add_device(
+            "new_1",
+            ControlPointManufactureInfo(
+                identifier="new",
+                model="2GV Switch",
+                hwVersion="4",
+                firmwareVersion="3.3.4.2",
+            ),
+        )
+
+        self.controller._ControlPoint__update_obsolete_firmware()
+
+        self.assertEqual(
+            self.controller.obsolete_firmware,
+            {"old_1": "1.20.50 < 3.3.4.2"},
+        )
+        self.assertEqual(self.controller.obsolete_firmware_devices, [older])
+        self.assertEqual(self.controller.obsolete_devices, [older])
+
+    def test_separates_peer_groups_by_hwversion(self):
+        self._add_device(
+            "older_1",
+            ControlPointManufactureInfo(
+                identifier="older",
+                model="2GV Switch",
+                hwVersion="4",
+                firmwareVersion="1.20.50",
+            ),
+        )
+        self._add_device(
+            "different_hw_1",
+            ControlPointManufactureInfo(
+                identifier="different_hw",
+                model="2GV Switch",
+                hwVersion="5",
+                firmwareVersion="9.9.9",
+            ),
+        )
+
+        self.controller._ControlPoint__update_obsolete_firmware()
+
+        self.assertEqual(self.controller.obsolete_firmware, {})
+
+    def test_flags_missing_manufacture_info(self):
+        device = ControlPointDevice(self.controller, "missing_1")
+        self.controller.devices[device.identifier] = device
+
+        self.controller._ControlPoint__update_obsolete_firmware()
+
+        self.assertEqual(
+            self.controller.obsolete_firmware,
+            {"missing_1": "missing manufacture_info"},
+        )
+
+    def test_flags_missing_firmware_version(self):
+        self._add_device(
+            "missing_fw_1",
+            ControlPointManufactureInfo(
+                identifier="missing_fw",
+                model="2GV Switch",
+                hwVersion="4",
+                firmwareVersion=None,
+            ),
+        )
+
+        self.controller._ControlPoint__update_obsolete_firmware()
+
+        self.assertEqual(
+            self.controller.obsolete_firmware,
+            {"missing_fw_1": "missing firmwareVersion"},
+        )
+
+    def test_describe_reports_obsolete_firmware_warning(self):
+        old_device = self._add_device(
+            "old_1",
+            ControlPointManufactureInfo(
+                identifier="old",
+                model="2GV Switch",
+                hwVersion="4",
+                firmwareVersion="1.20.50",
+            ),
+        )
+        old_device.properties = {"name": "Entry Switch", "roomName": "Hall"}
+        self._add_device(
+            "new_1",
+            ControlPointManufactureInfo(
+                identifier="new",
+                model="2GV Switch",
+                hwVersion="4",
+                firmwareVersion="3.3.4.2",
+            ),
+        )
+
+        self.controller._ControlPoint__update_obsolete_firmware()
+
+        description = self.controller.describe()
+
+        self.assertIn("obsolete firmware", description)
+        self.assertIn("fw=1.20.50, fw<3.3.4.2", description)
+
+    def test_tracks_missing_states_and_reports_inline_marker(self):
+        missing_device = self._add_device(
+            "missing_1",
+            ControlPointManufactureInfo(
+                identifier="missing",
+                model="2GV Switch",
+                hwVersion="4",
+                firmwareVersion="3.3.4.2",
+            ),
+        )
+        missing_device.properties = {
+            "name": "Entry Dimmer",
+            "roomName": "Hall",
+        }
+
+        self.controller._ControlPoint__update_missing_states()
+
+        self.assertEqual(
+            self.controller.missing_states,
+            {"missing_1": "missing states"},
+        )
+        self.assertEqual(self.controller.warnings, [missing_device])
+
+        description = self.controller.describe()
+
+        self.assertIn("incomplete data", description)
+        self.assertIn("{ MISSING }", description)
+
+    def _add_device(self, identifier, manufacture_info):
+        device = ControlPointDevice(self.controller, identifier)
+        device.manufacture_info = manufacture_info
+        self.controller.devices[identifier] = device
+        self.controller.manufacture_infos[manufacture_info.identifier] = (
+            manufacture_info
+        )
+        return device
+
+
+if __name__ == '__main__':
+    unittest.main()

zcc_helper-3.9.dev1/tests/test_manufacture_info.py

@@ -0,0 +1,35 @@
+import unittest
+
+from zcc.manufacture_info import (
+    ControlPointManufactureInfo,
+    compare_firmware_versions,
+    normalise_firmware_version,
+)
+
+
+class ManufactureInfoTest(unittest.TestCase):
+
+    def test_normalise_firmware_version(self):
+        self.assertEqual(normalise_firmware_version("2.10.4.2"), (2, 10, 4, 2))
+        self.assertIsNone(normalise_firmware_version("invalid"))
+
+    def test_compare_firmware_versions(self):
+        self.assertEqual(compare_firmware_versions("2.10.4.2", "2.14.4.2"), -1)
+        self.assertEqual(compare_firmware_versions("1.2", "1.2.0"), 0)
+        self.assertEqual(compare_firmware_versions("3.0", "2.9.9"), 1)
+
+    def test_cohort_key_requires_model_and_hwversion(self):
+        manufacture_info = ControlPointManufactureInfo(
+            identifier="device",
+            model="2GV Switch",
+            hwVersion="4",
+            firmwareVersion="3.3.4.2",
+        )
+        self.assertEqual(manufacture_info.cohort_key, ("2GV Switch", "4"))
+
+        manufacture_info.hwVersion = None
+        self.assertIsNone(manufacture_info.cohort_key)
+
+
+if __name__ == '__main__':
+    unittest.main()

{zcc_helper-3.8.1.dev1 → zcc_helper-3.9.dev1}/zcc/constants.py

@@ -9,4 +9,4 @@ APP_ID = "ZvWqWJQB"
 APP_TOKEN = "3422ecbb-cf6a-404c-b3dc-2023dd213535"
 
 NAME = "zcc_helper"
-VERSION = "3.8.1dev1"
+VERSION = "3.9dev1"

{zcc_helper-3.8.1.dev1 → zcc_helper-3.9.dev1}/zcc/controller.py

@@ -23,7 +23,11 @@ from zcc.constants import LEVEL_BY_VERBOSITY, NAME, VERSION
 from zcc.description import ControlPointDescription
 from zcc.device import ControlPointDevice
 from zcc.errors import ControlPointError
-from zcc.manufacture_info import ControlPointManufactureInfo
+from zcc.manufacture_info import (
+    ControlPointManufactureInfo,
+    compare_firmware_versions,
+    normalise_firmware_version,
+)
 from zcc.protocol import ControlPointProtocol
 from zcc.socket import ControlPointSocket
 from zcc.watchdog import ControlPointWatchdog
@@ -69,6 +73,9 @@ class ControlPoint:
 
         self.devices: Dict[ControlPointDevice] = {}
         self.manufacture_infos: Dict[ControlPointManufactureInfo] = {}
+        self.missing_states: Dict[str, str] = {}
+        self.obsolete_firmware: Dict[str, str] = {}
+        self.obsolete_firmware_baselines: Dict[tuple[str, str], str] = {}
 
         self.actions_received = 0
         self.manufacture_info_received = 0
@@ -148,7 +155,34 @@ class ControlPoint:
     @property
     def warnings(self) -> List[ControlPointDevice]:
         """Return a list of devices with empty or missing states (incomplete data)."""
-        return [device for device in self.devices.values() if not device.states]
+
+        return [
+            self.devices[identifier]
+            for identifier in self.missing_states
+            if identifier in self.devices
+        ]
+
+    @property
+    def missing_state_devices(self) -> List[ControlPointDevice]:
+        """Backward-compatible alias for devices flagged with missing states."""
+
+        return self.warnings
+
+    @property
+    def obsolete_firmware_devices(self) -> List[ControlPointDevice]:
+        """Return a list of devices flagged with obsolete firmware."""
+
+        return [
+            self.devices[identifier]
+            for identifier in self.obsolete_firmware
+            if identifier in self.devices
+        ]
+
+    @property
+    def obsolete_devices(self) -> List[ControlPointDevice]:
+        """Backward-compatible alias for devices flagged with obsolete firmware."""
+
+        return self.obsolete_firmware_devices
 
     async def connect(self, fast: bool = False) -> bool:
         """Connect to ZCC, build device table and subscribe to updates"""
@@ -314,13 +348,18 @@ class ControlPoint:
             description += header + "\n"
 
             # Add warnings section if there are devices with incomplete data
-            if self.warnings:
-                description += "| WARNING: One or more devices have incomplete data.   Check for WARNINGS and upgrade firmware with Zimi app                         |\n"
+            if self.missing_states:
+                description += "| WARNING: One or more devices have missing states. Check for state None below and upgrade firmware with Zimi app                  |\n"
+                description += "+" + "-" * 130 + "+\n"
+            if self.obsolete_firmware:
+                description += "| WARNING: One or more devices have obsolete firmware. Check for fw<new_version below and upgrade firmware with Zimi app           |\n"
                 description += "+" + "-" * 130 + "+\n"
 
             description_details = []
             for key in self.manufacture_infos:
-                description_details.append(self.manufacture_infos[key].describe())
+                description_details.append(
+                    self.__describe_manufacture_info(self.manufacture_infos[key])
+                )
             for key in self.devices:
                 description_details.append(self.devices[key].describe())
             description_details.sort()
@@ -427,10 +466,12 @@ class ControlPoint:
 
         for key in self.devices.keys():
             identifier_msb = self.devices[key].identifier.split("_")[0]
-            if self.manufacture_infos[identifier_msb]:
-                self.devices[key].manufacture_info = self.manufacture_infos[
-                    identifier_msb
-                ]
+            manufacture_info = self.manufacture_infos.get(identifier_msb)
+            if manufacture_info:
+                self.devices[key].manufacture_info = manufacture_info
+
+        self.__update_missing_states()
+        self.__update_obsolete_firmware()
 
     async def __get_states(self):
         """Get latest state data from controller and reset watchdog."""
@@ -673,6 +714,8 @@ class ControlPoint:
                 )
                 self.devices[identifier].notify_observers()
 
+            self.__update_missing_states()
+
         if (
             self.actions_received >= self.num_control_points
             and not self.actions_ready.done()
@@ -720,6 +763,99 @@ class ControlPoint:
         ):
             self.manufacture_info_ready.set_result(True)
 
+    def __update_obsolete_firmware(self):
+        """Flag devices that are behind their peer firmware cohort."""
+
+        self.obsolete_firmware = {}
+        self.obsolete_firmware_baselines = {}
+
+        for manufacture_info in self.manufacture_infos.values():
+            cohort_key = manufacture_info.cohort_key
+            if cohort_key is None:
+                continue
+            if normalise_firmware_version(manufacture_info.firmwareVersion) is None:
+                continue
+
+            latest_firmware = self.obsolete_firmware_baselines.get(cohort_key)
+            if latest_firmware is None:
+                self.obsolete_firmware_baselines[cohort_key] = (
+                    manufacture_info.firmwareVersion
+                )
+                continue
+
+            if (
+                compare_firmware_versions(
+                    manufacture_info.firmwareVersion, latest_firmware
+                )
+                == 1
+            ):
+                self.obsolete_firmware_baselines[cohort_key] = (
+                    manufacture_info.firmwareVersion
+                )
+
+        for identifier, device in self.devices.items():
+            reason = self.__get_obsolete_firmware_reason(device)
+            if reason:
+                self.obsolete_firmware[identifier] = reason
+                self.logger.warning(
+                    "Flagging obsolete firmware for %s: %s", identifier, reason
+                )
+
+    def __get_obsolete_firmware_reason(
+        self, device: ControlPointDevice
+    ) -> str | None:
+        """Return the reason a device is flagged as obsolete."""
+
+        manufacture_info = getattr(device, "manufacture_info", None)
+        if manufacture_info is None:
+            return "missing manufacture_info"
+        if not manufacture_info.model:
+            return "missing model"
+        if not manufacture_info.hwVersion:
+            return "missing hwVersion"
+        if not manufacture_info.firmwareVersion:
+            return "missing firmwareVersion"
+        if normalise_firmware_version(manufacture_info.firmwareVersion) is None:
+            return "invalid firmwareVersion"
+
+        baseline = self.obsolete_firmware_baselines.get(manufacture_info.cohort_key)
+        if baseline is None:
+            return "unable to compare firmwareVersion"
+
+        comparison = compare_firmware_versions(
+            manufacture_info.firmwareVersion, baseline
+        )
+        if comparison is None:
+            return "invalid firmwareVersion"
+        if comparison < 0:
+            return f"{manufacture_info.firmwareVersion} < {baseline}"
+
+        return None
+
+    def __describe_manufacture_info(
+        self, manufacture_info: ControlPointManufactureInfo
+    ) -> str:
+        """Render manufacture info, annotating obsolete firmware entries."""
+
+        description = manufacture_info.describe().rstrip("\n")
+        newer_firmware = self.obsolete_firmware_baselines.get(manufacture_info.cohort_key)
+        if newer_firmware and any(
+            device.identifier.split("_")[0] == manufacture_info.identifier
+            for device in self.obsolete_firmware_devices
+        ):
+            description = description.replace(
+                " )", f", fw<{newer_firmware} )"
+            )
+        return description + "\n"
+
+    def __update_missing_states(self):
+        """Track devices that do not yet have usable state payloads."""
+
+        self.missing_states = {}
+        for identifier, device in self.devices.items():
+            if not device.states:
+                self.missing_states[identifier] = "missing states"
+
     def __update_properties(self, properties):
         """Updates zcc gateway properties"""
 

{zcc_helper-3.8.1.dev1 → zcc_helper-3.9.dev1}/zcc/device.py

@@ -78,9 +78,9 @@ class ControlPointDevice:
             if fan_speed:
                 description += "/" + str(fan_speed)
         except IndexError:
-            description = "WARNING"
+            description = "None"
         except KeyError:
-            description = "WARNING"
+            description = "None"
         return description
 
     @property
@@ -115,12 +115,19 @@ class ControlPointDevice:
 
     def describe(self) -> str:
         """Returns a description of a device"""
+        actions = self.__actions
+        if self.controller and self.identifier in self.controller.missing_states:
+            if actions.endswith("}"):
+                actions = actions[:-1] + " MISSING }"
+            else:
+                actions = "{ MISSING }"
+
         return "%-40s   %-38.38s %-8.8s %-8s %s\n" % (
             self.identifier,
             self.location,
             self.type,
             self.__states,
-            self.__actions,
+            actions,
         )
 
     @property

zcc_helper-3.9.dev1/zcc/manufacture_info.py

@@ -0,0 +1,88 @@
+"""ControlPointManufactureInfo Class."""
+
+from dataclasses import dataclass
+from typing import Tuple
+
+
+def normalise_firmware_version(version: str) -> Tuple[int, ...] | None:
+    """Convert a dotted firmware version string to a comparable tuple."""
+
+    if not version:
+        return None
+
+    try:
+        return tuple(int(part) for part in version.split("."))
+    except (AttributeError, TypeError, ValueError):
+        return None
+
+
+def compare_firmware_versions(current: str, other: str) -> int | None:
+    """Compare two dotted firmware versions."""
+
+    current_version = normalise_firmware_version(current)
+    other_version = normalise_firmware_version(other)
+
+    if current_version is None or other_version is None:
+        return None
+
+    max_length = max(len(current_version), len(other_version))
+    current_version += (0,) * (max_length - len(current_version))
+    other_version += (0,) * (max_length - len(other_version))
+
+    if current_version < other_version:
+        return -1
+    if current_version > other_version:
+        return 1
+
+    return 0
+
+
+@dataclass
+class ControlPointManufactureInfo:
+    """Data class to store ControlPoint manufacture_info."""
+
+    identifier: str = None
+    manufacturer: str = None
+    model: str = None
+    hwVersion: str = None
+    firmwareVersion: str = None
+
+    @property
+    def cohort_key(self) -> Tuple[str, str] | None:
+        """Return the comparison cohort for peer firmware checks."""
+
+        if not self.model or not self.hwVersion:
+            return None
+
+        return (self.model, self.hwVersion)
+
+    def describe(self) -> str:
+        """Returns a description of a device"""
+        return "%-40s %-40.40s %-8.8s          %s\n" % (
+            self.identifier,
+            f"{self.model} ({self.name})",
+            "device",
+            f"( hw={self.hwVersion}, fw={self.firmwareVersion} )",
+        )
+
+    @property
+    def name(self) -> str:
+        """Returns simplified name of the device."""
+
+        if not self.model:
+            return "N/A"
+
+        if "Blind" in self.model:
+            return "Cover"
+        if "Fan" in self.model:
+            return "Fan"
+        if "Garage" in self.model:
+            return "Garage"
+        if "Door" in self.model:
+            return "Cover"
+        if "GPO" in self.model:
+            return "Outlet"
+        if "Switch" in self.model:
+            return "Switch"
+
+        return self.model

{zcc_helper-3.8.1.dev1 → zcc_helper-3.9.dev1/zcc_helper.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zcc_helper
-Version: 3.8.1.dev1
+Version: 3.9.dev1
 Summary: ZIMI ZCC helper module
 Author: Mark Hannon
 Author-email: mark.hannon@gmail.com

{zcc_helper-3.8.1.dev1 → zcc_helper-3.9.dev1}/zcc_helper.egg-info/SOURCES.txt

@@ -2,7 +2,9 @@ LICENSE.txt
 README.md
 setup.py
 zcc.py
+tests/test_controller.py
 tests/test_device.py
+tests/test_manufacture_info.py
 zcc/__init__.py
 zcc/__main__.py
 zcc/constants.py

zcc_helper-3.8.1.dev1/zcc/manufacture_info.py

@@ -1,45 +0,0 @@
-"""ControlPointManufactureInfo Class."""
-
-from dataclasses import dataclass
-
-
-@dataclass
-class ControlPointManufactureInfo:
-    """Data class to store ControlPoint manufacture_info."""
-
-    identifier: str = None
-    manufacturer: str = None
-    model: str = None
-    hwVersion: str = None
-    firmwareVersion: str = None
-
-    def describe(self) -> str:
-        """Returns a description of a device"""
-        return "%-40s %-40.40s %-8.8s          %s\n" % (
-            self.identifier,
-            f"{self.model} ({self.name})",
-            "device",
-            f"( hw={self.hwVersion}, fw={self.firmwareVersion} )",
-        )
-
-    @property
-    def name(self) -> str:
-        """Returns simplified name of the device."""
-
-        if not self.model:
-            return "N/A"
-
-        if "Blind" in self.model:
-            return "Cover"
-        if "Fan" in self.model:
-            return "Fan"
-        if "Garage" in self.model:
-            return "Garage"
-        if "Door" in self.model:
-            return "Cover"
-        if "GPO" in self.model:
-            return "Outlet"
-        if "Switch" in self.model:
-            return "Switch"
-
-        return self.model