pyg90alarm 1.19.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

pyg90alarm/{device_notifications.py → notifications/base.py}

@@ -1,4 +1,4 @@
-# Copyright (c) 2021 Ilia Sotnikov
+# Copyright (c) 2025 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
@@ -24,14 +24,14 @@ Implements support for notifications/alerts sent by G90 alarm panel.
 import json
 import logging
 from typing import (
-    Optional, Tuple, List, Any
+    Optional, List, Any, Callable
 )
 from dataclasses import dataclass
-import asyncio
 from asyncio.transports import BaseTransport
-from asyncio.protocols import DatagramProtocol
-from .callback import G90Callback
-from .const import (
+from datetime import datetime, timezone
+
+from ..callback import G90Callback
+from ..const import (
     G90MessageTypes,
     G90NotificationTypes,
     G90AlertTypes,
@@ -41,6 +41,7 @@ from .const import (
     G90AlertStates,
     G90RemoteButtonStates,
 )
+from .protocol import G90NotificationProtocol
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -104,7 +105,7 @@ class G90DeviceAlert:  # pylint: disable=too-many-instance-attributes
     other: str
 
 
-class G90DeviceNotifications(DatagramProtocol):
+class G90NotificationsBase:
     """
     Implements support for notifications/alerts sent by alarm panel.
 
@@ -115,32 +116,35 @@ class G90DeviceNotifications(DatagramProtocol):
     command to be performed first, one that fetches device GUID and then stores
     it using :attr:`.device_id` (e.g. :meth:`G90Alarm.get_host_info`).
     """
-    def __init__(self, local_port: int, local_host: str):
+    def __init__(
+        self, protocol_factory: Callable[[], G90NotificationProtocol],
+    ):
         # pylint: disable=too-many-arguments
-        self._notification_transport: Optional[BaseTransport] = None
-        self._notifications_local_host = local_host
-        self._notifications_local_port = local_port
-        # Host/port of the device is configured to communicating via commands.
-        # Inteded to validate if notifications/alert are received from the
-        # correct device.
-        self._host: Optional[str] = None
-        self._port: Optional[int] = None
+        self._transport: Optional[BaseTransport] = None
         # Same but for device ID (GUID) - the notifications logic uses it to
         # perform validation, but doesn't set it from messages received (it
         # will diminish the purpose of the validation, should be done by an
         # ancestor class).
         self._device_id: Optional[str] = None
+        self._protocol = protocol_factory()
+        self._last_device_packet_time: Optional[datetime] = None
+        self._last_upstream_packet_time: Optional[datetime] = None
 
-    def _handle_notification(
-        self, addr: Tuple[str, int], notification: G90Notification
+    def handle_notification(
+        self, notification: G90Notification
     ) -> None:
+        """
+        Handles notification received from the device.
+
+        :param notification: The notification to handle.
+        """
         # 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,
+                self._protocol.on_sensor_activity,
                 g90_zone_info.idx, g90_zone_info.name
             )
 
@@ -155,7 +159,7 @@ class G90DeviceNotifications(DatagramProtocol):
 
             _LOGGER.debug('Arm/disarm notification: %s',
                           state)
-            G90Callback.invoke(self.on_armdisarm, state)
+            G90Callback.invoke(self._protocol.on_armdisarm, state)
 
             return
 
@@ -164,14 +168,14 @@ class G90DeviceNotifications(DatagramProtocol):
             g90_zone_info = G90ZoneInfo(*notification.data)
             _LOGGER.debug('Door open detected when arming: %s', g90_zone_info)
             G90Callback.invoke(
-                self.on_door_open_when_arming,
+                self._protocol.on_door_open_when_arming,
                 g90_zone_info.idx, g90_zone_info.name
             )
             return
 
-        _LOGGER.warning('Unknown notification received from %s:%s:'
+        _LOGGER.warning('Unknown notification received:'
                         ' kind %s, data %s',
-                        addr[0], addr[1], notification.kind, notification.data)
+                        notification.kind, notification.data)
 
     def _handle_alert_sensor_activity(self, alert: G90DeviceAlert) -> bool:
         """
@@ -180,7 +184,7 @@ class G90DeviceNotifications(DatagramProtocol):
         if alert.source == G90AlertSources.REMOTE:
             _LOGGER.debug('Remote button press alert: %s', alert)
             G90Callback.invoke(
-                self.on_remote_button_press,
+                self._protocol.on_remote_button_press,
                 alert.event_id, alert.zone_name,
                 G90RemoteButtonStates(alert.state)
             )
@@ -197,7 +201,7 @@ class G90DeviceNotifications(DatagramProtocol):
 
             _LOGGER.debug('Door open_close alert: %s', alert)
             G90Callback.invoke(
-                self.on_door_open_close,
+                self._protocol.on_door_open_close,
                 alert.event_id, alert.zone_name, is_open
             )
 
@@ -209,7 +213,7 @@ class G90DeviceNotifications(DatagramProtocol):
         ):
             _LOGGER.debug('Low battery alert: %s', alert)
             G90Callback.invoke(
-                self.on_low_battery,
+                self._protocol.on_low_battery,
                 alert.event_id, alert.zone_name
             )
 
@@ -217,10 +221,17 @@ class G90DeviceNotifications(DatagramProtocol):
 
         return False
 
-    def _handle_alert(
-        self, addr: Tuple[str, int], alert: G90DeviceAlert,
+    def handle_alert(
+        self, alert: G90DeviceAlert,
         verify_device_id: bool = True
     ) -> None:
+        """
+        Handles alert received from the device.
+
+        :param alert: The alert to handle.
+        :param verify_device_id: Whether to verify the device ID (GUID) in the
+         alert. If set to False, the device ID will not be verified.
+        """
         handled = False
 
         # Stop processing when alert is received from the device with different
@@ -256,7 +267,7 @@ class G90DeviceNotifications(DatagramProtocol):
                 # 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)
+                G90Callback.invoke(self._protocol.on_armdisarm, state)
 
             handled = True
 
@@ -265,7 +276,8 @@ class G90DeviceNotifications(DatagramProtocol):
             if alert.source == G90AlertSources.REMOTE:
                 _LOGGER.debug('SOS: %s', alert.zone_name)
                 G90Callback.invoke(
-                    self.on_sos, alert.event_id, alert.zone_name, False
+                    self._protocol.on_sos,
+                    alert.event_id, alert.zone_name, False
                 )
             # Regular alarm
             else:
@@ -274,7 +286,7 @@ class G90DeviceNotifications(DatagramProtocol):
                     'Alarm: %s, is tampered: %s', alert.zone_name, is_tampered
                 )
                 G90Callback.invoke(
-                    self.on_alarm,
+                    self._protocol.on_alarm,
                     alert.event_id, alert.zone_name, is_tampered
                 )
 
@@ -286,42 +298,22 @@ class G90DeviceNotifications(DatagramProtocol):
 
             _LOGGER.debug('SOS: Host')
             G90Callback.invoke(
-                self.on_sos, alert.event_id, zone_name, True
+                self._protocol.on_sos, alert.event_id, zone_name, True
             )
 
             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
-    def connection_made(self, transport: BaseTransport) -> None:
-        """
-        Invoked when connection from the device is made.
-        """
-
-    def connection_lost(self, exc: Optional[Exception]) -> None:
-        """
-        Same but when the connection is lost.
-        """
+            _LOGGER.warning(
+                'Unknown alert received: type %s, data %s',
+                alert.type, alert
+            )
 
-    def datagram_received(  # pylint:disable=R0911
-        self, data: bytes, addr: Tuple[str, int]
-    ) -> None:
+    # pylint:disable=too-many-return-statements
+    def handle(self, data: bytes) -> None:
         """
-        Invoked when datagram is received from the device.
+        Invoked when message is received from the device.
         """
-        if self._host and self._host != addr[0]:
-            _LOGGER.error(
-                "Received notification/alert from wrong host '%s',"
-                " expected from '%s'",
-                addr[0], self._host
-            )
-            return
-
         try:
             s_data = data.decode('utf-8')
         except UnicodeDecodeError:
@@ -332,8 +324,7 @@ class G90DeviceNotifications(DatagramProtocol):
             _LOGGER.error('Missing end marker in data')
             return
         payload = s_data[:-1]
-        _LOGGER.debug('Received device message from %s:%s: %s',
-                      addr[0], addr[1], payload)
+
         try:
             message = json.loads(payload)
             g90_message = G90Message(*message)
@@ -351,10 +342,9 @@ class G90DeviceNotifications(DatagramProtocol):
             try:
                 notification_data = G90Notification(*g90_message.data)
             except TypeError as exc:
-                _LOGGER.error('Bad notification received from %s:%s: %s',
-                              addr[0], addr[1], exc)
+                _LOGGER.error('Bad notification received: %s', exc)
                 return
-            self._handle_notification(addr, notification_data)
+            self.handle_notification(notification_data)
             return
 
         # Device alerts
@@ -362,132 +352,34 @@ class G90DeviceNotifications(DatagramProtocol):
             try:
                 alert_data = G90DeviceAlert(*g90_message.data)
             except TypeError as exc:
-                _LOGGER.error('Bad alert received from %s:%s: %s',
-                              addr[0], addr[1], exc)
+                _LOGGER.error('Bad alert received: %s', exc)
                 return
-            self._handle_alert(addr, alert_data)
+            self.handle_alert(alert_data)
             return
 
-        _LOGGER.warning('Unknown message received from %s:%s: %s',
-                        addr[0], addr[1], message)
-
-    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_when_arming(
-        self, event_id: int, zone_name: str
-    ) -> None:
-        """
-        Invoked when door open is detected when panel is armed.
-
-        :param event_id: Index of the sensor.
-        :param zone_name: Name of the sensor that reports door open.
-        """
-
-    async def on_door_open_close(
-        self, event_id: int, zone_name: str, is_open: bool
-    ) -> 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, is_tampered: bool
-    ) -> 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.
-        """
+        _LOGGER.warning('Unknown message received: %s', message)
 
     async def listen(self) -> None:
         """
-        Listens for notifications/alers from the device.
+        Listens for notifications/alerts from the device.
         """
-        try:
-            loop = asyncio.get_running_loop()
-        except AttributeError:
-            loop = asyncio.get_event_loop()
-
-        _LOGGER.debug('Creating UDP endpoint for %s:%s',
-                      self._notifications_local_host,
-                      self._notifications_local_port)
-        (self._notification_transport,
-         _protocol) = await loop.create_datagram_endpoint(
-            lambda: self,
-            local_addr=(
-                self._notifications_local_host, self._notifications_local_port
-            ))
+        raise NotImplementedError
 
     @property
     def listener_started(self) -> bool:
         """
         Indicates if the listener of the device notifications has been started.
         """
-        return self._notification_transport is not None
+        return self._transport is not None
 
-    def close(self) -> None:
+    async def close(self) -> None:
         """
         Closes the listener.
         """
-        if self._notification_transport:
+        if self._transport:
             _LOGGER.debug('No longer listening for device notifications')
-            self._notification_transport.close()
-            self._notification_transport = None
+            self._transport.close()
+            self._transport = None
 
     @property
     def device_id(self) -> Optional[str]:
@@ -495,7 +387,7 @@ class G90DeviceNotifications(DatagramProtocol):
         The ID (GUID) of the panel being communicated with thru commands.
 
         Available when any panel command receives it from the device
-        (:meth:`G90Alarm.get_host_info` currently).
+        (`GETHOSTINFO` local command or Hello / HelloDiscovery cloud ones).
         """
         return self._device_id
 
@@ -510,3 +402,53 @@ class G90DeviceNotifications(DatagramProtocol):
             return
 
         self._device_id = device_id
+
+    def clear_device_id(self) -> None:
+        """
+        Clears the device ID.
+        """
+        self._device_id = None
+
+    @property
+    def last_device_packet_time(self) -> Optional[datetime]:
+        """
+        Returns the timestamp of the last packet received from the device.
+
+        This property can be used to monitor the communication health with the
+        device.
+        """
+        return self._last_device_packet_time
+
+    def set_last_device_packet_time(self) -> None:
+        """
+        Updates the timestamp of the last packet received from the device.
+
+        This method is called internally when a packet is received from the
+        device.
+        """
+        self._last_device_packet_time = datetime.now(tz=timezone.utc)
+        _LOGGER.debug(
+            'Last device packet time: %s', self._last_device_packet_time
+        )
+
+    @property
+    def last_upstream_packet_time(self) -> Optional[datetime]:
+        """
+        Returns the timestamp of the last packet sent to the upstream server.
+
+        This property can be used to monitor the communication health with the
+        cloud/upstream server.
+        """
+        return self._last_upstream_packet_time
+
+    def set_last_upstream_packet_time(self) -> None:
+        """
+        Updates the timestamp of the last packet sent to the upstream server.
+
+        This method is called internally when a packet is sent to the upstream
+        server.
+        """
+        self._last_upstream_packet_time = datetime.now(tz=timezone.utc)
+        _LOGGER.debug(
+            'Last upstream packet time: %s', self._last_upstream_packet_time
+        )

pyg90alarm/notifications/protocol.py

@@ -0,0 +1,116 @@
+# 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.
+
+"""
+Defines notification protocol for `NotificationBase` class.
+"""
+
+from ..const import (
+    G90ArmDisarmTypes,
+    G90RemoteButtonStates,
+)
+
+
+class G90NotificationProtocol:
+    """
+    Protocol for notification handling.
+    """
+    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_when_arming(
+        self, event_id: int, zone_name: str
+    ) -> None:
+        """
+        Invoked when door open is detected when panel is armed.
+
+        :param event_id: Index of the sensor.
+        :param zone_name: Name of the sensor that reports door open.
+        """
+
+    async def on_door_open_close(
+        self, event_id: int, zone_name: str, is_open: bool
+    ) -> 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, is_tampered: bool
+    ) -> 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.
+        """