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

pyg90alarm/__init__.py

@@ -23,17 +23,17 @@ Python package to control G90-based alarm systems.
 """
 
 from .alarm import G90Alarm
-from .base_cmd import G90BaseCommand
-from .paginated_result import G90PaginatedResult
-from .device_notifications import (
+from .local.base_cmd import G90BaseCommand
+from .local.paginated_result import G90PaginatedResult
+from .notifications.base import (
     G90DeviceAlert,
 )
 from .entities.sensor import G90Sensor, G90SensorTypes
 from .entities.device import G90Device
-from .host_info import (
+from .local.host_info import (
     G90HostInfo, G90HostInfoWifiStatus, G90HostInfoGsmStatus
 )
-from .host_status import G90HostStatus
+from .local.host_status import G90HostStatus
 from .const import (
     G90MessageTypes,
     G90NotificationTypes,

pyg90alarm/alarm.py

@@ -22,7 +22,8 @@
 """
 Provides interface to G90 alarm panel.
 
-.. note:: Only protocol 1.2 is supported!
+.. note:: Both local protocol (referred to as 1.2) and cloud one
+(mentioned as 1.1) are supported.
 
 The next example queries the device with IP address `10.10.10.250` for the
 information - the product name, protocol version, HW versions and such.
@@ -52,6 +53,7 @@ G90HostInfo(host_guid='<...>',
 from __future__ import annotations
 import asyncio
 from asyncio import Task
+from datetime import datetime
 import logging
 from typing import (
     TYPE_CHECKING, Any, List, Optional, AsyncGenerator,
@@ -63,27 +65,36 @@ from .const import (
     LOCAL_TARGETED_DISCOVERY_PORT,
     LOCAL_NOTIFICATIONS_HOST,
     LOCAL_NOTIFICATIONS_PORT,
+    CLOUD_NOTIFICATIONS_HOST,
+    CLOUD_NOTIFICATIONS_PORT,
+    REMOTE_CLOUD_HOST,
+    REMOTE_CLOUD_PORT,
     G90ArmDisarmTypes,
     G90RemoteButtonStates,
 )
-from .base_cmd import (G90BaseCommand, G90BaseCommandData)
-from .paginated_result import G90PaginatedResult, G90PaginatedResponse
+from .local.base_cmd import (G90BaseCommand, G90BaseCommandData)
+from .local.paginated_result import G90PaginatedResult, G90PaginatedResponse
 from .entities.sensor import (G90Sensor, G90SensorTypes)
+from .entities.sensor_list import G90SensorList
 from .entities.device import G90Device
-from .device_notifications import (
-    G90DeviceNotifications,
+from .entities.device_list import G90DeviceList
+from .notifications.protocol import (
+    G90NotificationProtocol
 )
-from .discovery import G90Discovery, G90DiscoveredDevice
-from .targeted_discovery import (
+from .notifications.base import G90NotificationsBase
+from .local.notifications import G90LocalNotifications
+from .local.discovery import G90Discovery, G90DiscoveredDevice
+from .local.targeted_discovery import (
     G90TargetedDiscovery, G90DiscoveredDeviceTargeted,
 )
-from .host_info import G90HostInfo
-from .host_status import G90HostStatus
-from .config import (G90AlertConfig, G90AlertConfigFlags)
-from .history import G90History
-from .user_data_crc import G90UserDataCRC
+from .local.host_info import G90HostInfo
+from .local.host_status import G90HostStatus
+from .local.config import (G90AlertConfig, G90AlertConfigFlags)
+from .local.history import G90History
+from .local.user_data_crc import G90UserDataCRC
 from .callback import G90Callback
 from .exceptions import G90Error, G90TimeoutError
+from .cloud.notifications import G90CloudNotifications
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -151,7 +162,7 @@ if TYPE_CHECKING:
 
 
 # pylint: disable=too-many-public-methods
-class G90Alarm(G90DeviceNotifications):
+class G90Alarm(G90NotificationProtocol):
 
     """
     Allows to interact with G90 alarm panel.
@@ -167,21 +178,15 @@ class G90Alarm(G90DeviceNotifications):
      simulated to go into inactive state.
     """
     # pylint: disable=too-many-instance-attributes,too-many-arguments
-    def __init__(self, host: str, port: int = REMOTE_PORT,
-                 reset_occupancy_interval: float = 3.0,
-                 notifications_local_host: str = LOCAL_NOTIFICATIONS_HOST,
-                 notifications_local_port: int = LOCAL_NOTIFICATIONS_PORT):
-        super().__init__(
-            local_host=notifications_local_host,
-            local_port=notifications_local_port
-        )
+    def __init__(
+        self, host: str, port: int = REMOTE_PORT,
+        reset_occupancy_interval: float = 3.0
+    ) -> None:
         self._host: str = host
         self._port: int = port
-        self._sensors: List[G90Sensor] = []
-        self._sensors_lock = asyncio.Lock()
-        self._devices: List[G90Device] = []
-        self._devices_lock = asyncio.Lock()
-        self._notifications: Optional[G90DeviceNotifications] = None
+        self._notifications: Optional[G90NotificationsBase] = None
+        self._sensors = G90SensorList(self)
+        self._devices = G90DeviceList(self)
         self._sensor_cb: Optional[SensorCallback] = None
         self._armdisarm_cb: Optional[ArmDisarmCallback] = None
         self._door_open_close_cb: Optional[DoorOpenCloseCallback] = None
@@ -201,6 +206,24 @@ class G90Alarm(G90DeviceNotifications):
         self._alert_simulation_task: Optional[Task[Any]] = None
         self._alert_simulation_start_listener_back = False
 
+    @property
+    def host(self) -> str:
+        """
+        Returns the hostname or IP address of the alarm panel.
+
+        This is the address used for communication with the device.
+        """
+        return self._host
+
+    @property
+    def port(self) -> int:
+        """
+        Returns the UDP port number used to communicate with the alarm panel.
+
+        By default, this is set to the standard G90 protocol port.
+        """
+        return self._port
+
     async def command(
         self, code: G90Commands, data: Optional[G90BaseCommandData] = None
     ) -> G90BaseCommandData:
@@ -268,109 +291,58 @@ class G90Alarm(G90DeviceNotifications):
     @property
     async def sensors(self) -> List[G90Sensor]:
         """
-        Property over new :meth:`.get_sensors` method, retained for
-        compatibility.
+        Returns the list of sensors configured in the device. Please note
+        it doesn't update those from the panel except initially when the list
+        if empty.
+
+        :return: List of sensors
         """
-        return await self.get_sensors()
+        return await self._sensors.entities
 
     async def get_sensors(self) -> List[G90Sensor]:
         """
-        Provides list of sensors configured in the device. Please note the list
-        is cached upon first call, so you need to re-instantiate the class to
-        reflect any updates there.
+        Provides list of sensors configured in the device, updating them from
+        panel on each call.
 
         :return: List of sensors
         """
-        # Use lock around the operation, to ensure no duplicated entries in the
-        # resulting list or redundant exchanges with panel are made when the
-        # method is called concurrently
-        async with self._sensors_lock:
-            if not self._sensors:
-                sensors = self.paginated_result(
-                    G90Commands.GETSENSORLIST
-                )
-                async for sensor in sensors:
-                    obj = G90Sensor(
-                        *sensor.data, parent=self, subindex=0,
-                        proto_idx=sensor.proto_idx
-                    )
-                    self._sensors.append(obj)
-
-                _LOGGER.debug(
-                    'Total number of sensors: %s', len(self._sensors)
-                )
+        return await self._sensors.update()
 
-            return self._sensors
-
-    async def find_sensor(self, idx: int, name: str) -> Optional[G90Sensor]:
+    async def find_sensor(
+        self, idx: int, name: str, exclude_unavailable: bool = True
+    ) -> Optional[G90Sensor]:
         """
         Finds sensor by index and name.
 
         :param idx: Sensor index
         :param name: Sensor name
+        :param exclude_unavailable: Flag indicating if unavailable sensors
+         should be excluded from the search
         :return: Sensor instance
         """
-        sensors = await self.get_sensors()
-
-        # Fast lookup by direct index
-        if idx < len(sensors) and sensors[idx].name == name:
-            sensor = sensors[idx]
-            _LOGGER.debug('Found sensor via fast lookup: %s', sensor)
-            return sensor
-
-        # Fast lookup failed, perform slow one over the whole sensors list
-        for sensor in sensors:
-            if sensor.index == idx and sensor.name == name:
-                _LOGGER.debug('Found sensor: %s', sensor)
-                return sensor
-
-        _LOGGER.error('Sensor not found: idx=%s, name=%s', idx, name)
-        return None
+        return await self._sensors.find(idx, name, exclude_unavailable)
 
     @property
     async def devices(self) -> List[G90Device]:
         """
-        Property over new :meth:`.get_devices` method, retained for
-        compatibility.
+        Returns the list of devices (switches) configured in the device. Please
+        note it doesn't update those from the panel except initially when
+        the list if empty.
+
+        :return: List of devices
         """
-        return await self.get_devices()
+        return await self._devices.entities
 
     async def get_devices(self) -> List[G90Device]:
         """
-        Provides list of devices (switches) configured in the device. Please
-        note the list is cached upon first call, so you need to re-instantiate
-        the class to reflect any updates there. Multi-node devices, those
+        Provides list of devices (switches) configured in the device, updating
+        them from panel on each call. Multi-node devices, those
         having multiple ports, are expanded into corresponding number of
         resulting entries.
 
         :return: List of devices
         """
-        # See `get_sensors` method for the rationale behind the lock usage
-        async with self._devices_lock:
-            if not self._devices:
-                devices = self.paginated_result(
-                    G90Commands.GETDEVICELIST
-                )
-                async for device in devices:
-                    obj = G90Device(
-                        *device.data, parent=self, subindex=0,
-                        proto_idx=device.proto_idx
-                    )
-                    self._devices.append(obj)
-                    # Multi-node devices (first node has already been added
-                    # above
-                    for node in range(1, obj.node_count):
-                        obj = G90Device(
-                            *device.data, parent=self,
-                            subindex=node, proto_idx=device.proto_idx
-                        )
-                        self._devices.append(obj)
-
-                _LOGGER.debug(
-                    'Total number of devices: %s', len(self._devices)
-                )
-
-            return self._devices
+        return await self._devices.update()
 
     @property
     async def host_info(self) -> G90HostInfo:
@@ -389,7 +361,8 @@ class G90Alarm(G90DeviceNotifications):
         """
         res = await self.command(G90Commands.GETHOSTINFO)
         info = G90HostInfo(*res)
-        self.device_id = info.host_guid
+        if self._notifications:
+            self._notifications.device_id = info.host_guid
         return info
 
     @property
@@ -544,6 +517,9 @@ class G90Alarm(G90DeviceNotifications):
             alert_config_flags = await self.alert_config
             door_close_alert_enabled = (
                 G90AlertConfigFlags.DOOR_CLOSE in alert_config_flags)
+            # The condition intentionally doesn't account for cord sensors of
+            # subtype door, since those won't send door open/close alerts, only
+            # notifications
             sensor_is_door = sensor.type == G90SensorTypes.DOOR
 
             # Alarm panel could emit door close alerts (if enabled) for sensors
@@ -553,7 +529,7 @@ class G90Alarm(G90DeviceNotifications):
             if not door_close_alert_enabled or not sensor_is_door:
                 _LOGGER.debug("Sensor '%s' is not a door (type %s),"
                               ' or door close alert is disabled'
-                              ' (alert config flags %s),'
+                              ' (alert config flags %s) or is a cord sensor,'
                               ' closing event will be emulated upon'
                               ' %s seconds',
                               name, sensor.type, alert_config_flags,
@@ -637,7 +613,7 @@ class G90Alarm(G90DeviceNotifications):
 
         # Reset the tampered and door open when arming flags on all sensors
         # having those set
-        for sensor in await self.get_sensors():
+        for sensor in await self.sensors:
             if sensor.is_tampered:
                 # pylint: disable=protected-access
                 sensor._set_tampered(False)
@@ -882,17 +858,19 @@ class G90Alarm(G90DeviceNotifications):
     def tamper_callback(self, value: TamperCallback) -> None:
         self._tamper_cb = value
 
-    async def listen_device_notifications(self) -> None:
+    async def listen_notifications(self) -> None:
         """
         Starts internal listener for device notifications/alerts.
         """
-        await self.listen()
+        if self._notifications:
+            await self._notifications.listen()
 
-    def close_device_notifications(self) -> None:
+    async def close_notifications(self) -> None:
         """
         Closes the listener for device notifications/alerts.
         """
-        self.close()
+        if self._notifications:
+            await self._notifications.close()
 
     async def arm_away(self) -> None:
         """
@@ -947,9 +925,12 @@ class G90Alarm(G90DeviceNotifications):
           each polling cycle
         """
         # Remember if device notifications listener has been started already
-        self._alert_simulation_start_listener_back = self.listener_started
+        self._alert_simulation_start_listener_back = (
+            self._notifications is not None
+            and self._notifications.listener_started
+        )
         # And then stop it
-        self.close()
+        await self.close_notifications()
 
         # Start the task
         self._alert_simulation_task = asyncio.create_task(
@@ -971,8 +952,11 @@ class G90Alarm(G90DeviceNotifications):
 
         # Start device notifications listener back if it was running when
         # simulated alerts have been enabled
-        if self._alert_simulation_start_listener_back:
-            await self.listen()
+        if (
+            self._notifications
+            and self._alert_simulation_start_listener_back
+        ):
+            await self._notifications.listen()
 
     async def _simulate_alerts_from_history(
         self, interval: float, history_depth: int
@@ -986,6 +970,10 @@ class G90Alarm(G90DeviceNotifications):
 
         See :meth:`.start_simulating_alerts_from_history` for the parameters.
         """
+        dummy_notifications = G90NotificationsBase(
+            protocol_factory=lambda: self
+        )
+
         last_history_ts = None
 
         _LOGGER.debug(
@@ -1029,8 +1017,7 @@ class G90Alarm(G90DeviceNotifications):
                         # Send the history entry down the device notification
                         # code as alert, as if it came from the device and its
                         # notifications port
-                        self._handle_alert(
-                            (self._host, self._notifications_local_port),
+                        dummy_notifications.handle_alert(
                             item.as_device_alert(),
                             # Skip verifying device GUID, since history entry
                             # don't have it
@@ -1056,3 +1043,61 @@ class G90Alarm(G90DeviceNotifications):
 
             # Sleep to next iteration
             await asyncio.sleep(interval)
+
+    async def use_local_notifications(
+        self, notifications_local_host: str = LOCAL_NOTIFICATIONS_HOST,
+        notifications_local_port: int = LOCAL_NOTIFICATIONS_PORT
+    ) -> None:
+        """
+        Switches to use local notifications for device alerts.
+        """
+        await self.close_notifications()
+
+        self._notifications = G90LocalNotifications(
+            protocol_factory=lambda: self,
+            host=self._host,
+            port=self._port,
+            local_host=notifications_local_host,
+            local_port=notifications_local_port
+        )
+
+    async def use_cloud_notifications(
+        self, cloud_local_host: str = CLOUD_NOTIFICATIONS_HOST,
+        cloud_local_port: int = CLOUD_NOTIFICATIONS_PORT,
+        upstream_host: str = REMOTE_CLOUD_HOST,
+        upstream_port: int = REMOTE_CLOUD_PORT,
+        keep_single_connection: bool = True
+    ) -> None:
+        """
+        Switches to use cloud notifications for device alerts.
+        """
+        await self.close_notifications()
+
+        self._notifications = G90CloudNotifications(
+            protocol_factory=lambda: self,
+            upstream_host=upstream_host,
+            upstream_port=upstream_port,
+            local_host=cloud_local_host,
+            local_port=cloud_local_port,
+            keep_single_connection=keep_single_connection
+        )
+
+    @property
+    def last_device_packet_time(self) -> Optional[datetime]:
+        """
+        Returns the time of the last packet received from the device.
+        """
+        if not self._notifications:
+            return None
+
+        return self._notifications.last_device_packet_time
+
+    @property
+    def last_upstream_packet_time(self) -> Optional[datetime]:
+        """
+        Returns the time of the last packet received from the upstream server.
+        """
+        if not self._notifications:
+            return None
+
+        return self._notifications.last_upstream_packet_time

pyg90alarm/cloud/__init__.py

@@ -0,0 +1,31 @@
+# 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
+# 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.
+
+"""
+Cloud communication implementation for G90 alarm systems.
+
+This module provides the necessary components to interact with G90 alarm
+systems through their cloud protocol (referred to as version 1.1).
+"""
+from .notifications import G90CloudNotifications  # noqa: F401
+
+__all__ = [
+    'G90CloudNotifications',
+]

pyg90alarm/cloud/const.py

@@ -0,0 +1,56 @@
+# 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
+# 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.
+
+"""
+Constants used in the G90 cloud protocol implementation.
+
+This module defines the main enumerations for direction and command types
+used in the cloud protocol communication with G90 alarm systems.
+"""
+from enum import IntEnum
+
+
+class G90CloudDirection(IntEnum):
+    """
+    Defines the direction of G90 cloud protocol messages.
+
+    These values indicate whether messages are flowing from the cloud to the
+    device, from the device to the cloud, or are part of discovery processes.
+    """
+    UNSPECIFIED = 0
+    CLOUD = 32  # 0x20
+    DEVICE = 16  # 0x10
+    DEVICE_DISCOVERY = 48  # 0x30
+    CLOUD_DISCOVERY = 208  # 0xD0
+
+
+class G90CloudCommand(IntEnum):
+    """
+    Defines the command types used in G90 cloud protocol messages.
+
+    These values identify the purpose of each cloud protocol message,
+    such as hello messages, notifications, commands, and status updates.
+    """
+    HELLO = 0x01
+    HELLO_ACK = 0x41
+    NOTIFICATION = 0x22
+    STATUS_CHANGE = 0x21
+    HELLO_INFO = 0x63
+    COMMAND = 0x29