Add Saunum integration (home-assistant#155099)

Co-authored-by: Joostlek <[email protected]>

Author: mettolen

CODEOWNERS

@@ -0,0 +1,50 @@
+"""The Saunum Leil Sauna Control Unit integration."""
+
+from __future__ import annotations
+
+import logging
+
+from pysaunum import SaunumClient, SaunumConnectionError
+
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.const import CONF_HOST
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import ConfigEntryNotReady
+
+from .const import PLATFORMS
+from .coordinator import LeilSaunaCoordinator
+
+_LOGGER = logging.getLogger(__name__)
+
+type LeilSaunaConfigEntry = ConfigEntry[LeilSaunaCoordinator]
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: LeilSaunaConfigEntry) -> bool:
+    """Set up Saunum Leil Sauna from a config entry."""
+    host = entry.data[CONF_HOST]
+
+    client = SaunumClient(host=host)
+
+    # Test connection
+    try:
+        await client.connect()
+    except SaunumConnectionError as exc:
+        raise ConfigEntryNotReady(f"Error connecting to {host}: {exc}") from exc
+
+    coordinator = LeilSaunaCoordinator(hass, client, entry)
+    await coordinator.async_config_entry_first_refresh()
+
+    entry.runtime_data = coordinator
+
+    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
+
+    return True
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: LeilSaunaConfigEntry) -> bool:
+    """Unload a config entry."""
+    if unload_ok := await hass.config_entries.async_unload_platforms(entry, PLATFORMS):
+        coordinator = entry.runtime_data
+        coordinator.client.close()
+
+    return unload_ok

homeassistant/components/saunum/__init__.py

