Skip to content

device-inactivity-alarm.mdx

Latest commit

 

History

History
394 lines (322 loc) · 18 KB

device-inactivity-alarm.mdx

File metadata and controls

394 lines (322 loc) · 18 KB
Raw

import DocLink from '@components/DocLink.astro'; import { Aside } from '@astrojs/starlight/components'; import MultiProductImageGallery from '/components/MultiProductImageGallery.astro'; import { Products } from '/models/site.models';

Monitor device connectivity and automatically create or clear an alarm when a device stops sending data.

Use case

Thermometer A1 (thermostat profile) sends temperature telemetry to ThingsBoard. When it stops reporting data, ThingsBoard marks it inactive and raises a Device inactive alarm. When the device reconnects, the alarm clears automatically.

Two approaches are covered:

  • Option 1: Alarm Rule — no-code, scoped to a device profile. Best for standard inactivity monitoring.
  • Option 2: Rule Engine — rule chain configuration, supports custom logic such as notifications or external forwarding.

Prerequisites

Create a device:

  • Name: Thermometer A1
  • Device profile: thermostat

{props.product === Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/prerequisite-1-ce.png', alt: 'Devices list showing Thermometer A1 with Inactive state badge', caption: 'Navigate to Entities ⇾ Devices and create Thermometer A1 with device profile thermostat. The Inactive badge appears once ThingsBoard detects no data within the inactivity window.' }, ]} /> )}

{props.product !== Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/prerequisite-1.png', alt: 'Devices list showing Thermometer A1 with Inactive state badge', caption: 'Navigate to Entities ⇾ Devices and create Thermometer A1 with device profile thermostat. The Inactive badge appears once ThingsBoard detects no data within the inactivity window.' }, ]} /> )}

ThingsBoard's Device State service automatically maintains two server attributes on every device:

  • active — true when the device is active, false when inactive
  • inactivityAlarmTime — timestamp of the last inactivity event

Option 1. Alarm Rule

You can import a ready-made alarm rule or build it manually.

Option 1. Import alarm rule

  • Download the Device Active/Inactive alarm rule as JSON file and import it into your instance.

When importing, set the thermostat as the target device profile.

During import, set the thermostat as the target entity.

Option 2. Create manually

Go to Alarms ⇾ Alarm rules and click + Add alarm rule ⇾ Create new alarm rule.

Step 1. Configure general settings

In the Alarm rule dialog, set:

  • Alarm type: Device inactive
  • Entity type: Device profile
  • Device profile: thermostat (here specify the device type of your device)

{props.product === Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-1-ce.png', alt: 'Alarm rule dialog with Device inactive alarm type and thermostat device profile', caption: 'Set Alarm type to Device inactive and apply the rule to the thermostat device profile. The 15 min badge in the top right enables debug mode — all debug messages will be logged for 15 minutes.' }, ]} /> )}

{props.product !== Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-1.png', alt: 'Alarm rule dialog with Device inactive alarm type and thermostat device profile', caption: 'Set Alarm type to Device inactive and apply the rule to the thermostat device profile. The 15 min badge in the top right enables debug mode — all debug messages will be logged for 15 minutes.' }, ]} /> )}

Step 2. Add argument

Click Add argument and configure it to read the active server attribute:

  • Entity type: Current entity
  • Argument type: Attribute
  • Attribute scope: Server attributes
  • Attribute key: active
  • Argument name: active

{props.product === Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-2-ce.png', alt: 'Argument settings dialog with active server attribute configured', caption: 'Add an argument that reads the active server attribute from the current entity and names it active for use in conditions.' }, ]} /> )}

{props.product !== Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-2.png', alt: 'Argument settings dialog with active server attribute configured', caption: 'Add an argument that reads the active server attribute from the current entity and names it active for use in conditions.' }, ]} /> )}

Step 3. Add trigger condition

In the Trigger conditions section, set Severity to Critical, then click Add condition and configure:

  • Mode: Script
  • Script: 
    return active == false;

{props.product === Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-3-ce.png', alt: 'Trigger conditions section with Critical severity and Add condition button', caption: 'Set Severity to Critical and click Add condition to open the alarm condition editor.' }, { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-4-ce.png', alt: 'Alarm condition dialog in Script mode with return active == false', caption: 'Select Script mode and enter return active == false;. The alarm is created when the device becomes inactive.' }, ]} /> )}

{props.product !== Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-3.png', alt: 'Trigger conditions section with Critical severity and Add condition button', caption: 'Set Severity to Critical and click Add condition to open the alarm condition editor.' }, { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-4.png', alt: 'Alarm condition dialog in Script mode with return active == false', caption: 'Select Script mode and enter return active == false;. The alarm is created when the device becomes inactive.' }, ]} /> )}

