pyvlx 0.2.27__py3-none-any.whl

pyvlx/parameter.py

@@ -0,0 +1,357 @@
+"""Module for Position class."""
+from typing import Optional
+
+from .exception import PyVLXException
+
+
+class Parameter:
+    """General object for storing parameters."""
+
+    UNKNOWN_VALUE = 0xF7FF  # F7 FF
+    CURRENT = 0xD200  # D2 00
+    MAX = 0xC800  # C8 00
+    MIN = 0x0000  # 00 00
+    ON = 0x0000  # 00 00
+    OFF = 0xC800  # C8 00
+    TARGET = 0xD100  # D1 00
+    IGNORE = 0xD400  # D4 00
+    DUAL_SHUTTER_CURTAINS = 0xD808  # D8 08
+
+    def __init__(self, raw: Optional[bytes] = None):
+        """Initialize Parameter class."""
+        self.raw = self.from_int(Position.UNKNOWN_VALUE)
+        if raw is not None:
+            self.raw = self.from_raw(raw)
+
+    def __bytes__(self) -> bytes:
+        """Convert object in byte representation."""
+        return self.raw
+
+    def from_parameter(self, parameter: "Parameter") -> None:
+        """Set internal raw state from parameter."""
+        if not isinstance(parameter, Parameter):
+            raise PyVLXException("parameter::from_parameter_wrong_object")
+        self.raw = parameter.raw
+
+    @staticmethod
+    def from_int(value: int) -> bytes:
+        """Create raw out of position value."""
+        if not isinstance(value, int):
+            raise PyVLXException("value_has_to_be_int")
+        if not Parameter.is_valid_int(value):
+            raise PyVLXException("value_out_of_range")
+        return bytes([value >> 8 & 255, value & 255])
+
+    @staticmethod
+    def to_int(raw: bytes) -> int:
+        """Create int position value out of raw."""
+        return raw[0] * 256 + raw[1]
+
+    @staticmethod
+    def is_valid_int(value: int) -> bool:
+        """Test if value can be rendered out of int."""
+        if 0 <= value <= Parameter.MAX:  # This includes ON and OFF
+            return True
+        valid_values = {
+            Parameter.UNKNOWN_VALUE,
+            Parameter.IGNORE,
+            Parameter.CURRENT,
+            Parameter.TARGET,
+            Parameter.DUAL_SHUTTER_CURTAINS,
+        }
+        if value in valid_values:
+            return True
+        return False
+
+    @staticmethod
+    def from_raw(raw: bytes) -> bytes:
+        """Test if raw packets are valid for initialization of Position."""
+        if not isinstance(raw, bytes):
+            raise PyVLXException("Position::raw_must_be_bytes")
+        if len(raw) != 2:
+            raise PyVLXException("Position::raw_must_be_two_bytes")
+        if (
+            raw != Position.from_int(Position.CURRENT)
+            and raw != Position.from_int(Position.IGNORE)
+            and raw != Position.from_int(Position.TARGET)
+            and raw != Position.from_int(Position.UNKNOWN_VALUE)
+            and Position.to_int(raw) > Position.MAX
+        ):
+            return Position.from_int(Position.UNKNOWN_VALUE)
+        return raw
+
+    @staticmethod
+    def from_percent(percent: int) -> bytes:
+        """Create raw value out of percent position."""
+        if not isinstance(percent, int):
+            raise PyVLXException("Position::percent_has_to_be_int")
+        if percent < 0:
+            raise PyVLXException("Position::percent_has_to_be_positive")
+        if percent > 100:
+            raise PyVLXException("Position::percent_out_of_range")
+        return bytes([percent * 2, 0])
+
+    @staticmethod
+    def to_percent(raw: bytes) -> int:
+        """Create percent position value out of raw."""
+        # The first byte has the vlue from 0 to 200. Ignoring the second one.
+        # Adding 0.5 allows a slight tolerance for devices (e.g. Velux SML) that
+        # do not return exactly 51200 as final position when closed.
+        return int(raw[0] / 2 + 0.5)
+
+    def __eq__(self, other: object) -> bool:
+        """Equal operator."""
+        if not isinstance(other, Parameter):
+            return NotImplemented
+        return self.raw == other.raw
+
+    def __str__(self) -> str:
+        """Return string representation of object."""
+        if self.raw == self.from_int(Position.UNKNOWN_VALUE):
+            return "UNKNOWN"
+        if self.raw == self.from_int(Position.CURRENT):
+            return "CURRENT"
+        if self.raw == self.from_int(Position.TARGET):
+            return "TARGET"
+        if self.raw == self.from_int(Position.IGNORE):
+            return "IGNORE"
+        if self.raw == self.from_int(Position.DUAL_SHUTTER_CURTAINS):
+            return "DUAL"
+        return "{} %".format(int(self.to_percent(self.raw)))
+
+
+class SwitchParameter(Parameter):
+    """Class for storing On or Off values."""
+
+    def __init__(
+        self, parameter: Optional[Parameter] = None, state: Optional[int] = None
+    ):
+        """Initialize Parameter class."""
+        super().__init__()
+        if parameter is not None:
+            self.from_parameter(parameter)
+        elif state is not None:
+            self.state = state
+
+    @property
+    def state(self) -> int:
+        """Position property."""
+        return self.to_int(self.raw)
+
+    @state.setter
+    def state(self, state: int) -> None:
+        """Setter of internal raw via state."""
+        self.raw = self.from_int(state)
+
+    def set_on(self) -> None:
+        """Set parameter to 'on' state."""
+        self.raw = self.from_int(Parameter.ON)
+
+    def set_off(self) -> None:
+        """Set parameter to 'off' state."""
+        self.raw = self.from_int(Parameter.OFF)
+
+    def is_on(self) -> bool:
+        """Return True if parameter is in 'on' state."""
+        return self.raw == self.from_int(Parameter.ON)
+
+    def is_off(self) -> bool:
+        """Return True if parameter is in 'off' state."""
+        return self.raw == self.from_int(Parameter.OFF)
+
+    def __str__(self) -> str:
+        """Return string representation of object."""
+        if self.raw == self.from_int(Parameter.ON):
+            return "ON"
+        if self.raw == self.from_int(Parameter.OFF):
+            return "OFF"
+        return "UNKNOWN"
+
+
+class SwitchParameterOn(SwitchParameter):
+    """Switch Parameter in switched 'on' state."""
+
+    def __init__(self) -> None:
+        """Initialize SwitchParameterOn class."""
+        super().__init__(state=Parameter.ON)
+
+
+class SwitchParameterOff(SwitchParameter):
+    """Switch Parameter in switched 'off' state."""
+
+    def __init__(self) -> None:
+        """Initialize SwitchParameterOff class."""
+        super().__init__(state=Parameter.OFF)
+
+
+class Position(Parameter):
+    """Class for storing a position."""
+
+    def __init__(
+        self,
+        parameter: Optional[Parameter] = None,
+        position: Optional[int] = None,
+        position_percent: Optional[int] = None,
+    ):
+        """Initialize Position class."""
+        super().__init__()
+        if parameter is not None:
+            self.from_parameter(parameter)
+        elif position is not None:
+            self.position = position
+        elif position_percent is not None:
+            self.position_percent = position_percent
+
+    @property
+    def known(self) -> bool:
+        """Known property, true if position is not in an unknown position."""
+        return self.raw != self.from_int(Position.UNKNOWN_VALUE)
+
+    @property
+    def open(self) -> bool:
+        """Return true if position is set to fully open."""
+        return self.raw == self.from_int(Position.MIN)
+
+    @property
+    def closed(self) -> bool:
+        """Return true if position is set to fully closed."""
+        # Consider closed even if raw is not exactly 51200 (tolerance for devices like Velux SML)
+        return self.to_percent(self.raw) == self.to_percent(self.from_int(Position.MAX))
+
+    @property
+    def position(self) -> int:
+        """Position property."""
+        return self.to_int(self.raw)
+
+    @position.setter
+    def position(self, position: int) -> None:
+        """Setter of internal raw via position."""
+        self.raw = self.from_int(position)
+
+    @property
+    def position_percent(self) -> int:
+        """Position percent property."""
+        # unclear why it returns a <property object> here
+        return int(self.to_percent(self.raw))
+
+    @position_percent.setter
+    def position_percent(self, position_percent: int) -> None:
+        """Setter of internal raw via percent position."""
+        self.raw = self.from_percent(percent=position_percent)
+
+
+class UnknownPosition(Position):
+    """Unknown position."""
+
+    def __init__(self) -> None:
+        """Initialize UnknownPosition class."""
+        super().__init__(position=Position.UNKNOWN_VALUE)
+
+
+class CurrentPosition(Position):
+    """Current position, used to stop devices."""
+
+    def __init__(self) -> None:
+        """Initialize CurrentPosition class."""
+        super().__init__(position=Position.CURRENT)
+
+
+class TargetPosition(Position):
+    """Class for using a target position."""
+
+    def __init__(self) -> None:
+        """Initialize TargetPosition class."""
+        super().__init__(position=Position.TARGET)
+
+
+class IgnorePosition(Position):
+    """The Ignore is used where a parameter in the frame is to be ignored."""
+
+    def __init__(self) -> None:
+        """Initialize CurrentPosition class."""
+        super().__init__(position=Position.IGNORE)
+
+
+class Intensity(Parameter):
+    """Class for storing an intensity."""
+
+    def __init__(
+        self,
+        parameter: Optional[Parameter] = None,
+        intensity: Optional[int] = None,
+        intensity_percent: Optional[int] = None,
+    ):
+        """Initialize Intensity class."""
+        super().__init__()
+        if parameter is not None:
+            self.from_parameter(parameter)
+        elif intensity is not None:
+            self.intensity = intensity
+        elif intensity_percent is not None:
+            self.intensity_percent = intensity_percent
+
+    @property
+    def known(self) -> bool:
+        """Known property, true if intensity is not in an unknown intensity."""
+        return self.raw != self.from_int(Intensity.UNKNOWN_VALUE)
+
+    @property
+    def on(self) -> bool:  # pylint: disable=invalid-name
+        """Return true if intensity is set to fully turn on."""
+        return self.raw == self.from_int(Intensity.MIN)
+
+    @property
+    def off(self) -> bool:
+        """Return true if intensity is set to fully turn off."""
+        return self.raw == bytes([self.MAX >> 8 & 255, self.MAX & 255])
+
+    @property
+    def intensity(self) -> int:
+        """Intensity property."""
+        return self.to_int(self.raw)
+
+    @intensity.setter
+    def intensity(self, intensity: int) -> None:
+        """Setter of internal raw via intensity."""
+        self.raw = self.from_int(intensity)
+
+    @property
+    def intensity_percent(self) -> int:
+        """Intensity percent property."""
+        # unclear why it returns a <property object> here
+        return int(self.to_percent(self.raw))
+
+    @intensity_percent.setter
+    def intensity_percent(self, intensity_percent: int) -> None:
+        """Setter of internal raw via percent intensity."""
+        self.raw = self.from_percent(percent=intensity_percent)
+
+    def __str__(self) -> str:
+        """Return string representation of object."""
+        if self.raw == self.from_int(Intensity.UNKNOWN_VALUE):
+            return "UNKNOWN"
+        return "{} %".format(self.intensity_percent)
+
+
+class UnknownIntensity(Intensity):
+    """Unknown intensity."""
+
+    def __init__(self) -> None:
+        """Initialize UnknownIntensity class."""
+        super().__init__(intensity=Intensity.UNKNOWN_VALUE)
+
+
+class CurrentIntensity(Intensity):
+    """Current intensity, used to stop devices."""
+
+    def __init__(self) -> None:
+        """Initialize CurrentIntensity class."""
+        super().__init__(intensity=Intensity.CURRENT)
+
+
+class DualRollerShutterPosition(Position):
+    """Position to be provided when addressing the upper or lower curtain of a dual roller shutter by using FP1 or FP2."""
+
+    def __init__(self) -> None:
+        """Initialize CurrentPosition class."""
+        super().__init__(position=Position.DUAL_SHUTTER_CURTAINS)

