python-pooldose 0.3.1__py3-none-any.whl

pooldose/__init__.py

@@ -0,0 +1,4 @@
+"""Async API client for SEKO Pooldose."""
+from .client import PooldoseClient
+
+__all__ = ["PooldoseClient"]

pooldose/client.py

@@ -0,0 +1,228 @@
+"""Client for async API client for SEKO Pooldose."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Optional
+from pooldose.values.instant_values import InstantValues
+from pooldose.request_handler import RequestHandler, RequestStatus
+from pooldose.values.static_values import StaticValues
+from pooldose.mappings.mapping_info import (
+    MappingInfo,
+    SensorMapping,
+    BinarySensorMapping,
+    NumberMapping,
+    SwitchMapping,
+    SelectMapping,
+)
+
+# pylint: disable=line-too-long
+
+_LOGGER = logging.getLogger(__name__)
+
+class PooldoseClient:
+    """
+    Async client for SEKO Pooldose API.
+    All getter methods return (status, data) and log errors.
+    """
+
+    def __init__(self, host: str, timeout: int = 10) -> None:
+        """
+        Initialize the Pooldose client.
+
+        Args:
+            host (str): The host address of the Pooldose device.
+            timeout (int): Timeout for API requests in seconds.
+        """
+        self._host = host
+        self._timeout = timeout
+        self._last_data = None
+        self._request_handler = None
+
+        # Initialize device info with default or placeholder values
+        self.device_info = {
+            "NAME": None,           # Device name
+            "SERIAL_NUMBER": None,  # Serial number
+            "DEVICE_ID": "01220000095B_DEVICE",      # Device ID, i.e., SERIAL_NUMBER + "_DEVICE"
+            "MODEL": None,          # Device model
+            "MODEL_ID": "PDPR1H1HAW100",       # Model ID
+            "OWNERID": None,        # Owner ID
+            "GROUPNAME": None,      # Group name
+            "FW_VERSION": None,     # Firmware version
+            "SW_VERSION": None,     # Software version
+            "API_VERSION": None,    # API version
+            "FW_CODE": "539187",        # Firmware code
+            "MAC": None,            # MAC address
+            "IP": None,             # IP address
+            "WIFI_SSID": None,      # WiFi SSID
+            "WIFI_KEY": None,       # WiFi key
+            "AP_SSID": None,        # Access Point SSID
+            "AP_KEY": None,         # Access Point key
+        }
+
+        # Mapping-Status und Mapping-Cache
+        self._mapping_status = None
+        self._mapping_info: Optional[MappingInfo] = None
+
+    @classmethod
+    async def create(cls, host: str, timeout: int = 10, include_sensitive_data: bool = False) -> tuple[RequestStatus, "PooldoseClient" | None]:
+        """
+        Asynchronous factory method to initialize the Pooldose client.
+
+        Args:
+            host (str): The host address of the Pooldose device.
+            timeout (int): Timeout for API requests in seconds.
+            include_sensitive_data (bool): If True, fetch WiFi and AP keys.
+
+        Returns:
+            tuple: (RequestStatus, PooldoseClient|None) - Status and client instance.
+        """
+        self = cls(host, timeout)
+        status, handler = await RequestHandler.create(host, timeout)
+        if status != RequestStatus.SUCCESS:
+            _LOGGER.error("Failed to create RequestHandler: %s", status)
+            return status, None
+        self._request_handler = handler
+
+        # Fetch core parameters and device info
+        self.device_info["API_VERSION"] = self._request_handler.api_version
+
+        status, debug_config = await self._request_handler.get_debug_config()
+        if status != RequestStatus.SUCCESS or not debug_config:
+            _LOGGER.error("Failed to fetch debug config: %s", status)
+            return status, None
+        if (gateway := debug_config.get("GATEWAY")) is not None:
+            self.device_info["SERIAL_NUMBER"] = gateway.get("DID")
+            self.device_info["NAME"] = gateway.get("NAME")
+            self.device_info["SW_VERSION"] = gateway.get("FW_REL")
+        if (device := debug_config.get("DEVICES")[0]) is not None:
+            self.device_info["DEVICE_ID"] = device.get("DID")
+            self.device_info["MODEL"] = device.get("NAME")
+            self.device_info["MODEL_ID"] = device.get("PRODUCT_CODE")
+            self.device_info["FW_VERSION"] = device.get("FW_REL")
+            self.device_info["FW_CODE"] = device.get("FW_CODE")
+        await asyncio.sleep(0.5)
+
+        # Mapping laden, sobald MODEL_ID und FW_CODE verfügbar sind (asynchron!)
+        self._mapping_info = await MappingInfo.load(
+            self.device_info.get("MODEL_ID"),
+            self.device_info.get("FW_CODE")
+        )
+
+        # WiFi station info
+        status, wifi_station = await self._request_handler.get_wifi_station()
+        if status != RequestStatus.SUCCESS or not wifi_station:
+            _LOGGER.warning("Failed to fetch WiFi station info: %s", status)
+        else:
+            self.device_info["WIFI_SSID"] = wifi_station.get("SSID")
+            self.device_info["MAC"] = wifi_station.get("MAC")
+            self.device_info["IP"] = wifi_station.get("IP")
+            # Only include WiFi key if explicitly requested
+            if include_sensitive_data:
+                self.device_info["WIFI_KEY"] = wifi_station.get("KEY")
+        await asyncio.sleep(0.5)
+
+        # Access point info
+        status, access_point = await self._request_handler.get_access_point()
+        if status != RequestStatus.SUCCESS or not access_point:
+            _LOGGER.warning("Failed to fetch access point info: %s", status)
+        else:
+            self.device_info["AP_SSID"] = access_point.get("SSID")
+            # Only include AP key if explicitly requested
+            if include_sensitive_data:
+                self.device_info["AP_KEY"] = access_point.get("KEY")
+        await asyncio.sleep(0.5)
+
+        # Network info
+        status, network_info = await self._request_handler.get_network_info()
+        if status != RequestStatus.SUCCESS or not network_info:
+            _LOGGER.error("Failed to fetch network info: %s", status)
+            return status, None
+        self.device_info["OWNERID"] = network_info.get("OWNERID")
+        self.device_info["GROUPNAME"] = network_info.get("GROUPNAME")
+
+        if not include_sensitive_data:
+            _LOGGER.info("Excluded WiFi and AP keys (use include_sensitive_data=True to include)")
+
+        _LOGGER.debug("Initialized Pooldose client with device info: %s", self.device_info)
+        return RequestStatus.SUCCESS, self
+
+    def static_values(self) -> tuple[RequestStatus, StaticValues | None]:
+        """
+        Get the static device values as a StaticValues object.
+
+        Returns:
+            tuple: (RequestStatus, StaticValues|None) - Status and static values object.
+        """
+        try:
+            return RequestStatus.SUCCESS, StaticValues(self.device_info)
+        except (ValueError, TypeError, KeyError) as err:
+            _LOGGER.warning("Error creating StaticValues: %s", err)
+            return RequestStatus.UNKNOWN_ERROR, None
+
+    def available_types(self) -> dict[str, list[str]]:
+        """
+        Returns a dictionary mapping type categories to lists of available type names.
+
+        Returns:
+            dict[str, list[str]]: A dictionary where each key is a type category (as a string),
+            and each value is a list of available type names (as strings). If no mapping information
+            is available, returns an empty dictionary.
+        """
+        return self._mapping_info.available_types() if self._mapping_info else {}
+
+    def available_sensors(self) -> dict[str, SensorMapping]:
+        """
+        Returns all available sensors from the mapping as SensorMapping objects.
+        """
+        return self._mapping_info.available_sensors() if self._mapping_info else {}
+
+    def available_binary_sensors(self) -> dict[str, BinarySensorMapping]:
+        """
+        Returns all available binary sensors from the mapping as BinarySensorMapping objects.
+        """
+        return self._mapping_info.available_binary_sensors() if self._mapping_info else {}
+
+    def available_numbers(self) -> dict[str, NumberMapping]:
+        """
+        Returns all available numbers from the mapping as NumberMapping objects.
+        """
+        return self._mapping_info.available_numbers() if self._mapping_info else {}
+
+    def available_switches(self) -> dict[str, SwitchMapping]:
+        """
+        Returns all available switches from the mapping as SwitchMapping objects.
+        """
+        return self._mapping_info.available_switches() if self._mapping_info else {}
+
+    def available_selects(self) -> dict[str, SelectMapping]:
+        """
+        Returns all available selects from the mapping as SelectMapping objects.
+        """
+        return self._mapping_info.available_selects() if self._mapping_info else {}
+
+    async def instant_values(self) -> tuple[RequestStatus, InstantValues | None]:
+        """
+        Fetch the current instant values from the Pooldose device.
+
+        Returns:
+            tuple: (RequestStatus, InstantValues|None) - Status and instant values object.
+        """
+        try:
+            status, raw_data = await self._request_handler.get_values_raw()
+            if status != RequestStatus.SUCCESS or raw_data is None:
+                return status, None
+            # Mapping aus Cache verwenden
+            mapping = self._mapping_info.mapping if self._mapping_info else None
+            if mapping is None:
+                return RequestStatus.UNKNOWN_ERROR, None
+            device_id = self.device_info["DEVICE_ID"]
+            device_raw_data = raw_data.get("devicedata", {}).get(device_id, {})
+            model_id = self.device_info["MODEL_ID"]
+            fw_code = self.device_info["FW_CODE"]
+            prefix = f"{model_id}_FW{fw_code}_"
+            return RequestStatus.SUCCESS, InstantValues(device_raw_data, mapping, prefix, device_id, self._request_handler)
+        except (KeyError, TypeError, ValueError) as err:
+            _LOGGER.warning("Error creating InstantValues: %s", err)
+            return RequestStatus.UNKNOWN_ERROR, None

pooldose/mappings/__init__.py

@@ -0,0 +1 @@
+"""Mappings for async API client for SEKO Pooldose."""

pooldose/mappings/mapping_info.py

@@ -0,0 +1,222 @@
+"""Mapping Parser for async API client for SEKO Pooldose."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+import importlib.resources
+import json
+import logging
+import aiofiles
+from pooldose.request_handler import RequestStatus
+
+# pylint: disable=line-too-long
+
+_LOGGER = logging.getLogger(__name__)
+
+@dataclass
+class SensorMapping:
+    """
+    Represents a sensor mapping entry.
+    Attributes:
+        key (str): The key for the sensor.
+        type (str): The type, always "sensor".
+        conversion (Optional[dict]): Optional conversion mapping.
+    """
+    key: str
+    type: str
+    conversion: Optional[dict] = None
+
+@dataclass
+class BinarySensorMapping:
+    """
+    Represents a binary sensor mapping entry.
+    Attributes:
+        key (str): The key for the binary sensor.
+        type (str): The type, always "binary_sensor".
+    """
+    key: str
+    type: str
+
+@dataclass
+class NumberMapping:
+    """
+    Represents a number mapping entry.
+    Attributes:
+        key (str): The key for the number.
+        type (str): The type, always "number".
+    """
+    key: str
+    type: str
+
+@dataclass
+class SwitchMapping:
+    """
+    Represents a switch mapping entry.
+    Attributes:
+        key (str): The key for the switch.
+        type (str): The type, always "switch".
+    """
+    key: str
+    type: str
+
+@dataclass
+class SelectMapping:
+    """
+    Represents a select mapping entry.
+    Attributes:
+        key (str): The key for the select.
+        type (str): The type, always "select".
+        conversion (dict): Mandatory conversion mapping.
+        options (dict): Mandatory options mapping.
+    """
+    key: str
+    type: str
+    conversion: dict
+    options: dict
+
+@dataclass
+class MappingInfo:
+    """
+    Provides utilities to load and query mapping configurations for different models and firmware codes.
+
+    Attributes:
+        mapping (Optional[Dict[str, Any]]): The loaded mapping configuration, or None if not loaded.
+        status (Optional[RequestStatus]): The status of the mapping load operation.
+    """
+    mapping: Optional[Dict[str, Any]] = None
+    status: Optional[RequestStatus] = None
+
+    @classmethod
+    async def load(cls, model_id: str, fw_code: str) -> "MappingInfo":
+        """
+        Asynchronously load the model-specific mapping configuration from a JSON file.
+
+        Args:
+            model_id (str): The model ID.
+            fw_code (str): The firmware code.
+
+        Returns:
+            MappingInfo: The loaded mapping info object.
+        """
+        try:
+            if not model_id or not fw_code:
+                _LOGGER.error("MODEL_ID or FW_CODE not set!")
+                return cls(mapping=None, status=RequestStatus.NO_DATA)
+            filename = f"model_{model_id}_FW{fw_code}.json"
+            path = importlib.resources.files("pooldose.mappings").joinpath(filename)
+            async with aiofiles.open(path, "r", encoding="utf-8") as f:
+                content = await f.read()
+                mapping = json.loads(content)
+                return cls(mapping=mapping, status=RequestStatus.SUCCESS)
+        except (OSError, json.JSONDecodeError, ModuleNotFoundError, FileNotFoundError) as err:
+            _LOGGER.warning("Error loading model mapping: %s", err)
+            return cls(mapping=None, status=RequestStatus.UNKNOWN_ERROR)
+
+    def available_types(self) -> dict[str, list[str]]:
+        """
+        Returns all available types and their keys for the current model/firmware.
+
+        Returns:
+            dict[str, list[str]]: Mapping from type to list of keys.
+        """
+        if not self.mapping:
+            return {}
+        result = {}
+        for key, entry in self.mapping.items():
+            typ = entry.get("type", "unknown")
+            result.setdefault(typ, []).append(key)
+        return result
+
+    def available_sensors(self) -> Dict[str, SensorMapping]:
+        """
+        Returns all available sensors from the mapping as SensorMapping objects.
+
+        Returns:
+            Dict[str, SensorMapping]: Mapping from name to SensorMapping.
+        """
+        if not self.mapping:
+            return {}
+        result = {}
+        for name, entry in self.mapping.items():
+            if entry.get("type") == "sensor":
+                result[name] = SensorMapping(
+                    key=entry["key"],
+                    type=entry["type"],
+                    conversion=entry.get("conversion"),
+                )
+        return result
+
+    def available_binary_sensors(self) -> Dict[str, BinarySensorMapping]:
+        """
+        Returns all available binary sensors from the mapping as BinarySensorMapping objects.
+
+        Returns:
+            Dict[str, BinarySensorMapping]: Mapping from name to BinarySensorMapping.
+        """
+        if not self.mapping:
+            return {}
+        result = {}
+        for name, entry in self.mapping.items():
+            if entry.get("type") == "binary_sensor":
+                result[name] = BinarySensorMapping(
+                    key=entry["key"],
+                    type=entry["type"],
+                )
+        return result
+
+    def available_numbers(self) -> Dict[str, NumberMapping]:
+        """
+        Returns all available numbers from the mapping as NumberMapping objects.
+
+        Returns:
+            Dict[str, NumberMapping]: Mapping from name to NumberMapping.
+        """
+        if not self.mapping:
+            return {}
+        result = {}
+        for name, entry in self.mapping.items():
+            if entry.get("type") == "number":
+                result[name] = NumberMapping(
+                    key=entry["key"],
+                    type=entry["type"],
+                )
+        return result
+
+    def available_switches(self) -> Dict[str, SwitchMapping]:
+        """
+        Returns all available switches from the mapping as SwitchMapping objects.
+
+        Returns:
+            Dict[str, SwitchMapping]: Mapping from name to SwitchMapping.
+        """
+        if not self.mapping:
+            return {}
+        result = {}
+        for name, entry in self.mapping.items():
+            if entry.get("type") == "switch":
+                result[name] = SwitchMapping(
+                    key=entry["key"],
+                    type=entry["type"],
+                )
+        return result
+
+    def available_selects(self) -> Dict[str, SelectMapping]:
+        """
+        Returns all available selects from the mapping as SelectMapping objects.
+
+        Returns:
+            Dict[str, SelectMapping]: Mapping from name to SelectMapping.
+        Raises:
+            KeyError: If a select entry does not contain 'conversion' or 'options'.
+        """
+        if not self.mapping:
+            return {}
+        result = {}
+        for name, entry in self.mapping.items():
+            if entry.get("type") == "select":
+                result[name] = SelectMapping(
+                    key=entry["key"],
+                    type=entry["type"],
+                    conversion=entry["conversion"],
+                    options=entry["options"],
+                )
+        return result

