Mapping Aspect Models to Asset Administration Shell (AAS) Submodel Templates

The Asset Administration Shell (AAS) and its information model is a widely recognized standard developed by the Industrial Digital Twin Association (IDTA) to express and handle Digital Twins. Central element of the AAS is the concept of Submodels, which describe certain aspects of a Digital Twin.

The SAMM Aspect Meta Model allows to specify aspects of a digital twin and its semantics. The AAS Generator module provides mapping implementations to derive AAS Submodels from SAMM Aspect Models. On the one hand, this allows to integrate SAMM models in AAS environments and on the other hand it allows AAS submodels to be described with rich semantics, as it is possible with SAMM.

Details of the Mapping Concept

In the following section, the mapping rules applied by the generator are explained. The rules apply to SAMM v2.0.0 and AAS Specification Part 1 V3.0.

SAMM AAS Comment

samm:Aspect

aas:Submodel with kind=Template

Empty Asset and AssetAdministrationShell entries are added to the output file

samm:name

aas:Submodel.idShort

samm:preferredName

aas:Submodel.displayName

samm:description

aas:Submodel.description

samm:property

see samm:Property

samm:operation

see samm:Operation

samm:Aspect.urn

aas:Submodel.semanticId

samm:Property

aas:Property, aas:SubmodelElementCollection

The AAS type is derived from the type of the SAMM Characteristic specifying the SAMM property. Depending on the type it is decided what the resulting AAS element will be. In case of an Entity it will result in a SubmodelElementCollection. It will also be a SubmodelElementCollection if the SAMM Characteristic is of a Collection type (see the Characteristics taxonomy). In all other cases an aas:Property will be generated

samm:Property.name

aas:Property.idShort

samm:Property.urn

aas:ConceptDescription.identification.id, aas:Property.semanticId

samm:Property.preferredName

aas:Property.displayName

samm:Property.description

aas:Property.description

Note: Also mapped to aas:DataSpecificationIEC61360.definition of the aas:ConceptDescription of this property

samm:Property.exampleValue

aas:Property.value

samm:Characteristic.dataType

aas:Property.valueType

samm:Operation

Operation

in/out parameters are not used in SAMM so the mapping only generates input variables and output variables in AAS

samm-c:Characteristic

aas:SubmodelElement, aas:ConceptDescription

Characteristics in SAMM define the semantics of a property, which includes there types as well as links to further definitions (standards, dictionaries, etc), a natural language description and name in different languages. Type and description are separated in AAS, which is why there is not a one-to-one mapping of a Characteristic to one element in AAS but rather Characteristics are used in the mapping of Properties, first, to guide the generation process and, second, to capture semantics in ConceptDescriptions of properties with data specification "DataSpecificationIEC61360" of the AAS.

samm-c:Collection

aas:SubmodelElementList, aas:ConceptDescription

The general remarks to Characteristics apply also to Collection type Characteristics. However, properties referencing Collections are mapped to SubmodelElementLists. Specific properties of collections are mapped. samm:Set is unique, samm:SortedSet is unique and sorted, samm:List is sorted.

samm-c:Quantifiable

aas:SubmodelElement, aas:ConceptDescription

The general remarks to Characteristics apply also to Quantifiable type Characteristics. Quantifiables (also Duration and Measurement) reference a unit, which is added to the ConceptDescription corresponding the mapped Characteristic.

samm-c:Either

aas:SubmodelElement, aas:ConceptDescription

The general remarks to Characteristics apply also to Either. However, the Either characteristic has two distinct entries of which one is to be selected. This concept is not present in AAS. Thus, both entries will be written to a Submodel template, where one has to be ignored.

samm-c:Trait

aas:SubmodelElement, aas:ConceptDescription

The general remarks to Characteristics apply also to Trait. However, the constraint of a trait will be ignored and only the base type will be evaluated, which will act as the characteristic of a property.

samm-c:Code

aas:SubmodelElement, aas:ConceptDescription

Similar to plain Characteristic.

samm-c:StructuredValue

aas:SubmodelElement, aas:ConceptDescription

