udmi

UDMI / Docs / Messages / System

Alarmset

Alarmset Specification

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

Specific alarm_names within a alarmset 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).

Alarmset is represented in four locations:

• Metadata
• Event
• State
• Config

Metadata

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

The metadata.alarmset 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 alarms that a device holds, along with, if the field is numeric, the expected units of those alarms. The general structure of a alarmset block exists inside of a complete metadata message

• alarmset: Top level block designator.
  • alarms: Collection of alarm names.
    • {alarm_name}: Alarm name.
      • units: Expected units designation for this alarm.

Event

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

A basic alarmset event message contains the alarm data sent from a device. The message contains just the top-level alarms designator, while the alarmset typing is applied as part of the message envelope.

• alarms: Collection of alarm names.
  • {alarm_name}: Alarm name.
    • present_value: The specific alarm data reading. If the value represents a number, then this must be serialized as a JSON number, not a quoted string.
• partial_update: Optional indicator if this is an incremental update (not all alarms included).

Event telemetry messages should be sent “as needed” or according to specific requirements as stipulated in the config block. The basic alarmset event message for a device should contain the values for all representative alarms from that device, as determined by the associated config block. If no alarms are specified in the config block, the device programming determines the representative alarms.

Incremental Updates and CoV

Incremental updates (e.g. for COV) can send only the specific updated alarms 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 alarms are not included, without this flag, is considered a validation error.

State

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

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

• alarmset: Top level block designator.
  • alarms: Collection of alarm names.
    • {alarm_name}: Alarm name.
      • (status): Optional status information about this alarm.
      • (value_state): Optional enumeration indicating the state of the alarms value.

In all cases, the alarms 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 alarmset block with the following structure:e

• alarmset: 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.
  • alarms: Collection of alarm names, defining the representative alarm set for this device.
    • {alarm_name}: Alarm name.
      • units: Set as-operating units for this alarm.
      • (set_value): Optional setting to control the specified device alarm. If the set_value represents a number, then this must be serialized as a JSON number, not a quoted string. See writeback documentation.
      • (cov_threshold): Optional threshold for triggering a COV event update.

The alarms defined in the config.alarmset.alarms dictionary is the authoritative source indicating the representative alarms for the device (in both event and state messages). If the device has additional alarms that are not stipulated in the config they should be silently dropped. If the device does not know about a stipulated alarm then it should report it as a alarm 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 alarmset.alarms object, then the device should determine on its own which alarms 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.”

This site is open source. Improve this page.