violet-poolController-api 0.0.1__py3-none-any.whl

violet_poolcontroller_api/circuit_breaker.py

@@ -0,0 +1,172 @@
+
+"""Circuit breaker implementation for resilient API calls."""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CircuitBreakerState:
+    """Circuit breaker states."""
+
+    CLOSED = "CLOSED"  # Normal operation
+    OPEN = "OPEN"  # Circuit is open, calls fail fast
+    HALF_OPEN = "HALF_OPEN"  # Testing if service recovered
+
+
+class CircuitBreaker:
+    """Circuit breaker pattern for API calls with automatic recovery.
+
+    Protects against cascading failures when the controller or network is down.
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        timeout: float = 60.0,
+        recovery_timeout: float = 300.0,
+        expected_exception: type[BaseException] = Exception,
+    ):
+        """
+        Initialize circuit breaker.
+
+        Args:
+            failure_threshold: Number of failures before opening circuit
+            timeout: How long to keep circuit open (seconds)
+            recovery_timeout: How long to stay in half-open state
+            expected_exception: Exception type to consider for failures
+        """
+        self.failure_threshold = failure_threshold
+        self.timeout = timeout
+        self.recovery_timeout = recovery_timeout
+        self.expected_exception = expected_exception
+
+        self.failure_count = 0
+        self.last_failure_time = 0.0
+        self.state = CircuitBreakerState.CLOSED
+        self.half_open_start_time = 0.0
+
+        # Protects mutable state from concurrent coroutine access (e.g., asyncio.gather)
+        self._lock = asyncio.Lock()
+
+        _LOGGER.debug(
+            "Circuit breaker initialized: threshold=%d, timeout=%.1fs, recovery=%.1fs",
+            failure_threshold,
+            timeout,
+            recovery_timeout,
+        )
+
+    async def call(self, func: Callable, *args, **kwargs) -> Any:
+        """
+        Execute function with circuit breaker protection.
+
+        Args:
+            func: The async function to call
+            *args: Arguments to pass to function
+            **kwargs: Keyword arguments to pass to function
+
+        Returns:
+            Result of function call
+
+        Raises:
+            CircuitBreakerOpenError: If circuit is open
+        """
+        current_time = time.monotonic()
+
+        # Check and update circuit state under lock to prevent races
+        async with self._lock:
+            # Check if circuit should be closed from timeout
+            if (
+                self.state == CircuitBreakerState.OPEN
+                and current_time - self.last_failure_time > self.timeout
+            ):
+                self.state = CircuitBreakerState.HALF_OPEN
+                self.half_open_start_time = current_time
+                _LOGGER.info("Circuit breaker entering HALF_OPEN state for recovery test")
+
+            # Check if half-open timeout exceeded
+            if (
+                self.state == CircuitBreakerState.HALF_OPEN
+                and current_time - self.half_open_start_time > self.recovery_timeout
+            ):
+                self.state = CircuitBreakerState.CLOSED
+                self.failure_count = 0
+                _LOGGER.info("Circuit breaker recovered to CLOSED state")
+
+            # Fail fast if circuit is open
+            if self.state == CircuitBreakerState.OPEN:
+                raise CircuitBreakerOpenError("Circuit breaker is OPEN")
+
+        try:
+            # Execute the function outside the lock to avoid blocking other coroutines
+            result = await func(*args, **kwargs)
+
+            # Success: reset failure count and close circuit if half-open
+            async with self._lock:
+                if self.state == CircuitBreakerState.HALF_OPEN:
+                    self.state = CircuitBreakerState.CLOSED
+                    self.failure_count = 0
+                    _LOGGER.info("Circuit breaker recovered from HALF_OPEN to CLOSED")
+                else:
+                    self.failure_count = 0
+
+            return result
+
+        except self.expected_exception as err:
+            async with self._lock:
+                self.failure_count += 1
+                self.last_failure_time = current_time
+
+                _LOGGER.debug(
+                    "Circuit breaker failure %d/%d: %s",
+                    self.failure_count,
+                    self.failure_threshold,
+                    str(err),
+                )
+
+                # Open circuit if threshold reached
+                if self.failure_count >= self.failure_threshold:
+                    self.state = CircuitBreakerState.OPEN
+                    _LOGGER.warning(
+                        "Circuit breaker OPENED due to %d failures",
+                        self.failure_threshold,
+                    )
+
+            # Re-raise the original exception
+            raise
+
+        except Exception as err:
+            # Unexpected exception - don't count for circuit breaker
+            _LOGGER.exception("Unexpected error in circuit breaker: %s", str(err))
+            raise
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get circuit breaker statistics."""
+        return {
+            "state": self.state,
+            "failure_count": self.failure_count,
+            "failure_threshold": self.failure_threshold,
+            "timeout": self.timeout,
+            "recovery_timeout": self.recovery_timeout,
+            "last_failure_time": self.last_failure_time,
+            "half_open_start_time": self.half_open_start_time,
+        }
+
+    def reset(self) -> None:
+        """Manually reset the circuit breaker (call from sync context only)."""
+        self.state = CircuitBreakerState.CLOSED
+        self.failure_count = 0
+        self.last_failure_time = 0.0
+        self.half_open_start_time = 0.0
+        _LOGGER.info("Circuit breaker manually reset to CLOSED state")
+
+
+class CircuitBreakerOpenError(Exception):
+    """Exception raised when circuit breaker is open."""
+
+    pass