pyvlx/pyvlx.py

@@ -0,0 +1,124 @@
+"""
+Module for PyVLX object.
+
+PyVLX is an asynchronous library for connecting to
+a VELUX KLF 200 device for controlling window openers
+and roller shutters.
+"""
+import asyncio
+from typing import Optional
+
+from .api import get_limitation
+from .api.frames import FrameBase
+from .config import Config
+from .connection import Connection
+from .exception import PyVLXException
+from .heartbeat import Heartbeat
+from .klf200gateway import Klf200Gateway
+from .log import PYVLXLOG
+from .node_updater import NodeUpdater
+from .nodes import Nodes
+from .scenes import Scenes
+
+
+class PyVLX:
+    """Class for PyVLX."""
+
+    def __init__(
+        self,
+        path: Optional[str] = None,
+        host: Optional[str] = None,
+        password: Optional[str] = None,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+        heartbeat_interval: int = 30,
+        heartbeat_load_all_states: bool = True,
+    ):
+        """Initialize PyVLX class."""
+        self.loop = loop or asyncio.get_event_loop()
+        self.config = Config(self, path, host, password)
+        self.connection = Connection(loop=self.loop, config=self.config)
+        self.heartbeat = Heartbeat(
+            pyvlx=self,
+            interval=heartbeat_interval,
+            load_all_states=heartbeat_load_all_states,
+        )
+        self.node_updater = NodeUpdater(pyvlx=self)
+        self.nodes = Nodes(self)
+        self.connection.register_frame_received_cb(self.node_updater.process_frame)
+
+        self.scenes = Scenes(self)
+        self.version = None
+        self.protocol_version = None
+        self.klf200 = Klf200Gateway(pyvlx=self)
+        self.api_call_semaphore = asyncio.Semaphore(1)  # Limit parallel commands
+
+    async def connect(self) -> None:
+        """Connect to KLF 200."""
+        PYVLXLOG.debug("Connecting to KLF 200")
+        await self.connection.connect()
+        assert self.config.password is not None
+        await self.klf200.password_enter(password=self.config.password)
+        await self.klf200.get_version()
+        await self.klf200.get_protocol_version()
+        PYVLXLOG.debug(
+            "Connected to: %s,  %s",
+            str(self.klf200.version),
+            str(self.klf200.protocol_version),
+        )
+        await self.klf200.house_status_monitor_disable(pyvlx=self)
+        await self.klf200.get_state()
+        await self.klf200.set_utc()
+        await self.klf200.get_network_setup()
+        await self.klf200.house_status_monitor_enable(pyvlx=self)
+        self.heartbeat.start()
+
+    async def reboot_gateway(self) -> None:
+        """For Compatibility: Reboot the KLF 200."""
+        if not self.get_connected():
+            PYVLXLOG.warning("KLF 200 reboot initiated, but gateway is not connected")
+        else:
+            PYVLXLOG.warning("KLF 200 reboot initiated")
+            await self.klf200.reboot()
+
+    def get_connected(self) -> bool:
+        """Return whether the gateway is currently connected."""
+        return self.connection.connected
+
+    async def check_connected(self) -> None:
+        """Check we're connected, and if not, connect."""
+        if not self.connection.connected:
+            await self.connect()
+
+    async def send_frame(self, frame: FrameBase) -> None:
+        """Send frame to API via connection."""
+        await self.check_connected()
+        self.connection.write(frame)
+
+    async def disconnect(self) -> None:
+        """Disconnect from KLF 200."""
+        await self.heartbeat.stop()
+        if self.connection.connected:
+            try:
+                # If the connection will be closed while house status monitor is enabled, a reconnection will fail on SSL handshake.
+                if self.klf200.house_status_monitor_enabled:
+                    await self.klf200.house_status_monitor_disable(pyvlx=self, timeout=5)
+                # Reboot KLF200 when disconnecting to avoid unresponsive KLF200.
+                await self.klf200.reboot()
+            except (OSError, PyVLXException):
+                PYVLXLOG.exception("Error during disconnect preparations")
+            self.connection.disconnect()
+            if self.connection.tasks:
+                await asyncio.gather(*self.connection.tasks)  # Wait for all tasks to finish
+
+    async def load_nodes(self, node_id: Optional[int] = None) -> None:
+        """Load devices from KLF 200, if no node_id is specified all nodes are loaded."""
+        await self.nodes.load(node_id)
+
+    async def load_scenes(self) -> None:
+        """Load scenes from KLF 200."""
+        await self.scenes.load()
+
+    async def get_limitation(self, node_id: int) -> None:
+        """Return limitation."""
+        limit = get_limitation.GetLimitation(self, node_id)
+        await limit.do_api_call()

