Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "BaSyx / Documentation / Components / AAS Server"

(AASX Upload)
m
 
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{| class="wikitable"
 
{| class="wikitable"
| [[BaSyx_/_Documentation_/_AssetAdministrationShell | Overview]]  <nowiki>|</nowiki>  [[BaSyx_/_Documentation_/_API_/_AssetAdministrationShell| Interface]]  <nowiki>|</nowiki>  [[BaSyx_/_Documentation_/_Implementation_/_AssetAdministrationShell | Implementation]]  <nowiki>|</nowiki>  [[BaSyx_/_Documentation_/_Components_/_AAS_Server | Component]]
+
| [[BaSyx_/_Documentation_/_AssetAdministrationShell | Overview]]  <nowiki>|</nowiki>  [[BaSyx_/_Documentation_/_API_/_AssetAdministrationShell| Interface]]  <nowiki>|</nowiki>  [[BaSyx_/_Documentation_/_Implementation_/_AssetAdministrationShell | Implementation]]  <nowiki>|</nowiki>  [[BaSyx_/_Documentation_/_Components_/_AAS_Server | Component]] <nowiki>|</nowiki> [[BaSyx_/_Documentation_/_Components_/_AAS_Server_/_Features | Features]]
 
|}
 
|}
  
Line 15: Line 15:
 
