Datapoint Objects

Datapoint objects combine value and meta data such as direction, type, and description. The data type is typically not changeable, although advanced applications and processors can support changes to the data type at runtime, subject to certain conditions.

An IAP Datapoint object has these properties:

Field Name

Type

Description

active

Boolean

Active flag is used with overrides. A write-only property.

For more information, see Working with Datapoint Values and Working with Unions.

cat

string

Either “in” (input to the block) or “out” (output from the block) to indicate the datapoint's direction.

An input datapoint is one that delivers a value into an application that processes the value. For example, an edge device that controls a physical light dimmer has an input datapoint through which it receives the desired dimming level. The application then drives the physical dimmer output circuitry accordingly.

An output datapoint is one that receives a value from an application that produces the value. For example, the light dimmer device can report the dimmer's operating state, electrical current and temperature with output datapoints.

Most properties are implemented using input datapoints, and are used to provide input to the application's algorithm, such as calibration data or alarm threshold values. Some properties can also provide outputs from the application, such as those that report an application's version number. Properties should be seen as directionless in the general case.

default

object

(Optional) Default value. If default is undefined, default is assumed to be all zeroes.

Value must match type.

For more information, see Working with Datapoint Values and Working with Unions.

desc

string

(Optional) A description of the datapoint.

name

string

(Optional) A human readable name for the datapoint. The name is absent or null if it is not supplied.

The name property specifies the datapoint instance name. If the name property is not supplied, the datapoint XIF name specifies the datapoint instance name.

Example block object:

{
     type: “SFPTopenLoopSensor”,               // the block’s profile
     nviCurrent_001: {                                     // datapoint name
          type: “SNVT_switch”,                         // datapoint type
          cat: “in”,                                              // datapoint direction
          name: “current”,                                 // datapoint programmable name
          …
     },
     …
}

monitor

String or object

monitor can be null (undefined), “0”, “none”, “slow”, “normal” or “fast”, or a Monitoring Preference Object for detailed control.

"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.

Simple monitoring always updates the feedback channel object, has no throttle, threshold or change filtering, and uses the default event category “data”.

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).

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.

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 by default.

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 in the threshold property in Monitoring Preference Object. Assume this datapoint implements the “speedReport” member of the object: glp/0/example/fb/dev/lon/8/if/speed/2 . And the 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.

prio

Number

(Optional) Priority used with assignments to value. prio can be set to integer levels 1 to 16. The prio property defaults to priority 8. prio is a write-only property.

When prio is assigned at the same time as value, processing the value assignment occurs under the new prio value.

For more information, see Working with Datapoint Values and Working with Unions.

property

Boolean

Set to True for property datapoints.

Defaults to False if undefined.

read-only

Boolean

A read-only datapoint or property is one that may not be changed through IAP. However, an output read-only datapoint or property can change its value.

Read-only input datapoints are supported but not in use except for datapoints implementing properties. Output datapoints that are implemented on remote edge devices are always considered read-only. But output datapoints that are local to an IAP application that defines them, can be written by that application, thereby providing output data to the network.

Defaults to False if undefined.

status

List of strings

(Optional) Datapoint status. The status property may be omitted if not supported. Otherwise, it is a list of strings, each string representing a known status. The list must not contain duplicates and cannot be assigned from a tool.

Non-standard status values can be conveyed with a prefix from the edge protocol identifier and a period. For example, an “xyz” protocol processor might include an “xyz.out-of-range” status.

The standard datapoint status values:

alarm	indicates an alarm condition. For example, a remote temperature sensor output datapoint could be configured to enter that state when the temperature exceeds a certain threshold.
disabled	indicates that the datapoint is disabled, out-of-service. Value assignments have no effect and monitoring tools never detect a value change when the datapoint is in that state
down	indicates a problem in communicating with the datapoint
fault	indicates a fault condition in relation to the peripheral device. For example, a remote temperature sensor output datapoint could be in this state if communication with the physical temperature sensor failed. The “fault” state does not indicate a failure in communication with the datapoint itself; see “down”.
overridden	indicates that the datapoint has been forced to an override value. Its current value is the override value and does not change, for example with a change of the measured temperature.

