How to monitor temperature and send alerts with Live Objects

Let’s try it! Receive an alert if a fridge is too hot

We will demonstrate some alerting features embedded in Live Objects. These features are only available through APIs and are documented in the developer guide.

Our use case: monitor a set of fridges and freezers. Be notified by email and HttpPush on a webhook when the temperature goes out of the normal range and be notified when the situation is back to normal.

For the demo purpose we will use MQTT devices, but you could use any other connectivity.

First, we will create devices and add a tag on each device (“freezer” or “fridge”) depending on the type of the device.

If you prefer, you can also use groups to separate your devices between fridges and freezers.

Use state processing rules for analyzing temperature changes

First define normal and abnormal state based on temperature level and be alerted when a device changes of state.

Then we will create  rules with our business case: temperature monitoring.

We will have 2 rules, one for freezers and one for fridges.

The rules are state processing rules: it computes a state of the device using the jsonLogic syntax. See developer guide for the syntax details.

The stateFunction retrieves the value.temp Json field of the telemetry Data Message and compares this temperatures with the provided limits. Then it returns a “state” (String value).

In this example, the state function output can be “too hot”, “normal” or “too cold”.

The filterPredicate selects the target devices for the rule based on tags. It checks that the required tag is in the set of tags of the device. If not, the rule is ignored. For that purpose we use the “in” operator that checks if a value is in a JSON array.

The stateKeyPath should be a unique identifier for storing and comparing states. By default use metadata.source.

Each time a device sends a message, the filter predicate is checked. If the tag selection is ok, then the state function is evaluated. The computed state is compared with the memorized previous state computed with the previous message. If the state changes, a stateChangeEvent is emitted. See the documentation to know more.

POST https:/liveobjects.orange-business.com/api/v0/eventprocessing/stateprocessing-rule
Headers
x-api-key : secretApiKey

Body
{
        "name": "freezer monitoring",
        "enabled": true,
        "stateFunction": {
            "if": [
                {
                    "<": [
                        {
                            "var": "value.temp"
                        },
                        -20
                    ]
                },
                "too cold",
                {
                    "<=": [
                        {
                            "var": "value.temp"
                        },
                        -10
                    ]
                },
                "normal",
                "too hot"
            ]
        },
        "filterPredicate": {
            "in": [
                "freezer",
                {
                    "var": "tags"
                }
            ]
        },
        "stateKeyPath": "metadata.source"
    }

POST https:/liveobjects.orange-business.com/api/v0/eventprocessing/stateprocessing-rule
Headers
x-api-key : secretApiKey

Body
{
        "name": "fridge monitoring",
        "enabled": true,
        "stateFunction": {
            "if": [
                {
                    "<": [
                        {
                            "var": "value.temp"
                        },
                        0
                    ]
                },
                "too cold",
                {
                    "<=": [
                        {
                            "var": "value.temp"
                        },
                        5
                    ]
                },
                "normal",
                "too hot"
            ]
        },
        "filterPredicate": {
            "in": [
                "fridge",
                {
                    "var": "tags"
                }
            ]
        },
        "stateKeyPath": "metadata.source"
    }

Create alerts with Event2action API

Now we want to forward alerts to human or automated systems. Live Objects can send emails or HttpPush (webhook) notifications. This is done with event2Action API.

We can use POST or PUT verb. If you use PUT, you must provide the id in the path and the body of the request.

We use a Mustach template to generate a human readable email. By default, the whole message is used as body.

Be careful of the filter.ruleIds field where you should add in the array the id of the state processing rule

POST https:/liveobjects.orange-business.com/api/v0/eventprocessing/stateprocessing-rule
Headers
x-api-key : secretApiKey

Body
{
   {
  "id": "freezernotifications",
  "name": "freezernotificationrule",
  "enabled": true,
  "triggers": {
    "stateChange": {
      "version": 1,
      "filter": {
        "ruleIds": ["insert here state processing rule Ids as list"]
      }
    }
  },
  "actions": {
    "emails": [
      {
        "type": "email",
        "to": ["you@yourdomain.com"],
        "subjectTemplate": "Freezer State change for {{stateKey}}",
        "contentTemplate": "Freezer {{stateKey}} has changed from state {{previousState}} to state {{newState}} ({{data.value.temp}} celcius) at {{timestamp}}"
      }
    ],
    "httpPush": [
      {"webhookUrl": "https://yourHTTPserver.com"}
    ]
  }
}

Then do the same with fridge tag.

We could use the same Event2action rule for freezer and fridge if the same person oversees the equipment… If so, in the ruleIds field, provide all the state processing ruleIds.

Let’s test it!

We use a MQTT application to simulate temperature telemetry of a freezer (MQTT.fx for instance).

We first send several temperature messages in the normal range:

Publish on topic dev/data
{"value": { "temp" : -12}}

After a first initialization message, no more messages should be received.

Then we send a measure with a high temperature:

Publish on topic dev/data
{"value": { "temp" : -3}}

An email is received with the body:

Freezer urn:lo:nsid:mqtt:freezer_1 has changed from state normal to state too hot (-3 celcius) at 2024-05-22T15:04:31.585Z

A webhook call is received with the body:

{“type”:”stateChange”,”version”:1,”stateKey”:”urn:lo:nsid:mqtt:freezer_1″,”previousState”:”normal”,”newState”:”too hot”,”timestamp”:”2024-05-22T15:04:31.585Z”,”stateProcessingRuleId”:”27d09c96-7999-491f-9161-22207de4448c”,”stateProcessingRule”:{“id”:”27d09c96-7999-491f-9161-22207de4448c”,”name”:”freezer monitoring”},”data”:{“type”:”dataMessage”,”version”:1,”streamId”:”urn:lo:nsid:mqtt:freezer_1″,”timestamp”:”2024-05-22T15:04:31.559Z”,”value”:{“temp”:-3},”tags”:[“freezer”],”extra”:{},”metadata”:{“source”:”urn:lo:nsid:mqtt:freezer_1″,”group”:{“id”:”root”,”path”:”/”},”connector”:”mqtt”,”network”:{“mqtt”:{“clientId”:”freezer_1″}}},”created”:”2024-05-22T15:04:31.559Z”}}

And so on… Each time a device changed its state an email will be sent. If a device stays in the same state no notification is sent.  You can customize email and SMS with templates.

How to go further

If you want to customize rules with dynamic parameters or implement hysteresis logic please have a look at the dedicated description in the developer guide.

Need to trigger when a value is exceeded?

In the next article we will explore event processing API which can also be used for monitoring and alerting with a different logic: be alerted at a chosen frequency of a temperature level beyond limits.