"A Submodel defines a specific aspect of the asset represented by the Asset Administration Shell. A Submodel is used to structure the virtual representation and technical functionality of an Administration Shell into distinguishable parts. Each Submodel refers to a well-defined domain or subject matter. Submodels can become standardized and thus become submodels types. Submodels can have different life-cycles." (Details of the Asset Administration Shell, 2018, p. 46, [1])
Amongst the official attributes of Submodels, BaSyx defines aggregates called data elements, operations and events. These aggregates are used to structure official SubmodelElements (Property, ReferenceElement, Event, Operation, etc.) into groups of same functionality, i.e.
- DataElements as collection for value-based properties
- Operations as collection for callable methods
- Events as collection for events descriptions.
But the information model of a Submodel is only one side of the coin. BaSyx follows a distributed approach, i.e. Submodels may be deployed in distributed infrastructure. Asset Administration Shells only refer to their Submodels by terms of a reference comprising the Submodel's endpoints. They do not know about their Submodels' content but they know the way to it. On the other side, Submodels may reference their Asset Administration Shells as well via a parent attribute.
In order to access the Submodel's content, BaSyx defines so-called Submodel Service Providers. These Service Providers are used to make data elements, operations and events accessible by defining various access methods, e.g. GET- and SET- resp. MethodCalled-handler. Initially, on an abstract level, there is no technology binding necessary to build or use a service provider. Later of course, when starting the runtime, BaSyx provides highly generic technology bindings which can be used to grant access to the Submodel's content via chosen technology (HTTP/REST, OPC UA, BaSyx native).
In a nutshell, BaSyx Submodel Service Providers enable access to Submodels' content. A Submodel Service Provider needs to implement the generic Submodel Service Provider interface that is exemplary described on this page in HTTP/REST technology. The Submodel Service Provider enables access to data elements, operations and events. The BaSyx Submodel Service Provider may provide a façade hiding numerous (proprietary) data sources, e.g. SQL databases, XML configuration files, AutomationML, Hashmaps, Lambda, XQuery and many more. Furthermore, the BaSyx SDK enables creation of custom Submodel Service Providers. This is done by deriving from abstract BaSyx Service Provider interfaces.
The BaSyx Submodel Service Provider in HTTP/REST technology is defined as follows:
Asset Administration Shell Aggregator Services
|
GET
|
/aasList
|
Description
- Retrieves all Asset Administration Shells from the endpoint
Response codes
- 200: Returns a list of found Asset Administration Shells
- 404: No Asset Administration Shells found
- 400: Bad Request
- 502: Bad Gateway
|
POST
|
/aasList
|
Description
- Creates a new Asset Administration Shell at the endpoint
Parameter
- (body): The AAS's description object
Response codes
- 201: Asset Administration Shell created successfully
- 400: Bad Request
- 502: Bad Gateway
|
GET
|
/aasList/{aasId}
|
Description
- Retrieves a specific Asset Administration Shell
Parameter
- aasId: The AAS's unique id
Response codes
- 200: Returns the requested Asset Administration Shell
- 404: No Asset Administration Shell found
- 400: Bad Request
- 502: Bad Gateway
|
PUT
|
/aasList/{aasId}
|
Description
- Updates a specific Asset Administration Shell
Parameter
- aasId: The AAS's unique id
- (body): The updated AAS
Response codes
- 200: Asset Administration Shell updated successfully
- 400: Bad Request
- 502: Bad Gateway
|
DELETE
|
/aasList/{aasId}
|
Description
- Deletes a specific Asset Administration Shell
Parameter
- aasId: The AAS's unique id
Response codes
- 200: Asset Administration Shell deleted successfully
- 400: Bad Request
- 502: Bad Gateway
|
Asset Administration Shell Services
|
GET
|
/aas
|
Description
- Retrieves the Asset Administration Shell
Response codes
- 200: Success
- 502: Bad Gateway - Asset Administration Shell not available
|
GET
|
/aas/submodels
|
Description
- Retrieves all Submodels from the Asset Administration Shell
Response codes
- 200: Returns a list of found Submodels
- 404: No Submodel Service Providers found
- 502: Bad Gateway
|
POST
|
/aas/submodels
|
Description
- Adds a new Submodel to an existing Asset Administration Shell
Parameter
- (body): The Submodel's description object
Response codes
- 201: Submodel created successfully
- 400: Bad Request
- 502: Bad Gateway
|
GET
|
/aas/submodels/{submodelId}
|
Description
- Retrieves the Submodel from the Asset Administration Shell
Parameter
- submodelId: The Submodel's unique id
Response codes
- 200: Submodel retrieved successfully
- 404: No Submodel Service Provider found
- 502: Bad Gateway
|
DELETE
|
/aas/submodels/{submodelId}
|
Description
- Deletes a specific Submodel from the Asset Administration Shell
Parameter
- submodelId: The Submodel's idShort
Response codes
- 200: Submodel deleted successfully
- 400: Bad Request
- 502: Bad Gateway
|
Submodel Binding
|
GET
|
/aas/submodels/bindings
|
Description
- Retrieves all registered Submodel Service Providers within an Asset Administation Shell Service Provider
Response codes
- 200: Returns the all registered Submodel Service Provider
- 404: No Submodel Service Provider found
- 400: Bad Request
- 502: Bad Gateway
|
GET
|
/aas/submodels/{submodelId}/binding
|
Description
- Retrieves a specific Submodel Service Provider from its containing Asset Administration Shell Service Provider
Parameter
Response codes
- 200: Returns the requested Submodel Service Provider
- 404: No Submodel Service Provider found
- 400: Bad Request
- 502: Bad Gateway
|
POST
|
/aas/submodels/{submodelId}/binding
|
Description
- Registers a new Distributed Submodel Service Provider at the Asset Administration Shell Service Provider
Parameter
- (body): The Submodel Service Provider' service descriptor object
Response codes
- 201: Submodel Service Provider registered successfully
- 400: Bad Request
- 502: Bad Gateway
|
DELETE
|
/aas/submodels/{submodelId}/binding
|
Description
- Unregisters a specific Submodel Service Provider from its containing Asset Administration Shell Service Provider
Parameter
Response codes
- 200: Submodel Service Provider unregistered successfully
- 400: Bad Request
- 502: Bad Gateway
|
Submodel Services
|
GET
|
/submodel
|
Description
Response codes
- 200: Success
- 404: Submodel not found
|
GET
|
/submodel/dataElements
|
Description
- Retrieves all DataElements from the current Submodel
Parameter
Response codes
- 200: Returns a list of found DataElements
- 404: Submodel not found / No DataElements found
- 502: Bad Gateway
|
POST
|
/submodel/dataElements
|
Description
- Adds a new DataElement to the Asset Administration Shell's Submodel
Parameter
- (body): The DataElement's description object
Response codes
- 201: DataElement created successfully
- 400: Bad Request
- 404: Submodel not found
- 502: Bad Gateway
|
GET
|
/submodel/operations
|
Description
- Retrieves all Operations from the current Submodel
Parameter
Response codes
- 200: Success
- 404: Submodel not found / No Operations found
- 502: Bad Gateway
|
POST
|
/submodel/operations
|
Description
- Adds a new operation to the Asset Administraiton Shell's Submodel
Parameter
- (body): The operation description object
Response codes
- 201: Operation created successfully
- 400: Bad Request
- 404: Submodel not found
- 502: Bad Gateway
|
GET
|
/submodel/events
|
Description
- Retrieves all Events from the current Submodel
Parameter
Response codes
- 200: Success
- 404: Submodel not found / No Events found
- 502: Bad Gateway
|
POST
|
/submodel/events
|
Description
- Adds a new event to the Asset Administration Shell's Submodel
Parameter
- (body): The Event description object
Response codes
- 201: Event created successfully
- 400: Bad Request
- 404: Submodel not found
- 502: Bad Gateway
|
GET
|
/submodel/dataElements/{dataElementId}
|
Description
- Retrieves a specific DataElement from the Asset Administrations's Submodel
Parameter
- dataElementId: The DataElement's short id
Response codes
- 200: Returns the requested DataElement
- 404: Submodel/DataElement not found
- 502: Bad Gateway
|
DELETE
|
/submodel/dataElements/{dataElementId}
|
Description
- Deletes a specific DataElement from the Asset Administration Shell's Submodel
Parameter
- dataElementId: The DataElement's short id
Response codes
- 200: DataElement deleted successfully
- 400: Bad Request
- 404: Submodel not found
- 502: Bad Gateway
|
GET
|
/submodel/dataElements/{dataElementId}/value
|
Description
- Retrieves the value of a specific DataElement from the Asset Administrations Shell's Submodel
Parameter
- dataElementId: The DataElement's short id
Response codes
- 200: Returns the requested DataElement's value
- 404: Submodel/DataElement not found
- 502: Bad Gateway
|
PUT
|
/submodel/dataElements/{dataElementId}/value
|
Description
- Updates the Asset Administration Shell's Submodel's DataElement
Parameter
- dataElementId: The DataElement's short id
- (body): The new value
Response codes
- 200: DataElement's value changed successfully
- 404: Submodel/DataElement not found
- 502: Bad Gateway
|
GET
|
/submodel/operations/{operationId}
|
Description
- Retrieves a specific Operation from the Asset Administration Shell's Submodel
Parameter
- operationId: The Operation's short id
Response codes
- 200: Success
- 404: Submodel/Operation not found
- 502: Bad Gateway
|
POST
|
/submodel/operations/{operationId}
|
Description
- Invokes a specific operation from the Asset Administration Shell' Submodel with a list of input parameters
Parameter
- operationId: The operation's short id
- (body): List of input arguments
Response codes
- 200: Operation invoked successfully
- 400: Bad Request
- 404: Submodel not found
- 502: Bad Gateway
|
DELETE
|
/submodel/operations/{operationId}
|
Description
- Deletes a specific Operation from the Asset Administration Shell's Submodel
Parameter
- operationId: The Operation's short id
Response codes
- 200: Operation deleted successfully
- 400: Bad Request
- 404: Submodel not found
- 502: Bad Gateway
|
GET
|
/submodel/events/{eventId}
|
Description
- Retrieves a specific event from the Asset Administration Shell's Submodel
Parameter
- eventId: The Event's short id
Response codes
- 200: Success
- 404: Submodel/Event not found
- 502: Bad Gateway
|
DELETE
|
/submodel/events/{eventId}
|
Description
- Deletes a specific event from the Asset Administration Shell's Submodel
Parameter
- eventId: The Event's short id
Response codes
- 200: Event deleted successfully
- 400: Bad Request
- 404: Submodel not found
- 502: Bad Gateway
|