type

string

See Data Type Definitions for information on data types.

Example: "SNVT_alarm2"

value

Any valid JSON that matches the type. Or the string "invalid" for an invalid value.

The current value. Matches type.

Datapoints support assignment of prioritized values with the value, prio, and default properties as follows:

A request to assign a new value to the value property is made with the priority chosen with the prio property. An assignment of value=null annuls the value on the selected priority level, and the highest priority value lower than that which was relinquished becomes effective. You can also annul the value of a priority level which is lower (numerically higher) than the currently active level. This annuls the selected value but does not change the actual value, which continues to be governed by the higher priority value.

Users can use priority levels from 1 to 16, where 1 is highest and 16 is the lowest priority. In addition to the numerical priority level selection, the literals “high”, “normal”, and “low” can be used for levels 1, 8, and 16, respectively. 1 to 16 are supported normal priority levels, and 17 is the relinquish default.

When no value of priority 16 or higher is active, the default value takes effect, which is at level 17.

For more information, see Working with Datapoint Values and Working with Unions.

values

Object

Active priority array, read only. For more information, see Working with Datapoint Values and Working with Unions.

Note: The 'inactive" value is depricated in SmartServer IoT v2.80.

values := {
   level: 8,
   levels: {
      "8": 123,
      "12": 0,
      "17": -1
   }
}

presets

Presets is available with SmartServer 2.8 and higher.

Object

(Optional) Presets map.

Datapoint presets allows you to specify preset values for a datapoint. A preset is an optional string that represents a specific native value for a datapoint. The string can be up to 256 characters with allowed spaces and special characters. For example, you might define a preset named ON for an nvoLampSW datapoint (which is defined as an SNVT_switch) as 100.0. You might also define a preset named ON for an nvoHeatSetpoint datapoint (which is of type SNVT_temp_f) to be 22.0.

The presets value has the same structure as the datapoint. If the value does not map to any of the presets, then no preset value is reported. For example, the nvoHeatSetpoint datapoint in the above paragraph only has 2 presets defined. The preset named ON to be 22.0 and OFF to be 80.0. The datapoint value is set to 100.0. In this case there is no corresponding preset that can be mapped to the datapoint value.

The scope for the datapoint presets is per datapoint. This means that each datapoint can have different presets even though they have the same datapoints type.

For example, datapoint #1 and datapoint #2 use SNVT_temp_f, where:

Datapoint #1 can have the presets { {name: “OCCUPIED”, value:69.8}, {name:”UNOCCUPIED”, value:60.8} }.
Datapoint #2 can have the presets { {name:“ON”, value:22.0}, {name:”OFF”, value:99.7} }.

For more information, see Datapoint Presets.

Example:

{
enabled: true
map:[
   {
    name:”OCCUPIED”,
     value:69.80
   },
    {
    name:”UNOCCUPIED”,
     value:60.80
   },
    {
     name:”STANDBY”,
     value:65.00
   }
   ]
}

localization

Localization is available with SmartServer 2.8 and higher.

Object

(Optional) The datapoint localization property contains the localization rules (value) to be used by this datapoint. It contains of the transformation maps for this datapoint. There is only one localization transformation rule specified in a value property for the datapoint. The value property may contain a transformation rule for each field, but only one rule per field. The localization value rules have the same structure as the datapoint.

The scope for the datapoint localization transformation is per datapoint. This means that each datapoint can have different localization transformations even though they have the same datapoints type.

localization can be null or empty. If it is not defined, there is no localization for this datapoint.

For more information, see Datapoint Localization.

Example:

{
value: {
occupied_cool: {
     transformA: 18,
     transformB: -1,
     transformC: 32,
     unit:"deg F"
   },
   standby_cool: {
     transformA: 18,
       transformB: -1,
     transformC: 32,
     unit:"deg F"
   },
   unoccupied_cool: {
     transformA: 18,
       transformB: -1,
     transformC: 32,
     unit:"deg F"
   }
}