Manage alarms and RPC requests on edge devices

Use case
Prerequisites
Configure Alarm Rules
Provision devices
Configure edge rule engine to handle alarms and send RPC calls
Connect “Air Conditioner” to edge and subscribe for RPC commands
Post telemetry to “DHT22” sensor to create alarm
Verify that RPC request was send to “Air Conditioner” device
Next Steps

Use case

Let’s assume you have a warehouse with two devices connected to ThingsBoard Edge:

DHT22 temperature sensor
Air Conditioner

ThingsBoard Edge has the following responsibilities:

Collects temperature readings from the DHT22 sensor
Creates and updates alarms if the temperature in the warehouse is higher than 50 °C
In case if the temperature becomes critical, ThingsBoard Edge turns on the cooler system by sending RPC call requests to the Air Conditioner device
Pushes telemetry to the cloud

Please note that this is just a simple theoretical use case to demonstrate the capabilities of the platform. You can use this tutorial as a basis for much more complex scenarios.

Prerequisites

We assume you have completed the following guides and reviewed the articles listed below:

Getting Started guide.
Rule Engine Overview article.
ThingsBoard Edge Getting Started article.
Edge Rule Chain Templates guide.

Please make sure that you have ThingsBoard PE server up and running. Additionally, ThingsBoard Edge must be up, running and connected to the cloud.

If you have these prerequisites in place let’s go to next steps.

In other case please visit this link to provision, install and connect Edge to Server guide.

Configure Alarm Rules

We will use alarm rules feature to raise alarm when temperature reading is greater than 50 °C degrees. For this purpose, we should create new device profile and add new alarm rule. We recommend creating dedicated device profiles for each corresponding device type. Let’s create new device profile “edge thermostat”.

Login to your ThingsBoard PE instance and open Device profiles menu page.
Click on the ("+") to add new device profile.
1. Input device profile name. For e.g., type edge thermostat. 2. Click on the Transport configuration to proceed.
For this example we will use default transport configuration. Click on the Alarm rules to proceed.
Click on the Add alarm rule button.
1. Specify alarm type. For e.g., High temperature. 2. Click on the ("+") icon to add new alarm condition.
Click on the Add key filter button.
1. Select key type. 2. Input key name 3. Select value type. 4. Click on Add button.
1. Select operation, greater than. 2. Input threshold value, 50. Click on the Add button.
Click on the Save button.
Click on the Add" button.
Newly create device profile will be show first in the list, because default sort order is by created time.

Login to your <b>ThingsBoard PE</b> instance and open <b>Device profiles</b> menu page. — Login to your **ThingsBoard PE** instance and open **Device profiles** menu page.

Click on the ("+") to add new device profile.

1. Input device profile name. For e.g., type edge thermostat. 2. Click on the Transport configuration to proceed.

For this example we will use default transport configuration. Click on the <b>Alarm rules</b> to proceed. — For this example we will use default transport configuration. Click on the **Alarm rules** to proceed.

Click on the <b>Add alarm rule</b> button. — Click on the **Add alarm rule** button.

1. Specify alarm type. For e.g., <b>High temperature</b>. 2. Click on the <b>("+")</b> icon to add new alarm condition. — 1. Specify alarm type. For e.g., **High temperature**. 2. Click on the **("+")** icon to add new alarm condition.

Click on the <b>Add key filter</b> button. — Click on the **Add key filter** button.

1. Select key type. 2. Input key name 3. Select value type. 4. Click on <b>Add</b> button. — 1. Select key type. 2. Input key name 3. Select value type. 4. Click on **Add** button.

1. Select operation, <b>greater than</b>. 2. Input threshold value, <b>50</b>. Click on the <b>Add</b> button. — 1. Select operation, **greater than**. 2. Input threshold value, 50. Click on the **Add** button.

Click on the <b>Save</b> button. — Click on the **Save** button.

Click on the <b>Add" button</b>. — Click on the **Add" button**.

Newly create device profile will be show first in the list, because default sort order is by created time.

Please open ThingsBoard Edge UI using the URL: EDGE_URL to see provisioned device profiles.

Login to your ThingsBoard Edge instance and open Device profiles page.
Verify that edge thermostat was provisioned to edge as well.

