pyvesync 3.0.0b0__py3-none-any.whl

pyvesync/devices/vesyncswitch.py

@@ -0,0 +1,449 @@
+"""Classes for VeSync Switch Devices.
+
+This module provides classes for VeSync Switch Devices:
+
+    1. VeSyncSwitch: Abstract Base class for VeSync Switch Devices.
+    2. VeSyncWallSwitch: Class for VeSync Wall Switch Devices ESWL01 and ESWL03.
+    3. VeSyncDimmerSwitch: Class for VeSync Dimmer Switch Devices ESWD16.
+
+
+Attributes:
+    feature_dict (dict): Dictionary of switch models and their supported features.
+        Defines the class to use for each switch model and the list of features
+    switch_modules (dict): Dictionary of switch models as keys and their associated
+        classes as string values.
+
+Note:
+    The switch device is built from the `feature_dict` dictionary and used by the
+    `vesync.object_factory` during initial call to pyvesync.vesync.update() and
+    determines the class to instantiate for each switch model. These classes should
+    not be instantiated manually.
+"""
+
+from __future__ import annotations
+from dataclasses import asdict
+import logging
+# from abc import ABCMeta, abstractmethod
+from typing import TYPE_CHECKING
+from deprecated import deprecated
+
+from pyvesync.base_devices.switch_base import VeSyncSwitch
+from pyvesync.utils.colors import Color
+from pyvesync.utils.helpers import Helpers, Validators, Timer
+from pyvesync.utils.device_mixins import BypassV1Mixin, process_bypassv1_result
+from pyvesync.const import ConnectionStatus, DeviceStatus
+from pyvesync.models.bypass_models import RequestBypassV1, TimerModels
+from pyvesync.models import switch_models
+
+if TYPE_CHECKING:
+    from pyvesync import VeSync
+    from pyvesync.models.vesync_models import ResponseDeviceDetailsModel
+    from pyvesync.device_map import SwitchMap
+
+_LOGGER = logging.getLogger(__name__)
+
+# --8<-- [start:feature_dict]
+
+feature_dict: dict[str, dict[str, list | str]] = {
+    'ESWL01': {
+        'module': 'VeSyncWallSwitch',
+        'features': []
+    },
+    'ESWD16': {
+        'module': 'VeSyncDimmerSwitch',
+        'features': ['dimmable']
+    },
+    'ESWL03': {
+        'module': 'VeSyncWallSwitch',
+        'features': []
+    }
+}
+
+# --8<-- [end:feature_dict]
+
+switch_modules: dict = {k: v['module']
+                        for k, v in feature_dict.items()}
+
+# __all__: list = [*switch_modules.values(), 'switch_modules']
+
+
+class VeSyncWallSwitch(BypassV1Mixin, VeSyncSwitch):
+    """Etekcity standard wall switch.
+
+    Inherits from the BypassV1Mixin and VeSyncSwitch classes.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, details: ResponseDeviceDetailsModel,
+                 manager: VeSync, feature_map: SwitchMap) -> None:
+        """Initialize Etekcity Wall Switch class.
+
+        Args:
+            details (ResponseDeviceDetailsModel): The device details.
+            manager (VeSync): The VeSync manager.
+            feature_map (SwitchMap): The feature map for the device.
+        """
+        super().__init__(details, manager, feature_map)
+
+    async def get_details(self) -> None:
+        r_dict = await self.call_bypassv1_api(
+            RequestBypassV1, method='deviceDetail', endpoint='deviceDetail'
+            )
+
+        r = Helpers.process_dev_response(_LOGGER, "get_details", self, r_dict)
+        if r is None:
+            return
+        resp_model = Helpers.model_maker(
+            _LOGGER, switch_models.ResponseSwitchDetails, "get_details", r, self
+        )
+        if resp_model is None:
+            return
+        result = resp_model.result
+        if not isinstance(result, switch_models.InternalSwitchResult):
+            _LOGGER.warning("Invalid response model for switch details")
+            return
+        self.state.device_status = result.deviceStatus
+        self.state.active_time = result.activeTime
+        self.state.connection_status = result.connectionStatus
+
+    async def toggle_switch(self, toggle: bool | None = None) -> bool:
+        """Toggle switch device."""
+        if toggle is None:
+            toggle = self.state.device_status != DeviceStatus.ON
+        toggle_str = DeviceStatus.from_bool(toggle)
+
+        r_dict = await self.call_bypassv1_api(
+            switch_models.RequestSwitchStatus,
+            {"status": toggle_str, "switchNo": 0},
+            'deviceStatus',
+            'deviceStatus'
+            )
+
+        r = Helpers.process_dev_response(_LOGGER, "get_details", self, r_dict)
+        if r is None:
+            return False
+
+        self.state.device_status = DeviceStatus.from_bool(toggle)
+        self.state.connection_status = ConnectionStatus.ONLINE
+        return True
+
+    async def get_timer(self) -> None:
+        r_dict = await self.call_bypassv1_api(
+            TimerModels.RequestV1GetTimer,
+            method='getTimers',
+            endpoint='timer/getTimers'
+        )
+        if r_dict is None:
+            return
+        result_model = process_bypassv1_result(
+            self, _LOGGER, "get_timer", r_dict, TimerModels.ResultV1GetTimer
+        )
+        if result_model is None:
+            return
+
+        timers = result_model.timers
+        if not isinstance(timers, list) or len(timers) == 0:
+            _LOGGER.debug("No timers found")
+            return
+        if len(timers) > 1:
+            _LOGGER.debug("More than one timer found, using first timer")
+        timer = timers[0]
+        if not isinstance(timer, TimerModels.TimerItemV1):
+            _LOGGER.warning("Invalid timer model")
+            return
+        self.state.timer = Timer(
+            int(timer.counterTimer),
+            action=timer.action,
+            id=int(timer.timerID),
+        )
+
+    async def set_timer(self, duration: int, action: str | None = None) -> bool:
+        if action is None:
+            action = (
+                DeviceStatus.ON
+                if self.state.device_status == DeviceStatus.OFF
+                else DeviceStatus.OFF
+            )
+        if action not in [DeviceStatus.ON, DeviceStatus.OFF]:
+            _LOGGER.warning("Invalid action for timer - on/off")
+            return False
+        update_dict = {
+            'action': action,
+            'counterTime': str(duration),
+        }
+        r_dict = await self.call_bypassv1_api(
+            TimerModels.RequestV1SetTime,
+            update_dict,
+            method='addTimer',
+            endpoint='timer/addTimer'
+        )
+        if r_dict is None:
+            return False
+        result_model = process_bypassv1_result(
+            self, _LOGGER, "set_timer", r_dict, TimerModels.ResultV1SetTimer
+        )
+        if result_model is None:
+            return False
+        self.state.timer = Timer(
+            int(duration),
+            action=action,
+            id=int(result_model.timerID),
+        )
+        return True
+
+    async def clear_timer(self) -> bool:
+        if self.state.timer is None:
+            _LOGGER.warning("No timer set, run get_timer() first.")
+            return False
+        update_dict = {
+            'timerId': str(self.state.timer.id),
+        }
+        r_dict = await self.call_bypassv1_api(
+            TimerModels.RequestV1ClearTimer,
+            update_dict,
+            method='deleteTimer',
+            endpoint='timer/deleteTimer'
+        )
+        if r_dict is None:
+            return False
+        result = Helpers.process_dev_response(_LOGGER, "clear_timer", self, r_dict)
+        if result is None:
+            return False
+        self.state.timer = None
+        return True
+
+
+class VeSyncDimmerSwitch(BypassV1Mixin, VeSyncSwitch):
+    """Vesync Dimmer Switch Class with RGB Faceplate.
+
+    Inherits from the BypassV1Mixin and VeSyncSwitch classes.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, details: ResponseDeviceDetailsModel,
+                 manager: VeSync, feature_map: SwitchMap) -> None:
+        """Initialize dimmer switch class.
+
+        Args:
+            details (ResponseDeviceDetailsModel): The device details.
+            manager (VeSync): The VeSync manager.
+            feature_map (SwitchMap): The feature map for the device.
+        """
+        super().__init__(details, manager, feature_map)
+
+    async def get_details(self) -> None:
+        r_bytes = await self.call_bypassv1_api(
+            switch_models.RequestDimmerDetails,
+            method="deviceDetail",
+            endpoint="deviceDetail",
+        )
+
+        r = Helpers.process_dev_response(_LOGGER, "get_details", self, r_bytes)
+        if r is None:
+            return
+
+        resp_model = Helpers.model_maker(
+            _LOGGER, switch_models.ResponseSwitchDetails, "set_timer", r, self
+        )
+        if resp_model is None:
+            return
+        result = resp_model.result
+        if not isinstance(result, switch_models.InternalDimmerDetailsResult):
+            _LOGGER.warning("Invalid response model for dimmer details")
+            return
+        self.state.active_time = result.activeTime
+        self.state.connection_status = result.connectionStatus
+        self.state.brightness = result.brightness
+        self.state.backlight_status = result.rgbStatus
+        new_color = result.rgbValue
+        if isinstance(new_color, switch_models.DimmerRGB):
+            self.state.backlight_color = Color.from_rgb(
+                new_color.red, new_color.green, new_color.blue
+                )
+        self.state.indicator_status = result.indicatorlightStatus
+        self.state.device_status = result.deviceStatus
+
+    @deprecated(
+        reason="switch_toggle() deprecated, use toggle_switch(toggle: bool | None = None)"
+    )
+    async def switch_toggle(self, status: str) -> bool:
+        """Toggle switch status."""
+        return await self.toggle_switch(status == DeviceStatus.ON)
+
+    async def toggle_switch(self, toggle: bool | None = None) -> bool:
+        if toggle is None:
+            toggle = self.state.device_status == 'off'
+        toggle_status = DeviceStatus.from_bool(toggle)
+
+        r_bytes = await self.call_bypassv1_api(
+            switch_models.RequestDimmerStatus,
+            {"status": toggle_status},
+            'dimmerPowerSwitchCtl',
+            'dimmerPowerSwitchCtl'
+            )
+
+        r = Helpers.process_dev_response(_LOGGER, "toggle_switch", self, r_bytes)
+        if r is None:
+            return False
+
+        self.state.device_status = toggle_status
+        return True
+
+    async def toggle_indicator_light(self, toggle: bool | None = None) -> bool:
+        """Toggle indicator light."""
+        if toggle is None:
+            toggle = self.state.indicator_status == 'off'
+        toggle_status = DeviceStatus.from_bool(toggle)
+
+        r_bytes = await self.call_bypassv1_api(
+            switch_models.RequestDimmerStatus,
+            {"status": toggle_status},
+            'dimmerIndicatorLightCtl',
+            'dimmerIndicatorLightCtl'
+            )
+
+        r = Helpers.process_dev_response(_LOGGER, "toggle_indicator_light", self, r_bytes)
+        if r is None:
+            return False
+
+        self.state.indicator_status = toggle_status
+        return True
+
+    async def set_backlight_status(
+        self,
+        status: bool,
+        red: int | None = None,
+        green: int | None = None,
+        blue: int | None = None,
+    ) -> bool:
+        if red is not None and blue is not None and green is not None:
+            new_color = Color.from_rgb(red, green, blue)
+        else:
+            new_color = None
+        status_str = DeviceStatus.from_bool(status)
+
+        update_dict: dict[str, str | dict] = {"status": status_str.value}
+        if new_color is not None:
+            update_dict['rgbValue'] = asdict(new_color.rgb)
+        r_bytes = await self.call_bypassv1_api(
+            switch_models.RequestDimmerStatus,
+            update_dict,
+            'dimmerRgbValueCtl',
+            'dimmerRgbValueCtl'
+            )
+
+        r = Helpers.process_dev_response(_LOGGER, "set_rgb_backlight", self, r_bytes)
+        if r is None:
+            return False
+
+        self.state.backlight_status = status_str
+        if new_color is not None:
+            self.state.backlight_color = new_color
+        self.state.backlight_status = status_str
+        self.state.device_status = DeviceStatus.ON
+        self.state.connection_status = ConnectionStatus.ONLINE
+        return True
+
+    async def set_brightness(self, brightness: int) -> bool:
+        """Set brightness of dimmer - 1 - 100."""
+        if not Validators.validate_zero_to_hundred(brightness):
+            _LOGGER.warning("Invalid brightness - must be between 0 and 100")
+            return False
+
+        r_bytes = await self.call_bypassv1_api(
+            switch_models.RequestDimmerBrightness,
+            {"brightness": brightness},
+            'dimmerBrightnessCtl',
+            'dimmerBrightnessCtl'
+            )
+
+        r = Helpers.process_dev_response(_LOGGER, "get_details", self, r_bytes)
+        if r is None:
+            return False
+
+        self.state.brightness = brightness
+        self.state.device_status = DeviceStatus.ON
+        self.state.connection_status = ConnectionStatus.ONLINE
+        return True
+
+    async def get_timer(self) -> None:
+        r_dict = await self.call_bypassv1_api(
+            TimerModels.RequestV1GetTimer,
+            method='getTimers',
+            endpoint='timer/getTimers'
+        )
+        result_model = process_bypassv1_result(
+            self, _LOGGER, "get_timer", r_dict, TimerModels.ResultV1GetTimer
+        )
+        if result_model is None:
+            return
+        timers = result_model.timers
+        if not isinstance(timers, list) or len(timers) == 0:
+            _LOGGER.info("No timers found")
+            return
+        if len(timers) > 1:
+            _LOGGER.debug("More than one timer found, using first timer")
+        timer = timers[0]
+        if not isinstance(timer, TimerModels.TimeItemV1):
+            _LOGGER.warning("Invalid timer model")
+            return
+        self.state.timer = Timer(
+            int(timer.counterTime),
+            action=timer.action,
+            id=int(timer.timerID),
+        )
+
+    async def set_timer(self, duration: int, action: str | None = None) -> bool:
+        if action is None:
+            action = (
+                DeviceStatus.ON
+                if self.state.device_status == DeviceStatus.OFF
+                else DeviceStatus.OFF
+            )
+        if action not in [DeviceStatus.ON, DeviceStatus.OFF]:
+            _LOGGER.warning("Invalid action for timer - on/off")
+            return False
+        update_dict = {
+            'action': action,
+            'counterTime': str(duration),
+            'status': "1"
+        }
+        r_dict = await self.call_bypassv1_api(
+            TimerModels.RequestV1SetTime,
+            update_dict,
+            method='addTimer',
+            endpoint='timer/addTimer'
+        )
+        result_model = process_bypassv1_result(
+            self, _LOGGER, "set_timer", r_dict, TimerModels.ResultV1SetTimer
+        )
+        if result_model is None:
+            return False
+        self.state.timer = Timer(
+            int(duration),
+            action=action,
+            id=int(result_model.timerID),
+        )
+        return True
+
+    async def clear_timer(self) -> bool:
+        if self.state.timer is None:
+            _LOGGER.debug("No timer set, run get_timer() first.")
+            return False
+        update_dict = {
+            'timerId': str(self.state.timer.id),
+            'status': "1"
+        }
+        r_dict = await self.call_bypassv1_api(
+            TimerModels.RequestV1ClearTimer,
+            update_dict,
+            method='deleteTimer',
+            endpoint='timer/deleteTimer'
+        )
+        result = Helpers.process_dev_response(_LOGGER, "clear_timer", self, r_dict)
+        if result is None:
+            return False
+        self.state.timer = None
+        return True

