pyg90alarm 2.1.0__py3-none-any.whl → 2.2.0__py3-none-any.whl

pyg90alarm/entities/sensor.py

@@ -29,9 +29,17 @@ from typing import (
 )
 
 from enum import IntEnum, IntFlag
-from ..definitions.sensors import SENSOR_DEFINITIONS, SensorDefinition
+from ..definitions.base import (
+    G90PeripheralDefinition,
+    G90PeripheralProtocols, G90PeripheralTypes,
+)
+from ..definitions.sensors import (
+    G90SensorDefinitions,
+)
 from ..const import G90Commands
 from .base_entity import G90BaseEntity
+from ..callback import G90CallbackList
+from ..exceptions import G90PeripheralDefinitionNotFound
 if TYPE_CHECKING:
     from ..alarm import (
         G90Alarm, SensorStateCallback, SensorLowBatteryCallback,
@@ -146,57 +154,6 @@ ALERT_MODES_MAP_BY_VALUE = dict(
 )
 
 
-class G90SensorProtocols(IntEnum):
-    """
-    Protocol types for the sensors.
-    """
-    RF_1527 = 0
-    RF_2262 = 1
-    RF_PRIVATE = 2
-    RF_SLIDER = 3
-    CORD = 5
-    WIFI = 4
-    USB = 6
-
-
-class G90SensorTypes(IntEnum):
-    """
-    Sensor types.
-    """
-    DOOR = 1
-    GLASS = 2
-    GAS = 3
-    SMOKE = 4
-    SOS = 5
-    VIB = 6
-    WATER = 7
-    INFRARED = 8
-    IN_BEAM = 9
-    REMOTE = 10
-    RFID = 11
-    DOORBELL = 12
-    BUTTONID = 13
-    WATCH = 14
-    FINGER_LOCK = 15
-    SUBHOST = 16
-    REMOTE_2_4G = 17
-    CORD_SENSOR = 126
-    SOCKET = 128
-    SIREN = 129
-    CURTAIN = 130
-    SLIDINGWIN = 131
-    AIRCON = 136
-    TV = 137
-    NIGHTLIGHT = 138
-    SOCKET_2_4G = 140
-    SIREN_2_4G = 141
-    SWITCH_2_4G = 142
-    TOUCH_SWITCH_2_4G = 143
-    CURTAIN_2_4G = 144
-    CORD_DEV = 254
-    UNKNOWN = 255
-
-
 _LOGGER = logging.getLogger(__name__)
 
 
@@ -227,28 +184,45 @@ class G90Sensor(G90BaseEntity):  # pylint:disable=too-many-instance-attributes
         self._parent = parent
         self._subindex = subindex
         self._occupancy = False
-        self._state_callback: Optional[SensorStateCallback] = None
-        self._low_battery_callback: Optional[SensorLowBatteryCallback] = None
+        self._state_callback: G90CallbackList[SensorStateCallback] = (
+            G90CallbackList()
+        )
+        self._low_battery_callback: G90CallbackList[
+            SensorLowBatteryCallback
+        ] = G90CallbackList()
         self._low_battery = False
         self._tampered = False
-        self._door_open_when_arming_callback: Optional[
+        self._door_open_when_arming_callback: G90CallbackList[
             SensorDoorOpenWhenArmingCallback
-        ] = None
-        self._tamper_callback: Optional[SensorTamperCallback] = None
+        ] = G90CallbackList()
+        self._tamper_callback: G90CallbackList[SensorTamperCallback] = (
+            G90CallbackList()
+        )
         self._door_open_when_arming = False
         self._proto_idx = proto_idx
         self._extra_data: Any = None
         self._unavailable = False
+        self._definition: Optional[G90PeripheralDefinition] = None
 
-        self._definition: Optional[SensorDefinition] = None
-        # Get sensor definition corresponds to the sensor type/subtype if any
-        for s_def in SENSOR_DEFINITIONS:
-            if (
-                s_def.type == self._protocol_data.type_id
-                and s_def.subtype == self._protocol_data.subtype  # noqa:W503
-            ):
-                self._definition = s_def
-                break
+    @property
+    def definition(self) -> Optional[G90PeripheralDefinition]:
+        """
+        Returns the definition for the sensor.
+
+        :return: Sensor definition
+        """
+        if not self._definition:
+            # No definition has been cached, try to find it by type, subtype
+            # and protocol
+            try:
+                self._definition = (
+                    G90SensorDefinitions.get_by_id(
+                        self.type, self.subtype, self.protocol
+                    )
+                )
+            except G90PeripheralDefinitionNotFound:
+                return None
+        return self._definition
 
     def update(self, obj: G90Sensor) -> None:
         """
@@ -272,41 +246,49 @@ class G90Sensor(G90BaseEntity):  # pylint:disable=too-many-instance-attributes
         return f'{self._protocol_data.parent_name}#{self._subindex + 1}'
 
     @property
-    def state_callback(self) -> Optional[SensorStateCallback]:
+    def state_callback(self) -> G90CallbackList[SensorStateCallback]:
         """
         Callback that is invoked when the sensor changes its state.
 
         :return: Sensor state callback
+
+        .. seealso:: :attr:`G90Alarm.sensor_callback` for compatiblity notes
         """
         return self._state_callback
 
     @state_callback.setter
     def state_callback(self, value: SensorStateCallback) -> None:
-        self._state_callback = value
+        self._state_callback.add(value)
 
     @property
-    def low_battery_callback(self) -> Optional[SensorLowBatteryCallback]:
+    def low_battery_callback(
+        self
+    ) -> G90CallbackList[SensorLowBatteryCallback]:
         """
         Callback that is invoked when the sensor reports on low battery
         condition.
 
         :return: Sensor's low battery callback
+
+        .. seealso:: :attr:`G90Alarm.sensor_callback` for compatiblity notes
         """
         return self._low_battery_callback
 
     @low_battery_callback.setter
     def low_battery_callback(self, value: SensorLowBatteryCallback) -> None:
-        self._low_battery_callback = value
+        self._low_battery_callback.add(value)
 
     @property
     def door_open_when_arming_callback(
         self
-    ) -> Optional[SensorDoorOpenWhenArmingCallback]:
+    ) -> G90CallbackList[SensorDoorOpenWhenArmingCallback]:
         """
         Callback that is invoked when the sensor reports on open door
         condition when arming.
 
         :return: Sensor's door open when arming callback
+
+        .. seealso:: :attr:`G90Alarm.sensor_callback` for compatiblity notes
         """
         return self._door_open_when_arming_callback
 
@@ -314,20 +296,22 @@ class G90Sensor(G90BaseEntity):  # pylint:disable=too-many-instance-attributes
     def door_open_when_arming_callback(
         self, value: SensorDoorOpenWhenArmingCallback
     ) -> None:
-        self._door_open_when_arming_callback = value
+        self._door_open_when_arming_callback.add(value)
 
     @property
-    def tamper_callback(self) -> Optional[SensorTamperCallback]:
+    def tamper_callback(self) -> G90CallbackList[SensorTamperCallback]:
         """
         Callback that is invoked when the sensor reports being tampered.
 
         :return: Sensor's tamper callback
+
+        .. seealso:: :attr:`G90Alarm.sensor_callback` for compatiblity notes
         """
         return self._tamper_callback
 
     @tamper_callback.setter
     def tamper_callback(self, value: SensorTamperCallback) -> None:
-        self._tamper_callback = value
+        self._tamper_callback.add(value)
 
     @property
     def occupancy(self) -> bool:
@@ -355,22 +339,22 @@ class G90Sensor(G90BaseEntity):  # pylint:disable=too-many-instance-attributes
         self._occupancy = value
 
     @property
-    def protocol(self) -> G90SensorProtocols:
+    def protocol(self) -> G90PeripheralProtocols:
         """
         Protocol type of the sensor.
 
         :return: Protocol type
         """
-        return G90SensorProtocols(self._protocol_data.protocol_id)
+        return G90PeripheralProtocols(self._protocol_data.protocol_id)
 
     @property
-    def type(self) -> G90SensorTypes:
+    def type(self) -> G90PeripheralTypes:
         """
         Type of the sensor.
 
         :return: Sensor type
         """
-        return G90SensorTypes(self._protocol_data.type_id)
+        return G90PeripheralTypes(self._protocol_data.type_id)
 
     @property
     def subtype(self) -> int:
@@ -456,6 +440,18 @@ class G90Sensor(G90BaseEntity):  # pylint:disable=too-many-instance-attributes
         """
         return self._proto_idx
 
+    @property
+    def type_name(self) -> Optional[str]:
+        """
+        Type of the sensor.
+
+        :return: Type
+        """
+        if not self.definition:
+            return None
+
+        return self.definition.name
+
     @property
     def supports_updates(self) -> bool:
         """
@@ -463,14 +459,12 @@ class G90Sensor(G90BaseEntity):  # pylint:disable=too-many-instance-attributes
 
         :return: Support for updates
         """
-        if not self._definition:
+        if not self.definition:
             _LOGGER.warning(
                 'Manipulating with user flags for sensor index=%s'
                 ' is unsupported - no sensor definition for'
-                ' type=%s, subtype=%s',
-                self.index,
-                self._protocol_data.type_id,
-                self._protocol_data.subtype
+                ' type=%s, subtype=%s, protocol=%s',
+                self.index, self.type, self.subtype, self.protocol
             )
             return False
         return True
@@ -498,7 +492,7 @@ class G90Sensor(G90BaseEntity):  # pylint:disable=too-many-instance-attributes
         """
         Indicates if the sensor is wireless.
         """
-        return self.protocol not in (G90SensorProtocols.CORD,)
+        return self.protocol not in (G90PeripheralProtocols.CORD,)
 
     @property
     def is_low_battery(self) -> bool:
@@ -597,7 +591,7 @@ class G90Sensor(G90BaseEntity):  # pylint:disable=too-many-instance-attributes
         # Checking private attribute directly, since `mypy` doesn't recognize
         # the check for sensor definition is done over
         # `self.supports_updates` property
-        if not self._definition:
+        if not self.definition:
             return
 
         if value & ~G90SensorUserFlags.USER_SETTABLE:
@@ -685,11 +679,11 @@ class G90Sensor(G90BaseEntity):  # pylint:disable=too-many-instance-attributes
             user_flags_data=self._protocol_data.user_flags_data,
             baudrate=self._protocol_data.baudrate,
             protocol_id=self._protocol_data.protocol_id,
-            reserved_data=self._definition.reserved_data,
+            reserved_data=self.definition.reserved_data,
             node_count=self._protocol_data.node_count,
-            rx=self._definition.rx,
-            tx=self._definition.tx,
-            private_data=self._definition.private_data,
+            rx=self.definition.rx,
+            tx=self.definition.tx,
+            private_data=self.definition.private_data,
         )
         # Modify the sensor
         await self._parent.command(

pyg90alarm/entities/sensor_list.py

@@ -20,19 +20,32 @@
 """
 Sensor list.
 """
-from typing import (
-    AsyncGenerator
-)
+from __future__ import annotations
+from typing import AsyncGenerator, Optional, TYPE_CHECKING
+import logging
+import asyncio
 
 from .sensor import G90Sensor
 from .base_list import G90BaseList
 from ..const import G90Commands
+from ..exceptions import G90EntityRegistrationError, G90Error
+from ..definitions.sensors import G90SensorDefinitions
+from ..entities.sensor import G90SensorUserFlags
+
+if TYPE_CHECKING:
+    from ..alarm import G90Alarm
+
+_LOGGER = logging.getLogger(__name__)
 
 
 class G90SensorList(G90BaseList[G90Sensor]):
     """
     Sensor list class.
     """
+    def __init__(self, parent: G90Alarm) -> None:
+        super().__init__(parent)
+        self._sensor_change_future: Optional[asyncio.Future[G90Sensor]] = None
+
     async def _fetch(self) -> AsyncGenerator[G90Sensor, None]:
         """
         Fetch the list of sensors from the panel.
@@ -48,3 +61,123 @@ class G90SensorList(G90BaseList[G90Sensor]):
                 *entity.data, parent=self._parent, subindex=0,
                 proto_idx=entity.proto_idx
             )
+
+    async def sensor_change_callback(
+        self, idx: int, name: str, added: bool
+    ) -> None:
+        """
+        Sensor change callback.
+
+        Should be invoked from corresponding panel's notification handler to
+        finish the registration process.
+
+        :param idx: Sensor index.
+        :param name: Sensor name.
+        :param added: True if the sensor was added, False if removed.
+        """
+        _LOGGER.debug(
+            "Sensor change callback: name='%s', index=%d, added=%s",
+            name, idx, added
+        )
+        # The method depends on the future to be created before it is called
+        if not self._sensor_change_future:
+            raise G90EntityRegistrationError(
+                "Sensor change callback called without a future"
+            )
+
+        # Update the sensor list to get the latest data, unfortunately there is
+        # no panel command to get just a single sensor
+        try:
+            await self.update()
+        except G90Error as err:
+            _LOGGER.debug(
+                "Failed to update the sensor list: %s", err
+            )
+            # Indicate the error to the caller
+            self._sensor_change_future.set_exception(err)
+            return
+
+        # Attempt to find the sensor just changed by its index
+        if not (found := await self.find_by_idx(
+            idx, exclude_unavailable=False
+        )):
+            msg = (
+                f"Failed to find the added sensor '{name}'"
+                f' at index {idx}'
+            )
+            _LOGGER.debug(msg)
+            # Indicate the error to the caller
+            self._sensor_change_future.set_exception(
+                G90EntityRegistrationError(msg)
+            )
+            return
+
+        # Provide the found sensor as the future result so that the caller
+        # can use it
+        self._sensor_change_future.set_result(found)
+
+    async def register(
+        self, definition_name: str,
+        room_id: int, timeout: float, name: Optional[str] = None,
+    ) -> G90Sensor:
+        """
+        Registers sensor to the panel.
+
+        :param definition_name: Sensor definition name.
+        :param room_id: Room ID to assign the sensor to.
+        :param timeout: Timeout for the registration process.
+        :param name: Optional name for the sensor, if not provided, the
+         definition name will be used.
+        :raises G90EntityRegistrationError: If the registration fails.
+        :return: G90Sensor: The registered sensor entity.
+        """
+        sensor_definition = G90SensorDefinitions.get_by_name(definition_name)
+        dev_name = name or sensor_definition.name
+
+        # Future is needed to coordinate the registration process with panel
+        # notifications (see `sensor_change_callback()` method)
+        self._sensor_change_future = asyncio.get_running_loop().create_future()
+
+        # Register the sensor with the panel
+        await self._parent.command(
+            G90Commands.ADDSENSOR, [
+                dev_name,
+                # Registering sensor requires to provide a free index from
+                # panel point of view
+                await self.find_free_idx(),
+                room_id,
+                sensor_definition.type,
+                sensor_definition.subtype,
+                sensor_definition.timeout,
+                # Newly registered sensors are enabled by default and set to
+                # alarm in away and home modes
+                G90SensorUserFlags.ENABLED
+                | G90SensorUserFlags.ALERT_WHEN_AWAY_AND_HOME,
+                sensor_definition.baudrate,
+                sensor_definition.protocol,
+                sensor_definition.reserved_data,
+                sensor_definition.node_count,
+                sensor_definition.rx,
+                sensor_definition.tx,
+                sensor_definition.private_data
+            ]
+        )
+
+        # Waiting for the registration to finish, where panel will send
+        # corresponding notification processed by `sensor_change_callback()`
+        # method, which manipulates the future created above.
+        done, _ = await asyncio.wait(
+            [self._sensor_change_future], timeout=timeout
+        )
+
+        if self._sensor_change_future not in done:
+            msg = f"Failed to learn the device '{dev_name}', timed out"
+            _LOGGER.debug(msg)
+            raise G90EntityRegistrationError(msg)
+
+        # Propagate any exception that might have occurred in
+        # `sensor_change_callback()` method during the registration process
+        self._sensor_change_future.exception()
+
+        # Return the registered sensor entity
+        return self._sensor_change_future.result()

pyg90alarm/exceptions.py

@@ -37,3 +37,27 @@ class G90TimeoutError(asyncio.TimeoutError):  # pylint:disable=R0903
     Raised when particular package class to report an operation (typically
     device command) has timed out.
     """
+
+
+class G90CommandFailure(G90Error):
+    """
+    Raised when a command to the alarm panel reports failure.
+    """
+
+
+class G90CommandError(G90Error):
+    """
+    Raised when a command to the alarm panel reports an error.
+    """
+
+
+class G90EntityRegistrationError(G90Error):
+    """
+    Raised when registering an entity to the alarm panel fails.
+    """
+
+
+class G90PeripheralDefinitionNotFound(G90Error):
+    """
+    Raised when a peripheral definition is not found.
+    """

pyg90alarm/local/base_cmd.py

@@ -30,7 +30,9 @@ from asyncio.protocols import DatagramProtocol
 from asyncio.transports import DatagramTransport, BaseTransport
 from typing import Optional, Tuple, List, Any
 from dataclasses import dataclass
-from ..exceptions import (G90Error, G90TimeoutError)
+from ..exceptions import (
+    G90Error, G90TimeoutError, G90CommandFailure, G90CommandError
+)
 from ..const import G90Commands
 
 
@@ -168,19 +170,39 @@ class G90BaseCommand(DatagramProtocol):
         if not data.endswith('IEND\0'):
             raise G90Error('Missing end marker in data')
         payload = data[6:-5]
-        _LOGGER.debug("Decoded from wire: JSON string '%s'", payload)
+        _LOGGER.debug("Decoded from wire: string '%s'", payload)
+
+        if not payload:
+            return
+
+        # Panel may report the last command has failed
+        if payload == 'fail':
+            raise G90CommandFailure(
+                f"Command {self._code.name}"
+                f" (code={self._code.value}) failed"
+            )
+
+        # Also, panel may report an error supplying specific reason, e.g.
+        # command and its arguments that have failed
+        if payload.startswith('error'):
+            error = payload[5:]
+            raise G90CommandError(
+                f"Command {self._code.name}"
+                f" (code={self._code.value}) failed"
+                f" with error: '{error}'")
 
         resp = None
-        if payload:
-            try:
-                resp = json.loads(payload)
-            except json.JSONDecodeError as exc:
-                raise G90Error('Unable to parse response as JSON:'
-                               f" '{payload}'") from exc
-
-            if not isinstance(resp, list):
-                raise G90Error('Mailformed response,'
-                               f" 'list' expected: '{payload}'")
+        try:
+            resp = json.loads(payload, strict=False)
+        except json.JSONDecodeError as exc:
+            raise G90Error(
+                f"Unable to parse response as JSON: '{payload}'"
+            ) from exc
+
+        if not isinstance(resp, list):
+            raise G90Error(
+                f"Malformed response, 'list' expected: '{payload}'"
+            )
 
         if resp is not None:
             self._resp = G90Header(*resp)

pyg90alarm/local/notifications.py

@@ -42,12 +42,12 @@ class G90LocalNotifications(G90NotificationsBase, DatagramProtocol):
     There is a basic check to ensure only notifications/alerts from the correct
     device are processed - the check uses the host and port of the device, and
     the device ID (GUID) that is set by the ancestor class that implements the
-    commands (e.g. :class:`G90Alarm`). The latter to work correctly needs a
+    commands (e.g. :class:`.G90Alarm`). The latter to work correctly needs a
     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`).
+    it using :attr:`.device_id` (e.g. :meth:`.G90Alarm.get_host_info`).
 
     :param protocol_factory: A callable that returns a new instance of the
-     :class:`G90NotificationProtocol` class.
+     :class:`.G90NotificationProtocol` class.
     :param port: The port on which the device is listening for notifications.
     :param host: The host on which the device is listening for notifications.
     :param local_port: The port on which the local host is listening for

pyg90alarm/notifications/base.py

@@ -89,6 +89,18 @@ class G90ArmDisarmInfo:
     state: int
 
 
+@dataclass
+class G90SensorChangeInfo:
+    """
+    Represents the sensor added notification received from the device.
+
+    :meta private:
+    """
+    idx: int
+    name: str
+    action: int  # 1 - if added, 2 - for update (?)
+
+
 @dataclass
 class G90DeviceAlert:  # pylint: disable=too-many-instance-attributes
     """
@@ -112,9 +124,9 @@ class G90NotificationsBase:
     There is a basic check to ensure only notifications/alerts from the correct
     device are processed - the check uses the host and port of the device, and
     the device ID (GUID) that is set by the ancestor class that implements the
-    commands (e.g. :class:`G90Alarm`). The latter to work correctly needs a
+    commands (e.g. :class:`.G90Alarm`). The latter to work correctly needs a
     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`).
