Track 3: Use and provide your own AAS

Motivation

AAS as a foundation technology enabling:

Dataspaces (Manufacturing-X, ...): generate value with data, efficiency gain based on interoperable data exchange, ...
Digital Product Passports (DPP): comply with EU regulations while having an interoperable foundation to create value, ...

Overview

This developer-track focuses on below points:

Discover and Load AAS
Provide Data via AAS (create and register)

The idea of this track is to get acquainted with different components of the AAS Infrastructure such as AAS-registry, discovery and repository along with interactions among them through APIs.

Target Group

AAS Developers, AAS Implementation Experts

Prerequisites

Laptop
REST API Client (recommendation Insomnia)

Tutorial

Basics - components of an AAS Infrastructure

As described in AAS Spec Part 2 (API) (pp. 20), an AAS infrastructure comprises of the following elements:

AAS repository stores the data of AAS, Submodels, and Concept Descriptions
AAS registry are directories that stores AAS IDs, Submodel IDs together with the related endpoints (typically a URL path into a repository or to a single AAS/Submodel)
AAS Discovery (servers) supports a fast search and only store copies of essential information, i.e. key value pairs to find IDs by other IDs.

Example for scenario based on Manufacturing-X

The following Figures depict a simplified example of a scenario based on Manufacturing-X. Note that for the sake of simplicity, some of the elementary components needed for Manufacturing-X are not considered and we will focus on the required components to enable interoperability based on AAS. In this example, a Manufacturer produces a machine that uses components from Supplier A and Supplier B.

So that the Manufacturer can set all business processes related to the production of a machine, it needs to obtain data related to the components built. Thus, the Manufacturer searches for the digital twins of the components from the suppliers via the AAS registry.

Once the Manufacturer obtains the endpoints to the repositories storing the AAS, the Manufacturer can download it and onboard into its own infrastructure

Based on this scenario, in this tutorial the tasks will have two parts: 1. Part: Participants looks for an AAS via the Discovery API and download the shell. 2. Part: Participants modify the downloaded AAS, upload to AAS repository and then register to AAS registry

Before starting the following tasks, please make yourself acquainted with the AAS infrastructure used for this tutorial:

AAS repository: https://techday2-repo1.admin-shell-io.com
AAS registry: https://techday2-registry.admin-shell-io.com
Swagger UI: https://techday2-repo1.admin-shell-io.com/swagger/index.html

Part 1: Look for an AAS and download it

Persona: As an engineer, you are looking for components for the machine you are designing.
Life-cycle-phase: engineering – design of a machine
Goal: use AAS infrastructure to find components and import them into your system.

Tasks description:

Find an AAS Type and its ID via the Discovery API

Start by searching for AAS types based on their descriptors in the AAS registry

GET https://techday2-registry.admin-shell-io.com/shell-descriptors/

Find out what AAS are representing the type of an asset.
Find out what submodels are associated to the AAS.
Optionally, try to get the descriptor of a specific AAS. For that, use

GET https://techday2-registry.admin-shell-io.com/shell-descriptors/{aasIdentifier}

Note that aasIdentifier is the AAS ID in base64url format. Feel free to use tools like https://www.base64encode.org to generate the aasIdentifiers accordingly.

As a result, you will get a JSON similar to Figure below:

Get the endpoint of the AAS via the Registry Interface

Analyze the outcome of the JSON, select an AAS and find the endpoint of this specific AAS.
Example:

https://techday2-repo1.admin-shell-io.com/shells/aHR0cHM6Ly9kcHA0MC5oYXJ0aW5nLmNvbS9zaGVsbHMvWlNOMQ

old example to "wrong" repository:

https://techday1-repo1.admin-shell-io.com/shells/aHR0cHM6Ly96dmVpLm9yZy9kZW1vL2Fhcy9Db250cm9sQ2FiaW5ldA

Access the selected AAS type in the AAS repository

Based on the selected AAS type, get the endpoint of the AAS repository
Example GET https://techday2-repo1.admin-shell-io.com/shells/{aasIdentifier}
Optionally, go to the repository and look for all available AAS

Download the AAS in JSON format

Example by executing GET https://techday2-repo1.admin-shell-io.com/shells/{aasIdentifier}
Use your client to either directly download the JSON or Copy-Paste the outcome into your code editor.

Download the Submodel Digital Nameplate of the selected AAS Type

Example by executing

GET https://techday2-repo1.admin-shell-io.com/shells/{aasIdentifier}/submodels/{submodelIdentifier}

Note that submodelIdentifier is the Submodel ID in base64url format. Feel free to use tools like https://www.base64encode.org to generate the aasIdentifiers accordingly.

Story 2: Derive your AAS Instance

Persona: As a master data engineer, you want to create instances of the assets being produced so that it can be handed over to customers
Life-cycle: Manufacturing – manufacturer produces assets and provides AAS of asset instances to customers
Goal: Create AAS instances out of type and make it available within manufacturer’s data space
Requirement: The AAS Instance should have only Digital Nameplate as a Submodel