Login to your ThingsBoard <b>Edge</b> instance and open Device profiles page. — Login to your ThingsBoard **Edge** instance and open Device profiles page.

Verify that <b>edge thermostat</b> was provisioned to edge as well. — Verify that **edge thermostat** was provisioned to edge as well.

Provision devices

For simplicity, we will provision device manually using the UI.

Let’s first create DHT22 temperature sensor and Air Conditioner devices on the edge and add relation between these devices. This relation will be used to find related Air Conditioner device once DHT22 temperature sensor will send critical temperature value.

We are going to provision device on the Edge. Please open ThingsBoard Edge UI using the URL: EDGE_URL.

Login to your ThingsBoard Edge instance and open Device groups page.
Open All device group.
Click on the ("+") icon in the top right corner of the table.
1. Input device name. For e.g., DHT22. 2. Select edge thermostat from device profiles list. No other changes required at this time. 3. Click Add to add the device.
Now your DHT22 device should be listed first, since table sort devices using created time by default. Click on the Add to add one more device.
Input device name. For e.g., Air Conditioner. No other changes required at this time. Click on the Add button to add the device.
Now your Air Conditioner device should be listed first, since table sort devices using created time by default.
Click on the DHT22 device row to open device details and navigate to Relations tab. Click on the ("+") icon to add new relation.
Specify relation type Manages and select Air Conditioner device from the list. Click on the Add to add this relation. Now we verify that devices were provisioned to cloud.

Login to your ThingsBoard <b>Edge</b> instance and open Device groups page. — Login to your ThingsBoard **Edge** instance and open Device groups page.

Open <b>All</b> device group. — Open **All** device group.

Click on the <b>("+")</b> icon in the top right corner of the table. — Click on the **("+")** icon in the top right corner of the table.

1. Input device name. For e.g., <b>DHT22</b>. 2. Select <b>edge thermostat</b> from device profiles list. No other changes required at this time. 3. Click <b>Add</b> to add the device. — 1. Input device name. For e.g., **DHT22**. 2. Select **edge thermostat** from device profiles list. No other changes required at this time. 3. Click **Add** to add the device.

Now your <b>DHT22</b> device should be listed first, since table sort devices using created time by default. Click on the <b>Add</b> to add one more device. — Now your **DHT22** device should be listed first, since table sort devices using created time by default. Click on the **Add** to add one more device.

Input device name. For e.g., <b>Air Conditioner</b>. No other changes required at this time. Click on the <b>Add</b> button to add the device. — Input device name. For e.g., **Air Conditioner**. No other changes required at this time. Click on the **Add** button to add the device.

Now your <b>Air Conditioner</b> device should be listed first, since table sort devices using created time by default. — Now your **Air Conditioner** device should be listed first, since table sort devices using created time by default.

Click on the <b>DHT22</b> device row to open device details and navigate to <b>Relations</b> tab. Click on the <b>("+")</b> icon to add new relation. — Click on the **DHT22** device row to open device details and navigate to **Relations** tab. Click on the **("+")** icon to add new relation.

Specify relation type <b>Manages</b> and select <b>Air Conditioner</b> device from the list. Click on the <b>Add</b> to add this relation. Now we verify that devices were provisioned to cloud. — Specify relation type **Manages** and select **Air Conditioner** device from the list. Click on the **Add** to add this relation. Now we verify that devices were provisioned to cloud.

Please open ThingsBoard PE using the URL SERVER_URL:

Login to your ThingsBoard PE instance and open "Device groups" menu page.
Click on the the group All in the menu or in the device groups list.
Make sure that DHT22 and </b>Air Conditioner</b> devices are in the devices list.
Verify that relation from DHT22 to Air Conditioner was provisioned as well.

Login to your <b>ThingsBoard PE</b> instance and open "Device groups" menu page. — Login to your **ThingsBoard PE** instance and open "Device groups" menu page.

Click on the the group <b>All</b> in the menu or in the device groups list. — Click on the the group **All** in the menu or in the device groups list.

Make sure that <b>DHT22</b> and </b>Air Conditioner</b> devices are in the devices list. — Make sure that **DHT22** and </b>Air Conditioner</b> devices are in the devices list.

