qbusmqttapi 0.2.7__tar.gz

qbusmqttapi-0.2.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Qbus
+
+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.

qbusmqttapi-0.2.7/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.1
+Name: qbusmqttapi
+Version: 0.2.7
+Summary: MQTT API for Qbus Home Automation.
+Home-page: https://github.com/Qbus-iot/qbusmqttapi
+Author: Koen Schockaert
+Author-email: ks@qbus.be
+License: MIT License 2024
+Project-URL: Source Code, https://github.com/Qbus-iot/qbusmqttapi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# qbusmqttapi
+Python MQTT API for Qbus Home Automation

qbusmqttapi-0.2.7/README.md

@@ -0,0 +1,2 @@
+# qbusmqttapi
+Python MQTT API for Qbus Home Automation

qbusmqttapi-0.2.7/pyproject.toml

@@ -0,0 +1,26 @@
+[tool.ruff]
+exclude = [".git", ".vscode", ".pytest_cache", ".mypy_cache", ".env"]
+line-length = 125
+
+[tool.ruff.lint]
+ignore = ["B008", "ISC001", "E501", "W191"]
+select = [
+    "B",
+    "E",
+    "F",
+    "W",
+    "I",
+    "N",
+    "C4",
+    "EXE",
+    "ISC",
+    "ICN",
+    "PIE",
+    "PT",
+    "RET",
+    "SIM",
+    "ERA",
+    "PLC",
+    "RUF",
+    "ARG",
+]

qbusmqttapi-0.2.7/setup.cfg

@@ -0,0 +1,7 @@
+[metadata]
+license_files = LICENSE
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

qbusmqttapi-0.2.7/setup.py

@@ -0,0 +1,27 @@
+from pathlib import Path
+
+import setuptools
+
+VERSION = "0.2.7"  # PEP-440
+
+setuptools.setup(
+    name="qbusmqttapi",
+    version=VERSION,
+    description="MQTT API for Qbus Home Automation.",
+    url="https://github.com/Qbus-iot/qbusmqttapi",
+    project_urls={
+        "Source Code": "https://github.com/Qbus-iot/qbusmqttapi",
+    },
+    author="Koen Schockaert",
+    author_email="ks@qbus.be",
+    license="MIT License 2024",
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Environment :: Console",
+        "Programming Language :: Python :: 3.10",
+    ],
+    python_requires=">=3.8",
+    # Requirements
+    long_description=Path("README.md").read_text(),
+    long_description_content_type="text/markdown",
+)

qbusmqttapi-0.2.7/src/qbusmqttapi/__init__.py

@@ -0,0 +1 @@
+"""QBUS MQTT API."""

qbusmqttapi-0.2.7/src/qbusmqttapi/const.py

@@ -0,0 +1,14 @@
+"""Qbus MQTT API constants."""
+
+TOPIC_PREFIX = "cloudapp/QBUSMQTTGW"
+
+KEY_OUTPUT_ACTION = "action"
+KEY_OUTPUT_ACTIONS = "actions"
+KEY_OUTPUT_ID = "id"
+KEY_OUTPUT_NAME = "name"
+KEY_OUTPUT_PROPERTIES = "properties"
+KEY_OUTPUT_REF_ID = "refId"
+KEY_OUTPUT_TYPE = "type"
+
+KEY_PROPERTIES_AUTHKEY = "authKey"
+KEY_PROPERTIES_VALUE = "value"

qbusmqttapi-0.2.7/src/qbusmqttapi/discovery.py