violet_poolcontroller_api/const_api.py

@@ -0,0 +1,136 @@
+
+"""This module defines constants related to the Violet Pool Controller API.
+
+It includes API endpoints, command actions, rate limiting settings, and
+definitions for various controllable functions like switches, covers, and dosing pumps.
+These constants provide a centralized and consistent way to interact with the
+controller's HTTP API.
+"""
+from __future__ import annotations
+
+# =============================================================================
+# API ENDPOINTS
+# =============================================================================
+
+API_READINGS = "/getReadings"
+API_SET_FUNCTION_MANUALLY = "/setFunctionManually"
+API_SET_DOSING_PARAMETERS = "/setDosingParameters"
+API_SET_TARGET_VALUES = "/setTargetValues"
+API_GET_CONFIG = "/getConfig"
+API_SET_CONFIG = "/setConfig"
+API_GET_CALIB_RAW_VALUES = "/getCalibRawValues"
+API_GET_CALIB_HISTORY = "/getCalibHistory"
+API_RESTORE_CALIBRATION = "/restoreOldCalib"
+API_SET_OUTPUT_TESTMODE = "/setOutputTestmode"
+API_GET_HISTORY = "/getHistory"
+API_GET_WEATHER_DATA = "/getWeatherdata"
+API_GET_OVERALL_DOSING = "/getOverallDosing"
+API_GET_OUTPUT_STATES = "/getOutputstates"
+
+# Settings for optimizing data refreshes by fetching specific groups.
+SPECIFIC_READING_GROUPS = (
+    "ADC",
+    "DOSAGE",
+    "RUNTIMES",
+    "PUMPPRIOSTATE",
+    "BACKWASH",
+    "SYSTEM",
+    "INPUT1",
+    "INPUT2",
+    "INPUT3",
+    "INPUT4",
+    "date",
+    "time",
+)
+SPECIFIC_FULL_REFRESH_INTERVAL = 10  # Number of updates before a full refresh
+
+# =============================================================================
+# API ACTIONS
+# =============================================================================
+
+ACTION_ON = "ON"
+ACTION_OFF = "OFF"
+ACTION_AUTO = "AUTO"
+ACTION_PUSH = "PUSH"
+ACTION_MAN = "MAN"
+ACTION_COLOR = "COLOR"
+ACTION_ALLON = "ALLON"
+ACTION_ALLOFF = "ALLOFF"
+ACTION_ALLAUTO = "ALLAUTO"
+ACTION_LOCK = "LOCK"
+ACTION_UNLOCK = "UNLOCK"
+
+# Common Query and Target Parameters
+QUERY_ALL = "ALL"
+TARGET_PH = "pH"
+TARGET_ORP = "ORP"
+TARGET_MIN_CHLORINE = "MinChlorine"
+KEY_MAINTENANCE = "MAINTENANCE"
+KEY_PVSURPLUS = "PVSURPLUS"
+
+# =============================================================================
+# API RATE LIMITING
+# =============================================================================
+
+API_RATE_LIMIT_REQUESTS = 10  # Max requests per window
+API_RATE_LIMIT_WINDOW = 1.0  # Window duration in seconds
+API_RATE_LIMIT_BURST = 3  # Number of burst requests allowed
+API_RATE_LIMIT_RETRY_AFTER = 0.1  # Wait time after exceeding the limit
+
+# Priority levels for API requests
+API_PRIORITY_CRITICAL = 1  # For state changes and critical operations
+API_PRIORITY_HIGH = 2  # For target value updates
+API_PRIORITY_NORMAL = 3  # For regular data fetches
+API_PRIORITY_LOW = 4  # For history and statistics
+
+# =============================================================================
+# API FUNCTION AND KEY DEFINITIONS
+# =============================================================================
+
+# Base switchable functions
+SWITCH_FUNCTIONS = {
+    "PUMP": "Filter Pump",
+    "SOLAR": "Solar Absorber",
+    "HEATER": "Heater",
+    "LIGHT": "Lighting",
+    "ECO": "Eco Mode",
+    "BACKWASH": "Backwash",
+    "BACKWASHRINSE": "Backwash Rinse",
+    "REFILL": "Water Refill",
+    "PVSURPLUS": "PV Surplus",
+}
+
+# Dynamically add extension relays
+for ext_bank in [1, 2]:
+    for relay_num in range(1, 9):
+        SWITCH_FUNCTIONS[f"EXT{ext_bank}_{relay_num}"] = (
+            f"Erweiterung {ext_bank}.{relay_num}"
+        )
+
+# Dynamically add DMX scenes
+for scene_num in range(1, 13):
+    SWITCH_FUNCTIONS[f"DMX_SCENE{scene_num}"] = f"DMX Szene {scene_num}"
+
+# Dynamically add digital input rules
+for rule_num in range(1, 8):
+    SWITCH_FUNCTIONS[f"DIRULE_{rule_num}"] = f"Schaltregel {rule_num}"
+
+# Dynamically add Omni DC outputs
+for dc_num in range(6):
+    SWITCH_FUNCTIONS[f"OMNI_DC{dc_num}"] = f"Omni DC{dc_num}"
+
+# Cover control functions
+COVER_FUNCTIONS = {
+    "OPEN": "COVER_OPEN",
+    "CLOSE": "COVER_CLOSE",
+    "STOP": "COVER_STOP",
+}
+
+# Dosing pump functions
+DOSING_FUNCTIONS = {
+    "pH-": "DOS_4_PHM",
+    "pH+": "DOS_5_PHP",
+    "Chlor": "DOS_1_CL",
+    "Elektrolyse": "DOS_2_ELO",
+    "Flockmittel": "DOS_6_FLOC",
+}