+    it using :attr:`.device_id` (e.g. :meth:`.G90Alarm.get_host_info`).
     """
     def __init__(
         self, protocol_factory: Callable[[], G90NotificationProtocol],
@@ -173,6 +185,21 @@ class G90NotificationsBase:
             )
             return
 
+        # Sensor has been added or removed
+        if notification.kind == G90NotificationTypes.SENSOR_CHANGE:
+            g90_sensor_info = G90SensorChangeInfo(*notification.data)
+            sensor_added = g90_sensor_info.action == 1
+            _LOGGER.debug(
+                'Sensor change notification, added=%s: %s',
+                sensor_added, g90_sensor_info
+            )
+            G90Callback.invoke(
+                self._protocol.on_sensor_change,
+                g90_sensor_info.idx, g90_sensor_info.name,
+                sensor_added
+            )
+            return
+
         _LOGGER.warning('Unknown notification received:'
                         ' kind %s, data %s',
                         notification.kind, notification.data)

pyg90alarm/notifications/protocol.py

@@ -114,3 +114,14 @@ class G90NotificationProtocol:
         :param zone_name: Name of the sensor that reports SOS.
         :param is_host_sos: Indicates if the SOS is host-initiated.
         """
+
+    async def on_sensor_change(
+        self, sensor_idx: int, sensor_name: str, added: bool
+    ) -> None:
+        """
+        Invoked when a sensor is added or changed on the panel.
+
+        :param sensor_idx: Index of the sensor.
+        :param sensor_name: Name of the sensor.
+        :param added: True if the sensor was added.
+        """

{pyg90alarm-2.1.0.dist-info → pyg90alarm-2.2.0.dist-info}/METADATA

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