Device Profiles

Overview
Device Profile settings

Overview

A Tenant administrator is able to configure common settings for multiple devices using Device Profiles. Each Device has one and only profile at a single point in time.

Let’s take a look at the settings available in the device profile one by one.

Device Profile settings

Rule Chain

By default, the Root Rule Chain processes all incoming messages and events for any device. However, the more different device types you have, the more complex your Root Rule Chain may become. Many platform users create their Root Rule Chain for the sole purpose of sending messages to specific rule chains depending on the device type.

To avoid this painful and mundane activity, you can specify a custom root Rule Chain for your devices. The new Rule Chain will receive all telemetry, device activity(Active/Inactive), and device lifecycle(Created/Updated/Deleted) events. This setting is available in the Device Profile wizard and in the Device Profile details.

Queue Name

By default, the Main queue will be used to store all incoming messages and events from any device. The transport layer will submit messages to this queue and Rule Engine will poll the queue for new messages. However, for multiple use cases, you might want to use different queues for different devices. For example, you might want to isolate data processing for Fire Alarm/Smoke Detector sensors and other devices. This way, even if your system has a peak load produced by millions of water meters, whenever the Fire Alarm is reported, it will be processed without delay. Separation of the queues also allows you to customize different submit and processing strategies.

This setting is available in the Device Profile wizard and Device Profile details.

Transport configuration

The platform supports two transport types: Default and MQTT.

Default transport type

The Default transport type is intended for backward compatibility with previous releases. With the Default transport type, you can continue to use the platform’s default MQTT, HTTP, CoAP and LwM2M APIs to connect your devices. There is no specific configuration setting for the default transport type.

MQTT transport type

The MQTT transport type enables advanced MQTT transport settings. Now you are able to specify custom MQTT topics filters for time-series data and attribute updates that correspond to the telemetry upload API and attribute update API, respectively.

The MQTT transport type has the following settings:

MQTT device topic filters

Custom MQTT topic filters support single ‘+’ and multi-level ‘#’ wildcards and allow you to connect to almost any MQTT based device that sends a payload using JSON or Protobuf. For example, using the configuration from the image below will allow you to publish time-series data with the following command:

mosquitto_pub -h 'iothub.magenta.at' -i 'c1' -u 't1' -P 'secret' -t '/telemetry' -m '{"humidity": 10.3}'

and attribute updates with the following command:

mosquitto_pub -h 'iothub.magenta.at' -i 'c1' -u 't1' -P 'secret' -t '/attributes' -m '{"firmwareVersion": "1.3"}'

assuming you have provisioned basic MQTT credentials for your device with the client id ‘c1’, username ‘t1’ and password ‘secret’.

MQTT device payload

By default, the platform expects devices to send data via JSON. However, it is also possible to send data via Protocol Buffers

Protocol Buffers, or Protobuf, is a language- and a platform-neutral way of serializing structured data. It is convenient to minimize the size of transmitted data.

At the moment of writing (IoT Hub 3.2), platform supports customizable proto schemas for telemetry upload and attribute upload. We plan to the add ability to define a schema for downlink messages (RPC calls and attribute updates) in future releases.

IoT Hub parses the protobuf structures dynamically, that is why, it does not support some protobuf features like OneOf, extensions and maps, yet.

CoAP transport type

The CoAP transport type enables advanced CoAP transport settings. With the CoAP transport type, you have the ability to select the CoAP device type.

CoAP device type: Default

By default CoAP device type Default have CoAP device payload set to JSON that supports basic CoAP API same as for Default transport type. However, it is also possible to send data via Protocol Buffers by changing the parameter CoAP device payload to Protobuf.

Protocol Buffers, or Protobuf, is a language- and a platform-neutral way of serializing structured data. It is convenient to minimize the size of transmitted data.

At the moment of writing (IoT Hub 3.3.2), platform supports customizable proto schemas for telemetry upload and attribute upload. We plan to the add ability to define a schema for downlink messages (RPC calls and attribute updates) in future releases.

IoT Hub parses the protobuf structures dynamically, that is why, it does not support some protobuf features like OneOf, extensions and maps, yet.

CoAP device type: Efento NB-IoT

At the moment of writing (IoT Hub 3.3.2), platform supports integration with next Efento NB-IoT sensors:

temperature,
humidity,
air pressure,
differential pressure,
open / close,
leakage,
I/O.

FW version: 06.02 or newer.

Alarm Rules

Platform users can use Rule Engine to configure alarms. Rule Engine is a quite powerful feature, but it requires some programming skills. Since IoT Hub 3.2, we have introduced Alarm Rules to simplify the process of configuring the most popular alarm types. Now you don’t need to be the Rule Engine guru to configure your processing logic. Under the hood, Rule Engine evaluates Alarm Rules using the “Device Profile” rule node.

