velbus-aio 2021.8.7__py3-none-any.whl → 2025.11.0__py3-none-any.whl

velbusaio/protocol.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import asyncio
+import binascii
+import logging
+import time
+import typing as t
+from asyncio import transports
+
+import backoff
+
+from velbusaio.const import MAXIMUM_MESSAGE_SIZE, MINIMUM_MESSAGE_SIZE, SLEEP_TIME
+from velbusaio.raw_message import RawMessage
+from velbusaio.raw_message import create as create_message_info
+
+
+def _on_write_backoff(details):
+    logging.debug(
+        f"Transport is not open, waiting {details.wait} seconds after {details.tries}"
+    )
+
+
+class VelbusProtocol(asyncio.BufferedProtocol):
+    """Handles the Velbus protocol
+
+    This class is expected to be wrapped inside a VelbusConnection class object which will maintain the socket
+    and handle auto-reconnects"""
+
+    def __init__(
+        self,
+        message_received_callback: t.Callable[[RawMessage], t.Awaitable[None]],
+        connection_lost_callback=None,
+    ) -> None:
+        super().__init__()
+        self._log = logging.getLogger("velbus-protocol")
+        self._message_received_callback = message_received_callback
+        self._connection_lost_callback = connection_lost_callback
+
+        # everything for reading from Velbus
+        self._buffer = bytearray(MAXIMUM_MESSAGE_SIZE)
+        self._buffer_view = memoryview(self._buffer)
+        self._buffer_pos = 0
+
+        self._serial_buf = b""
+        self.transport = None
+
+        # everything for writing to Velbus
+        self._send_queue = asyncio.Queue()
+        self._write_transport_lock = asyncio.Lock()
+        self._writer_task = None
+        self._restart_writer = False
+        self.restart_writing()
+
+        self._closing = False
+
+    def connection_made(self, transport: transports.BaseTransport) -> None:
+        self.transport = transport
+        self._log.info("Connection established to Velbus")
+
+        self._restart_writer = True
+        self.restart_writing()
+
+    async def pause_writing(self) -> None:
+        """Pause writing."""
+        self._restart_writer = False
+        if self._writer_task:
+            self._send_queue.put_nowait(None)
+        await asyncio.sleep(0.1)
+
+    def restart_writing(self) -> None:
+        """Resume writing."""
+        if self._restart_writer and not self._write_transport_lock.locked():
+            self._writer_task = asyncio.ensure_future(
+                self._get_message_from_send_queue()
+            )
+            self._writer_task.add_done_callback(lambda _future: self.restart_writing())
+
+    def close(self) -> None:
+        self._closing = True
+        self._restart_writer = False
+        if self.transport:
+            self.transport.close()
+
+    def connection_lost(self, exc: t.Optional[Exception]) -> None:
+        self.transport = None
+
+        if self._closing:
+            return  # Connection loss was expected, nothing to do here...
+        elif exc is None:
+            self._log.warning("EOF received from Velbus")
+        else:
+            self._log.error(f"Velbus connection lost: {exc!r}")
+
+        self.transport = None
+        asyncio.ensure_future(self.pause_writing())
+        if self._connection_lost_callback:
+            self._connection_lost_callback(exc)
+
+    # Everything read-related
+
+    def get_buffer(self, sizehint: int) -> memoryview:
+        return self._buffer_view[self._buffer_pos :]
+
+    def data_received(self, data: bytes) -> None:
+        """Receive data from the Streaming protocol.
+        Called when asyncio.Protocol detects received data from serial port.
+        """
+        self._serial_buf += data
+        self._log.debug(
+            "Received {nbytes} bytes from Velbus: {data_hex}".format(
+                nbytes=len(data),
+                data_hex=binascii.hexlify(self._serial_buf[: len(data)], " "),
+            )
+        )
+        _recheck = True
+
+        while len(self._serial_buf) > MINIMUM_MESSAGE_SIZE and _recheck:
+            # try to construct a Velbus message from the buffer
+
+            _remaining_buf = self._serial_buf[MAXIMUM_MESSAGE_SIZE:]
+            msg, remaining_data = create_message_info(
+                bytearray(self._serial_buf[:MAXIMUM_MESSAGE_SIZE])
+            )
+
+            if msg is not None:
+                asyncio.ensure_future(self._process_message(msg))
+                _recheck = True
+            else:
+                _recheck = False
+            self._serial_buf = bytes(remaining_data) + _remaining_buf
+
+    def buffer_updated(self, nbytes: int) -> None:
+        """Receive data from the Buffered Streaming protocol.
+        Called when asyncio.BufferedProtocol detects received data from network.
+        """
+        self._buffer_pos += nbytes
+        # self._log.debug(
+        #    "Received {nbytes} bytes from Velbus: {data_hex}".format(
+        #        nbytes=nbytes,
+        #        data_hex=binascii.hexlify(
+        #            self._buffer[self._buffer_pos - nbytes : self._buffer_pos], " "
+        #        ),
+        #    )
+        # )
+
+        if self._buffer_pos > MINIMUM_MESSAGE_SIZE:
+            # try to construct a Velbus message from the buffer
+            msg, remaining_data = create_message_info(self._buffer)
+
+            if msg is not None:
+                asyncio.ensure_future(self._process_message(msg))
+
+            self._new_buffer(remaining_data)
+
+    def _new_buffer(self, remaining_data=None) -> None:
+        new_buffer = bytearray(MAXIMUM_MESSAGE_SIZE)
+        if remaining_data:
+            new_buffer[: len(remaining_data)] = remaining_data
+
+        self._buffer = new_buffer
+        self._buffer_pos = len(remaining_data) if remaining_data else 0
+        self._buffer_view = memoryview(self._buffer)
+
+    async def _process_message(self, msg: RawMessage) -> None:
+        # self._log.debug(f"RX: {msg}")
+        await self._message_received_callback(msg)
+
+    # Everything write-related
+
+    async def write_auth_key(self, authkey: str) -> None:
+        self._log.debug("TX: authentication key")
+        if not self.transport.is_closing():
+            self.transport.write(authkey.encode("utf-8"))
+
+    async def send_message(self, msg: RawMessage) -> None:
+        self._send_queue.put_nowait(msg)
+
+    async def _get_message_from_send_queue(self) -> None:
+        self._log.debug("Starting Velbus write message from send queue")
+        self._log.debug("Acquiring write lock")
+        await self._write_transport_lock.acquire()
+        while self._restart_writer:
+            # wait for an item from the queue
+            msg_info: RawMessage | None = await self._send_queue.get()
+            if msg_info is None:
+                self._restart_writer = False
+                return
+            message_sent = False
+            try:
+                start_time = time.perf_counter()
+                while not message_sent:
+                    message_sent = await self._write_message(msg_info)
+                send_time = time.perf_counter() - start_time
+
+                self._send_queue.task_done()  # indicate that the item of the queue has been processed
+
+                queue_sleep_time = self._calculate_queue_sleep_time(msg_info, send_time)
+                await asyncio.sleep(queue_sleep_time)
+
+            except (asyncio.CancelledError, GeneratorExit) as exc:
+                if not self._closing:
+                    self._log.error(f"Stopping Velbus writer due to {exc!r}")
+                self._restart_writer = False
+            except Exception as exc:
+                self._log.error(f"Restarting Velbus writer due to {exc!r}")
+                self._restart_writer = True
+        if self._write_transport_lock.locked():
+            self._write_transport_lock.release()
+        self._log.debug("Ending Velbus write message from send queue")
+
+    @staticmethod
+    def _calculate_queue_sleep_time(msg_info, send_time):
+        sleep_time = SLEEP_TIME
+
+        if msg_info.rtr:
+            sleep_time = SLEEP_TIME  # this is a scan command. We could be quicker?
+
+        if msg_info.command == 0xEF:
+            # 'channel name request' command provokes in worst case 99 answer packets from VMBGPOD
+            sleep_time = SLEEP_TIME * 33  # TODO make this adaptable on module_type
+
+        if send_time > sleep_time:
+            return 0  # no need to wait, we are already late
+        else:
+            return sleep_time - send_time
+
+    @backoff.on_predicate(
+        backoff.expo,
+        lambda is_sent: not is_sent,
+        max_tries=10,
+        on_backoff=_on_write_backoff,
+    )
+    async def _write_message(self, msg: RawMessage) -> bool:
+        self._log.debug(f"TX: {msg}")
+        if not self.transport.is_closing():
+            self.transport.write(msg.to_bytes())
+            return True
+        else:
+            return False
+
+    async def wait_on_all_messages_sent_async(self) -> None:
+        self._log.debug("Waiting on all messages sent")
+        await self._send_queue.join()

