Live Objects - complete developer guide

Activity Processing

Concepts

Activity processing (AP) service aims at detecting devices that have no activity.

All of the following 'activities' are monitored :

'connected' event sent by the device
new data sent with the deviceId as 'metadata.source'
command response from this device
setParam response from this device

Activity rules

You can set up Activity rules to define how devices activity should be monitored.

You can target a list of deviceIds or a list of groups. All devices of these groups will be targeted. You can target a group with its path, including or not the subPath.

If a device is targeted by several rules, then several activity events can be thrown for this device.

Table 1. **Activity rule**
field name	required ?	description
enabled	required	Defines if the rule should be activated or not.
name	required	Name of the rule that can be used to ease rule management, must be unique and not empty.
silentPolicy	required	Define the duration of device inactivity before throwing an event. This duration will be reused when the device will be active once again. You can also define a repeat interval (optional) : the 'silent' event will be re-thrown at this interval as long as the device remains silent. All the duration are defined using ISO 8601, e.g. 'P1D' for 1 day, 'PT12H' for 12 hours, 'P2DT3H30M' for 2 days 3 hours 30 minutes. Please note that any duration below 10 minutes will be handled by the platform as a 10 minutes delay (this goes for both inactivity delay and repeat interval)
targets	required	List of deviceIds and/or devices groups that targeted by the rule. At least 1 deviceId or 1 group must be set. Groups are targeted by their path (e.g. '/europe/france'), and an additional marker to specify if all subpath groups must be targeted. If a new device is added to or removed from a targeted group, it will be taken into account.
tags	optional	A list of tags can be set : they will be recorded in all events triggered by this rule. This can ease event search and management.

When an activityRule is updated, all activity states linked to this rule are reset to a specific 'UNKNOWN' state.

Activity States

An activity state is unique for a couple 'activity rule id + device id', it holds :

the state 'ACTIVE', 'SILENT' or 'UNKNOWN' of the device for this rule. As a device can be targeted by several rules with different silent duration, at a specific moment, 1 device can have several activity states, with different states. 'UNKNOWN' is specific to the initial state after activity rule creation or update.
the last activity timestamp of the device.
the timestamp of the next alarm that will be sent if there is no device activity until then. It can be triggered by the silent duration or repeatInterval duration depending on the current state (respectively ACTIVE or SILENT).
the number of times a reminder has been sent for the current state.

Activity Events

Activity 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 deviceActivity events.

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

Example

Here is one example of usage of the activity processing.

ActivityRule targeting the group path '/france/lyon' an all its sub path. The silent trigger is 1 day and the repeat alarm interval is 12 hours.

{
  "name": "devices in Lyon",
  "enabled": true,
  "silentPolicy": {
    "duration" : "P1D",
    "repeatInterval" : "PT12H"
  },
  "targets": {
    "groupPaths" : [
      {
        "path" : "/france/lyon",
        "includeSubPath" : true
      }
    ]
  }
}

If the device does not connect nor send any data for 1 day, then the following event will be sent:

{
  "deviceId": "urn:lo:nsid:dongle:00-14-22-01-23-45",
  "deviceAdditionalInfo": {
    "deviceName": "myDongle001",
    "groupPath": "/france/lyon"
  },
  "state":"SILENT",
  "numberOfAlarmReminders": 0,
  "timestamp": "2018-04-24T08:29:49.029Z",
  "activityRule": {
    "id": "d16b4319-a486-4cb8-a10e-b4a452cda4be",
    "name": "devices in Lyon",
    "enabled": true,
    "silentPolicy": {
      "duration" : "P1D",
      "repeatInterval" : "PT12H"
    },
    "targets": {
      "groupPaths" : [
        {
          "path" : "/france/lyon",
          "includeSubPath" : true
        }
      ]
    }
  }
}

12 hours later, if the device is still silent, the event will be sent again with 'numberOfAlarmReminders' incremented by 1:

{
  "deviceId": "urn:lo:nsid:dongle:00-14-22-01-23-45",
  "deviceAdditionalInfo": {
    "deviceName": "myDongle001",
    "groupPath": "/france/lyon"
  },
  "state":"SILENT",
  "numberOfAlarmReminders": 1,
  "timestamp": "2018-04-24T20:29:49.029Z",
  "activityRule": {
    "id": "d16b4319-a486-4cb8-a10e-b4a452cda4be",
    "name": "devices in Lyon",
    "enabled": true,
    "silentPolicy": {
      "duration" : "P1D",
      "repeatInterval" : "PT12H"
    },
    "targets": {
      "groupPaths" : [
        {
          "path" : "/france/lyon",
          "includeSubPath" : true
        }
      ]
    }
  }
}