violet_poolcontroller_api/const_devices.py

@@ -0,0 +1,307 @@
+
+"""This module defines constants related to device characteristics and states.
+
+It includes detailed parameter configurations for various devices (e.g., pumps, heaters),
+state mappings for normalizing device statuses, and visual configurations like icons
+and colors. The module also provides helper functions and a `VioletState` class to
+consistently interpret and manage device states throughout the integration.
+"""
+from __future__ import annotations
+
+from typing import Any, cast
+
+# =============================================================================
+# DEVICE PARAMETERS - Extended Configuration
+# =============================================================================
+
+DEVICE_PARAMETERS = {
+    "PUMP": {
+        "supports_speed": True,
+        "api_template": "PUMP,{action},{duration},{speed}",
+    },
+    "HEATER": {
+        "supports_timer": True,
+        "api_template": "HEATER,{action},{duration},0",
+    },
+    "SOLAR": {
+        "supports_timer": True,
+        "api_template": "SOLAR,{action},{duration},0",
+    },
+    "LIGHT": {
+        "supports_color_pulse": True,
+        "api_template": "LIGHT,{action},0,0",
+    },
+    "DOS_1_CL": {
+        "supports_timer": True,
+        "dosing_type": "Chlor",
+        "api_template": "DOS_1_CL,{action},{duration},0",
+    },
+    "DOS_4_PHM": {
+        "supports_timer": True,
+        "dosing_type": "pH-",
+        "api_template": "DOS_4_PHM,{action},{duration},0",
+    },
+    "DOS_5_PHP": {
+        "supports_timer": True,
+        "dosing_type": "pH+",
+        "api_template": "DOS_5_PHP,{action},{duration},0",
+    },
+    "DOS_6_FLOC": {
+        "supports_timer": True,
+        "dosing_type": "Flockmittel",
+        "api_template": "DOS_6_FLOC,{action},{duration},0",
+    },
+    "BACKWASH": {
+        "supports_timer": True,
+        "api_template": "BACKWASH,{action},{duration},0",
+    },
+    "BACKWASHRINSE": {
+        "supports_timer": True,
+        "api_template": "BACKWASHRINSE,{action},{duration},0",
+    },
+    "PVSURPLUS": {
+        "supports_speed": True,
+        "api_template": "PVSURPLUS,{action},{speed},0",
+    },
+}
+
+# Dynamically add extension relays
+for ext_bank in [1, 2]:
+    for relay_num in range(1, 9):
+        key = f"EXT{ext_bank}_{relay_num}"
+        DEVICE_PARAMETERS[key] = {
+            "supports_timer": True,
+            "api_template": f"EXT{ext_bank}_{relay_num},{{action}},{{duration}},0",
+        }
+
+# Dynamically add digital input rules
+for rule_num in range(1, 8):
+    key = f"DIRULE_{rule_num}"
+    DEVICE_PARAMETERS[key] = {
+        "supports_lock": True,
+        "api_template": f"DIRULE_{rule_num},{{action}},0,0",
+    }
+
+# Dynamically add DMX scenes
+for scene_num in range(1, 13):
+    key = f"DMX_SCENE{scene_num}"
+    DEVICE_PARAMETERS[key] = {
+        "api_template": f"DMX_SCENE{scene_num},{{action}},0,0",
+    }
+
+# =============================================================================
+# STATE MAPPINGS - Critical for 3-State Logic
+# =============================================================================
+
+DEVICE_STATE_MAPPING = {
+    # String-based states from the API
+    "ON": {"mode": "manual", "active": True, "desc": "Manual ON"},
+    "OFF": {"mode": "manual", "active": False, "desc": "Manual OFF"},
+    "AUTO": {"mode": "auto", "active": None, "desc": "Auto Mode"},
+    # Numeric states from the API
+    "0": {"mode": "auto", "active": False, "desc": "Auto - Standby"},
+    "1": {"mode": "manual", "active": True, "desc": "Manual ON"},
+    "2": {"mode": "auto", "active": True, "desc": "Auto - Active"},
+    "3": {"mode": "auto", "active": True, "desc": "Auto - Active (Timer)"},
+    "4": {"mode": "manual", "active": True, "desc": "Manual ON (Forced)"},
+    "5": {"mode": "auto", "active": False, "desc": "Auto - Waiting"},
+    "6": {"mode": "manual", "active": False, "desc": "Manual OFF"},
+    # Special protection modes (from PUMPSTATE field with pipe separator)
+    "3|PUMP_ANTI_FREEZE": {
+        "mode": "frost_protection",
+        "active": True,
+        "desc": "Frost Protection Active",
+    },
+    "PUMP_ANTI_FREEZE": {
+        "mode": "frost_protection",
+        "active": True,
+        "desc": "Frost Protection Active",
+    },
+    # Generic operational states
+    "STOPPED": {"mode": "manual", "active": False, "desc": "Stopped"},
+    "ERROR": {"mode": "error", "active": False, "desc": "Error State"},
+    "MAINTENANCE": {"mode": "maintenance", "active": False, "desc": "Maintenance"},
+}
+
+# Simplified map for quick boolean checks (is the device considered "on"?)
+STATE_MAP = {
+    # Numeric states (as int and str)
+    0: False,
+    1: True,
+    2: True,
+    3: True,
+    4: True,
+    5: False,
+    6: False,
+    "0": False,
+    "1": True,
+    "2": True,
+    "3": True,
+    "4": True,
+    "5": False,
+    "6": False,
+    # String states
+    "ON": True,
+    "OFF": False,
+    "AUTO": False,
+    "MAN": True,
+    "MANUAL": True,
+    "ACTIVE": True,
+    "RUNNING": True,
+    "IDLE": False,
+}
+
+# State mapping specific to cover entities
+COVER_STATE_MAP = {
+    "0": "open",
+    "1": "opening",
+    "2": "closed",
+    "3": "closing",
+    "4": "stopped",
+    "OPEN": "open",
+    "OPENING": "opening",
+    "CLOSED": "closed",
+    "CLOSING": "closing",
+    "STOPPED": "stopped",
+}
+
+# =============================================================================
+# STATE VISUALIZATION
+# =============================================================================
+
+STATE_ICONS = {
+    "auto_active": "mdi:autorenew",
+    "auto_inactive": "mdi:autorenew-off",
+    "manual_on": "mdi:power-plug",
+    "manual_off": "mdi:power-plug-off",
+    "frost_protection": "mdi:snowflake-alert",
+    "error": "mdi:alert-circle",
+    "maintenance": "mdi:wrench",
+}
+
+STATE_COLORS = {
+    "auto_active": "#4CAF50",  # Green
+    "auto_inactive": "#2196F3",  # Blue
+    "manual_on": "#FF9800",  # Orange
+    "manual_off": "#F44336",  # Red
+    "frost_protection": "#00BCD4",  # Cyan (frost/ice color)
+    "error": "#9C27B0",  # Purple
+    "maintenance": "#607D8B",  # Blue Grey
+}
+
+STATE_TRANSLATIONS = {
+    "en": {
+        "auto_active": "Auto (Active)",
+        "auto_inactive": "Auto (Ready)",
+        "manual_on": "Manual On",
+        "manual_off": "Manual Off",
+        "frost_protection": "Frost Protection",
+        "error": "Error",
+        "maintenance": "Maintenance",
+        "unknown": "Unknown",
+    },
+    "de": {
+        "auto_active": "Automatik (Aktiv)",
+        "auto_inactive": "Automatik (Bereit)",
+        "manual_on": "Manuell Ein",
+        "manual_off": "Manuell Aus",
+        "frost_protection": "Frostschutz",
+        "error": "Fehler",
+        "maintenance": "Wartung",
+        "unknown": "Unbekannt",
+    },
+}
+
+# =============================================================================
+# HELPER FUNCTIONS and STATE CLASS
+# =============================================================================
+
+
+def get_device_state_info(raw_state: Any) -> dict[str, Any]:
+    """Get extended state information for a given raw state.
+
+    Handles plain numeric states ("2"), pipe-separated composite states
+    ("2|BLOCKED_BY_OUTSIDE_TEMP"), and empty arrays ("[]").
+    """
+    state_str = str(raw_state).upper().strip()
+
+    # Direct lookup first (handles exact matches like "3|PUMP_ANTI_FREEZE")
+    if state_str in DEVICE_STATE_MAPPING:
+        return cast(dict[str, Any], DEVICE_STATE_MAPPING[state_str])
+
+    # Handle pipe-separated composite states by extracting numeric prefix
+    if "|" in state_str:
+        prefix = state_str.split("|", 1)[0].strip()
+        if prefix in DEVICE_STATE_MAPPING:
+            return cast(dict[str, Any], DEVICE_STATE_MAPPING[prefix])
+
+    # Handle empty arrays (e.g., SOLARSTATE = "[]")
+    if state_str in ("[]", "{}", ""):
+        return {"mode": "unknown", "active": None, "desc": "No data"}
+
+    return cast(
+        dict[str, Any],
+        {"mode": "unknown", "active": None, "desc": f"Unknown: {raw_state}"},
+    )
+
+
+def get_device_mode_from_state(raw_state: Any) -> str:
+    """Determine the UI display mode from a raw state."""
+    state_info = get_device_state_info(raw_state)
+    mode, active = state_info["mode"], state_info["active"]
+
+    if mode == "manual":
+        return "manual_on" if active else "manual_off"
+    if mode == "auto":
+        return "auto_active" if active else "auto_inactive"
+    return cast(str, mode)
+
+
+class VioletState:
+    """A helper class to interpret and manage complex device states.
+
+    This class provides a structured way to access different aspects of a
+    device's state, such as its operational mode, activity status, and
+    UI representations (icon, color, translated name).
+
+    Attributes:
+        raw_state (str): The original state value from the controller.
+        device_key (str | None): The unique key of the device.
+    """
+
+    def __init__(self, raw_state: Any, device_key: str | None = None):
+        self.raw_state = str(raw_state).strip()
+        self.device_key = device_key
+        self._info = get_device_state_info(self.raw_state)
+
+    @property
+    def mode(self) -> str:
+        """The primary operational mode (e.g., 'auto', 'manual', 'error')."""
+        return cast(str, self._info["mode"])
+
+    @property
+    def is_active(self) -> bool | None:
+        """Whether the device is currently active (running)."""
+        return cast(bool | None, self._info["active"])
+
+    @property
+    def description(self) -> str:
+        """A human-readable description of the current state."""
+        return cast(str, self._info["desc"])
+
+    @property
+    def display_mode(self) -> str:
+        """The translated name for the current state, suitable for UI display."""
+        mode_key = get_device_mode_from_state(self.raw_state)
+        return STATE_TRANSLATIONS.get("de", {}).get(
+            mode_key, mode_key.replace("_", " ").title()
+        )
+
+    @property
+    def icon(self) -> str:
+        """The appropriate icon for the current state."""
+        mode_key = get_device_mode_from_state(self.raw_state)
+        return STATE_ICONS.get(mode_key, "mdi:help-circle")
+
+    def __repr__(self) -> str:
+        return f"VioletState(raw='{self.raw_state}', mode='{self.mode}', active={self.is_active})"