pyg90alarm 2.3.0__py3-none-any.whl → 2.4.0__py3-none-any.whl

pyg90alarm/local/alert_config.py

@@ -0,0 +1,190 @@
+# Copyright (c) 2021 Ilia Sotnikov
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""
+Represents various configuration aspects of the alarm panel.
+"""
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional
+import logging
+from dataclasses import dataclass
+from enum import IntFlag
+
+from pyg90alarm.exceptions import G90Error
+from ..const import G90Commands
+if TYPE_CHECKING:
+    from ..alarm import G90Alarm
+
+
+class G90AlertConfigFlags(IntFlag):
+    """
+    Alert configuration flags, used bitwise
+    """
+    AC_POWER_FAILURE = 1
+    AC_POWER_RECOVER = 2
+    ARM_DISARM = 4
+    HOST_LOW_VOLTAGE = 8
+    SENSOR_LOW_VOLTAGE = 16
+    WIFI_AVAILABLE = 32
+    WIFI_UNAVAILABLE = 64
+    DOOR_OPEN = 128
+    DOOR_CLOSE = 256
+    SMS_PUSH = 512
+    UNKNOWN1 = 2048
+    UNKNOWN2 = 8192
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class G90AlertConfigData:
+    """
+    Represents alert configuration data as received from the alarm panel.
+    """
+    flags_data: int
+
+    @property
+    def flags(self) -> G90AlertConfigFlags:
+        """
+        :return: The alert configuration flags
+        """
+        return G90AlertConfigFlags(self.flags_data)
+
+    @flags.setter
+    def flags(self, value: G90AlertConfigFlags) -> None:
+        """
+        :param value: The alert configuration flags
+        """
+        self.flags_data = value.value
+
+
+class G90AlertConfig:
+    """
+    Represents alert configuration as received from the alarm panel.
+    """
+    def __init__(self, parent: G90Alarm) -> None:
+        self.parent = parent
+        self._cached_data: Optional[G90AlertConfigData] = None
+
+    async def _get(self) -> G90AlertConfigData:
+        """
+        Retrieves the alert configuration flags directly from the device.
+
+        :return: The alerts configured
+        """
+        _LOGGER.debug('Retrieving alert configuration from the device')
+        res = await self.parent.command(G90Commands.GETNOTICEFLAG)
+        data = G90AlertConfigData(*res)
+        _LOGGER.debug(
+            'Alert configuration: %s, flags: %s', data,
+            repr(data.flags)
+        )
+
+        # Cache the retrieved data for `flags_with_fallback` property
+        self._cached_data = data
+
+        return data
+
+    async def set(self, flags: G90AlertConfigFlags) -> None:
+        """
+        .. deprecated:: 2.3.0
+
+        This method is deprecated and will always raise a RuntimeError.
+        Please use :meth:`set_flag` to set individual flags.
+        """
+        raise RuntimeError(
+            'The set() method is deprecated. Please use set_flag() to set'
+            ' individual flags instead.'
+        )
+
+    async def _set(self, flags: G90AlertConfigFlags) -> None:
+        """
+        Sets the alert configuration flags on the device.
+        """
+        _LOGGER.debug('Setting alert configuration to %s', repr(flags))
+        await self.parent.command(G90Commands.SETNOTICEFLAG, [flags.value])
+
+    async def get_flag(self, flag: G90AlertConfigFlags) -> bool:
+        """
+        :param flag: The flag to check
+        """
+        return flag in await self.flags
+
+    async def set_flag(self, flag: G90AlertConfigFlags, value: bool) -> None:
+        """
+        Sets the given flag to the desired value.
+
+        Uses read-modify-write approach.
+
+        :param flag: The flag to set
+        :param value: The value to set
+        """
+        # Retrieve current flags
+        current_flags = await self.flags
+        # Skip updating the flag if it has the desired value
+        if (flag in current_flags) == value:
+            _LOGGER.debug(
+                'Flag %s already set to %s, skipping update',
+                repr(flag), value
+            )
+            return
+
+        # Set or reset corresponding user flag depending on desired value
+        if value:
+            current_flags |= flag
+        else:
+            current_flags &= ~flag
+
+        # Set the updated flags
+        await self._set(current_flags)
+
+    @property
+    async def flags(self) -> G90AlertConfigFlags:
+        """
+        :return: Symbolic names for corresponding flag bits
+        """
+        return (await self._get()).flags
+
+    @property
+    async def flags_with_fallback(self) -> Optional[G90AlertConfigFlags]:
+        """
+        :return: Symbolic names for corresponding flag bits, falling back to
+         cached data if device communication fails
+        """
+        result = None
+
+        try:
+            result = (await self._get()).flags
+        except G90Error as exc:
+            _LOGGER.debug(
+                'Retrieving alert config flags resulted in error %s',
+                repr(exc)
+            )
+            if self._cached_data is not None:
+                _LOGGER.debug(
+                    'Falling back to cached alert configuration flags: %s',
+                    repr(self._cached_data.flags)
+                )
+                result = self._cached_data.flags
+            else:
+                _LOGGER.debug('No cached alert configuration flags available')
+
+        return result

pyg90alarm/local/config.py

@@ -17,141 +17,16 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
-
 """
