Getting Started with Rule Engine

• What is ThingsBoard Rule Engine?
• Typical Use Cases
• Hello-World Example
  • Adding temperature validation node
  • Validate results
• See Also:
• Next steps

What is ThingsBoard Rule Engine?

Rule Engine is an easy to use framework for building event-based workflows. There are 3 main components:

• Message - any incoming event. It can be an incoming data from devices, device life-cycle event, REST API event, RPC request, etc.
• Rule Node - a function that is executed on an incoming message. There are many different Node types that can filter, transform or execute some action on incoming Message.
• Rule Chain - nodes are connected with each other with relations, so the outbound message from rule node is sent to next connected rule nodes.

Typical Use Cases

ThingsBoard Rule Engine is a highly customizable framework for complex event processing. Here are some common use cases that one can configure via ThingsBoard Rule Chains:

• Data validation and modification for incoming telemetry or attributes before saving to the database.
• Copy telemetry or attributes from devices to related assets so you can aggregate telemetry. For example data from multiple devices can be aggregated in related Asset.
• Create/Update/Clear alarms based on defined conditions.
• Trigger actions based on device life-cycle events. For example, create alerts if Device is Online/Offline.
• Load additional data required for processing. For example, load temperature threshold value for a device that is defined in Device’s Customer or Tenant attribute.
• Trigger REST API calls to external systems.
• Send emails when complex event occurs and use attributes of other entities inside Email Template.
• Take into account User preferences during event processing.
• Make RPC calls based on defined condition.
• Integrate with external pipelines like Kafka, Spark, AWS services, etc.

Hello-World Example

Let’s assume your device is using DHT22 sensor to collect and push temperature to the ThingsBoard. DHT22 sensor can measure temperature from -40°C to +80°C.

In this tutorial we will configure ThingsBoard Rule Engine to store all temperature within -40 to 80°C range and log all other readings to the system log.

Adding temperature validation node

In Thingsboard UI go to Rule Chains section and open Root Rule Chain.

Drag and Drop Script Filter rule node to the chain. Node configuration window will be opened. We will use this script for data validation:

return typeof msg.temperature === 'undefined' 
        || (msg.temperature >= -40 && msg.temperature <= 80);

If temperature property not defined or temperature is valid - script will return True, otherwise it will return False. If script returns True incoming message will be routed to the next nodes that are connected with True relation.

Now we want that all telemetry requests pass through this validation script. We need to remove the existing Post Telemetry relation between Message Type Switch node and Save Telemetry node:

And connect Message Type Switch node with Script Filter node using Post Telemetry relation:

Next, we need to connect Script Filter node with Save Telemetry node using True relation. So all valid telemetry will be saved:

Also, we will connect Script Filter node with Log Other node using False relation. So that all not valid telemetry will be logged in the system log:

Press Save button to apply changes.

Validate results

For validating results we will need to create Device and submit telemetry to the Thingsboard. So go to Devices section and create new Device:

For posting device telemetry we will use Rest API. To do this this we will need to copy device access token from the device Thermostat Home.

Lets post temperature = 99. We will see that telemetry was not added in Device Latest Telemetry section:

curl -v -X POST -d '{"temperature":99}' http://localhost:8080/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

*you need to replace $ACCESS_TOKEN with actual device token

Lets post temperature = 24. We will see that telemetry was saved successfully.

curl -v -X POST -d '{"temperature":24}' http://localhost:8080/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

See Also:

You can use the next links for learning more about Thingsboard Rule Engine:

• Rule Engine Overview
• Rule Engine Architecture
• Debug Node Execution
• Validate incoming telemetry
• Transform incoming telemetry
• Transform telemetry using previous record
• Create & clear alarms
• Send email on alarm
• Create alarm when the device is offline
• Check Relation between Entities
• RPC Request to Related Device
• Add & remove devices to group dynamically
• Aggregate incoming data stream

Next steps

• Installation guides - Learn how to setup ThingsBoard on various available operating systems.

• Connect your device - Learn how to connect devices based on your connectivity technology or solution.

• Data visualization - These guides contain instructions how to configure complex ThingsBoard dashboards.

• Data processing & actions - Learn how to use ThingsBoard Rule Engine.

• IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.

• Hardware samples - Learn how to connect various hardware platforms to ThingsBoard.

• Advanced features - Learn about advanced ThingsBoard features.

• Contribution and Development - Learn about contribution and development in ThingsBoard.