BaSyx / Documentation / API / Submodel

"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 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
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
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
GET	/submodel	Description Retrieves the Submodel 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