aioads 0.1.0.dev3__tar.gz → 0.1.0.dev5__tar.gz

aioads-0.1.0.dev5/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  # Keep the SHA-pinned GitHub Actions current (Dependabot updates both the
+  # pinned SHA and the trailing version comment).
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  # Python dev/runtime dependencies tracked in pdm.lock / pyproject.toml.
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]

aioads-0.1.0.dev5/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up PDM
+        uses: pdm-project/setup-pdm@973541a5febeafcfdadf8a51211435be6ecfd90f  # v4.5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: true
+
+      - name: Install dependencies
+        run: pdm install
+
+      - name: Lint
+        run: pdm run lint
+
+      - name: Run tests with coverage
+        run: pdm run coverage
+
+      - name: Upload coverage artifact
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: ignore

aioads-0.1.0.dev5/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Avoid two releases racing to publish the same version.
+concurrency:
+  group: publish-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up PDM
+        uses: pdm-project/setup-pdm@973541a5febeafcfdadf8a51211435be6ecfd90f  # v4.5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: pdm build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Only publish for real releases, not manual test runs.
+    if: github.event_name == 'release'
+    environment:
+      name: pypi
+      url: https://pypi.org/project/aioads/
+    permissions:
+      # IMPORTANT: required for OIDC trusted publishing.
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+        with:
+          # Sign the published distributions with PEP 740 build provenance.
+          attestations: true

{aioads-0.1.0.dev3 → 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.dev3 → 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.dev3 → aioads-0.1.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aioads
-Version: 0.1.0.dev3
+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.dev3 → 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.dev3 → 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,56 +255,67 @@ 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
     ) -> dict[str, SymbolReadResult]:
         """
         Read multiple symbols by their names from the ADS device.
+
+        The returned dict is keyed by the symbol names exactly as requested,
+        preserving their original casing.
         """
         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()
+        # 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
         ]
-        function = AdsSumRead(
+        if not readable:
+            return output
+
+        sum_read = AdsSumRead(
             transport=self.transport,
             ams_address=self.dst_address,
-            commands=read_commands,
+            commands=[
+                AdsReadCommand(
+                    transport=self.transport,
+                    ams_address=self.dst_address,
+                    idx_group=info.idx_group,
+                    idx_offset=info.idx_offset,
+                    length=info.idx_length,
+                )
+                for _, info in readable
+            ],
         )
+        response = await sum_read.execute()
 
-        response = await function.execute()
-        output: dict[str, SymbolReadResult] = {}
-
-        tasks = []
-        for (_, resp_payload), (error_code, symbol_info) in zip(
-            response, symbol_infos.values()
+        for (name, info), (read_response, resp_payload) in zip(
+            readable, response, strict=True
         ):
-            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,
-                )
+            if not read_response.error_code.ok:
+                output[name] = SymbolReadResult(read_response.error_code, None)
+                continue
+            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 symbol_data, (error_code, symbol_info) in zip(parsed, symbol_infos.values()):
-            output[symbol_info.symbol_name] = SymbolReadResult(
-                error_code, symbol_data)
 
         return output
 

{aioads-0.1.0.dev3 → 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.dev3 → 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.dev3 → 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.dev3 → aioads-0.1.0.dev5}/aioads/commands/ads_add_notification.py

@@ -77,7 +77,7 @@ class AdsAddNotificationCommand(ICommand[AdsAddNotificationResponse]):
     Ads command to create a ads notification (subscription to a remote resource)
     """
 
-    SERIALIZE_STRUCT_DEF: Final[Struct] = Struct("<IIIIIII16s")
+    SERIALIZE_STRUCT_DEF: Final[Struct] = Struct("<IIIIII16s")
 
     def __init__(
         self,

{aioads-0.1.0.dev3 → aioads-0.1.0.dev5}/aioads/commands/errors.py

@@ -27,4 +27,7 @@ class AdsCommandError(Exception):
 
     def __repr__(self) -> str:
         """Returns a detailed representation of the error for debugging."""
-        return f"AdsCommandError(error_code={self.error_code!r}, error_message:{self.error_code.description} args={self.args!r})"
+        return (
+            f"AdsCommandError(error_code={self.error_code!r}, "
+            f"error_message:{self.error_code.description} args={self.args!r})"
+        )