pyvlx/scene.py

@@ -0,0 +1,53 @@
+"""Module for scene."""
+from typing import TYPE_CHECKING, Any
+
+from .api import ActivateScene
+from .exception import PyVLXException
+
+if TYPE_CHECKING:
+    from pyvlx import PyVLX
+
+
+class Scene:
+    """Object for scene."""
+
+    def __init__(self, pyvlx: "PyVLX", scene_id: int, name: str):
+        """Initialize Scene object.
+
+        Parameters:
+            * pyvlx: PyVLX object
+            * scene_id: internal id for addressing scenes.
+                Provided by KLF 200 device
+            * name: scene name
+
+        """
+        self.pyvlx = pyvlx
+        self.scene_id = scene_id
+        self.name = name
+
+    async def run(self, wait_for_completion: bool = True) -> None:
+        """Run scene.
+
+        Parameters:
+            * wait_for_completion: If set, function will return
+                after device has reached target position.
+
+        """
+        activate_scene = ActivateScene(
+            pyvlx=self.pyvlx,
+            wait_for_completion=wait_for_completion,
+            scene_id=self.scene_id,
+        )
+        await activate_scene.do_api_call()
+        if not activate_scene.success:
+            raise PyVLXException("Unable to activate scene")
+
+    def __str__(self) -> str:
+        """Return object as readable string."""
+        return '<{} name="{}" id="{}"/>'.format(
+            type(self).__name__, self.name, self.scene_id
+        )
+
+    def __eq__(self, other: Any) -> bool:
+        """Equal operator."""
+        return self.__dict__ == other.__dict__