The general remarks to Characteristics apply also to StructuredValue. However, AAS has no concpet like deconstruction rule. Thus, the deconstruction rule and the sub properties of the deconstruction entity will be ignored and only the Characteristic is mapped.

samm-c:Enumeration

aas:SubmodelElement, aas:ConceptDescription

The general remarks to Characteristics apply also to Enumerations. Additionally, the values of an Enumeration are mapped to a valueList of a DataSpecificationIEC61360.

samm-c:State

aas:SubmodelElement, aas:ConceptDescription

Same as Enumeration.

samm-c:MultiLanguageText

aas:MultiLanguageProperty

if a MultiLanguageText is used in SAMM it is mapped to the MultiLanguageProperty in AAS.

Known Limitations

The AAS Generator implements a base set of features, which are mapped from SAMM to AAS. However, there are still limitations:

  • Predefined entity mapping (FileResource would be mapped to aas:File)

  • samm-c:Either is mapped to aas:SubmodelElementCollection with two entries for left and right side

  • Recursive optional properties of SAMM model are not included in output but dropped straight away

Translate Aspect Model to AAS

The following code demonstrates how the API to translate an Aspect Model into one of the valid AAS formats (JSON, XML, AASX) is used:

Show used imports 
import org.eclipse.esmf.aspectmodel.aas.AasGenerationConfig;
import org.eclipse.esmf.aspectmodel.aas.AasGenerationConfigBuilder;
import org.eclipse.esmf.aspectmodel.aas.AspectModelAasGenerator;
import org.eclipse.esmf.aspectmodel.aas.AasFileFormat;
import org.eclipse.esmf.aspectmodel.loader.AspectModelLoader;
import org.eclipse.esmf.metamodel.Aspect;
import org.eclipse.esmf.metamodel.AspectModel;
// AspectModel as returned by the AspectModelLoader
final AspectModel aspectModel = // ...

final AasGenerationConfig config = AasGenerationConfigBuilder.builder()
      .format( AasFileFormat.AASX )
      .aspectData( null ) // Optional: Provide a JsonNode representing Aspect data
      .propertyMappers( List.of() ) // Optional: Customize SAMM->AAS property mapping
      .build();
new AspectModelAasGenerator( aspect, config ).generate( this::outputStreamForName );

To include the translator artifact, use the following dependencies:

Maven
<dependency>
    <groupId>org.eclipse.esmf</groupId>
    <artifactId>esmf-aspect-aas-generator</artifactId>
    <version>2.12.0</version>
</dependency>
Gradle Groovy DSL
implementation 'org.eclipse.esmf:esmf-aspect-model-aas-generator:2.12.0'
Gradle Kotlin DSL
implementation("org.eclipse.esmf:esmf-aspect-model-aas-generator:2.12.0")

Translate AAS to Aspect Model

It is also possible to translate AAS Submodel Templates to Aspect Models using a best-effort. The following example shows how the API to translate an AAS environment containing one or more Submodel Templates to Aspect Models:

Show used imports 
import java.io.File;

import org.eclipse.esmf.aspectmodel.aas.AasFileFormat;
import org.eclipse.esmf.aspectmodel.aas.AasGenerationConfigBuilder;
import org.eclipse.esmf.aspectmodel.aas.AasToAspectModelGenerator;
import org.eclipse.esmf.aspectmodel.aas.AspectModelAasGenerator;
import org.eclipse.esmf.aspectmodel.generator.AspectArtifact;
import org.eclipse.esmf.aspectmodel.loader.AspectModelLoader;
import org.eclipse.esmf.metamodel.AspectModel;
final File file = // an AAS file that ends in .aasx, .xml or .json

// Multiple "from" methods are available: fromFile (which checks the file extension),
// fromAasJson, fromAasXml, fromAasx as well as fromEnvironment (for an AAS4J AAS environment)
final AasToAspectModelGenerator generator = AasToAspectModelGenerator.fromFile( file );
generator.generate().map( AspectArtifact::getContent ).forEach( aspect -> {
   // do something with the generated aspect
} );

To include the translator artifact, use the same same dependencies as shown above in section Translate AAS to Aspect Model.