This page discusses values of both regular and configuration datapoints.  See also Working with Unions.

Regular Datapoints and Configuration Datapoints

A regular datapoint is one that does not implement a configuration datapoint. Regular datapoints report property: false (the default is false), while a configuration datapoint reports property: true.

Regular datapoints support features not available with configuration datapoints, such as optional prioritized override values.

Actual Value

Every datapoint has an actual value. The actual value is obtained from the edge device with datapoint monitoring, on-demand datapoint “get” requests, or certain types of datapoint connections.

The actual value is generally available only once the device has been provisioned.

When an actual value is obtained for an output datapoint, the actual value is copied into the normal value.  When an actual value is obtained for an input datapoint, the actual value is copied to the normal value if no override is active.

Datapoint monitoring and on-demand datapoint reading requests report the actual value.

Datapoint connections implemented as peer-to-peer connections use the actual value, and datapoint connections implemented as point-to-point connections use the present value.

Present Value

The present value is the desired value.  For a regular datapoint, the present value is computed from the 16 override levels and the normal value level. The present value is the value of the highest active priority level among those 17 levels.

For property datapoints, the present value is the normal value.

Feedback includes the value property, which reports the present value.

Normal Value

The normal value becomes the present value when no override is active. For configuration datapoints, the normal value is always the present value. For regular datapoints, the normal value uses priority level 17, the lowest priority.

The normal value always has a value. It cannot be relinquished or de-activated. Doing so yields an error and preserves the existing value without change.  The normal value has an initial normal value obtained from the device, or from an explicit designated default value, if available.

A normal value can be assigned by writing the value without a priority level identifier prio, or by writing the value together with prio: 17.

Feedback for regular datapoints includes the values map, which includes the normal value at priority level 17.

Default Value

Some datapoints support an optional, explicit default value, accessible with the default property.

Such a default value plays no role in calculating the present value, but it is used to derive an initial normal value. The default value is typically used to return configuration datapoints to their original state, and can be used in context with other APIs to manage the configuration of complete interface blocks or devices.

Override Values and Priorities

Regular datapoints support 16 optional override values, one for each of 16 priorities numbered 1 to 16, where priority 1 is the highest and 16 is the lowest priority.

Override values can be defined and relinquished, which renders them inactive and removes the previous value definition.

IAP does not stipulate a specific interpretation of priorities 1 to 16, but the following are suggested:

• 1: Manual Life Safety
• 2: Automatic Life Safety
• 5: Critical Equipment
• 8: Manual Operator

Priority 17 is reserved for use with the normal value. The normal value cannot be deactivated or relinquished. When priorities are labeled within a user interface, this label is recommended:

• 17: Normal

Creating an Override Value

To create an override value, specify the desired value and the desired priority with one request. The same method is used to change the override defined at the same level:

To deactivate the value at priority 8, set the active flag to false as shown in this example:

To re-activate the priority 8 override, set the active flag to true:

To deactivate and delete the priority 8 override, set the value to null:

Both prio and active are write-only properties, which means they are used explicitly in an assignment request within the request channel, but are not explicitly reported within the feedback channel.

Feedback reports the complete values map, which shows all active and inactive overrides and the current priority. The present value can always be obtained from the values map, and is also presented with the value property.

The following example shows the values and value properties of a datapoint object. Note that neither prio nor active are explicitly reported in the feedback:

Note that JSON encoding requires that keys are strings. Therefore, the levels object within the values map specifies the keys as strings even though keys report numeric priorities.

For example, the JSON-encoded version of the values map shown above will be as shown below. Note that JSON requires the use of neutral double quotes.

Values are Atomic

All value objects associated with normal, actual, present, default, or override values are considered atomic. Writing a partial value object or addressing fewer than all fields within a datapoint value object is not supported.

Property Datapoints

Property datapoints behave like regular datapoints, but do not support 16 overrides. Their feedback does not include a values map. A property datapoint has a normal value. The present value always equals the normal value, and is reported in feedback with the value property.

The normal value can be addressed without an explicit priority level indication or with priority level 17. Addressing any other priority level yields an error.