pointset.md

UDMI / Docs / Messages / System

Pointset

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

Pointset is represented in four locations:

• Metadata
• Event
• State
• Config

Metadata

• Schema Definition: model_pointset.json (🧬View)
• Working metadata Example

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.

Event

• Schema Definition: events_pointset.json (🧬View)
• Working events_pointset Example

A basic pointset event 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).

Event telemetry messages should be sent "as needed" or according to specific requirements as stipulated in the config block. The basic pointset event 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 and CoV

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

• Schema Definition: state_pointset.json (🧬View interactive)
• Working state Example

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.

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

• 🧬Schema
• Working config Example

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

• 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 specified device point. See writeback documentation.
      • (cov_threshold): Optional threshold for triggering a COV event update.

The points defined in the config.pointset.points dictionary is the authoritative source indicating the representative points for the device (in both event 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 event 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."