pyvesync/devices/vesyncthermostat.py

@@ -0,0 +1,175 @@
+"""Thermostat device classes."""
+
+from __future__ import annotations
+import logging
+from typing import TYPE_CHECKING
+
+from pyvesync.base_devices.thermostat_base import VeSyncThermostat
+from pyvesync.utils.device_mixins import BypassV2Mixin, process_bypassv2_result
+from pyvesync.utils.helpers import Helpers, Validators
+from pyvesync.const import (
+    ThermostatConst,
+    ThermostatHoldStatus,
+    ThermostatEcoTypes,
+    ThermostatFanModes,
+    ThermostatWorkModes
+    )
+from pyvesync.models.thermostat_models import (
+    ResultThermostatDetails,
+    ThermostatMinorDetails,
+)
+
+if TYPE_CHECKING:
+    from pyvesync import VeSync
+    from pyvesync.models.vesync_models import ResponseDeviceDetailsModel
+    from pyvesync.device_map import ThermostatMap
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class VeSyncAuraThermostat(BypassV2Mixin, VeSyncThermostat):
+    """VeSync Aura Thermostat."""
+    def __init__(
+        self,
+        details: ResponseDeviceDetailsModel,
+        manager: VeSync,
+        feature_map: ThermostatMap,
+    ) -> None:
+        """Initialize VeSync Aura Thermostat."""
+        super().__init__(details, manager, feature_map)
+
+    def _process_details(self, details: ResultThermostatDetails) -> None:
+        """Internal method to process thermostat details."""
+        self.state.work_mode = ThermostatConst.WorkMode(details.workMode)
+        self.state.work_status = ThermostatConst.WorkStatus(details.workStatus)
+        self.state.fan_status = ThermostatConst.FanStatus(details.fanStatus)
+        self.state.fan_mode = ThermostatConst.FanMode(details.fanMode)
+        self.state.temperature_unit = details.tempUnit
+        self.state.temperature = details.temperature
+        self.state.humidity = details.humidity
+        self.state.heat_to_temp = details.heatToTemp
+        self.state.cool_to_temp = details.coolToTemp
+        self.state.deadband = details.deadband
+        self.state.lock_status = details.lockStatus
+        self.state.schedule_or_hold = ThermostatConst.ScheduleOrHoldOption(
+            details.scheduleOrHold
+            )
+        self.state.hold_end_time = details.holdEndTime
+        self.state.hold_option = ThermostatConst.HoldOption(details.holdOption)
+        self.state.eco_type = ThermostatConst.EcoType(details.ecoType)
+        self.state.alert_status = details.alertStatus
+        self.state.routine_running_id = details.routineRunningId
+        self.state.routines = details.routines
+
+    async def get_details(self) -> None:
+        """Get the details of the thermostat."""
+        r_dict = await self.call_bypassv2_api("getTsStatus")
+        r_model = process_bypassv2_result(
+            self, _LOGGER, "get_details", r_dict, ResultThermostatDetails
+        )
+        if r_model is None:
+            return
+        self._process_details(r_model)
+
+    async def get_configuration(self) -> None:
+        """Get configuration or 'minor details'."""
+        r_dict = await self.call_bypassv2_api("getTsMinorInfo")
+        result = process_bypassv2_result(
+            self, _LOGGER, "get_configuration", r_dict, ThermostatMinorDetails
+        )
+        if result is None:
+            return
+        self.state.configuration = result
+
+    async def _set_hold_status_api(
+        self,
+        key: str | None = None,
+        temp: float | None = None,
+        hold_status: ThermostatHoldStatus | None = None,
+    ) -> bool:
+        """Internal function to call the 'setHoldStatus' API."""
+        if key is None and temp is None and hold_status is None:
+            _LOGGER.debug("At least one of key, temp, or hold_status must be provided.")
+            return False
+        payload_data: dict[str, str | float] = {}
+        if hold_status is not None and hold_status.value == ThermostatHoldStatus.CANCEL:
+            payload_data = {"holdStatus": ThermostatHoldStatus.CANCEL}
+        else:
+            if key is None or temp is None:
+                _LOGGER.debug("Either key or temp must be provided.")
+                return False
+            payload_data = {key: temp, "holdStatus": ThermostatHoldStatus.SET.value}
+        r_dict = await self.call_bypassv2_api("setHoldStatus", data=payload_data)
+        result = Helpers.process_dev_response(
+            _LOGGER, "setHoldStatus", self, r_dict
+        )
+        return bool(result)
+
+    async def set_temp_point(self, temperature: float) -> bool:
+        return await self._set_hold_status_api("setTempPoint", temperature)
+
+    async def cancel_hold(self) -> bool:
+        """Cancel hold."""
+        return await self._set_hold_status_api(hold_status=ThermostatHoldStatus.CANCEL)
+
+    async def set_cool_to_temp(self, temperature: float) -> bool:
+        """Set cool to temperature."""
+        return await self._set_hold_status_api("coolToTemp", temperature)
+
+    async def set_heat_to_temp(self, temperature: float) -> bool:
+        """Set heat to temperature."""
+        return await self._set_hold_status_api("heatToTemp", temperature)
+
+    async def set_mode(self, mode: ThermostatWorkModes) -> bool:
+        """Set thermostat mode."""
+        if mode not in self.work_modes:
+            _LOGGER.debug("Invalid mode: %s", mode)
+            return False
+        payload_data = {"tsMode": mode}
+        r_dict = await self.call_bypassv2_api("setTsMode", data=payload_data)
+        result = Helpers.process_dev_response(
+            _LOGGER, "setTsMode", self, r_dict
+        )
+        return bool(result)
+
+    async def set_fan_mode(self, mode: ThermostatFanModes) -> bool:
+        """Set thermostat fan mode."""
+        if mode not in self.fan_modes:
+            _LOGGER.debug("Invalid fan mode: %s", mode)
+            return False
+        payload_data = {"fanMode": mode.value}
+        r_dict = await self.call_bypassv2_api("setFanMode", data=payload_data)
+        result = Helpers.process_dev_response(
+            _LOGGER, "setFanMode", self, r_dict
+        )
+        return bool(result)
+
+    async def toggle_lock(self, toggle: bool, pin: int | str | None = None) -> bool:
+        """Toggle thermostat lock status."""
+        if toggle is True and pin is None:
+            _LOGGER.debug("PIN required to lock the thermostat.")
+            return False
+        payload_data: dict[str, bool | str] = {"lockStatus": toggle}
+        if toggle is True:
+            pin_int = int(pin) if isinstance(pin, str) else pin
+            if not Validators.validate_range(pin_int, 0, 9999):
+                _LOGGER.debug("PIN must be between 0 and 9999.")
+                return False
+            payload_data['lockPinCode'] = f"{pin_int:0>4}"
+        r_dict = await self.call_bypassv2_api("setLockStatus", data=payload_data)
+        result = Helpers.process_dev_response(
+            _LOGGER, "toggle_lock_status", self, r_dict
+        )
+        return bool(result)
+
+    async def set_eco_type(self, eco_type: ThermostatEcoTypes) -> bool:
+        """Set thermostat eco type."""
+        if eco_type not in self.eco_types:
+            _LOGGER.debug("Invalid eco type: %s", eco_type)
+            return False
+        payload_data = {"ecoType": eco_type.value}
+        r_dict = await self.call_bypassv2_api("setECOType", data=payload_data)
+        result = Helpers.process_dev_response(
+            _LOGGER, "setEcoType", self, r_dict
+        )
+        return bool(result)

pyvesync/models/__init__.py

@@ -0,0 +1,11 @@
+"""Data models for VeSync API requests and responses.
+
+Models should follow the naming convention of Request/Response + API Name.
+Internal models can have any descriptive name.
+
+The `base_models` module contains the base classes for the VeSync API models, while the
+models for each device type and other API calls are stored in their respective modules.
+
+The [bypassv2_models][pyvesync.models.bypass_models] module contains the models for
+the common bypassV2 API calls.
+"""