pyvlx/scenes.py

@@ -0,0 +1,60 @@
+"""Module for storing and accessing scene list."""
+from typing import TYPE_CHECKING, Iterator, List, Union
+
+from .api import GetSceneList
+from .exception import PyVLXException
+from .scene import Scene
+
+if TYPE_CHECKING:
+    from pyvlx import PyVLX
+
+
+class Scenes:
+    """Class for storing and accessing ."""
+
+    def __init__(self, pyvlx: "PyVLX"):
+        """Initialize Scenes class."""
+        self.pyvlx = pyvlx
+        self.__scenes: List[Scene] = []
+
+    def __iter__(self) -> Iterator[Scene]:
+        """Iterate."""
+        yield from self.__scenes
+
+    def __getitem__(self, key: Union[str, int]) -> Scene:
+        """Return scene by name or by index."""
+        if isinstance(key, int):
+            for scene in self.__scenes:
+                if scene.scene_id == key:
+                    return scene
+        for scene in self.__scenes:
+            if scene.name == key:
+                return scene
+        raise KeyError
+
+    def __len__(self) -> int:
+        """Return number of scenes."""
+        return len(self.__scenes)
+
+    def add(self, scene: Scene) -> None:
+        """Add scene, replace existing scene if scene with scene_id is present."""
+        if not isinstance(scene, Scene):
+            raise TypeError()
+        for i, j in enumerate(self.__scenes):
+            if j.scene_id == scene.scene_id:
+                self.__scenes[i] = scene
+                return
+        self.__scenes.append(scene)
+
+    def clear(self) -> None:
+        """Clear internal scenes array."""
+        self.__scenes = []
+
+    async def load(self) -> None:
+        """Load scenes from KLF 200."""
+        get_scene_list = GetSceneList(pyvlx=self.pyvlx)
+        await get_scene_list.do_api_call()
+        if not get_scene_list.success:
+            raise PyVLXException("Unable to retrieve scene information")
+        for scene in get_scene_list.scenes:
+            self.add(Scene(pyvlx=self.pyvlx, scene_id=scene[0], name=scene[1]))