-Represents various configuration aspects of the alarm panel.
+Compatibility module for the alert configuration, which should be imported
+from `local.alert_config` instead.
 """
-from __future__ import annotations
-from typing import TYPE_CHECKING
-import logging
-from dataclasses import dataclass
-from enum import IntFlag
-from ..const import G90Commands
-if TYPE_CHECKING:
-    from ..alarm import G90Alarm
-
-
-class G90AlertConfigFlags(IntFlag):
-    """
-    Alert configuration flags, used bitwise
-    """
-    AC_POWER_FAILURE = 1
-    AC_POWER_RECOVER = 2
-    ARM_DISARM = 4
-    HOST_LOW_VOLTAGE = 8
-    SENSOR_LOW_VOLTAGE = 16
-    WIFI_AVAILABLE = 32
-    WIFI_UNAVAILABLE = 64
-    DOOR_OPEN = 128
-    DOOR_CLOSE = 256
-    SMS_PUSH = 512
-    UNKNOWN1 = 2048
-    UNKNOWN2 = 8192
-
-
-_LOGGER = logging.getLogger(__name__)
-
-
-@dataclass
-class G90AlertConfigData:
-    """
-    Represents alert configuration data as received from the alarm panel.
-    """
-    flags_data: int
-
-    @property
-    def flags(self) -> G90AlertConfigFlags:
-        """
-        :return: The alert configuration flags
-        """
-        return G90AlertConfigFlags(self.flags_data)
-
-    @flags.setter
-    def flags(self, value: G90AlertConfigFlags) -> None:
-        """
-        :param value: The alert configuration flags
-        """
-        self.flags_data = value.value
-
-
-class G90AlertConfig:
-    """
-    Represents alert configuration as received from the alarm panel.
-    """
-    def __init__(self, parent: G90Alarm) -> None:
-        self.parent = parent
-
-    async def _get(self) -> G90AlertConfigData:
-        """
-        Retrieves the alert configuration flags directly from the device.
-
-        :return: The alerts configured
-        """
-        _LOGGER.debug('Retrieving alert configuration from the device')
-        res = await self.parent.command(G90Commands.GETNOTICEFLAG)
-        data = G90AlertConfigData(*res)
-        _LOGGER.debug(
-            'Alert configuration: %s, flags: %s', data,
-            repr(data.flags)
-        )
-        return data
-
-    async def set(self, flags: G90AlertConfigFlags) -> None:
-        """
-        .. deprecated:: 2.3.0
-
-        This method is deprecated and will always raise a RuntimeError.
-        Please use :meth:`set_flag` to set individual flags.
-        """
-        raise RuntimeError(
-            'The set() method is deprecated. Please use set_flag() to set'
-            ' individual flags instead.'
-        )
-
-    async def _set(self, flags: G90AlertConfigFlags) -> None:
-        """
-        Sets the alert configuration flags on the device.
-        """
-        _LOGGER.debug('Setting alert configuration to %s', repr(flags))
-        await self.parent.command(G90Commands.SETNOTICEFLAG, [flags.value])
-
-    async def get_flag(self, flag: G90AlertConfigFlags) -> bool:
-        """
-        :param flag: The flag to check
-        """
-        return flag in await self.flags
-
-    async def set_flag(self, flag: G90AlertConfigFlags, value: bool) -> None:
-        """
-        Sets the given flag to the desired value.
-
-        Uses read-modify-write approach.
-
-        :param flag: The flag to set
-        :param value: The value to set
-        """
-        # Retrieve current flags
-        current_flags = await self.flags
-        # Skip updating the flag if it has the desired value
-        if (flag in current_flags) == value:
-            _LOGGER.debug(
-                'Flag %s already set to %s, skipping update',
-                repr(flag), value
-            )
-            return
-
-        # Set or reset corresponding user flag depending on desired value
-        if value:
-            current_flags |= flag
-        else:
-            current_flags &= ~flag
-
-        # Set the updated flags
-        await self._set(current_flags)
-
-    @property
-    async def flags(self) -> G90AlertConfigFlags:
-        """
-        :return: Symbolic names for corresponding flag bits
-        """
-        return (await self._get()).flags
+from .alert_config import (
+    G90AlertConfig, G90AlertConfigData, G90AlertConfigFlags
+)
+
+__all__ = [
+    'G90AlertConfig',
+    'G90AlertConfigData',
+    'G90AlertConfigFlags',
+]

pyg90alarm/local/dataclass_load_save.py

@@ -0,0 +1,131 @@
+
+# Copyright (c) 2026 Ilia Sotnikov
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""
+Base class for loading/saving dataclasses to a device.
+"""
+from __future__ import annotations
+from typing import TYPE_CHECKING, Type, TypeVar, Optional, ClassVar, Any, Dict
+import logging
+from dataclasses import dataclass, astuple, asdict
+from ..const import G90Commands
+if TYPE_CHECKING:
+    from ..alarm import G90Alarm
+
+
+_LOGGER = logging.getLogger(__name__)
+S = TypeVar('S', bound='DataclassLoadSave')
+
+
+@dataclass
+class DataclassLoadSave:
+    """
+    Base class for loading/saving dataclasses to a device.
+
+    There are multiple ways to implement the functionality:
+     - Encapsulate the dataclass inside another class that handles
+       loading/saving and exposes dataclass fields as properties. The latter
+       part gets complex as properties need to be asynchronous, as well as
+       added dynamically at runtime to improve maintainability.
+     - Inherit from this class, which provides `load` and `save` methods on top
+       of standard dataclasses. This is believed to be more concise and easier
+       to understand.
+
+    Implementing classes must define `LOAD_COMMAND` and `SAVE_COMMAND` class
+    variables to specify which commands to use for loading and saving data.
+
+    Example usage:
+
+        @dataclass
+        class G90ExampleConfig(DataclassLoadSave):
+            LOAD_COMMAND = G90Commands.GETEXAMPLECONFIG
+            SAVE_COMMAND = G90Commands.SETEXAMPLECONFIG
+            field1: int
+            field2: str
+
+        # Loading data
+        config = await G90ExampleConfig.load(G90_alarm_instance)
+        print(config.field1, config.field2)
+
+        # Modifying and saving data
+        config.field1 = 42
+        await config.save()
+    """
+    LOAD_COMMAND: ClassVar[Optional[G90Commands]] = None
+    SAVE_COMMAND: ClassVar[Optional[G90Commands]] = None
+
+    def __post_init__(self) -> None:
+        """
+        Post-initialization processing.
+        """
+        # Instance variable to hold reference to parent G90Alarm instance,
+        # declared here to avoid being part of dataclass fields
+        self._parent: Optional[G90Alarm] = None
+
+    async def save(self) -> None:
+        """
+        Save the current data to the device.
+        """
+        assert self.SAVE_COMMAND is not None, '`SAVE_COMMAND` must be defined'
+        assert self._parent is not None, 'Please call `load()` first'
+
+        _LOGGER.debug('Setting data to the device: %s', str(self))
+        await self._parent.command(
+            self.SAVE_COMMAND,
+            list(astuple(self))
+        )
+
+    @classmethod
+    async def load(cls: Type[S], parent: G90Alarm) -> S:
+        """
+        Create an instance with values loaded from the device.
+
+        :return: An instance of the dataclass loaded from the device.
+        """
+        assert cls.LOAD_COMMAND is not None, '`LOAD_COMMAND` must be defined'
+        assert parent is not None, '`parent` must be provided'
+
+        data = await parent.command(cls.LOAD_COMMAND)
+        obj = cls(*data)
+        _LOGGER.debug('Loaded data: %s', str(obj))
+
+        obj._parent = parent
+
+        return obj
+
+    def _asdict(self) -> Dict[str, Any]:
+        """
+        Returns the dataclass fields as a dictionary.
+
+        :return: A dictionary representation.
+        """
+        return asdict(self)
+
+    def __str__(self) -> str:
+        """
+        Textual representation of the entry.
+
+        `str()` is used instead of `repr()` since dataclass provides `repr()`
+        by default, and it would be impractical to require each ancestor to
+        disable that.
+
+        :return: A textual representation.
+        """
+        return super().__repr__() + f'({str(self._asdict())})'