pooldose/mappings/model_PDPR1H1HAW100_FW539187.json

@@ -0,0 +1,153 @@
+{
+  "temperature": {
+    "key": "w_1eommf39k",
+    "type": "sensor"
+  },
+  "ph": {
+    "key": "w_1ekeigkin",
+    "type": "sensor"
+  },
+  "orp": {
+    "key": "w_1eklenb23",
+    "type": "sensor"
+  },
+  "ph_type_dosing": {
+    "key": "w_1eklg44ro",
+    "type": "sensor",
+    "conversion": {
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklg44ro_ALCALYNE|": "alcalyne",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklg44ro_ACID|"    : "acid"
+    }
+  },
+  "peristaltic_ph_dosing": {
+    "key": "w_1eklj6euj",
+    "type": "sensor",
+    "conversion": {
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklj6euj_OFF|": "off",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklj6euj_PROPORTIONAL|": "proportional",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklj6euj_ON_OFF|": "on_off",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklj6euj_TIMED|": "timed"
+    }
+  },
+  "ofa_ph_value": {
+    "key": "w_1eo1ttmft",
+    "type": "sensor"
+  },
+  "orp_type_dosing": {
+    "key": "w_1eklgnolb",
+    "type": "sensor",
+    "conversion": {
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklgnolb_LOW|": "low",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklgnolb_HIGH|": "high"
+    }
+  },
+  "peristaltic_orp_dosing": {
+    "key": "w_1eo1s18s8",
+    "type": "sensor",
+    "conversion": {
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eo1s18s8_OFF|": "off",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eo1s18s8_PROPORTIONAL|": "proportional",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eo1s18s8_ON_OFF|": "on_off",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eo1s18s8_TIMED|": "timed"
+    }
+  },
+  "ofa_orp_value": {
+    "key": "w_1eo1tui1d",
+    "type": "sensor"
+  },
+  "ph_calibration_type": {
+    "key": "w_1eklh8gb7",
+    "type": "sensor",
+    "conversion": {
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklh8gb7_OFF|": "off",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklh8gb7_REFERENCE|": "reference",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklh8gb7_1_POINT|": "1_point",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklh8gb7_2_POINTS|": "2_points"
+    }
+  },
+  "ph_calibration_offset": {
+    "key": "w_1eklhs3b4",
+    "type": "sensor"
+  },
+  "ph_calibration_slope": {
+    "key": "w_1eklhs65u",
+    "type": "sensor"
+  },
+  "orp_calibration_type": {
+    "key": "w_1eklh8i5t",
+    "type": "sensor",
+    "conversion": {
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklh8i5t_OFF|": "off",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklh8i5t_REFERENCE|": "reference",
+        "|PDPR1H1HAW100_FW539187_LABEL_w_1eklh8i5t_1_POINT|": "1_point"
+    }
+  },
+  "orp_calibration_offset": {
+    "key": "w_1eklhs8r3",
+    "type": "sensor"
+  },
+  "orp_calibration_slope": {
+    "key": "w_1eklhsase",
+    "type": "sensor"
+  },
+  "pump_running": {
+    "key": "w_1ekga097n",
+    "type": "binary_sensor"
+  },
+  "ph_level_ok": {
+    "key": "w_1eklf77pm",
+    "type": "binary_sensor"
+  },
+  "orp_level_ok": {
+    "key": "w_1eo04bcr2",
+    "type": "binary_sensor"
+  },
+  "flow_rate_ok": {
+    "key": "w_1eo04nc5n",
+    "type": "binary_sensor"
+  },
+  "alarm_relay": {
+    "key": "w_1eklffdl0",
+    "type": "binary_sensor"
+  },
+  "relay_aux1_ph": {
+    "key": "w_1eoi2rv4h",
+    "type": "binary_sensor"
+  },
+  "relay_aux2_orpcl": {
+    "key": "w_1eoi2s16b",
+    "type": "binary_sensor"
+  },
+    "ph_target": {
+    "key": "w_1ekeiqfat",
+    "type": "number"
+  },
+    "orp_target": {
+    "key": "w_1eklgnjk2",
+    "type": "number"
+  },
+    "stop_pool_dosing": {
+    "key": "w_1emtltkel",
+    "type": "switch"
+  },
+    "pump_detection": {
+    "key": "w_1eklft47q",
+    "type": "switch"
+  },
+    "frequency_input": {
+    "key": "w_1eklft5qt",
+    "type": "switch"
+  },
+    "water_meter_unit": {
+        "key": "w_1eklinki6",
+        "type": "select",
+        "options": {
+            "0": "PDPR1H1HAW100_FW539187_COMBO_w_1eklinki6_M_",
+            "1": "PDPR1H1HAW100_FW539187_COMBO_w_1eklinki6_LITER"
+        },
+        "conversion": {
+            "PDPR1H1HAW100_FW539187_COMBO_w_1eklinki6_M_": "m³",
+            "PDPR1H1HAW100_FW539187_COMBO_w_1eklinki6_LITER": "L"
+        }
+    }   
+}