Datapoint Monitor

Datapoints can be monitored by an IAP server so that the server can maintain a snapshot of the current state of all monitored datapoints. This snapshot can be used to quickly get the current state for a set of datapoints to be displayed on a web page, to be analyzed by an analytics application, or to be evaluated for a control application.

Datapoint values can be periodically polled, or can be received by event-driven delivery for protocols that support event-driven updates. 

URI Definition

Method       

URI and Fields

GET/iap/devs/{id}/if/{block}/{block_index}/{datapoint_name}/monitor

Returns the monitoring configuration for the specified datapoints. 

The following fields are returned: 

rateRequested monitoring rate for the specified datapoint. The value can be "none", "slow", "normal", "fast", "auto", or a number representing the requested monitoring interval, in seconds. Defaults to "slow" for non-property output datapoints, and "none" for property datapoints and input datapoints. If "slow", "normal", "fast", or a number is specified the edge protocol processor chooses an appropriate rate based the edge protocol, aggregate polling activity, and available resources. The "auto" setting requests the edge protocol processor to capture values automatically without frequent and periodic polling. The method used depend on the edge protocol. For example, for LON output datapoints, the LON protocol processor creates a LON connection to the protocol processor if possible.

report

Reporting mode. The value can be "any", "change", "threshold-any", or "threshold-all". In "any" change reporting mode, every received update that meets throttle and threshold conditions is reported. In "change" reporting mode, only changes from the last reported value, and that meet throttle and threshold conditions, are reported. In "threshold-any" reporting mode, every received update that meets throttle and at least one of the threshold conditions is reported. In "threshold-all" reporting mode, every received update that meets throttle and all of the threshold conditions is reported.

If report is not specified, it defaults to "change".

throttle

Minimum interval between value reports. A 0 (zero) or undefined value disables throttling. A non-zero, positive number enables throttling, in units of seconds. A throttle of X seconds means that a captured value that meets the report and threshold conditions is only reported if the most recently reported value was reported at least X seconds earlier. The throttle does not postpone data reports. For example, with a rate of 10 seconds and a throttle of 15 seconds, when all other criteria are met, if captured value A occurs at t=0 seconds, B at t=10, C at t=20, and so on, value B will not be reported because A has been reported less than 15 seconds ago. Value C will be reported because the throttle has expired since the most recently reported value A. However, value B will not be reported at t=15 seconds after A; the throttle setting of 15 seconds means that value B is ignored and A remains the most recently published value (at t=0). 

If throttle is not specified, it defaults to "0" to disable the throttle.

threshold      Minimum absolute difference between a captured value and the most recently reported value to qualify for reporting. A 0 (zero) or undefined value disables threshold filtering. A non-zero value defines the minimum value difference between two published values. For example if A, B, and C values are captured at t=0, 10, and 20 seconds with values 100, 75, 150, and a threshold of 30, value A is reported because there is no history. Value B is ignored because abs(75-100) < 30. Value C is permitted because abs(150-100) >= 30. For datapoints with structured values, the threshold value is specified as an object that mirrors the datapoint value, with threshold values for each scalar field. A threshold value cannot be specified for any string fields. Thresholds are always unsigned numbers as they define the unsigned (absolute) difference between the current and the most recently reported value.

focus

Specifies a field within a structured value to be used for evaluating throttlereport, and threshold specifications. Nested fields within a structure are specified as a path with slashes ("/") separating the nested field names. When a focus is specified, all reporting and all evaluations of throttlereport, and threshold specifications ignore all except for the property in focus. The resultant data report only contains the focussed field. For example, focus = "speed" examines and reports only the speed field from a structure with a top-level field named "speed". A focus = "point/z" setting examines and reports only the z coordinate within a point field.

XIFname vs Instance Name

  • The block path element uses the block XIFname.
  • The datapoint_name path element uses the datapoint instance name.

Path Parameters

The optional path parameters for the id, block, block_index, and datapoint_name path elements are listed on the Path Parameters page.

PUT

/iap/devs/{id}/if/{block}/{block_index}/{datapoint_name}/monitor

Updates the monitoring configuration for the specified datapoints.

The following fields are returned:

