qolsys-controller 0.0.12__tar.gz → 0.0.76__tar.gz

qolsys_controller-0.0.76/.github/workflows/build.yml

@@ -0,0 +1,30 @@
+name: Build
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint_and_typecheck:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install ruff mypy
+
+      - name: Ruff lint
+        run: ruff check .
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+      - name: Mypy type checking
+        run: mypy .

{qolsys_controller-0.0.12 → qolsys_controller-0.0.76}/.github/workflows/publish.yml

@@ -1,6 +1,7 @@
     name: Publish Python package to PyPI
 
     on:
+      workflow_dispatch:
       release:
         types: [published]
 

qolsys_controller-0.0.76/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: qolsys-controller
+Version: 0.0.76
+Summary: A Python module that emulates a virtual IQ Remote device, enabling full local control of a Qolsys IQ Panel
+Project-URL: Homepage, https://github.com/EHylands/QolsysController
+Project-URL: Issues, https://github.com/EHylands/QolsysController/issues
+Project-URL: Repository, https://github.com/EHylands/QolsysController.git
+Author: Eric Hylands
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Qolsys Controller - qolsys-controller
+
+[![Build](https://github.com/EHylands/QolsysController/actions/workflows/build.yml/badge.svg)](https://github.com/EHylands/QolsysController/actions/workflows/build.yml)
+
+A Python module that emulates a virtual IQ Remote device, enabling full **local control** of a Qolsys IQ Panel over MQTT — no cloud access required.
+
+## QolsysController
+- ✅ Connects directly to the **Qolsys Panel's local MQTT server as an IQ Remote**
+- 🔐 Pairs by only using **Installer Code** (same procedure as standard IQ Remote pairing)
+- 🔢 Supports **4-digit user codes**
+- ⚠️ Uses a **custom local usercode database** — panel's internal user code verification process is not yet supported
+
+## ✨ Functionality Highlights
+
+| Category               | Feature                              | Status |
+|------------------------|--------------------------------------|--------|
+| **Panel**              | Diagnostic Sensors                   | ✅     |
+|                        | Panel Scenes                         | ✅     |
+|                        | Weather Forecast                     | ✅     |
+|                        | (Alarm.com Weather to Panel)         |        |
+| **Partition**          | Arming Status                        | ✅     |
+|                        | Alarm State                          | ✅     |
+|                        | Home Instant Arming                  | ✅     |
+|                        | Home Silent Disarming (Firmware 4.6.1)| ✅     |
+|                        | Set Exit Sounds                      | ✅     |
+|                        | Set Entry Delay                      | ✅            |
+|                        | TTS                                  | 🛠️     |
+| **Zones**              | Sensor Status                        | ✅     |
+|                        | Tamper State                         | ✅     |
+|                        | Battery Level                        | ✅     |
+|                        | Temperature (supported PowerG device)| ✅     |
+|                        | Light (supported PowerG device)      | ✅     |
+|                        | Average dBm                          | ✅     |
+|                        | Latest dBm                           | ✅     |
+| **Z-Wave Devices**     | Battery Level                        | ✅     |
+|                        | Node Status                          | ✅     |
+|                        | Control Generic Devices              | TBD    |
+| **Z-Wave Dimmers**     | Binary Switch                        | ✅     |
+|                        | Multi Level Dimmer                   | ✅     |
+| **Z-Wave Door Locks**  | Lock, Unlock                         | ✅     |
+| **Z-Wave Thermostats** | Read device status                   | ✅     |
+|                        | Write device status                  | ✅     |
+| **Z-Wave Garage Doors**|                                      | 🛠️     |
+| **Z-Wave Outlets**     |                                      | 🛠️     |
+
+
+## ⚠️ Certificate Warning
+
+During pairing, the main panel issues **only one signed client certificate** per virtual IQ Remote. If any key files are lost or deleted, re-pairing may become impossible. 
+
+A new PKI, including a new private key, can be recreated under specific circumstances, though the precise conditions remain unknown at this time.
+
+**Important:**  
+Immediately back up the following files from the `pki/` directory after initial pairing:
+
+- `.key` (private key)
+- `.cer` (certificate)
+- `.csr` (certificate signing request)
+- `.secure` (signed client certificate)
+- `.qolsys` (Qolsys Panel public certificate)
+
+Store these files securely.
+
+## 📦 Installation
+
+```bash
+git clone https://github.com/EHylands/QolsysController.git
+cd qolsys_controller
+pip3.12 install -r requirements.txt
+
+# Change panel_ip and plugin_in in main.py file
+python3.12 example.py
+```

qolsys_controller-0.0.76/README.md

@@ -0,0 +1,73 @@
+# Qolsys Controller - qolsys-controller
+
+[![Build](https://github.com/EHylands/QolsysController/actions/workflows/build.yml/badge.svg)](https://github.com/EHylands/QolsysController/actions/workflows/build.yml)
+
+A Python module that emulates a virtual IQ Remote device, enabling full **local control** of a Qolsys IQ Panel over MQTT — no cloud access required.
+
+## QolsysController
+- ✅ Connects directly to the **Qolsys Panel's local MQTT server as an IQ Remote**
+- 🔐 Pairs by only using **Installer Code** (same procedure as standard IQ Remote pairing)
+- 🔢 Supports **4-digit user codes**
+- ⚠️ Uses a **custom local usercode database** — panel's internal user code verification process is not yet supported
+
+## ✨ Functionality Highlights
+
+| Category               | Feature                              | Status |
+|------------------------|--------------------------------------|--------|
+| **Panel**              | Diagnostic Sensors                   | ✅     |
+|                        | Panel Scenes                         | ✅     |
+|                        | Weather Forecast                     | ✅     |
+|                        | (Alarm.com Weather to Panel)         |        |
+| **Partition**          | Arming Status                        | ✅     |
+|                        | Alarm State                          | ✅     |
+|                        | Home Instant Arming                  | ✅     |
+|                        | Home Silent Disarming (Firmware 4.6.1)| ✅     |
+|                        | Set Exit Sounds                      | ✅     |
+|                        | Set Entry Delay                      | ✅            |
+|                        | TTS                                  | 🛠️     |
+| **Zones**              | Sensor Status                        | ✅     |
+|                        | Tamper State                         | ✅     |
+|                        | Battery Level                        | ✅     |
+|                        | Temperature (supported PowerG device)| ✅     |
+|                        | Light (supported PowerG device)      | ✅     |
+|                        | Average dBm                          | ✅     |
+|                        | Latest dBm                           | ✅     |
+| **Z-Wave Devices**     | Battery Level                        | ✅     |
+|                        | Node Status                          | ✅     |
+|                        | Control Generic Devices              | TBD    |
+| **Z-Wave Dimmers**     | Binary Switch                        | ✅     |
+|                        | Multi Level Dimmer                   | ✅     |
+| **Z-Wave Door Locks**  | Lock, Unlock                         | ✅     |
+| **Z-Wave Thermostats** | Read device status                   | ✅     |
+|                        | Write device status                  | ✅     |
+| **Z-Wave Garage Doors**|                                      | 🛠️     |
+| **Z-Wave Outlets**     |                                      | 🛠️     |
+
+
+## ⚠️ Certificate Warning
+
+During pairing, the main panel issues **only one signed client certificate** per virtual IQ Remote. If any key files are lost or deleted, re-pairing may become impossible. 
+
+A new PKI, including a new private key, can be recreated under specific circumstances, though the precise conditions remain unknown at this time.
+
+**Important:**  
+Immediately back up the following files from the `pki/` directory after initial pairing:
+
+- `.key` (private key)
+- `.cer` (certificate)
+- `.csr` (certificate signing request)
+- `.secure` (signed client certificate)
+- `.qolsys` (Qolsys Panel public certificate)
+
+Store these files securely.
+
+## 📦 Installation
+
+```bash
+git clone https://github.com/EHylands/QolsysController.git
+cd qolsys_controller
+pip3.12 install -r requirements.txt
+
+# Change panel_ip and plugin_in in main.py file
+python3.12 example.py
+```

{qolsys_controller-0.0.12 → qolsys_controller-0.0.76}/bin/qolsys.py

@@ -6,12 +6,11 @@ import logging
 import os
 import sys
 
-from qolsys_controller import qolsys_controller
+from qolsys_controller import qolsys_controller  # type: ignore[attr-defined]
 from qolsys_controller.errors import QolsysMqttError, QolsysSqlError, QolsysSslError
 
 
 async def main() -> None:  # noqa: D103
-
     cli_parser = argparse.ArgumentParser()
     cli_parser.add_argument("--panel-ip", help="Qolsys Panel IP", default="")
     cli_parser.add_argument("--plugin-ip", help="Plugin IP", default="")
@@ -28,26 +27,23 @@ async def main() -> None:  # noqa: D103
     asyncio.set_event_loop(loop)
 
     Panel = qolsys_controller()
-
-    # Select plugin
-    Panel.select_plugin("remote")
     Panel.settings.config_directory = args.config_dir
-    Panel.plugin.settings.panel_ip = args.panel_ip
-    Panel.plugin.settings.plugin_ip = args.plugin_ip
-    Panel.plugin.settings.random_mac = ""
+    Panel.settings.panel_ip = args.panel_ip
+    Panel.settings.plugin_ip = args.plugin_ip
+    Panel.settings.random_mac = ""
 
     # Additionnal remote plugin config
-    Panel.plugin.check_user_code_on_disarm = False
-    Panel.plugin.log_mqtt_mesages = args.debug
-    Panel.plugin.auto_discover_pki = args.pki_autodiscovery
+    Panel.settings.check_user_code_on_disarm = False
+    Panel.settings.log_mqtt_mesages = args.debug
+    Panel.settings.auto_discover_pki = args.pki_autodiscovery
 
     # Configure remote plugin
-    if not await Panel.plugin.config(start_pairing=True):
+    if not await Panel.config(start_pairing=True):
         LOGGER.debug("Error Configuring remote plugin")
         return
 
     try:
-        await Panel.plugin.start_operation()
+        await Panel.start_operation()
 
     except QolsysMqttError:
         LOGGER.debug("QolsysMqttError")
@@ -58,7 +54,7 @@ async def main() -> None:  # noqa: D103
     except QolsysSqlError:
         LOGGER.debug("QolsysSqlError")
 
-    if not Panel.plugin.connected:
+    if not Panel.connected:
         LOGGER.error("Panel not ready for operation")
         return
 
@@ -67,9 +63,14 @@ async def main() -> None:  # noqa: D103
     stop_event = asyncio.Event()
     await stop_event.wait()
 
+
 # Change to the "Selector" event loop if platform is Windows
 if sys.platform.lower() == "win32" or os.name.lower() == "nt":
-    from asyncio import WindowsSelectorEventLoopPolicy, set_event_loop_policy
+    from asyncio import (  # type: ignore[attr-defined]
+        WindowsSelectorEventLoopPolicy,
+        set_event_loop_policy,
+    )
+
     set_event_loop_policy(WindowsSelectorEventLoopPolicy())
 
 asyncio.run(main())

qolsys_controller-0.0.76/example.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+
+import asyncio
+import logging
+import os
+import sys
+
+from qolsys_controller.controller import QolsysController
+from qolsys_controller.errors import QolsysMqttError, QolsysSqlError, QolsysSslError
+
+logging.basicConfig(level=logging.DEBUG, format="%(levelname)s - %(module)s: %(message)s")
+LOGGER = logging.getLogger(__name__)
+
+
+async def main() -> None:  # noqa: D103
+    remote = QolsysController()
+    remote.settings.config_directory = "./config/"
+    remote.settings.panel_ip = "****"
+    remote.settings.plugin_ip = "****"
+    remote.settings.random_mac = ""  # Example: F2:16:3E:33:ED:20
+
+    # Additionnal remote plugin config
+    remote.settings.check_user_code_on_disarm = False  # Check user code in user.conf file
+    remote.settings.log_mqtt_mesages = False  # Enable for MQTT debug purposes
+    remote.settings.auto_discover_pki = True
+
+    # Configure remote plugin
+    if not await remote.config(start_pairing=True):
+        LOGGER.debug("Error Configuring remote plugin")
+        return
+
+    try:
+        await remote.start_operation()
+
+    except QolsysMqttError:
+        LOGGER.debug("QolsysMqttError")
+
+    except QolsysSslError:
+        LOGGER.debug("QolsysSslError")
+
+    except QolsysSqlError:
+        LOGGER.debug("QolsysSqlError")
+
+    if not remote.connected:
+        LOGGER.error("Panel not ready for operation")
+        return
+
+    LOGGER.debug("Qolsys Panel Ready for operation")
+
+    await asyncio.sleep(5)
+    # await remote.command_zwave_switch_multi_level(node_id="6",level=99)
+    # await remote.command_zwave_switch_binary_set(node_id="8", status=True)
+    # await remote.plugin.command_arm(
+    #   partition_id='0',
+    #   arming_type=PartitionArmingType:ARM_NIGHT,
+    #   user_code="1111",
+    #   exit_sounds=False,
+    #   instant_arm=True)
+    # await remote.command_disarm(partition_id="0", user_code="1111")
+    # await remote.command_panel_execute_scene(scene_id="3")
+    # await remote.command_zwave_doorlock_set(node_id="7",locked=True)
+    # await remote.stop_operation()
+
+    # Use an asyncio.Event to keep the program running efficiently
+    stop_event = asyncio.Event()
+    await stop_event.wait()
+
+
+# Change to the "Selector" event loop if platform is Windows
+if sys.platform.lower() == "win32" or os.name.lower() == "nt":
+    from asyncio import (  # type: ignore[attr-defined]
+        WindowsSelectorEventLoopPolicy,
+        set_event_loop_policy,
+    )
+
+    set_event_loop_policy(WindowsSelectorEventLoopPolicy())
+
+asyncio.run(main())

qolsys_controller-0.0.76/mypy.ini

@@ -0,0 +1,6 @@
+[mypy]
+python_version = 3.12
+warn_unused_configs = True
+disallow_untyped_defs = True
+ignore_missing_imports = True
+strict = True

{qolsys_controller-0.0.12 → qolsys_controller-0.0.76}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qolsys-controller"
-version = "0.0.12"
+version = "0.0.76"
 authors = [
   { name="Eric Hylands", email="" },
 ]
@@ -27,9 +27,13 @@ build-backend = "hatchling.build"
 packages = ["qolsys_controller/"]
 
 [tool.ruff]
-line-length = 88
+line-length = 127
+target-version = "py312"
+
 
 [tool.ruff.lint]
-select = ['ALL']
-ignore = ["E501","S608","S311","S104","D100","D101", "D102","D107","ERA001", "FBT001","FBT002", "N802","N806","PERF401"]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]
 
+[tool.ruff.lint.mccabe]
+max-complexity = 25

qolsys_controller-0.0.76/qolsys_controller/adc_device.py

@@ -0,0 +1,202 @@
+import json
+import logging
+from typing import TYPE_CHECKING
+
+from .adc_service import QolsysAdcService
+from .adc_service_garagedoor import QolsysAdcGarageDoorService
+from .enum_adc import vdFuncLocalControl, vdFuncName, vdFuncState, vdFuncType
+from .observable import QolsysObservable
+
+if TYPE_CHECKING:
+    from .adc_service import QolsysAdcService
+
+LOGGER = logging.getLogger(__name__)
+
+
+class QolsysAdcDevice(QolsysObservable):
+    def __init__(self, adc_dict: dict[str, str]) -> None:
+        super().__init__()
+
+        self._services: list[QolsysAdcService] = []
+
+        self._id: str = adc_dict.get("_id", "")
+        self._partition_id: str = adc_dict.get("partition_id", "")
+        self._device_id: str = adc_dict.get("device_id", "")
+        self._name: str = adc_dict.get("name", "")
+        self._type: str = adc_dict.get("type", "")
+        self._create_time: str = adc_dict.get("create_time", "")
+        self._created_by: str = adc_dict.get("created_by", "")
+        self._update_time: str = adc_dict.get("update_time", "")
+        self._updated_by: str = adc_dict.get("updated_by", "")
+        self._device_zone_list: str = adc_dict.get("device_zone_list", "")
+        self._func_list = ""
+        self.func_list = adc_dict.get("func_list", "")
+
+    def update_adc_device(self, data: dict[str, str]) -> None:
+        # Check if we are updating same device_id
+        device_id_update = data.get("device_id", "")
+        if device_id_update != self._device_id:
+            LOGGER.error(
+                "Updating ADC%s (%s) with ADC%s (different device_id)",
+                self._device_id,
+                self._name,
+                device_id_update,
+            )
+            return
+
+        self.start_batch_update()
+
+        if "partition_id" in data:
+            self.partition_id = data.get("partition_id", "")
+
+        if "name" in data:
+            self.name = data.get("name", "")
+
+        if "type" in data:
+            self.type = data.get("type", "")
+
+        self.end_batch_update()
+
+        if "func_list" in data:
+            self.func_list = data.get("func_list", "")
+
+    def get_adc_service(self, id: int) -> QolsysAdcService | None:
+        for service in self._services:
+            if service.id == id:
+                return service
+        return None
+
+    def add_adc_service(
+        self,
+        id: int,
+        local_control: vdFuncLocalControl,
+        func_name: vdFuncName,
+        func_type: vdFuncType,
+        func_state: vdFuncState,
+        timestamp: str,
+    ) -> None:
+        # Garage Door
+        if func_name == vdFuncName.OPEN_CLOSE and func_type == vdFuncType.BINARY_ACTUATOR:
+            LOGGER.debug("ADC%s (%s) - Adding garage door service", self.device_id, self.name)
+            self._services.append(
+                QolsysAdcGarageDoorService(self, id, func_name, local_control, func_type, func_state, timestamp)
+            )
+            self.notify()
+            return
+
+        # Add generic service if other services have beed identified
+        LOGGER.debug("ADC%s (%s) - Adding generic service", self.device_id, self.name)
+        self._services.append(QolsysAdcService(self, id, func_name, local_control, func_type, func_state, timestamp))
+        self.notify()
+        return
+
+    # -----------------------------
+    # properties + setters
+    # -----------------------------
+
+    @property
+    def device_id(self) -> str:
+        return self._device_id
+
+    @device_id.setter
+    def device_id(self, value: str) -> None:
+        self._device_id = value
+
+    @property
+    def services(self) -> list[QolsysAdcService]:
+        return self._services
+
+    @property
+    def partition_id(self) -> str:
+        return self._partition_id
+
+    @partition_id.setter
+    def partition_id(self, value: str) -> None:
+        if self._partition_id != value:
+            LOGGER.debug("ADC%s (%s) - partition_id: %s", self.device_id, self.name, value)
+            self._partition_id = value
+            self.notify()
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        if self._name != value:
+            LOGGER.debug("ADC%s (%s) - name: %s", self.device_id, self.name, value)
+            self._name = value
+            self.notify()
+
+    @property
+    def type(self) -> str:
+        return self._type
+
+    @type.setter
+    def type(self, value: str) -> None:
+        if self._type != value:
+            LOGGER.debug("ADC%s (%s) - type: %s", self.device_id, self.name, value)
+            self._type = value
+            self.notify()
+
+    @property
+    def func_list(self) -> str:
+        return self._func_list
+
+    @func_list.setter
+    def func_list(self, value: str) -> None:
+        if self._func_list != value:
+            LOGGER.debug("ADC%s (%s) - func_list: %s", self.device_id, self.name, value)
+            self._func_list = value
+
+            try:
+                json_func_list = json.loads(self._func_list)
+                new_service_id: list[int] = []
+                self.start_batch_update()
+
+                for function in json_func_list:
+                    try:
+                        id = function.get("vdFuncId")
+                        local_control = vdFuncLocalControl(function.get("vdFuncLocalControl"))
+                        func_name = vdFuncName(function.get("vdFuncName"))
+                        func_type = vdFuncType(function.get("vdFuncType"))
+                        func_state = vdFuncState(function.get("vdFuncState"))
+                        timestamp = function.get("vdFuncBackendTimestamp")
+                        new_service_id.append(id)
+
+                        service = self.get_adc_service(id)
+                        if service is not None:
+                            service.update_adc_service(func_name, local_control, func_type, func_state, timestamp)
+
+                        if service is None:
+                            self.add_adc_service(id, local_control, func_name, func_type, func_state, timestamp)
+
+                    except ValueError as e:
+                        LOGGER.error("Error converting value:", e)
+                        continue
+
+                # Check if service have been removed
+                for service in self._services:
+                    if service.id not in new_service_id:
+                        self._services.remove(service)
+                        self.notify()
+
+                self.end_batch_update()
+
+            except json.JSONDecodeError as e:
+                LOGGER.error("ADC%s - Error parsing JSON:", self.device_id, e)
+
+    def to_dict_adc(self) -> dict[str, str]:
+        return {
+            "_id": self._id,
+            "partition_id": self.partition_id,
+            "device_id": self.device_id,
+            "name": self.name,
+            "type": self.type,
+            "func_list": self.func_list,
+            "create_time": self._create_time,
+            "created_by": self._created_by,
+            "update_time": self._update_time,
+            "updated_by": self._updated_by,
+            "device_zone_list": self._device_zone_list,
+        }