Verify that relation from <b>DHT22</b> to <b>Air Conditioner</b> was provisioned as well. — Verify that relation from **DHT22** to **Air Conditioner** was provisioned as well.

Configure edge rule engine to handle alarms and send RPC calls

We are going to update “Edge Root Rule Chain” that will handle Alarm Created events for “DHT22” sensor and will send appropriate commands to the “Air Conditioner” device. Here is the final configuration of edge root rule chain:

In the next steps we are going to create TBEL script language node to create appropriate RPC commands to the Air Conditioner device. JavaScript for script node that will emulate enabling of Air Conditioner:

var newMsg = {};
newMsg.method = "enabled_air_conditioner";
newMsg.params = {"speed": 1.0};
return { msg: newMsg, metadata: metadata, msgType: msgType }; 

Please use this snippet in the next steps, if required.

Here are the steps to update default edge “Root Rule Chain” to the rule chain above:

Login to your ThingsBoard PE instance and open Rule chain templates menu page.
Click on the Open rule chain icon to start editing Edge Root Rule Chain.
Filter node by script word and drag script node (Transformation) to rule chain.
Input node name and add TBEL script language code (you can copy and paste it from the snippet above) to create proper enable command for Air Conditioner device. Click on Add to proceed.
Drag connection from Device Profile Node to newly added enabled script node.
Select Alarm Created from the list and click on the Add button.
Click on the Apply changes button to save current progress.
Filter rule nodes by change word and add change originator node to rule chain.
Select Related source. Select Manages filter. Select Device type. Click on the Add button.
Add Success relations from script node to change originator. Add Success relation from change originator to RPC Call Request node. Save changes.

Login to your <b>ThingsBoard PE</b> instance and open <b>Rule chain</b> templates menu page. — Login to your **ThingsBoard PE** instance and open **Rule chain** templates menu page.

Click on the <b>Open rule chain</b> icon to start editing <b>Edge Root Rule Chain</b>. — Click on the **Open rule chain** icon to start editing **Edge Root Rule Chain**.

Filter node by <b>script</b> word and drag script node (Transformation) to rule chain. — Filter node by **script** word and drag script node (Transformation) to rule chain.

Input node name and add <b>TBEL</b> script language code (you can copy and paste it from the snippet above) to create proper <b>enable</b> command for Air Conditioner device. Click on <b>Add</b> to proceed. — Input node name and add **TBEL** script language code (you can copy and paste it from the snippet above) to create proper **enable** command for Air Conditioner device. Click on **Add** to proceed.

Drag connection from Device Profile Node to newly added enabled script node.

Select <b>Alarm Created</b> from the list and click on the <b>Add</b> button. — Select **Alarm Created** from the list and click on the **Add** button.

Click on the <b>Apply changes</b> button to save current progress. — Click on the **Apply changes** button to save current progress.

Filter rule nodes by <b>change</b> word and add <b>change originator</b> node to rule chain. — Filter rule nodes by **change** word and add **change originator** node to rule chain.

Select <b>Related</b> source. Select <b>Manages</b> filter. Select <b>Device</b> type. Click on the <b>Add</b> button. — Select **Related** source. Select **Manages** filter. Select **Device** type. Click on the **Add** button.

Add <b>Success</b> relations from script node to change originator. Add <b>Success</b> relation from change originator to RPC Call Request node. Save changes. — Add **Success** relations from script node to change originator. Add **Success** relation from change originator to RPC Call Request node. Save changes.

Now let’s open ThingsBoard Edge UI to see updated root rule chain:

Login to your ThingsBoard Edge instance and open Rule chains menu page.
Open Edge Root Rule Chain.
Verify that rule chain is the same as you have updated on cloud.

Login to your ThingsBoard <b>Edge</b> instance and open <b>Rule chains</b> menu page. — Login to your ThingsBoard **Edge** instance and open **Rule chains** menu page.

Open <b>Edge Root Rule Chain</b>. — Open **Edge Root Rule Chain**.

Verify that rule chain is the same as you have updated on cloud.