@@ -0,0 +1,107 @@
+"""Climate platform for Saunum Leil Sauna Control Unit."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from pysaunum import MAX_TEMPERATURE, MIN_TEMPERATURE, SaunumException
+
+from homeassistant.components.climate import (
+    ClimateEntity,
+    ClimateEntityFeature,
+    HVACAction,
+    HVACMode,
+)
+from homeassistant.const import ATTR_TEMPERATURE, UnitOfTemperature
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import HomeAssistantError
+from homeassistant.helpers.entity_platform import AddConfigEntryEntitiesCallback
+
+from . import LeilSaunaConfigEntry
+from .const import DELAYED_REFRESH_SECONDS
+from .entity import LeilSaunaEntity
+
+_LOGGER = logging.getLogger(__name__)
+
+PARALLEL_UPDATES = 1
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry: LeilSaunaConfigEntry,
+    async_add_entities: AddConfigEntryEntitiesCallback,
+) -> None:
+    """Set up Saunum Leil Sauna climate entity."""
+    coordinator = entry.runtime_data
+    async_add_entities([LeilSaunaClimate(coordinator)])
+
+
+class LeilSaunaClimate(LeilSaunaEntity, ClimateEntity):
+    """Representation of a Saunum Leil Sauna climate entity."""
+
+    _attr_name = None
+    _attr_hvac_modes = [HVACMode.OFF, HVACMode.HEAT]
+    _attr_supported_features = ClimateEntityFeature.TARGET_TEMPERATURE
+    _attr_temperature_unit = UnitOfTemperature.CELSIUS
+    _attr_min_temp = MIN_TEMPERATURE
+    _attr_max_temp = MAX_TEMPERATURE
+
+    @property
+    def current_temperature(self) -> float | None:
+        """Return the current temperature in Celsius."""
+        return self.coordinator.data.current_temperature
+
+    @property
+    def target_temperature(self) -> float | None:
+        """Return the target temperature in Celsius."""
+        return self.coordinator.data.target_temperature
+
+    @property
+    def hvac_mode(self) -> HVACMode:
+        """Return current HVAC mode."""
+        session_active = self.coordinator.data.session_active
+        return HVACMode.HEAT if session_active else HVACMode.OFF
+
+    @property
+    def hvac_action(self) -> HVACAction | None:
+        """Return current HVAC action."""
+        if not self.coordinator.data.session_active:
+            return HVACAction.OFF
+
+        heater_elements_active = self.coordinator.data.heater_elements_active
+        return (
+            HVACAction.HEATING
+            if heater_elements_active and heater_elements_active > 0
+            else HVACAction.IDLE
+        )
+
+    async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:
+        """Set new HVAC mode."""
+        try:
+            if hvac_mode == HVACMode.HEAT:
+                await self.coordinator.client.async_start_session()
+            else:
+                await self.coordinator.client.async_stop_session()
+        except SaunumException as err:
+            raise HomeAssistantError(f"Failed to set HVAC mode to {hvac_mode}") from err
+
+        # The device takes 1-2 seconds to turn heater elements on/off and
+        # update heater_elements_active. Wait and refresh again to ensure
+        # the HVAC action state reflects the actual heater status.
+        await asyncio.sleep(DELAYED_REFRESH_SECONDS.total_seconds())
+        await self.coordinator.async_request_refresh()
+
+    async def async_set_temperature(self, **kwargs: Any) -> None:
+        """Set new target temperature."""
+        try:
+            await self.coordinator.client.async_set_target_temperature(
+                int(kwargs[ATTR_TEMPERATURE])
+            )
+        except SaunumException as err:
+            raise HomeAssistantError(
+                f"Failed to set temperature to {kwargs[ATTR_TEMPERATURE]}"
+            ) from err
+
+        await self.coordinator.async_request_refresh()

homeassistant/components/saunum/climate.py

@@ -0,0 +1,76 @@
+"""Config flow for Saunum Leil Sauna Control Unit integration."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pysaunum import SaunumClient, SaunumException
+import voluptuous as vol
+
+from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
+from homeassistant.const import CONF_HOST
+from homeassistant.helpers import config_validation as cv
+
+from .const import DOMAIN
+
+_LOGGER = logging.getLogger(__name__)
+
+STEP_USER_DATA_SCHEMA = vol.Schema(
+    {
+        vol.Required(CONF_HOST): cv.string,
+    }
+)
+
+
+async def validate_input(data: dict[str, Any]) -> None:
+    """Validate the user input allows us to connect.
+
+    Data has the keys from STEP_USER_DATA_SCHEMA with values provided by the user.
+    """
+    host = data[CONF_HOST]
+
+    client = SaunumClient(host=host)
+
+    try:
+        await client.connect()
+        # Try to read data to verify communication
+        await client.async_get_data()
+    finally:
+        client.close()
+
+
+class LeilSaunaConfigFlow(ConfigFlow, domain=DOMAIN):
+    """Handle a config flow for Saunum Leil Sauna Control Unit."""
+
+    VERSION = 1
+    MINOR_VERSION = 1
+
+    async def async_step_user(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Handle the initial step."""
+        errors: dict[str, str] = {}
+
+        if user_input is not None:
+            # Check for duplicate configuration
+            self._async_abort_entries_match(user_input)
+
+            try:
+                await validate_input(user_input)
+            except SaunumException:
+                errors["base"] = "cannot_connect"
+            except Exception:
+                _LOGGER.exception("Unexpected exception")
+                errors["base"] = "unknown"
+            else:
+                return self.async_create_entry(
+                    title="Saunum Leil Sauna",
+                    data=user_input,
+                )
+
+        return self.async_show_form(
+            step_id="user",
+            data_schema=STEP_USER_DATA_SCHEMA,
+            errors=errors,
+        )

homeassistant/components/saunum/config_flow.py

@@ -0,0 +1,16 @@
+"""Constants for the Saunum Leil Sauna Control Unit integration."""
+
+from datetime import timedelta
+from typing import Final
+
+from homeassistant.const import Platform
+
+DOMAIN: Final = "saunum"
+
+# Platforms
+PLATFORMS: list[Platform] = [
+    Platform.CLIMATE,
+]
+
+DEFAULT_SCAN_INTERVAL: Final = timedelta(seconds=60)
+DELAYED_REFRESH_SECONDS: Final = timedelta(seconds=3)

homeassistant/components/saunum/const.py

@@ -0,0 +1,47 @@
+"""Coordinator for Saunum Leil Sauna Control Unit integration."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from pysaunum import SaunumClient, SaunumData, SaunumException
+
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
+
+from .const import DEFAULT_SCAN_INTERVAL, DOMAIN
+
+if TYPE_CHECKING:
+    from . import LeilSaunaConfigEntry
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class LeilSaunaCoordinator(DataUpdateCoordinator[SaunumData]):
+    """Coordinator for fetching Saunum Leil Sauna data."""
+
+    config_entry: LeilSaunaConfigEntry
+
+    def __init__(
+        self,
+        hass: HomeAssistant,
+        client: SaunumClient,
+        config_entry: LeilSaunaConfigEntry,
+    ) -> None:
+        """Initialize the coordinator."""
+        super().__init__(
+            hass,
+            _LOGGER,
+            name=DOMAIN,
+            update_interval=DEFAULT_SCAN_INTERVAL,
+            config_entry=config_entry,
+        )
+        self.client = client
+
+    async def _async_update_data(self) -> SaunumData:
+        """Fetch data from the sauna controller."""
+        try:
+            return await self.client.async_get_data()
+        except SaunumException as err:
+            raise UpdateFailed(f"Communication error: {err}") from err

homeassistant/components/saunum/coordinator.py

@@ -0,0 +1,27 @@
+"""Base entity for Saunum Leil Sauna Control Unit integration."""
+
+from __future__ import annotations
+
+from homeassistant.helpers.device_registry import DeviceInfo
+from homeassistant.helpers.update_coordinator import CoordinatorEntity
+
+from .const import DOMAIN
+from .coordinator import LeilSaunaCoordinator
+
+
+class LeilSaunaEntity(CoordinatorEntity[LeilSaunaCoordinator]):
+    """Base entity for Saunum Leil Sauna."""
+
+    _attr_has_entity_name = True
+
+    def __init__(self, coordinator: LeilSaunaCoordinator) -> None:
+        """Initialize the entity."""
+        super().__init__(coordinator)
+        entry_id = coordinator.config_entry.entry_id
+        self._attr_unique_id = entry_id
+        self._attr_device_info = DeviceInfo(
+            identifiers={(DOMAIN, entry_id)},
+            name="Saunum Leil",
+            manufacturer="Saunum",
+            model="Leil Touch Panel",
+        )

homeassistant/components/saunum/entity.py

@@ -0,0 +1,12 @@
+{
+  "domain": "saunum",
+  "name": "Saunum Leil",
+  "codeowners": ["@mettolen"],
+  "config_flow": true,
+  "documentation": "https://www.home-assistant.io/integrations/saunum",
+  "integration_type": "device",
+  "iot_class": "local_polling",
+  "loggers": ["pysaunum"],
+  "quality_scale": "silver",
+  "requirements": ["pysaunum==0.1.0"]
+}