pystuderxcom 3.0.0__py3-none-any.whl

pystuderxcom/__init__.py

@@ -0,0 +1,26 @@
+from .api_tcp import AsyncXcomApiTcp, XcomApiTcp
+from .api_udp import AsyncXcomApiUdp, XcomApiUdp
+from .api_serial import AsyncXcomApiSerial, XcomApiSerial
+
+from .api_base_async import AsyncXcomApiBase
+from .discover_async import AsyncXcomDiscover
+from .factory_async import AsyncXcomFactory
+
+from .api_base_sync import XcomApiBase
+from .discover_sync import XcomDiscover
+from .factory_sync import XcomFactory
+
+from .const import XcomVoltage, XcomLevel, XcomFormat, XcomCategory, XcomAggregationType
+from .const import XcomApiWriteException, XcomApiReadException, XcomApiTimeoutException, XcomApiUnpackException, XcomApiResponseIsError, XcomDiscoverNotConnected, XcomParamException
+from .data import XcomDiscoveredClient, XcomDiscoveredDevice
+from .datapoints import XcomDataset, XcomDatapoint, XcomDatapointUnknownException
+from .families import XcomDeviceFamily, XcomDeviceFamilies, XcomDeviceFamilyUnknownException, XcomDeviceCodeUnknownException, XcomDeviceAddrUnknownException
+from .messages import XcomMessage, XcomMessageUnknownException
+from .values import XcomValues, XcomValuesItem
+
+# For unit testing
+from .const import ScomObjType, ScomObjId, ScomService, ScomQspId, ScomQspLevel, ScomAddress, ScomErrorCode
+from .data import XcomData, XcomDataMessageRsp, XcomDataMultiInfoReq, XcomDataMultiInfoReqItem, XcomDataMultiInfoRsp, XcomDataMultiInfoRspItem
+from .messages import XcomMessageDef, XcomMessageSet
+from .protocol import XcomHeader, XcomFrame, XcomService, XcomPackage
+

pystuderxcom/api_base_async.py

