Working with IoT device attributes

IIoTNext Platform provides the ability to assign custom attributes to your entities and manage these attributes. Those attributes are stored in the database and may be used for data visualization and data processing.

Attributes are treated as key-value pairs. Flexibility and simplicity of the key-value format allow easy and seamless integration with almost any IoT device on the market. Key is always a string and is basically an attribute name, while the attribute value can be either string, boolean, double, integer, or JSON. For example:

{
 "firmwareVersion":"v2.3.1", 
 "booleanParameter":true, 
 "doubleParameter":42.0, 
 "longParameter":73, 
 "configuration": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
 }
}

Attribute names

As a platform user, you can define any attribute name. However, we recommend to use camelCase. This make it easy to write custom JS functions for data processing and visualization.

Attribute types

There are three types of attributes. Let’s review them with examples:

Server-side attributes

This type of attribute is supported by almost any platform entity: Device, Asset, Customer, Tenant, User, etc. Server-side attributes are the ones that you may configure via Administration UI or REST API. The device firmware can’t access the server-side attribute.

 

Let’s assume you would like to build a building monitoring solution and review few examples:

1. The latitude, longitude, and address are good examples of server-side attributes you may assign to assets that represent a building or other real estate. You may use these attributes on the Map Widget in your dashboard to visualize the location of the buildings.
2. The floorPlanImage may contain a URL to the image. You may use this attribute to visualize the floor plan on the Image Map Widget.
3. The maxTemperatureThreshold and temperatureAlarmEnabled may be used to configure and enable/disable alarms for a certain device or asset.

Administration UI

• Go to Devices. Click on the particular device row to open device details. Select “Attributes” tab. Choose “Server attributes” scope. Click “+” Icon.
• Input new attribute name. Select attribute value type and input attribute value.
• Sort using “Last update time” to quickly locate the newly created attribute.

 

Shared attributes

This type of attributes is available only for Devices. It is similar to the Server-side attributes but has one important difference. The device firmware/application may request the value of the shared attribute(s) or subscribe to the updates of the attribute(s). The devices which communicate over MQTT or other bi-directional communication protocols may subscribe to attribute updates and receive notifications in real-time. The devices which communicate over HTTP or other request-response communication protocols may periodically request the value of the shared attribute.

 

 

The most common use case of shared attributes is to store device settings. Let’s assume the same building monitoring solution and review few examples:

1. The targetFirmwareVersion attribute may be used to store the firmware version for particular Device.
2. The maxTemperature attribute may be used to automatically enable HVAC if it is too hot in the room.

The user may change the attribute via UI. The script or other server-side application may change the attribute value via REST API.

Administration UI

Client-side attributes

This type of attribute is available only for Devices. It is used to report various semi-static data from Device (Client) to IIoTNext Platform (Server). It is similar to shared attributes but has one important difference. The device firmware/application may send the value of the attributes from the device to the platform.

 

The most common use case of client attributes is to report device state. Let’s assume the same building monitoring solution and review few examples:

1. The currentFirmwareVersion attribute may be used to report the installed firmware/application version for the device to the platform.
2. The currentConfiguration attribute may be used to report current firmware/application configuration to the platform.
3. The currentState may be used to persist and restore the current firmware/application state via the network if the device does not have persistent storage.

The user and server-side applications may browser the client-side attributes via UI/REST API but they are not able to change them. Basically, the value of the client-side attribute is read-only for the UI/REST API.

Attributes persistence

IIoTNext Platform stores the latest value of the attribute and last modification time in the SQL database. This enables use of entity filters in the dashboards. Changes to the attributes initiated by the user are recorded in the audit logs.

Data visualization

We assume you have already provisioned device attributes. Now you may use them in your dashboards. We recommend dashboards overview to get started. Once you are familiar with how to create dashboards and configure data sources, you may use digital and analog gauges to visualize temperature, speed, pressure, or other numeric values. You may also use cards to visualize multiple attributes using a card or entities table.

You may also use input widgets to allow dashboard users to change the values of the attributes on the dashboards.

Rule engine

The Rule Engine is responsible for processing all sorts of incoming data and events. You may find the most popular scenarios of using attributes within the rule engine below:

Generate alarms based on the logical expressions against attribute values

Use alarm rules to configure most common alarm conditions via UI or use filter nodes to configure more specific use cases via custom JS functions.

Modify incoming client-side attributes before they are stored in the database

Use message type switch rule node to filter messages that contain “Post attributes” requests. Then, use transformation rule nodes to modify a particular message.

React on the change of server-side attribute

Use message type switch rule node to filter messages that contain “Attributes Updated” notification. Then, use action or external to react on the incoming event.

Fetch attribute values to analyze incoming telemetry from the device

Use enrichment rule nodes to enrich incoming telemetry messages with attributes of the device, related asset, customer, or tenant. This is an extremely powerful technique that allows modifying processing logic and parameters based on settings stored in the attributes.