ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.

Device Profiles


Since ThingsBoard 3.2, the 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.

Experienced ThingsBoard users can notice that the device type has been deprecated in favor of the Device Profile. The update script will automatically create Device Profiles based on unique Device Types and assign them to the appropriate devices.

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, since ThingsBoard 3.2, 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. Please note that if you choose to use a custom queue name, you should configure it in the thingsboard.yml file before you using it.

Transport configuration

Since ThingsBoard 3.2, 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, and CoAP 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 '' -i 'c1' -u 't1' -P 'secret' -t '/telemetry' -m '{"humidity": 10.3}'

and attribute updates with the following command:

mosquitto_pub -h '' -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 (ThingsBoard 3.2), platform supports customizable proto schemas for telemetry upload and [attribute upload]/docs/reference/MQTT-API/#publish-attribute-update-to-the-server). We plan to the add ability to define a schema for downlink messages (RPC calls and attribute updates) in future releases.

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

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 ThingsBoard 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:

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

mosquitto_pub -d -h '' -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.

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.

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’.

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.

Example 5. Define alarm rule schedule

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

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”.

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 ThingsBoard 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 ThingsBoard either during or after manufacturing. See separate documentation page for more details.