Lesson 4. Alarm management

• Adding alarm rules
  • Rules for devices that use the air-sensor device profile
    • High temperature alarm rule
    • Low temperature alarm rule
    • High humidity alarm rule
    • Low humidity alarm rule
    • High CO2 alarm rule
• Customizing rule chain
• Adding alarms table widget
• Alarm trigger testing
• Adding alarm widget to all other states
  • Adding alarm widget to office state
  • Adding alarm widget to building state
  • Adding alarm widget to buildings (default) state
• Final view of the dashboard for this lesson
• Next step

We continue to develop our dashboard. In the previous lesson, we added and configured separate states for each device and configured them to display telemetry data. We recommend reviewing it if you haven’t done so yet.

Lesson 3: Adding and configuring individual states for each device

In this lesson, we will talk about alarms.

An alarm is a notification generated when a predefined condition or rule is met. Alarms are associated with entities such as devices, assets, customers, and others.

Alarms in ThingsBoard are a powerful mechanism to monitor and react to critical events and conditions occurring in your IoT ecosystem. An alarm represents a significant state or condition that requires attention, such as a device malfunction, a breach of predefined thresholds, or unexpected behavior in your system. Understanding and effectively utilizing alarms is key to maintaining the health, performance, and security of your IoT infrastructure.

Core Concepts of Alarms in ThingsBoard:

• Severity Levels: Alarms are categorized by severity levels, which include Critical, Major, Minor, Warning, and Indeterminate. This categorization helps prioritize responses.

• Lifecycle States: Each alarm has a lifecycle consisting of states such as Active, Cleared, and Acknowledged. The state transitions allow effective tracking and resolution.

• Rule-Based Triggers: Alarms are triggered by rules defined in device profiles or rule chains. These rules evaluate incoming telemetry data, attribute changes, or other events.

• Visualization and Management: ThingsBoard provides a centralized interface to view, filter, and manage alarms. This includes tools for real-time monitoring and historical analysis.

By implementing alarms, you can automate responses to predefined conditions, improve operational efficiency, and ensure system reliability.

As you may recall, the Indoor Air Quality Sensor transmits telemetry values such as temperature, humidity, and CO2 levels to ThingsBoard. In this lesson, we will configure alarm rules for the Indoor Air Quality Sensor and add a widget to manage the device's alarms. Let's start.

Adding alarm rules

First, you need to define the rules that will trigger the alarm. The simplest way to create the alarm rule is to configure it within the device profile. These rules specify the conditions under which reminders should be generated.

Rules for devices that use the air-sensor device profile

Devices using the air-sensor device profile transmit telemetry data such as temperature, humidity, and CO2 levels. Let's configure alarm rules for each of these telemetry keys:

High temperature alarm rule

We will configure the High temperature alarm rule with two severity levels and a separate clearing condition:

• A Major alarm is created if the temperature exceeds 24 °C but does not go above 26 °C (inclusive).
• A Critical alarm is created if the temperature exceeds 26 °C.
• When the temperature drops below 24 °C, the alarm is cleared.

1. Create new alarm rule

• Go to the Device profile page in the Profiles section.
• Click air-sensor to open its details.
• Navigate to the Alarm rules tab.
• Click the “+” button and select Create new alarm rule.

2. Configure the General parameters

In the General section, specify the alarm type — High temperature (or any other name you prefer) — which serves as both the name and the unique identifier of the alarm.

3. Add an argument

Before defining the alarm trigger condition, you must add an argument — the data source that the rule will use.

In the Arguments section:

• Click Add argument and fill in:
  • Entity type: Current entity
  • Argument type: Latest telemetry
  • Time series key: temperature
  • Argument name: temperature
• Click Add.

This creates the variable temperature, which will be used in all condition expressions.

4. Configure the condition for creating the Critical alarm

In the Create condition section, click Add create condition.

• Severity: Critical
• Condition
  • Click Add condition.
  • In the configuration window, click Add argument filter and specify:
    • General block:
      • Argument: temperature (the argument added earlier)
      • Value type: Numeric
    • Filters block:
      • Click Add filter:
        • Operation: greater than
        • Value source: Static
        • Value: 26
    • Click Add.

  Condition settings

  • Condition type: Simple
  • Click Save.

An alarm with the severity “Critical” will be created when the temperature exceeds 26 °C.

5. Configure the condition for creating the Major alarm

Click Add create condition.

• Severity: Major
• Condition
  • Click Add condition.
  • In the configuration window, click Add argument filter and specify:
    • General block:
      • Argument: temperature
      • Value type: Numeric
    • Filters block:
      • Click Add filter:
        • Operation: greater than
        • Value source: Static
        • Value: 24
      • Add another condition. Click Add
        • Operation: less or equal
        • Value source: Static
        • Value: 26
    • Click Add.

  Condition settings

  • Condition type: Simple
  • Click Save.

A Major alarm will be created when the temperature is between 24 °C and 26 °C inclusive.

6. Add the condition to clear the alarm

Click Add clearing condition.