velbusaio/raw_message.py

@@ -0,0 +1,149 @@
+import binascii
+import logging
+from typing import NamedTuple, Optional, Tuple
+
+from velbusaio.const import (
+    END_BYTE,
+    HEADER_LENGTH,
+    MAXIMUM_MESSAGE_SIZE,
+    MINIMUM_MESSAGE_SIZE,
+    NO_RTR,
+    PRIORITIES,
+    RTR,
+    START_BYTE,
+    TAIL_LENGTH,
+)
+from velbusaio.util import checksum
+from velbusaio.util import checksum as calculate_checksum
+
+
+class RawMessage(NamedTuple):
+    priority: int
+    address: int
+    rtr: bool
+    data: bytes
+
+    @property
+    def command(self) -> Optional[int]:
+        return self.data[0] if len(self.data) > 0 else None
+
+    @property
+    def data_only(self) -> Optional[bytes]:
+        return self.data[1:] if len(self.data) > 1 else None
+
+    def to_bytes(self) -> bytes:
+        # create header:
+        header_bytes = bytes(
+            [
+                START_BYTE,
+                self.priority,
+                self.address,
+                (RTR if self.rtr else NO_RTR) | len(self.data),
+            ]
+        )
+
+        tail_bytes = bytes([checksum(header_bytes + self.data), END_BYTE])
+
+        return header_bytes + self.data + tail_bytes
+
+    def __repr__(self) -> str:
+        return (
+            f"RawMessage(priority={self.priority:02x}, address={self.address:02x},"
+            f" rtr={self.rtr!r}, command={self.command},"
+            f" data={binascii.hexlify(self.data, ' ')})"
+        )
+
+
+def create(rawmessage: bytearray) -> Tuple[Optional[RawMessage], bytearray]:
+    rawmessage = _trim_buffer_garbage(rawmessage)
+
+    while True:
+        if len(rawmessage) < MINIMUM_MESSAGE_SIZE:
+            logging.debug("Buffer does not yet contain a full message")
+            return None, rawmessage
+
+        try:
+            return _parse(rawmessage)
+        except ParseError:
+            logging.error(
+                f"Could not parse the message {binascii.hexlify(rawmessage)}. Truncating invalid data."
+            )
+            rawmessage = _trim_buffer_garbage(
+                rawmessage[1:]
+            )  # try to find possible start of a message
+
+
+class ParseError(Exception):
+    pass
+
+
+def _parse(rawmessage: bytearray) -> Tuple[Optional[RawMessage], bytearray]:
+    if len(rawmessage) < MINIMUM_MESSAGE_SIZE or len(rawmessage) > MAXIMUM_MESSAGE_SIZE:
+        raise ValueError("Received a raw message with an illegal lemgth")
+    if rawmessage[0] != START_BYTE:
+        raise ValueError("Received a raw message with the wrong startbyte")
+
+    priority = rawmessage[1]
+    if priority not in PRIORITIES:
+        raise ParseError(
+            f"Invalid priority byte: {priority:02x} in {binascii.hexlify(rawmessage)}"
+        )
+
+    address = rawmessage[2]
+
+    rtr = rawmessage[3] & RTR == RTR  # high nibble of the 4th byte
+    data_size = rawmessage[3] & 0x0F  # low nibble of the 4th byte
+
+    if HEADER_LENGTH + data_size + TAIL_LENGTH > len(rawmessage):
+        return (
+            None,
+            rawmessage,
+        )  # the full package is not available in the current buffer
+
+    if rawmessage[HEADER_LENGTH + data_size + 1] != END_BYTE:
+        raise ParseError(f"Invalid end byte in {binascii.hexlify(rawmessage)}")
+
+    checksum = rawmessage[HEADER_LENGTH + data_size]
+
+    calculated_checksum = calculate_checksum(rawmessage[: HEADER_LENGTH + data_size])
+
+    if calculated_checksum != checksum:
+        raise ParseError(
+            f"Invalid checksum: expected {calculated_checksum:02x},"
+            f" but got {checksum:02x} in {binascii.hexlify(rawmessage)}"
+        )
+
+    data = bytes(rawmessage[HEADER_LENGTH : HEADER_LENGTH + data_size])
+
+    return (
+        RawMessage(priority, address, rtr, data),
+        rawmessage[HEADER_LENGTH + data_size + TAIL_LENGTH :],
+    )
+
+
+def _trim_buffer_garbage(rawmessage: bytearray) -> bytearray:
+    """
+    Remove leading garbage bytes from a byte stream.
+    """
+
+    # A proper message byte stream begins with 0x0F.
+    if rawmessage and rawmessage[0] != START_BYTE:
+        start_index = rawmessage.find(START_BYTE)
+        if start_index > -1:
+            #           logging.debug(
+            #                "Trimming leading garbage from buffer content: {buffer} becomes {new_buffer}".format(
+            #                    buffer=binascii.hexlify(rawmessage),
+            #                    new_buffer=binascii.hexlify(rawmessage[start_index:]),
+            #                )
+            #            )
+            return rawmessage[start_index:]
+        else:
+            logging.debug(
+                "Trimming whole buffer as it does not contain the start byte: {buffer}".format(
+                    buffer=binascii.hexlify(rawmessage)
+                )
+            )
+            return []
+
+    else:
+        return rawmessage

