aioWiserHeatAPI 1.7.7__tar.gz → 1.7.9__tar.gz

aiowiserheatapi-1.7.9/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: aioWiserHeatAPI
+Version: 1.7.9
+Summary: An AsyncIO API for controlling the Drayton Wiser Heating system
+Home-page: https://github.com/msp1974/aioWiserHeatAPI
+Author: Mark Parker
+Author-email: msparker@sky.com
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: zeroconf>=0.131.0
+Requires-Dist: aiohttp>=3.9.3
+Requires-Dist: aiofiles>=23.2.1
+Requires-Dist: pyyaml>=6.0.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Drayton Wiser Hub API Async
+
+An asynchronous Python API for the Drayton Wiser heating system used in the UK.
+It supports one-, two-, and three-channel HeatHubs, Smart Plugs, shutters, lights,
+and other Wiser devices.
+
+## Requirements
+
+Python 3.12 or later.
+
+## Installation
+
+```sh
+python -m pip install aioWiserHeatAPI
+```
+
+## Hub setup
+
+### 1. Find your HeatHub secret key
+
+1. Press the setup button on your HeatHub. The light will start flashing.
+2. Connect your computer or phone to the Wi-Fi network named `WiserHeatXXXXXX`,
+   where `XXXXXX` is the last six digits of the hub's MAC address.
+3. Open `http://192.168.8.1/secret` in a browser. Save the returned string as your
+   hub's secret key.
+4. Press the setup button again to return the HeatHub to normal operation.
+
+See the [HeatHub connection guide](https://it.knightnet.org.uk/kb/nr-qa/drayton-wiser-heating-control/#controlling-the-system)
+for more information.
+
+### 2. Find your HeatHub IP address
+
+Use your router's connected-device list to find the HeatHub's IP address. The hub
+usually identifies itself as `WiserHeatXXXXXX`.
+
+Hub discovery is also available through the API; see
+[discovery.py](aioWiserHeatAPI/discovery.py).
+
+## Documentation
+
+- [API documentation](docs/info.md)
+- [API implementation](aioWiserHeatAPI/wiserhub.py)
+- [Release history](CHANGELOG.md)

aiowiserheatapi-1.7.9/README.md

@@ -0,0 +1,43 @@
+# Drayton Wiser Hub API Async
+
+An asynchronous Python API for the Drayton Wiser heating system used in the UK.
+It supports one-, two-, and three-channel HeatHubs, Smart Plugs, shutters, lights,
+and other Wiser devices.
+
+## Requirements
+
+Python 3.12 or later.
+
+## Installation
+
+```sh
+python -m pip install aioWiserHeatAPI
+```
+
+## Hub setup
+
+### 1. Find your HeatHub secret key
+
+1. Press the setup button on your HeatHub. The light will start flashing.
+2. Connect your computer or phone to the Wi-Fi network named `WiserHeatXXXXXX`,
+   where `XXXXXX` is the last six digits of the hub's MAC address.
+3. Open `http://192.168.8.1/secret` in a browser. Save the returned string as your
+   hub's secret key.
+4. Press the setup button again to return the HeatHub to normal operation.
+
+See the [HeatHub connection guide](https://it.knightnet.org.uk/kb/nr-qa/drayton-wiser-heating-control/#controlling-the-system)
+for more information.
+
+### 2. Find your HeatHub IP address
+
+Use your router's connected-device list to find the HeatHub's IP address. The hub
+usually identifies itself as `WiserHeatXXXXXX`.
+
+Hub discovery is also available through the API; see
+[discovery.py](aioWiserHeatAPI/discovery.py).
+
+## Documentation
+
+- [API documentation](docs/info.md)
+- [API implementation](aioWiserHeatAPI/wiserhub.py)
+- [Release history](CHANGELOG.md)

{aiowiserheatapi-1.7.7 → aiowiserheatapi-1.7.9}/aioWiserHeatAPI/__init__.py

@@ -3,6 +3,6 @@ import logging
 name = "aioWiserHeatAPI"
 __all__ = ["wiserAPI", "wiserDiscovery"]
 
-__VERSION__ = "1.7.7"
+__VERSION__ = "1.7.9"
 
 _LOGGER = logging.getLogger(__name__)

{aiowiserheatapi-1.7.7 → aiowiserheatapi-1.7.9}/aioWiserHeatAPI/automation.py

@@ -1,8 +1,13 @@
 import inspect
 
 from . import _LOGGER
-from .const import TEXT_UNKNOWN, WISERSYSTEM
-from .rest_controller import _WiserRestController
+from .const import (
+    TEXT_UNKNOWN,
+    WISERAUTOMATION,
+    WISERHUBAUTOMATION,
+    WISERSYSTEM,
+)
+from .rest_controller import WiserRestActionEnum, _WiserRestController
 
 
 class _WiserAutomation:
@@ -11,6 +16,8 @@ class _WiserAutomation:
     ):
         self._wiser_rest_controller = wiser_rest_controller
         self._automation_data = automation_data
+        self._details = {}
+        self._details_loaded = False
 
     async def _send_command(self, cmd: dict) -> bool:
         """
@@ -46,10 +53,48 @@ class _WiserAutomation:
     def notification_enabled(self) -> bool:
         return self._automation_data.get("EnableNotification", False)
 
+    async def get_details(self, refresh: bool = False) -> dict:
+        """Return the automation triggers, actions and time constraints."""
+        if refresh or not self._details_loaded:
+            details = await self._wiser_rest_controller.get_hub_data(
+                f"{WISERHUBAUTOMATION}{self.id}",
+                False,
+            )
+            self._details = details if isinstance(details, dict) else {}
+            self._details_loaded = True
+        return self._details.copy()
+
     async def enable_notification(self):
         """Activate automation"""
         return await self._send_command({"EnableNotification": self.id})
 
+    async def set_notification_enabled(self, enabled: bool) -> bool:
+        """Enable or disable notifications for this automation."""
+        await self._wiser_rest_controller._send_command(
+            f"{WISERAUTOMATION.format(self.id)}/EnableNotification",
+            enabled,
+        )
+        self._automation_data["EnableNotification"] = enabled
+        return True
+
+    async def set_enabled(self, enabled: bool) -> bool:
+        """Enable or disable this automation."""
+        await self._wiser_rest_controller._send_command(
+            f"{WISERAUTOMATION.format(self.id)}/Enabled",
+            enabled,
+        )
+        self._automation_data["Enabled"] = enabled
+        return True
+
+    async def delete(self) -> bool:
+        """Delete this automation from the hub."""
+        await self._wiser_rest_controller._send_command(
+            WISERAUTOMATION.format(self.id),
+            None,
+            WiserRestActionEnum.DELETE,
+        )
+        return True
+
 
 class _WiserAutomationCollection(object):
     def __init__(

{aiowiserheatapi-1.7.7 → aiowiserheatapi-1.7.9}/aioWiserHeatAPI/binary_sensor.py

@@ -6,6 +6,7 @@ import inspect
 
 from aioWiserHeatAPI import _LOGGER
 
+from .const import WiserWindowDoorEnableNotificationEnum
 from .helpers.battery import _WiserBattery
 from .helpers.device import _WiserDevice
 from .helpers.threshold import _WiserThresholdSensor
@@ -60,10 +61,54 @@ class _WiserBinarySensor(_WiserDevice):
         return self._device_type_data.get("Type")
 
     @property
-    def enable_notification(self) -> str:
-        """Get if notifications is enable"""
+    def enable_notification(self) -> str | None:
+        """Return the native notification mode, when supported."""
         return self._device_type_data.get("EnableNotification")
 
+    @property
+    def available_enable_notification(self) -> list[str]:
+        """Return the native notification modes accepted by the hub."""
+        return [mode.value for mode in WiserWindowDoorEnableNotificationEnum]
+
+    @property
+    def notification_enabled(self) -> bool | None:
+        """Return whether any native notification mode is enabled."""
+        mode = self.enable_notification
+        if mode is None:
+            return None
+        if isinstance(mode, bool):
+            return mode
+        return mode != WiserWindowDoorEnableNotificationEnum.none.value
+
+    async def set_enable_notification(
+        self,
+        enable_notification: WiserWindowDoorEnableNotificationEnum | str,
+    ) -> bool:
+        """Set the native notification mode for this sensor."""
+        if isinstance(
+            enable_notification, WiserWindowDoorEnableNotificationEnum
+        ):
+            enable_notification = enable_notification.value
+        if enable_notification not in self.available_enable_notification:
+            raise ValueError(
+                f"{enable_notification} is not a valid notification mode. "
+                f"Valid modes are {self.available_enable_notification}"
+            )
+        await self._wiser_rest_controller._send_command(
+            self._endpoint.format(self.device_type_id),
+            {"EnableNotification": enable_notification},
+        )
+        self._device_type_data["EnableNotification"] = enable_notification
+        return True
+
+    async def set_notification_enabled(self, enabled: bool) -> bool:
+        """Enable or disable native notifications for this sensor."""
+        return await self.set_enable_notification(
+            WiserWindowDoorEnableNotificationEnum.oneither
+            if enabled
+            else WiserWindowDoorEnableNotificationEnum.none
+        )
+
     @property
     def battery(self) -> _WiserBattery:
         """Get the battery information for the smokealarm"""

{aiowiserheatapi-1.7.7 → aiowiserheatapi-1.7.9}/aioWiserHeatAPI/const.py

@@ -63,7 +63,6 @@ TEXT_WEEKDAYS = "Weekdays"
 TEXT_WEEKENDS = "Weekends"
 TEXT_ALL = "All"
 TEXT_UNABLE = "Unable"
-# added by Lgo44
 
 TEXT_REVERSE = "ReverseWithLoad"
 TEXT_CONSISTENT = "ConsistentWithLoad"
@@ -74,7 +73,10 @@ TEXT_OFF_AFTER_2S = "OffAfter2s"
 TEXT_LASTON = "LastOnBrightness"
 TEXT_LEVELPERCENT = "LevelPercent"
 
-# End added by Lgo44
+TEXT_RL_LED = "RL_LED"
+
+TEXT_RELAY = "Relay"
+TEXT_FIL_PILOTE = "FilPilote"
 
 # Day Value Lists
 WEEKDAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
@@ -93,6 +95,7 @@ WISERHUBSCHEDULES = WISERHUBURL + "schedules/"
 WISERHUBOPENTHERM = WISERHUBURL + "opentherm/"
 WISERHUBOPENTHERMV2 = WISERHUBURL + "openTherm/"
 WISERHUBSTATUS = WISERHUBURL + "status/"
+WISERHUBAUTOMATION = "{}:{}/Automation/"
 WISERSYSTEM = "System"
 WISERDEVICE = "Device/{}"
 WISERHOTWATER = "HotWater/{}"
@@ -113,6 +116,7 @@ WISERBUTTONPANEL = "ButtonPanel/{}"
 WISEREQUIPMENT = "Equipment/{}"
 WISERTHRESHOLDSENSOR = "ThresholdSensor/{}"
 WISERUICONFIGURATION = "UIConfiguration/{}"
+WISERAUTOMATION = "Automation/{}"
 
 
 # Enums
@@ -131,6 +135,15 @@ class WiserTempLimitsEnum(enum.Enum):
     floorHeatingOffset = {"min": -9, "max": 9, "type": "range"}
 
 
+class WiserWindowDoorEnableNotificationEnum(enum.Enum):
+    """Native notification modes supported by window and door sensors."""
+
+    oneither = "OnEither"
+    none = "None"
+    ontrue = "OnTrue"
+    onfalse = "OnFalse"
+
+
 class WiserAwayActionEnum(enum.Enum):
     off = TEXT_OFF
     nochange = TEXT_NO_CHANGE
@@ -141,7 +154,6 @@ class WiserShutterAwayActionEnum(enum.Enum):
     nochange = TEXT_NO_CHANGE
 
 
-# added by Lgo44
 class WiserLightLedIndicatorEnum(enum.Enum):
     reverse = TEXT_REVERSE
     consistent = TEXT_CONSISTENT
@@ -155,7 +167,21 @@ class WiserLightPowerOnBehaviourEnum(enum.Enum):
     levelpercent = TEXT_LEVELPERCENT
 
 
-# End added by Lgo44
+class WiserLightOutputModeEnum(enum.Enum):
+    auto = TEXT_AUTO
+    rl_led = TEXT_RL_LED
+
+
+class WiserSmartPlugLedIndicatorEnum(enum.Enum):
+    reverse = TEXT_REVERSE
+    consistent = TEXT_CONSISTENT
+    allwayson = TEXT_ALWAYSON
+    allwaysoff = TEXT_ALWAYSOFF
+
+
+class WiserHeatingActuatorOutputTypeEnum(enum.Enum):
+    relay = TEXT_RELAY
+    fil_pilote = TEXT_FIL_PILOTE
 
 
 class WiserDeviceModeEnum(enum.Enum):

{aiowiserheatapi-1.7.7 → aiowiserheatapi-1.7.9}/aioWiserHeatAPI/devices.py

@@ -29,6 +29,7 @@ from .const import (
     WISERUICONFIGURATION,
 )
 from .evse import _WiserEVSE, _WiserEVSECollection
+from .equipments import _WiserEquipmentsCollection
 from .heating_actuator import _WiserHeatingActuator, _WiserHeatingActuatorCollection
 from .helpers.device import _WiserDevice
 from .helpers.threshold import (
@@ -182,7 +183,13 @@ class _WiserDeviceCollection:
         self._wiser_rest_controller = wiser_rest_controller
         self._device_data = domain_data.get("Device", {})
         self._domain_data = domain_data
-        self._equipment_data = domain_data.get("Equipment", {})  # Supported by v2 hub
+        equipment_data = domain_data.get("Equipment")
+        self._equipment_data = (
+            equipment_data if isinstance(equipment_data, list) else []
+        )
+        self._equipments = _WiserEquipmentsCollection(
+            wiser_rest_controller, self._equipment_data
+        )
         self._schedules = schedules
         self._device_collection = {}
 
@@ -358,6 +365,11 @@ class _WiserDeviceCollection:
         except KeyError:
             return None
 
+    @property
+    def equipments(self) -> _WiserEquipmentsCollection:
+        """Return all equipment records reported by the hub."""
+        return self._equipments
+
     @property
     def lights(self) -> _WiserLightCollection:
         """Return all lights"""

aiowiserheatapi-1.7.9/aioWiserHeatAPI/equipments.py

@@ -0,0 +1,159 @@
+"""Represent and manage equipment records returned by a Wiser hub."""
+
+from typing import Literal
+
+from .const import WISEREQUIPMENT
+from .helpers.equipment import _WiserEquipment
+from .rest_controller import WiserRestActionEnum, _WiserRestController
+
+PowerNotificationName = Literal[
+    "UnderPowerNotification", "OverPowerNotification"
+]
+
+
+class _WiserEquipments(_WiserEquipment):
+    """A single equipment record, including its writable settings."""
+
+    def __init__(
+        self, wiser_rest_controller: _WiserRestController, data: dict
+    ) -> None:
+        super().__init__(data)
+        self._wiser_rest_controller = wiser_rest_controller
+
+    async def _set_power_notification(
+        self,
+        notification_name: PowerNotificationName,
+        period_mins: int,
+        limit: int,
+        enabled: bool,
+    ) -> bool:
+        """Create or replace a native power notification on the hub."""
+        notification = {
+            "PeriodMins": period_mins,
+            "Limit": limit,
+            "Enabled": enabled,
+        }
+        await self._wiser_rest_controller._send_command(
+            WISEREQUIPMENT.format(self.id),
+            {notification_name: notification},
+        )
+        self._data[notification_name] = notification
+        return True
+
+    async def set_under_power_notification(
+        self, period_mins: int, limit: int, enabled: bool = True
+    ) -> bool:
+        """Create or replace the native under-power notification."""
+        return await self._set_power_notification(
+            "UnderPowerNotification", period_mins, limit, enabled
+        )
+
+    async def set_over_power_notification(
+        self, period_mins: int, limit: int, enabled: bool = True
+    ) -> bool:
+        """Create or replace the native over-power notification."""
+        return await self._set_power_notification(
+            "OverPowerNotification", period_mins, limit, enabled
+        )
+
+    async def _set_power_notification_enabled(
+        self, notification_name: PowerNotificationName, enabled: bool
+    ) -> bool:
+        """Update an existing notification without losing its settings."""
+        notification = self._data.get(notification_name)
+        if not isinstance(notification, dict):
+            return False
+
+        updated_notification = {
+            key: notification[key]
+            for key in ("PeriodMins", "Limit")
+            if key in notification
+        }
+        updated_notification["Enabled"] = enabled
+        await self._wiser_rest_controller._send_command(
+            WISEREQUIPMENT.format(self.id),
+            {notification_name: updated_notification},
+        )
+        notification["Enabled"] = enabled
+        return True
+
+    async def set_under_power_notification_enabled(self, enabled: bool) -> bool:
+        """Enable or disable the under-power notification."""
+        return await self._set_power_notification_enabled(
+            "UnderPowerNotification", enabled
+        )
+
+    async def set_over_power_notification_enabled(self, enabled: bool) -> bool:
+        """Enable or disable the over-power notification."""
+        return await self._set_power_notification_enabled(
+            "OverPowerNotification", enabled
+        )
+
+    async def _delete_power_notification(
+        self, notification_name: PowerNotificationName
+    ) -> bool:
+        """Delete a native power notification from the hub."""
+        if notification_name not in self._data:
+            return False
+
+        await self._wiser_rest_controller._send_command(
+            f"{WISEREQUIPMENT.format(self.id)}/{notification_name}/",
+            None,
+            WiserRestActionEnum.DELETE,
+        )
+        self._data.pop(notification_name, None)
+        return True
+
+    async def delete_under_power_notification(self) -> bool:
+        """Delete the native under-power notification."""
+        return await self._delete_power_notification("UnderPowerNotification")
+
+    async def delete_over_power_notification(self) -> bool:
+        """Delete the native over-power notification."""
+        return await self._delete_power_notification("OverPowerNotification")
+
+
+class _WiserEquipmentsCollection:
+    """Collection of equipment records reported by the hub."""
+
+    def __init__(
+        self,
+        wiser_rest_controller: _WiserRestController,
+        equipments_data: list[dict] | None = None,
+    ) -> None:
+        records = equipments_data if isinstance(equipments_data, list) else []
+        self._items = [
+            _WiserEquipments(wiser_rest_controller, record)
+            for record in records
+            if isinstance(record, dict)
+        ]
+        self._items_by_id = {
+            item.id: item
+            for item in self._items
+            if isinstance(item._data.get("id"), int)
+        }
+
+    @property
+    def all(self) -> list[_WiserEquipments]:
+        """Return all equipment records."""
+        return list(self._items)
+
+    @property
+    def count(self) -> int:
+        """Return the number of equipment records."""
+        return len(self._items)
+
+    def get_by_id(self, equipment_id: int) -> _WiserEquipments | None:
+        """Return an equipment record by its id."""
+        return self._items_by_id.get(equipment_id)
+
+    def get_by_equipment_id(self, equipment_id: int) -> _WiserEquipments | None:
+        """Return an equipment record by its equipment id."""
+        return self.get_by_id(equipment_id)
+
+    def get_by_device_id(self, device_id: int) -> _WiserEquipments | None:
+        """Return the equipment record linked to a device instance."""
+        return next(
+            (item for item in self._items if item.device_id == device_id),
+            None,
+        )

{aiowiserheatapi-1.7.7 → aiowiserheatapi-1.7.9}/aioWiserHeatAPI/evse.py

@@ -36,7 +36,7 @@ class _WiserEVSE(_WiserDevice):
     @property
     def available_control_states(self) -> list[str]:
         """Return control states accepted by the hub for this equipment."""
-        return self._device_type_data.get("AvailableControlState") or []
+        return self.equipment.available_control_states
 
     @property
     def control_state(self) -> str:
@@ -69,12 +69,15 @@ class _WiserEVSE(_WiserDevice):
         result = await self._wiser_rest_controller._send_command(
             WISEREQUIPMENT.format(self.equipment_id), {"ControlState": state}
         )
-        if result:
-            # Some hub versions return only the changed field. Preserve the
-            # equipment telemetry and advertised states until the next poll.
-            self._device_type_data = {**self._device_type_data, **result}
-            return True
-        return False
+        # Successful hub commands can return an empty object or only the
+        # changed field. Preserve existing telemetry and reflect the requested
+        # state until the next poll supplies a complete equipment record.
+        self._device_type_data = {
+            **self._device_type_data,
+            **result,
+            "ControlState": result.get("ControlState", state),
+        }
+        return True
 
     async def turn_on(self) -> bool:
         """Return the EVSE to its normal self-managed state."""

{aiowiserheatapi-1.7.7 → aiowiserheatapi-1.7.9}/aioWiserHeatAPI/heating_actuator.py

@@ -1,4 +1,13 @@
-from .const import TEMP_OFF, TEXT_UNKNOWN, WISERHEATINGACTUATOR, WiserTempLimitsEnum
+from typing import Union
+
+from .const import (
+    TEMP_OFF,
+    TEXT_UNKNOWN,
+    WISERDEVICE,
+    WISERHEATINGACTUATOR,
+    WiserHeatingActuatorOutputTypeEnum,
+    WiserTempLimitsEnum,
+)
 from .helpers.device import _WiserDevice
 from .helpers.equipment import _WiserEquipment
 from .helpers.temp import _WiserTemperatureFunctions as tf
@@ -115,6 +124,22 @@ class _WiserHeatingActuator(_WiserDevice):
         self._threshold_sensors: list[_WiserThresholdSensor] = []
         self._uiconfig_sensors: list[_WiserUIConfigSensor] = []
 
+    async def _send_command(self, cmd: dict, device_level: bool = False) -> bool:
+        """Send commands using the ID belonging to the requested endpoint."""
+        endpoint = (
+            WISERDEVICE.format(self.id)
+            if device_level
+            else self._endpoint.format(self.device_type_id)
+        )
+        result = await self._wiser_rest_controller._send_command(endpoint, cmd)
+        if not result:
+            return False
+        if device_level:
+            self._data = result
+        else:
+            self._device_type_data = result
+        return True
+
     @property
     def current_target_temperature(self) -> float:
         """Get the current target temperature setting"""
@@ -164,11 +189,6 @@ class _WiserHeatingActuator(_WiserDevice):
         """Get the amount of current passing through the device now"""
         return self._device_type_data.get("InstantaneousDemand", None)
 
-    @property
-    def output_type(self) -> str:
-        """Get output type"""
-        return self._device_type_data.get("OutputType", TEXT_UNKNOWN)
-
     @property
     def threshold_sensors(self) -> list[_WiserThresholdSensor]:
         """Get threshold sensors."""
@@ -179,6 +199,30 @@ class _WiserHeatingActuator(_WiserDevice):
         """Get ui configuration sensors."""
         return self._uiconfig_sensors
 
+    @property
+    def available_output_type(self) -> list[str]:
+        """Get available heating-actuator output types."""
+        return [output_type.value for output_type in WiserHeatingActuatorOutputTypeEnum]
+
+    @property
+    def output_type(self) -> str:
+        """Get the output type for the heating actuator."""
+        return self._device_type_data.get("OutputType", TEXT_UNKNOWN)
+
+    async def set_output_type(
+        self, output_type: Union[WiserHeatingActuatorOutputTypeEnum, str]
+    ) -> bool:
+        """Set the output type using an enum or case-insensitive string."""
+        if isinstance(output_type, WiserHeatingActuatorOutputTypeEnum):
+            output_type = output_type.value
+        if isinstance(output_type, str):
+            for mode in WiserHeatingActuatorOutputTypeEnum:
+                if output_type.casefold() == mode.value.casefold():
+                    return await self._send_command({"OutputType": mode.value})
+        raise ValueError(
+            f"{output_type} is not a valid type.  Valid types are {self.available_output_type}"
+        )
+
 
 class _WiserHeatingActuatorCollection(object):
     """Class holding all wiser heating actuators"""