Skip to content

Latest commit

 

History

History
90 lines (70 loc) · 5.13 KB

pointset.md

File metadata and controls

90 lines (70 loc) · 5.13 KB
Raw

Pointset Specification

A pointset represents a set of points reporting telemetry data. This is the most common data, and should be stored in an appropriate time-series database.

Specific point_names within a pointset should be specified in snake_case and adhere to the data ontology for the device (stipulated and verified outside of UDMI, e.g. Digital Buildings Ontology).

Metadata

The metadata.pointset subblock represents the abstract system expectation for what the device should be doing, and how it should be configured and operated. This block specifies the expected points that a device holds, along with, if the field is numeric, the expected units of those points. The general structure of a pointset block exists inside of a complete metadata message.

  • pointset: Top level block designator.
    • points: Collection of point names.
      • {point_name}: Point name.
        • units: Expected units designation for this point.

Telemetry

A basic pointset telemetry message contains the point data sent from a device. The message contains just the top-level points designator, while the pointset typing is applied as part of the message envelope.

  • points: Collection of point names.
    • {point_name}: Point name.
      • present_value: The specific point data reading.
  • partial_update: Optional indicator if this is an incremental update (not all points included).

Telemetry update messages should be sent "as needed" or according to specific requirements as stipulated in the config block. The basic pointset telemetry message for a device should contain the values for all representative points from that device, as determined by the associated config block. If no points are specified in the config block, the device programming determines the representative points.

Incremental updates (e.g. for COV) can send only the specific updated points as an optimization, while setting the top-level partial_update field to true. These messages may be indiscriminately dropped by the backend systems, so a periodic full-update must still be sent (as per sample_rate_sec below). Sending an update where all expected points are not included, without this flag, is considered a validation error.

State

The state message from a device contains a pointset block with the following structure:

  • pointset: Top level block designator.
    • points: Collection of point names.
      • {point_name}: Point name.
        • (status): Optional status information about this point.
        • (value_state): Optional enumeration indicating the state of the points value.

Valid value_state settings include:

  • : No set_value config has been specified, the source is device-native.
  • applied: The set_value config has been successfully applied.
  • overridden: The config setting is being overridden by another source.
  • invalid: A problem has been identified with the config setting.
  • failure: The config is fine, but a problem has been encountered applying the setting.

In all cases, the points status field can be used to supply more information (e.g., the reason for an invalid or failure value_state).

Config

The config message for a device contains a pointset block with the following structure:

  • pointset: Top level block designator.
    • sample_rate_sec: Maximum time between samples for the device to send out a complete update. It can send out updates more frequently than this.
    • sample_limit_sec: Minimum time between sample updates for the device (including complete and COV updates). Updates more frequent than this should be coalesced into one update.
    • points: Collection of point names, defining the representative point set for this device.
      • {point_name}: Point name.
        • units: Set as-operating units for this point.
        • (set_value): Optional setting to control the specificed device point. See writeback documentation.
        • (cov_threshold): Optional threshold for triggering a COV telemetry update.

The points defined in the config.pointset.points dictionary is the authoritative source indicating the representative points for the device (in both telemetry and state messages). If the device has additional points that are not stipulated in the config they should be silently dropped. If the device does not know about a stipulated point then it should report it as a point with an error level status entry in its state message, and exclude it from the telemetry message. If a config block is not present, or does not contain a pointset.points object, then the device should determine on its own which points to report.

If sample_rate_sec is not defined (or zero), then the system is expected to send an update at least every 300 seconds (5 minutes as a default value). A negative value would mean "don't send updates."