pyg90alarm 1.10.1__tar.gz → 1.13.0__tar.gz

{pyg90alarm-1.10.1 → pyg90alarm-1.13.0}/.github/workflows/main.yml

@@ -31,6 +31,9 @@ jobs:
           - os: ubuntu-latest
             python: '3.11'
             toxenv: py
+          - os: ubuntu-latest
+            python: '3.12'
+            toxenv: py
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout the code

{pyg90alarm-1.10.1 → pyg90alarm-1.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyg90alarm
-Version: 1.10.1
+Version: 1.13.0
 Summary: G90 Alarm system protocol
 Home-page: https://github.com/hostcc/pyg90alarm
 Author: Ilia Sotnikov
@@ -22,10 +22,15 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.7, <4
 Description-Content-Type: text/x-rst
+License-File: LICENSE
 Provides-Extra: dev
+Requires-Dist: check-manifest; extra == "dev"
 Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: asynctest; extra == "test"
 Provides-Extra: docs
-License-File: LICENSE
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
 
 .. image::  https://github.com/hostcc/pyg90alarm/actions/workflows/main.yml/badge.svg?branch=master
    :target: https://github.com/hostcc/pyg90alarm/tree/master
@@ -153,6 +158,13 @@ set the IP address allocation up.
    status will not be reflected and those will always be reported as inactive,
    since there is no way to read their state in a polled manner.
 
+   To work that limitation around the package now supports simulating device
+   notifications from periodically polling the history it records - the
+   simulation works only for the alerts, not notifications (e.g. notifications
+   include low battery events and alike). This also requires the particular
+   alert to be enabled in the mobile application, otherwise it won't be
+   recorded in the history.
+
 Quick start
 ===========
 

{pyg90alarm-1.10.1 → pyg90alarm-1.13.0}/README.rst

@@ -124,6 +124,13 @@ set the IP address allocation up.
    status will not be reflected and those will always be reported as inactive,
    since there is no way to read their state in a polled manner.
 
+   To work that limitation around the package now supports simulating device
+   notifications from periodically polling the history it records - the
+   simulation works only for the alerts, not notifications (e.g. notifications
+   include low battery events and alike). This also requires the particular
+   alert to be enabled in the mobile application, otherwise it won't be
+   recorded in the history.
+
 Quick start
 ===========
 

pyg90alarm-1.13.0/docs/requirements.txt

@@ -0,0 +1,10 @@
+sphinx-rtd-theme
+enum-tools[sphinx]
+pygments>=2.15.0 # not directly required, pinned by Snyk to avoid a vulnerability
+sphinx>=3.3.0 # not directly required, pinned by Snyk to avoid a vulnerability
+setuptools>=65.5.1 # not directly required, pinned by Snyk to avoid a vulnerability
+certifi>=2023.7.22 # not directly required, pinned by Snyk to avoid a vulnerability
+requests>=2.32.0 # not directly required, pinned by Snyk to avoid a vulnerability
+jinja2>=3.1.4 # not directly required, pinned by Snyk to avoid a vulnerability
+requests>=2.31.0 # not directly required, pinned by Snyk to avoid a vulnerability
+idna>=3.7 # not directly required, pinned by Snyk to avoid a vulnerability

{pyg90alarm-1.10.1 → pyg90alarm-1.13.0}/src/pyg90alarm/alarm.py

@@ -48,7 +48,7 @@ G90HostInfo(host_guid='<...>',
             wifi_signal_level=100)
 
 """
-
+import asyncio
 import logging
 from .const import (
     G90Commands, REMOTE_PORT,
@@ -72,11 +72,14 @@ from .config import (G90AlertConfig, G90AlertConfigFlags)
 from .history import G90History
 from .user_data_crc import G90UserDataCRC
 from .callback import G90Callback
+from .exceptions import G90Error, G90TimeoutError
 
 _LOGGER = logging.getLogger(__name__)
 
 
-class G90Alarm:  # pylint: disable=too-many-public-methods
+# pylint: disable=too-many-public-methods
+class G90Alarm(G90DeviceNotifications):
+
     """
     Allows to interact with G90 alarm panel.
 
@@ -92,9 +95,12 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
      simulated to go into inactive state.
     :type reset_occupancy_interval: int, optional
     """
-    # pylint: disable=too-many-instance-attributes
+    # pylint: disable=too-many-instance-attributes,too-many-arguments
     def __init__(self, host, port=REMOTE_PORT,
-                 reset_occupancy_interval=3):
+                 reset_occupancy_interval=3,
+                 notifications_host='0.0.0.0',
+                 notifications_port=NOTIFICATIONS_PORT):
+        super().__init__(host=notifications_host, port=notifications_port)
         self._host = host
         self._port = port
         self._sensors = []
@@ -104,9 +110,12 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
         self._armdisarm_cb = None
         self._door_open_close_cb = None
         self._alarm_cb = None
+        self._low_battery_cb = None
         self._reset_occupancy_interval = reset_occupancy_interval
         self._alert_config = None
         self._sms_alert_when_armed = False
+        self._alert_simulation_task = None
+        self._alert_simulation_start_listener_back = False
 
     async def command(self, code, data=None):
         """
@@ -400,10 +409,15 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
         """
         res = self.paginated_result(G90Commands.GETHISTORY,
                                     start, count)
-        history = [G90History(*x.data) async for x in res]
-        return history
 
-    async def _internal_sensor_cb(self, idx, name, occupancy=True):
+        # Sort the history entries from older to newer - device typically does
+        # that, but apparently that is not guaranteed
+        return sorted(
+            [G90History(*x.data) async for x in res],
+            key=lambda x: x.datetime, reverse=True
+        )
+
+    async def on_sensor_activity(self, idx, name, occupancy=True):
         """
         Callback that invoked both for sensor notifications and door open/close
         alerts, since the logic for both is same and could be reused. Please
@@ -420,6 +434,7 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
          alerts (only for `door` type sensors, if door open/close alerts are
          enabled)
         """
+        _LOGGER.debug('on_sensor_activity: %s %s %s', idx, name, occupancy)
         sensor = await self.find_sensor(idx, name)
         if sensor:
             _LOGGER.debug('Setting occupancy to %s (previously %s)',
@@ -477,19 +492,21 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
     def sensor_callback(self, value):
         self._sensor_cb = value
 
-    async def _internal_door_open_close_cb(self, idx, name, is_open):
+    async def on_door_open_close(self, event_id, zone_name, is_open):
         """
         Callback that invoked when door open/close alert comes from the alarm
         panel. Please note the callback is for internal use by the class.
 
-        .. seealso:: `method`:_internal_sensor_cb for arguments
+        .. seealso:: `method`:on_sensor_activity for arguments
         """
         # Same internal callback is reused both for door open/close alerts and
         # sensor notifications. The former adds reporting when a door is
         # closed, since the notifications aren't sent for such events
-        await self._internal_sensor_cb(idx, name, is_open)
+        await self.on_sensor_activity(event_id, zone_name, is_open)
         # Invoke user specified callback if any
-        G90Callback.invoke(self._door_open_close_cb, idx, name, is_open)
+        G90Callback.invoke(
+            self._door_open_close_cb, event_id, zone_name, is_open
+        )
 
     @property
     def door_open_close_callback(self):
@@ -509,7 +526,7 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
         """
         self._door_open_close_cb = value
 
-    async def _internal_armdisarm_cb(self, state):
+    async def on_armdisarm(self, state):
         """
         Callback that invoked when the device is armed or disarmed. Please note
         the callback is for internal use by the class.
@@ -545,7 +562,7 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
     def armdisarm_callback(self, value):
         self._armdisarm_cb = value
 
-    async def _internal_alarm_cb(self, sensor_idx, sensor_name):
+    async def on_alarm(self, event_id, zone_name):
         """
         Callback that invoked when alarm is triggered. Fires alarm callback if
         set by the user with `:property:G90Alarm.alarm_callback`.
@@ -554,14 +571,20 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
         :param int: Index of the sensor triggered alarm
         :param str: Sensor name
         """
-        sensor = await self.find_sensor(sensor_idx, sensor_name)
+        sensor = await self.find_sensor(event_id, zone_name)
         # The callback is still delivered to the caller even if the sensor
-        # isn't found, only `extra_data` is skipped. That is to ensur the
+        # isn't found, only `extra_data` is skipped. That is to ensure the
         # important callback isn't filtered
         extra_data = sensor.extra_data if sensor else None
+        # Invoke the sensor activity callback to set the sensor occupancy if
+        # sensor is known, but only if that isn't already set - it helps when
+        # device notifications on triggerring sensor's activity aren't receveid
+        # by a reason
+        if sensor and not sensor.occupancy:
+            await self.on_sensor_activity(event_id, zone_name, True)
 
         G90Callback.invoke(
-            self._alarm_cb, sensor_idx, sensor_name, extra_data
+            self._alarm_cb, event_id, zone_name, extra_data
         )
 
     @property
@@ -581,27 +604,49 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
     def alarm_callback(self, value):
         self._alarm_cb = value
 
-    async def listen_device_notifications(
-        self, host='0.0.0.0', port=NOTIFICATIONS_PORT
-    ):
+    async def on_low_battery(self, event_id, zone_name):
+        """
+        Callback that invoked when the sensor reports on low battery. Fires
+        corresponding callback if set by the user with
+        `:property:G90Alarm.on_low_battery_callback`.
+        Please note the callback is for internal use by the class.
+
+        :param int: Index of the sensor triggered alarm
+        :param str: Sensor name
+        """
+        sensor = await self.find_sensor(event_id, zone_name)
+        if sensor:
+            # Invoke per-sensor callback if provided
+            G90Callback.invoke(sensor.low_battery_callback)
+
+        G90Callback.invoke(self._low_battery_cb, event_id, zone_name)
+
+    @property
+    def low_battery_callback(self):
+        """
+        Get or set low battery callback, the callback is invoked when sensor
+        the condition is reported by a sensor.
+
+        :type: .. py:function:: ()(idx, name)
+        """
+        return self._low_battery_cb
+
+    @low_battery_callback.setter
+    def low_battery_callback(self, value):
+        self._low_battery_cb = value
+
+    async def listen_device_notifications(self):
         """
         Starts internal listener for device notifications/alerts.
 
         """
-        self._notifications = G90DeviceNotifications(
-            host=host, port=port,
-            sensor_cb=self._internal_sensor_cb,
-            door_open_close_cb=self._internal_door_open_close_cb,
-            armdisarm_cb=self._internal_armdisarm_cb,
-            alarm_cb=self._internal_alarm_cb)
-        await self._notifications.listen()
+        await self.listen()
 
     def close_device_notifications(self):
         """
         Closes the listener for device notifications/alerts.
         """
-        if self._notifications:
-            self._notifications.close()
+        self.close()
 
     async def arm_away(self):
         """
@@ -638,3 +683,125 @@ class G90Alarm:  # pylint: disable=too-many-public-methods
     @sms_alert_when_armed.setter
     def sms_alert_when_armed(self, value):
         self._sms_alert_when_armed = value
+
+    async def start_simulating_alerts_from_history(
+        self, interval=5, history_depth=5
+    ):
+        """
+        Starts the separate task to simulate device alerts from history
+        entries.
+
+        The listener for device notifications will be stopped, so device
+        notifications will not be processed thus resulting in possible
+        duplicated if those could be received from the network.
+
+        :param int interval: Interval (in seconds) between polling for newer
+          history entities
+        :param int history_depth: Amount of history entries to fetch during
+          each polling cycle
+        """
+        # Remember if device notifications listener has been started already
+        self._alert_simulation_start_listener_back = self.listener_started
+        # And then stop it
+        self.close()
+
+        # Start the task
+        self._alert_simulation_task = asyncio.create_task(
+            self._simulate_alerts_from_history(interval, history_depth)
+        )
+
+    async def stop_simulating_alerts_from_history(self):
+        """
+        Stops the task simulating device alerts from history entries.
+
+        The listener for device notifications will be started back, if it was
+        running when simulation has been started.
+        """
+        # Stop the task simulating the device alerts from history if it was
+        # running
+        if self._alert_simulation_task:
+            self._alert_simulation_task.cancel()
+            self._alert_simulation_task = None
+
+        # 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()
+
+    async def _simulate_alerts_from_history(self, interval, history_depth):
+        """
+        Periodically fetches history entries from the device and simulates
+        device alerts off of those.
+
+        Only the history entries occur after the process is started are
+        handled, to avoid triggering callbacks retrospectively.
+
+        See :method:`start_simulating_alerts_from_history` for the parameters.
+        """
+        last_history_ts = None
+
+        _LOGGER.debug(
+            'Simulating device alerts from history:'
+            ' interval %s, history depth %s',
+            interval, history_depth
+        )
+        while True:
+            try:
+                # Retrieve the history entries of the specified amount - full
+                # history retrieval might be an unnecessary long operation
+                history = await self.history(count=history_depth)
+
+                # Initial iteration where no timestamp of most recent history
+                # entry is recorded - do that and skip to next iteration, since
+                # it isn't yet known what entries would be considered as new
+                # ones.
+                # Empty history will skip recording the timestamp and the
+                # looping over entries below, effectively skipping to next
+                # iteration
+                if not last_history_ts and history:
+                    # First entry in the list is assumed to be the most recent
+                    # one
+                    last_history_ts = history[0].datetime
+                    _LOGGER.debug(
+                        'Initial time stamp of last history entry: %s',
+                        last_history_ts
+                    )
+                    continue
+
+                # Process history entries from older to newer to preserve the
+                # order of happenings
+                for item in reversed(history):
+                    # Process only the entries newer than one been recorded as
+                    # most recent one
+                    if item.datetime > last_history_ts:
+                        _LOGGER.debug(
+                            'Found newer history entry: %s, simulating alert',
+                            repr(item)
+                        )
+                        # 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_port),
+                            item.as_device_alert()
+                        )
+
+                        # Record the entry as most recent one
+                        last_history_ts = item.datetime
+                        _LOGGER.debug(
+                            'Time stamp of last history entry: %s',
+                            last_history_ts
+                        )
+            except (G90Error, G90TimeoutError) as exc:
+                _LOGGER.debug(
+                    'Error interacting with device, ignoring %s', repr(exc)
+                )
+            except Exception as exc:
+                _LOGGER.error(
+                    'Exception simulating device alerts from history: %s',
+                    repr(exc)
+                )
+                raise exc
+
+            # Sleep to next iteration
+            await asyncio.sleep(interval)

