pyvlx 0.2.27__py3-none-any.whl

pyvlx/dataobjects.py

@@ -0,0 +1,161 @@
+"""Module for Dataobjects."""
+import time
+from datetime import datetime
+from typing import Optional
+
+from .const import (
+    DHCPParameter, GatewayState, GatewaySubState,
+    LeaveLearnStateConfirmationStatus)
+
+
+class DtoLocalTime:
+    """Dataobject to hold KLF200 Time Data."""
+
+    def __init__(self, utctime: Optional[datetime] = None, localtime: Optional[datetime] = None):
+        """Initialize DtoLocalTime class."""
+        if utctime is None:
+            utctime = datetime.fromtimestamp(0)
+        if localtime is None:
+            localtime = datetime.fromtimestamp(0)
+        self.utctime = utctime
+        self.localtime = localtime
+
+    def __str__(self) -> str:
+        """Return human readable string."""
+        return (
+            '<{} utctime="{}" localtime="{}"/>'.format(
+                type(self).__name__, self.utctime, self.localtime)
+        )
+
+    def from_payload(self, payload: bytes) -> None:
+        """Build the Dto From Data."""
+        self.utctime = datetime.fromtimestamp(int.from_bytes(payload[0:4], "big"))
+        weekday = payload[11] - 1
+        if weekday == -1:
+            weekday = 6
+
+        self.localtime = datetime.fromtimestamp(time.mktime(
+            (int.from_bytes(payload[9:11], byteorder='big') + 1900,  # Year
+             payload[8],  # month
+             payload[7],  # day
+             payload[6],  # hour
+             payload[5],  # minute
+             payload[4],  # second
+             weekday,
+             int.from_bytes(payload[12:14], byteorder='big'),  # day of year
+             int.from_bytes(payload[14:15], byteorder='big', signed=True))))
+
+    def to_payload(self) -> bytes:
+        """Build the Dto From Data."""
+        payload = b''
+        payload = int(self.utctime.timestamp()).to_bytes(4, byteorder='big')
+        payload += self.localtime.second.to_bytes(1, "big")
+        payload += self.localtime.minute.to_bytes(1, "big")
+        payload += self.localtime.hour.to_bytes(1, "big")
+        payload += self.localtime.day.to_bytes(1, "big")
+        payload += self.localtime.month.to_bytes(1, "big")
+        payload += (self.localtime.year - 1900).to_bytes(2, "big")
+        if self.localtime.weekday == 6:
+            payload += (0).to_bytes(1, "big")
+        else:
+            payload += (self.localtime.weekday() + 1).to_bytes(1, "big")
+        payload += self.localtime.timetuple().tm_yday.to_bytes(2, "big")
+        payload += (self.localtime.timetuple().tm_isdst).to_bytes(1, "big", signed=True)
+        return payload
+
+
+class DtoNetworkSetup:
+    """Dataobject to hold KLF200 Network Setup."""
+
+    def __init__(self,
+                 ipaddress: Optional[str] = None,
+                 gateway: Optional[str] = None,
+                 netmask: Optional[str] = None,
+                 dhcp: Optional[DHCPParameter] = None):
+        """Initialize DtoNetworkSetup class."""
+        self.ipaddress = ipaddress
+        self.gateway = gateway
+        self.netmask = netmask
+        self.dhcp = dhcp
+
+    def __str__(self) -> str:
+        """Return human readable string."""
+        return '<{} ipaddress="{}" gateway="{}" gateway="{}"  dhcp="{}"/>'.format(
+            type(self).__name__, self.ipaddress, self.gateway,
+            self.gateway, self.dhcp
+        )
+
+
+class DtoProtocolVersion:
+    """KLF 200 Dataobject for Protocol version."""
+
+    def __init__(self, majorversion: Optional[int] = None, minorversion: Optional[int] = None):
+        """Initialize DtoProtocolVersion class."""
+        self.majorversion = majorversion
+        self.minorversion = minorversion
+
+    def __str__(self) -> str:
+        """Return human readable string."""
+        return (
+            '<{} majorversion="{}" minorversion="{}"/>'.format(
+                type(self).__name__, self.majorversion, self.minorversion
+            )
+        )
+
+
+class DtoState:
+    """Data Object for Gateway State."""
+
+    def __init__(self, gateway_state: Optional[GatewayState] = None, gateway_sub_state: Optional[GatewaySubState] = None):
+        """Initialize DtoState class."""
+        self.gateway_state = gateway_state
+        self.gateway_sub_state = gateway_sub_state
+
+    def __str__(self) -> str:
+        """Return human readable string."""
+        return (
+            '<{} gateway_state="{}" gateway_sub_state="{}"/>'.format(
+                type(self).__name__, self.gateway_state, self.gateway_sub_state
+            )
+        )
+
+
+class DtoVersion:
+    """Object for KLF200 Version Information."""
+
+    def __init__(self,
+                 softwareversion: Optional[str] = None,
+                 hardwareversion: Optional[int] = None,
+                 productgroup: Optional[int] = None,
+                 producttype: Optional[int] = None):
+        """Initialize DtoVersion class."""
+        self.softwareversion = softwareversion
+        self.hardwareversion = hardwareversion
+        self.productgroup = productgroup
+        self.producttype = producttype
+
+    def __str__(self) -> str:
+        """Return human readable string."""
+        return (
+            '<{} softwareversion="{}" hardwareversion="{}" '
+            'productgroup="{}" producttype="{}"/>'.format(
+                type(self).__name__,
+                self.softwareversion, self.hardwareversion, self.productgroup, self.producttype
+            )
+        )
+
+
+class DtoLeaveLearnState:
+    """Dataobject to hold KLF200 Data."""
+
+    def __init__(self, status: Optional[LeaveLearnStateConfirmationStatus] = None):
+        """Initialize DtoLeaveLearnState class."""
+        self.status = status
+
+    def __str__(self) -> str:
+        """Return human readable string."""
+        return (
+            '<{} status="{}"/>'.format(
+                type(self).__name__, self.status
+            )
+        )

