Asset Administration Shell (AAS) Thing Python SDK

A Python toolkit for building Industry 4.0-compliant Things using Asset Administration Shell (AAS), with seamless integration into the Smart Systems Service Infrastructure (S³I). Please refer to the whitepaper for details:

Hoppen M., Chen, J., Roßmann, J. (2025) Smart Systems Service Infrastructure (S3I) — Design and deployment of the Smart Systems Service Infrastructure (S3I) for decentralized networking in Forestry 4.0. KWH4.0 Position Paper. DOI: 10.18154/RWTH-2025-03168

Table of Contents

• Overview
• Features
  • Core Functionality
  • Roadmap
• Technical Structure
• Installation
• Documentation
• Contributing
• License

Overview

The AAS Thing Python SDK helps you:

• Instantiate and manipulate AAS and submodels using the Eclipse BaSyx Python SDK
• Exchange standardized I4.0 messages (VDI 2193-1) over AMQP (store-and-forward) or (in future) HTTP
• Authenticate, manage and discover services, exchange information via the S³I core (IdentityProvider, Directory, Repository, Broker)

By following the AAS specification, your Things become members in Industry 4.0 ecosystems, interoperating securely and reliably.

Features

Core Functionality

• AAS management
  Load and parse .json, .xml, or .aasx AAS on disk using BaSyx Python SDK.

• Message-based communication
  Create, send and receive I4.0 messages (I40Message) combined with the AAS API specification defined in Specification of the Asset Administration Shell Part 2, over AMQP (store-and-forward) or (in future) HTTP.

• S³I integration

  • IdentityProvider: OpenID Connect authentication via Keycloak
  • Broker: AMQP 0.9 messaging with RabbitMQ
  • Directory & Repository: Endpoint discovery and cloud storage

Global instance of S³I

We provide a global instance of the S³I, which runs in a server located at MMI, RWTH Aachen University and can be used for testing. It includes:

Roadmap of the SDK

In the near future, we will provide the supports to:

• Postbox API: REST-based alternative to AMQP for sending and receiving I4.0 messages
• Discovery Service: Endpoint discovery using query parameters
• Authorization: XACML-based access control framework
• Events: Support for AAS- and AMQP-based events
• Server Infrastructure: The open-source server infrastructure for the Smart Systems Service Infrastructure (S³I) and its configuration for docker and kubernetes

Technical Structure

Installation

Install from PyPI:

$ python -m pip install aas-thing

Or build & install from source:

$ git clone git@git.rwth-aachen.de:co2for-it/s3i/aas-thing-python-sdk.git
$ cd aas-thing-python-sdk
$ python -m pip install .

Thing lifecycle

Constructing a BaseAASThing is local-only: it loads configuration and stores handler registrations, but does not contact the Identity Provider, AAS Repository, or AMQP Broker. Network resources are acquired by open() and released by close().

thing = DemoHarvester("config.yaml")
thing.register_operation_handler(
    submodel_id=f"{thing.thing_id}/JobManagement",
    operation_id="AcceptJob",
    handler=thing.acceptJob,
)
thing.start()  # synchronous wrapper around asyncio.run(thing.serve_forever())

Async applications can manage the same lifecycle explicitly:

async with thing:
    await thing.wait_until_stopped()

open() authenticates and loads the AAS first, validates and binds queued handlers next, and only then opens Broker channels. Startup failures trigger automatic rollback of resources that were already acquired.

The supported public integration surface is:

thing.register_operation_handler(submodel_id, operation_id, operation_handler)
thing.register_event_handler("factory/jobs", event_handler)
thing.register_reply_handler(correlation_id, reply_handler)

thing.on_idp_ready(on_idp)
thing.on_repository_ready(on_repository)
thing.on_message_broker_ready(on_messages)
thing.on_event_broker_ready(on_events)

thing.subscribe("factory/jobs")
reply = await thing.send_request(request, timeout=10)
thing.stop()

Synchronous handlers are run in worker threads so that they do not block the event loop; coroutine handlers are awaited directly. During shutdown, consumers are stopped first, active handlers are drained, maintenance tasks and pending requests are cancelled, Broker connections are awaited, and the IdP is closed last.

Configuration

s3i_connector.identity_provider and exactly one aas_connector backend (http or file) are required. Message Broker, Event Broker, Authorization, and Directory sections are optional. The whole configuration is validated when the Thing is constructed.

Relative paths passed as the configuration filename are resolved against the current working directory. A relative aas_connector.file.path is resolved against the directory containing that configuration file.

Secrets can be supplied without committing them to YAML:

client_id: "${S3I_CLIENT_ID}"
client_secret: "${S3I_CLIENT_SECRET}"
request_timeout: 30
broker_connect_timeout: 30

Values use the process environment by default. Applications with a secret provider can inject its resolved mapping through BaseAASThing(..., config_values=secret_values). ${NAME:-default} supplies an optional fallback.

Documentation

Full API reference, tutorials, and demos are available in the documentation.

Contributing

Contributions, bug reports, and feature requests are welcome!

Please:

• Fork the repository
• Create a feature branch (git checkout -b feature/XYZ)
• Commit your changes (git commit -m "Add XYZ")
• Push to your fork (git push origin feature/XYZ)
• Open a Merge Request

See CONTRIBUTING.md for detailed guidelines.

License

This project is licensed under the LGPL v3 License. See the LICENSE file for details.