pystudernext 0.0.1__py3-none-any.whl

pystudernext/__init__.py

@@ -0,0 +1,22 @@
+from .shared.studer_types import StuderUserLevel, StuderAccess, StuderTarget, StuderDataType
+from .shared.studer_types import StuderDiscoveredGateway, StuderDiscoveredDevice, StuderDiscoverNotConnected
+from .shared.studer_types import StuderParamException
+from .shared.studer_dataset import StuderDataset, StuderDatapoint, StuderDatapointUnknownException, StuderDatapointSyntaxException, StuderDatapointEnumNotFoundException
+from .shared.studer_families import StuderDeviceFamily, StuderDeviceFamilies, StuderDeviceFamilyUnknownException, StuderDeviceCodeUnknownException, StuderDeviceAddressUnknownException, StuderDeviceSlaveUnknownException
+from .shared.studer_interfaces_async import AsyncStuderApi, AsyncStuderDiscover, StuderDiscoverFlags
+from .shared.studer_interfaces_sync import StuderApi, StuderDiscover
+
+from .api_async import AsyncNextApi
+from .api_sync import NextApi
+from .discover_async import AsyncNextDiscover
+from .discover_sync import NextDiscover
+
+from .const import DEFAULT_HOST, DEFAULT_PORT
+from .data import NextDataType, NextUserLevel
+from .data import NextApiConnectException, NextApiTimeoutException, NextPackException, NextUnpackException
+from .datapoints import NextDataset, NextDatapoint, NextDatasetFlag
+from .families import NextDeviceFamily, NextDeviceFamilies, NextDeviceFamiliesFlag
+from .values import NextValueItem, NextValueSet
+
+# For unit testing
+# - none

pystudernext/api_async.py