pyvlx/discovery.py

@@ -0,0 +1,100 @@
+"""Module to discover Velux KLF200 devices on the network."""
+import asyncio
+from asyncio import Event, Future, Task
+from dataclasses import dataclass
+from typing import Any, Optional, Set
+
+from zeroconf import IPVersion
+from zeroconf.asyncio import (
+    AsyncServiceBrowser, AsyncServiceInfo, AsyncZeroconf)
+
+SERVICE_STARTS_WITH: str = "VELUX_KLF_LAN"
+SERVICE_TYPE: str = "_http._tcp.local."
+
+
+@dataclass
+class VeluxHost():
+    """Class to store Velux KLF200 host information."""
+
+    hostname: str
+    ip_address: str
+
+
+def sanitize_hostname(hostname: str) -> str:
+    """Sanitize KLF200 hostname."""
+    hostname = hostname.upper()
+    hostname = hostname.replace("._HTTP._TCP.LOCAL.", "")
+    # KLF report it's hostname within Zeroconf ServiceInfo with the "LAN_" prefix, on DHCP requests without
+    hostname = hostname.replace("LAN_", "")
+    return hostname
+
+
+class VeluxDiscovery():
+    """Class to discover Velux KLF200 devices on the network."""
+
+    hosts: list[VeluxHost] = []
+    infos: list[AsyncServiceInfo | None] = []
+
+    def __init__(self, zeroconf: AsyncZeroconf,) -> None:
+        """Initialize VeluxDiscovery object."""
+        self.zc: AsyncZeroconf = zeroconf
+
+    async def _async_discover_hosts(self, min_wait_time: float, expected_hosts: int | None) -> None:
+        """Listen for zeroconf ServiceInfo."""
+        self.hosts.clear()
+        service_names: list[str] = []
+        tasks: Set[Task] = set()
+        got_host: Event = Event()
+
+        def add_info_and_host(fut: Future) -> None:
+            info: AsyncServiceInfo = fut.result()
+            self.infos.append(info)
+            hostname = sanitize_hostname(info.name)
+            host = VeluxHost(
+                hostname=hostname,
+                ip_address=info.parsed_addresses(version=IPVersion.V4Only)[0],
+            )
+            self.hosts.append(host)
+            got_host.set()
+
+        def handler(name: str, **kwargs: Any) -> None:  # pylint: disable=W0613:unused-argument
+            if name.startswith(SERVICE_STARTS_WITH):
+                if name not in service_names:
+                    service_names.append(name)
+                    task = asyncio.create_task(self.zc.async_get_service_info(type_=SERVICE_TYPE, name=name))
+                    tasks.add(task)
+                    task.add_done_callback(add_info_and_host)
+                    task.add_done_callback(tasks.remove)
+
+        browser: AsyncServiceBrowser = AsyncServiceBrowser(self.zc.zeroconf, SERVICE_TYPE, handlers=[handler])
+        if expected_hosts:
+            while len(self.hosts) < expected_hosts:
+                await got_host.wait()
+                got_host.clear()
+        while not self.hosts:
+            await asyncio.sleep(min_wait_time)
+        await browser.async_cancel()
+        if tasks:
+            await asyncio.gather(*tasks)
+
+    async def async_discover_hosts(
+        self,
+        timeout: float = 10,
+        min_wait_time: float = 3,
+        expected_hosts: Optional[int] = None
+    ) -> bool:
+        """Return true if Velux KLF200 devices found on the network.
+
+        This function creates a zeroconf AsyncServiceBrowser and
+        waits min_wait_time (seconds) for ServiceInfos from hosts.
+        Some devices may take some time to respond (i.e. if they currently have a high CPU load).
+        If one or more Hosts are found, the function cancels the ServiceBrowser and returns true.
+        If expected_hosts is set, the function ignores min_wait_time and returns true once expected_hosts are found.
+        If timeout (seconds) is exceeded, the function returns false.
+        """
+        try:
+            async with asyncio.timeout(timeout):
+                await self._async_discover_hosts(min_wait_time, expected_hosts)
+        except TimeoutError:
+            return False
+        return True

