plugwise 0.36.3__tar.gz → 0.37.0__tar.gz

{plugwise-0.36.3 → plugwise-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: plugwise
-Version: 0.36.3
+Version: 0.37.0
 Summary: Plugwise Smile (Adam/Anna/P1) and Stretch module for Python 3.
 Home-page: https://github.com/plugwise/python-plugwise
 Author: Plugwise device owners

plugwise-0.37.0/plugwise/__init__.py

@@ -0,0 +1,391 @@
+"""Use of this source code is governed by the MIT license found in the LICENSE file.
+
+Plugwise backend module for Home Assistant Core.
+"""
+from __future__ import annotations
+
+from plugwise.constants import (
+    DEFAULT_PORT,
+    DEFAULT_TIMEOUT,
+    DEFAULT_USERNAME,
+    DOMAIN_OBJECTS,
+    LOGGER,
+    MODULES,
+    NONE,
+    SMILES,
+    STATUS,
+    SYSTEM,
+    PlugwiseData,
+    ThermoLoc,
+)
+from plugwise.exceptions import (
+    InvalidSetupError,
+    PlugwiseError,
+    ResponseError,
+    UnsupportedDeviceError,
+)
+from plugwise.helper import SmileComm
+from plugwise.legacy.smile import SmileLegacyAPI
+from plugwise.smile import SmileAPI
+
+import aiohttp
+from defusedxml import ElementTree as etree
+
+# Dict as class
+# Version detection
+import semver
+
+
+class Smile(SmileComm):
+    """The Plugwise SmileConnect class."""
+
+    # pylint: disable=too-many-instance-attributes, too-many-public-methods
+
+    def __init__(
+        self,
+        host: str,
+        password: str,
+        websession: aiohttp.ClientSession,
+        username: str = DEFAULT_USERNAME,
+        port: int = DEFAULT_PORT,
+        timeout: float = DEFAULT_TIMEOUT,
+
+    ) -> None:
+        """Set the constructor for this class."""
+        super().__init__(
+            host,
+            password,
+            websession,
+            username,
+            port,
+            timeout,
+        )
+
+        self._host = host
+        self._passwd = password
+        self._websession = websession
+        self._user = username
+        self._port = port
+        self._timeout = timeout
+
+        self._cooling_present = False
+        self._elga = False
+        self._is_thermostat = False
+        self._last_active: dict[str, str | None] = {}
+        self._on_off_device = False
+        self._opentherm_device = False
+        self._schedule_old_states: dict[str, dict[str, str]] = {}
+        self._smile_api: SmileAPI | SmileLegacyAPI
+        self._stretch_v2 = False
+        self._target_smile: str = NONE
+        self.gateway_id: str = NONE
+        self.loc_data: dict[str, ThermoLoc] = {}
+        self.smile_fw_version: str | None
+        self.smile_hostname: str
+        self.smile_hw_version: str | None = None
+        self.smile_legacy = False
+        self.smile_mac_address: str | None
+        self.smile_model: str
+        self.smile_name: str
+        self.smile_type: str
+        self.smile_version: tuple[str, semver.version.Version]
+        self.smile_zigbee_mac_address: str | None = None
+
+    async def connect(self) -> bool:
+        """Connect to Plugwise device and determine its name, type and version."""
+        result = await self._request(DOMAIN_OBJECTS)
+        # Work-around for Stretch fw 2.7.18
+        if not (vendor_names := result.findall("./module/vendor_name")):
+            result = await self._request(MODULES)
+            vendor_names = result.findall("./module/vendor_name")
+
+        names: list[str] = []
+        for name in vendor_names:
+            names.append(name.text)
+
+        vendor_models = result.findall("./module/vendor_model")
+        models: list[str] = []
+        for model in vendor_models:
+            models.append(model.text)
+
+        dsmrmain = result.find("./module/protocols/dsmrmain")
+        if "Plugwise" not in names and dsmrmain is None:  # pragma: no cover
+            LOGGER.error(
+                "Connected but expected text not returned, we got %s. Please create"
+                " an issue on http://github.com/plugwise/python-plugwise",
+                result,
+            )
+            raise ResponseError
+
+        # Check if Anna is connected to an Adam
+        if "159.2" in models:
+            LOGGER.error(
+                "Your Anna is connected to an Adam, make sure to only add the Adam as integration."
+            )
+            raise InvalidSetupError
+
+        # Determine smile specifics
+        await self._smile_detect(result, dsmrmain)
+
+        self._smile_api = SmileAPI(
+            self._host,
+            self._passwd,
+            self._websession,
+            self._cooling_present,
+            self._elga,
+            self._is_thermostat,
+            self._last_active,
+            self._on_off_device,
+            self._opentherm_device,
+            self._schedule_old_states,
+            self.gateway_id,
+            self.loc_data,
+            self.smile_fw_version,
+            self.smile_hostname,
+            self.smile_hw_version,
+            self.smile_legacy,
+            self.smile_mac_address,
+            self.smile_model,
+            self.smile_name,
+            self.smile_type,
+            self.smile_version,
+            self._user,
+            self._port,
+            self._timeout,
+         )
+        if self.smile_legacy:
+            self._smile_api = SmileLegacyAPI(
+                self._host,
+                self._passwd,
+                self._websession,
+                self._is_thermostat,
+                self._on_off_device,
+                self._opentherm_device,
+                self._stretch_v2,
+                self._target_smile,
+                self.loc_data,
+                self.smile_fw_version,
+                self.smile_hostname,
+                self.smile_hw_version,
+                self.smile_mac_address,
+                self.smile_model,
+                self.smile_name,
+                self.smile_type,
+                self.smile_version,
+                self.smile_zigbee_mac_address,
+                self._user,
+                self._port,
+                self._timeout,
+            )
+
+        # Update all endpoints on first connect
+        await self._smile_api.full_update_device()
+
+        return True
+
+    async def _smile_detect(self, result: etree, dsmrmain: etree) -> None:
+        """Helper-function for connect().
+
+        Detect which type of Smile is connected.
+        """
+        model: str = "Unknown"
+        if (gateway := result.find("./gateway")) is not None:
+            if (v_model := gateway.find("vendor_model")) is not None:
+                model = v_model.text
+            self.smile_fw_version = gateway.find("firmware_version").text
+            self.smile_hw_version = gateway.find("hardware_version").text
+            self.smile_hostname = gateway.find("hostname").text
+            self.smile_mac_address = gateway.find("mac_address").text
+        else:
+            model = await self._smile_detect_legacy(result, dsmrmain, model)
+
+        if model == "Unknown" or self.smile_fw_version is None:  # pragma: no cover
+            # Corner case check
+            LOGGER.error(
+                "Unable to find model or version information, please create"
+                " an issue on http://github.com/plugwise/python-plugwise"
+            )
+            raise UnsupportedDeviceError
+
+        ver = semver.version.Version.parse(self.smile_fw_version)
+        self._target_smile = f"{model}_v{ver.major}"
+        LOGGER.debug("Plugwise identified as %s", self._target_smile)
+        if self._target_smile not in SMILES:
+            LOGGER.error(
+                "Your Smile identified as %s seems unsupported by our plugin, please"
+                " create an issue on http://github.com/plugwise/python-plugwise",
+                self._target_smile,
+            )
+            raise UnsupportedDeviceError
+
+        if self._target_smile in ("smile_open_therm_v2", "smile_thermo_v3"):
+            LOGGER.error(
+                "Your Smile identified as %s needs a firmware update as it's firmware is severely outdated",
+                self._target_smile,
+            )  # pragma: no cover
+            raise UnsupportedDeviceError  # pragma: no cover
+
+        self.smile_model = "Gateway"
+        self.smile_name = SMILES[self._target_smile].smile_name
+        self.smile_type = SMILES[self._target_smile].smile_type
+        self.smile_version = (self.smile_fw_version, ver)
+
+        if self.smile_type == "stretch":
+            self._stretch_v2 = self.smile_version[1].major == 2
+
+        if self.smile_type == "thermostat":
+            self._is_thermostat = True
+            # For Adam, Anna, determine the system capabilities:
+            # Find the connected heating/cooling device (heater_central),
+            # e.g. heat-pump or gas-fired heater
+            onoff_boiler: etree = result.find("./module/protocols/onoff_boiler")
+            open_therm_boiler: etree = result.find(
+                "./module/protocols/open_therm_boiler"
+            )
+            self._on_off_device = onoff_boiler is not None
+            self._opentherm_device = open_therm_boiler is not None
+
+            # Determine the presence of special features
+            locator_1 = "./gateway/features/cooling"
+            locator_2 = "./gateway/features/elga_support"
+            if result.find(locator_1) is not None:
+                self._cooling_present = True
+            if result.find(locator_2) is not None:
+                self._elga = True
+
+    async def _smile_detect_legacy(
+        self, result: etree, dsmrmain: etree, model: str
+    ) -> str:
+        """Helper-function for _smile_detect()."""
+        return_model = model
+        # Stretch: find the MAC of the zigbee master_controller (= Stick)
+        if (network := result.find("./module/protocols/master_controller")) is not None:
+            self.smile_zigbee_mac_address = network.find("mac_address").text
+        # Find the active MAC in case there is an orphaned Stick
+        if zb_networks := result.findall("./network"):
+            for zb_network in zb_networks:
+                if zb_network.find("./nodes/network_router") is not None:
+                    network = zb_network.find("./master_controller")
+                    self.smile_zigbee_mac_address = network.find("mac_address").text
+
+        # Legacy Anna or Stretch:
+        if (
+            result.find('./appliance[type="thermostat"]') is not None
+            or network is not None
+        ):
+            system = await self._request(SYSTEM)
+            self.smile_fw_version = system.find("./gateway/firmware").text
+            return_model = system.find("./gateway/product").text
+            self.smile_hostname = system.find("./gateway/hostname").text
+            # If wlan0 contains data it's active, so eth0 should be checked last
+            for network in ("wlan0", "eth0"):
+                locator = f"./{network}/mac"
+                if (net_locator := system.find(locator)) is not None:
+                    self.smile_mac_address = net_locator.text
+        # P1 legacy:
+        elif dsmrmain is not None:
+            status = await self._request(STATUS)
+            self.smile_fw_version = status.find("./system/version").text
+            return_model = status.find("./system/product").text
+            self.smile_hostname = status.find("./network/hostname").text
+            self.smile_mac_address = status.find("./network/mac_address").text
+        else:  # pragma: no cover
+            # No cornercase, just end of the line
+            LOGGER.error(
+                "Connected but no gateway device information found, please create"
+                " an issue on http://github.com/plugwise/python-plugwise"
+            )
+            raise ResponseError
+
+        self.smile_legacy = True
+        return return_model
+
+    async def full_update_device(self) -> None:
+        """Perform a first fetch of all XML data, needed for initialization."""
+        await self._smile_api.full_update_device()
+
+    def get_all_devices(self) -> None:
+        """Determine the devices present from the obtained XML-data."""
+        self._smile_api.get_all_devices()
+
+    async def async_update(self) -> PlugwiseData:
+        """Perform an incremental update for updating the various device states."""
+        data: PlugwiseData = await self._smile_api.async_update()
+        self.gateway_id = data.gateway["gateway_id"]
+        return data
+
+########################################################################################################
+###  API Set and HA Service-related Functions                                                        ###
+########################################################################################################
+
+    async def set_schedule_state(
+        self,
+        loc_id: str,
+        new_state: str,
+        name: str | None = None,
+    ) -> None:
+        """Activate/deactivate the Schedule, with the given name, on the relevant Thermostat."""
+        await self._smile_api.set_schedule_state(loc_id, new_state, name)
+
+    async def set_preset(self, loc_id: str, preset: str) -> None:
+        """Set the given Preset on the relevant Thermostat."""
+        await self._smile_api.set_preset(loc_id, preset)
+
+    async def set_temperature(self, loc_id: str, items: dict[str, float]) -> None:
+        """Set the given Temperature on the relevant Thermostat."""
+        try:
+            await self._smile_api.set_temperature(loc_id, items)
+        except PlugwiseError as exc:
+            raise PlugwiseError(
+                    "Plugwise: failed setting temperature: no valid input provided"
+                ) from exc
+
+    async def set_number_setpoint(self, key: str, _: str, temperature: float) -> None:
+        """Set the max. Boiler or DHW setpoint on the Central Heating boiler."""
+        try:
+            await self._smile_api.set_number_setpoint(key, temperature)
+        except PlugwiseError as exc:
+            raise PlugwiseError(f"Plugwise: cannot change setpoint, {key} not found.") from exc
+
+    async def set_temperature_offset(self, _: str, dev_id: str, offset: float) -> None:
+        """Set the Temperature offset for thermostats that support this feature."""
+        try:
+            await self._smile_api.set_temperature_offset(dev_id, offset)
+        except PlugwiseError as exc:
+            raise PlugwiseError(
+                "Plugwise: this device does not have temperature-offset capability."
+            ) from exc
+
+    async def set_switch_state(
+        self, appl_id: str, members: list[str] | None, model: str, state: str
+    ) -> None:
+        """Set the given State of the relevant Switch."""
+        try:
+            await self._smile_api.set_switch_state(appl_id, members, model, state)
+        except PlugwiseError as exc:
+            raise PlugwiseError("Plugwise: the locked Relay was not switched.") from exc
+
+    async def set_gateway_mode(self, mode: str) -> None:
+        """Set the gateway mode."""
+        try:
+            await self._smile_api.set_gateway_mode(mode)
+        except PlugwiseError as exc:
+            raise PlugwiseError("Plugwise: invalid gateway mode.") from exc
+
+    async def set_regulation_mode(self, mode: str) -> None:
+        """Set the heating regulation mode."""
+        try:
+            await self._smile_api.set_regulation_mode(mode)
+        except PlugwiseError as exc:
+            raise PlugwiseError("Plugwise: invalid regulation mode.") from exc
+
+    async def set_dhw_mode(self, mode: str) -> None:
+        """Set the domestic hot water heating regulation mode."""
+        try:
+            await self._smile_api.set_dhw_mode(mode)
+        except PlugwiseError as exc:
+            raise PlugwiseError("Plugwise: invalid dhw mode.") from exc
+
+    async def delete_notification(self) -> None:
+        """Delete the active Plugwise Notification."""
+        await self._smile_api.delete_notification()

plugwise-0.37.0/plugwise/data.py

@@ -0,0 +1,263 @@
+"""Use of this source code is governed by the MIT license found in the LICENSE file.
+
+Plugwise Smile protocol data-collection helpers.
+"""
+from __future__ import annotations
+
+from plugwise.constants import (
+    ADAM,
+    ANNA,
+    MAX_SETPOINT,
+    MIN_SETPOINT,
+    NONE,
+    OFF,
+    SWITCH_GROUP_TYPES,
+    ZONE_THERMOSTATS,
+    ActuatorData,
+    DeviceData,
+)
+from plugwise.helper import SmileHelper
+from plugwise.util import remove_empty_platform_dicts
+
+
+class SmileData(SmileHelper):
+    """The Plugwise Smile main class."""
+
+    def __init__(self) -> None:
+        """Init."""
+        SmileHelper.__init__(self)
+
+
+    def _update_gw_devices(self) -> None:
+        """Helper-function for _all_device_data() and async_update().
+
+        Collect data for each device and add to self.gw_devices.
+        """
+        for device_id, device in self.gw_devices.items():
+            data = self._get_device_data(device_id)
+            self._add_or_update_notifications(device_id, device, data)
+            device.update(data)
+            self._update_for_cooling(device)
+            remove_empty_platform_dicts(device)
+
+    def _add_or_update_notifications(
+        self, device_id: str, device: DeviceData, data: DeviceData
+    ) -> None:
+        """Helper-function adding or updating the Plugwise notifications."""
+        if (
+            device_id == self.gateway_id
+            and (
+                self._is_thermostat or self.smile_type == "power"
+            )
+        ) or (
+            "binary_sensors" in device
+            and "plugwise_notification" in device["binary_sensors"]
+        ):
+            data["binary_sensors"]["plugwise_notification"] = bool(self._notifications)
+            self._count += 1
+
+    def _update_for_cooling(self, device: DeviceData) -> None:
+        """Helper-function for adding/updating various cooling-related values."""
+        # For Anna and heating + cooling, replace setpoint with setpoint_high/_low
+        if (
+            self.smile(ANNA)
+            and self._cooling_present
+            and device["dev_class"] == "thermostat"
+        ):
+            thermostat = device["thermostat"]
+            sensors = device["sensors"]
+            temp_dict: ActuatorData = {
+                "setpoint_low": thermostat["setpoint"],
+                "setpoint_high": MAX_SETPOINT,
+            }
+            if self._cooling_enabled:
+                temp_dict = {
+                    "setpoint_low": MIN_SETPOINT,
+                    "setpoint_high": thermostat["setpoint"],
+                }
+            thermostat.pop("setpoint")
+            temp_dict.update(thermostat)
+            device["thermostat"] = temp_dict
+            if "setpoint" in sensors:
+                sensors.pop("setpoint")
+            sensors["setpoint_low"] = temp_dict["setpoint_low"]
+            sensors["setpoint_high"] = temp_dict["setpoint_high"]
+            self._count += 2
+
+    def _all_device_data(self) -> None:
+        """Helper-function for get_all_devices().
+
+        Collect data for each device and add to self.gw_data and self.gw_devices.
+        """
+        self._update_gw_devices()
+        self.device_items = self._count
+        self.gw_data.update(
+            {
+                "gateway_id": self.gateway_id,
+                "item_count": self._count,
+                "notifications": self._notifications,
+                "smile_name": self.smile_name,
+            }
+        )
+        if self._is_thermostat:
+            self.gw_data.update(
+                {"heater_id": self._heater_id, "cooling_present": self._cooling_present}
+            )
+
+    def _device_data_switching_group(
+        self, device: DeviceData, data: DeviceData
+    ) -> None:
+        """Helper-function for _get_device_data().
+
+        Determine switching group device data.
+        """
+        if device["dev_class"] in SWITCH_GROUP_TYPES:
+            counter = 0
+            for member in device["members"]:
+                if self.gw_devices[member]["switches"].get("relay"):
+                    counter += 1
+            data["switches"]["relay"] = counter != 0
+            self._count += 1
+
+    def _device_data_adam(self, device: DeviceData, data: DeviceData) -> None:
+        """Helper-function for _get_device_data().
+
+        Determine Adam heating-status for on-off heating via valves,
+        available regulations_modes and thermostat control_states.
+        """
+        if self.smile(ADAM):
+            # Indicate heating_state based on valves being open in case of city-provided heating
+            if (
+                device["dev_class"] == "heater_central"
+                and self._on_off_device
+                and isinstance(self._heating_valves(), int)
+            ):
+                data["binary_sensors"]["heating_state"] = self._heating_valves() != 0
+
+            # Show the allowed regulation modes and gateway_modes
+            if device["dev_class"] == "gateway":
+                if self._reg_allowed_modes:
+                    data["regulation_modes"] = self._reg_allowed_modes
+                    self._count += 1
+                if self._gw_allowed_modes:
+                    data["gateway_modes"] = self._gw_allowed_modes
+                    self._count += 1
+
+            # Control_state, only for Adam master thermostats
+            if device["dev_class"] in ZONE_THERMOSTATS:
+                loc_id = device["location"]
+                if ctrl_state := self._control_state(loc_id):
+                    data["control_state"] = ctrl_state
+                    self._count += 1
+
+    def _device_data_climate(self, device: DeviceData, data: DeviceData) -> None:
+        """Helper-function for _get_device_data().
+
+        Determine climate-control device data.
+        """
+        loc_id = device["location"]
+
+        # Presets
+        data["preset_modes"] = None
+        data["active_preset"] = None
+        self._count += 2
+        if presets := self._presets(loc_id):
+            data["preset_modes"] = list(presets)
+            data["active_preset"] = self._preset(loc_id)
+
+        # Schedule
+        avail_schedules, sel_schedule = self._schedules(loc_id)
+        data["available_schedules"] = avail_schedules
+        data["select_schedule"] = sel_schedule
+        self._count += 2
+
+        # Operation modes: auto, heat, heat_cool, cool and off
+        data["mode"] = "auto"
+        self._count += 1
+        if sel_schedule == NONE:
+            data["mode"] = "heat"
+            if self._cooling_present:
+                data["mode"] = "cool" if self.check_reg_mode("cooling") else "heat_cool"
+
+        if self.check_reg_mode("off"):
+            data["mode"] = "off"
+
+        if NONE not in avail_schedules:
+            self._get_schedule_states_with_off(
+                loc_id, avail_schedules, sel_schedule, data
+            )
+
+    def check_reg_mode(self, mode: str) -> bool:
+        """Helper-function for device_data_climate()."""
+        gateway = self.gw_devices[self.gateway_id]
+        return (
+            "regulation_modes" in gateway and gateway["select_regulation_mode"] == mode
+        )
+
+    def _get_schedule_states_with_off(
+        self, location: str, schedules: list[str], selected: str, data: DeviceData
+    ) -> None:
+        """Collect schedules with states for each thermostat.
+
+        Also, replace NONE by OFF when none of the schedules are active.
+        """
+        loc_schedule_states: dict[str, str] = {}
+        for schedule in schedules:
+            loc_schedule_states[schedule] = "off"
+            if schedule == selected and data["mode"] == "auto":
+                loc_schedule_states[schedule] = "on"
+        self._schedule_old_states[location] = loc_schedule_states
+
+        all_off = True
+        for state in self._schedule_old_states[location].values():
+            if state == "on":
+                all_off = False
+        if all_off:
+            data["select_schedule"] = OFF
+
+    def _check_availability(
+        self, device: DeviceData, dev_class: str, data: DeviceData, message: str
+    ) -> None:
+        """Helper-function for _get_device_data().
+
+        Provide availability status for the wired-commected devices.
+        """
+        if device["dev_class"] == dev_class:
+            data["available"] = True
+            self._count += 1
+            for item in self._notifications.values():
+                for msg in item.values():
+                    if message in msg:
+                        data["available"] = False
+
+    def _get_device_data(self, dev_id: str) -> DeviceData:
+        """Helper-function for _all_device_data() and async_update().
+
+        Provide device-data, based on Location ID (= dev_id), from APPLIANCES.
+        """
+        device = self.gw_devices[dev_id]
+        data = self._get_measurement_data(dev_id)
+
+        # Check availability of wired-connected devices
+        # Smartmeter
+        self._check_availability(
+            device, "smartmeter", data, "P1 does not seem to be connected"
+        )
+        # OpenTherm device
+        if device["name"] != "OnOff":
+            self._check_availability(
+                device, "heater_central", data, "no OpenTherm communication"
+            )
+
+        # Switching groups data
+        self._device_data_switching_group(device, data)
+        # Adam data
+        self._device_data_adam(device, data)
+        # Skip obtaining data for non master-thermostats
+        if device["dev_class"] not in ZONE_THERMOSTATS:
+            return data
+
+        # Thermostat data (presets, temperatures etc)
+        self._device_data_climate(device, data)
+
+        return data