Configuring Periodic Monitoring for a Datapoint

A datapoint has a Monitoring Preference Object with rate, report, throttle, threshold, focus, cat and inFeedback fields available for detailed control.

The rate field can be used to determine the rate at which the datapoint is polled.

The rate field can be set to null (undefined), “0”, “none”, “slow”, “normal”, “fast” or an absolute value in seconds.

"None" disables monitoring. Defaults to “none” if monitor is undefined.

“slow”, “normal”, and “fast” enable monitoring with polling at automatically selected rates.

Monitoring preferences are ignored for property datapoints.

Changes to datapoint and properties initiated through IAP always yield an updated value in the feedback channel.

A datapoint can also be monitored for unsolicited change, that is, for a change that is not initiated through IAP. Monitoring looks for changes that occur due to external events, such as peer-to-peer connections, or due to events occurring on the edge device, such as new physical sensor samples or alerts. Changes to a monitored datapoint will generate updates the feedback and event channel associated topics, see monitor preference object below.

Default simple monitoring always updates both the event and feedback channel objects, has no throttle, threshold or change filtering, and uses the default event category “data”.

Examples:

IAP/MQ:

Node.js Example:

/* jshint esversion: 6 */
/* jslint node: true, maxerr: 10000 */

"use strict";
const mqtt = require("mqtt");
const client = mqtt.connect("mqtt://localhost:1883");
const SID = "17q3ak7"; // SID to be used in the topics

/**
* @param {String} protocol protocol of the device
* @param {String} deviceHandle handle of the device
* @param {String} blockHandle block handle such as Lamp, Switch, LighTSensor
* @param {String} blockIndex block index such as 0,1
* @param {String} dataPoint datapoint name
* @param {Object} monitorObj monitor configuration object which could specify the rate, throttle, threshold etc
*/

function configureMonitor(
protocol, deviceHandle, blockHandle, blockIndex, dataPoint, monitorObj
) {

   // create topic glp/0/SID/rq/dev/P/H/if/BLOCK_HANDLE/BLOCK_INDEX/monitor

   let topic = "glp/0/" + SID + "/rq/dev/" + protocol + "/" + deviceHandle + "/if/" + blockHandle + "/" + blockIndex + "/" + dataPoint + "/monitor";
   client.publish(topic, JSON.stringify(monitorObj));
   client.end();
}

client.on("connect", function () {

// configure monitoring for a datapoint 'nvoLuxLevel', of a 'lon' device with device handle '2',block handle LightSensor and block index 0

   configureMonitor(
       "lon", "2", "LightSensor", "0", "nvoLuxLevel", {
           "rate": 5
       }
   );
});

IAP/REST:

PUT /iap/devs/8/if/Lamp/0/nviValue/monitor {"rate": 5}
PUT /iap/devs/8/if/Lamp/0/nviValue/monitor {"rate": 0}
PUT /iap/devs/8/if/Lamp/0/nviValue/monitor {"rate": "normal"}

Monitoring Preference Object

When the monitoring engine detects a new value for a datapoint, it examines the new value and the most recently reported value for the datapoint under the rules detailed in the monitoring preference object. This evaluation may cause a report of the new value in the event channel using an Event object (see Events in the IAP/MQ API Reference).

Newly captured values also trigger an update of the feedback channel object that contains the corresponding datapoint, if the value changed. This can cause frequent updates of large feedback channel objects. The monitoring preferences can suppress this feedback update with the inFeedback property, described in Monitoring Preference Object in the IAP/MQ API Reference.

Reporting a Captured Value

When a captured value qualifies for reporting, the report is made through an Event object in the IAP/MQ event channel, using the sub-channel selected with the monitoring preference object’s cat property (the Event object properties are described in Events).

The default for the category is “data”, and therefore the corresponding Event object is published to glp/0/{SID}/ev/data.

Three properties in the Event object are of particular interest in terms of reporting a captured value:

data	contains the captured value, limited to the focus, if a focus is specified.
topic	contains the IAP/MQ feedback channel topic of the object containing the datapoint, typically a reference to an interface block. topic references a published object, not including references to properties within that object.
message	contains the property path within the object addressed in the topic to the data reported.

For example, consider the examples described in Monitoring Preference Object in the IAP/MQ API Reference. Assume this datapoint implements the “speedReport” member of the object: glp/0/example/fb/dev/lon/8/if/speed/2. And assume a focus is not defined. In this case, the event object’s topic is glp/0/example/fb/dev/lon/8/if/speed/2, and the message is speedReport/value.

With an additional focus of point/z the message property becomes speedReport/value/point/z.

The topic and message properties combine to complete the path to the property that corresponds to the data reported.