Replace placeholder alarm schema

docs/messages/alarmset.md

@@ -4,9 +4,9 @@
 
 # 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.
+An `alarmset` represents a set of alarms reporting state change events.
 
-Specific `alarm_names` within a `alarmset` should be specified in _snake_case_ and adhere to the
+Specific `alarm_names` within an `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](https://github.com/google/digitalbuildings/tree/master/ontology)).
 
 
@@ -24,89 +24,64 @@ Alarmset is represented in four locations:
 
 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
+expected alarms that a device holds.
+The general structure of an `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](../../schema/events_alarmset.json)
  ([_🧬View_](../../gencode/docs/events_alarmset.html#alarms))
 - [Working `events_alarmset` Example](../../tests/schemas/events_alarmset/example.json)
 
-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](envelope.md).
+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](envelope.md).
 
 * `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).
+    * `active`: Boolean indicating whether or not the alarm is currently active.
+    * `activate_time`: The timestamp of when the alarm most recently became active.
+    * `activate_ack`: Optional details about acknowledgement of the alarm activation.
+    * `return_to_normal_time`: Optional timestamp of when the alarm deactivated.
+    * `return_to_normal_ack`: Optional details about acknowledgement of the alarm returning to normal.
 
-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`](../../gencode/docs/events_alarmset.html#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.
+Alarm event messages should be sent when a configured alarm activates, returns to normal, or is
+acknowledged.
 
 ## State
 
 - **Schema Definition:** [state_alarmset.json](../../schema/state_alarmset.json)
  ([_🧬View interactive_](../../gencode/docs/state.html#alarmset))
 - [Working `state` Example](../../tests/schemas/state/example.json)
 
-The [state](state.md) message from a device contains a `alarmset` block with the following
+The [state](state.md) message from a device contains an `alarmset` block with the following
 structure:
 
 * `alarmset`: Top level block designator.
   * `alarms`: Collection of alarm names.
     * _{`alarm_name`}_: Alarm name.
       * (`status`): Optional [status](status.md) information about this alarm.
-      * (`value_state`): Optional enumeration indicating the
-        [state of the alarms value.](../specs/sequences/writeback.md#value_state)
-
-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](../../gencode/docs/config.html#alarmset)
-- [Working `config` Example](../../tests/schemas/config/writeback.json)
 
-The [config](config.md) message for a device contains a `alarmset`
-block with the following structure:e
+The [config](config.md) message for a device contains an `alarmset`
+block with the following structure:
 
 * `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](../specs/sequences/writeback.md).
-      * (`cov_threshold`): Optional threshold for triggering a COV event update.
+      * `ref`: Reference name of the alarm's internal counterpart.
 
 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,
+If a `config` block is not present, or does not contain an `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."

docs/messages/event.md

@@ -4,7 +4,7 @@
 
 Events can be one of:
 - [Pointset (telemetry)](pointset.md#telemetry) ([_🧬schema_](../../gencode/docs/events_pointset.html))
-- [Alarmset (telemetry)](alarmset.md#telemetry) ([_🧬schema_](../../gencode/docs/events_alarmset.html))
+- [Alarmset](alarmset.md) ([_🧬schema_](../../gencode/docs/events_alarmset.html))
 - [System (logging, etc)](system.md#event) ([_🧬schema_](../../gencode/docs/events_system.html))
 - [Discovery](../specs/discovery.md) ([_🧬schema_](../../gencode/docs/events_discovery.html))
 

docs/messages/readme.md

@@ -11,7 +11,7 @@ Each message has an associated sub block (sometimes called a _subFolder_) that i
 scoping of the message or block:
 
 - [pointset](pointset.md) messages deal with data point telemetry (e.g. temperature reading)
-- [alarmset](alarmset.md) messages deal with alarm point telemetry
+- [alarmset](alarmset.md) messages deal with alarms
 - [system](system.md) messages handle system events such as rebooting, config processing, firmware, etc...
 
 ## Message Types
@@ -52,7 +52,7 @@ See the individual block folder documentation to learn more about those aspects.
 - [state](state.md) ([_🧬schema_](../../gencode/docs/config.html))
 - [event](event.md)
   - [Pointset (telemetry)](pointset.md#telemetry) ([_🧬schema_](../../gencode/docs/events_pointset.html))
-  - [Alarmset (telemetry)](alarmset.md#telemetry) ([_🧬schema_](../../gencode/docs/events_alarmset.html))
+  - [Alarmset](alarmset.md) ([_🧬schema_](../../gencode/docs/events_alarmset.html))
   - [System (logging, etc)](system.md) ([_🧬schema_](../../gencode/docs/events_system.html))
   - [Discovery](../specs/discovery.md) ([_🧬schema_](../../gencode/docs/events_discovery.html))
 - [envelope](envelope.md)

docs/specs/categories.md

@@ -35,6 +35,9 @@ could be used with a **WARNING** level for a warning case during normal operatio
     * _overridden_: (**WARNING**) The reported value has been overridden locally
     * _failure_: (**ERROR**) The system failed to read/write the point
     * _invalid_: (**ERROR**) A `config` parameter for the point is invalid in some way
+* _alarmset_: Handling alarm configuration
+  * _alarm_: Conditions specific to an individual alarm
+    * _invalid_: (**ERROR**) A `config` parameter for the alarm is invalid in some way
 * _localnet_: Aspects of working with various local networks
   * _network_: (**INFO**) Aspects of a specific network
     * _connect_: (**NOTICE**) Connected status of the device on