rateRequested monitoring rate for the specified datapoint. The value can be "none", "slow", "normal", "fast", "auto", or a number representing the requested monitoring interval, in seconds. Defaults to "slow" for non-property output datapoints, and "none" for property datapoints and input datapoints. If "slow", "normal", "fast", or a number is specified the edge protocol processor chooses an appropriate rate based the edge protocol, aggregate polling activity, and available resources. The "autosetting requests the edge protocol processor to capture values automatically without frequent and periodic polling. The method used depend on the edge protocol. For example, for LON output datapoints, the LON protocol processor creates a LON connection to the protocol processor if possible.

report

Reporting mode. The value can be "any", "change", "threshold-any", or "threshold-all". In "any" change logging mode, every received update that meets throttle and threshold conditions is reported. In "change" reporting mode, only changes from the last reported value, and that meet throttle and threshold conditions, are reported. In "threshold-any" reporting mode, every received update that meets throttle and at least one of the threshold conditions is reported. In "threshold-all" reporting mode, every received update that meets throttle and all of the threshold conditions is reported.

If report is not specified, it defaults to "change".

throttle

Minimum interval between value reports. A 0 (zero) or undefined value disables throttling. A non-zero, positive number enables throttling, in units of seconds. A throttle of X seconds means that a captured value that meets the report and threshold conditions is only reported if the most recently reported value was reported at least X seconds earlier. The throttle does not postpone data reports. For example, with a rate of 10 seconds and a throttle of 15 seconds, when all other criteria are met, if captured value A occurs at t=0 seconds, B at t=10, C at t=20, and so on, value B will not be reported because A has been reported less than 15 seconds ago. Value C will be reported because the throttle has expired since the most recently reported value A. However, value B will not be reported at t=15 seconds after A; the throttle setting of 15 seconds means that value B is ignored and A remains the most recently published value (at t=0). 

If throttle is not specified, it defaults to "0" to disable the throttle.

threshold      

Minimum absolute difference between a captured value and the most recently reported value to qualify for reporting. A 0 (zero) or undefined value disables threshold filtering. A value greater than zero defines the minimum value difference between two published values. For example, if A, B and C values are captured at t=0, 10, and 20 seconds with values 100, 75, 150, and a threshold of 30, value A is reported because there is no history. Value B is ignored because abs(75-100) < 30. Value C is permitted because abs(150-100) >= 30. For datapoints with structured values, the threshold value is specified as an object that mirrors the datapoint value, with threshold values for each scalar field. A threshold value cannot be specified for any string fields. Thresholds are always unsigned numbers as they define the unsigned (absolute) difference between the current and the most recently reported value.

focus

Specifies a field within a structured value to be used for evaluating throttlereport, and threshold specifications. Nested fields within a structure are specified as a path with slashes ("/") separating the nested field names. When a focus is specified, all reporting and all evaluations of throttlereport, and threshold specifications ignore all except for the property in focus. The resultant data report only contains the focussed field. For example, focus = "speed" examines and reports only the speed field from a structure with a top-level field named "speed". A focus = "point/z" setting examines and reports only the z coordinate within a point field.

XIFname vs Instance Name

  • The block path element uses the block XIFname.
  • The datapoint_name path element uses the datapoint instance name.

Path Parameters

The optional path parameters for the id, block, block_index, and datapoint_name path elements are listed on the Path Parameters page.

DELETE


/iap/devs/{id}/if/{block}/{block_index}/{datapoint_name}/monitor

Disables monitoring for the specified datapoints. Sets all log specification fields to defaults, including "none" for the rate.

XIFname vs Instance Name

  • The block path element uses the block XIFname.
  • The datapoint_name path element uses the datapoint instance name.

Path Parameters

The optional path parameters for the id, block, block_index, and datapoint_name path elements are listed on the Path Parameters page.

Queries

You can include queries with your IAP/REST request to specify a selection rule for your request.  As described in Queries and Parameters, you can specify a query as a query parameter  appended to the end of your URI preceded with a "?" character, or as a path parameter within a path element of the path component.

The optional path parameters for the id, block, block_index, and datapoint_name path elements are listed on the Path Parameters page.