• broker endpoints and credentials for listening to device IoT data.

• backend credentials for performing REST API requests.

• certificates for client authentication and secure channel establishment.

Meta Data Events

The connector subscribes to events published under the topic EVENT.APP.METADATASERVICE.

According to the received event type the connector updates the things and gateways.

METADATA_DEVICE_INCLUDED

When an event is received, the connector performs the following steps:

1. Reads the message UUID and retrieves all the things having the mapping Asset Id equals to the UUID.
2. Reads all the attribute inside the metadata report message node.
3. Reads the value description report and group properties by prefix (name part before "_").
4. Filter the found things having the mapping path equals to the prefix (if preset).
5. If the thing is missing:
   1. Retrieves the Location by using the LocationId present into the attributes.
   2. Retrieves the Thing Definition having the "deviceTypeId" property equals to the DeviceTypeId present into the attributes.
   3. A new thing is created under the location.
6. The thing is activated
7. The Serial Number is updated by using the "SerialNumber" attribute.
8. The "GTW_SGTIN" thing property is updated by using the gateway SGTIN present into the event.
9. The "UUID" thing property is updated by using the UUID present into the event.
10. The "SGTIN" thing property is updated by using the device SGTIN present into the event.
11. The "deviceUsageId" thing property is updated by using the metadata report "DeviceUsageId" value.
12. The "PATH" thing property is updated by using the metadata indexed prefix path (if present).
13. The "MeterSerialNumber" thing property is updated by using the metadata report "MeterSerialNumber" value.
14. The "MeterDeviceUsage" thing property is updated by using the metadata report "MeterDeviceUsage" value.
15. Update any other property with group "Connector" with the relative metadata report value, by suing the thing property name as key (also replacing "-" with "_").
16. Updates thing properties whose name is prefixed by "device_". 
    
    

METADATA_CHANGED

When an event is received, the connector performs the sames steps as per METADATA_DEVICE_INCLUDED events without the thing provisioning steps.

METADATA_DEVICE_REMOVED

When an event is received, the connector performs the following steps:

1. Reads the message UUID and retrieves all the things having the mapping Asset Id equals to the UUID.
2. Deletes all the found things.
3. Optionally uses the metadata report "LocationId" attribute to search for things to delete.
   
   

METADATA_DEVICE_EXCLUDED

When an event is received, the connector performs the following steps:

1. Reads the message UUID and retrieves all the things having the mapping Asset Id equals to the UUID.
2. Deactivates all the found things.
3. Optionally uses the metadata report "LocationId" attribute to search for things to deactivate.
   
   

METADATA_GATEWAY_INCLUDED

When an event is received, the connector performs the same steps for the METADATA_DEVICE_INCLUDED, but limited to the gateway device type creation. You must have a thing definition having the same "DeviceTypeId" property value, or "Gateway" as fallback "DeviceTypeId" value.

METADATA_GATEWAY_REMOVED

When an event is received, the connector performs no steps, so the event at the moment is discarded.

Device Description Reported Events

The connector subscribes to events published to this topic EVENT.APP.TOPOSERVICE.DEVICE_DESCRIPTION_REPORTED.

You can define properties of things with the prefix "device_" in the name; the connector updates these properties based on the contents of the DEVICE_DESCRIPTION_REPORTED event.

Note that, to identify the thing to be updated, it is mandatory to define the thing property named "SGTIN". This property is automatically updated by the connector during METADATA events processing (e.g. METADATA_DEVICE_INCLUDED, METADATA_CHANGED).

 When an event is received, the connector performs the following steps:

1. Retrieves the Thing by SGTIN.
2. Extracts all the "device_description_report" child nodes having the "name" attribute equal to "info".
3. For each element, reads the "type_id" attribute.
4. Searches for a property whose name is equal to "device_<@type_id>".
5. If the property is missing replaces the "-" character with "_" and searches again.
6. Retrieves the value by reading one of these attributes: "number", "string", "hex".
7. Converts the value according to the property type (e.g. boolean 1 -> true).
8. Updates the property. 

Status Reported Events

The connector subscribes to events published to this topic EVENT.APP.STATUSSERVICE.STATUS_REPORTED.

When an event is received, the connector performs the following steps:

1. Retrieves the thing by using the SGTIN property which must be equal to the device SGTIN included in the message.
2. For each status report item, computes a JSON message and publish under the "LBStatusReport" thing metric.

TOPIC: <USERNAME>/<ASSET_ID>/ms
PAYLOAD:
{
  "ts" : 1719478178000,
  "data": {
     "LBStatusReport" : "<StatusReportItem as JSON>"
  }
}

Heartbeat Events

The connector subscribes to events published to this topic EVENT.APP.METADATASERVICE.METADATA_HEARTBEAT_REPORTED.

When an event is received, the connector performs the following steps:

1. Reads the message UUID and retrieves the gateway thing having the mapping Asset Id equals to the Gateway UUID.
2. For each metadata device retrieves the thing having the mapping Asset Id equals to the Device UUID.
3. If the gateway has been found, the heartbeat timestamp is publised under the "heartbeat" metric.
   

   TOPIC: <USERNAME>/<ASSET_ID>/ms
   
   PAYLOAD:
   {
     "ts" : 1719478178000,
     "data": {
        "heartbeat" : 1719478178000
     }
   }

4. For each identified thing, the location property "gatewayHeartbeat" is updated with the heartbeat timestamp.