@@ -0,0 +1,592 @@
+"""xcom_api.py: communication api to Studer Xcom via LAN."""
+
+import asyncio
+import binascii
+import logging
+
+from datetime import datetime, timedelta
+
+from .const import (
+    START_TIMEOUT,
+    STOP_TIMEOUT,
+    REQ_TIMEOUT,
+    REQ_RETRIES,
+    REQ_BURST_PERIOD,
+    ScomAddress,
+    XcomFormat,
+    XcomCategory,
+    XcomAggregationType,
+    ScomObjType,
+    ScomObjId,
+    ScomService,
+    ScomQspId,
+    XcomApiReadException,
+    XcomApiWriteException,
+    XcomApiUnpackException,
+    XcomApiTimeoutException,
+    XcomApiResponseIsError,
+    XcomParamException,
+    safe_len,
+)
+from .data import (
+    XcomData,
+    XcomDataMessageRsp,
+    MULTI_INFO_REQ_MAX,
+)
+from .datapoints import (
+    XcomDatapoint,
+)
+from .factory_async import (
+    AsyncXcomFactory,
+)
+from .factory_sync import (
+    XcomFactory,
+)
+from .families import (
+    XcomDeviceFamilies
+)
+from .messages import (
+    XcomMessage,
+)
+from .protocol import (
+    XcomPackage,
+)
+from .values import (
+    XcomValues,
+    XcomValuesItem,
+)
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+##
+## Base cass abstracting Xcom Api
+##
+class AsyncXcomApiBase:
+
+    def __init__(self):
+        """
+        MOXA is connecting to the TCP Server we are creating here.
+        Once it is connected we can send package requests.
+        """
+        self._connected = False
+        self._remote_ip = None
+        self._request_id = 0
+        self._sendRequestLock = asyncio.Lock() # to make sure _sendRequest_inner is never called concurrently
+
+        # Cached values
+        self._msg_set = None
+
+        # Diagnostics gathering
+        self._diag_retries = {}
+        self._diag_durations = {}
+
+
+    async def start(self, timeout=START_TIMEOUT) -> bool:
+        """
+        Start the Xcom Server and listening to the Xcom client.
+        """
+        raise NotImplementedError()
+
+
+    async def stop(self):
+        """
+        Stop listening to the the Xcom Client and stop the Xcom Server.
+        """
+        raise NotImplementedError()
+    
+
+    @property
+    def connected(self) -> bool:
+        """Returns True if the Xcom client is connected, otherwise False"""
+        return self._connected
+
+
+    @property
+    def remote_ip(self) -> str|None:
+        """Returns the IP address of the connected Xcom client, otherwise None"""
+        return self._remote_ip
+    
+
+    async def _wait_until_connected(self, timeout) -> bool:
+        """Wait for Xcom client to connect. Or timout."""
+        try:
+            for i in range(timeout):
+                if self._connected:
+                    return True
+                
+                await asyncio.sleep(1)
+
+        except Exception as e:
+            _LOGGER.warning(f"Exception while checking connection to Xcom client: {e}")
+
+        return False
+
+
+    async def requestGuid(self, retries = None, timeout = None, verbose=False):
+        """
+        Request the GUID that is used for remotely identifying the installation.
+        This function is only for the Modem or Ethernet mode
+
+        Returns None if not connected, otherwise returns the requested value
+        Throws
+            XcomApiWriteException
+            XcomApiReadException
+            XcomApiTimeoutException
+            XcomApiResponseIsError
+        """
+
+        # Compose the request and send it
+        request: XcomPackage = XcomPackage.genPackage(
+            service_id = ScomService.READ,
+            object_type = ScomObjType.GUID,
+            object_id = ScomObjId.NONE,
+            property_id = ScomQspId.NONE,
+            property_data = XcomData.NONE,
+            dst_addr = ScomAddress.RCC
+        )
+
+        response = await self._sendRequest(request, retries=retries, timeout=timeout, verbose=verbose)
+        if response is not None:
+            # Unpack the response value
+            try:
+                return XcomData.unpack(response.frame_data.service_data.property_data, XcomFormat.GUID)
+
+            except Exception as e:
+                msg = f"Failed to unpack response package for GUID:{request.header.dst_addr}, data={response.frame_data.service_data.property_data.hex()}: {e}"
+                raise XcomApiUnpackException(msg) from None
+
+                                         
+    async def requestValue(self, parameter: XcomDatapoint, dstAddr = 100, retries = None, timeout = None, verbose=False):
+        """
+        Request a param or info.
+        Returns None if not connected, otherwise returns the requested value
+        Throws
+            XcomApiWriteException
+            XcomApiReadException
+            XcomApiTimeoutException
+            XcomApiResponseIsError
+        """
+
+        # Check/convert input parameters        
+        if type(dstAddr) is str:
+            dstAddr = XcomDeviceFamilies.getAddrByCode(dstAddr)
+
+        # Compose the request and send it
+        request: XcomPackage = XcomPackage.genPackage(
+            service_id = ScomService.READ,
+            object_type = ScomObjType.PARAMETER if parameter.category == XcomCategory.PARAMETER else ScomObjType.INFO,
+            object_id = parameter.nr,
+            property_id = ScomQspId.UNSAVED_VALUE if parameter.category == XcomCategory.PARAMETER else ScomQspId.VALUE,
+            property_data = XcomData.NONE,
+            dst_addr = dstAddr
+        )
+
+        response = await self._sendRequest(request, retries=retries, timeout=timeout, verbose=verbose)
+        if response is not None:
+            # Unpack the response value
+            try:
+                return XcomData.unpack(response.frame_data.service_data.property_data, parameter.format)
+
+            except Exception as e:
+                msg = f"Failed to unpack response package for {parameter.nr}:{dstAddr}, data={response.frame_data.service_data.property_data.hex()}: {e}"
+                raise XcomApiUnpackException(msg) from None
+
+                                         
+    async def requestInfos(self, request_data: XcomValues, retries = None, timeout = None, verbose=False) -> XcomValues:
+        """
+        Request multiple infos in one call.
+        Per info you can indicate what device to get it from, or to get Average or Sum of multiple devices
+
+        Returns None if not connected, otherwise returns the list of requested values
+        Throws
+            XcomApiWriteException
+            XcomApiReadException
+            XcomApiTimeoutException
+            XcomApiResponseIsError
+
+        Note: this requires at least firmware version 1.6.74 on your Xcom-232i/Xcom-LAN.
+              On older versions it results in a 'Service not supported' response from the Xcom client
+        """
+
+        # Sanity check
+        for item in request_data.items:
+            if item.datapoint.category != XcomCategory.INFO:
+                raise XcomParamException(f"Invalid datapoint passed to requestInfos; must have type INFO. Violated by datapoint '{item.datapoint.name}' ({item.datapoint.nr})")
+            
+            if item.aggregation_type not in XcomAggregationType:
+                raise XcomParamException(f"Invalid aggregation_type passed to requestInfos; violated by '{item.aggregation_type}'")                
+
+        # Compose the request and send it
+        request: XcomPackage = XcomPackage.genPackage(
+            service_id = ScomService.READ,
+            object_type = ScomObjType.MULTI_INFO,
+            object_id = ScomObjId.MULTI_INFO,
+            property_id = self._getNextRequestId() & 0xffff,
+            property_data = request_data.packRequest(),
+            dst_addr = ScomAddress.RCC
+        )
+
+        response = await self._sendRequest(request, retries=retries, timeout=timeout, verbose=verbose)
+        if response is not None:
+            try:
+                # Unpack the response value
+                return XcomValues.unpackResponse(response.frame_data.service_data.property_data, request_data)
+
+            except Exception as e:
+                msg = f"Failed to unpack response package for multi-info request, data={response.frame_data.service_data.property_data.hex()}: {e}"
+                raise XcomApiUnpackException(msg) from None
+
+
+    async def requestValues(self, request_data: XcomValues, retries = None, timeout = None, verbose=False) -> XcomValues:
+        """
+        Request multiple infos and params in one call.
+        Can only retrieve actual device values, NOT the average or sum over multiple devices.
+
+        The function will try to be as efficient as possible and combine retrieval of multiple infos in one call.
+        When the xcom-client does not support multiple-infos in one call, they are retried one by one. 
+        Requested params are always retrieved one by one, so the function can take a while to finish.        
+
+        Returns None if not connected, otherwise returns the list of requested values
+        Throws
+            XcomApiWriteException
+            XcomApiReadException
+            XcomApiTimeoutException
+            XcomApiResponseIsError
+        """
+
+        # Sort out which XcomValues can be done via multi requestValues and which must be done via single requestValue
+        req_singles: list[XcomValuesItem] = []
+        req_multi_items: list[XcomValuesItem] = []
+        req_multis: list[XcomValues] = []
+        idx_last = safe_len(request_data.items)-1
+
+        for idx,item in enumerate(request_data.items):
+            
+            match item.datapoint.category:
+                case XcomCategory.INFO:
+                    if item.aggregation_type is not None and item.aggregation_type in range(XcomAggregationType.DEVICE1, XcomAggregationType.DEVICE15+1):
+                        # Can be combined with other infos in a requestValues call
+                        req_multi_items.append(item)
+
+                    elif item.address is not None:
+                        # Any others need to be done via an individual requestValue cal
+                        req_singles.append(item)
+
+                    else:
+                        raise XcomParamException(f"Invalid XcomValuesItem passed to requestValues; violated by code='{item.code}', address={item.address}, aggregation_type={item.aggregation_type}")
+
+                case XcomCategory.PARAMETER:
+                    if item.address is not None:
+                        # Needs to be done via an individual requestValue call
+                        req_singles.append(item)
+
+                    else:
+                        raise XcomParamException(f"Invalid XcomValuesItem passed to requestValues; violated by code='{item.code}', address={item.address}, aggregation_type={item.aggregation_type}")
+            
+            if (len(req_multi_items) == MULTI_INFO_REQ_MAX) or \
+               (len(req_multi_items) > 0 and idx == idx_last):
+
+                # Start a new multi-items if current one if full or on last item of enumerate
+                req_multis.append( XcomValues(items=req_multi_items) )
+                req_multi_items = []
+
+        # Now perform all the multi requestValues requests
+        result_items: list[XcomValues] = []
+        burst_start = datetime.now()
+
+        for req_multi in req_multis:
+            try:
+                rsp_multi = await self.requestInfos(req_multi, retries=retries, timeout=timeout, verbose=verbose)
+
+                # Success; gather the returned response items
+                result_items.extend(rsp_multi.items)
+            
+            except XcomApiTimeoutException as tex:
+                _LOGGER.debug(f"Failed to retrieve infos via single call. {tex}")
+
+                # Fail; do not retry as single requestValue also expected to give timeout
+                value = None
+                error = str(tex)
+                result_items.extend( [XcomValuesItem(req.datapoint, code=req.code, address=req.address, aggregation_type=req.aggregation_type, value=value, error=error) for req in req_multi.items] )
+            
+            except Exception as ex:
+                _LOGGER.debug(f"Failed to retrieve infos via single call; will retry retrieve one-by-one. {ex}")
+
+                # Fail; retry all items as single requestValue
+                req_singles.extend(req_multi.items)
+
+            # Periodically wait for a second. This will make sure we do not block Xcom-LAN with
+            # too many requests at once and prevent it from uploading data to the Studer portal.
+            if (datetime.now() - burst_start).total_seconds() > REQ_BURST_PERIOD:
+                await asyncio.sleep(1)
+                burst_start = datetime.now()
+
+        # Next perform all the single requestValue requests
+        for req_single in req_singles:
+            try:
+                error = None
+                value = await self.requestValue(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 = XcomValuesItem(
+                datapoint = req_single.datapoint, 
+                code = req_single.code,
+                address = req_single.address,
+                aggregation_type=req_single.aggregation_type, 
+                value = value,
+                error = error,
+            )
+            result_items.append(rsp_single)
+
+            # Periodically wait for a second. This will make sure we do not block Xcom-LAN with
+            # too many requests at once and prevent it from uploading data to the Studer portal.
+            if (datetime.now() - burst_start).total_seconds() > REQ_BURST_PERIOD:
+                await asyncio.sleep(1)
+                burst_start = datetime.now()
+
+        # Return all reponse items as one XcomValues object
+        return XcomValues(result_items)
+
+
+    async def updateValue(self, parameter: XcomDatapoint, value, dstAddr = 100, retries = None, timeout = None, verbose=False):
+        """
+        Update a param
+        Returns None if not connected, otherwise returns True on success
+        Throws
+            XcomApiWriteException
+            XcomApiReadException
+            XcomApiTimeoutException
+            XcomApiResponseIsError
+        """
+        # Sanity check: the parameter/datapoint must have category == XcomDatapointType.PARAMETER
+        if parameter.category != XcomCategory.PARAMETER:
+            _LOGGER.warning(f"Ignoring attempt to update readonly infos value {parameter}")
+            return None
+
+        if type(dstAddr) is str:
+            dstAddr = XcomDeviceFamilies.getAddrByCode(dstAddr)
+
+        _LOGGER.debug(f"Update value {parameter} on addr {dstAddr}")
+
+        # Compose the request and send it
+        request: XcomPackage = XcomPackage.genPackage(
+            service_id = ScomService.WRITE,
+            object_type = ScomObjType.PARAMETER,
+            object_id = parameter.nr,
+            property_id = ScomQspId.UNSAVED_VALUE,
+            property_data = XcomData.pack(value, parameter.format),
+            dst_addr = dstAddr
+        )
+
+        response = await self._sendRequest(request, retries=retries, timeout=timeout, verbose=verbose)
+        if response is not None:
+            # No need to unpack the response value
+            return True
+        
+        return False
+    
+
+    async def requestMessage(self, index:int = 0, retries = None, timeout = None, verbose=False) -> XcomMessage:
+        """
+        Request a Message from the RCC.
+        Reading a message with index 0 will return the last saved message in the flash memory of 
+        the Xcom-232i and will also return the the number of remaining messages.
+        A side effect of reading a message with index 0 is that it will erase the flag informing 
+        that there are new messages.
+
+        Reading a message with an index above 0 will return the message saved with that index.
+
+        Note: this requires at least firmware version 1.5.0 on your Xcom-232i/Xcom-LAN.
+              On older versions it results in a 'Service not supported' response from the Xcom client
+        
+        Returns None if not connected, otherwise returns the requested value
+        Throws
+            XcomApiWriteException
+            XcomApiReadException
+            XcomApiTimeoutException
+            XcomApiResponseIsError
+        """
+
+        # Make sure we have access to the message_set
+        if self._msg_set is None:
+            self._msg_set = await AsyncXcomFactory.create_messageset()
+
+        # Compose the request and send it
+        request: XcomPackage = XcomPackage.genPackage(
+            service_id = ScomService.READ,
+            object_type = ScomObjType.MESSAGE,
+            object_id = index,
+            property_id = ScomQspId.NONE,
+            property_data = XcomData.NONE,
+            dst_addr = ScomAddress.RCC,
+        )
+
+        response = await self._sendRequest(request, retries=retries, timeout=timeout, verbose=verbose)
+        if response is not None:
+            # Unpack the response value
+            try:
+                # Unpack the response value
+                rsp_data = XcomDataMessageRsp.unpack(response.frame_data.service_data.property_data)
+                return XcomMessage(rsp_data, self._msg_set)
+
+            except Exception as e:
+                msg = f"Failed to unpack response package for message request, data={response.frame_data.service_data.property_data.hex()}: {e}"
+                raise XcomApiUnpackException(msg) from None
+                        
+
+    async def _sendRequest(self, request: XcomPackage, retries = None, timeout = None, verbose=False):
+    
+        # Sometimes the Xcom client does not seem to pickup a request
+        # so retry if needed
+        if not self._connected:
+            _LOGGER.warning(f"_sendRequest - not connected")
+            return None
+        
+        last_exception = None
+        retries = retries or REQ_RETRIES
+        timeout = timeout or REQ_TIMEOUT
+
+        for retry in range(retries):
+            try:
+                async with self._sendRequestLock:
+                    ts_start = datetime.now()
+
+                    response = await self._sendRequest_inner(request, timeout=timeout, verbose=verbose)
+
+                    # Update diagnostics
+                    ts_end = datetime.now()
+                    await self._addDiagnostics(retries = retry, duration = ts_end-ts_start)
+
+                    # Check the response
+                    if response is None:
+                        return None
+
+                    if response.isError():
+                        raise XcomApiResponseIsError(response.getError())
+                    
+                    # Success
+                    return response
+                        
+            except Exception as e:
+                last_exception = e
+
+        # Update diagnostics in case of timeout of each retry
+        await self._addDiagnostics(retries = retry)
+
+        if last_exception:
+            raise last_exception from None
+
+
+    async def _sendRequest_inner(self, request: XcomPackage, retries = None, timeout = None, verbose=False):
+        """
+        Send a request package to the Xcom client and wait for the correct response package
+        """
+
+        # Send the request package to the Xcom client
+        try:
+            if verbose:
+                data = request.getBytes()
+                _LOGGER.debug(f"send {len(data)} bytes ({binascii.hexlify(data).decode('ascii')}), decoded: {request}")
+
+            await self._sendPackage(request)
+
+        except Exception as e:
+            msg = f"Exception while sending request package to Xcom client: {e}"
+            raise XcomApiWriteException(msg) from None
+
+        # Receive packages until we get the one we expect
+        # We implement our own primitive timeout mechanism that
+        # is robust when converted from async to sync via unasyncd tool
+        ts_end = datetime.now() + timedelta(seconds=timeout)
+
+        while datetime.now() < ts_end:
+            try:
+                response = await self._receivePackage()
+                
+                if response is None:
+                    continue
+
+                if response.isResponse() and \
+                    response.frame_data.service_id == request.frame_data.service_id and \
+                    response.frame_data.service_data.object_id == request.frame_data.service_data.object_id and \
+                    response.frame_data.service_data.property_id == request.frame_data.service_data.property_id:
+
+                    # Yes, this is the answer to our request
+                    if verbose:
+                        data = response.getBytes()
+                        _LOGGER.debug(f"recv {len(data)} bytes ({binascii.hexlify(data).decode('ascii')}), decoded: {response}")
+
+                    return response
+                else:
+                    # No, not an answer to our request, continue loop for next answer (or timeout)
+                    if verbose:
+                        data = response.getBytes()
+                        _LOGGER.debug(f"skip {len(data)} bytes ({binascii.hexlify(data).decode('ascii')}), decoded: {response}")
+
+            except Exception as e:
+                msg = f"Exception while listening for response package from Xcom client: {e}"
+                raise XcomApiReadException() from None
+
+        # If we reach this point then there was a timeout
+        msg = f"Timeout while listening for response package from Xcom client"
+        raise XcomApiTimeoutException(msg) from None
+
+
+    async def _sendPackage(self, package: XcomPackage):
+        """
+        Send an Xcom package.
+        Exception handling is dealed with by the caller.
+        
+        Must be implemented in derived classes.
+        """
+        raise NotImplementedError()
+    
+
+    async def _receivePackage(self) -> XcomPackage | None:
+        """
+        Attempt to receive an Xcom package. 
+        Return None of nothing was received within REQ_TIMEOUT.
+        Exception handling is dealed with by the caller.
+        
+        Must be implemented in derived classes.
+        """
+        raise NotImplementedError()
+    
+
+    def _getNextRequestId(self) -> int:
+        self._request_id += 1
+        return self._request_id
+
+
+    async def _addDiagnostics(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 getDiagnostics(self):
+        return {
+            "statistics": {
+                "retries": dict(sorted(self._diag_retries.items())),
+                "durations": dict(sorted(self._diag_durations.items())),
+            }
+        }
+