Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
BaSyx / Documentation / Components / Registry
Overview | Interface | Component |
Contents
Registry Component
The Registry is a central component to the Asset Administration Shell (AAS) infrastructure for looking up available AAS and their contained submodels. Hence, it is realized as a separate component that can also be containerized. Currently, there exists a single Registry component that can be configured to utilize different types of backends.
Download
The registry image is made available via Docker Hub and can be pulled by:
docker pull eclipsebasyx/aas-registry:1.0.3
Alternatively, the command described in Startup section will download the image.
Startup
To easily start the registry component, you can use the following command:
docker run --name=registry -p 8082:4000 eclipsebasyx/aas-registry:1.0.3
Now the endpoint for registering and looking up AAS will be:
http://localhost:8082/registry/api/v1/registry
And the container can be stopped, started and removed using its name (see --name):
docker stop registry docker start registry docker rm registry
Context Configuration
As with the other components, the registry's context can be customized using the context configuration.
Backend Configuration
By default, the registry uses the non-persistent InMemory-"backend". This can be changed by providing a registry configuration file when starting the container. The configuration file contains a single property registry.properties and looks like this:
registry.backend=SQL
Eventing via MQTT can be enabled in the property file as well. This will publish events for every action to a separately specified server:
registry.events=MQTT
Together with SQL, the values InMemory and MongoDB are also allowed. By default, this configuration file is assumed to be located at "/usr/share/config/registry.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=registry -p 8082:4000 -v C:/tmp:/usr/share/config eclipsebasyx/aas-registry:1.0.3
In this example, the registry.properties file is located in C:/tmp/.
SQL Backend
Uses an SQL backend, e.g. postgres to persist registry entries. The connector to the SQL database can be configured with its own configuration file.
MongoDB Backend
Uses a MongoDB backend. Both, the SQL and the MongoDB variants 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
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!!
Authorized AAS Registry
As stated above in context configuration there are some properties stated related to JWT based Authorization. This Authorization mechanism makes authorized access to the AAS Registry. Read and write authorization is enabled. Inorder to read from the registry or write to the registry there is a need of authorized token.
Following steps to secure the endpoints of AAS Registry:
Step 1 : Create an instance of Authorized AAS registry proxy.
Code Snippet
private void createAuthorizedAASRegistryProxy() {
registry = new AuthorizedAASRegistryProxy(REGISTRY_ENDPOINT, authorizationProvider.getAuthorizationSupplier());
}
Step 2 : Create an instance of Connected AAS manager using the above instance of registry.
Code Snippet
private void createConnectedAASManager() {
IConnectorFactory connectorFactory = new HTTPConnectorFactory();
aasManager = new ConnectedAssetAdministrationShellManager(registry, connectorFactory);
}
Step 3 : Use the above Connected AAS manager to perform the general operation like Creating AAS, Creating Submodels etc.
Code Snippet to create AAS
private void createAssetAdministrationShellOnCloudServer() {
aasManager.createAAS(componentFactory.getAAS(), CLOUD_ENDPOINT);
}
Code Snippet to create Submodel
private void createSubmodelOnAasCloudServer() {
Submodel docuSubmodel = componentFactory.getDocuSM();
asManager.createSubmodel(aasIdentifier, docuSubmodel);
}
Complete example demonstrating above steps is here
Authorized_Registry_Example.
Eventing with MQTT
Additionally, to the registry.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 backend configuration. It allows you to add credentials and a Quality of Service level (default: 1) besides the mandatory server address.
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_REGISTRY to configure the path of the registry configuration file. For example, you can specify the path of the registry configuration file via
java -jar -DBASYX_REGISTRY="C:/tmp/registry.properties" registry.jar