Alarm Rule consists of the following properties:

Alarm Type - a type of Alarm. Alarm type must be unique within the device profile alarm rules;
Create Conditions - defines the criteria when the Alarm will be created/updated. The condition consists of the following properties:
- Severity - will be used to create/update an alarm. IoT Hub verifies Create Conditions in the descending order of the severity. For example, if a condition with Critical severity is true, the platform will raise alarm with Critical severity, and “Major”, “Minor” or “Warning” conditions will not be evaluated. Severity must be unique per alarm rule (e.g., two conditions created within the same alarm rule can’t have the same severity);
- Key Filters - list of logical expressions against attributes or telemetry values. For example, “(temperature < 0 OR temperature > 20) AND softwareVersion = ‘2.5.5’“;
- Condition Type - either simple, duration, or repeating. For example, 3 times in a row or during 5 minutes. The simple condition will raise an alarm once the first matching event occurrs;
- Schedule - defines the time interval during which the rule is active. Either “active all the time”, “active at specific time” or “custom”;
- Details - the alarm details template supports substitution of the telemetry and/or attribute values using ${attributeName} syntax;
Clear condition - defines criteria when the Alarm will be cleared;
Advanced settings - defines alarm propagation to related assets, customers, tenant, or other entities.

Let’s learn how to use the Alarm Rules with an example. Let’s assume we would like to keep track of the temperature inside of the fridge with valuable goods.
We also assume that we have already created a device profile called “Temperature Sensors”, and provisioned our device with the temperature sensor and with access token - “ACCESS_TOKEN”. The command listed below upload the temperature readings to iothub.magenta.at.

mosquitto_pub -d -h 'iothub.magenta.at' -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -m '{"temperature": 5.3}'

Example 1. Simple alarm conditions

We would like to create a Critical alarm when the temperature is greater than 10 degrees.

Step 1. Open the device profile and toggle edit mode.
Step 2. Click the "Add alarm rule" button.
Step 3. Input Alarm Type and click on the red "+" sign.
Step 4. Click the "Add Key Filter" button.
Step 5. Select the "Timeseries" key type. Input the "temperature" key name. Change "Value type" to "Numeric". Click the "Add" button.
Step 6. Select the "greater than" operation and input the threshold value. Click "Add".
Step 7. Click the "Save" button.
Step 8. Finally, apply changes.

Example 2. Alarm condition with a duration

Let’s assume that we would like to modify Example 1 and raise alarms only if the temperature exceeds a certain threshold for 1 minute.

For this purpose, we need to edit the alarm condition and modify the condition type from “Simple” to “Duration”. We should also specify the duration value and unit.

Step 1. Edit the alarm condition and change the condition type to "Duration". Specify duration value and unit. Save the condition.
Step 2. Apply changes.

Now let’s assume you would like to replace the 1 minute duration with a dynamic value that depends on the settings for a particular device, customer or tenant.

For this purpose, you should use the server-side attributes feature.

Please create a server-side attribute “highTemperatureDurationThreshold” with the integer value “2” for your device.

Step 3. Edit the alarm condition and change the condition type to "Duration". Specify default duration value and time unit. This value will be used by default, if no attribute is set for your device;
Step 4. Go to the dynamic value of the alarm delay by pressing the "Switch to dynamic value" button;
Step 5. Select a value: current device, current customer or current tenant. And specify the attribute from which the alarm threshold value will be taken. You may optionally check "Inherit from owner". Inheritance allows to take the threshold value from customer if it is not set on the device level. If the attribute value is not set on both device and customer levels, rule will take the value from the tenant attributes;
Step 6. Apply all changes.

Example 3. Repeating alarm condition

Let’s assume we would like to modify Example 1 and raise alarms only if the sensor reports a temperature that exceeds the threshold 3 times in a row.

For this purpose, we need to edit the alarm condition and modify the condition type from “Simple” to “Repeating”. We should also specify 3 as ‘Count of events’.

Step 1. Edit the alarm condition and change the condition type to "Repeating". Specify 3 as "Count of events". Save the condition.
Step 2. Apply changes.

Now let’s assume you would like to replace the set number of times the alarm condition is exceeded with a dynamic value that depends on the settings for a particular device, customer or tenant.

For this purpose, you should use the server-side attributes feature.

Please create a server-side attribute “highTemperatureRepeatingThreshold”, with the integer value “5” for your device.

Step 3. Edit the alarm condition and change the condition type to "Repeating". Specify default value "Count of events" to trigger the alarm; This value will be used by default, if no attribute is set for your device;
Step 4. Go to the dynamic value of the repeating alarm condition by pressing the "Switch to dynamic value" button;
Step 5. Select a value: current device, current customer or current tenant. And specify the attribute from which the value will be taken, how many times the threshold value must be exceeded for an alarm to be triggered. You may optionally check "Inherit from owner". Inheritance allows to take the threshold value from customer if it is not set on the device level. If the attribute value is not set on both device and customer levels, rule will take the value from the tenant attributes;
Step 6. Apply all changes.