pyvlx/exception.py

@@ -0,0 +1,26 @@
+"""Module for PyVLX Exceptions."""
+from typing import Any
+
+
+class PyVLXException(Exception):
+    """Default PyVLX Exception."""
+
+    def __init__(self, description: str, **kwargs: Any):
+        """Initialize PyVLXException class."""
+        super().__init__(description)
+        self.description = description
+        self.parameter = kwargs
+
+    def _format_parameter(self) -> str:
+        return " ".join(
+            [
+                '%s="%s"' % (key, value)
+                for (key, value) in sorted(self.parameter.items())
+            ]
+        )
+
+    def __str__(self) -> str:
+        """Return object as readable string."""
+        return '<{} description="{}" {}/>'.format(
+            type(self).__name__, self.description, self._format_parameter()
+        )

pyvlx/heartbeat.py

@@ -0,0 +1,79 @@
+"""Module for sending get state requests to API in regular periods."""
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from .api import GetState
+from .api.status_request import StatusRequest
+from .exception import PyVLXException
+from .log import PYVLXLOG
+from .opening_device import Blind, DualRollerShutter
+
+if TYPE_CHECKING:
+    from pyvlx import PyVLX
+
+
+class Heartbeat:
+    """Class for sending heartbeats to API."""
+
+    def __init__(
+        self, pyvlx: "PyVLX", interval: int = 30, load_all_states: bool = True
+    ):
+        """Initialize Heartbeat object."""
+        PYVLXLOG.debug("Heartbeat __init__")
+        self.pyvlx = pyvlx
+        self.interval = interval
+        self.load_all_states = load_all_states
+        self.task: Any = None
+
+    async def _run(self) -> None:
+        PYVLXLOG.debug("Heartbeat: task started")
+        while True:
+            PYVLXLOG.debug("Heartbeat: sleeping")
+            await asyncio.sleep(self.interval)
+            PYVLXLOG.debug("Heartbeat: pulsing")
+            try:
+                await self.pulse()
+            except (OSError, PyVLXException) as e:
+                PYVLXLOG.debug("Heartbeat: pulsing failed: %s", e)
+
+    async def _start(self) -> None:
+        if self.task is not None:
+            await self.stop()
+        PYVLXLOG.debug("Heartbeat: creating task")
+        self.task = asyncio.create_task(self._run())
+
+    def start(self) -> None:
+        """Start heartbeat."""
+        PYVLXLOG.debug("Heartbeat start")
+        asyncio.run_coroutine_threadsafe(self._start(), self.pyvlx.loop)
+
+    @property
+    def stopped(self) -> bool:
+        """Return Heartbeat running state."""
+        return self.task is None
+
+    async def stop(self) -> None:
+        """Stop heartbeat."""
+        if self.task is not None:
+            self.task.cancel()
+            self.task = None
+            PYVLXLOG.debug("Heartbeat stopped")
+        else:
+            PYVLXLOG.debug("Heartbeat was not running")
+
+    async def pulse(self) -> None:
+        """Send get state request to API to keep the connection alive."""
+        PYVLXLOG.debug("Heartbeat pulse")
+        get_state = GetState(pyvlx=self.pyvlx)
+        await get_state.do_api_call()
+        if not get_state.success:
+            raise PyVLXException("Unable to send get state.")
+
+        # If nodes contain Blind or DualRollerShutter device, refresh orientation or upper/lower curtain positions because House Monitoring
+        # delivers wrong values for FP1, FP2 and FP3 parameter
+        for node in self.pyvlx.nodes:
+            if isinstance(node, (Blind, DualRollerShutter)) or self.load_all_states:
+                status_request = StatusRequest(self.pyvlx, node.node_id)
+                await status_request.do_api_call()
+                # give user requests a chance
+                await asyncio.sleep(0.5)

