Live Objects - complete developer guide

State Processing

Concepts

State processing (SP) service aims at detecting changes in "device state" computed from data messages.

A state can represent any result computed from Live Objects data messages : geo-zone ("paris-area", "london-area", ..), temperature status ("hot", "cold", ..), availability status ("ok" , "ko"). Each state is identified by a key retrieved from the user-defined json-path in the data message.

stateKeyPath examples : "streamId", "metadata.source"

A state is computed by applying a state function to a data Message. A notification is sent by Live Objects each time a state value change. State processing differs from event processing as it provides stateful rules which is useful for use cases more complex than normal/alert status. State processing can be seen as a basic state machine where transitions between states are managed by the state function result and events are transition notifications.

State Processing rules

You can set up StateProcessing rules to define how data messages are processed by the SP service.

A StateProcessing rule applies to all new data messages.

Table 1. **StateProcessing rule**
field name	required ?	description
enabled	required	Defines if the rule should be enabled and applied to new data message.
filterPredicate	optional	Filters data on which the state processing logic should be applied. This boolean function is described in JsonLogic syntax. If no filter predicate is specified, state function is applied to every data message.
stateKeyPath	required	A json-path that will be used to retrieve the state key form the triggering data message. Example: In order to associate a state with a device status and depending on your needs, you can use streamId or metadata.source as stateKey path.
stateFunction	required	This is the core of the state processing logic. This function takes as input a data message and computes a state associated whith the state key. The State function is written in JsonLogic syntax and can return any primitive value : String, Number, Boolean.

State change events

State change events are accessible with the MQTT API. Your business application must connect using MQTT application mode and subscribe to a FIFO. This FIFO should previously be filled with stateChange events.

References: MQTT Application mode, Event base trigger and Alarm output model.

State processing initialization

When a state is computed for the first time, it generates a state change event with previous state equals null.

Examples

Here are some examples of usage of the state processing.

Temperature monitoring of a device sensor, with 3 temperature ranges.

Temperature State processing logic:

if temperature is below 0 degree Celsius, sensor state is cold.
if temperature is between 0 and 100 degrees Celsius sensor state is normal.
if temperature is higher than 100 degrees Celsius sensor state is hot.

The sensor is identified by the streamId field within the data message.

{
  "name": "temperature state rule",
  "enabled": true,
  "stateKeyPath": "streamId",
  "stateFunction": {
    "if": [
      {"<": [
        {"var": "value.temp"},
        0
      ]},
      "cold",
      {"<=": [
        {"var": "value.temp"},
        100
      ]},
      "normal",
      "hot"
    ]
  }
}

We assume that the current state of the sensor is "normal".

The following data message will generate a state change event from "normal" to "hot" for state key : "urn:lo:nsid:mqtt:myTest".

{
  "streamId":"urn:lo:nsid:dongle:00-14-22-01-23-45!temperature",
  "location":{
    "lat":37.773972,
    "lon":-122.431297
  },
  "model":"temperatureDevice_v0",
  "value":{
    "temp":200
  }
}

State change event :

{
  "stateProcessingRuleId": "75c47213-b7fb-4fd9-8c4a-9d2209236a60",
  "data": {
    "metadata": {
      "connector": "mqtt",
      "source": "urn:lo:nsid:mqtt:myTest",
      "transformation": {
        "published": {
          "location": {
            "lon": -122.431297,
            "lat": 37.773972
          }
        }
      },
      "group": {
        "path": "/",
        "id": "root"
      },
      "network": {
        "mqtt": {
          "clientId": "urn:lo:nsid:mqtt:myTest"
        }
      }
    },
    "streamId": "urn:lo:nsid:dongle:00-14-22-01-23-45!temperature",
    "extra": {},
    "location": {
      "lon": -122.431297,
      "lat": 37.773972
    },
    "model": "temperatureDevice_v0",
    "value": {
      "temp": 200
    },
    "timestamp": "2021-06-17T12:30:16.659Z",
    "tags": []
  },
  "tenantId": "5c0a6fb49a927971342aea06",
  "newState": "hot",
  "previousState": "normal",
  "timestamp": "2021-06-17T12:30:16.708Z",
  "stateProcessingRule": {
    "stateKeyPath": "urn:lo:nsid:dongle:00-14-22-01-23-45!temperature",
    "name": "temperature state rule",
    "stateFunction": "{\"if\":[{\"<\":[{\"var\":\"value.temp\"},0]},\"cold\",{\"<\":[{\"var\":\"value.temp\"},100]},\"normal\",\"hot\"]}",
    "id": "75c47213-b7fb-4fd9-8c4a-9d2209236a60",
    "enabled": true,
    "filterPredicate": "null"
  }
}