Example 4. Clear alarm rule

Let’s assume we would like to automatically clear the alarm if the temperature in the fridge goes back to normal.

Step 1. Open the device profile and toggle edit mode. Click the "Add clear condition" button.
Step 2. Click on the red "+" sign.
Step 3. Add Key Filter.
Step 4. Finally, apply changes.

Example 5. Define alarm rule schedule

Let’s assume we would like an alarm rule to evaluate alarms only during working hours.

Step 1. Edit the schedule of the alarm rule.
Step 2. Select timezone, days, time interval, and click "Save".
Step 3. Finally, apply changes.

Example 6. Advanced thresholds

Let’s assume we would like our users to be able to overwrite the thresholds from Dashboard UI. We can also add the flag to enable or disable certain alarms for each device. For this, we will use dynamic values in the alarm rule condition. We will use two attributes: the boolean temperatureAlarmFlag, and the numeric temperatureAlarmThreshold. Our goal is to trigger an alarm creation when “temperatureAlarmFlag = True AND temperature is greater than temperatureAlarmThreshold”.

Step 1. Modify the temperature key filter and change the value type to dynamic.
Step 2. Select a dynamic source type and input the *temperatureAlarmThreshold*, then click "Update". You may optionally check "Inherit from owner". Inheritance allows to take the threshold value from customer if it is not set on the device level. If the attribute value is not set on both device and customer levels, rule will take the value from the tenant attributes.
Step 3. Add another key filter for the *temperatureAlarmFlag*, then click "Add".
Step 4. Finally, click "Save" and apply changes.
Step 5. Provision device attributes either manually or via the script.

Example 7. Dynamic thresholds based on the tenant or customer attributes

Example 6 demonstrates how to enable or disable rule based on the value of “temperatureAlarmFlag” attribute of the device. But what if you would like to enable or disable certain rule for all devices that belong to a tenant or customer? To avoid configuration of the attribute for each device, you may configure alarm rule to compare constant value with the value of Tenant or Customer Attribute. For this purpose, you should use “Constant” key type and compare it with dynamic value. See configuration example below:

Choose constant type and value and compare it with the value of the tenant or customer attribute.

The technique mentioned above may be used to enable or disable rules or combine filters on device telemetry/attributes with filters on tenant or customer attributes.

Device profile rule node

Device Profile rule node creates and clears alarms based on the alarm rules defined in the device profile. By default, this is the first rule node in the chain of processing. The rule node processes all incoming messages and reacts to the attributes and telemetry values. There are two important settings in the rule node:

Persist state of alarm rules - forces the rule node to store the state of processing. Disabled by default. This setting is useful if you have duration or repeating conditions. Let’s assume you have a condition “Temperature is greater than 50 for 1 hour”, and the first event with a temperature greater than 50 was reported at 1 pm. At 2 pm you should receive the alarm (assuming temperature conditions will not change). However, if you will restart the server after 1 pm and before 2 pm, the rule node needs to lookup the state from DB. Basically, if you enable this and the ‘Fetch state of alarm rules’ option, the rule node will be able to raise the alarm. If you leave it disabled, the rule node will not generate the alarm. We disable this setting by default for performance reasons. If enabled, and if the incoming message matches at least one of the alarm conditions, it will cause additional write operation to persist in the state.

Fetch state of alarm rules - forces rule node to restore the state of processing on initialization. Disabled by default. This setting is useful if you have duration or repeating conditions. It should work in tandem with the ‘Persist state of alarm rules’ option, but on rare occasions, you may want to disable this setting while the ‘Persist state of alarm rules’ option is enabled. Assuming you have many devices that send data frequently or constantly, you can avoid loading the state from the DB on initialization. The Rule Node will fetch the state from the database when the first message from a specific device arrives.

Notifications about alarms

Assuming you have configured alarm rules you may also want to receive a notification when IoT Hub creates or updates the alarm. The device profile rule node has three main outbound relation types that you can use: ‘Alarm Created’, ‘Alarm Severity Updated’, and ‘Alarm Cleared’. See the example rule chain below. Please make sure that the system administrator has configured the SMS/email providers before you proceed or configure your own settings in the rule nodes.

You may also use existing guides: Send email on alarm (Use part which explains ‘to email’ and ‘send email’ nodes) or Telegram notifications. There is also an additional ‘Alarm Updated’ relation type that should be ignored in most cases to avoid duplicate notifications.

Device provisioning

Device provisioning allows a device to automatically register in IoT Hub either during or after manufacturing. See separate documentation page for more details.

On this page