{pyg90alarm-1.10.1 → pyg90alarm-1.13.0}/src/pyg90alarm/base_cmd.py

@@ -44,62 +44,6 @@ class G90Header(NamedTuple):
     data: Optional[str] = None
 
 
-class G90DeviceProtocol:
-    """
-    tbd
-
-    :meta private:
-    """
-    def __init__(self):
-        """
-        tbd
-        """
-        self._data = None
-
-    @property
-    def future_data(self):
-        """
-        tbd
-        """
-        return self._data
-
-    @future_data.setter
-    def future_data(self, value):
-        """
-        tbd
-        """
-        self._data = value
-
-    def connection_made(self, transport):
-        """
-        tbd
-        """
-
-    def connection_lost(self, exc):
-        """
-        tbd
-        """
-
-    def datagram_received(self, data, addr):
-        """
-        tbd
-        """
-        if asyncio.isfuture(self._data):
-            if self._data.done():
-                _LOGGER.warning('Excessive packet received'
-                                ' from %s:%s: %s',
-                                addr[0], addr[1], data)
-                return
-            self._data.set_result((*addr, data))
-
-    def error_received(self, exc):
-        """
-        tbd
-        """
-        if asyncio.isfuture(self._data) and not self._data.done():
-            self._data.set_exception(exc)
-
-
 class G90BaseCommand:
     """
     tbd
@@ -123,6 +67,7 @@ class G90BaseCommand:
         self._retries = retries
         self._data = '""'
         self._result = None
+        self._connection_result = None
         if data:
             self._data = json.dumps([code, data],
                                     # No newlines to be inserted
@@ -131,11 +76,39 @@ class G90BaseCommand:
                                     separators=(',', ':'))
         self._resp = G90Header()
 
-    def _proto_factory(self):
+    # Implementation of datagram protocol,
+    # https://docs.python.org/3/library/asyncio-protocol.html#datagram-protocols
+    def connection_made(self, transport):
+        """
+        tbd
+        """
+
+    def connection_lost(self, exc):
+        """
+        tbd
+        """
+
+    def datagram_received(self, data, addr):
+        """
+        tbd
+        """
+        if asyncio.isfuture(self._connection_result):
+            if self._connection_result.done():
+                _LOGGER.warning('Excessive packet received'
+                                ' from %s:%s: %s',
+                                addr[0], addr[1], data)
+                return
+            self._connection_result.set_result((*addr, data))
+
+    def error_received(self, exc):
         """
         tbd
         """
-        return G90DeviceProtocol()
+        if (
+            asyncio.isfuture(self._connection_result) and not
+            self._connection_result.done()
+        ):
+            self._connection_result.set_exception(exc)
 
     async def _create_connection(self):
         """
