diff --git a/README.md b/README.md index d51dab46..e5805805 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,29 @@

Eclipse BaSyx Python SDK

-The Eclipse BaSyx Python project focuses on providing a Python implementation of the Asset Administration Shell (AAS) -for Industry 4.0 Systems. +[![CI](https://github.com/eclipse-basyx/basyx-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/eclipse-basyx/basyx-python-sdk/actions/workflows/ci.yml) +[![PyPI Version](https://img.shields.io/pypi/v/basyx-python-sdk)](https://pypi.org/project/basyx-python-sdk/) +[![Conda Version](https://img.shields.io/conda/vn/conda-forge/basyx-python-sdk)](https://anaconda.org/conda-forge/basyx-python-sdk) +[![PyPI Downloads](https://img.shields.io/pypi/dm/basyx-python-sdk)](https://pypi.org/project/basyx-python-sdk/) +[![License](https://img.shields.io/github/license/eclipse-basyx/basyx-python-sdk)](LICENSE) +![Min](https://img.shields.io/badge/dynamic/toml?url=https://raw.githubusercontent.com/eclipse-basyx/basyx-python-sdk/7192d207fa8f17afe1a35bdebcff3291a85facef/versions.toml&query=$.python.min&label=python%20min) +![Max](https://img.shields.io/badge/dynamic/toml?url=https://raw.githubusercontent.com/eclipse-basyx/basyx-python-sdk/7192d207fa8f17afe1a35bdebcff3291a85facef/versions.toml&query=$.python.max&label=python%20max) -**Please note that the SDK version number is independent of the supported AAS versions!** +The Eclipse BaSyx Python SDK is a Python implementation of the +[Asset Administration Shell (AAS)](https://industrialdigitaltwin.org/en/content-hub/aasspecifications) +for Industry 4.0 systems. It lets you model, serialize, validate, store, and serve AAS data +entirely in Python. -These are the implemented AAS specifications of the [current SDK release](https://github.com/eclipse-basyx/basyx-python-sdk/releases/latest), which can be also found on [PyPI](https://pypi.org/project/basyx-python-sdk/): +The project is part of the [Eclipse BaSyx](https://www.eclipse.org/basyx/) middleware +framework, developed under the umbrella of the Eclipse Foundation. + +## Specification Compliance + +> [!NOTE] +> The SDK version number is independent of the supported AAS specification versions. + +These are the AAS specifications implemented by the +[current release](https://github.com/eclipse-basyx/basyx-python-sdk/releases/latest): | Specification | Version | |---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| @@ -19,56 +36,153 @@ These are the implemented AAS specifications of the [current SDK release](https: | Part 3a: Data Specification IEC 61360 | [v3.1.1 (01003-a)](https://industrialdigitaltwin.org/wp-content/uploads/2025/08/IDTA-01003-a-3-1-1_AAS-Specification_Part3a_DataSpecification.pdf) | | Part 5: Package File Format (AASX) | [v3.1 (01005)](https://industrialdigitaltwin.org/wp-content/uploads/2025/06/IDTA_01005-25-01_AAS-Specification_Part5_AASXPackageFileFormat.pdf) | +For older specification support, consult the [prior releases](https://github.com/eclipse-basyx/basyx-python-sdk/releases). +Each release has a similar table in its notes. + +--- + +## Table of Contents + +- [Features](#features) +- [Getting Started](#getting-started) +- [Examples and Tutorials](#examples-and-tutorials) +- [FAQ](#faq) +- [Release Schedule](#release-schedule) +- [Contributing](#contributing) +- [License](#license) -If you need support to an older version of the specifications, please refer to our [prior releases](https://github.com/eclipse-basyx/basyx-python-sdk/releases). -Each of them has a similar table at the top of the release notes. +--- ## Features -This repository is structured into separate packages. -The `sdk` directory provides the AAS metamodel as Python objects and fundamental functionalities to handle AAS. -The `server` implements a specification-compliant Docker HTTP server for AASs. -The `compliance_tool` is a command-line tool for checking whether JSON and XML files comply with the AAS specification. - -* [SDK](./sdk/README.md): - * Modelling of AASs as Python objects - * Reading and writing of AASX package files - * (De-)serialization of AAS objects into/from JSON and XML - * Experimental serialization to RDF (see branch [Experimental/Adapter/RDF](https://github.com/eclipse-basyx/basyx-python-sdk/tree/Experimental/Adapter/RDF/basyx/aas/adapter/rdf)). - Please refer to discussion of PR [#308](https://github.com/eclipse-basyx/basyx-python-sdk/pull/308) for the reasoning behind keeping this feature experimental. - * Storing of AAS objects in CouchDB, Backend infrastructure for easy expansion - * Compliance checking of AAS XML and JSON files -* [Server](./server/README.md): Docker Image of a specification compliant HTTP Server implementing the interfaces: - * Asset Administration Shell Repository - * Submodel Repository - * Asset Administration Shell Registry Service - * Submodel Registry Service - * Discovery -* [Compliance Tool](./compliance_tool/README.md): A command-line tool for checking compliance of JSON and XML files - to the specification of the AAS -## License +This mono-repository contains three self-contained Python packages that cover different +aspects of working with Asset Administration Shells: -The BaSyx Python SDK project is licensed under the terms of the MIT License. +### [SDK](./sdk) -SPDX-License-Identifier: MIT +The SDK is the core of this project. It provides: + +- **AAS Metamodel** — full Python object model of the AAS metamodel (Part 1) +- **Serialization** — read and write AAS data as JSON, XML, or AASX package files +- **Backend Storage** — persist AAS objects in CouchDB or as local JSON files, with an + extensible backend interface +- **Experimental RDF Support** — serialization to RDF is available on the + [Experimental/Adapter/RDF](https://github.com/eclipse-basyx/basyx-python-sdk/tree/Experimental/Adapter/RDF/basyx/aas/adapter/rdf) + branch (see [#308](https://github.com/eclipse-basyx/basyx-python-sdk/pull/308) for context) + +### [Server](./server) + +A Docker image that exposes a specification-compliant HTTP/REST API (AAS Part 2), currently +implementing the following service interfaces: + +- Asset Administration Shell Repository +- Submodel Repository +- AAS Registry +- AAS Discovery + +It can serve AAS data from AASX, JSON, or XML files, optionally with persistent +storage via the Local-File Backend. + +### [Compliance Tool](./compliance_tool) + +A command-line utility for checking whether AAS JSON, XML, or AASX files conform to the +official schema. Useful for CI pipelines, data validation, and interoperability testing. + +--- + +## Getting Started + +Each package in this repository can be set up independently. Refer to the package-level +READMEs for detailed installation instructions, usage examples, and configuration options: + +- [SDK](./sdk/README.md#getting-started) (install from + PyPI or conda-forge, quick code example, tutorials) +- [Server](./server/README.md#running) (Docker build & run, + environment variables, persistence options) +- [Compliance Tool](./compliance_tool/README.md) + (install, command-line usage) + +--- + +## Examples and Tutorials -For more information, especially considering the licenses of included third-party works, please consult the `NOTICE` -file. +### SDK Tutorials + +The SDK ships with step-by-step tutorials in [`sdk/basyx/aas/examples/`](./sdk/basyx/aas/examples): + +| Tutorial | What You Will Learn | +|---|---| +| [Create a Simple AAS](./sdk/basyx/aas/examples/tutorial_create_simple_aas.py) | Build an Asset Administration Shell with an Asset and a Submodel from scratch | +| [Navigate Submodels](./sdk/basyx/aas/examples/tutorial_navigate_aas.py) | Traverse AAS Submodels using IdShorts and IdShortPaths | +| [Object Storage](./sdk/basyx/aas/examples/tutorial_storage.py) | Manage many AAS objects with ObjectStores and resolve references | +| [Serialization & Deserialization](./sdk/basyx/aas/examples/tutorial_serialization_deserialization.py) | Read and write AAS data as JSON and XML | +| [AASX Packages](./sdk/basyx/aas/examples/tutorial_aasx.py) | Export AAS shells with related objects and auxiliary files to AASX packages | +| [CouchDB Backend](./sdk/basyx/aas/examples/tutorial_backend_couchdb.py) | Store and retrieve AAS objects in a CouchDB document database | + +A detailed, complete API [documentation](https://basyx-python-sdk.readthedocs.io) is available on Read the Docs. + +### Server Example Configurations + +Ready-to-use Docker Compose configurations can be found in `server/example_configurations/`: + +| Configuration | Description | +|--------------------------------------------------------------------------------|------------------------------------| +| [Repository Standalone](./server/example_configurations/repository_standalone) | AAS and Submodel repository server | +| [Registry Standalone](./server/example_configurations/registry_standalone) | AAS and Submodel registry service | +| [Discovery Standalone](./server/example_configurations/discovery_standalone) | AAS discovery service | + +--- + +## FAQ + +**Q: I can't read a JSON/XML/AASX file from another tool with this SDK. What should I do?** + +A: The SDK enforces strict compliance with the AAS specification that your file might not comply with. To diagnose the issue: +- Check that the file targets the same AAS specification version supported by your SDK version + ([Specification Compliance](#specification-compliance) for the current release) +- Run the [Compliance Tool](./compliance_tool/README.md) on the file to identify schema violations +- If the file is spec-compliant and the SDK still rejects it, please + [open an issue](https://github.com/eclipse-basyx/basyx-python-sdk/issues/new) with the + error message and, if possible, a minimal example file. + +**Q: Can I run the server without Docker?** + +A: Yes, for debugging purposes. See the +[Server README](./server/README.md#running-without-docker-debugging-only) for instructions. +This mode is not suitable for production. + +--- ## Release Schedule -The Eclipse BaSyx-Python SDK Team evaluates bi-monthly the newly added commits to the main branch towards the need -of releasing a new version. -If decided the changes warrant a release, it is initiated, using semantic versioning for the new release number. -If the changes do not warrant a release, the decision is postponed to the next meeting. +The Eclipse BaSyx Python SDK team meets bi-monthly to evaluate whether the changes accumulated +on the `develop` branch warrant a new release. If so, the changes are merged into the `main` branch and a +new version is published to +[PyPI](https://pypi.org/project/basyx-python-sdk/) and +[conda-forge](https://anaconda.org/conda-forge/basyx-python-sdk) +using [semantic versioning](https://semver.org/). If not, the decision is deferred to the +next meeting. Security fixes may be released at any time. -Additionally, security fixes may be released at any point. +--- ## Contributing -For contributing with issues and code, please see our [Contribution Guideline](./CONTRIBUTING.md). +We welcome contributions of all kinds. Please read our [Contribution Guideline](./CONTRIBUTING.md) before +getting started. ### Eclipse Contributor Agreement -To contribute code to this project you need to sign the [Eclipse Contributor Agreement (ECA)](https://www.eclipse.org/legal/ECA.php). -This is done by creating an Eclipse account for your git e-mail address and then submitting the following form: https://accounts.eclipse.org/user/eca +To contribute code, you must sign the +[Eclipse Contributor Agreement (ECA)](https://www.eclipse.org/legal/ECA.php). +Create an Eclipse account with the same email address you use for Git commits, then submit +the form at: https://accounts.eclipse.org/user/eca + +--- + +## License + +This project is licensed under the terms of the **MIT License**. + +SPDX-License-Identifier: MIT + +For details on third-party dependencies and their licenses, see the [NOTICE](./NOTICE) file. \ No newline at end of file