Migrating event subType to events to keep consistency across MQTT top…

…ics (#856)
faucetsdn · Apr 15, 2024 · 356527b · 356527b
1 parent f10a6f9
commit 356527b
Show file tree

Hide file tree

Showing 212 changed files with 1,316 additions and 1,314 deletions.
diff --git a/.gencode_hash.txt b/.gencode_hash.txt
diff --git a/bin/gencode_root_schemas b/bin/gencode_root_schemas
@@ -15,11 +15,11 @@ import json
 import argparse
 
 # Files to compeltely ignore
-IGNORE_LIST = ['event.json']
+IGNORE_LIST = ['events.json']
 
 # Files to always include as root schema
 # These are sometimes referenced (e.g. by pubber) but should be considered root
-ALWAYS_ROOT = ['configuration_endpoint.json', 'event_system.json']
+ALWAYS_ROOT = ['configuration_endpoint.json', 'events_system.json']
 
 def parse_command_line_args():
   parser = argparse.ArgumentParser()

diff --git a/docs/messages/event.md b/docs/messages/event.md
@@ -3,8 +3,8 @@
 # Events
 
 Events can be one of:
-- [Pointset (telemetry)](pointset.md#telemetry) ([_🧬schema_](../../gencode/docs/event_pointset.html))
-- [System (logging, etc)](system.md#event) ([_🧬schema_](../../gencode/docs/event_system.html))
-- [Discovery](../specs/discovery.md) ([_🧬schema_](../../gencode/docs/event_discovery.html))
+- [Pointset (telemetry)](pointset.md#telemetry) ([_🧬schema_](../../gencode/docs/events_pointset.html))
+- [System (logging, etc)](system.md#event) ([_🧬schema_](../../gencode/docs/events_system.html))
+- [Discovery](../specs/discovery.md) ([_🧬schema_](../../gencode/docs/events_discovery.html))
 
 Events are sent to the `events/<TYPE>` MQTT topic, e.g. `events/pointset` for pointset/telemetry updates
diff --git a/docs/messages/pointset.md b/docs/messages/pointset.md
@@ -34,9 +34,9 @@ The general structure of a `pointset` block exists inside of a complete metadata
 
 ## Event
 
-- **Schema Definition:** [event_pointset.json](../../schema/event_pointset.json)
- ([_🧬View_](../../gencode/docs/event_pointset.html#points))
-- [Working `event_pointset` Example](../../tests/schemas/event_pointset/example.json)
+- **Schema Definition:** [events_pointset.json](../../schema/events_pointset.json)
+ ([_🧬View_](../../gencode/docs/events_pointset.html#points))
+- [Working `events_pointset` Example](../../tests/schemas/events_pointset/example.json)
 
 A basic `pointset` event message contains
 the point data sent from a device. The message contains just the top-level `points` designator,
@@ -57,7 +57,7 @@ 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`](../../gencode/docs/event_pointset.html#partial_update) field to `true` These
+[🧬`partial_update`](../../gencode/docs/events_pointset.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 points are not
 included, without this flag, is considered a validation error.

diff --git a/docs/messages/readme.md b/docs/messages/readme.md
@@ -32,13 +32,13 @@ flow, but also the treatment of the message as it moves through the system:
 |         | __Uplink__  | __Downlink__  |
 |---------|---------|-----------|
 | __Sticky__  | _state_ | _config_  |
-| __Stream__  | _event_ | _command_ |
+| __Stream__  | _events_ | _command_ |
 
 The properties and uses of the four types fall out from this accordingly:
 * _state_: Sticky to the cloud information from the device, including information such as the overall
 status of the device, and any errors or conditions from, e.g., writing points. See
 [IoT Core State Docs](https://cloud.google.com/iot/docs/how-tos/config/getting-state) for more information.
-* _event_: The canonical streaming telemetry messages from the device, usually containing things
+* _events_: The canonical streaming telemetry messages from the device, usually containing things
 like temperature readings or system memory utilization. See
 [IoT Core Event Docs](https://cloud.google.com/iot/docs/how-tos/mqtt-bridge#publishing_telemetry_events) for more information.
 * _config_: Ability to control the behavior of a device, e.g. for key rotation, writeback, etc... See
@@ -54,9 +54,9 @@ See the individual block folder documentation to learn more about those aspects.
 - [config](config.md) ([_🧬schema_](../../gencode/docs/config.html))
 - [state](state.md) ([_🧬schema_](../../gencode/docs/config.html))
 - [event](event.md)
-  - [Pointset (telemetry)](pointset.md#telemetry) ([_🧬schema_](../../gencode/docs/event_pointset.html))
-  - [System (logging, etc)](system.md) ([_🧬schema_](../../gencode/docs/event_system.html))
-  - [Discovery](../specs/discovery.md) ([_🧬schema_](../../gencode/docs/event_discovery.html))
+  - [Pointset (telemetry)](pointset.md#telemetry) ([_🧬schema_](../../gencode/docs/events_pointset.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)
 
 ## MQTT Topics

diff --git a/docs/messages/status.md b/docs/messages/status.md
@@ -9,11 +9,11 @@ follow the same structure.
   “device disconnected”.
     - [🧬Pointset Status](../../gencode/docs/state.html#pointset_points_pattern1_status) 
     - [🧬System Status](../../gencode/docs/state.html#system_status)
-- [🧬Logentry events](../../gencode/docs/event_system.html#logentries) are transitory event that
+- [🧬Logentry events](../../gencode/docs/events_system.html#logentries) are transitory event that
   happen, e.g. “connection failed”.
 
 ## Example
 
 The working examples below demonstrate `status` and `logentries` fields in different message types:
 - `state`(../../tests/schemas/state/example.json)
-- `event_system`(../../tests/schemas/event_system/example.json)
+- `events_system`(../../tests/schemas/events_system/example.json)
diff --git a/docs/messages/system.md b/docs/messages/system.md
@@ -15,9 +15,9 @@ Primarily used for things like logging, general status, firmware management, etc
 
 ## Event
 
-- **Schema Definition:** [event_system.json](../../schema/event_system.json)
- ([_🧬View_](../../gencode/docs/event_system.html))
-- [Working `event_system` Example](../../tests/schemas/event_system/example.json)
+- **Schema Definition:** [events_system.json](../../schema/events_system.json)
+ ([_🧬View_](../../gencode/docs/events_system.html))
+- [Working `events_system` Example](../../tests/schemas/events_system/example.json)
 
 ## Metadata
 

diff --git a/docs/specs/discovery.md b/docs/specs/discovery.md
@@ -16,8 +16,8 @@ information about how the device is indexed in the world around it.
 information intrinsic to a device and the capabilities it provides.
 
 Backend services will receive a streaming set of
-[_discovery enumeration messages_](../../tests/schemas/event_discovery/enumeration.json) that
-follow the appropriate [_discovery event schema_](../../gencode/docs/event_discovery.html).
+[_discovery enumeration messages_](../../tests/schemas/events_discovery/enumeration.json) that
+follow the appropriate [_discovery event schema_](../../gencode/docs/events_discovery.html).
 
 ## Sequence Diagram
 
@@ -84,7 +84,7 @@ scan (_scan_ enumeration). Both report the same kind of content, but the mechani
 Within an enumeration message, there's a number of different kinds of information that can
 be reported:
   * `points`: A listing of all the data points that a device has to offer. The normal
-  `pointset` _config_/_state_/_event_ messages only operate on a curated subset of all
+  `pointset` _config_/_state_/_events_ messages only operate on a curated subset of all
   the available points, while this enumeration lists _all_ of them.
   * `blobs`: A listing of all the data blobs that a device knows how to handle. This could
   be components like firmware updates, key rotation, etc... Some blobs will be standardized

diff --git a/docs/specs/gateway.md b/docs/specs/gateway.md
@@ -59,7 +59,7 @@ are a large number of devices.
 Any attach errors, e.g. the gateway can not successfully attach to the target
 device, should be reported in the [`gateway` _block_](../../gencode/docs/state.html#gateway) of the [state](../messages/state.md) message
 
-A [_🧬logentry_](../../gencode/docs/event_system.html#logentries)) message should be used to detail
+A [_🧬logentry_](../../gencode/docs/events_system.html#logentries)) message should be used to detail
 the nature of the problem. If the gateway can attach successfully, any other errors, e.g. the
 inability to communicate with the device over the local network, should be indicated as part of the
 proxy device status block.
@@ -115,7 +115,7 @@ message.
 
 [Telemetry](../messages/pointset.md#telemetry) is handled similarly, with the gateway responsible for
 proxying data from local devices through to UDMI. In many cases, this would be translating specific
-device points into a [_pointset_ message](../../tests/schemas/event_pointset/example.json).
+device points into a [_pointset_ message](../../tests/schemas/events_pointset/example.json).
 
 ### metadata
 

diff --git a/docs/specs/mapping.md b/docs/specs/mapping.md
@@ -49,16 +49,16 @@ sequenceDiagram
 
 1. *(Fieldbus Discovery)* scan for fieldbus _device_ information from devices (e.g. BACnet, format out of scope for UDMI):
   * "I am device `78F936` with points { `room_temp`, `step_size`, and `operation_count` }"
-2. **[Discovery Events](../../tests/schemas/event_discovery/enumeration.json)** wraps the device info from the discovery
+2. **[Discovery Events](../../tests/schemas/events_discovery/enumeration.json)** wraps the device info from the discovery
    into a UDMI-normalized format, e.g.:
   * "Device `78F936` has points { }, with a public key `XYZZYZ`"
 3. **[Mapping Config](../../tests/schemas/config_mapping/mapping.json)** from the _agent_ indicates that the _mapper_ should export responses.
-3. **[Mapping Events](../../tests/schemas/event_mapping/mapping.json)** from the _mapper_ contain actual calculated point mappings:
+3. **[Mapping Events](../../tests/schemas/events_mapping/mapping.json)** from the _mapper_ contain actual calculated point mappings:
   * "Device `78F936` is an `AHU` called `AHU-183`, and `room_temp` is really a `flow_temperatue`"
-3. **[Mapping Command](../../tests/schemas/command_mapping/mapping.json)** to the _mapper_ contain results of initial provisioning:
+3. **[Mapping Command](../../tests/schemas/commands_mapping/mapping.json)** to the _mapper_ contain results of initial provisioning:
   * "Device `78F936` has a numerical id `2198372198752`
 4. *(Onboard Info)* are sent to the _pipeline_ to onboard a device (contents are defined by _pipeline_ and out of scope for UDMI).
-8. **[Telemetry Events](../../tests/schemas/event_pointset/example.json)** are data events from _device_ to _pipeline_... business as usual:
+8. **[Telemetry Events](../../tests/schemas/events_pointset/example.json)** are data events from _device_ to _pipeline_... business as usual:
   * "I am `AHU-183`, and my `room_temp` is `73`"
 
 ## Example Test Setup

diff --git a/docs/specs/sequences/discovery.md b/docs/specs/sequences/discovery.md
@@ -30,8 +30,8 @@ Depending on the system, this might encompass a number of different network prot
   by the `generation` timestamp (defined, not-the-same as the previous scan generation, and after the device's last start time).
 * [_start state_](../../../tests/schemas/state/discovery.json): Indicates the device is actively
   scanning, with `generation` should match that of _config_, and the `active` as `true`.
-* [_discovery event_](../../../tests/schemas/event_discovery/discovery.json): Streaming results
-  for scanned devices (keyed by matching `generation` field): one _event_ for each unique device scanned.
+* [_discovery events_](../../../tests/schemas/events_discovery/discovery.json): Streaming results
+  for scanned devices (keyed by matching `generation` field): one _events_ for each unique device scanned.
 * [_stop state_](../../../tests/schemas/state/scan_stop.json): Once complete, the _active_ field is `false`
   (or removed). Ideally the `generation` field would remain to indicate the last scan performed.
 
@@ -62,7 +62,7 @@ or transient BACnet traffic.
 * [_start config_](../../../tests/schemas/config/continuous.json): There is no `generation` marker, since
   scanning is always happening. The `scan_interval_sec` triggers the capability (see below).
 * [_start state_](../../../tests/schemas/state/continuous.json): Indicates that scanning is `active`, but no `generation`.
-* [_discovery event_](../../../tests/schemas/event_discovery/continuous.json): Events as per normal, except no `generation`.
+* [_discovery events_](../../../tests/schemas/events_discovery/continuous.json): Events as per normal, except no `generation`.
 
 For this case, there is no _stop state_ message since the scan never stops: The process silently stops when the
 `scan_interval_sec` parameter is removed from the config. Additionally, the `scan_interval_sec` field indicates the
@@ -80,11 +80,11 @@ and can be explicitly directed to enumerate itself. This also applies to all dir
   block starts the self enumeration process (rather than the `discovery` block).
 * [_start state_](../../../tests/schemas/state/enumeration.json): The `system` block indicates the `generation`
   of enumeration that is currently being processed.
-* [_discovery event_](../../../tests/schemas/event_discovery/enumeration.json): The results do not have a `family` block,
+* [_discovery events_](../../../tests/schemas/events_discovery/enumeration.json): The results do not have a `family` block,
   rather, the device id is determined from the envelope's `deviceId` field.
 
 With self enumeration there is no specific _stop state_, as the system deterministically sends a single device's
-_discovery event_ corresponding to the _config_ trigger.
+_discovery events_ corresponding to the _config_ trigger.
 
 ## Scan Enumeration
 
@@ -95,7 +95,7 @@ then automatically enumerates each device encountered.
 * [_start config_](../../../tests/schemas/config/implicit.json): Initiates the scan, along with an added
   `enumerate` field indicating that the system should enumerate each device it encounters.
 * [_start state_](../../../tests/schemas/state/discovery.json): Same as base scan case.
-* [_discovery event_](../../../tests/schemas/event_discovery/implicit.json): Same as _scan_ result, except
+* [_discovery events_](../../../tests/schemas/events_discovery/implicit.json): Same as _scan_ result, except
   includes enumeration fields (typically discovered `points`).
 * [_stop state_](../../../tests/schemas/state/scan_stop.json): Same as base scan case.
 
@@ -107,7 +107,7 @@ There's different ways to report errors, depending on the scope of the error.
 potentially affecting all _devices_ or points during a scan.
 * [_self error_](../../../tests/schemas/state/enumeration.json): Details status while processing _self_ enumeration
   that potentially affects all _points_.
-* [_point error_](../../../tests/schemas/event_discovery/point_error.json): Details how an _individual_ point error
+* [_point error_](../../../tests/schemas/events_discovery/point_error.json): Details how an _individual_ point error
   should be reported during (_self_ or _scan_) enumeration.
-* [_scan enumeration error_](../../../tests/schemas/event_discovery/scan_error.json): Details how a _scan_ enumeration
+* [_scan enumeration error_](../../../tests/schemas/events_discovery/scan_error.json): Details how a _scan_ enumeration
   error that affects all points should be reported (i.e. while trying to enumerate the scanned device).
diff --git a/docs/specs/subblocks.md b/docs/specs/subblocks.md
@@ -24,7 +24,7 @@ different sources:
   static set of files somewhere.
 * **Event**: Streaming telemetry. This is essentially a raw feed from the device itself,
   and will always be segmented by subblock (e.g. for a
-  [pointset event](../../tests/schemas/event_pointset/example.json)). Streaming telemetry
+  [pointset event](../../tests/schemas/events_pointset/example.json)). Streaming telemetry
   is sent from the device, so will be _received by_ a client app.
 * **State**: Device state for this subblock. Unlike a
   [comprehensive device state message](../../tests/schemas/state/example.json)
@@ -39,7 +39,7 @@ different sources:
 
 In all cases, the _Subblock API_ messages encode the relevant subblock ID { pointset, discovery, ... }
 in the [message envelope's](../../tests/schemas/envelope/example.json) _subFolder_ field.
-The _subType_ field encodes the relevant type { _event_, _config_, _state_, _model_ }.
+The _subType_ field encodes the relevant type { _events_, _config_, _state_, _model_ }.
 
 ## System
 
@@ -56,7 +56,7 @@ the device-to-cloud connection.
 
 * [**Model**](../../tests/schemas/model_pointset/example.json): Expected model for what the device should
   be reporting.
-* [**Event**](../../tests/schemas/event_pointset/example.json): Streaming telemetry events from the device
+* [**Event**](../../tests/schemas/events_pointset/example.json): Streaming telemetry events from the device
   containing the actual data points.
 * [**State**](../../tests/schemas/state_pointset/example.json): State of the device points, indicating any
   sticky errors or status of any cloud-to-device config.

diff --git a/docs/specs/tech_stack.md b/docs/specs/tech_stack.md
@@ -30,7 +30,7 @@ For GCP implementations the full topic would be `/devices/{device_id}/{suffix}`
 Any backend system (in a GCP project) should adhere to the following guidelines:
 * All messages to/from the devices should conform to the UDMI schema payloads (pass validation).
 * All exchanges with the devices should go through a PubSub topic:
-  * The _state_ and _event_ messages are published to a topic configured through the IoT Core registry.
+  * The _state_ and _events_ messages are published to a topic configured through the IoT Core registry.
   * If necessary, any _config_ or _command_ messages should go through a PubSub topic, and then converted to the requisite Cloud IoT
   config write using a simple cloud function.
 

diff --git a/docs/specs/validation.md b/docs/specs/validation.md
@@ -13,12 +13,12 @@ seen, or never seen, etc...). This capability is an extension of the basic
 
 The validation agent runs autonomously, consumes messages, and injects _result_ or _report_ messages as needed.
 All validation messages are defined by the
-[validation event schema](../../schema/event_validation.json)([_🧬View_](../../gencode/docs/event_validation.html)).
+[validation event schema](../../schema/events_validation.json)([_🧬View_](../../gencode/docs/events_validation.html)).
 and
 [validation state schema](../../schema/state_validation.json)([_🧬View_](../../gencode/docs/state_validation.html)).
 schema, and are instantiated in two flavors:
 
-* _result_: Validation results for an individual device [example](../../tests/schemas/event_validation/simple_ok.json).
+* _result_: Validation results for an individual device [example](../../tests/schemas/events_validation/simple_ok.json).
 * _report_: Validation report for an entire site [example](../../tests/schemas/state_validation/report.json).
 
 ## Message Channel

diff --git a/docs/tools/validator.md b/docs/tools/validator.md
@@ -135,8 +135,8 @@ Caused by: java.io.IOException: The Application Default Credentials are not avai
 - Ensure the validator tools are not running under `sudo`
 
 ```
-Processing device #1/12: XXX-1/event_unknown
-Unknown schema subFolder 'event_unknown' for XXX-1
+Processing device #1/12: XXX-1/events_unknown
+Unknown schema subFolder 'events_unknown' for XXX-1
 ```
 - Ensure the subscription used for the validator is to the `udmi_target` topic,
   and not the `udmi_state` topic or any others

diff --git a/etc/schema.out b/etc/schema.out
@@ -1,10 +1,10 @@
 RESULT pass schemas device_state_alpha ALPHA 5/5 Schema validation passed
 RESULT pass schemas device_state_beta BETA 5/5 Schema validation passed
 RESULT pass schemas device_state_stable STABLE 5/5 Schema validation passed
-RESULT pass schemas event_pointset_beta BETA 5/5 Schema validation passed
-RESULT pass schemas event_system_alpha ALPHA 5/5 Schema validation passed
-RESULT pass schemas event_system_beta BETA 5/5 Schema validation passed
-RESULT pass schemas event_system_stable STABLE 5/5 Schema validation passed
+RESULT pass schemas events_pointset_beta BETA 5/5 Schema validation passed
+RESULT pass schemas events_system_alpha ALPHA 5/5 Schema validation passed
+RESULT pass schemas events_system_beta BETA 5/5 Schema validation passed
+RESULT pass schemas events_system_stable STABLE 5/5 Schema validation passed
 RESULT pass schemas state_update_alpha ALPHA 5/5 Schema validation passed
 RESULT pass schemas state_update_beta BETA 5/5 Schema validation passed
 RESULT pass schemas state_update_stable STABLE 5/5 Schema validation passed