aioads 0.1.0.dev1__py3-none-any.whl

aioads/ads_client.py

@@ -0,0 +1,333 @@
+"""ADS Client for communicating with ADS devices asynchronously."""
+import asyncio
+import logging
+import os
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any
+
+from aioads.ads_error_codes import AdsErrorCode
+from aioads.ads_notifications import NotificationManager
+from aioads.ads_notifications import TNotificationCallback
+from aioads.ads_symbol_cache import AdsSymbolCache
+from aioads.ads_symbol_parser import AdsSymbolParser
+from aioads.ads_symbol_parser import ISymbolParser
+from aioads.ams_address import AmsAddress
+from aioads.commands.ads_add_notification import TransmissionMode
+from aioads.commands.ads_read import AdsReadCommand
+from aioads.commands.ads_read_state import ReadStateCommand
+from aioads.commands.errors import AdsCommandError
+from aioads.functions.ads_enable_route import AdsEnableRoute
+from aioads.functions.ads_enable_route import RouteSwitch
+from aioads.functions.ads_sum_read import AdsSumRead
+from aioads.functions.ads_symbol_datatype_by_name import AdsSymbolDataTypeByName
+from aioads.functions.ads_symbol_datatype_upload import AdsSymbolDataTypeUpload
+from aioads.functions.ads_symbol_info_by_name_ex import SymbolInfo
+from aioads.functions.ads_symbol_upload import AdsSymbolUpload
+from aioads.functions.ads_symbol_upload_info import AdsSymbolUploadInfo2
+from aioads.transport import AdsTcpTransport
+from aioads.transport import ITransport
+
+
+@dataclass(frozen=True, slots=True)
+class SymbolReadResult:
+    """
+    Result for a multi-symbol read operation.
+    """
+
+    error_code: AdsErrorCode
+    value: Any
+
+
+class AdsClient:
+    """
+    ADS Client for communicating with ADS devices asynchronously.
+    """
+
+    def __init__(
+        self,
+        transport: ITransport,
+        dst_address: AmsAddress,
+        parser: ISymbolParser,
+        cache: AdsSymbolCache,
+        notification: NotificationManager,
+    ) -> None:
+        self.logger = logging.getLogger(f"{__name__}.'{dst_address.net_id}'")
+        self.transport = transport
+        self.dst_address = dst_address
+        self.parser = parser
+        self._cache = cache
+        self._notification = notification
+        self.parser_pool = ThreadPoolExecutor(
+            max_workers=(os.cpu_count() or 1) * 2
+        )
+
+    @classmethod
+    def create_tcp(
+        cls, src: AmsAddress, dst: AmsAddress, ip: str, port: int = 48898
+    ) -> "AdsClient":
+        """
+        Create a new ADS client with TCP transport.
+        :param src: The source AMS address
+        :param dst: The destination AMS address
+        :param ip: The target IP address
+        :param port: The target port
+        :return: An instance of AdsClient
+        """
+        parser = AdsSymbolParser([])
+        transport = AdsTcpTransport(src_address=src, ip=ip, port=port)
+        cache = AdsSymbolCache(transport=transport, dst_address=dst)
+        notification_manager = NotificationManager(
+            transport=transport,
+            dst_address=dst,
+            symbol_cache=cache,
+            parser=parser,
+        )
+        return cls(
+            transport=transport,
+            parser=parser,
+            dst_address=dst,
+            cache=cache,
+            notification=notification_manager,
+        )
+
+    @classmethod
+    def create_from_transport(cls, dst: AmsAddress, transport: ITransport) -> "AdsClient":
+        """
+        Create a new ADS client with an existing transport instance.
+        :param src: The source AMS address
+        :param dst: The destination AMS address
+        :param transport: The existing transport instance
+        :return: An instance of AdsClient
+        """
+        parser = AdsSymbolParser([])
+        cache = AdsSymbolCache(transport=transport, dst_address=dst)
+        notification_manager = NotificationManager(
+            transport=transport,
+            dst_address=dst,
+            symbol_cache=cache,
+            parser=parser,
+        )
+        return cls(
+            transport=transport,
+            parser=parser,
+            dst_address=dst,
+            cache=cache,
+            notification=notification_manager,
+        )
+
+    async def connect(self) -> None:
+        """
+        Connect to the ADS device.
+        """
+        await self.transport.connect()
+        await self._cache.start_cache_monitor()
+        # ? Should we fail here if symbol upload fails?
+        # ? If it fails, we are still able to read basic value types but not complex
+        # ? structures.
+        try:
+            types_ = await self.get_symbol_datatypes()
+            self.parser.update_datatypes(types_)
+        except Exception:  # pylint: disable=broad-exception-caught
+            pass
+
+    async def disconnect(self) -> None:
+        """
+        Disconnect from the ADS device.
+        """
+        await self._cache.stop_cache_monitor()
+        await self.transport.disconnect()
+
+    async def read_state(self):
+        """
+        Read the state of the ADS device.
+        """
+        request = ReadStateCommand(
+            transport=self.transport,
+            ams_address=self.dst_address,
+        )
+        return await request.request()
+
+    async def enable_route(self, route_name: str, enabled: bool):
+        """
+        Enable or disable a ads route. 
+        Example route name for `ads over mqtt`: `MQTT:192.168.178.12.1.1:ads` (MQTT:<NetID>:<Topic>)
+        Example with defined name: `MQTT:MyBroker`
+        """
+
+        request = AdsEnableRoute(
+            self.transport,
+            self.dst_address,
+            route_name,
+            RouteSwitch.ROUTE_ENABLE_TMP if enabled else RouteSwitch.ROUTE_DISABLE_TMP
+        )
+        response = await request.execute()
+        if not response.error_code.ok:
+            raise AdsCommandError(response.error_code)
+
+    async def get_symbols(self):
+        """
+        Get all root symbols from the ADS device.
+        """
+        tree_info_request = AdsSymbolUploadInfo2(
+            transport=self.transport,
+            ams_address=self.dst_address,
+        )
+        tree_info = await tree_info_request.execute()
+
+        request = AdsSymbolUpload(
+            transport=self.transport,
+            ams_address=self.dst_address,
+            tree_size=tree_info.symbol_size,
+        )
+        return await request.execute()
+
+    async def get_symbol_datatypes(self):
+        """
+        Get all symbol datatypes from the ADS device.
+        """
+        tree_info_request = AdsSymbolUploadInfo2(
+            transport=self.transport,
+            ams_address=self.dst_address,
+        )
+        tree_info = await tree_info_request.execute()
+        request = AdsSymbolDataTypeUpload(
+            transport=self.transport,
+            ams_address=self.dst_address,
+            dt_size=tree_info.datatype_size,
+        )
+        return await request.execute()
+
+    async def read_datatype_by_name(self, datatype_name: str):
+        """
+        Read a datatype by its name from the ADS device.
+        """
+        request = AdsSymbolDataTypeByName(
+            transport=self.transport,
+            ams_address=self.dst_address,
+            datatype_name=datatype_name,
+        )
+        return await request.execute()
+
+    async def read_symbol_info_by_name(self, symbol_name: str):
+        """
+        Read symbol information by its name from the ADS device.
+        """
+        return await self._cache.read_symbol_info_by_name(symbol_name)
+
+    async def read_symbol_infos_by_names(self, symbol_names: set[str]):
+        """
+        Read symbol information for multiple symbols by their names from the ADS device.
+        """
+        return await self._cache.read_symbol_infos_by_names(symbol_names)
+
+    async def read_symbol_by_name(self, symbol_name: str) -> Any:
+        """
+        Read a symbol by its name from the ADS device.
+        """
+        symbol_info = await self._cache.read_symbol_info_by_name(symbol_name)
+        read_command = AdsReadCommand(
+            transport=self.transport,
+            ams_address=self.dst_address,
+            idx_group=symbol_info.idx_group,
+            idx_offset=symbol_info.idx_offset,
+            length=symbol_info.idx_length,
+        )
+        _, payload = await read_command.request()
+        return self.parser.parse(
+            data_type=symbol_info.data_type,
+            type_name=symbol_info.type_name,
+            raw_data=payload,
+        )
+
+    def _raise_if_error(
+        self, symbol_infos: dict[str, tuple[AdsErrorCode, SymbolInfo]]
+    ) -> None:
+        """
+        Generate a human-readable error message for symbol read errors.
+        """
+        symbol_errors = [
+            (error_code, name)
+            for name, (error_code, _) in symbol_infos.items()
+            if error_code != 0
+        ]
+        exceptions: list[AdsCommandError] = []
+        for error_code, symbol_name in symbol_errors:
+            symbol_path = symbol_name.replace(".", " → ")
+            exceptions.append(AdsCommandError(error_code, symbol_path))
+
+        if exceptions:
+            raise ExceptionGroup(
+                "One or more symbol read errors occurred", exceptions)
+
+    async def read_symbols_by_names(
+        self, symbol_names: set[str], raise_errors: bool = True
+    ) -> dict[str, SymbolReadResult]:
+        """
+        Read multiple symbols by their names from the ADS device.
+        """
+        symbol_infos = await self._cache.read_symbol_infos_by_names(symbol_names)
+        if raise_errors:
+            self._raise_if_error(symbol_infos)
+
+        read_commands = [
+            AdsReadCommand(
+                transport=self.transport,
+                ams_address=self.dst_address,
+                idx_group=symbol_info.idx_group,
+                idx_offset=symbol_info.idx_offset,
+                length=symbol_info.idx_length,
+            )
+            for _, symbol_info in symbol_infos.values()
+        ]
+        function = AdsSumRead(
+            transport=self.transport,
+            ams_address=self.dst_address,
+            commands=read_commands,
+        )
+
+        response = await function.execute()
+        output: dict[str, SymbolReadResult] = {}
+
+        tasks = []
+        for (_, resp_payload), (error_code, symbol_info) in zip(
+            response, symbol_infos.values()
+        ):
+            tasks.append(
+                asyncio.get_running_loop().run_in_executor(
+                    self.parser_pool,
+                    self.parser.parse,
+                    symbol_info.data_type,
+                    symbol_info.type_name,
+                    resp_payload,
+                )
+            )
+        parsed = await asyncio.gather(*tasks)
+
+        for symbol_data, (error_code, symbol_info) in zip(parsed, symbol_infos.values()):
+            output[symbol_info.symbol_name] = SymbolReadResult(
+                error_code, symbol_data)
+
+        return output
+
+    @asynccontextmanager
+    async def subscribe_notification(
+        self,
+        symbol_name: str,
+        callback: TNotificationCallback,
+        mode: TransmissionMode = TransmissionMode.CYCLIC,
+        cycle_time: int = 50,
+        max_delay: int = 100,
+    ):
+        """
+        Subscribe to notifications for a symbol by its name.
+        """
+        async with self._notification.create_notification(
+            symbol_name,
+            callback,
+            mode,
+            cycle_time,
+            max_delay,
+        ) as notification_handle:
+            yield notification_handle