@@ -0,0 +1,297 @@
+"""
+api.py: communication api to Studer Next via Modbus over TCP.
+"""
+
+import asyncio
+import logging
+
+from datetime import datetime, timedelta
+from pymodbus.client import AsyncModbusTcpClient, ModbusTcpClient
+from typing import Any
+
+from .shared.studer_dataset import StuderDatapoint
+from .shared.studer_interfaces_async import AsyncStuderApi
+from .shared.studer_interfaces_sync import StuderApi
+from .shared.studer_types import StuderAccess, StuderDataType, StuderDiscoveredDevice, StuderParamException
+from .const import DEFAULT_HOST, DEFAULT_PORT, REQ_BURST_PERIOD
+from .data import NextDataType, NextApiConnectException, NextApiReadException, NextApiUpdateException, NextPackException, NextUnpackException
+from .datapoints import NextDatapoint
+from .families import NextDeviceFamilies
+from .values import NextValueItem, NextValueSet
+
+
+_LOGGER = logging.getLogger(__name__)
+logging.getLogger("pymodbus").setLevel(logging.WARNING)
+
+
+class AsyncNextApi(AsyncStuderApi):
+    """
+    The actual Api for requesting and updating parameters via an async modbus tcp client.
+    """
+
+    def __init__(self, host:str=DEFAULT_HOST, port:int=DEFAULT_PORT):
+        """
+        We connect to the MX Gateway.
+        Once it is connected we can send Modbus requests.
+        """
+        self._host = host
+        self._port = port
+
+        self._client: AsyncModbusTcpClient = None
+        self._families = NextDeviceFamilies.get_instance()
+
+        # Diagnostics gathering
+        self._diag_retries = {}
+        self._diag_durations = {}
+
+
+    async def start(self) -> bool:
+        """
+        Connect to the remote gateway
+        """
+        try:
+            await self._get_connected_client()
+            return True
+        
+        except Exception as err:
+            return False
+
+
+    async def stop(self):
+        """
+        Close the client
+        """
+        try:
+            if self._client:
+                await self._client.close()
+
+        except Exception:
+            pass
+
+        finally:
+            self._client = None
+
+
+    @property
+    def connected(self) -> bool:
+        """Returns True if the Next client is connected, otherwise False"""
+        return self._client is not None and self._client.connected
+    
+
+    @property
+    def remote_host(self) -> str|None:
+        """Returns the Host or IP address of the Next Gateway we connect to, otherwise None"""
+        return self._host
+    
+    @property
+    def remote_port(self) -> str|None:
+        """Returns the port of the Next Gateway we connect to, otherwise None"""
+        return self._port
+    
+
+    async def request_value(self, parameter: StuderDatapoint, device: StuderDiscoveredDevice|int|str=None, retries = None, timeout = None, verbose=False) -> Any:
+        """
+        Request a parameter.
+        One of device, slave or code needs to be passed.
+        Returns None if not connected, otherwise returns the requested value
+
+        Throws
+            StuderParamException
+            NextApiConnectException
+            NextApiTimeoutException
+            NextUnpackException
+        """
+
+        # Sanity check
+        if parameter is None:
+            return None
+            
+        if parameter.access not in [StuderAccess.READ, StuderAccess.READ_WRITE]:
+            raise StuderParamException(f"Datapoint {parameter.family_id}:{parameter.address} is not readable")
+            
+        if isinstance(device, StuderDiscoveredDevice):
+            slave = device.slave
+        elif isinstance(device, int):
+            slave = device
+        elif isinstance(device, str):  
+            slave = self._families.get_slave_by_code(code=device)
+        else:
+            raise StuderParamException(f"Parameter 'device' must be a NextDiscoverdDevice, a slave number or a device code in call to request_value")
+
+        # Send the request
+        try:
+            if verbose:
+                _LOGGER.debug(f"Modbus read registers for '{parameter.name}' ({parameter.address} via {slave})")
+            
+            client = await self._get_connected_client()
+            result = await client.read_holding_registers(address=parameter.address, count=parameter.size, device_id=slave)
+
+        except Exception as err:
+            raise NextApiReadException(f"Modbus exception while requesting value for slave {slave}, address {parameter.address}, count {parameter.size}, error: {err}")
+
+        if result.isError():
+            raise NextApiReadException(f"Modbus error while requesting value for slave {slave}, address {parameter.address}, count {parameter.size}, error: {result.exception_code}")
+
+        # Unpack the response value
+        try:
+            value = AsyncModbusTcpClient.convert_from_registers(result.registers, data_type=NextDataType.to_datatype(parameter.data_type))
+
+            match parameter.data_type:
+                case StuderDataType.ENUM32: return parameter.enum_value(value)
+                case StuderDataType.BITFIELD: return parameter.bitfield_value(value)
+                case _: return value
+
+        except Exception as e:
+            raise NextPackException(f"Failed to unpack response value for slave {slave}, address {parameter.address}: registers={result.registers}, format={parameter.data_type}, size={parameter.size}") from None
+
+
+    async def request_values(self, request_data: NextValueSet, retries = None, timeout = None, verbose=False) -> NextValueSet:
+        """
+        Request multiple parameters in one call.
+        Can only retrieve actual device values, NOT the average or sum over multiple devices.
+
+        Returns None if not connected, otherwise returns the list of requested values
+        Throws
+            StuderParamException
+            NextApiConnectException
+            NextApiTimeoutException
+            NextUnpackException
+        """
+
+        # Unlike the Studer Xcom protocol, the Studer Next protocol does not have a function to request multiple
+        # items in one call.
+        # As a result we just resolve all requested values sequentially
+        result_items: list[NextValueItem] = []
+        burst_start = datetime.now()
+
+        for req_single in request_data.items:
+            try:
+                error = None
+                value = await self.request_value(req_single.datapoint, req_single.address, retries=retries, timeout=timeout, verbose=verbose)
+            
+            except Exception as ex:
+                value = None
+                error = str(ex)
+
+            if error is not None:
+                _LOGGER.debug(f"Failed to retrieve info or param {req_single.datapoint.nr}:{req_single.address}; {error}")
+
+            # Add to results
+            rsp_single = NextValueItem(
+                datapoint = req_single.datapoint, 
+                device = req_single.code,
+                value = value,
+                error = error,
+            )
+            result_items.append(rsp_single)
+
+            # Periodically wait for a second. 
+            # This will make sure we do not block the Next Gateway with too many requests at once
+            if (datetime.now() - burst_start).total_seconds() > REQ_BURST_PERIOD:
+                await asyncio.sleep(1)
+                burst_start = datetime.now()
+
+        # Return all reponse items as one XcomValueSet object
+        return NextValueSet(result_items)
+
+
+    async def update_value(self, parameter: NextDatapoint, value: Any, device: StuderDiscoveredDevice|int|str=None, retries = None, timeout = None, verbose=False):
+        """
+        Update a parameter
+        Returns None if not connected, otherwise returns True on success
+
+        Throws
+            StuderParamException
+            NextApiConnectException
+            NextApiTimeoutException
+            NextPackException
+        """
+        # Sanity check
+        if parameter is None or value is None:
+            return None
+
+        if parameter.access not in [StuderAccess.WRITE, StuderAccess.READ_WRITE]:
+            raise StuderParamException(f"Device parameter {parameter.family_id}:{parameter.address} is not writable")
+            
+        if isinstance(device, StuderDiscoveredDevice):
+            slave = device.slave
+        elif isinstance(device, int):
+            slave = device
+        elif isinstance(device, str):  
+            slave = self._families.get_slave_by_code(code=device)
+        else:
+            raise StuderParamException(f"Device parameter must be a NextDiscoverdDevice, a slave number or a device code in call to update_value")
+
+        _LOGGER.debug(f"Update '{parameter.name}' ({parameter.address} via {slave}) to {value}")
+
+        # Pack the data
+        try:
+            client = await self._get_connected_client()
+            regs = AsyncModbusTcpClient.convert_to_registers(value, data_type=NextDataType.to_datatype(parameter.data_type))
+
+        except Exception as e:
+            raise NextPackException(f"Failed to pack value for slave {slave}, address {parameter.address}: value={value}, format={parameter.data_type}, size={parameter.size}") from None
+        
+        # Send the request
+        try:
+            if verbose:
+                _LOGGER.debug(f"Modbus update registers for '{parameter.name}' ({parameter.address} via {slave})")
+            
+            result = await client.write_registers(address=parameter.address, values=regs, device_id=slave)
+
+        except Exception as err:
+            raise NextApiUpdateException(f"Modbus exception while updating value for slave {slave}, address {parameter.address}, error: {err}")
+
+        if result.isError():
+            raise NextApiReadException(f"Modbus error while updating value for slave {slave}, address {parameter.address}, count {parameter.size}, error: {result.exception_code}")    
+
+        return None
+
+
+    async def _get_connected_client(self) -> AsyncModbusTcpClient:
+        """
+        Return a connected client, reconnecting if needed.
+        """
+        if not self.connected:
+            client = self._create_client()
+
+            if await client.connect():
+                self._client = client
+            else:
+                self._client = None
+                raise NextApiConnectException(f"Cannot connect to Studer Gateway at {self._host}:{self._port}")
+            
+        return self._client            
+
+
+    def _create_client(self):
+        """
+        Helper to create the Modbus Client.
+        In a separate function to make it easier to replace the client with a stub for unit-tests.
+        """
+        return AsyncModbusTcpClient(host=self._host, port=self._port)
+
+
+    async def _add_diagnostics(self, retries: int = None, duration: timedelta = None):
+        if retries is not None:
+            if retries not in self._diag_retries:
+                self._diag_retries[retries] = 1
+            else:
+                self._diag_retries[retries] += 1
+
+        if duration is not None:
+            duration = round(duration.total_seconds(), 1)
+            if duration not in self._diag_durations:
+                self._diag_durations[duration] = 1
+            else:
+                self._diag_durations[duration] += 1
+
+
+    async def get_diagnostics(self):
+        return {
+            "statistics": {
+                "retries": dict(sorted(self._diag_retries.items())),
+                "durations": dict(sorted(self._diag_durations.items())),
+            }
+        }
+

