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.

For simplicity we are going to refer to server UI URL as SERVER_URL despite if you installed ThingsBoard server on-previse or using cloud host version.

Edge UI URL respectively as EDGE_URL below in tutorial.

If you changed the Edge HTTP bind port to 18080 during Edge installation, use the following ThingsBoard Edge UI link: http://localhost:18080.

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 page.
• Click "+" to add new device profile.
• Input device profile name. For example, type "edge thermostat". Click "Transport configuration" to proceed.
• For this example we will use default transport configuration. Click "Alarm rules" to proceed.
• Click "Add alarm rule" button.
• Specify alarm type. For example, "High temperature". Click "+" icon to add new alarm condition.
• Click "Add key filter" button.
• Select key type, input key name, select value type and click "Add".
• Select operation and input threshold value. Click "Add".
• Click "Save" button.
• Click "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.

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 "Add Device"("+") icon in the top right corner of the table.
• Input device name. For example, "DHT22". Select "edge thermostat" from device profiles list. No other changes required at this time. Click "Add" to add the device.
• Now your "DHT22" device should be listed first, since table sort devices using created time by default. Click "Add" to add one more device.
• Input device name. For example, "Air Conditioner". No other changes required at this time. Click "Add" to add the device.
• Now your "Air Conditioner" device should be listed first, since table sort devices using created time by default.
• Click on "DHT22" device row to open device details and navigate to "Relations" tab. Click "+" icon to add new relation.
• Specify relation type "Manages" and select "Air Conditioner" device from the list. Click "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" page.
• Click on the group "All" in the menu or in the device groups list.
• Make sure that "DHT22" and "Air Conditioner" devices are in the devices list.
• 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 JavaScript node to create appropriate RPC commands to the Air Conditioner device. JavaScript for script node that will emulate enabling of Air Conditioner:

1
2
3
4
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 page.
• Click "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 JavaScript code (you can copy and paste it from the snippet above) to create proper enable command for Air Conditioner device. Click "Add" to proceed.
• Drag connection from "Device Profile Node" to newly added enabled script node.
• Select "Alarm Created" from the list and click "Add" button.
• Click "Apply changes" 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 "Add".
• 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 page.
• Open "Edge Root Rule Chain".
• Verify that rule chain is the same as you have updated on cloud.

Connect “Air Conditioner” to edge and subscribe for RPC commands

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 page in the ThingsBoard Edge instance.
• Open "All" device group.
• Click on the Air Conditioner device row in the table to open device details.
• Click "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:

• mqtt-js.sh
• cooler.js

We assume that you have Node.js and NPM installed on your local PC.

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:

1
 chmod +x *.sh

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

1
npm install mqtt --save

Then run the following command:

1
bash mqtt-js.sh

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

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

Please open a new terminal tab to push temperature telemetry to device and leave this running in the background until end of the guide.

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 page in the ThingsBoard Edge instance.
• Open "All" device group.
• Click on the DHT22 device row in the table to open device details.
• Click "Copy access token". Token will be copied to your clipboard. Save it to a safe place.

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: 1 sudo apt-get install curl Install cURL for macOS: 1 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. 1 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: 1 curl -v -X POST -d "{\"temperature\": 25}" http://localhost:8080/api/v1/ABC123/telemetry --header "Content-Type:application/json"

Install mqtt client for Ubuntu: 1 sudo apt-get install mosquitto-clients Install cURL for macOS: 1 brew install mosquitto-clients Replace $HOST_NAME, $MQTT_PORT and $ACCESS_TOKEN with corresponding values. 1 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: 1 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: 1 2 3 4 5 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 "Publish" button.

Install coap-cli. Assuming you have Node.js and NPM installed on your Windows/Linux/MacOS machine, execute the following command: 1 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. 1 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: 1 echo -n '{"temperature": 25}' | coap post coap://localhost:5683/api/v1/ABC123/telemetry

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

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

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

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

1
2
3
4
5
6
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.