1. Overview
   1. Meta Data
   2. Gateways and Commander Digital Twins
      1. How the Routing Key/Gateway Path is constructed in Commander
      2. Regular Expressions (RegEx) and gateways to Digital Twin endpoints:

Overview

Once the SDK has been installed, Devices have been chosen and the SDK is connected to the V-Raptor, the chosen Device can now be configured to send telemetry from connected physical devices to Commander.

In order for Commander to process telemetry from the V-Raptor accurately, a gateway needs to be configured in both Commander and the Device Interface in the SDK.

Creating a gateway entails configuring the meta data (and including a Gateway Id) in the Driver’s Device Interface, and matching this meta packet to a format that Commander is configured to identify.

Meta Data

Meta data is data that physical devices send about the instrument itself. Examples of meta data include the physical device’s type, name, serial number, etc.

Once the Device Integration (Driver) microservice executes, it will send meta data (meta requests) to the Collector microservice before sending telemetry data (telemetry requests).

This is done manually by the Receptor Device.

Gateways and Commander Digital Twins

Digital Twins are templates created in Commander that represent data being sent from the V-Raptor.

Each instance of a Digital Twin includes a Routing Key (or Gateway Path) that will conform to a certain structure. This structure creates a unique identifier for a specific data point. It includes all the properties the Digital Twin will need in order to connect the telemetry sent from the physical device to the correct endpoints created in the Digital Twin.

For more information about how to create a Digital Twin instance, see existing documentation about Digital Twins.

How the Routing Key/Gateway Path is constructed in Commander

The image below shows an example of a Digital Twin for an energy meter:

Figure 1 - Single Phase Energy Meter Digital Twin Example

The Routing Key will include the following properties, in the order provided below:

It will be written in Commander in the following way:

<GatewayId>.<GroupName>:<DeviceType>|<DeviceId>.<Property>

These properties should be configured using the following rules:

• Gateway Id: The property which can scale in the application. This can be the serial number of the physical device, which in most cases will be extracted from the telemetry the physical devices are sending to the Driver.
• Group Name: A common characteristic found in all the devices linked to this Digital Twin. Examples of this grouping include:
  • Power
  • Environmental
  • Security
• Device Type: The purpose of the device, for example Energy Meter.
• Device Id: The brand (product name) of the physical device (for example, Kamstrup).
• Property: The property that the device is measuring, for example.

An example of a Routing Key with the following characteristics (using the example Digital Twin shown in Figure 1):

• The device serial number is the Gateway Id.
• The device is part of a group of devices measuring power.
• Devices being linked are energy meters (i.e. “AC Meter”).
• The brand (product name) of the device is Kamstrup.
• The data point (property from the physical device) that needs to be read and pulled through to the Digital Twin endpoint is “Current”. In the example above (Figure 1), one of the endpoints is “Current”. We will use this endpoint as an example to build our Routing Key.

The structure will be compiled like this in Commander:

123532.Power:ACMeter|Kamstrup.Current

The following rules need to be applied when creating Routing Key:

• Important - when creating a Gateway Id, either in Commander or in building a Registration message in the Device, do not use underscores to separate parts of the value. For example, for a Gateway ID with multiple words (e.g. Kamstrup Device), make the Gateway Id KAMSTRUP-DEVICE or KamstrupDevice. Do not write it as Kamstrup_Device or KAPSTRUP_DEVICE.
• Do not use spaces. If one field has multiple words, rather use a dash to separate the words or capitalise the first letter of each word.
• No special characters are allowed in the Routing Key.
• Use generally known terms when naming the fields.
• Ensure the spelling is correct.

These properties will also be configured in the SDK to match this format.

Regular Expressions (RegEx) and gateways to Digital Twin endpoints:

To make sure the gateway knows which endpoint to link to within the Digital Twin instance, use the Routing Key and provide for all possible versions of these data points (this is known as creating the RegEx).

From the Routing Key example above, the general structure is the following:

<Gateway Id>.<Group Name>:<Device Type>|<Device Id>.<Property>

And the example Routing Key is the following:

123532.Power:ACMeter|Kamstrup.Current

To make this a RegEx, the string above needs to be modified to include all possible versions of this key.

For example, in a use case where an AC Meter Digital Twin is created for different types of energy meters with the same endpoints, the Digital Twin could present as Figure 1 above.

To define a RegEx to which the “Current” endpoint needs to link, taking into account there are possibly multiple device types linking to this AC Meter Digital Twin, the RegEx for the “Current” Gateway Path will be structured in the following way:

<Gateway Id>.Power.EnergyMeter\|(Kamstrup|LandisGyr|MeterStar).Current

Note that all possible Device Ids are added to the string so that the RegEx will search for all relevant gateways related to any of those Device Ids. Also note that the first pipe | is preceded by an escape character (“\”) so that this part of the string is not read as an “or” argument.

The RegEx will search for any version of this expression, and link it to the relevant endpoint (in this case the “Current” endpoint) in the Digital Twin.

The Gateway Id will be a placeholder that will be populated once telemetry is received from the V-Raptor.