aioads/ads_error_codes.py

@@ -0,0 +1,160 @@
+"""
+ADS Error Codes Module
+https://infosys.beckhoff.com/english.php?content=../content/1033/tcadscommon/12440276875.html&id=
+"""
+
+
+class AdsErrorCodes:  # pylint: disable=too-few-public-methods
+    """
+    ADS Error Codes for ADS protocol communication.
+    """
+
+    ERROR_CODES = {
+        0: "no error",
+        1: "Internal error",
+        2: "No Rtime",
+        3: "Allocation locked memory error",
+        4: "Insert mailbox er",
+        5: "Wrong receive HMSG",
+        6: "target port not found   ADS Server not started",
+        7: "target machine not found    Missing ADS routes",
+        8: "Unknown command ID",
+        9: "Bad task ID",
+        10: "No IO",
+        11: "Unknown ADS command",
+        12: "Win 32 error",
+        13: "Port not connected",
+        14: "Invalid ADS length",
+        15: "Invalid ADS Net ID",
+        16: "Low Installation level",
+        17: "No debug available",
+        18: "Port disabled",
+        19: "Port already connected",
+        20: "ADS Sync Win32 error",
+        21: "ADS Sync Timeout",
+        22: "ADS Sync AMS error",
+        23: "ADS Sync no index map",
+        24: "Invalid ADS port",
+        25: "No memory",
+        26: "TCP send error",
+        27: "Host unreachable",
+        28: "Invalid AMS fragm",
+        1280: "ROUTERERR_NOLOCKEDMEMORY",
+        1281: "ROUTERERR_RESIZEMEMORY",
+        1282: "ROUTERERR_MAILBOXFULL",
+        1283: "ROUTERERR_DEBUGBOXFULL",
+        1284: "ROUTERERR_UNKNOWNPORTTYPE",
+        1285: "ROUTERERR_NOTINITIALIZED",
+        1286: "ROUTERERR_PORTALREADYINUSE",
+        1287: "ROUTERERR_NOTREGISTERED",
+        1288: "ROUTERERR_NOMOREQUEUES",
+        1289: "ROUTERERR_INVALIDPORT",
+        1290: "ROUTERERR_NOTACTIVATED",
+        1291: "ROUTERERR_FRAGMENTBOXFULL",
+        1292: "ROUTERERR_FRAGMENTTIMEOUT",
+        1293: "ROUTERERR_TOBEREMOVED",
+        1792: "error class <device error>",
+        1793: "Service is not supported by server",
+        1794: "invalid index group",
+        1795: "invalid index offset",
+        1796: "reading/writing not permitted",
+        1797: "parameter size not correct",
+        1798: "invalid parameter value(s)",
+        1799: "device is not in a ready state",
+        1800: "device is busy",
+        1801: "invalid context (must be in Windows)",
+        1802: "out of memory",
+        1803: "invalid parameter value(s)",
+        1804: "not found (files, ...)",
+        1805: "syntax error in command or file",
+        1806: "objects do not match",
+        1807: "object already exists",
+        1808: "symbol not found",
+        1809: "symbol version invalid. Onlinechange. Release handle and get a new one",
+        1810: "server is in invalid state",
+        1811: "AdsTransMode not supported",
+        1812: "Notification handle is invalid. Onlinechange. Release handle and get a new one",  # noqa: E501
+        1813: "Notification client not registered",
+        1814: "no more notification handles",
+        1815: "size for watch too big",
+        1816: "device not initialized",
+        1817: "device has a timeout",
+        1818: "query interface failed",
+        1819: "wrong interface required",
+        1820: "class ID is invalid",
+        1821: "object ID is invalid",
+        1822: "requests is pending",
+        1823: "requests is aborted",
+        1824: "signal warning",
+        1825: "invalid array index",
+        1826: "symbol not active. Onlinechange. Release handle and get a new one",
+        1827: "access denied",
+        1828: "missing license. Activate license for TwinCAT 3 function",
+        1836: "exception occurred during system start. Check each device transistions",
+        1856: "Error class <client error>",
+        1857: "invalid parameter at service",
+        1858: "polling list is empty",
+        1859: "var connection already in use",
+        1860: "invoke ID in use",
+        1861: "timeout elapsed",
+        1862: "error in win32 subsystem",
+        1863: "Invalid client timeout value",
+        1864: "ads-port not opened",
+        1872: "internal error in ads sync",
+        1873: "hash table overflow",
+        1874: "key not found in hash",
+        1875: "no more symbols in cache",
+        1876: "invalid response received",
+        1877: "sync port is locked",
+        4096: "RTERR_INTERNAL",
+        4097: "RTERR_BADTIMERPERIODS",
+        4098: "RTERR_INVALIDTASKPTR",
+        4099: "RTERR_INVALIDSTACKPTR",
+        4100: "RTERR_PRIOEXISTS",
+        4101: "RTERR_NOMORETCB",
+        4102: "RTERR_NOMORESEMAS",
+        4103: "RTERR_NOMOREQUEUES",
+        4104: "TwinCAT reserved 1.",
+        4105: "TwinCAT reserved 2.",
+        4106: "TwinCAT reserved 3.",
+        4107: "TwinCAT reserved 4.",
+        4108: "TwinCAT reserved 5.",
+        4109: "RTERR_EXTIRQALREADYDEF",
+        4110: "RTERR_EXTIRQNOTDEF",
+        4111: "RTERR_EXTIRQINSTALLFAILED",
+        4112: "RTERR_IRQLNOTLESSOREQUAL",
+        4119: "RTERR_VMXNOTSUPPORTED",
+        4120: "RTERR_VMXDISABLED",
+        4121: "RTERR_VMXCONTROLSMISSING",
+        4122: "RTERR_VMXENABLEFAILS",
+        10060: "A socket operation was attempted to an unreachable host",
+        10061: "A connection attempt failed because the connected party did not properly respond after a "
+        "period of time, or established connection failed because connected host has failed to respond.",
+        # noqa: E501
+        10065: "No connection could be made because the target machine actively refused it",
+    }
+
+    @classmethod
+    def description(cls, error_code: int) -> str:
+        """
+        Get the description for a given ADS error code.
+        """
+        return cls.ERROR_CODES.get(error_code, "Unknown error code")
+
+
+class AdsErrorCode(int):
+    """ADS Error Code with description property"""
+
+    @property
+    def description(self) -> str:
+        """
+        Get the description for this ADS error code.
+        """
+        return AdsErrorCodes.description(self)
+
+    @property
+    def ok(self) -> bool:
+        """
+        Check if the error code represents a successful operation (error code 0).
+        """
+        return self == 0