The AAS Server image is made available via [https://hub.docker.com/r/eclipsebasyx/aas-server Docker Hub] and can be pulled by:
 
The AAS Server image is made available via [https://hub.docker.com/r/eclipsebasyx/aas-server Docker Hub] and can be pulled by:
  
  docker pull eclipsebasyx/aas-server:1.2.0
+
  docker pull eclipsebasyx/aas-server:1.5.1
  
 
Alternatively, the command described in Startup section will download the image.
 
Alternatively, the command described in Startup section will download the image.
Line 23: Line 23:
 
To easily start the AAS server component, you can use the following command:
 
To easily start the AAS server component, you can use the following command:
  
  docker run --name=aas -p 8081:4001 eclipsebasyx/aas-server:1.2.0
+
  docker run --name=aas -p 8081:4001 eclipsebasyx/aas-server:1.5.1
  
 
Next, the HTTP/REST endpoint of the server with its AAS is accessible via
 
Next, the HTTP/REST endpoint of the server with its AAS is accessible via
Line 41: Line 41:
 
As with the other components, the server's context can be customized using the [[BaSyx_/_Documentation_/_Components_/_Context | context configuration]].
 
As with the other components, the server's context can be customized using the [[BaSyx_/_Documentation_/_Components_/_Context | context configuration]].
  
== AAS Configuration ==  
+
== AAS Server Configuration ==  
  
For the AAS server component, three main options can be configured:
+
For the AAS server component, a multitude of features can be configured via the aas.properties file. By default, this configuration file is assumed to be located at ''"/usr/share/config/aas.properties"'' within the container.
* The backend
+
* The AAS source file
+
* The registry url
+
  
Additionally the usage of MQTT events, the option to upload *.aasx files, and basic authorization options can be set.
 
 
By default, this configuration file is assumed to be located at ''"/usr/share/config/aas.properties"'' within the container.
 
 
Thus, another configuration file can be set by mounting a local configuration file into the container during startup. As an example, a local folder containing the configuration files can be mounted using:
 
Thus, another configuration file can be set by mounting a local configuration file into the container during startup. As an example, a local folder containing the configuration files can be mounted using:
  
  docker run --name=aas -p 8081:4001 -v C:/tmp:/usr/share/config eclipsebasyx/aas-server:1.2.0
+
  docker run --name=aas -p 8081:4001 -v C:/tmp:/usr/share/config eclipsebasyx/aas-server:1.5.1
  
 
In this example, the '''aas.properties''' file is located in C:/tmp/. Similarly, the AAS source file also needs to be mounted into the docker container.
 
In this example, the '''aas.properties''' file is located in C:/tmp/. Similarly, the AAS source file also needs to be mounted into the docker container.
  
=== Backend ===
+
The features of the AAS Server component are documented on their own page:
 
+
[[BaSyx_/_Documentation_/_Components_/_AAS_Server_/_Features | Features]]
By default, an empty InMemory server is started. The backend can be changed with the option
+
 
+
aas.backend=InMemory
+
 
+
Currently, the other valid option for the backend is '''MongoDB''' that persists the whole AAS together with its submodels in a MongoDB. Additionally, it is possible to give an input file for the server using an absolute file path:
+
 
+
=== Initial AAS Source ===
+
 
+
aas.source=/usr/share/config/myAAS.aasx
+
 
+
This loads the file myAAS.aasx into the server as soon as it is started. For input files, the json and xml serializations are supported as well:
+
 
+
aas.source=/usr/share/config/myAAS.xml
+
 
+
Additionally, it is possible to specify multiple aas sources using a JSON syntax:
+
 
+
aas.source=["json/aas.json","aasx/aas.aasx","xml/aas.xml"]
+
 
+
=== Registry Integration ===
+
Furthermore, when loading a default AAS, it can be registered in an external registry by specifying the registry url. The registry path depends on the deployment location. Thus, when starting a local docker registry for testing purposes, it needs to be in the same docker network as the AAS to be reachable. So for a non-docker deployment, the registry address could be:
+
 
+
registry.path=http://localhost:4000/registry/
+
 
+
Whereas it could be different for a deployment with docker containers:
+
 
+
registry.path=http://registry:4000/registry/
+
 
+
See also the official [https://docs.docker.com/network/ Docker documentation] for more information on that topic.
+
 
+
Additionally, the AAS Server will try to look up unknown submodels of hosted AAS via the registry, if they can't be found within the AAS Server itself.
+
 
+
 
+
If the external URL of the AAS Server differs from its internal address, this external address can be specified to be used when auto registering AASs/Submodels:
+
 
+
registry.host=http://external-address:4000/aasServer
+
 
+
If this value is not specified the internal address of the AAS Server will be used.
+
 
+
=== MQTT Eventing ===
+
 
+
Eventing via MQTT is disabled by default. It can be enabled in the aas.properties file as well. This will publish events for every action to a separately specified server:
+
 
+
aas.events=MQTT
+
aas.events=None
+
 
+
=== AASX Upload ===
+
The option to upload *.aasx files via multipart form upload is enabled by default. It can be configured in the aas.properties:
+
 
+
aas.aasxUpload=Enabled
+
aas.aasxUpload=Disabled
+
 
+
 
+
If this feature is enabled, it is possible to use the following endpoint for uploading the file via multipart form upload with an HTTP-POST request:
+
http://<server>:<port>/<contextPath>/shells/aasx
+
 
+
Use the following code to create an AAS aggregator with AASX-Upload function:
+
 
+
  IAASAggregator aasAggregator = new AASAggregatorAASXUpload(new AASAggregator());
+
 
+
In order to upload an AASX package to the AAS-server, use the method uploadAAX(InputStream aasxStream)to upload an AASX-package. Befor that, it is worth to pay attention that the AASX-package must be load as an input-stream. The following code example shows how to perform this step. We assume that the path of the AASX-package is specified by the AASX_PATH with:
+
 
+
  public static final String AASX_PATH = "src/test/resources/aas/factory/aasx/01_Festo.aasx";
+
 
+
Uploading an aasx works as following:
+
 
+
  File file = Paths.get(AASX_PATH).toFile();
+
  aggregator.uploadAASX(new FileInputStream(file));
+
+
The complete unit-test for AASXUpload can be found under: https://github.com/eclipse-basyx/basyx-java-sdk/blob/main/src/test/java/org/eclipse/basyx/testsuite/regression/extensions/aas/aggregator/aasxupload/TestAASAggregatorAASXUploadSuite.java
+
 
+
=== Authorization ===
+
 
+
Authorization is disabled by default. Basic authorization can be configured in the aas.properties:
+
 
+
aas.authorization=Enabled
+
aas.authorization=Disabled
+
 
+
== MongoDB Backend ==
+
 
+
Uses a MongoDB backend that can be configured using the .properties files in ''src/main/resources'' of the components. Similar to the SQL backend, for the MongoDB backend, another [[BaSyx_/_Documentation_/_Components_/_MongoDB | configuration file]] can be specified.
+
 
+
== InMemory Backend ==
+
 
+
Stores the Registry entries in RAM. ''!!Please be aware that this is not persistent and therefore only for testing! After component restart, all entries are lost. Use this only for testing!!''
+
 
+
== Eventing with MQTT ==
+
 
+
Additionally, to the '''aas.properties''' file, you need to edit the [[BaSyx_/_Documentation_/_Components_/_MQTT | '''mqtt.properties''' file]] in order to connect to the right MQTT broker. The MQTT configuration file can be found in the same folder as the AAS configuration. It allows you to add credentials and a Quality of Service level (default: 1) besides the mandatory server address.
+
By default the configuration adds a whitelist for filtering specific submodel/submodelelement events to avoid unnecessary messages.
+
 
+
Information about what events will be published can be found in the [[BaSyx_/_Developer_/_Extensions_/_Eventing | eventing extension]].
+
 
+
== Authorization ==
+
 
+
The authorization is a basic implementation to enable only authorized requests for <code>WRITE</code> and <code>READ</code> operations for both the AAS and the submodels.
+
This implementation uses OAuth2 tokens and scopes, with the scopes being defined [[https://github.com/eclipse-basyx/basyx-java-sdk/blob/development/src/main/java/org/eclipse/basyx/extensions/submodel/aggregator/authorization/SubmodelAggregatorScopes.java#L10-L11 for submodels]] and [[https://github.com/eclipse-basyx/basyx-java-sdk/blob/development/src/main/java/org/eclipse/basyx/extensions/aas/aggregator/authorization/AASAggregatorScopes.java#L20-L21 for the AAS]].
+
As long as the token includes the respective scopes, an operation can be performed if the authorization is enabled.
+
 
+
An example for the authorization can be found in the [[BaSyx_/_Scenarios_/_Authorization | scenario with Keycloak]].
+
 
+
== Operation Delegation ==
+
An operation is a specific type of submodel element that is capable of performing server-side functions. However, in certain environments this is not possible. Therefore, the operation can be delegated to an independent destination URL to be executed.
+
The operation invocation request is defined on [https://app.swaggerhub.com/apis/BaSyx/basyx_submodel_http_rest_api/v1#/Submodel/InvokeOperationByIdShort swaggerhub]. The type and the number of the in and output variables is defined within the operation itself. An example request body is given below. The strong and italic formatted attribute(s) <code>value</code> is/are the value(s) to be processed by the operation.
+
{
+
    "requestId": "1",
+
    "timeout": 60,
+
    "inputArguments": [{
+
      "value": {
+
          "idShort": "in",
+
          "valueType": "integer",
+
          '''''"value": 1''''',
+
          "modelType": {
+
            "name": "Property"
+
          }
+
      }
+
    }]
+
}
+
Alternatively to the full request body above, the raw data can simply be passed as an array of values to be processed by the operation. In this case, the response would also consist of raw data instead of a structured body.
+
 
+
# To create an operation delegation, an AAS with a Submodel that has a Operation(-SubmodelElement) must be present.
+
## The Operation has neither input, output nor inout variables
+
## To achieve the Delegation functionality, a Qualifier of type "invocationDelegation" is added to the operation.
+
##* As value, the url to the desired operation must be given.
+
##* The url follows the pattern
+
:::: <code>http://{server}:{port}/{contextPath}/{idShortPathToOperation}/invoke</code>
+
::::resp. it is the url for direct operation invocation.
+
::::* Knowledge about the operation to be delegated to, with regard to the number and type of input and output parameters is assumed.
+
 
+
This achieves that operations can be delegated to endpoints of the same server as well as to external servers. For the frontend it remains completely transparent whether an operation was called directly or delegated.
+
  
 
== Java Implementation ==
 
== Java Implementation ==

Latest revision as of 03:47, 5 February 2024

Overview | Interface | Implementation | Component | Features

AAS Server Component

The AAS server component provides an empty AAS server that can be used to host several AAS and Submodels. For its API usage see Aggregator API. Additionally, there's a video illustrating the configuration and usage in 5 minutes: YouTube.

For a complete deployment of the AAS infrastructure, additionally to this server a registry is needed. For this registry, the Registry Component can be used.

For illustration on how to create an AAS on the server provided by the component and how to retrieve it see the snippet in the repository.

Download

The AAS Server image is made available via Docker Hub and can be pulled by:

docker pull eclipsebasyx/aas-server:1.5.1

Alternatively, the command described in Startup section will download the image.

Startup

To easily start the AAS server component, you can use the following command:

docker run --name=aas -p 8081:4001 eclipsebasyx/aas-server:1.5.1

Next, the HTTP/REST endpoint of the server with its AAS is accessible via

http://localhost:8081/aasServer/shells/

If there's no AAS configured during startup, an empty JSON list "[]" will be returned.

And the container can be stopped, started and removed using its name (see --name):

docker stop aas
docker start aas
docker rm aas

Context Configuration

As with the other components, the server's context can be customized using the context configuration.

AAS Server Configuration

For the AAS server component, a multitude of features can be configured via the aas.properties file. By default, this configuration file is assumed to be located at "/usr/share/config/aas.properties" within the container.

Thus, another configuration file can be set by mounting a local configuration file into the container during startup. As an example, a local folder containing the configuration files can be mounted using:

docker run --name=aas -p 8081:4001 -v C:/tmp:/usr/share/config eclipsebasyx/aas-server:1.5.1

In this example, the aas.properties file is located in C:/tmp/. Similarly, the AAS source file also needs to be mounted into the docker container.

The features of the AAS Server component are documented on their own page: Features

Java Implementation

Within the project, the component can be found in the Java repository at Java. In this project, the executable can take the parameter BASYX_AAS to configure the path of the aas configuration file. For example, you can specify the path of the aas configuration file via

java -jar -DBASYX_AAS="C:/tmp/aas.properties" aas.jar

Back to the top