BaSyx Device AAS (1)

This scenario explains the adding of a new device to a production environment. It illustrates how a device that contains an AAS transfers this AAS to an AAS server, which ensures the availability of the device AAS also if the device fails to operate later. This scenario also illustrates uploading of AAS sub models to a sub model server, registration of AAS and sub models with a central registry, continuous updating of sub model properties with live data by the device, and how e.g. a dashboard may access device sub models to display live status data.

Devices may opt to implement their own sub model servers and provide sub model property values on request, or to upload sub models to servers and regularly update the values of remote properties. Sub models with high-frequent value changing properties should be kept in the device, which requires developers to implement a sub model server in their devices.

The BaSys setup for this functional example is the following:

This functional example illustrates the following steps:

1. Adding of a new device

// 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");

1.1. Device manager function of device transfers the device AAS to AAS server

// AAS URL on server
String aasURLOnServer = "/aas/submodels/aasRepository/"+deviceAASID.getEncodedURN();
// - Transfer device AAS to server
connSubModel.createElement(aasURLOnServer, aas);

1.2. Device manager instantiates status sub model with an ID

// The device also brings a sub model structure with an own ID that is being pushed on the server
ModelUrn deviceStatusSMID = new ModelUrn("de.FHG", "devices.es.iese", "statusSM", "1.0", "3", "x-509", "001");
// - Create generic sub model 
SubModel_ statusSM = new SubModel_();
((Map<String, Object>) statusSM.get("properties")).put("status", "offline");

1.3. Device manager transfers its status sub model to sub model server

// Sub model URL on server
String statusSubmodelURLOnServer = "/aas/submodels/aasRepository/"+deviceStatusSMID.getEncodedURN();
// - Transfer device sub model to server
connSubModel.createElement(statusSubmodelURLOnServer, statusSM);

1.4. Device manager registers AAS on server in registry. The AAS contains a sub model descriptor for the sub model.

// Register AAS and sub models in directory (push AAS descriptor to server)
// - Create an AAS descriptor
AASDescriptor deviceAASDescriptor = new AASDescriptor(deviceAASID.getURN(), Identification.URI, aasSrvURL+aasURLOnServer);
// - Add a sub model descriptor for device
SubmodelDescriptor deviceStatusSubmodelDescriptor = new SubmodelDescriptor(deviceStatusSMID.getURN(), Identification.URI, aasSrvURL+statusSubmodelURLOnServer);
deviceAASDescriptor.addSubmodelDescriptor(deviceStatusSubmodelDescriptor);
// - Push AAS descriptor to server
client.post(wsURL+"/api/v1/registry", JSONTools.Instance.serialize(deviceAASDescriptor).toString());

2. Device control component updates of “status” property in status sub model to “ready”

connSubModel.updateElementValue(statusSubmodelURLOnServer+"/properties/status", "ready");

3. Application component, e.g. dashboard accesses device status

3.1. Dashboard looks up device AAS

// Lookup device AAS
// - Lookup AAS from AAS directory, get AAS descriptor
String jsonData = client.get(wsURL+"/api/v1/registry/"+deviceAASID.getEncodedURN());
// - De-serialize AAS descriptor
AASDescriptor aasDescriptor = new AASDescriptor((Map<String, Object>) JSONTools.Instance.deserialize(new JSONObject(jsonData)));

3.2. Dashboard retrieves status sub model end point from AAS descriptor

// - Get information about status sub model
SubmodelDescriptor smDescriptor = aasDescriptor.getSubModelDescriptor(deviceStatusSMID.getURN());

3.3. Dashboard connects to status sub model provider

// Connect to status sub model end point
VABElementProxy connSM = connManager.connectToVABElementByURL(smDescriptor.getFirstEndpoint());

3.4. Dashboard queries "ready" property of sub model

Map<String, Object> deviceSM = (Map<String, Object>) connSM.readElementValue("/");
// - Output status information
System.out.println("ReadBack:"+((Map<String, Object>) deviceSM.get("properties")).get("status"));