aioads/ads_notifications.py

@@ -0,0 +1,203 @@
+"""
+This module is still just a POC to verify the general functionality of ads notifications. 
+We want to add default monitoring of plc cycle usage to automatically disable notifications before
+we are the reason of cycle time violations. 
+
+Future Features: 
+    - Queueing of messages
+    - parallel parsing of notifications (plc tasks are faster as we can parse)
+    - QOS for queueing and parsing ? 
+
+"""
+import asyncio
+import logging
+from collections import defaultdict
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any
+from typing import AsyncGenerator
+from typing import Callable
+from typing import Coroutine
+
+from aioads.ads_symbol_cache import AdsSymbolCache
+from aioads.ads_symbol_parser import AdsSymbolParser
+from aioads.ams_address import AmsAddress
+from aioads.ams_header import AmsHeader
+from aioads.commands.ads_add_notification import (
+    AdsAddNotificationCommand, TransmissionMode
+)
+from aioads.commands.ads_delete_notification import AdsDeleteNotificationCommand
+from aioads.functions.ads_symbol_info_by_name_ex import SymbolInfo
+from aioads.stream import AdsStream
+from aioads.transport import ITransport
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationValue:
+    """
+    The callback value for parsed notifications
+    """
+    handle: int
+    timestamp: int
+    value: Any
+
+
+TNotificationCallback = Callable[[
+    list[NotificationValue]], Coroutine[None, None, None]]
+
+
+class NotificationManager:
+    """
+    The notification manager is still in progress,
+    the notification manager is responsible to ensure a proper cleanup of all
+    not longer used notification subscriptions and distribution of parsed notifications
+    """
+
+    MAX_SUBSCRIPTIONS = 100  # Beckhoff PLCs support up to 500 notifications
+
+    def __init__(
+        self,
+        transport: ITransport,
+        dst_address: AmsAddress,
+        symbol_cache: AdsSymbolCache,
+        parser: AdsSymbolParser,
+    ):
+        self._logger = logging.getLogger(__name__)
+        self.transport = transport
+        self.transport.set_notification_callback(self.on_notification_received)
+        self.dst_address = dst_address
+        self.symbol_cache = symbol_cache
+        self.symbol_parser = parser
+        self._callback_handles: dict[int,
+                                     tuple[TNotificationCallback, SymbolInfo]] = {}
+        self._remove_tasks: dict[int, asyncio.Task] = {}
+
+    async def _create_notification(
+        self,
+        symbol_info: SymbolInfo,
+        mode: TransmissionMode,
+        cycle_time: int,
+        max_delay: int,
+    ) -> int:
+        """
+        Add a notification and return the id of the new created handle
+        """
+
+        function = AdsAddNotificationCommand(
+            transport=self.transport,
+            ams_address=self.dst_address,
+            idx_group=symbol_info.idx_group,
+            idx_offset=symbol_info.idx_offset,
+            length=symbol_info.idx_length,
+            transmission_mode=mode,
+            max_delay=max_delay,
+            cycle_time=cycle_time,
+        )
+        response = await function.request()
+        self._logger.info(
+            "Created notification handle %d for symbol %s",
+            response.notification_handle,
+            symbol_info.symbol_name,
+        )
+        return response.notification_handle
+
+    async def _remove_notification(self, notification_handle: int) -> None:
+        """
+        Remove a notification by the handle
+        """
+        function = AdsDeleteNotificationCommand(
+            transport=self.transport,
+            ams_address=self.dst_address,
+            notification_handle=notification_handle,
+        )
+        await function.request()
+        self._remove_tasks.pop(notification_handle, None)
+        self._logger.info(
+            "Removed notification handle %d scheduled size %d",
+            notification_handle,
+            len(self._remove_tasks),
+        )
+
+    async def parse_notification_payload(
+        self, payload: AdsStream
+    ) -> AsyncGenerator[tuple[int, int, Any], None]:
+        """
+        Handle the parsing of the notifications
+        """
+
+        unknown_handles: set[int] = set()
+
+        _length = int.from_bytes(payload.read(4), "little")
+        stamp_count = int.from_bytes(payload.read(4), "little")
+
+        for _ in range(stamp_count):
+            timestamp = int.from_bytes(payload.read(8), "little")
+            samples = int.from_bytes(payload.read(4), "little")
+            for _ in range(samples):
+                notification_handle = int.from_bytes(payload.read(4), "little")
+                sample_size = int.from_bytes(payload.read(4), "little")
+                handler = self._callback_handles.get(notification_handle)
+                if not handler:
+                    unknown_handles.add(notification_handle)
+                    # Skip unknown notification
+                    payload.seek(payload.tell() + sample_size)
+                    continue
+                _, symbol_info = handler
+                value = self.symbol_parser.parse(
+                    symbol_info.data_type, symbol_info.type_name, payload
+                )
+                yield notification_handle, timestamp, value
+
+        for handle in unknown_handles:
+            self._logger.warning(
+                "Received notification for unknown handle %d",
+                handle,
+            )
+            await self._remove_notification(handle)
+
+    async def on_notification_received(self, _ams_header: AmsHeader, payload: AdsStream) -> None:
+        """
+        handler for the raw notification events that need parsing and distribution
+        """
+
+        notifications: list[NotificationValue] = []
+
+        async for handle, timestamp, value in self.parse_notification_payload(payload):
+            notifications.append(NotificationValue(handle, timestamp, value))
+
+        grouped_by_handle: dict[int,
+                                list[NotificationValue]] = defaultdict(list)
+        for notification in notifications:
+            grouped_by_handle[notification.handle].append(notification)
+
+        async with asyncio.TaskGroup() as tg:
+            for handle, notification_group in grouped_by_handle.items():
+                callback, _ = self._callback_handles[handle]
+                tg.create_task(callback(notification_group))
+
+    @asynccontextmanager
+    async def create_notification(
+        self,
+        symbol_name: str,
+        callback: TNotificationCallback,
+        mode: TransmissionMode,
+        cycle_time: int,
+        max_delay: int,
+    ) -> AsyncGenerator[int, None]:
+        """contextmanager to subscribe to variables that ensures we always remove
+        the unstd subscriptions.
+        """
+
+        if len(self._callback_handles) >= self.MAX_SUBSCRIPTIONS:
+            raise ValueError("Maximum number of notifications reached")
+
+        symbol_info = await self.symbol_cache.read_symbol_info_by_name(symbol_name)
+        notification_handle = await self._create_notification(
+            symbol_info, mode, cycle_time, max_delay
+        )
+        try:
+            self._callback_handles[notification_handle] = (
+                callback, symbol_info)
+            yield notification_handle
+        finally:
+            await self._remove_notification(notification_handle)