View source for BaSyx RAW AAS/Submodel provider

== RAW AAS/Sub model provider static configuration == 

The Raw AAS/sub model provider provides the values described in its configuration file as virtual automation bus object. Through this configuration file, the complete structure of the exported object may be configured, which includes its meta data. This way, an Asset Administration Shell, a sub model, or any other object may be exported. The raw AAS/sub model provider is implemented by servlet class <code>org.eclipse.basyx.components.servlets.RawCFGSubModelProviderServlet</code>. It accepts the following configuration parameter:

:: config: Path to configuration file

The following snippet illustrates an Apache Tomcat configuration for the sub model provider ''Example_RawProvider''. It configures the location of the configuration file inside the WEB-INF folder and configures the URL pattern that is used to access the sub model to <code>/Testsuite/components/BaSys/1.0/provider/rawcfgsm/*</code>. 


<syntaxhighlight lang="xml">
  <servlet>
    <servlet-name>Example_RawProvider</servlet-name>
    <servlet-class> org.eclipse.basyx.components.servlets.RAWCFGSubModelProviderServlet </servlet-class>
 
    <init-param>
        <param-name>config</param-name>
        <param-value>/WEB-INF/config/rawprovider/samplecfg.properties</param-value>
    </init-param>
    
    <load-on-startup>5</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>Example_RawProvider</servlet-name>
    <url-pattern>/Testsuite/components/BaSys/1.0/provider/rawsm/*</url-pattern>
  </servlet-mapping>
</syntaxhighlight>


The main configuration file of the Raw AAS/sub model provider contains the sub model ID and all sub model properties and meta data properties that are exported by the RAW AAS/sub model provider. For a more in depth description, please refer to <<<PDF>>>. 

:: basyx.submodelID  ID of sub model

Meta data of sub models needs to be exported as properties. The property definition 

::<code>administration/version = 1.0</code> 

defines the value of meta data administration/version to value 1.0. Property values are exported as strings by default. Changing a type is supported via the $ftype extension. Therefore, adding the line

::<code>administration/version$ftype = int</code>

defines that the administration/version property should be exported as integer value.


== Example static configuration == 

The following illustrates an example configuration file for the RAW AAS/sub modelfile provider:

<syntaxhighlight lang="properties" style="margin-left: 2em">
# ##############################################################
# Configuration sub model provider configuration file
# ##############################################################


# ##############################################################
# Sub model provider configuration

# Name of provided sub model
basyx.submodelID       = rawSampleCFG


# ##############################################################
# Sub model meta data

# Sub model version
administration/version           = 1.0



# ##############################################################
# Exported configuration


# Export property "cfgProperty1" and its meta data
properties/cfgProperty1/value        = exampleStringValueRaw
properties/cfgProperty1/description  = Configuration property description

# Export property "cfgProperty2" and its meta data
properties/cfgProperty2/value        = 12
properties/cfgProperty2/value$ftype  = int
properties/cfgProperty2/description  = Configuration property description \
                                       on multiple lines

# Export property "cfgProperty3" and its meta data
properties/cfgProperty3/value        = 45.8

# Export property "cfgProperty4" and its meta data
cfgProperty4/value        = 44.8
cfgProperty4/description  = Another configuration property description
cfgProperty4/newMetaData  = 8
</syntaxhighlight>


Exporting a conforming sub model with the raw AAS/sub model provider requires the configuration file to define all required meta data properties for a sub model, as defined in <<<PDF>>>. The following configuration file excerpt defines a RAW AAS/sub model provider configuration file that describes meta data for a sub model:


<syntaxhighlight lang="properties" style="margin-left: 2em">
# ##############################################################
# Sub model meta data

# Sub model version
administration/version           = 1.0
</syntaxhighlight>


== RAW AAS/Sub model provider dynamic model deployment ==
In addition to the aforementioned static configuration through configuration file properties, the raw AAS/sub model provider also enables the dynamic deployment of VAB objects, e.g. sub models and asset administration shells. Dynamic sub model deployments require the sub model to be deployed as JSON serialized object that conform to the serialization format of the platform Industrie 4.0 (cf. <<<>>>). The standard provider REST calls (see here) may be used to put new VAB elements, AAS and sub models on the server, to query VAB elements, or to modify and add properties. 
In the following example, the BaSyx SDK is used to serialize a new Asset Administration Shell as JSON and to deploy it on a raw CFG sub model provider. 


<syntaxhighlight lang="java" style="margin-left: 2em">
// Server connections
// - Connect to AAS server
VABElementProxy connSubModel = this.connManager.connectToVABElement("AASServer");

// AAS repository server URL
String aasSrvURL = "http://localhost:8080/basys.examples/Testsuite/components/BaSys/1.0/aasserver";

// Create device AAS
// - Product ID (urn:<legalEntity>:<subUnit>:<subModel>:<version>:<revision>:<elementID>#<elementInstance>)
ModelUrn deviceAASID = new ModelUrn("de.FHG", "devices.es.iese", "aas", "1.0", "3", "x-509", "001");

// - Create device AAS
AssetAdministrationShell_ aas = new AssetAdministrationShell_();
aas.put("idShort", "DeviceIDShort");
// - Transfer device AAS to server
connSubModel.createElement("/aas/submodels/aasRepository/"+deviceAASID.getEncodedURN(), aas);
</syntaxhighlight>


== RAW AAS/sub model provider Java example ==

The following code snippets illustrate the RAW AAS/sub model provider use from the JAVA SDK. 


* Connect to RAW AAS/sub model provider via directory service. RAW AAS/sub model provider is available with ID CfgFileTestAAS. 
<syntaxhighlight lang="java" style="margin-left: 2em">
// Connect to sub model "TestAAS"
VABElementProxy connSubModel = this.connManager.connectToVABElement("TestAAS");
</syntaxhighlight>


* Read property value from a property exported by RAW AAS/sub model provider. When non-existint properties are read, a null object is returned.
<syntaxhighlight lang="java" style="margin-left: 2em">
// Get property value
Object value1 = connSubModel.readElementValue("/aas/submodels/TestAAS/properties/cfgProperty1/value");
</syntaxhighlight>


* Read property meta data
<syntaxhighlight lang="java" style="margin-left: 2em">
// Get property meta data value
Object value1meta = connSubModel.readElementValue("/aas/submodels/TestAAS/properties/cfgProperty1/description");
</syntaxhighlight>


* Read sub model meta data
<syntaxhighlight lang="java" style="margin-left: 2em">
// Get sub model meta data value
Object subModelDescription = connSubModel.readElementValue("/aas/submodels/TestAAS/description");
</syntaxhighlight>


* Update propery or sub model value. The RAW AAS/sub model provider supports changing, creating, and deletion of property values. It however currently does not back up properties to a persistent storage (but we are working on that). Changes are therefore lost after the provider servlet is restarted.
<syntaxhighlight lang="java" style="margin-left: 2em">
// Update property value
connSubModel.updateElementValue("/aas/submodels/TestAAS/administration/version", "2.0");
</syntaxhighlight>


* Create propery or sub model value. The  RAW AAS/sub model provider supports changing, creating, and deletion of property values. It however does not back up properties to a persistent storage. Changes are therefore lost after the provider servlet is restarted.
<syntaxhighlight lang="java" style="margin-left: 2em">
// Create property value
connSubModel.createElement("/aas/submodels/TestAAS/administration/version2", "3.0");
</syntaxhighlight>


* Delete propery or sub model value. The  RAW AAS/sub model provider supports changing, creating, and deletion of property values. It however does not back up properties to a persistent storage. Changes are therefore lost after the provider servlet is restarted.
<syntaxhighlight lang="java" style="margin-left: 2em">
// Delete property value
connSubModel.deleteElement("/aas/submodels/TestAAS/administration/version2");
</syntaxhighlight>


* Read complete sub model 
<syntaxhighlight lang="java" style="margin-left: 2em">
// Get complete sub model
Object value3 = connSubModel.readElementValue("/aas/submodels/TestAAS");
</syntaxhighlight>