IoT Hub
IoT Hub Documentation
Getting Started with Rule Engine
Getting Started Documentation Guides API FAQ

On this page

Getting Started with Rule Engine

What is IoT Hub 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

IoT Hub Rule Engine is a highly customizable framework for complex event processing. Here are some common use cases that one can configure via IoT Hub 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 IoT Hub. DHT22 sensor can measure temperature from -40°C to +80°C.

In this tutorial we will configure IoT Hub 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 IoT Hub UI go to Rule Chains section and open Root Rule Chain.

image

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

1
2

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

image

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:

image

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

image

image

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

image

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:

image

Press Save button to apply changes.

Validate results

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

image

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.

image

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

1

curl -v -X POST -d '{"temperature":99}' https://iothub.magenta.at/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

*you need to replace $ACCESS_TOKEN with actual device token

image

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

1

curl -v -X POST -d '{"temperature":24}' https://iothub.magenta.at/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

image

See Also:

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



Next steps