Skip to main content
Jump to: navigation, search

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:

Submodel Services
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


BaSyx project links: Project BaSyx main wiki page | What is BaSyx? | BaSyx Developer Documentation

Back to the top