• Severity: Major
• Condition
  • Click Add clearing condition.
  • In the configuration window, click Add argument filter and specify:
    • General block:
      • Argument: temperature
      • Value type: Numeric
    • Filters block:
      • Click Add:
        • Operation: less or equal
        • Value source: Static
        • Value: 24
    • Click Add.

  Condition settings

  • Condition type: Simple
  • Click Save.

The alarm will be cleared automatically once the temperature drops below 24 °C.

7. Propagate alarm to related entities

In the Advanced settings section, enable the Propagate alarm to related entities option to automatically forward the alarm to the asset linked to the device.
Specify the relation type used between the device and the asset — Contains.

This allows device alarms to be displayed at higher levels of the hierarchy, for example: Device → Office → Building.

Result

The alarm rule will be created and activated.

Now, using this example, you can configure additional alarm rules on your own for:

• low temperature
• high humidity
• low humidity
• high CO₂ levels

Go ahead!

Low temperature alarm rule

Set the following rules for creating and clearing a low air temperature alarm:

Alarm creation:

• If the temperature drops below 20 °C but not below 18 °C (inclusive), an alarm of the severity type “Major” will be created;
• If the temperature drops below 18 °C, an alarm of the severity type “Critical” will be created.

Alarm clearing:

• When the temperature rises above 20 °C, the alarm will be cleared.

Rules for creating and clearing high and low humidity alarms

For the telemetry key “humidity”, we will define two conditions for triggering a high humidity alarm and one condition for clearing the alarm:

High humidity alarm rule

Alarm creation:

• An alarm with severity type “Major” will be created if humidity rises above 60 % but does not exceed 65 % (inclusive).
• An alarm with severity type “Critical” will be created if humidity exceeds 65 %.

Alarm clearing:

• The alarm will clear when humidity drops below 60 %.

Low humidity alarm rule

Alarm creation:

• An alarm with severity type “Major” will be created if humidity drops below 40 % but does not fall below 35 % (inclusive).
• An alarm with severity type “Critical” will be created if humidity drops below 35 %.

Alarm clearing:

• The alarm will clear when humidity rises above 40 %.

High CO2 alarm rule

Finally, for the telemetry key “co2”, we will define the following conditions for creating and clearing alarms:

Alarm creation:

• If the CO2 level is equal to or exceeds 490 ppm but does not exceed 500 ppm, the alarm with severity type “Major” will be created.
• If the CO2 level exceeds 500 ppm, the alarm with severity type “Critical” will be triggered.

Alarm clearing:

• The alarm will be cleared when the CO2 level drops below 490 ppm.

Now that we have defined all the alarm rules for the air-sensor device profile, the next step is to add a widget to manage the alarms.

Import device profile

If, for any reason, you were unable to configure the rules mentioned above, you can download the air-sensor device profile with pre-configured alarm rules and import it into your ThingsBoard instance.

Important! If you choose to import the device profile, you will need to assign the new device profile air-sensor(imported) to all devices currently using the air-sensor device profile, specifically the Indoor Air Quality Sensor and IAQ Sensor.

Customizing rule chain

As you may recall, we created a separate rule chain where telemetry for our devices is generated by generator nodes and directly stored in the database. However, for the reminder rules configured in the device profiles to work, messages from the generator nodes must pass through the device profile node before being stored in the database. The device profile rule node processes all incoming messages and reacts to the telemetry values.
Therefore, we need to add the device profile node in the Device Telemetry Emulators rule chain before the “save timeseries” node.

• Go to the “Rule chains” page, and open the “Device Telemetry Emulators” rule chain;
• Remove all links from the “generator” nodes to the “save telemetry” node;
• Find the “device profile” node in the node library, and drag it into the rule chain canvas;
• Node configuration window will be opened. Name it “Device profile node”, and click “Add”;
• Link the “generator” nodes to the “device profile” node. Select the “Success” link for these connections;
• Connect the “device profile” node to the “save timeseries” node. Again, select the “Success” link;
• Afterwards, save rule chain.

Adding alarms table widget

Displaying alarms in a user-friendly format is essential for monitoring and managing them effectively. The “Alarms table” widget in ThingsBoard provides a customizable interface for easy monitoring and interaction with alarms.

Steps to add the “Alarm table” widget:

• Click on the "Indoor Air Quality Sensor" device row in the "Office sensors list" widget to transition to its state;
• Enter dashboard editing mode;
• Click the "+ Add widget" button at the top of the screen;
• Find the "Alarm widgets" widgets bundle and click on it;
• Choose the "Alarms table" widget;
• Specify "Selected entity" alias as the data source. Check "Active" in the alarm status list of the filter section to show only active alarms;
• Remove "assignee" column;
• Change widget title to "Air sensor alarms". In the "Table buttons" section, leave only the "Allow alarms acknowledgment" and "Allow alarms clear" options turned on;
• Uncheck "Data export" option in the "Card appearance" section. Then, click "Add" to confirm adding widget;
• We have added a widget that will display the active alarms for your device. Place the "Air sensor alarms" widget on the free space of the dashboard and adjust its size by dragging the lower right corner. Then, save the dashboard.