velbusaio/util.py

@@ -0,0 +1,55 @@
+"""
+Some common utils.
+"""
+
+from typing import Union
+
+from velbusaio.const import MAXIMUM_MESSAGE_SIZE, MINIMUM_MESSAGE_SIZE
+
+
+# Copyright (c) 2017 Thomas Delaet
+# Copied from python-velbus (https://github.com/thomasdelaet/python-velbus)
+def checksum(data: Union[bytes, bytearray]) -> int:
+    if len(data) < MINIMUM_MESSAGE_SIZE - 2:
+        raise ValueError("The message is shorter then expected")
+    if len(data) > MAXIMUM_MESSAGE_SIZE - 2:
+        raise ValueError("The message is longer then expected")
+    __checksum = 0
+    for data_byte in data:
+        __checksum += data_byte
+    __checksum = -(__checksum % 256) + 256
+    return __checksum % 256
+
+
+class VelbusException(Exception):
+    """Velbus Exception."""
+
+    def __init__(self, value):
+        Exception.__init__(self)
+        self.value = value
+
+    def __str__(self) -> str:
+        return repr(self.value)
+
+
+class MessageParseException(Exception):
+    pass
+
+
+class BitSet:
+    def __init__(self, value: int):
+        self._value = value
+
+    def __getitem__(self, idx: int) -> bool:
+        if idx > 8 or idx <= 0:
+            raise ValueError("The bitSet id is not within expected range 0 < id < 8")
+        return bool((1 << idx) & self._value)
+
+    def __setitem__(self, idx: int, value: bool) -> None:
+        if idx > 8 or idx <= 0:
+            raise ValueError("The bitSet id is not within expected range 0 < id < 8")
+        mask = (0xFF ^ (1 << idx)) & self._value
+        self._value = mask & (value << idx)
+
+    def __len__(self) -> int:
+        return 8  # a bitset represents one byte

