pyg90alarm 1.16.1__tar.gz → 1.17.1__tar.gz

{pyg90alarm-1.16.1 → pyg90alarm-1.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyg90alarm
-Version: 1.16.1
+Version: 1.17.1
 Summary: G90 Alarm system protocol
 Home-page: https://github.com/hostcc/pyg90alarm
 Author: Ilia Sotnikov

{pyg90alarm-1.16.1 → pyg90alarm-1.17.1}/src/pyg90alarm/alarm.py

@@ -63,6 +63,7 @@ from .const import (
     LOCAL_NOTIFICATIONS_HOST,
     LOCAL_NOTIFICATIONS_PORT,
     G90ArmDisarmTypes,
+    G90RemoteButtonStates,
 )
 from .base_cmd import (G90BaseCommand, G90BaseCommandData)
 from .paginated_result import G90PaginatedResult, G90PaginatedResponse
@@ -109,8 +110,18 @@ if TYPE_CHECKING:
         Callable[[G90ArmDisarmTypes], None],
         Callable[[G90ArmDisarmTypes], Coroutine[None, None, None]]
     ]
+    SosCallback = Union[
+        Callable[[int, str, bool], None],
+        Callable[[int, str, bool], Coroutine[None, None, None]]
+    ]
+    RemoteButtonPressCallback = Union[
+        Callable[[int, str, G90RemoteButtonStates], None],
+        Callable[
+            [int, str, G90RemoteButtonStates], Coroutine[None, None, None]
+        ]
+    ]
     # Sensor-related callbacks for `G90Sensor` class - despite that class