pyg90alarm/local/history.py

@@ -33,7 +33,9 @@ from ..const import (
     G90AlertStateChangeTypes,
     G90HistoryStates,
     G90RemoteButtonStates,
+    G90RFIDKeypadStates,
 )
+from ..event_mapping import map_alert_state
 from ..notifications.base import G90DeviceAlert
 
 _LOGGER = logging.getLogger(__name__)
@@ -54,6 +56,8 @@ states_mapping_alerts = {
         G90HistoryStates.LOW_BATTERY,
     G90AlertStates.ALARM:
         G90HistoryStates.ALARM,
+    G90AlertStates.MOTION_DETECTED:
+        G90HistoryStates.MOTION_DETECTED,
 }
 
 states_mapping_state_changes = {
@@ -86,6 +90,27 @@ states_mapping_remote_buttons = {
         G90HistoryStates.REMOTE_BUTTON_SOS,
 }
 
+states_mapping_rfid = {
+    G90RFIDKeypadStates.ARM_AWAY:
+        G90HistoryStates.RFID_KEY_ARM_AWAY,
+    G90RFIDKeypadStates.ARM_HOME:
+        G90HistoryStates.RFID_KEY_ARM_HOME,
+    G90RFIDKeypadStates.DISARM:
+        G90HistoryStates.RFID_KEY_DISARM,
+    G90RFIDKeypadStates.LOW_BATTERY:
+        G90HistoryStates.LOW_BATTERY,
+    G90RFIDKeypadStates.CARD_0:
+        G90HistoryStates.RFID_CARD_0,
+    G90RFIDKeypadStates.CARD_1:
+        G90HistoryStates.RFID_CARD_1,
+    G90RFIDKeypadStates.CARD_2:
+        G90HistoryStates.RFID_CARD_2,
+    G90RFIDKeypadStates.CARD_3:
+        G90HistoryStates.RFID_CARD_3,
+    G90RFIDKeypadStates.CARD_4:
+        G90HistoryStates.RFID_CARD_4,
+}
+
 
 @dataclass
 class ProtocolData:
@@ -140,21 +165,28 @@ class G90History:
         """
         State for the history entry.
         """
+        # pylint: disable=too-many-return-statements
         # No meaningful state for SOS alerts initiated by the panel itself
         # (host)
         if self.type == G90AlertTypes.HOST_SOS:
             return None
 
         try:
-            # State of the remote indicate which button has been pressed
-            if (
-                self.type in [
-                    G90AlertTypes.SENSOR_ACTIVITY, G90AlertTypes.ALARM
-                ] and self.source == G90AlertSources.REMOTE
-            ):
-                return states_mapping_remote_buttons[
-                    G90RemoteButtonStates(self._protocol_data.state)
-                ]
+            # Remote button pressed or RFID keypad event occurred
+            if self.type in [
+                G90AlertTypes.SENSOR_ACTIVITY, G90AlertTypes.ALARM
+            ]:
+                # State of the remote indicate which button has been pressed
+                if self.source == G90AlertSources.REMOTE:
+                    return states_mapping_remote_buttons[
+                        G90RemoteButtonStates(self._protocol_data.state)
+                    ]
+
+                # State of the RFID keypad indicate which action has occurred
+                if self.source == G90AlertSources.RFID:
+                    return states_mapping_rfid[
+                        G90RFIDKeypadStates(self._protocol_data.state)
+                    ]
 
             # Door open/close or alert types, mapped against `G90AlertStates`
             # using `state` incoming field
@@ -162,8 +194,14 @@ class G90History:
                 G90AlertTypes.SENSOR_ACTIVITY, G90AlertTypes.ALARM
             ]:
                 return G90HistoryStates(
+                    # Map to history state via consolidated alert state
                     states_mapping_alerts[
-                        G90AlertStates(self._protocol_data.state)
+                        # Map to consolidated alert state first
+                        map_alert_state(
+                            # Defaults to sensor source if none available
+                            self.source or G90AlertSources.SENSOR,
+                            self._protocol_data.state
+                        )
                     ]
                 )
         except (ValueError, KeyError):
@@ -228,8 +266,12 @@ class G90History:
         ID of the sensor related to the history entry, might be empty if none
         associated.
         """
-        # Sensor ID will only be available if entry source is a sensor
-        if self.source == G90AlertSources.SENSOR:
+        # Sensor ID will only be available if entry source is an infrared, RFID
+        # keypad or other sensor
+        if self.source in [
+            G90AlertSources.SENSOR, G90AlertSources.RFID,
+            G90AlertSources.INFRARED
+        ]:
             return self._protocol_data.event_id
 
         return None
@@ -267,6 +309,6 @@ class G90History:
 
     def __repr__(self) -> str:
         """
-        Textural representation of the history entry.
+        Textual representation of the history entry.
         """
         return super().__repr__() + f'({repr(self._asdict())})'