1. Account configuration in Commander
2. Blueprints
3. Understanding the telemetry streaming data package
4. Digital Twins and Entity tree structures
5. Adding a Blueprint tag to a Digital Twin

Telemetry streaming gives you the ability to monitor and react to events by giving you immediate access to the data you need most. This feature is not enabled by default, so please contact your IoT.nxt^® representative to have it enabled.

All Telemetry data configurations and the connection to Kafka is managed from the Core portal while all Telemetry data will be sent to your Kafka instance.

Account configuration in Commander

When Telemetry Streaming is deployed on your tenant, you will see the Telemetry Streaming menu item in your Commander platform.

Figure 1 - If enabled, you'll see the Telemetry streaming tab

On the Telemetry streaming tab, under Account configuration, you can Enable telemetry streaming, filtering and alarm streaming. Data will be streamed automatically once you have clicked the Update button.

Figure 2 - You can enable or disable Telemetry functions under Account management.

• Enable telemetry streaming: Enable to start streaming telemetry data.
• Enable filtering: Will only stream data for entities that are selected under Stream entities. When this checkbox is disabled, all data from devices that are linked to an entity will be streamed.
• Enable alarm streaming: If enabled all alarm events will be streamed.

Blueprints

A Blueprint is a template that matches the Entity ID with an easily identifiable Property Name that you specify. All the property names of a Blueprint must match existing entities in the immediate level of the group or site that you have tagged. In other words, the group must have endpoints with the same name as the property names in the Blueprint. You can also link a Blueprint to a widget and then have all the telemetry data that matches the Blueprint displayed in a widget.

It is important to note that if the properties of a Blueprint do not match the entities listed on your template, it will not be applied. You’ll need to ensure that all properties match before you can continue. Once they do, your Blueprint will be automatically applied.

When your Blueprints are configured correctly, you can start streaming telemetry data from your endpoints.

Figure 3 - Select the entities you want to receive data from.

To start, browse to the Telemetry streaming tab in Commander and select the Stream entities tab. You will see a list of all the entities you have set up. Browse to the entities you want to receive data from and make sure the checkbox is selected for each one.

Before data will be exported, you first need to link a gateway to each of the entities. To do this, click on an entity, then select the Gateways tab at the top of the window and search for the gateway you want to link to.

When this is done, your streaming packet will start to generate.

Understanding the telemetry streaming data package

The telemetry streaming data package is sent in a JSON structure to Kafka. The first part of the telemetry streaming package contains the header information and Endpoint IDs with associated telemetry data.

Figure 4 - The telemetry streaming data package.

• publishId: This is the key on which all the telemetry streaming data is published on. The publishId is represented by top level entity’s ID.
• isDigitwin: If the entity where data is streamed from is a Digitwin, then this will be set to true.
• entryTime: The time at which the change occurred
• fromUTC: The time of the previous packet
• postUtc: The time this packet was posted
• processUtc: The time this packet was processed
• enpoints: Contains a collection of Endpoints. Each line can contain an endpointId, triggerId, or functionId. The value received can be a simple value like a string or a complex object like a set of coordinates.

Please note: All UTC times are the values received or set when ingested, telemetry streaming does not change these values.

Figure 5 - The the blueprintMap package consists of [1] the entity path, [2] the blueprint name, and [3] the properties that are matched with the matching endpoint IDs.

• accountID: The account ID to from which the telemetry data is collected.
• metadata: A collection of blueprints.
• blueprintMap: These are the blueprints that are linked to your endpoints.

The blueprintMap includes the entity path to the group that is tagged with the blueprint, the blueprint name and property that is matched, as well as the enity ID that correlates with the endpoints.

Digital Twins and Entity tree structures

The Publish ID of all entities in a Digital Twin is always the root of the Digital Twin. Even if it is a nested Digital Twin. In the screenshot example below, the Entity ID of Capacity will be the Entity ID of Bravo Station in the hierarchy, it will not be collated under Battery 1’s ID as is the case with normal entities in a tree structure.

Figure 6 - Identifying the Publish ID of an entity in a Digital Twin.

Adding a Blueprint tag to a Digital Twin

When you design a Digital Twin, you can tag it with one or more Blueprints that you have created. Just like you do with entities, you create the Blueprint first, then you tag the digital design with the Blueprint. You do this for each level of the Digital Twin, whether its top level or nested.

To create a Blueprint, click on the Blueprint management icon on the left side menu. Then map your Property Names to the Endpoint IDs. Once created, the Blueprint will appear under Predefined Blueprints on the Digital Twin design page you are managing.

Figure 7 - Identifying the Publish ID of an entity in a Digital Twin.

When you are done designing your Blueprint and finished tagging your Digital Twins, you can activate the Digital Twin as per normal. When you provision the Digital Twin it will roll out with the new Blueprint tags attached.

Please note: Only the Blueprints that you apply as a Predefined Blueprint, or when you include a Blueprint as a nested item, is taken into account when the telemetry streamer exports the data.