@@ -0,0 +1,160 @@
+"""Qbis discovery models."""
+
+from __future__ import annotations
+
+from .const import (
+    KEY_OUTPUT_ACTIONS,
+    KEY_OUTPUT_ID,
+    KEY_OUTPUT_NAME,
+    KEY_OUTPUT_PROPERTIES,
+    KEY_OUTPUT_REF_ID,
+    KEY_OUTPUT_TYPE,
+)
+
+
+KEY_DEVICES = "devices"
+
+KEY_DEVICE_FUNCTIONBLOCKS = "functionBlocks"
+KEY_DEVICE_ID = "id"
+KEY_DEVICE_IP = "ip"
+KEY_DEVICE_MAC = "mac"
+KEY_DEVICE_NAME = "name"
+KEY_DEVICE_SERIAL_NR = "serialNr"
+KEY_DEVICE_TYPE = "type"
+KEY_DEVICE_VERSION = "version"
+
+
+class QbusMqttOutput:
+    """MQTT representation of a Qbus output."""
+
+    def __init__(self, data: dict, device: QbusMqttDevice) -> None:
+        """Initialize based on a json loaded dictionary."""
+        self._data = data
+        self._device = device
+
+    @property
+    def id(self) -> str:
+        """Return the id."""
+        return self._data.get(KEY_OUTPUT_ID) or ""
+
+    @property
+    def type(self) -> str:
+        """Return the type."""
+        return self._data.get(KEY_OUTPUT_TYPE) or ""
+
+    @property
+    def name(self) -> str:
+        """Return the name."""
+        return self._data.get(KEY_OUTPUT_NAME) or ""
+
+    @property
+    def ref_id(self) -> str:
+        """Return the ref id."""
+        return self._data.get(KEY_OUTPUT_REF_ID) or ""
+
+    @property
+    def properties(self) -> dict:
+        """Return the properties."""
+        return self._data.get(KEY_OUTPUT_PROPERTIES) or {}
+
+    @property
+    def actions(self) -> dict:
+        """Return the actions."""
+        return self._data.get(KEY_OUTPUT_ACTIONS) or {}
+
+    @property
+    def device(self) -> QbusMqttDevice:
+        """Return the device."""
+        return self._device
+
+
+class QbusMqttDevice:
+    """MQTT representation of a Qbus device."""
+
+    def __init__(self, data: dict) -> None:
+        """Initialize based on a json loaded dictionary."""
+        self._data = data
+
+    @property
+    def id(self) -> str:
+        """Return the id."""
+        return self._data.get(KEY_DEVICE_ID) or ""
+
+    @property
+    def ip(self) -> str:
+        """Return the ip address."""
+        return self._data.get(KEY_DEVICE_IP) or ""
+
+    @property
+    def mac(self) -> str:
+        """Return the ip address."""
+        return self._data.get(KEY_DEVICE_MAC) or ""
+
+    @property
+    def name(self) -> str:
+        """Return the ip address."""
+        return self._data.get(KEY_DEVICE_NAME) or ""
+
+    @property
+    def serial_number(self) -> str:
+        """Return the serial number."""
+        return self._data.get(KEY_DEVICE_SERIAL_NR) or ""
+
+    @property
+    def type(self) -> str:
+        """Return the mac address."""
+        return self._data.get(KEY_DEVICE_TYPE) or ""
+
+    @property
+    def version(self) -> str:
+        """Return the version."""
+        return self._data.get(KEY_DEVICE_VERSION) or ""
+
+    @property
+    def outputs(self) -> list[QbusMqttOutput]:
+        """Return the outputs."""
+
+        outputs: list[QbusMqttOutput] = []
+
+        if self._data.get(KEY_DEVICE_FUNCTIONBLOCKS):
+            outputs = [
+                QbusMqttOutput(x, self) for x in self._data[KEY_DEVICE_FUNCTIONBLOCKS]
+            ]
+
+        return outputs
+
+
+class QbusDiscovery:
+    """MQTT representation of a Qbus config."""
+
+    def __init__(self, data: dict) -> None:
+        """Initialize based on a json loaded dictionary."""
+        if KEY_DEVICES in data:
+            self._devices = [QbusMqttDevice(x) for x in data[KEY_DEVICES]]
+
+        self._name = data["app"]
+
+    def get_device_by_id(self, id: str) -> QbusMqttDevice | None:
+        """Get the device by id."""
+        return next((x for x in self.devices if x.id.casefold() == id.casefold()), None)
+
+    def get_device_by_serial(self, serial: str) -> QbusMqttDevice | None:
+        """Get the device by serial."""
+        return next(
+            (
+                x
+                for x in self.devices
+                if x.serial_number.casefold() == serial.casefold()
+            ),
+            None,
+        )
+
+    @property
+    def devices(self) -> list[QbusMqttDevice]:
+        """Return the devices."""
+        return self._devices
+
+    @property
+    def name(self):
+        """Return device name."""
+        return self._name

