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"

m
m (Fixes spelling)
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{| 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]]
 +
|}
 +
 
= AAS Server Component =
 
= AAS Server Component =
 
The AAS server component provides an empty AAS server that can be used to host several AAS and Submodels.
 
The AAS server component provides an empty AAS server that can be used to host several AAS and Submodels.
For its API usage see [[BaSyx_/_Documentation_/_API_/_AssetAdministrationShell | Aggregator API]].
+
For its API usage see [[BaSyx_/_Documentation_/_API_/_AssetAdministrationShell | Aggregator API]]. Additionally, there's a video illustrating the configuration and usage in  5 minutes: [https://www.youtube.com/watch?v=nGRNg0sj1oY YouTube].
In the following, a small code snippet shows its usage when it is already deployed. It assumes that somewhere a registry is already running. For this registry, the [[BaSyx_/_Documentation_/_Components_/_Registry | Registry Component]] can be used.
+
 
 +
For a complete deployment of the AAS infrastructure, additionally to this server a registry is needed. For this registry, the [[BaSyx_/_Documentation_/_Components_/_Registry | 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 [https://git.eclipse.org/r/plugins/gitiles/basyx/basyx/+/master/examples/basys.examples/src/test/java/org/eclipse/basyx/examples/snippets/aas/registry/ConnectToAASEndpoints.java snippet] in the repository.
 +
 
 +
== Download ==
 +
 
 +
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:0.1.0-PREVIEW
 +
 
 +
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:0.1.0-PREVIEW
 +
 
 +
Now the endpoint for accessing the server with its AAS is
 +
 
 +
http://localhost:8081/aasServer/shells/
 +
 
 +
And the container can be stopped, started and removed using its name (see --name):
 +
 
 +
docker stop aas
 +
docker start aas
 +
docker rm aas
 +
 
 +
== AAS Configuration ==
 +
 
 +
For the AAS server component, three options can be configured: The AAS source file, the backend and the registry url. 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:
 +
 
 +
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 .xml file ending is supported as well:
 +
 
 +
aas.source=/usr/share/config/myAAS.xml
 +
 
 +
Eventing via MQTT can be enabled in the property file as well. This will publish events for every action to a separately specified server:
 +
 
 +
aas.events=MQTT
 +
 
 +
Finally, 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.
 +
 
 +
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:0.1.0-PREVIEW
 +
 
 +
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.
 +
 
 +
== 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]].
 +
 
 +
== Java Implementation ==
  
<syntaxhighlight lang="java" style="margin-left: 4em">
+
Within the project, the component can be found in the Java repository at [https://git.eclipse.org/r/plugins/gitiles/basyx/basyx/+/master/components/basys.components/basyx.components.docker/basyx.components.AASServer/src/main/java/org/eclipse/basyx/components/aas/executable/ 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
AssetAdministrationShell shell = new AssetAdministrationShell();
+
IIdentifier identifier = new ModelUrn("aasId");
+
shell.setIdentification(identifier);
+
shell.setIdShort("aasIdShort");
+
  
                IAASRegistryService aasRegistry = new AASRegistryProxy(URL); // URL has to be filled in by the user to point to the AAS registry
+
java -jar -DBASYX_AAS="C:/tmp/aas.properties" aas.jar
ConnectedAssetAdministrationShellManager manager = new ConnectedAssetAdministrationShellManager(aasRegistry);
+
                manager.createAAS(shell, identifier, COMPONENT_URL); // Component URL has to filled in by the user to point to the component
+
  
                // The registered AAS can then be retrieved using a manager configured in the same way
+
== Context Configuration ==
IAssetAdministrationShell remote = manager.retrieveAAS(identifier);
+
  
</syntaxhighlight>
+
As with the other components, the server's context can be customized using the [[BaSyx_/_Documentation_/_Components_/_Context | context configuration]].

Revision as of 09:40, 10 September 2021

Overview | Interface | Implementation | Component

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:0.1.0-PREVIEW

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:0.1.0-PREVIEW

Now the endpoint for accessing the server with its AAS is

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

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

docker stop aas
docker start aas
docker rm aas

AAS Configuration

For the AAS server component, three options can be configured: The AAS source file, the backend and the registry url. 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:

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 .xml file ending is supported as well:

aas.source=/usr/share/config/myAAS.xml

Eventing via MQTT can be enabled in the property file as well. This will publish events for every action to a separately specified server:

aas.events=MQTT

Finally, 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 Docker documentation for more information on that topic.

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:0.1.0-PREVIEW

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.

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 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 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 eventing extension.

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

Context Configuration

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

Back to the top