pyvlx/slip.py

@@ -0,0 +1,48 @@
+"""Module for Serial Line Internet Protocol (SLIP)."""
+
+from typing import Optional, Tuple
+
+SLIP_END = 0xC0
+SLIP_ESC = 0xDB
+SLIP_ESC_END = 0xDC
+SLIP_ESC_ESC = 0xDD
+
+
+def is_slip(raw: bytes) -> bool:
+    """Check if raw is a SLIP packet."""
+    if len(raw) < 2:
+        return False
+    return raw[0] == SLIP_END and SLIP_END in raw[1:]
+
+
+def decode(raw: bytes) -> bytes:
+    """Decode SLIP message."""
+    return raw.replace(bytes([SLIP_ESC, SLIP_ESC_END]), bytes([SLIP_END])).replace(
+        bytes([SLIP_ESC, SLIP_ESC_ESC]), bytes([SLIP_ESC])
+    )
+
+
+def encode(raw: bytes) -> bytes:
+    """Encode SLIP message."""
+    return raw.replace(bytes([SLIP_ESC]), bytes([SLIP_ESC, SLIP_ESC_ESC])).replace(
+        bytes([SLIP_END]), bytes([SLIP_ESC, SLIP_ESC_END])
+    )
+
+
+def get_next_slip(raw: bytes) -> Tuple[Optional[bytes], bytes]:
+    """
+    Get the next slip packet from raw data.
+
+    Returns the extracted packet plus the raw data with the remaining data stream.
+    """
+    if not is_slip(raw):
+        return None, raw
+    length = raw[1:].index(SLIP_END)
+    slip_packet = decode(raw[1 : length + 1])
+    new_raw = raw[length + 2 :]
+    return slip_packet, new_raw
+
+
+def slip_pack(raw: bytes) -> bytes:
+    """Pack raw message to complete slip message."""
+    return bytes([SLIP_END]) + encode(raw) + bytes([SLIP_END])

pyvlx/string_helper.py

@@ -0,0 +1,20 @@
+"""Module for string encoding, decoding."""
+from .exception import PyVLXException
+
+
+def string_to_bytes(string: str, size: int) -> bytes:
+    """Convert string to bytes add padding."""
+    if len(string) > size:
+        raise PyVLXException("string_to_bytes::string_to_large")
+    encoded = bytes(string, encoding="utf-8")
+    return encoded + bytes(size - len(encoded))
+
+
+def bytes_to_string(raw: bytes) -> str:
+    """Convert bytes to string."""
+    ret = bytes()
+    for byte in raw:
+        if byte == 0x00:
+            return ret.decode("utf-8")
+        ret += bytes([byte])
+    return ret.decode("utf-8")