aioads 0.1.0.dev4__tar.gz → 0.1.0.dev5__tar.gz

{aioads-0.1.0.dev4 → aioads-0.1.0.dev5}/.gitignore

@@ -160,3 +160,6 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# Local integration test endpoint configuration
+tests/integration/config.toml

{aioads-0.1.0.dev4 → aioads-0.1.0.dev5}/.vscode/settings.json

@@ -10,5 +10,14 @@
     },
     "terminal.integrated.env.windows": {
         "PYTHONPATH": "${workspaceFolder}"
-    }
+    },
+    "python.testing.unittestArgs": [
+        "-v",
+        "-s",
+        "./tests",
+        "-p",
+        "test*.py"
+    ],
+    "python.testing.pytestEnabled": false,
+    "python.testing.unittestEnabled": true
 }

{aioads-0.1.0.dev4 → aioads-0.1.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aioads
-Version: 0.1.0.dev4
+Version: 0.1.0.dev5
 Summary: An asynchronous Python library for communicating with Beckhoff TwinCAT PLCs
 Author-email: MkKiefer <102972583+MkKiefer@users.noreply.github.com>
 License: MIT
@@ -49,33 +49,34 @@ pip install aioads[aiomqtt]
 ```python
 import asyncio
 from aioads import AdsClient, AmsAddress
+from aioads.ams_service_port import AmsServicePort
 
 async def main():
     # Create client
     client = AdsClient.create_tcp(
         src=AmsAddress(net_id="192.168.1.100.1.1", port=1234),
-        dst=AmsAddress(net_id="192.168.1.200.1.1", port=851),
+        dst=AmsAddress(net_id="192.168.1.200.1.1", port=AmsServicePort.TC3_RUNTIME_1),
         ip="192.168.1.200",
         port=48898,
     )
-    
+
     try:
         # Connect to PLC
         await client.connect()
-        
+
         # Read device state
         state = await client.read_state()
         print(f"PLC State: {state.ads_state.name}")
-        
+
         # Read single symbol
         value = await client.read_symbol_by_name("MAIN.MyVariable")
         print(f"Value: {value}")
-        
+
         # Read multiple symbols efficiently
         symbols = ["MAIN.Var1", "MAIN.Var2", "MAIN.Var3"]
         values = await client.read_symbols_by_names(symbols)
         print(f"Values: {values}")
-        
+
     finally:
         await client.disconnect()
 
@@ -121,7 +122,7 @@ Efficiently read multiple symbols in a single operation:
 # Prepare symbol list
 symbols_to_read = {
     "MAIN.Temperature",
-    "MAIN.Pressure", 
+    "MAIN.Pressure",
     "MAIN.FlowRate",
     "MAIN.Status.Running",
     "MAIN.Recipe.CurrentStep"
@@ -191,7 +192,7 @@ async def read_diagnostics(client, diag_symbols):
 async def main():
     client = AdsClient.create_tcp(...)
     await client.connect()
-    
+
     try:
         # Run multiple concurrent tasks
         async with asyncio.TaskGroup() as tg:
@@ -223,14 +224,12 @@ Full support for TwinCAT data types:
 - **Complex Types**: Custom user-defined types
 - **Arrays**: Multi-dimensional arrays with proper indexing
 
-
 ## Requirements
 
 - Python 3.11+
 - asyncio
 - aiomqtt (optional)
 
-
 ## Disclaimer
 
 This project is an independent, open‑source implementation of the ADS (Automation Device Specification) protocol. It is not affiliated with, endorsed by, or supported by Beckhoff Automation GmbH & Co. KG, the developer of TwinCAT and the ADS protocol.
@@ -252,7 +251,6 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 
 1. **PLC State**: Ensure PLC is in RUN mode for symbol access
 
-
 ## Contributing guidelines
 
 AIOADS is a personal hobby project, developed and maintained in my spare time.

{aioads-0.1.0.dev4 → aioads-0.1.0.dev5}/README.md

@@ -35,33 +35,34 @@ pip install aioads[aiomqtt]
 ```python
 import asyncio
 from aioads import AdsClient, AmsAddress
+from aioads.ams_service_port import AmsServicePort
 
 async def main():
     # Create client
     client = AdsClient.create_tcp(
         src=AmsAddress(net_id="192.168.1.100.1.1", port=1234),
-        dst=AmsAddress(net_id="192.168.1.200.1.1", port=851),
+        dst=AmsAddress(net_id="192.168.1.200.1.1", port=AmsServicePort.TC3_RUNTIME_1),
         ip="192.168.1.200",
         port=48898,
     )
-    
+
     try:
         # Connect to PLC
         await client.connect()
-        
+
         # Read device state
         state = await client.read_state()
         print(f"PLC State: {state.ads_state.name}")
-        
+
         # Read single symbol
         value = await client.read_symbol_by_name("MAIN.MyVariable")
         print(f"Value: {value}")
-        
+
         # Read multiple symbols efficiently
         symbols = ["MAIN.Var1", "MAIN.Var2", "MAIN.Var3"]
         values = await client.read_symbols_by_names(symbols)
         print(f"Values: {values}")
-        
+
     finally:
         await client.disconnect()
 
@@ -107,7 +108,7 @@ Efficiently read multiple symbols in a single operation:
 # Prepare symbol list
 symbols_to_read = {
     "MAIN.Temperature",
-    "MAIN.Pressure", 
+    "MAIN.Pressure",
     "MAIN.FlowRate",
     "MAIN.Status.Running",
     "MAIN.Recipe.CurrentStep"
@@ -177,7 +178,7 @@ async def read_diagnostics(client, diag_symbols):
 async def main():
     client = AdsClient.create_tcp(...)
     await client.connect()
-    
+
     try:
         # Run multiple concurrent tasks
         async with asyncio.TaskGroup() as tg:
@@ -209,14 +210,12 @@ Full support for TwinCAT data types:
 - **Complex Types**: Custom user-defined types
 - **Arrays**: Multi-dimensional arrays with proper indexing
 
-
 ## Requirements
 
 - Python 3.11+
 - asyncio
 - aiomqtt (optional)
 
-
 ## Disclaimer
 
 This project is an independent, open‑source implementation of the ADS (Automation Device Specification) protocol. It is not affiliated with, endorsed by, or supported by Beckhoff Automation GmbH & Co. KG, the developer of TwinCAT and the ADS protocol.
@@ -238,7 +237,6 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 
 1. **PLC State**: Ensure PLC is in RUN mode for symbol access
 
-
 ## Contributing guidelines
 
 AIOADS is a personal hobby project, developed and maintained in my spare time.

{aioads-0.1.0.dev4 → aioads-0.1.0.dev5}/aioads/ads_client.py

@@ -1,8 +1,6 @@
 """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
@@ -59,9 +57,6 @@ class AdsClient:
         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(
@@ -93,7 +88,9 @@ class AdsClient:
         )
 
     @classmethod
-    def create_from_transport(cls, dst: AmsAddress, transport: ITransport) -> "AdsClient":
+    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
@@ -151,7 +148,7 @@ class AdsClient:
 
     async def enable_route(self, route_name: str, enabled: bool):
         """
-        Enable or disable a ads route. 
+        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`
         """
@@ -160,7 +157,7 @@ class AdsClient:
             self.transport,
             self.dst_address,
             route_name,
-            RouteSwitch.ROUTE_ENABLE_TMP if enabled else RouteSwitch.ROUTE_DISABLE_TMP
+            RouteSwitch.ROUTE_ENABLE_TMP if enabled else RouteSwitch.ROUTE_DISABLE_TMP,
         )
         response = await request.execute()
         if not response.error_code.ok:
@@ -258,8 +255,7 @@ class AdsClient:
             exceptions.append(AdsCommandError(error_code, symbol_path))
 
         if exceptions:
-            raise ExceptionGroup(
-                "One or more symbol read errors occurred", 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
@@ -274,64 +270,53 @@ class AdsClient:
         if raise_errors:
             self._raise_if_error(symbol_infos)
 
-        output: dict[str, SymbolReadResult] = {}
-
-        # Only symbols whose info resolved successfully can be read. Symbols
-        # with a lookup error are reported as-is; building a read command from
-        # their (invalid) index group/offset would misalign the bulk response.
-        readable: list[tuple[str, SymbolInfo]] = []
-        for requested_name, (error_code, symbol_info) in symbol_infos.items():
-            if not error_code.ok:
-                output[requested_name] = SymbolReadResult(error_code, None)
-            else:
-                readable.append((requested_name, symbol_info))
-
+        # Pre-seed the result with lookup errors so the output preserves the
+        # requested order; successful entries are overwritten after the read.
+        # Symbols with a failed lookup cannot be read: their idx_group/offset
+        # would misalign the bulk response.
+        output: dict[str, SymbolReadResult] = {
+            name: SymbolReadResult(error_code, None)
+            for name, (error_code, _) in symbol_infos.items()
+        }
+        readable = [
+            (name, info)
+            for name, (error_code, info) in symbol_infos.items()
+            if error_code.ok
+        ]
         if not readable:
             return output
 
-        function = AdsSumRead(
+        sum_read = AdsSumRead(
             transport=self.transport,
             ams_address=self.dst_address,
             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,
+                    idx_group=info.idx_group,
+                    idx_offset=info.idx_offset,
+                    length=info.idx_length,
                 )
-                for _, symbol_info in readable
+                for _, info in readable
             ],
         )
-        response = await function.execute()
+        response = await sum_read.execute()
 
-        loop = asyncio.get_running_loop()
-        parse_names: list[str] = []
-        tasks = []
-        for (requested_name, symbol_info), (read_response, resp_payload) in zip(
-            readable, response
+        for (name, info), (read_response, resp_payload) in zip(
+            readable, response, strict=True
         ):
-            # A failed read yields no usable payload, so skip parsing it.
-            if read_response.error_code != 0:
-                output[requested_name] = SymbolReadResult(
-                    read_response.error_code, None)
+            if not read_response.error_code.ok:
+                output[name] = SymbolReadResult(read_response.error_code, None)
                 continue
-            parse_names.append(requested_name)
-            tasks.append(
-                loop.run_in_executor(
-                    self.parser_pool,
-                    self.parser.parse,
-                    symbol_info.data_type,
-                    symbol_info.type_name,
-                    resp_payload,
-                )
+            output[name] = SymbolReadResult(
+                AdsErrorCode(0),
+                self.parser.parse(
+                    data_type=info.data_type,
+                    type_name=info.type_name,
+                    raw_data=resp_payload,
+                ),
             )
 
-        parsed = await asyncio.gather(*tasks)
-        for requested_name, symbol_data in zip(parse_names, parsed):
-            output[requested_name] = SymbolReadResult(
-                AdsErrorCode(0), symbol_data)
-
         return output
 
     @asynccontextmanager

{aioads-0.1.0.dev4 → aioads-0.1.0.dev5}/aioads/ams_address.py

@@ -11,7 +11,7 @@ config:
         rowHeight: 45
         bitWidth: 32
         bitsPerRow: 8
-        showBits: ture
+        showBits: true
 ---
 packet
 +6: "AMSNetId (6 bytes)"

{aioads-0.1.0.dev4 → aioads-0.1.0.dev5}/aioads/ams_header.py

@@ -10,7 +10,7 @@ config:
         rowHeight: 40
         bitWidth: 80
         bitsPerRow: 8
-        showBits: ture
+        showBits: true
 ---
 packet
 +6: "AMSNetId Target (6 bytes)"

aioads-0.1.0.dev5/aioads/ams_service_port.py

@@ -0,0 +1,83 @@
+"""AMS service port constants used to address well-known endpoints on a target."""
+
+from enum import IntEnum
+
+
+class AmsServicePort(IntEnum):
+    """Well-known AMS service port numbers used in AMS/ADS communication."""
+
+    # --- Core / Router ---
+    ADS_ROUTER = 1
+    AMS_DEBUGGER = 2
+    LICENSE_SERVER = 30
+
+    # --- Logging / Events ---
+    LOGGER = 100
+    EVENT_LOGGER = 110
+    EVENT_LOGGER_USER_V2 = 130
+    EVENT_LOGGER_RT_V2 = 131
+    EVENT_LOGGER_PUBLISHER_V2 = 132
+
+    # --- System / Core Services ---
+    SYSTEM_SERVICE = 10000
+    TCPIP_SERVER = 10201
+    SYSTEM_MANAGER = 10300
+    SMS_SERVER = 10400
+    MODBUS_SERVER = 10500
+    AMS_LOGGER = 10502
+    XML_DATA_SERVER = 10600
+    AUTO_CONFIGURATION = 10700
+    PLC_CONTROL = 10800
+    FTP_CLIENT = 10900
+
+    # --- NC / Motion / Automation ---
+    NC_CONTROL = 11000
+    NC_INTERPRETER = 11500
+    GST_INTERPRETER = 11600
+    TRACK_CONTROL = 12000
+    CAM_CONTROL = 13000
+
+    # --- Monitoring / Diagnostics ---
+    SCOPE_SERVER = 14000
+    CONDITION_MONITORING = 14100
+
+    # --- Communication / Integration ---
+    CONTROL_NET = 16000
+    OPC_SERVER = 17000
+    OPC_CLIENT = 17500
+    MAIL_SERVER = 18000
+
+    # --- Management / Infrastructure ---
+    MGMT_SERVER = 19100
+    HMI_SERVER = 19800
+    DATABASE_SERVER = 21372
+
+    # --- PLC Runtime (TwinCAT 2) ---
+    TC2_PLC = 800
+    TC2_RUNTIME_1 = 801
+    TC2_RUNTIME_2 = 811
+    TC2_RUNTIME_3 = 821
+    TC2_RUNTIME_4 = 831
+
+    # --- PLC Runtime (TwinCAT 3) ---
+    TC3_PLC_BASE = 850
+    TC3_RUNTIME_1 = 851
+    TC3_RUNTIME_2 = 852
+    TC3_RUNTIME_3 = 853
+    TC3_RUNTIME_4 = 854
+
+    # --- Real-time / Ring 0 ---
+    R0_REALTIME = 200
+    R0_TRACE = 290
+    R0_IO = 300
+    R0_PLC_LEGACY = 400
+    R0_NC = 500
+    R0_NC_SAF = 501
+    NC_INSTANCE = 520
+    R0_CNC = 600
+    R0_LINE = 700
+
+    # --- Misc / Optional services ---
+    CAM_CONTROLLER = 900
+    CAM_TOOL = 950
+    FTP = 10900  # alias

{aioads-0.1.0.dev4 → aioads-0.1.0.dev5}/aioads/ams_tcp_header.py

@@ -10,7 +10,7 @@ config:
         rowHeight: 40
         bitWidth: 80
         bitsPerRow: 8
-        showBits: ture
+        showBits: true
 ---
 packet
 +2: "reserved (2 bytes)"

{aioads-0.1.0.dev4 → aioads-0.1.0.dev5}/aioads/functions/ads_enable_route.py

@@ -9,7 +9,7 @@ config:
         rowHeight: 40
         bitWidth: 80
         bitsPerRow: 8
-        showBits: ture
+        showBits: true
 ---
 packet
 +4: "IndexGroup = 808 (4 bytes)"
@@ -25,7 +25,7 @@ IndexOffset values:
 4 = ADS_ROUTE_ENABLE_TMP    (temporary)
 
 
-Example of a route config `/3.1/Target/Routes/<route.xml>` 
+Example of a route config `/3.1/Target/Routes/<route.xml>`
 ```
 <!-- Route configuration example -->
 <Mqtt Disabled="true">
@@ -35,12 +35,13 @@ Example of a route config `/3.1/Target/Routes/<route.xml>`
 </Mqtt>
 ```
 
-Expected route name string: `MQTT:MyBroker` 
+Expected route name string: `MQTT:MyBroker`
 """
 
 from enum import IntEnum
 
 from aioads.ams_address import AmsAddress
+from aioads.ams_service_port import AmsServicePort
 from aioads.commands.ads_write import AdsWriteCommand, AdsWriteResponse
 from aioads.functions.ads_function import AdsFunctionSymbolGroup, IAdsFunction
 from aioads.transport import ITransport
@@ -48,9 +49,10 @@ from aioads.transport import ITransport
 
 class RouteSwitch(IntEnum):
     """
-    Enum (index offset) to control the state of a route. 
-    A route can temporarily enabled / disabled and gets reset after a restart of the runtime. 
+    Enum (index offset) to control the state of a route.
+    A route can temporarily enabled / disabled and gets reset after a restart of the runtime.
     """
+
     ROUTE_DISABLE = 1
     ROUTE_ENABLE = 2
     ROUTE_DISABLE_TMP = 3
@@ -69,16 +71,19 @@ class AdsEnableRoute(IAdsFunction[AdsWriteResponse]):
     or if a name in the mqtt route config section is defined
     `MQTT:<RouteName>`
 
-    I think that this interface allows the same for the default router but i have not tested it yet. 
+    I think that this interface allows the same for the default router but i have not tested it yet.
     """
 
-    SYSTEM_SERVICE_PORT = 10000
-
-    def __init__(self, transport: ITransport, ams_address: AmsAddress, route: str, switch: RouteSwitch) -> None:
+    def __init__(
+        self,
+        transport: ITransport,
+        ams_address: AmsAddress,
+        route: str,
+        switch: RouteSwitch,
+    ) -> None:
         # We modify the port here as this function only works on the system service
         self.modified_address = AmsAddress(
-            net_id=ams_address.net_id,
-            port=self.SYSTEM_SERVICE_PORT
+            net_id=ams_address.net_id, port=AmsServicePort.SYSTEM_SERVICE
         )
         self.transport = transport
         self.route = route
@@ -94,6 +99,6 @@ class AdsEnableRoute(IAdsFunction[AdsWriteResponse]):
             ams_address=self.modified_address,
             idx_group=AdsFunctionSymbolGroup.ADSIGRP_TOGGLE_ROUTE_ENABLE,
             idx_offset=self.switch.value,
-            payload=self.serialize()
+            payload=self.serialize(),
         )
         return await command.request()

{aioads-0.1.0.dev4 → aioads-0.1.0.dev5}/aioads/functions/ads_sum_read_write.py

@@ -12,7 +12,7 @@ config:
         rowHeight: 40
         bitWidth: 80
         bitsPerRow: 8
-        showBits: ture
+        showBits: true
 ---
 packet
 +4: "1 - idx group (4 bytes)"
@@ -37,7 +37,7 @@ config:
         rowHeight: 40
         bitWidth: 80
         bitsPerRow: 8
-        showBits: ture
+        showBits: true
 ---
 packet
 +4: "1 - error code (4 bytes)"

{aioads-0.1.0.dev4 → aioads-0.1.0.dev5}/aioads/functions/ads_symbol_datatype_by_name.py

@@ -10,7 +10,7 @@ config:
         rowHeight: 40
         bitWidth: 80
         bitsPerRow: 8
-        showBits: ture
+        showBits: true
 ---
 packet
 +4: "entry length (4 bytes)"
@@ -37,6 +37,8 @@ packet
 
 """
 from dataclasses import dataclass
+from struct import Struct
+from typing import ClassVar
 from aioads.ams_address import AmsAddress
 from aioads.commands.ads_read_write import AdsReadWriteCommand
 from aioads.functions.ads_function import AdsFunctionSymbolGroup, IAdsFunction
@@ -57,6 +59,8 @@ class AdsDatatypeArrayInfo:
     l_bound: int
     e_elements: int
 
+    STRUCT_DEF: ClassVar[Struct] = Struct("<II")
+
     def serialize(self) -> bytes:
         """
         serialize the `AdsDatatypeArrayInfo` to bytes
@@ -71,8 +75,8 @@ class AdsDatatypeArrayInfo:
         """
         Create `AdsDatatypeArrayInfo` from the `AdsStream`
         """
-        l_bound = int.from_bytes(data.read_view(4), byteorder="little")
-        e_elements = int.from_bytes(data.read_view(4), byteorder="little")
+        l_bound, e_elements = data.read_struct(
+            AdsDatatypeArrayInfo.STRUCT_DEF)
         return AdsDatatypeArrayInfo(
             l_bound=l_bound,
             e_elements=e_elements,
@@ -98,6 +102,11 @@ class SymbolDataTypeResponse:
     array: list[AdsDatatypeArrayInfo]
     sub_items: list["SymbolDataTypeResponse"]
 
+    # entry_length, version, hash_value, type_hash_value, size, offs,
+    # data_type, flags, name_length, type_name_length, comment_length,
+    # array_dim, sub_items_count
+    FIXED_STRUCT: ClassVar[Struct] = Struct("<8I5H")
+
     def serialize(self) -> bytes:
         """
         Serialize the SymbolDataTypeResponse into bytes.
@@ -141,25 +150,24 @@ class SymbolDataTypeResponse:
         """
 
         start_pos = data.tell()
-        entry_length = int.from_bytes(data.read_view(4), byteorder="little")
-        version = int.from_bytes(data.read_view(4), byteorder="little")
-        hash_value = int.from_bytes(data.read_view(4), byteorder="little")
-        type_hash_value = int.from_bytes(data.read_view(4), byteorder="little")
-        size = int.from_bytes(data.read_view(4), byteorder="little")
-        offs = int.from_bytes(data.read_view(4), byteorder="little")
-        data_type = AdsSymbolDataType.from_bytes(
-            data.read_view(4), byteorder="little")
-        flags = AdsSymbolFlags.from_bytes(
-            data.read_view(4), byteorder="little")
-        name_length = int.from_bytes(data.read_view(2), byteorder="little") + 1
-        type_length = int.from_bytes(data.read_view(2), byteorder="little") + 1
-        comment_length = int.from_bytes(
-            data.read_view(2), byteorder="little") + 1
-        array_dim = int.from_bytes(data.read_view(2), byteorder="little")
-        sub_items_cnt = int.from_bytes(data.read_view(2), byteorder="little")
-        name = data.read(name_length).rstrip(b"\x00").decode("cp1252")
-        type_name = data.read(type_length).rstrip(b"\x00").decode("cp1252")
-        comment = data.read(comment_length).rstrip(b"\x00").decode("cp1252")
+        (
+            entry_length,
+            version,
+            hash_value,
+            type_hash_value,
+            size,
+            offs,
+            data_type,
+            flags,
+            name_length,
+            type_length,
+            comment_length,
+            array_dim,
+            sub_items_cnt,
+        ) = data.read_struct(SymbolDataTypeResponse.FIXED_STRUCT)
+        name = data.read(name_length + 1).rstrip(b"\x00").decode("cp1252")
+        type_name = data.read(type_length + 1).rstrip(b"\x00").decode("cp1252")
+        comment = data.read(comment_length + 1).rstrip(b"\x00").decode("cp1252")
         array_info: list[AdsDatatypeArrayInfo] = []
         for _ in range(array_dim):
             array_info.append(AdsDatatypeArrayInfo.deserialize(data))
@@ -176,8 +184,8 @@ class SymbolDataTypeResponse:
             type_hash_value=type_hash_value,
             size=size,
             offs=offs,
-            data_type=data_type,
-            flags=flags,
+            data_type=AdsSymbolDataType(data_type),
+            flags=AdsSymbolFlags(flags),
             name=name,
             type_name=type_name,
             comment=comment,