@@ -153,7 +126,7 @@ class G90BaseCommand:
             extra_kwargs['local_addr'] = ('0.0.0.0', self._local_port)
 
         transport, protocol = await loop.create_datagram_endpoint(
-            self._proto_factory,
+            lambda: self,
             remote_addr=(self.host, self.port),
             **extra_kwargs,
             allow_broadcast=True)
@@ -241,7 +214,7 @@ class G90BaseCommand:
         tbd
         """
 
-        transport, protocol = await self._create_connection()
+        transport, _ = await self._create_connection()
         attempts = self._retries
         while True:
             attempts = attempts - 1
@@ -249,24 +222,24 @@ class G90BaseCommand:
                 loop = asyncio.get_running_loop()
             except AttributeError:
                 loop = asyncio.get_event_loop()
-            protocol.future_data = loop.create_future()
+            self._connection_result = loop.create_future()
             async with self._sk_lock:
                 _LOGGER.debug('(code %s) Sending request to %s:%s',
                               self._code, self.host, self.port)
                 transport.sendto(self.to_wire())
-                done, _ = await asyncio.wait([protocol.future_data],
+                done, _ = await asyncio.wait([self._connection_result],
                                              timeout=self._timeout)
-            if protocol.future_data in done:
+            if self._connection_result in done:
                 break
             # Cancel the future to signal protocol handler it is no longer
             # valid, the future will be re-created on next retry
-            protocol.future_data.cancel()
+            self._connection_result.cancel()
             if not attempts:
                 transport.close()
                 raise G90TimeoutError()
             _LOGGER.debug('Timed out, retrying')
         transport.close()
-        (host, port, data) = protocol.future_data.result()
+        (host, port, data) = self._connection_result.result()
         _LOGGER.debug('Received response from %s:%s', host, port)
         if self.host != '255.255.255.255':
             if self.host != host or host == '255.255.255.255':

{pyg90alarm-1.10.1 → pyg90alarm-1.13.0}/src/pyg90alarm/const.py

@@ -185,10 +185,21 @@ class G90AlertSources(IntEnum):
     """
     Defines possible sources of the alert sent by the panel.
     """
+    DEVICE = 0
     SENSOR = 1
     DOORBELL = 12
 
 
+class G90AlertStates(IntEnum):
+    """
+    Defines possible states of the alert sent by the panel.
+    """
+    DOOR_CLOSE = 0
+    DOOR_OPEN = 1
+    TAMPER = 3
+    LOW_BATTERY = 4
+
+
 class G90AlertStateChangeTypes(IntEnum):
     """
     Defines types of alert for device state changes.
@@ -201,3 +212,21 @@ class G90AlertStateChangeTypes(IntEnum):
     LOW_BATTERY = 6
     WIFI_CONNECTED = 7
     WIFI_DISCONNECTED = 8
+
+
+class G90HistoryStates(IntEnum):
+    """
+    Defines possible states for history entities.
+    """
+    DOOR_CLOSE = 1
+    DOOR_OPEN = 2
+    TAMPER = 3
+    ALARM = 4
+    AC_POWER_FAILURE = 5
+    AC_POWER_RECOVER = 6
+    DISARM = 7
+    ARM_AWAY = 8
+    ARM_HOME = 9
+    LOW_BATTERY = 10
+    WIFI_CONNECTED = 11
+    WIFI_DISCONNECTED = 12