pystudernext/api_sync.py

@@ -0,0 +1,300 @@
+# Do not edit this file directly. It has been autogenerated from
+# src\pystudernext\api_async.py
+"""
+api.py: communication api to Studer Next via Modbus over TCP.
+"""
+
+import asyncio
+import logging
+
+from datetime import datetime, timedelta
+from pymodbus.client import AsyncModbusTcpClient, ModbusTcpClient
+from typing import Any
+
+from .shared.studer_dataset import StuderDatapoint
+from .shared.studer_interfaces_async import AsyncStuderApi
+from .shared.studer_interfaces_sync import StuderApi
+from .shared.studer_types import StuderAccess, StuderDataType, StuderDiscoveredDevice, StuderParamException
+from .const import DEFAULT_HOST, DEFAULT_PORT, REQ_BURST_PERIOD
+from .data import NextDataType, NextApiConnectException, NextApiReadException, NextApiUpdateException, NextPackException, NextUnpackException
+from .datapoints import NextDatapoint
+from .families import NextDeviceFamilies
+from .values import NextValueItem, NextValueSet
+import time
+
+
+_LOGGER = logging.getLogger(__name__)
+logging.getLogger("pymodbus").setLevel(logging.WARNING)
+
+
+class NextApi(StuderApi):
+    """
+    The actual Api for requesting and updating parameters via an async modbus tcp client.
+    """
+
+    def __init__(self, host:str=DEFAULT_HOST, port:int=DEFAULT_PORT):
+        """
+        We connect to the MX Gateway.
+        Once it is connected we can send Modbus requests.
+        """
+        self._host = host
+        self._port = port
+
+        self._client: ModbusTcpClient = None
+        self._families = NextDeviceFamilies.get_instance()
+
+        # Diagnostics gathering
+        self._diag_retries = {}
+        self._diag_durations = {}
+
+
+    def start(self) -> bool:
+        """
+        Connect to the remote gateway
+        """
+        try:
+            self._get_connected_client()
+            return True
+        
+        except Exception as err:
+            return False
+
+
+    def stop(self):
+        """
+        Close the client
+        """
+        try:
+            if self._client:
+                self._client.close()
+
+        except Exception:
+            pass
+
+        finally:
+            self._client = None
+
+
+    @property
+    def connected(self) -> bool:
+        """Returns True if the Next client is connected, otherwise False"""
+        return self._client is not None and self._client.connected
+    
+
+    @property
+    def remote_host(self) -> str|None:
+        """Returns the Host or IP address of the Next Gateway we connect to, otherwise None"""
+        return self._host
+    
+    @property
+    def remote_port(self) -> str|None:
+        """Returns the port of the Next Gateway we connect to, otherwise None"""
+        return self._port
+    
+
+    def request_value(self, parameter: StuderDatapoint, device: StuderDiscoveredDevice|int|str=None, retries = None, timeout = None, verbose=False) -> Any:
+        """
+        Request a parameter.
+        One of device, slave or code needs to be passed.
+        Returns None if not connected, otherwise returns the requested value
+
+        Throws
+            StuderParamException
+            NextApiConnectException
+            NextApiTimeoutException
+            NextUnpackException
+        """
+
+        # Sanity check
+        if parameter is None:
+            return None
+            
+        if parameter.access not in [StuderAccess.READ, StuderAccess.READ_WRITE]:
+            raise StuderParamException(f"Datapoint {parameter.family_id}:{parameter.address} is not readable")
+            
+        if isinstance(device, StuderDiscoveredDevice):
+            slave = device.slave
+        elif isinstance(device, int):
+            slave = device
+        elif isinstance(device, str):  
+            slave = self._families.get_slave_by_code(code=device)
+        else:
+            raise StuderParamException(f"Parameter 'device' must be a NextDiscoverdDevice, a slave number or a device code in call to request_value")
+
+        # Send the request
+        try:
+            if verbose:
+                _LOGGER.debug(f"Modbus read registers for '{parameter.name}' ({parameter.address} via {slave})")
+            
+            client = self._get_connected_client()
+            result = client.read_holding_registers(address=parameter.address, count=parameter.size, device_id=slave)
+
+        except Exception as err:
+            raise NextApiReadException(f"Modbus exception while requesting value for slave {slave}, address {parameter.address}, count {parameter.size}, error: {err}")
+
+        if result.isError():
+            raise NextApiReadException(f"Modbus error while requesting value for slave {slave}, address {parameter.address}, count {parameter.size}, error: {result.exception_code}")
+
+        # Unpack the response value
+        try:
+            value = ModbusTcpClient.convert_from_registers(result.registers, data_type=NextDataType.to_datatype(parameter.data_type))
+
+            match parameter.data_type:
+                case StuderDataType.ENUM32: return parameter.enum_value(value)
+                case StuderDataType.BITFIELD: return parameter.bitfield_value(value)
+                case _: return value
+
+        except Exception as e:
+            raise NextPackException(f"Failed to unpack response value for slave {slave}, address {parameter.address}: registers={result.registers}, format={parameter.data_type}, size={parameter.size}") from None
+
+
+    def request_values(self, request_data: NextValueSet, retries = None, timeout = None, verbose=False) -> NextValueSet:
+        """
+        Request multiple parameters in one call.
+        Can only retrieve actual device values, NOT the average or sum over multiple devices.
+
+        Returns None if not connected, otherwise returns the list of requested values
+        Throws
+            StuderParamException
+            NextApiConnectException
+            NextApiTimeoutException
+            NextUnpackException
+        """
+
+        # Unlike the Studer Xcom protocol, the Studer Next protocol does not have a function to request multiple
+        # items in one call.
+        # As a result we just resolve all requested values sequentially
+        result_items: list[NextValueItem] = []
+        burst_start = datetime.now()
+
+        for req_single in request_data.items:
+            try:
+                error = None
+                value = self.request_value(req_single.datapoint, req_single.address, retries=retries, timeout=timeout, verbose=verbose)
+            
+            except Exception as ex:
+                value = None
+                error = str(ex)
+
+            if error is not None:
+                _LOGGER.debug(f"Failed to retrieve info or param {req_single.datapoint.nr}:{req_single.address}; {error}")
+
+            # Add to results
+            rsp_single = NextValueItem(
+                datapoint = req_single.datapoint, 
+                device = req_single.code,
+                value = value,
+                error = error,
+            )
+            result_items.append(rsp_single)
+
+            # Periodically wait for a second. 
+            # This will make sure we do not block the Next Gateway with too many requests at once
+            if (datetime.now() - burst_start).total_seconds() > REQ_BURST_PERIOD:
+                time.sleep(1)
+                burst_start = datetime.now()
+
+        # Return all reponse items as one XcomValueSet object
+        return NextValueSet(result_items)
+
+
+    def update_value(self, parameter: NextDatapoint, value: Any, device: StuderDiscoveredDevice|int|str=None, retries = None, timeout = None, verbose=False):
+        """
+        Update a parameter
+        Returns None if not connected, otherwise returns True on success
+
+        Throws
+            StuderParamException
+            NextApiConnectException
+            NextApiTimeoutException
+            NextPackException
+        """
+        # Sanity check
+        if parameter is None or value is None:
+            return None
+
+        if parameter.access not in [StuderAccess.WRITE, StuderAccess.READ_WRITE]:
+            raise StuderParamException(f"Device parameter {parameter.family_id}:{parameter.address} is not writable")
+            
+        if isinstance(device, StuderDiscoveredDevice):
+            slave = device.slave
+        elif isinstance(device, int):
+            slave = device
+        elif isinstance(device, str):  
+            slave = self._families.get_slave_by_code(code=device)
+        else:
+            raise StuderParamException(f"Device parameter must be a NextDiscoverdDevice, a slave number or a device code in call to update_value")
+
+        _LOGGER.debug(f"Update '{parameter.name}' ({parameter.address} via {slave}) to {value}")
+
+        # Pack the data
+        try:
+            client = self._get_connected_client()
+            regs = ModbusTcpClient.convert_to_registers(value, data_type=NextDataType.to_datatype(parameter.data_type))
+
+        except Exception as e:
+            raise NextPackException(f"Failed to pack value for slave {slave}, address {parameter.address}: value={value}, format={parameter.data_type}, size={parameter.size}") from None
+        
+        # Send the request
+        try:
+            if verbose:
+                _LOGGER.debug(f"Modbus update registers for '{parameter.name}' ({parameter.address} via {slave})")
+            
+            result = client.write_registers(address=parameter.address, values=regs, device_id=slave)
+
+        except Exception as err:
+            raise NextApiUpdateException(f"Modbus exception while updating value for slave {slave}, address {parameter.address}, error: {err}")
+
+        if result.isError():
+            raise NextApiReadException(f"Modbus error while updating value for slave {slave}, address {parameter.address}, count {parameter.size}, error: {result.exception_code}")    
+
+        return None
+
+
+    def _get_connected_client(self) -> ModbusTcpClient:
+        """
+        Return a connected client, reconnecting if needed.
+        """
+        if not self.connected:
+            client = self._create_client()
+
+            if client.connect():
+                self._client = client
+            else:
+                self._client = None
+                raise NextApiConnectException(f"Cannot connect to Studer Gateway at {self._host}:{self._port}")
+            
+        return self._client            
+
+
+    def _create_client(self):
+        """
+        Helper to create the Modbus Client.
+        In a separate function to make it easier to replace the client with a stub for unit-tests.
+        """
+        return ModbusTcpClient(host=self._host, port=self._port)
+
+
+    def _add_diagnostics(self, retries: int = None, duration: timedelta = None):
+        if retries is not None:
+            if retries not in self._diag_retries:
+                self._diag_retries[retries] = 1
+            else:
+                self._diag_retries[retries] += 1
+
+        if duration is not None:
+            duration = round(duration.total_seconds(), 1)
+            if duration not in self._diag_durations:
+                self._diag_durations[duration] = 1
+            else:
+                self._diag_durations[duration] += 1
+
+
+    def get_diagnostics(self):
+        return {
+            "statistics": {
+                "retries": dict(sorted(self._diag_retries.items())),
+                "durations": dict(sorted(self._diag_durations.items())),
+            }
+        }
+

pystudernext/const.py

@@ -0,0 +1,23 @@
+#! /usr/bin/env python3
+
+##
+# Definition of all parameters / constants used in the Next protocol
+##
+
+from dataclasses import dataclass
+from enum import IntEnum, StrEnum
+from pymodbus.client import AsyncModbusTcpClient
+from typing import Iterable
+
+
+DEFAULT_HOST = ""
+DEFAULT_PORT = 502
+
+REQ_BURST_PERIOD = 5 # do burst of requests for 5 seconds, then wait a second, then the next burst
+
+   
+def safe_len(lst: Iterable):
+    try:
+        return len(lst)
+    except:
+        return sum(1 for i in lst)