pyvlx/klf200gateway.py

@@ -0,0 +1,167 @@
+"""Module for basic klf200 gateway functions."""
+
+from typing import TYPE_CHECKING, Awaitable, Callable, List, Optional
+
+from .api import (
+    FactoryDefault, GetLocalTime, GetNetworkSetup, GetProtocolVersion,
+    GetState, GetVersion, HouseStatusMonitorDisable, HouseStatusMonitorEnable,
+    LeaveLearnState, PasswordEnter, Reboot, SetUTC)
+from .dataobjects import (
+    DtoLocalTime, DtoNetworkSetup, DtoProtocolVersion, DtoState, DtoVersion)
+from .exception import PyVLXException
+
+if TYPE_CHECKING:
+    from pyvlx import PyVLX
+
+CallbackType = Callable[["Klf200Gateway"], Awaitable[None]]
+
+
+class Klf200Gateway:
+    """Class for node abstraction."""
+
+    def __init__(self, pyvlx: "PyVLX"):
+        """Initialize Node object."""
+        self.pyvlx = pyvlx
+        self.state: Optional[DtoState] = None
+        self.network_setup: Optional[DtoNetworkSetup] = None
+        self.password: Optional[str] = None
+        self.time: Optional[DtoLocalTime] = None
+        self.protocol_version: Optional[DtoProtocolVersion] = None
+        self.version: Optional[DtoVersion] = None
+        self.device_updated_cbs: List[CallbackType] = []
+        self.house_status_monitor_enabled = False
+
+    def register_device_updated_cb(self, device_updated_cb: CallbackType) -> None:
+        """Register device updated callback."""
+        self.device_updated_cbs.append(device_updated_cb)
+
+    def unregister_device_updated_cb(self, device_updated_cb: CallbackType) -> None:
+        """Unregister device updated callback."""
+        self.device_updated_cbs.remove(device_updated_cb)
+
+    async def after_update(self) -> None:
+        """Execute callbacks after internal state has been changed."""
+        for device_updated_cb in self.device_updated_cbs:
+            # pylint: disable=not-callable
+            await device_updated_cb(self)
+
+    async def get_state(self) -> bool:
+        """Retrieve state from API."""
+        get_state = GetState(pyvlx=self.pyvlx)
+        await get_state.do_api_call()
+        if not get_state.success:
+            raise PyVLXException("Unable to retrieve state")
+        self.state = get_state.state
+        return get_state.success
+
+    async def get_network_setup(self) -> bool:
+        """Retrieve network setup from API."""
+        get_network_setup = GetNetworkSetup(pyvlx=self.pyvlx)
+        await get_network_setup.do_api_call()
+        if not get_network_setup.success:
+            raise PyVLXException("Unable to retrieve network setup")
+        self.network_setup = get_network_setup.networksetup
+        return get_network_setup.success
+
+    async def get_version(self) -> bool:
+        """Retrieve version from API."""
+        get_version = GetVersion(pyvlx=self.pyvlx)
+        await get_version.do_api_call()
+        if not get_version.success:
+            raise PyVLXException("Unable to retrieve version")
+        self.version = get_version.version
+        return get_version.success
+
+    async def get_protocol_version(self) -> bool:
+        """Retrieve protocol version from API."""
+        get_protocol_version = GetProtocolVersion(pyvlx=self.pyvlx)
+        await get_protocol_version.do_api_call()
+        if not get_protocol_version.success:
+            raise PyVLXException("Unable to retrieve protocol version")
+        self.protocol_version = get_protocol_version.protocolversion
+        return get_protocol_version.success
+
+    async def leave_learn_state(self) -> bool:
+        """Leave Learn state from API."""
+        leave_learn_state = LeaveLearnState(pyvlx=self.pyvlx)
+        await leave_learn_state.do_api_call()
+        if not leave_learn_state.success:
+            raise PyVLXException("Unable to leave learn state")
+        return leave_learn_state.success
+
+    async def set_utc(self) -> bool:
+        """Set UTC Clock."""
+        setutc = SetUTC(pyvlx=self.pyvlx)
+        await setutc.do_api_call()
+        if not setutc.success:
+            raise PyVLXException("Unable to set utc.")
+        return setutc.success
+
+    async def set_rtc_time_zone(self) -> None:
+        """Set the RTC Time Zone."""
+        # idontwant = setrtctimezone(pyvlx=self.pyvlx)
+        raise PyVLXException("KLF 200 RTC Timezone Set not implemented")
+        # return setrtctimezone.success
+
+    async def reboot(self) -> bool:
+        """Reboot gateway."""
+        reboot = Reboot(pyvlx=self.pyvlx)
+        await reboot.do_api_call()
+        if not reboot.success:
+            raise PyVLXException("Unable to reboot gateway.")
+        await self.pyvlx.disconnect()
+        return reboot.success
+
+    async def set_factory_default(self) -> bool:
+        """Set Gateway to Factory Default."""
+        factorydefault = FactoryDefault(pyvlx=self.pyvlx)
+        await factorydefault.do_api_call()
+        if not factorydefault.success:
+            raise PyVLXException("Unable to factory Default Reset gateway.")
+        return factorydefault.success
+
+    async def get_local_time(self) -> bool:
+        """Get local time from gateway."""
+        getlocaltime = GetLocalTime(pyvlx=self.pyvlx)
+        await getlocaltime.do_api_call()
+        if not getlocaltime.success:
+            raise PyVLXException("Unable to get local time.")
+        self.time = getlocaltime.localtime
+        return getlocaltime.success
+
+    async def password_enter(self, password: str) -> bool:
+        """Get enter Password for gateway."""
+        self.password = password
+        passwordenter = PasswordEnter(pyvlx=self.pyvlx, password=self.password)
+        await passwordenter.do_api_call()
+        if not passwordenter.success:
+            raise PyVLXException("Login to KLF 200 failed, check credentials")
+        return passwordenter.success
+
+    async def house_status_monitor_enable(self, pyvlx: "PyVLX") -> None:
+        """Enable house status monitor."""
+        status_monitor_enable = HouseStatusMonitorEnable(pyvlx=pyvlx)
+        await status_monitor_enable.do_api_call()
+        if not status_monitor_enable.success:
+            raise PyVLXException("Unable enable house status monitor.")
+        self.house_status_monitor_enabled = True
+
+    async def house_status_monitor_disable(self, pyvlx: "PyVLX", timeout: Optional[int] = None) -> None:
+        """Disable house status monitor."""
+        status_monitor_disable = HouseStatusMonitorDisable(pyvlx=pyvlx)
+        if timeout is not None:
+            status_monitor_disable.timeout_in_seconds = timeout
+        await status_monitor_disable.do_api_call()
+        if not status_monitor_disable.success:
+            raise PyVLXException("Unable disable house status monitor.")
+        self.house_status_monitor_enabled = False
+
+    def __str__(self) -> str:
+        """Return object as readable string."""
+        return '<{} state="{}" network_setup="{}"  version="{}"  protocol_version="{}"/>'.format(
+            type(self).__name__,
+            str(self.state),
+            str(self.network_setup),
+            str(self.version),
+            str(self.protocol_version),
+        )

