Skip to main content

aidconnect

ci PyPI

Connect to an industrial asset from its Asset Administration Shell. The AAS file says where the asset's OPC UA server is, which security it wants and which datapoints it has; aidconnect reads that and connects. No endpoint, tag list or security setting in your code.

import asyncio
import aidconnect

async def main():
    async with aidconnect.connect("tank.aasx") as session:
        print(await session.read())   # {'Level': 2.5, 'PumpOn': True, 'Cycles': 7, 'Name': 'B101'}

asyncio.run(main())

The information comes from the Asset Interfaces Description submodel (IDTA 02017) inside the AAS. Swap the file and the same code talks to a different machine.

Install

pip install aidconnect

Without internet (a plant PC, a commissioning laptop on the machine network): download the offline bundle for your system from the latest release, carry it over on a USB stick, unzip it and run inside the folder:

python -m pip install --no-index --find-links . aidconnect

The bundle holds this tool and every package it needs; nothing is downloaded. Each bundle is installed in a clean environment and started once before it is published. Python 3.11 or newer.

The REST side of the gateway needs the Eclipse BaSyx Python server. The offline bundle includes it; with the wheel alone, install it with the pinned line in requirements-dev.txt.

What it does

aidconnect.read_interface(file) Endpoint, security and datapoints (name, type, unit, range, node reference) as plain Python objects. Opens no connection.
aidconnect.connect(file, ...) A session configured exactly as the AAS demands. await session.read() returns all datapoints in one request, typed (float, int, bool, str).
aidconnect.Gateway(file, ...) Keeps reading, reconnects after a connection loss (1 s … 30 s back-off), and publishes the values as submodel OperationalData on the AAS Part 2 REST API, read-only. If the file has an Asset Interfaces Mapping Configuration (IDTA 02027), each mapped value is also written into the Property the mapping names.
python -m aidconnect inspect file Prints what the AAS says.
python -m aidconnect serve file Runs the gateway.

Mapping values into your own submodels (IDTA 02027)

Put an Asset Interfaces Mapping Configuration (AIMC 1.0) next to the AID in the same AAS. Each MappingSourceSinkRelation names a datapoint of the AID (first) and a Property in any submodel (second), for example TankLevel in a monitoring submodel. The gateway then acts as the Data Mapping Processor of the template: it writes every value it reads into that Property, and the REST side serves the submodel live.

The mapping is checked when the file is loaded: a relation whose source is not a datapoint, whose sink is not a Property, or whose sink has a value type the datapoint cannot fill (a number into xs:int) is refused with a ValueError that names it. Configurations that point at another interface of the AID are left alone.

A secured asset

If the AAS asks for an encrypted channel and a login, you provide the three things a file must never contain:

cert, key = await aidconnect.ensure_client_certificate("pki")     # give client_cert.der to the server's admin
async with aidconnect.connect("plant.aasx",
                              client_cert=cert, client_key=key,
                              server_cert="server_cert.der",        # the only server this client will talk to
                              username="operator", password=os.environ["PLANT_PASSWORD"]) as session:
    values = await session.read()

If something is missing you get a ConfigurationError that names it, before any connection is attempted.

Security

  • Never weaker than the AAS says. Security policy and mode come from the file; there is no option to downgrade them.
  • The server is checked, not only the client. A secure connection needs the server's certificate; the channel is encrypted for that certificate and the session is refused if the server shows another one.
  • Remote AAS files are pinned. fetch_aasx(url, sha256) only accepts https and only a file with the expected hash, because the file decides where credentials are sent.
  • Read-only. The library reads datapoints. It has no function that writes to a controller. The REST side refuses everything except GET and HEAD and binds to localhost by default.
  • Passwords are passed in by the caller (the command line reads AIDCONNECT_PASSWORD); nothing is stored.

Tested

pytest starts two OPC UA servers the library knows nothing about and connects to each from its AAS file only:

  • an open server with four data types (number, integer, boolean, string);
  • a secured server (Basic256Sha256, SignAndEncrypt, trust list, UserName login): the right setup reads; a wrong password, an untrusted client certificate and a wrong server certificate are each refused with the expected error;
  • the gateway: live values over REST, asset switched off and on again, reconnects by itself;
  • AIMC: an AASX with a mapping configuration, written and read back, puts the live values into the mapped properties; a wrong value type and a source that is not a datapoint are refused.

Limits

  • OPC UA only. The Asset Interfaces Description can also describe Modbus, MQTT and HTTP interfaces; those are not implemented.
  • Scalar values only (number, integer, boolean, string). No arrays or structures.
  • No hardware test yet. Everything is tested against software servers on one machine. A Siemens S7-1500 names its nodes like ns=3;s="DB"."tag"; that form is parsed, but not tried on a real controller.
  • AIMC 1.0, asset to AAS only, as the template itself defines it. OperationalData stays as the gateway's own status submodel (connection state, last update, every datapoint).
  • The REST side needs the Eclipse BaSyx Python server, which is not on PyPI. Install it with the pinned line in requirements-dev.txt.
  • Polling, not subscriptions. One batched read per period (default 1 s).

FA³ST Service (Fraunhofer IOSB) and the Eclipse BaSyx DataBridge also build asset connections from interface descriptions. Both are Java services you deploy. aidconnect is a small Python library for scripts, test rigs and notebooks.

Where it comes from

Split out of heating-plant-aas, where the same code connects to a simulated S7-1500 heating plant.

Licence

MIT

Metadata

Release files for aidconnect 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aidconnect 0.2.0
File Size Uploaded Provenance Actions
aidconnect-0.2.0.tar.gz 20.5 kB With provenance Details for aidconnect-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aidconnect 0.2.0
File Interpreter ABI Platform Actions
aidconnect-0.2.0-py3-none-any.whl Python 3 none any Details for aidconnect-0.2.0-py3-none-any.whl

Total release size: 37.1 kB

Release files / aidconnect-0.2.0.tar.gz

Download URL aidconnect-0.2.0.tar.gz
Size 20.5 kB
Tags Source
SHA-256 checksum
How to use checksums
5505eaeb278e47cd8ccaffd772f6daca6e5b5b72dc9a5acfe3649987075ebce2
BLAKE2b-256 checksum
How to use checksums
c724ef2f1884b8ebb82c729738537aaab1d44c05dd818e3a89ea46eb4bc387d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / aidconnect-0.2.0-py3-none-any.whl

Download URL aidconnect-0.2.0-py3-none-any.whl
Size 16.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a69a77e6e76416e7975a1e0fbb82eb1c9ac3f76f29aeee45f954d7f5d4950134
BLAKE2b-256 checksum
How to use checksums
cc03d6fa38aca8025f2985cab75e78e44fb079fafded67dd573c33a123d224e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for aidconnect 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aidconnect-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page