qbusmqttapi-0.2.7/src/qbusmqttapi/factory.py

@@ -0,0 +1,172 @@
+"""Qbus MQTT factory."""
+
+from dataclasses import dataclass
+import json
+import logging
+from typing import Any, TypeVar
+
+from .const import (
+    KEY_PROPERTIES_AUTHKEY,
+    TOPIC_PREFIX,
+)
+from .discovery import QbusDiscovery, QbusMqttDevice
+from .state import (
+    QbusMqttControllerState,
+    QbusMqttState,
+    StateAction,
+    StateType,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class QbusMqttRequestMessage:
+    """Qbus MQTT request data class."""
+
+    topic: str
+    payload: str | bytes
+
+
+class QbusMqttMessageFactory:
+    """Factory methods for Qbus MQTT messages."""
+
+    T = TypeVar("T", bound="QbusMqttState")
+
+    def __init__(self) -> None:
+        self._topic_factory = QbusMqttTopicFactory()
+
+    def parse_discovery(self, payload: str | bytes) -> QbusDiscovery | None:
+        """Parse an MQTT message and return an instance
+        of QbusDiscovery if successful, otherwise None."""
+
+        discovery: QbusDiscovery | None = self.deserialize(QbusDiscovery, payload)
+
+        # Discovery data must include the Qbus device type and name.
+        if discovery is not None and len(discovery.devices) == 0:
+            _LOGGER.error("Incomplete discovery payload: %s", payload)
+            return None
+
+        return discovery
+
+    def parse_controller_state(
+        self, payload: str | bytes
+    ) -> QbusMqttControllerState | None:
+        """Parse an MQTT message and return an instance
+        of QbusMqttControllerState if successful, otherwise None."""
+
+        return self.deserialize(QbusMqttControllerState, payload)
+
+    def parse_output_state(self, cls: type[T], payload: str | bytes) -> T | None:
+        """Parse an MQTT message and return an instance
+        of T if successful, otherwise None."""
+
+        return self.deserialize(cls, payload)
+
+    def create_device_activate_request(
+        self, device: QbusMqttDevice, prefix: str = TOPIC_PREFIX
+    ) -> QbusMqttRequestMessage:
+        """Create a message to request device activation."""
+        state = QbusMqttState(
+            id=device.id, type=StateType.ACTION, action=StateAction.ACTIVATE
+        )
+        state.write_property(KEY_PROPERTIES_AUTHKEY, "ubielite")
+
+        return QbusMqttRequestMessage(
+            self._topic_factory.get_device_command_topic(device.id, prefix),
+            self.serialize(state),
+        )
+
+    def create_device_state_request(
+        self, device: QbusMqttDevice, prefix: str = TOPIC_PREFIX
+    ) -> QbusMqttRequestMessage:
+        """Create a message to request a device state."""
+        return QbusMqttRequestMessage(
+            self._topic_factory.get_get_state_topic(prefix), json.dumps([device.id])
+        )
+
+    def create_state_request(
+        self, entity_ids: list[str], prefix: str = TOPIC_PREFIX
+    ) -> QbusMqttRequestMessage:
+        """Create a message to request entity states."""
+        return QbusMqttRequestMessage(
+            self._topic_factory.get_get_state_topic(prefix), json.dumps(entity_ids)
+        )
+
+    def create_set_output_state_request(
+        self, device: QbusMqttDevice, state: QbusMqttState, prefix: str = TOPIC_PREFIX
+    ) -> QbusMqttRequestMessage:
+        """Create a message to update the output state."""
+        return QbusMqttRequestMessage(
+            self._topic_factory.get_output_command_topic(device.id, state.id, prefix),
+            self.serialize(state),
+        )
+
+    def serialize(self, obj: Any) -> str:
+        """Convert an object to json payload."""
+        return json.dumps(obj, cls=IgnoreNoneJsonEncoder)
+
+    def deserialize(self, state_cls: type[Any], payload: str | bytes) -> Any | None:
+        """Parse an MQTT message and return the requested type if successful, otherwise None."""
+
+        if payload is None:
+            _LOGGER.warning("Empty state payload for %s", state_cls.__name__)
+            return None
+
+        try:
+            data = json.loads(payload)
+        except ValueError:
+            _LOGGER.error(
+                "Invalid state payload for %s: %s", state_cls.__name__, payload
+            )
+            return None
+
+        return state_cls(data)
+
+
+class QbusMqttTopicFactory:
+    """Factory methods for topics of the Qbus MQTT API."""
+
+    def get_get_config_topic(self, prefix: str = TOPIC_PREFIX) -> str:
+        """Return the getConfig topic."""
+        return f"{prefix}/getConfig"
+
+    def get_config_topic(self, prefix: str = TOPIC_PREFIX) -> str:
+        """Return the config topic."""
+        return f"{prefix}/config"
+
+    def get_get_state_topic(self, prefix: str = TOPIC_PREFIX) -> str:
+        """Return the getState topic."""
+        return f"{prefix}/getState"
+
+    def get_device_state_topic(self, device_id: str, prefix: str = TOPIC_PREFIX) -> str:
+        """Return the state topic."""
+        return f"{prefix}/{device_id}/state"
+
+    def get_device_command_topic(
+        self, device_id: str, prefix: str = TOPIC_PREFIX
+    ) -> str:
+        """Return the 'set state' topic."""
+        return f"{prefix}/{device_id}/setState"
+
+    def get_output_command_topic(
+        self, device_id: str, entity_id: str, prefix: str = TOPIC_PREFIX
+    ) -> str:
+        """Return the 'set state' topic of an output."""
+        return f"{prefix}/{device_id}/{entity_id}/setState"
+
+    def get_output_state_topic(
+        self, device_id: str, entity_id: str, prefix: str = TOPIC_PREFIX
+    ) -> str:
+        """Return the state topic of an output."""
+        return f"{prefix}/{device_id}/{entity_id}/state"
+
+
+class IgnoreNoneJsonEncoder(json.JSONEncoder):
+    """A json encoder to ignore None values when serializing."""
+
+    def default(self, o):
+        if hasattr(o, "__dict__"):
+            # Filter out None values
+            return {k: v for k, v in o.__dict__.items() if v is not None}
+        return super().default(o)

qbusmqttapi-0.2.7/src/qbusmqttapi/state.py

@@ -0,0 +1,140 @@
+"""Qbus state models."""
+
+from enum import StrEnum
+from typing import Any
+from .const import (
+    KEY_OUTPUT_ACTION,
+    KEY_OUTPUT_ID,
+    KEY_OUTPUT_PROPERTIES,
+    KEY_OUTPUT_TYPE,
+    KEY_PROPERTIES_VALUE,
+)
+
+KEY_CONTROLLER_CONNECTABLE = "connectable"
+KEY_CONTROLLER_CONNECTED = "connected"
+KEY_CONTROLLER_ID = "id"
+KEY_CONTROLLER_STATE_PROPERTIES = "properties"
+
+
+class StateType(StrEnum):
+    """Values to be used as state type."""
+
+    ACTION = "action"
+    STATE = "state"
+
+
+class StateAction(StrEnum):
+    """Values to be used as state action."""
+
+    ACTIVATE = "activate"
+    ACTIVE = "active"
+
+
+class QbusMqttControllerStateProperties:
+    """MQTT representation a Qbus controller its state properties."""
+
+    def __init__(self, data: dict) -> None:
+        """Initialize based on a json loaded dictionary."""
+        self.connectable: bool | None = data.get(KEY_CONTROLLER_CONNECTABLE)
+        self.connected: bool | None = data.get(KEY_CONTROLLER_CONNECTED)
+
+
+class QbusMqttControllerState:
+    """MQTT representation of a Qbus controller state."""
+
+    def __init__(self, data: dict) -> None:
+        """Initialize based on a json loaded dictionary."""
+        self.id: str | None = data.get(KEY_CONTROLLER_ID)
+
+        properties = data.get(KEY_CONTROLLER_STATE_PROPERTIES)
+        self.properties: QbusMqttControllerStateProperties | None = (
+            QbusMqttControllerStateProperties(properties)
+            if properties is not None
+            else None
+        )
+
+
+class QbusMqttState:
+    """MQTT representation of a Qbus state."""
+
+    def __init__(
+        self,
+        data: dict | None = None,
+        *,
+        id: str | None = None,
+        type: str | None = None,
+        action: str | None = None,
+    ) -> None:
+        """Initialize state."""
+        self.id: str = ""
+        self.type: str = ""
+        self.action: str | None = None
+        self.properties: dict | None = None
+
+        if data is not None:
+            self.id = data.get(KEY_OUTPUT_ID, "")
+            self.type = data.get(KEY_OUTPUT_TYPE, "")
+            self.action = data.get(KEY_OUTPUT_ACTION)
+            self.properties = data.get(KEY_OUTPUT_PROPERTIES)
+
+        if id is not None:
+            self.id = id
+
+        if type is not None:
+            self.type = type
+
+        if action is not None:
+            self.action = action
+
+    def read_property(self, key: str, default: Any) -> Any:
+        """Read a property."""
+        return self.properties.get(key, default) if self.properties else default
+
+    def write_property(self, key: str, value: Any) -> None:
+        """Add or update a property."""
+        if self.properties is None:
+            self.properties = {}
+
+        self.properties[key] = value
+
+
+class QbusMqttOnOffState(QbusMqttState):
+    """MQTT representation of a Qbus on/off output."""
+
+    def __init__(
+        self,
+        data: dict | None = None,
+        *,
+        id: str | None = None,
+        type: str | None = None,
+    ) -> None:
+        super().__init__(data, id=id, type=type)
+
+    def read_value(self) -> bool:
+        """Read the value of the Qbus output."""
+        return self.read_property(KEY_PROPERTIES_VALUE, False)
+
+    def write_value(self, value: bool) -> None:
+        """Set the value of the Qbus output."""
+        self.write_property(KEY_PROPERTIES_VALUE, value)
+
+
+class QbusMqttAnalogState(QbusMqttState):
+    """MQTT representation of a Qbus analog output."""
+
+    def __init__(
+        self,
+        data: dict | None = None,
+        *,
+        id: str | None = None,
+        type: str | None = None,
+    ) -> None:
+        super().__init__(data, id=id, type=type)
+
+    def read_percentage(self) -> float:
+        """Read the value of the Qbus output."""
+        return self.read_property(KEY_PROPERTIES_VALUE, 0)
+
+    def write_percentage(self, percentage: float) -> None:
+        """Set the value of the Qbus output."""
+        self.write_property(KEY_PROPERTIES_VALUE, percentage)

qbusmqttapi-0.2.7/src/qbusmqttapi.egg-info/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.1
+Name: qbusmqttapi
+Version: 0.2.7
+Summary: MQTT API for Qbus Home Automation.
+Home-page: https://github.com/Qbus-iot/qbusmqttapi
+Author: Koen Schockaert
+Author-email: ks@qbus.be
+License: MIT License 2024
+Project-URL: Source Code, https://github.com/Qbus-iot/qbusmqttapi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# qbusmqttapi
+Python MQTT API for Qbus Home Automation

qbusmqttapi-0.2.7/src/qbusmqttapi.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+setup.cfg
+setup.py
+src/qbusmqttapi/__init__.py
+src/qbusmqttapi/const.py
+src/qbusmqttapi/discovery.py
+src/qbusmqttapi/factory.py
+src/qbusmqttapi/state.py
+src/qbusmqttapi.egg-info/PKG-INFO
+src/qbusmqttapi.egg-info/SOURCES.txt
+src/qbusmqttapi.egg-info/dependency_links.txt
+src/qbusmqttapi.egg-info/top_level.txt

qbusmqttapi-0.2.7/src/qbusmqttapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qbusmqttapi-0.2.7/src/qbusmqttapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+qbusmqttapi