A fully configured air_sensor state should look like this:

Now that the alarm rules have been defined and the widget for displaying active alarms has been added, let's test its functionality by sending telemetry values that exceed the threshold specified in the alarm rule.

Alarm trigger testing

To test the alarm triggering, it is not necessary to wait for the generator node to produce telemetry values exceeding the threshold. We can manually send telemetry with a value that exceeds the threshold specified in the alarm rule. As you may recall, if the temperature value exceeds 24°C, an alarm with a severity type of “Major” is triggered.

• Go to the "Devices" page. Choose the "Indoor Air Quality Sensor" device and click the "Check connectivity” button in the "Device details" window;
• In the opened window choose the desired messaging protocol and select your operating system. Install the required client tools, if necessary. Next, copy the provided command, which includes telemetry data;
• Open the Terminal and paste the copied command. This command will send a POST request to the ThingsBoard server with the {"temperature":25} data. Execute this command. After successful execution, the "temperature" reading will be published. Then, close the connectivity window.

Return to the air_sensor dashboard state. In the “Alarms table” widget, an alarm should appear displaying the created time, originator of the alarm, its severity and its status. When an alarm is triggered, it initially has the status “Active” and “Unacknowledged”. A user can acknowledge the alarm, changing its status to “Acknowledged”. However, it will remain active until it is resolved (cleared).

You will also receive a notification about the triggered alarm in the Notification center. Learn more about notifications and how to configure them here.

Acknowledge alarm

To acknowledge an alarm, click the “Acknowledge” icon next to the alarm event and confirm the action.

Clear alarm

To clear an alarm, click the “Clear” icon next to the alarm event and confirm the action.

Adding alarm widget to all other states

Next, we will add the alarm widget to each state of the dashboard to monitor alarms that appear on your device at any level of the dashboard.

Adding alarm widget to office state

Add an alarm widget to the office state. This widget will display alarms from all devices associated with the selected office. We'll add this widget using the copy method.

• Go to the air_sensor state, and enter dashboard edit mode;
• Right-click on the alarm widget, and select "Copy" from the dropdown menu;
• Navigate to the office state, right-click on an empty area of the dashboard, and select "Paste";
• Place the widget in an empty spot on the dashboard and adjust its size. Then, save the dashboard;

After saving the changes, you will automatically be redirected to the air_sensor state. Switch to the Office A state to check the result.

As you may notice, active alarms are not displayed in the widget. This happens because the “Office A” entity is currently selected, while the alarm was created on a device that has a relationship with this office. Previously, in the alarm rule, we specified that the alarm should propagate to related entities.

Now we need to configure the widget to search for and display alarms for both the selected entity and its child entities, provided that relationships exist between them:

• Enter the dashboard edit mode and click the "pencil" icon on the alarm widget to edit it;
• Change the alarms source to "Office sensors" entity alias. Turn on the "Search propagated alarms" option. This option enables displaying alarms for both the selected entity and its child entities, provided that relationships exist between them;
• Change the widget title to "Office alarms". Then, apply the changes;
• Save the dashboard.

Now, as you can see, the widget displays the alarms of the devices that have a relation to the selected office.

Adding alarm widget to building state

Similar to the previous steps, we will add an alarm widget to the building state. This widget will display alarms from all devices associated with the selected building. We will also add this widget using the copy method.

• Being in the office state, enter dashboard edit mode. Right-click on the alarm widget, and select "Copy" from the dropdown menu;
• Navigate to the Buildings (default) state, right-click on an empty area of the dashboard, and select "Paste";
• Place the widget in an empty spot on the dashboard and adjust its size. Click the "pencil" icon on the alarm widget to edit it;
• Change the alarms source to "Building offices" entity alias;
• Change the widget title to "Building alarms". Then, apply the changes;
• Save the dashboard.

The alarm widget displays the alarms of the devices related to the selected building.

Adding alarm widget to buildings (default) state

Now it remains to add the alarm widget to the Building (default) state. Also by copying method:

• Being in the office state, enter dashboard edit mode. Right-click on the alarm widget, and select "Copy" from the dropdown menu;
• Navigate to the Buildings (default) state, right-click on an empty area of the dashboard, and select "Paste";
• Place the widget in an empty area on the dashboard and adjust its size. Then, click the "pencil" icon on the alarm widget to edit it;
• Change the alarm source to "Buildings" entity alias;
• Rename the widget to "All alarms", and apply changes;
• Finally, save the dashboard.

Now, if there are alarms on your devices, they will be displayed in the alarms widget in the Building (default) state.

Final view of the dashboard for this lesson

Finally, your dashboard should look like this:

The configuration of alarm creation rules for the Energy Meter and Water Flow Meter devices is slightly more complex. This is because the alarm should not be triggered by a single value but by the sum of telemetry values over an hour. To achieve this, we will use the rule engine for additional calculations. The configuration of alarm creation rules for these devices will be covered in the following lessons.

Next step

In the next lesson, we will share this dashboard with customers. When you are ready to proceed, simply click the button below.

Lesson 5: Share dashboard with customer