aidconnect
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.
OperationalDatastays 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).
Related work
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.