Tasks description:

Select one AAS type and open it as a JSON using your code editor

See example in the Figure below

Create an empty AAS instance by modifying the following fields:

Create a new AAS id
Create a new IdShort
Modify the AAS so that is an instance (AssetKind = Instance)
Remove the defaultThumbnail property:

Remove the submodel references

Upload your AAS instance to the AAS repository with

POST  https://techday2-repo1.admin-shell-io.com/shells

and the JSON of your AAS instance as the body. See example below, you must the response 201 created

367192972-d7c9b479-0e7e-4503-b9d4-704ec1bb70bd

Check if your AAS instance has been uploaded by using

GET https://techday2-repo1.admin-shell-io.com/shells

and accessing the UI via https://techday2-repo1.admin-shell-io.com in your browser.

Access your AAS instance with

GET https://techday2-repo1.admin-shell-io.com/shells/{aasIdentifier}

Remember that you have to cover the aasIdentifier of your AAS instance into base64url(https://www.base64encode.org).

Create a instance of Submodel Digital Nameplate

As a reference for this task, get the Submodel Digital Nameplate from the AAS Type. To get a Submodel, you use the endpoint

/shells/{AASIdentifier}/submodels/{submodelIdentifier}

whereas the {submodelIdentifier} is the Submodel id. For example,

GET https://techday2-repo1.admin-shell-io.com/shells/aHR0cHM6Ly9kcHA0MC5oYXJ0aW5nLmNvbS9zaGVsbHMvWlNOMQ/submodels/aHR0cHM6Ly9kcHA0MC5oYXJ0aW5nLmNvbS9zaGVsbHMvWlNOMS9zdWJtb2RlbHMvTmFtZXBsYXRl

Create a new Submodel id ("id": "{your new submodel ID}")
Create a Serial-Number and assign it to the corresponding property of the Submodel.

    {
      "idShort": "SerialNumber",
      "semanticId": {
        "type": "ExternalReference",
        "keys": [
          {
            "type": "GlobalReference",
            "value": "0173-1#02-AAM556#002"
          }
        ]
      },
      "valueType": "xs:string",
      "value": "{PUT YOUR SERIAL NUMBER HERE}",
      "modelType": "Property"
    },

Upload the AAS Submodel to AASX Server (Repository) with POST https://techday2-repo1.admin-shell-io.com/submodels by using aasIdentifier of your AAS as a Parameter as shown below

Optionally, you can directly access the property SerialNumber via the API

https://techday2-repo1.admin-shell-io.com/shells/{aasIdentifier}/submodels/{submodelIdentifier}/submodel-elements/SerialNumber

and feel free to change it.

Once it is uploaded, register the AAS and Submodel in the Registry.

Chose an example from GET https://techday2-registry.admin-shell-io.com/shell-descriptors/
Or alternatively use the following example by updating it with the identifiers of your AAS and submodels

{
	"assetKind": "NotApplicable",
	"endpoints": [
		{
			"interface": "AAS-1.0",
			"protocolInformation": {
				"href": "https://techday2-repo1.admin-shell-io.com/shells/{your base64 encoded AASIdentifier}"
			}
		}
	],
	"globalAssetId": "{globalAssetID of your AAS}",
	"idShort": "{your AAS idShort}",
	"id": "{your AAS identifier}",
	"specificAssetIds": [
		{
			"name": "assetKind",
			"value": "Type",
			"externalSubjectId": {
				"type": "ExternalReference",
				"keys": [
					{
						"type": "GlobalReference",
						"value": "assetKind"
					}
				]
			}
		}
	],
	"submodelDescriptors": [
		{
			"endpoints": [
				{
					"interface": "SUBMODEL-1.0",
					"protocolInformation": {
						"href": "https://techday2-repo1.admin-shell-io.com/shells/{your base64 encoded AASIdentifier}/submodels/{your base64 encoded Digital Nameplate Submode ID}"
					}
				}
			],
			"idShort": "DigitalNameplate",
			"id": "{your Digital Nameplate Submode Identifier}",
			"semanticId": {
				"type": "ExternalReference",
				"keys": [
					{
						"type": "GlobalReference",
						"value": "https://admin-shell.io/zvei/nameplate/2/0/Nameplate"
					}
				]
			}
		}
	]
}

Upload it with POST https://techday2-registry.admin-shell-io.com/shell-descriptors/ by using your JSON as body.

(optional) ”exchange” AAS with any other participant

(*) empty means here an AAS without any submodels

Links

AASX Server: https://techday2-repo1.admin-shell-io.com
AASX Registry: https://techday2-registry.admin-shell-io.com
Swagger UI: https://techday2-repo1.admin-shell-io.com/swagger/index.html
Base64url converter: https://www.base64encode.org/

Provide feedback

Saved searches

Use saved searches to filter your results more quickly