velbusaio/vlp_reader.py

@@ -0,0 +1,249 @@
+import importlib.resources
+import json
+import logging
+import sys
+
+from aiofile import async_open
+from bs4 import BeautifulSoup
+
+from velbusaio.command_registry import MODULE_DIRECTORY
+from velbusaio.helpers import h2
+
+
+class VlpFile:
+
+    def __init__(self, file_path) -> None:
+        self._file_path = file_path
+        self._modules = []
+        self._log = logging.getLogger("velbus-vlpFile")
+
+    def get(self) -> dict:
+        return self._modules
+
+    async def read(self) -> None:
+        async with async_open(self._file_path) as file:
+            xml_content = await file.read()
+        _soup = BeautifulSoup(xml_content, "xml")
+        for module in _soup.find_all("Module"):
+            mod = vlpModule(
+                module.find("Caption").get_text(),
+                module["address"],
+                module["build"],
+                module["serial"],
+                module["type"],
+                module.find("Memory").get_text(),
+            )
+            self._modules.append(mod)
+            await mod.parse()
+        self._modules.sort(key=lambda mod: mod.get_decimal_addr())
+
+    def dump(self) -> None:
+        for m in self._modules:
+            print(f"Module {m.get_decimal_addr()}: {m._name}, type {m._type_id}")
+            for key, value in m._channels.items():
+                name = value["Name"]
+                print(f"  {key} => {name}")
+
+
+class vlpModule:
+
+    def __init__(self, name, addresses, build, serial, type, memory) -> None:
+        self._name = name
+        self._addresses = addresses
+        self._build = build
+        self._serial = serial
+        self._type = type
+        self._memory = memory
+        self._spec = {}
+        self._channels = {}
+        self._type_id = next(
+            (key for key, value in MODULE_DIRECTORY.items() if value == self._type),
+            None,
+        )
+        self._log = logging.getLogger("velbus-vlpFile")
+        self._log.info(
+            f"=> Created vlpModule address: {self._addresses} type: {self._type} ({self._type_id})"
+        )
+
+    def get(self) -> None:
+        print(self._channels)
+        print(self)
+
+    def get_addr(self) -> str:
+        return self._addresses
+
+    def get_name(self) -> str:
+        return self._name
+
+    def get_type(self) -> int | None:
+        return self._type_id
+
+    def get_serial(self) -> str:
+        return self._serial
+
+    def get_memory(self) -> str:
+        return self._memory
+
+    def get_build(self) -> str:
+        return self._build
+
+    def get_channels(self) -> dict:
+        return self._channels
+
+    def __str__(self):
+        return f"vlpModule(name={self._name}, addresses={self._addresses}, build={self._build}, serial={self._serial}, type={self._type})"
+
+    def get_decimal_addr(
+        self,
+    ) -> int:  # lgor: get the numeric value of primary module address
+        addr = self._addresses.split(",")[0]
+        return int(addr, 16)
+
+    async def parse(self) -> None:
+        await self._load_module_spec()
+
+        if "Memory" not in self._spec:
+            self._log.debug("  => no Memory locations found")
+            return None
+
+        # channel names
+        self._channels = self._spec.get("Channels", {})
+        for addr, chan in self._channels.items():
+            self._log.debug(f" => Processing channel {addr}:")
+            if ("Editable" in chan) and (chan["Editable"] == "yes"):
+                self._log.debug(f"  => channel {addr} is editable, getting name")
+                name = self._get_channel_name(int(addr))
+                if name:
+                    self._log.debug(f"  => got name '{name}' for channel {addr}")
+                    self._channels[addr]["Name"] = name
+                    self._channels[addr]["_is_loaded"] = True
+
+        # extra
+        self._load_extra_data()
+
+    def _load_extra_data(self) -> None:
+        self._log.debug(" => Getting extra data")
+        if "Extras" not in self._spec["Memory"]:
+            self._log.debug("  => no Extra Memory locations found")
+            return None
+        for addr, extra in self._spec["Memory"]["Extras"].items():
+            byte_data = bytes.fromhex(self._read_from_memory(addr))
+            self._log.debug(
+                f"  => got extra data {byte_data.hex().upper()} from address {addr}"
+            )
+            if "Translate" in extra:
+                translation_found = False
+                for translate_key, translate_value in extra["Translate"].items():
+                    if translate_key.startswith("%"):
+                        # Binary pattern matching
+                        if self._match_binary_pattern(translate_key, byte_data):
+                            self._log.debug(
+                                f"   => Binary pattern {translate_key} matched, value: {translate_value}"
+                            )
+                            self._channels[translate_value["Channel"]][
+                                translate_value["SubName"]
+                            ] = translate_value["Value"]
+                            translation_found = True
+                    else:
+                        # Direct value matching (existing behavior for integer keys)
+                        try:
+                            int_key = int(translate_key)
+                            if len(byte_data) > 0 and byte_data[0] == int_key:
+                                self._log.debug(
+                                    f"   => Direct match for value {int_key}: {translate_value}"
+                                )
+                                translation_found = True
+                        except ValueError:
+                            # Not an integer key, skip
+                            continue
+                if not translation_found:
+                    self._log.error(
+                        f" => No translation found for data {byte_data.hex().upper()}"
+                    )
+
+    def _match_binary_pattern(self, pattern: str, byte_data: bytes) -> bool:
+        """
+        Match a binary pattern like %......00 against byte data.
+        % indicates binary pattern
+        . means don't care bit
+        0/1 are specific bits that must match
+        """
+        if not pattern.startswith("%"):
+            return False
+
+        # Remove the % prefix
+        binary_pattern = pattern[1:]
+
+        # Convert byte_data to binary string (without '0b' prefix)
+        if len(byte_data) == 0:
+            return False
+
+        # Take the first byte for pattern matching
+        byte_value = byte_data[0]
+        binary_data = format(byte_value, "08b")
+
+        # Check if pattern length matches
+        if len(binary_pattern) != len(binary_data):
+            return False
+
+        # Check each bit position
+        for i, (pattern_bit, data_bit) in enumerate(zip(binary_pattern, binary_data)):
+            if pattern_bit == ".":
+                # Don't care bit, skip
+                continue
+            elif pattern_bit != data_bit:
+                # Specific bit must match
+                return False
+
+        return True
+
+    def _get_channel_name(self, chan: int) -> str | None:
+        if "Channels" not in self._spec["Memory"]:
+            self._log.debug("  => no Channels Memory locations found")
+            return None
+        dchan = format(chan, "02d")
+        if dchan not in self._spec["Memory"]["Channels"]:
+            self._log.debug(f"  => no chan {chan} Memory locations found")
+            return None
+        byte_data = bytes.fromhex(
+            self._read_from_memory(self._spec["Memory"]["Channels"][dchan]).replace(
+                "FF", ""
+            )
+        )
+        try:
+            name = byte_data.decode("ascii")
+        except UnicodeDecodeError as e:
+            self._log.error(f"  => UnicodeDecodeError: {e}")
+            name = byte_data
+        finally:
+            return name
+
+    async def _load_module_spec(self) -> None:
+        self._log.debug(f" => Load module spec for {self._type_id}")
+        if sys.version_info >= (3, 13):
+            with importlib.resources.path(
+                __name__, f"module_spec/{h2(self._type_id)}.json"
+            ) as fspath:
+                async with async_open(fspath) as protocol_file:
+                    self._spec = json.loads(await protocol_file.read())
+        else:
+            async with async_open(
+                str(
+                    importlib.resources.files(__name__.split(".")[0]).joinpath(
+                        f"module_spec/{h2(self._type_id)}.json"
+                    )
+                )
+            ) as protocol_file:
+                self._spec = json.loads(await protocol_file.read())
+
+    def _read_from_memory(self, address_range) -> str | None:
+        # its a single address
+        if "-" not in address_range:
+            start = int(address_range, 16) * 2
+            end = (int(address_range, 16) + 1) * 2
+            return self._memory[start:end]
+        # its a range
+        start_str, end_str = address_range.split("-")
+        start = int(start_str, 16) * 2
+        end = (int(end_str, 16) + 1) * 2
+        return self._memory[start:end]