Step 4. Add clear condition

Scroll down to Clear condition, click Add condition, and configure:

  • Mode: Script
  • Script: 
    return active == true;

{props.product === Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-5-ce.png', alt: 'Clear condition section with Add condition button', caption: 'Scroll to the Clear condition section and click Add condition.' }, { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-6-ce.png', alt: 'Alarm condition dialog in Script mode with return active == true', caption: 'Select Script mode and enter return active == true;. The alarm clears when the device becomes active again.' }, { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-7-ce.png', alt: 'Completed alarm rule with clear condition showing function expression', caption: 'The clear condition is now set. Click Add to save the alarm rule.' }, ]} /> )}

{props.product !== Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-5.png', alt: 'Clear condition section with Add condition button', caption: 'Scroll to the Clear condition section and click Add condition.' }, { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-6.png', alt: 'Alarm condition dialog in Script mode with return active == true', caption: 'Select Script mode and enter return active == true;. The alarm clears when the device becomes active again.' }, { src: '/src/assets/images/recipes/device-inactivity-alarm/alarm-rule-7.png', alt: 'Completed alarm rule with clear condition showing function expression', caption: 'The clear condition is now set. Click Add to save the alarm rule.' }, ]} /> )}

Click Add to save the alarm rule.

Step 5. Verify

Open Thermometer A1 ⇾ Attributes ⇾ Server attributes. ThingsBoard writes active and inactivityAlarmTime automatically.

To simulate inactivity, edit the active attribute and set it to false:

{props.product === Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/verify-1-ce.png', alt: 'Thermometer A1 server attributes showing active attribute', caption: 'ThingsBoard writes the active server attribute automatically. It is updated by the Device State service whenever the device connectivity state changes.' }, { src: '/src/assets/images/recipes/device-inactivity-alarm/verify-2-ce.png', alt: 'Editing active attribute with Boolean toggle set to False', caption: 'Edit the active attribute and set it to False to simulate a device going offline.' }, ]} /> )}

{props.product !== Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/verify-1.png', alt: 'Thermometer A1 server attributes showing active and inactivityAlarmTime', caption: 'ThingsBoard writes active and inactivityAlarmTime as server attributes. These are updated automatically by the Device State service.' }, { src: '/src/assets/images/recipes/device-inactivity-alarm/verify-2.png', alt: 'Editing active attribute with Boolean toggle set to False', caption: 'Edit the active attribute and set it to False to simulate a device going offline.' }, ]} /> )}

Open Thermometer A1 ⇾ Alarms. A Device inactive Critical alarm appears:

{props.product === Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/verify-3-ce.png', alt: 'Thermometer A1 Alarms tab showing Device inactive Critical alarm', caption: 'A Device inactive Critical alarm is created on Thermometer A1.' }, ]} /> )}

{props.product !== Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/verify-3.png', alt: 'Thermometer A1 Alarms tab showing Device inactive Critical alarm', caption: 'A Device inactive Critical alarm is created on Thermometer A1.' }, ]} /> )}

Set active back to true to clear the alarm:

{props.product === Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/verify-4-ce.png', alt: 'Editing active attribute with Boolean toggle set to True', caption: 'Set the active attribute back to True to simulate the device reconnecting.' }, { src: '/src/assets/images/recipes/device-inactivity-alarm/verify-5-ce.png', alt: 'Thermometer A1 Alarms tab empty after alarm is cleared', caption: 'The alarm is cleared. The Alarms tab shows no active alarms for Thermometer A1.' }, ]} /> )}

{props.product !== Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/verify-4.png', alt: 'Editing active attribute with Boolean toggle set to True', caption: 'Set the active attribute back to True to simulate the device reconnecting.' }, { src: '/src/assets/images/recipes/device-inactivity-alarm/verify-5.png', alt: 'Thermometer A1 Alarms tab empty after alarm is cleared', caption: 'The alarm is cleared. The Alarms tab shows no active alarms for Thermometer A1.' }, ]} /> )}

Option 2. Rule Engine

Use this approach when you need custom processing alongside the alarm — for example, sending a notification email, forwarding data to an external system, or chaining conditional logic.

The Rule Engine processes device connectivity events as special message types:

  • INACTIVITY_EVENT — fired when the device exceeds the inactivity timeout
  • ACTIVITY_EVENT — fired when the device resumes activity

Step 1. Set inactivity timeout (optional)

The global default timeout is 600 seconds (DEFAULT_INACTIVITY_TIMEOUT). To shorten the timeout for the devices in this recipe, set it at the device profile level, the device level, or both.

Option A: Device profile (recommended)

Open the thermostat profile and set Device inactivity timeout (under the Details tab) to 60 seconds. The new value applies to every device assigned to the profile.

Option B: Per-device override

Add an inactivityTimeout server-side attribute on Thermometer A1 to override the profile value for this device only:

  • Key: inactivityTimeout
  • Type: Integer
  • Value: 60000 (60 seconds, milliseconds)

The per-device attribute always wins over the profile value. See device connectivity status for the full resolution order.

{props.product === Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/set-inactivity-timeout-1-ce.png', alt: 'Thermometer A1 server attributes configuration', caption: 'Open Thermometer A1, go to the Attributes tab, and configure server attribute inactivityAlarmTime used for inactivity alarm detection.' }, ]} /> )}

{props.product !== Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/set-inactivity-timeout-1.png', alt: 'Thermometer A1 server attributes configuration', caption: 'Open Thermometer A1, go to the Attributes tab, and configure server attribute inactivityAlarmTime used for inactivity alarm detection.' }, ]} /> )}

Step 2. Configure the rule chain

Open your Root Rule Chain and create two nodes:

Create Alarm node:

  • Name: Create Inactivity Alarm
  • Alarm type: Inactivity Timeout

Clear Alarm node:

  • Name: Clear Inactivity Alarm
  • Alarm type: Inactivity Timeout

Connect these two nodes to the existing Message Type Switch node:

  • Message Type Switch ⇾ Inactivity Event ⇾ Create Inactivity Alarm
  • Message Type Switch ⇾ Activity Event ⇾ Clear Inactivity Alarm
The Message Type Switch node is present in the default root rule chain. Add the alarm nodes and connect them to the existing node's Inactivity Event and Activity Event output links.

{props.product === Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/configure-rule-chain-1-ce.png', alt: 'Root Rule Chain with inactivity alarm flow', caption: 'The Message Type Switch node is present in the default root rule chain. Add the alarm nodes and connect them to the existing node's Inactivity Event and Activity Event output links.' }, ]} /> )}

{props.product !== Products.CE && ( <MultiProductImageGallery product={props.product} images={[ { src: '/src/assets/images/recipes/device-inactivity-alarm/configure-rule-chain-1.png', alt: 'Root Rule Chain with inactivity alarm flow', caption: 'The Message Type Switch node is present in the default root rule chain. Add the alarm nodes and connect them to the existing node's Inactivity Event and Activity Event output links.' }, ]} /> )}

See also

  • Device connectivity status — how ThingsBoard tracks device state
  • Alarm rules — full alarm rule reference
  • Create & clear alarms — threshold-based alarm recipe