pyads-agile Features

This page summarizes the main additions and integrations maintained in the pyads-agile repository beyond baseline upstream compatibility.

RPC and typing enhancements

  • Native RPC proxy calls via pyads.Connection.get_object().

  • Typed RPC interface declarations with pyads.ads_path(), using PLC type annotations for IntelliSense and signature inference.

  • Manual override support for inferred parameter/return types when needed.

Async runtime and safety

  • pyads.AsyncConnection with a dedicated worker thread per connection.

  • In-order serialized ADS call execution to avoid race conditions on mutable connection state.

  • submit_* methods returning asyncio.Future and awaitable async method variants for core operations.

Async wrappers for core ADS APIs

The async layer mirrors the core sync APIs, including:

  • read, write, read_write

  • read_by_name, write_by_name

  • read_structure_by_name, write_structure_by_name

  • sum_read / sum_write

  • read_state, read_device_info, write_control

  • get_local_address, get_handle, release_handle, set_timeout

Async RPC and stepchain integration

  • Async typed RPC proxies via pyads.AsyncConnection.get_async_object().

  • Async interface decorator for type-safe future-returning methods: pyads.ads_async_path().

  • Stepchain-aware async interfaces via pyads.StepChainRpcInterface and pyads.stepchain_start().

  • pyads.StepChainOperation with:

    • accepted phase (RPC returned)

    • done phase (completion detected via configured status symbols)

    • awaitable operation behavior returning the latest ADS status snapshot (await op == await op.done)

    • generic transport type extraction via StepChainOperation[PLCTYPE_*]

  • Auto-generated request IDs for stepchain methods when the request id argument is omitted.

  • Default stepchain naming aligned with common TwinCAT conventions: stStepStatus, udiRequestId, xBusy, xDone, xError, diErrorCode.

  • Built-in stepchain status helper methods on StepChainRpcInterface proxies: status_symbol(), get_status_structure_def(), and read_status().

  • Stepchain completion backends selectable per interface: completion="poll" or completion="notify".

Testing and quality additions

  • Fake-backend async integration tests (testserver target).

  • Real-target async integration tests for Beckhoff runtime environments.

  • Dedicated tests for typed RPC inference, async serialization behavior, and stepchain completion/error paths.