pyvlx/lightening_device.py

@@ -0,0 +1,102 @@
+"""Module for lights."""
+from typing import TYPE_CHECKING, Optional
+
+from .api import CommandSend
+from .node import Node
+from .parameter import Intensity
+
+if TYPE_CHECKING:
+    from pyvlx import PyVLX
+
+
+class LighteningDevice(Node):
+    """Meta class for turning on device with one main parameter for intensity."""
+
+    def __init__(self, pyvlx: "PyVLX", node_id: int, name: str, serial_number: Optional[str]):
+        """Initialize turning on device.
+
+        Parameters:
+            * pyvlx: PyVLX object
+            * node_id: internal id for addressing nodes.
+                Provided by KLF 200 device
+            * name: node name
+            * serial_number: serial number of the node.
+
+        """
+        super().__init__(
+            pyvlx=pyvlx, node_id=node_id, name=name, serial_number=serial_number
+        )
+        self.intensity = Intensity()
+
+    async def set_intensity(self, intensity: Intensity, wait_for_completion: bool = True) -> None:
+        """Set light to desired intensity.
+
+        Parameters:
+            * intensity: Intensity object containing the target intensity.
+            * wait_for_completion: If set, function will return
+                after device has reached target intensity.
+
+        """
+        command = CommandSend(
+            pyvlx=self.pyvlx,
+            wait_for_completion=wait_for_completion,
+            node_id=self.node_id,
+            parameter=intensity,
+        )
+        await command.send()
+        await self.after_update()
+
+    async def turn_on(self, wait_for_completion: bool = True) -> None:
+        """Turn on light.
+
+        Parameters:
+            * wait_for_completion: If set, function will return
+                after device has reached target intensity.
+
+        """
+        await self.set_intensity(
+            intensity=Intensity(intensity_percent=0),
+            wait_for_completion=wait_for_completion,
+        )
+
+    async def turn_off(self, wait_for_completion: bool = True) -> None:
+        """Turn off light.
+
+        Parameters:
+            * wait_for_completion: If set, function will return
+                after device has reached target intensity.
+
+        """
+        await self.set_intensity(
+            intensity=Intensity(intensity_percent=100),
+            wait_for_completion=wait_for_completion,
+        )
+
+
+class Light(LighteningDevice):
+    """Light object."""
+
+    def __init__(self, pyvlx: "PyVLX", node_id: int, name: str, serial_number: Optional[str]):
+        """Initialize Light class.
+
+        Parameters:
+            * pyvlx: PyVLX object
+            * node_id: internal id for addressing nodes.
+                Provided by KLF 200 device
+            * name: node name
+            * serial_number: serial number of the node.
+
+        """
+        super().__init__(
+            pyvlx=pyvlx, node_id=node_id, name=name, serial_number=serial_number
+        )
+
+    def __str__(self) -> str:
+        """Return object as readable string."""
+        return (
+            '<{} name="{}" '
+            'node_id="{}" '
+            'serial_number="{}"/>'.format(
+                type(self).__name__, self.name, self.node_id, self.serial_number
+            )
+        )

pyvlx/log.py

@@ -0,0 +1,4 @@
+"""Module for global PyVLX logging object."""
+import logging
+
+PYVLXLOG = logging.getLogger("pyvlx")