-    # stores them, the invication is done by the `G90Alarm` class hence these
+    # stores them, the invocation is done by the `G90Alarm` class hence these
     # are defined here
     SensorStateCallback = Union[
         Callable[[bool], None],
@@ -157,6 +168,10 @@ class G90Alarm(G90DeviceNotifications):
         self._door_open_close_cb: Optional[DoorOpenCloseCallback] = None
         self._alarm_cb: Optional[AlarmCallback] = None
         self._low_battery_cb: Optional[LowBatteryCallback] = None
+        self._sos_cb: Optional[SosCallback] = None
+        self._remote_button_press_cb: Optional[
+            RemoteButtonPressCallback
+        ] = None
         self._reset_occupancy_interval = reset_occupancy_interval
         self._alert_config: Optional[G90AlertConfigFlags] = None
         self._sms_alert_when_armed = False
@@ -671,6 +686,86 @@ class G90Alarm(G90DeviceNotifications):
     def low_battery_callback(self, value: LowBatteryCallback) -> None:
         self._low_battery_cb = value
 
+    async def on_sos(
+        self, event_id: int, zone_name: str, is_host_sos: bool
+    ) -> None:
+        """
+        Invoked when SOS alert is triggered. Fires corresponding callback if
+        set by the user with :attr:`.sos_callback`.
+
+        Please note the method is for internal use by the class.
+
+        :param event_id: Index of the sensor triggered alarm
+        :param zone_name: Sensor name
+        :param is_host_sos:
+          Flag indicating if the SOS alert is triggered by the panel itself
+          (host)
+        """
+        _LOGGER.debug('on_sos: %s %s %s', event_id, zone_name, is_host_sos)
+        G90Callback.invoke(self._sos_cb, event_id, zone_name, is_host_sos)
+
+        # Also report the event as alarm for unification, hard-coding the
+        # sensor name in case of host SOS
+        await self.on_alarm(event_id, 'Host SOS' if is_host_sos else zone_name)
+
+        if not is_host_sos:
+            # Also report the remote button press for SOS - the panel will not
+            # send corresponding alert
+            await self.on_remote_button_press(
+                event_id, zone_name, G90RemoteButtonStates.SOS
+            )
+
+    @property
+    def sos_callback(self) -> Optional[SosCallback]:
+        """
+        SOS callback, which is invoked when SOS alert is triggered.
+        """
+        return self._sos_cb
+
+    @sos_callback.setter
+    def sos_callback(self, value: SosCallback) -> None:
+        self._sos_cb = value
+
+    async def on_remote_button_press(
+        self, event_id: int, zone_name: str, button: G90RemoteButtonStates
+    ) -> None:
+        """
+        Invoked when remote button is pressed. Fires corresponding callback if
+        set by the user with :attr:`.remote_button_press_callback`.
+
+        Please note the method is for internal use by the class.
+
+        :param event_id: Index of the sensor triggered alarm
+        :param zone_name: Sensor name
+        :param button: The button pressed
+        """
+        _LOGGER.debug(
+            'on_remote_button_press: %s %s %s', event_id, zone_name, button
+        )
+        G90Callback.invoke(
+            self._remote_button_press_cb, event_id, zone_name, button
+        )
+
+        # Also report the event as sensor activity for unification (remote is
+        # just a special type of the sensor)
+        await self.on_sensor_activity(event_id, zone_name, True)
+
+    @property
+    def remote_button_press_callback(
+        self
+    ) -> Optional[RemoteButtonPressCallback]:
+        """
+        Remote button press callback, which is invoked when remote button is
+        pressed.
+        """
+        return self._remote_button_press_cb
+
+    @remote_button_press_callback.setter
+    def remote_button_press_callback(
+        self, value: RemoteButtonPressCallback
+    ) -> None:
+        self._remote_button_press_cb = value
+
     async def listen_device_notifications(self) -> None:
         """
         Starts internal listener for device notifications/alerts.
@@ -820,7 +915,10 @@ class G90Alarm(G90DeviceNotifications):
                         # notifications port
                         self._handle_alert(
                             (self._host, self._notifications_local_port),
-                            item.as_device_alert()
+                            item.as_device_alert(),
+                            # Skip verifying device GUID, since history entry
+                            # don't have it
+                            verify_device_id=False
                         )
 
                         # Record the entry as most recent one

{pyg90alarm-1.16.1 → pyg90alarm-1.17.1}/src/pyg90alarm/const.py

@@ -187,8 +187,11 @@ class G90AlertTypes(IntEnum):
     """
     Defines types of alerts sent by the alarm panel.
     """
+    HOST_SOS = 1
     STATE_CHANGE = 2
     ALARM = 3
+    SENSOR_ACTIVITY = 4
+    # Retained for compatibility, deprecated
     DOOR_OPEN_CLOSE = 4
 
 
@@ -245,3 +248,17 @@ class G90HistoryStates(IntEnum):
     LOW_BATTERY = 10
     WIFI_CONNECTED = 11
     WIFI_DISCONNECTED = 12
+    REMOTE_BUTTON_ARM_AWAY = 13
+    REMOTE_BUTTON_ARM_HOME = 14
+    REMOTE_BUTTON_DISARM = 15
+    REMOTE_BUTTON_SOS = 16
+
+
+class G90RemoteButtonStates(IntEnum):
+    """
+    Defines possible states for remote control buttons.
+    """
+    ARM_AWAY = 0
+    ARM_HOME = 1
+    DISARM = 2
+    SOS = 3

{pyg90alarm-1.16.1 → pyg90alarm-1.17.1}/src/pyg90alarm/device_notifications.py

@@ -39,6 +39,7 @@ from .const import (
     G90ArmDisarmTypes,
     G90AlertSources,
     G90AlertStates,
+    G90RemoteButtonStates,
 )
 
 _LOGGER = logging.getLogger(__name__)
@@ -136,11 +137,13 @@ class G90DeviceNotifications(DatagramProtocol):
         # Sensor activity notification
         if notification.kind == G90NotificationTypes.SENSOR_ACTIVITY:
             g90_zone_info = G90ZoneInfo(*notification.data)
+
             _LOGGER.debug('Sensor notification: %s', g90_zone_info)
             G90Callback.invoke(
                 self.on_sensor_activity,
                 g90_zone_info.idx, g90_zone_info.name
             )
+
             return
 
         # Arm/disarm notification
@@ -149,52 +152,81 @@ class G90DeviceNotifications(DatagramProtocol):
                 *notification.data)
             # Map the state received from the device to corresponding enum
             state = G90ArmDisarmTypes(g90_armdisarm_info.state)
+
             _LOGGER.debug('Arm/disarm notification: %s',
                           state)
             G90Callback.invoke(self.on_armdisarm, state)
+
             return
 
         _LOGGER.warning('Unknown notification received from %s:%s:'
                         ' kind %s, data %s',
                         addr[0], addr[1], notification.kind, notification.data)
 
+    def _handle_alert_sensor_activity(self, alert: G90DeviceAlert) -> bool:
+        """
+        Handles sensor activity alert.
+        """
+        if alert.source == G90AlertSources.REMOTE:
+            _LOGGER.debug('Remote button press alert: %s', alert)
+            G90Callback.invoke(
+                self.on_remote_button_press,
+                alert.event_id, alert.zone_name,
+                G90RemoteButtonStates(alert.state)
+            )
+
+            return True
+
+        if alert.state in (
+            G90AlertStates.DOOR_OPEN, G90AlertStates.DOOR_CLOSE
+        ):
+            is_open = (
+                alert.source == G90AlertSources.SENSOR
+                and alert.state == G90AlertStates.DOOR_OPEN  # noqa: W503
+            ) or alert.source == G90AlertSources.DOORBELL
+
+            _LOGGER.debug('Door open_close alert: %s', alert)
+            G90Callback.invoke(
+                self.on_door_open_close,
+                alert.event_id, alert.zone_name, is_open
+            )
+
+            return True
+
+        if (
+            alert.source == G90AlertSources.SENSOR
+            and alert.state == G90AlertStates.LOW_BATTERY  # noqa: W503
+        ):
+            _LOGGER.debug('Low battery alert: %s', alert)
+            G90Callback.invoke(
+                self.on_low_battery,
+                alert.event_id, alert.zone_name
+            )
+
+            return True
+
+        return False
+
     def _handle_alert(
-        self, addr: Tuple[str, int], alert: G90DeviceAlert
+        self, addr: Tuple[str, int], alert: G90DeviceAlert,
+        verify_device_id: bool = True
     ) -> None:
+        handled = False
+
         # Stop processing when alert is received from the device with different
-        # GUID
-        if self.device_id and alert.device_id != self.device_id:
+        # GUID (if enabled)
+        if (
+            verify_device_id and self.device_id
+            and alert.device_id != self.device_id
+        ):
             _LOGGER.error(
                 "Received alert from wrong device: expected '%s', got '%s'",
                 self.device_id, alert.device_id
             )
             return
 
-        if alert.type == G90AlertTypes.DOOR_OPEN_CLOSE:
-            if alert.state in (
-                G90AlertStates.DOOR_OPEN, G90AlertStates.DOOR_CLOSE
-            ):
-                is_open = (
-                    alert.source == G90AlertSources.SENSOR
-                    and alert.state == G90AlertStates.DOOR_OPEN  # noqa: W503
-                ) or alert.source == G90AlertSources.DOORBELL
-                _LOGGER.debug('Door open_close alert: %s', alert)
-                G90Callback.invoke(
-                    self.on_door_open_close,
-                    alert.event_id, alert.zone_name, is_open
-                )
-                return
-
-            if (
-                alert.source == G90AlertSources.SENSOR
-                and alert.state == G90AlertStates.LOW_BATTERY  # noqa: W503
-            ):
-                _LOGGER.debug('Low battery alert: %s', alert)
-                G90Callback.invoke(
-                    self.on_low_battery,
-                    alert.event_id, alert.zone_name
-                )
-                return
+        if alert.type == G90AlertTypes.SENSOR_ACTIVITY:
+            handled = self._handle_alert_sensor_activity(alert)
 
         if alert.type == G90AlertTypes.STATE_CHANGE:
             # Define the mapping between device state received in the alert, to
@@ -209,25 +241,46 @@ class G90DeviceNotifications(DatagramProtocol):
                 G90AlertStateChangeTypes.DISARM: G90ArmDisarmTypes.DISARM
             }
 
-            state = alarm_arm_disarm_state_map.get(alert.event_id)
+            state = alarm_arm_disarm_state_map.get(alert.event_id, None)
             if state:
                 # We received the device state change related to arm/disarm,
                 # invoke the corresponding callback
                 _LOGGER.debug('Arm/disarm state change: %s', state)
                 G90Callback.invoke(self.on_armdisarm, state)
-                return
+
+            handled = True
 
         if alert.type == G90AlertTypes.ALARM:
-            _LOGGER.debug('Alarm: %s', alert.zone_name)
+            # Remote SOS
+            if alert.source == G90AlertSources.REMOTE:
+                _LOGGER.debug('SOS: %s', alert.zone_name)
+                G90Callback.invoke(
+                    self.on_sos, alert.event_id, alert.zone_name, False
+                )
+            # Regular alarm
+            else:
+                _LOGGER.debug('Alarm: %s', alert.zone_name)
+                G90Callback.invoke(
+                    self.on_alarm,
+                    alert.event_id, alert.zone_name
+                )
+            handled = True
+
+        # Host SOS
+        if alert.type == G90AlertTypes.HOST_SOS:
+            zone_name = 'Host SOS'
+
+            _LOGGER.debug('SOS: Host')
             G90Callback.invoke(
-                self.on_alarm,
-                alert.event_id, alert.zone_name
+                self.on_sos, alert.event_id, zone_name, True
             )
-            return
 
-        _LOGGER.warning('Unknown alert received from %s:%s:'
-                        ' type %s, data %s',
-                        addr[0], addr[1], alert.type, alert)
+            handled = True
+
+        if not handled:
+            _LOGGER.warning('Unknown alert received from %s:%s:'
+                            ' type %s, data %s',
+                            addr[0], addr[1], alert.type, alert)
 
     # Implementation of datagram protocol,
     # https://docs.python.org/3/library/asyncio-protocol.html#datagram-protocols
@@ -307,11 +360,16 @@ class G90DeviceNotifications(DatagramProtocol):
     async def on_armdisarm(self, state: G90ArmDisarmTypes) -> None:
         """
         Invoked when device is armed or disarmed.
+
+        :param state: State of the device
         """
 
     async def on_sensor_activity(self, idx: int, name: str) -> None:
         """
         Invoked on sensor activity.
+
+        :param idx: Index of the sensor.
+        :param name: Name of the sensor.
         """
 
     async def on_door_open_close(
@@ -319,16 +377,55 @@ class G90DeviceNotifications(DatagramProtocol):
     ) -> None:
         """
         Invoked when door sensor reports it opened or closed.
+
+        :param event_id: Index of the sensor reporting the event.
+        :param zone_name: Name of the sensor that reports door open/close.
+        :param is_open: Indicates if the door is open.
         """
 
     async def on_low_battery(self, event_id: int, zone_name: str) -> None:
         """
         Invoked when a sensor reports it is low on battery.
+
+        :param event_id: Index of the sensor.
+        :param zone_name: Name of the sensor that reports low battery.
         """
 
     async def on_alarm(self, event_id: int, zone_name: str) -> None:
         """
         Invoked when device triggers the alarm.
+
+        :param event_id: Index of the sensor.
+        :param zone_name: Name of the zone that triggered the alarm.
+        """
+
+    async def on_remote_button_press(
+        self, event_id: int, zone_name: str, button: G90RemoteButtonStates
+    ) -> None:
+        """
+        Invoked when a remote button is pressed.
+
+        Please note there will only be call to the method w/o invoking
+        :meth:`G90DeviceNotifications.on_sensor_activity`.
+
+        :param event_id: Index of the sensor associated with the remote.
+        :param zone_name: Name of the sensor that reports remote button press.
+        :param button: The button pressed on the remote
+        """
+
+    async def on_sos(
+        self, event_id: int, zone_name: str, is_host_sos: bool
+    ) -> None:
+        """
+        Invoked when SOS is triggered.
+
+        Please note that the panel might not set its status to alarm
+        internally, so that :meth:`G90DeviceNotifications` might need an
+        explicit call in the derived class to simulate that.
+
+        :param event_id: Index of the sensor.
+        :param zone_name: Name of the sensor that reports SOS.
+        :param is_host_sos: Indicates if the SOS is host-initiated.
         """
 
     async def listen(self) -> None:
@@ -378,4 +475,12 @@ class G90DeviceNotifications(DatagramProtocol):
 
     @device_id.setter
     def device_id(self, device_id: str) -> None:
+        # Under not yet identified circumstances the device ID might be empty
+        # string provided by :meth:`G90Alarm.get_host_info` - disallow that
+        if not device_id or len(device_id.strip()) == 0:
+            _LOGGER.debug(
+                'Device ID is empty or contains whitespace only, not setting'
+            )
+            return
+
         self._device_id = device_id

{pyg90alarm-1.16.1 → pyg90alarm-1.17.1}/src/pyg90alarm/history.py

@@ -32,15 +32,17 @@ from .const import (
     G90AlertStates,
     G90AlertStateChangeTypes,
     G90HistoryStates,
+    G90RemoteButtonStates,
 )
 from .device_notifications import G90DeviceAlert
 
 _LOGGER = logging.getLogger(__name__)
 
 
-# The state of the incoming history entries are mixed of `G90AlertStates` and
-# `G90AlertStateChangeTypes`, depending on entry type - hence two separate
-# dictionaries, since enums used for keys have conflicting values
+# The state of the incoming history entries are mixed of `G90AlertStates`,
+# `G90AlertStateChangeTypes` and `G90RemoteButtonStates`, depending on entry
+# type - hence separate dictionaries, since enums used for keys have
+# conflicting values
 states_mapping_alerts = {
     G90AlertStates.DOOR_CLOSE:
         G90HistoryStates.DOOR_CLOSE,
@@ -71,6 +73,17 @@ states_mapping_state_changes = {
         G90HistoryStates.WIFI_DISCONNECTED,
 }
 
+states_mapping_remote_buttons = {
+    G90RemoteButtonStates.ARM_AWAY:
+        G90HistoryStates.REMOTE_BUTTON_ARM_AWAY,
+    G90RemoteButtonStates.ARM_HOME:
+        G90HistoryStates.REMOTE_BUTTON_ARM_HOME,
+    G90RemoteButtonStates.DISARM:
+        G90HistoryStates.REMOTE_BUTTON_DISARM,
+    G90RemoteButtonStates.SOS:
+        G90HistoryStates.REMOTE_BUTTON_SOS,
+}
+
 
 @dataclass
 class ProtocolData:
@@ -112,7 +125,7 @@ class G90History:
         """
         try:
             return G90AlertTypes(self._protocol_data.type)
-        except ValueError:
+        except (ValueError, KeyError):
             _LOGGER.warning(
                 "Can't interpret '%s' as alert type (decoded protocol"
                 " data '%s', raw data '%s')",
@@ -125,18 +138,33 @@ class G90History:
         """
         State for the history entry.
         """
+        # 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)
+                ]
+
             # Door open/close or alert types, mapped against `G90AlertStates`
             # using `state` incoming field
             if self.type in [
-                G90AlertTypes.DOOR_OPEN_CLOSE, G90AlertTypes.ALARM
+                G90AlertTypes.SENSOR_ACTIVITY, G90AlertTypes.ALARM
             ]:
                 return G90HistoryStates(
                     states_mapping_alerts[
                         G90AlertStates(self._protocol_data.state)
                     ]
                 )
-        except ValueError:
+        except (ValueError, KeyError):
             _LOGGER.warning(
                 "Can't interpret '%s' as alert state (decoded protocol"
                 " data '%s', raw data '%s')",
@@ -151,7 +179,7 @@ class G90History:
                     G90AlertStateChangeTypes(self._protocol_data.event_id)
                 ]
             )
