Metadata-Version: 2.4
Name: aidconnect
Version: 0.2.0
Summary: Connect to an industrial asset from its Asset Administration Shell: the Asset Interfaces Description tells where and how, aidconnect does it (OPC UA).
Author: Suleman Ali
License: MIT
Project-URL: Repository, https://github.com/sulemanali5760/aidconnect
Keywords: asset-administration-shell,aas,opc-ua,industry-4-0,asset-interfaces-description,idta
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: asyncua<3,>=1.1
Requires-Dist: basyx-python-sdk<3,>=2.0
Dynamic: license-file

# aidconnect

[![ci](https://github.com/sulemanali5760/aidconnect/actions/workflows/ci.yml/badge.svg)](https://github.com/sulemanali5760/aidconnect/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/aidconnect)](https://pypi.org/project/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.

```python
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

```bash
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](https://github.com/sulemanali5760/aidconnect/releases/latest), carry
it over on a USB stick, unzip it and run inside the folder:

```bash
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:

```python
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).

## Related work

[FA³ST Service](https://github.com/FraunhoferIOSB/FAAAST-Service) (Fraunhofer IOSB) and the [Eclipse BaSyx DataBridge](https://github.com/eclipse-basyx/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](https://github.com/sulemanali5760/heating-plant-aas), where the same code connects to a simulated S7-1500 heating plant.

## Licence

MIT
