How to Use the Asset Administration Shell

A tutorial on creating and interacting with digital twins using AASX Package Explorer and AASX Server

In my article “What Is a Digital Twin?” I explained the concept of digital twin technology.

This article is a tutorial on how to actually use the digital twin with available open source software.

Specifically, I will show you how to use the Asset Administration Shell with software from the Industrial Digital Twin Association’s admin-shell-io GitHub repository.

Asset Administration Shell

The Asset Administration Shell (AAS) is a digital twin implementation for Industry 4.0. The AAS specifications are currently described in two parts in [1] and [2]. There is also an international standard under development as IEC 63278: Asset Administration Shell for industrial applications.

The idea behind the AAS is that it digitally encapsulates an asset. Together, asset and administration shell are called an Industry 4.0 component.

A UML metamodel of the AAS is documented in [1]. In short, at the top level we have the AAS, which is associated with an asset. On the next level, we have multiple submodels that each contain data elements, e.g., variables or files.

API documentation can be found in [2]. Currently, only the HTTP/REST API is documented. MQTT and OPC UA support is planned for the future.

AASX Package Explorer

The AASX Package Explorer is used to create and edit *.AASX files.

The open source AASX Package Explorer is freely available on GitHub, which provides executables for Windows 10. Download and unzip the latest version, e.g., aasx-package-explorer.2023–02–03.alpha.zip, and then run AasxPackageExplorer.exe.

To view an example, go to File → Open and open content-for-demo/Example_AAS_ServoDCMotor_21.aasx. This will open the following example AAS for a DC motor.

On the top level, there is the ExampleMotor AAS. At the next level, there are four submodels. Each submodel contains properties and their values.

For example, we find the constant MaxRotationSpeed under TechnicalData. The variable RotationSpeed is located under OperationalData.

If you want to change values or add new submodels or properties, you must enable editing by selecting Workspace → Edit.

AASX Server

The AASX Server provides the REST API to interact with our digital twins.

The open source software is freely available on GitHub, where binaries for Windows and Linux are available. A Docker container is also provided.

On Windows, download and unzip the latest version, e.g., AasxServerWindows.2022–01–13.alpha.zip. Then, run startForDemo.bat.

You should now see the following message:

C:\AasxServerWindows>AasxServerWindows.exe --rest --no-security --data-path aasxs
Serving the AASXs from: aasxs
Security 1 Startup - Server
Security 1.1 Load X509 Root Certificates into X509 Store Root 
Loading aasxs\Example_AAS_ServoDCMotor_21.aasx... 

Please wait for the servers to start...
Connect to REST by: localhost:51310
http://localhost:51310/
REST Server started.
Servers successfully started. Press Ctrl-C to exit... 

We can now interact with the example DC motor. A few basic API commands are documented here. I use Postman to send and receive HTTP requests.

GET available Asset Administration Shells

To check all available *.aasx files on the server, use

GET http://localhost:51310/server/listaas

This will give you the following response:

{
    "aaslist": [
        "0 : ExampleMotor : [IRI] http://customer.com/aas/9175_7013_7091_9168 : aasxs\\Example_AAS_ServoDCMotor_21.aasx"
    ]
}

The ExampleMotor is the only available digital twin, and it has the index 0.

GET Submodel Elements

Next, let’s read the current RotationSpeed with the following HTTP request:

GET http://localhost:51310/aas/ExampleMotor/submodels/OperationalData/elements/RotationSpeed

or

GET http://localhost:51310/aas/0/submodels/OperationalData/elements/RotationSpeed

This will give us the response:

{
    "elem": {
        "value": "4370",
        "valueId": null,
        "semanticId": {
            "keys": [
                {
                    "type": "ConceptDescription",
                    "local": true,
                    "value": "http://customer.com/cd//1/1/18EBD56F6B43D895",
                    "index": 0,
                    "idType": "IRI"
                }
            ]
        },
        "constraints": [],
        "hasDataSpecification": [],
        "idShort": "RotationSpeed",
        "category": "VARIABLE",
        "modelType": {
            "name": "Property"
        },
        "valueType": {
            "dataObjectType": {
                "name": "integer"
            }
        },
        "kind": "Instance",
        "descriptions": null
    }, ...
}

If we only want the actual value, we can use:

GET http://localhost:51310/aas/ExampleMotor/submodels/OperationalData/elements/RotationSpeed/value

{
    "value": "4370"
}

PUT Submodel Elements

Now, let’s change the RotationSpeed to a new value 1234 with the following HTTP request:

PUT http://localhost:51310/aas/ExampleMotor/submodels/OperationalData/elements

with the Payload (Body) from the elem content above:

{
    "value": "1234",
    "valueId": null,
    "semanticId": {
      "keys": [
        {
          "type": "ConceptDescription",
          "local": true,
          "value": "http://customer.com/cd//1/1/18EBD56F6B43D895",
          "index": 0,
          "idType": "IRI"
        }
      ]
    },
    "constraints": [],
    "hasDataSpecification": [],
    "idShort": "RotationSpeed",
    "category": "VARIABLE",
    "modelType": {
      "name": "Property"
    },
    "valueType": {
      "dataObjectType": {
        "name": "integer"
      }
    }
}

If we change the idShort name in the payload, we can also create a new property instead of updating an existing one.

DELETE Submodel Elements

Lastly, we can delete the RotationSpeed property with the following HTTP request:

DELETE http://localhost:51310/aas/ExampleMotor/submodels/OperationalData/elements/RotationSpeed

Conclusion

Use the AASX Package Explorer to create your own digital twin. The AASX Server provides an HTTP/REST API with the GET, PUT, and DELETE commands.

The AAS specifications are still under development. Therefore, the AASX software is still in alpha and subject to change.

The use case below shows what is currently possible. For example, real-time measurements are sent from the physical demo box to its digital Asset Administration Shell. In addition, the AAS includes PDF documents and a 3D CAD model.

References

[1] Plattform Industrie 4.0: Details of the Asset Administration Shell — Part 1 (2022)

[2] Plattform Industrie 4.0: Details of the Asset Administration Shell — Part 2 (2021)

Additional Resources

Level Up Coding

Thanks for being a part of our community! Before you go:

• 👏 Clap for the story and follow the author 👉
• 📰 View more content in the Level Up Coding publication
• 🔔 Follow us: Twitter | LinkedIn | Newsletter

🚀👉 Join the Level Up talent collective and find an amazing job