To subscribe to RPC commands from edge for the Air Conditioner device you need to get the Air Conditioner device credentials first. ThingsBoard supports different device credentials. We recommend to use default auto-generated credentials which is access token for this guide.

Please open ThingsBoard Edge UI using the URL: EDGE_URL.

Open Device groups menu page in the ThingsBoard Edge instance.
Open All device group.
Click on the the Air Conditioner device row in the table to open device details.
Click on the Copy access token. Token will be copied to your clipboard. Save it to a safe place.

Open Device groups menu page in the ThingsBoard <b>Edge</b> instance. — Open Device groups menu page in the ThingsBoard **Edge** instance.

Click on the the <b>Air Conditioner</b> device row in the table to open device details. — Click on the the **Air Conditioner** device row in the table to open device details.

Click on the <b>Copy access token</b>. Token will be copied to your clipboard. Save it to a safe place. — Click on the **Copy access token**. Token will be copied to your clipboard. Save it to a safe place.

Now you are ready to subscribe to RPC commands for Air Conditioner device. We will use simple commands to subscribe to RPC commands over MQTT protocol in this example.

Please download following scripts to your local folder:

Before running the scripts, please modify mqtt-js.sh accordingly:

Replace YOUR_ACCESS_TOKEN with Air Conditioner device access token copied from the steps above.
Replace YOUR_TB_EDGE_HOST with your ThingsBoard Edge host. For example, localhost.
Replace YOUR_TB_EDGE_MQTT_PORT with your ThingsBoard Edge MQTT port. For example, 11883 or 1883.

Open the terminal, go to the folder that contains mqtt-js.sh and cooler.js scripts and make sure it is executable:

 chmod +x *.sh

Install mqtt node module to be able to use mqtt package in the cooler.js script:

npm install mqtt --save

Then run the following command:

bash mqtt-js.sh

You should see the following screen with your host and device token:

pc@pc-XPS-15-9550:~/alarm-tutorial$ bash mqtt-js.sh
Connecting to: localhost:1883 using access token: sFqoF18PTyViO8L0qo7c
Cooler is connected!

Post telemetry to “DHT22” sensor to create alarm

To post temperature telemetry to the DHT22 sensor you need to get the DHT22 sensor credentials first. ThingsBoard support different device credentials. We recommend to use default auto-generated credentials which is access token for this guide.

Please open ThingsBoard Edge UI using the URL: EDGE_URL.

Open Device groups menu page in the ThingsBoard Edge instance.
Open All device group.
Click on the DHT22 device row in the table to open device details.
Click on the Copy access token. Token will be copied to your clipboard. Save it to a safe place.

Click on the <b>DHT22</b> device row in the table to open device details. — Click on the **DHT22** device row in the table to open device details.

Now you are ready to publish temperature telemetry data on behalf of your device. We will use simple commands to publish temperature data over HTTP or MQTT in this example.

HTTPLinux, macOS or Windows

MQTTLinux or macOS

MQTTWindows

CoAPLinux or macOS

Install cURL for Ubuntu:

sudo apt-get install curl

Install cURL for macOS:

brew install curl

Install cURL for Windows:

Starting Windows 10 b17063, cURL is available by default. More info is available in this MSDB blog post. If you are using older version of Windows OS, you may find official installation guides here.

This command works for Windows, Ubuntu and macOS, assuming the cURL tool is already installed. Replace $HOST_NAME and $ACCESS_TOKEN with corresponding values.

curl -v -X POST -d "{\"temperature\": 25}" $HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

For example, $HOST_NAME reference your local ThingsBoard Edge installation, access token is ABC123:

curl -v -X POST -d "{\"temperature\": 25}" http://localhost:8080/api/v1/ABC123/telemetry --header "Content-Type:application/json"

Install mqtt client for Ubuntu:

sudo apt-get install mosquitto-clients

Install cURL for macOS:

brew install mosquitto-clients

Replace $HOST_NAME, $MQTT_PORT and $ACCESS_TOKEN with corresponding values.

mosquitto_pub -d -q 1 -h "$HOST_NAME" -p "$MQTT_PORT" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -m {"temperature":25}

For example, $HOST_NAME reference your local ThingsBoard Edge installation, MQTT port is 1883 and access token is ABC123:

mosquitto_pub -d -q 1 -h "localhost" -p "1883" -t "v1/devices/me/telemetry" -u "ABC123" -m {"temperature":25}

Successful output should look similar to this one:

Client mosqpub|xxx sending CONNECT
Client mosqpub|xxx received CONNACK
Client mosqpub|xxx sending PUBLISH (d0, q1, r0, m1, 'v1/devices/me/telemetry', ... (16 bytes))
Client mosqpub|xxx received PUBACK (Mid: 1)
Client mosqpub|xxx sending DISCONNECT

Note: Since ThingsBoard 3.2, you are able to use basic MQTT credentials (combination of client id, user name and password ) and customize topic names and payload type using Device Profile. See more info here.

Install MQTTBox plugin for Chrome. Use the instructions listed below:

Create new MQTT Client with the properties listed in screenshots below.
Populate the topic name and payload. Make sure the payload is a valid JSON document. Click on the Publish button.

Create new MQTT Client with the properties listed in screenshots below.

Populate the topic name and payload. Make sure the payload is a valid JSON document. Click on the <b>Publish</b> button. — Populate the topic name and payload. Make sure the payload is a valid JSON document. Click on the **Publish** button.

Install coap-cli. Assuming you have Node.js and NPM installed on your Windows/Linux/MacOS machine, execute the following command:

npm install coap-cli -g

Replace $HOST_NAME, $COAP_PORT and $ACCESS_TOKEN with corresponding values. If $COAP_PORT is not specified, default 5683 used.

echo -n '{"temperature": 25}' | coap post coap://$HOST_NAME:$COAP_PORT/api/v1/$ACCESS_TOKEN/telemetry

For example, $HOST_NAME reference your local ThingsBoard Edge installation, coap port is 5683 and access token is ABC123:

echo -n '{"temperature": 25}' | coap post coap://localhost:5683/api/v1/ABC123/telemetry

Once you have successfully published the “temperature” readings with value 51:

HTTPLinux, macOS or Windows

MQTTLinux or macOS

MQTTWindows

CoAPLinux or macOS

curl -v -X POST -d "{\"temperature\": 51}" http://localhost:8080/api/v1/ABC123/telemetry --header "Content-Type:application/json"

mosquitto_pub -d -q 1 -h "localhost" -p "1883" -t "v1/devices/me/telemetry" -u "ABC123" -m {"temperature":51}

Using MQTTBox please publish temperature telemetry with value 51.

echo -n '{"temperature": 51}' | coap post coap://localhost:5683/api/v1/ABC123/telemetry

You should immediately see alarm in the Device Alarm Tab:

Click on the DHT22 device row in the table to open device details.
Navigate to the alarm tab.

Verify that RPC request was send to “Air Conditioner” device

Open the terminal where mqtt-js.sh script is running. You should see similar messages on the screen:

pc@pc-XPS-15-9550:~/alarm-tutorial$ bash mqtt-js.sh
Connecting to: localhost:1883 using access token: sFqoF18PTyViO8L0qo7c
Cooler is connected!
Received RPC command from edge!
Method: enabled_air_conditioner
Speed params: 1

Congratulations! RPC request was successfully sent to Air Conditioner device based on the temperature readings from the DHT22 sensor.

Next Steps

Getting started guide - Provide quick overview of main ThingsBoard Edge features. Designed to be completed in 15-30 minutes:
Installation guides - Learn how to setup ThingsBoard Edge on various available operating systems and connect to ThingsBoard CE server.
Edge Rule Engine:
- Rule Chain Templates - Learn how to use ThingsBoard Edge Rule Chain Templates.
- Provision Rule Chains from cloud to edge - Learn how to provision edge rule chains from cloud to edge.
Security:
- gRPC over SSL/TLS - Learn how to configure gRPC over SSL/TLS for communication between edge and cloud.
Features:
- Edge Status - Learn about Edge Status page on ThingsBoard Edge.
- Cloud Events - Learn about Cloud Events page on ThingsBoard Edge.
Use cases:
- Data filtering and traffic reduce - This guide will show how to send to cloud from edge only filterd amount of device data:
Roadmap - ThingsBoard Edge roadmap.