-        except ValueError:
+        except (ValueError, KeyError):
             _LOGGER.warning(
                 "Can't interpret '%s' as state change (decoded protocol"
                 " data '%s', raw data '%s')",
@@ -166,13 +194,14 @@ class G90History:
         Source of the history entry.
         """
         try:
-            # Device state changes or open/close events are mapped against
-            # `G90AlertSources` using `source` incoming field
+            # Device state changes, open/close or alarm events are mapped
+            # against `G90AlertSources` using `source` incoming field
             if self.type in [
-                G90AlertTypes.STATE_CHANGE, G90AlertTypes.DOOR_OPEN_CLOSE
+                G90AlertTypes.STATE_CHANGE, G90AlertTypes.SENSOR_ACTIVITY,
+                G90AlertTypes.ALARM
             ]:
                 return G90AlertSources(self._protocol_data.source)
-        except ValueError:
+        except (ValueError, KeyError):
             _LOGGER.warning(
                 "Can't interpret '%s' as alert source (decoded protocol"
                 " data '%s', raw data '%s')",
@@ -180,11 +209,6 @@ class G90History:
             )
             return None
 
-        # Alarm will have `SENSOR` as the source, since that is likely what
-        # triggered it
-        if self.type == G90AlertTypes.ALARM:
-            return G90AlertSources.SENSOR
-
         # Other sources are assumed to be initiated by device itself
         return G90AlertSources.DEVICE
 

{pyg90alarm-1.16.1 → pyg90alarm-1.17.1}/src/pyg90alarm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyg90alarm
-Version: 1.16.1
+Version: 1.17.1
 Summary: G90 Alarm system protocol
 Home-page: https://github.com/hostcc/pyg90alarm
 Author: Ilia Sotnikov

{pyg90alarm-1.16.1 → pyg90alarm-1.17.1}/src/pyg90alarm.egg-info/SOURCES.txt

@@ -51,5 +51,6 @@ tests/device_mock.py
 tests/test_alarm.py
 tests/test_base_commands.py
 tests/test_discovery.py
+tests/test_history.py
 tests/test_notifications.py
 tests/test_paginated_commands.py