From b60285b2abf535c920f1026f8ab6cfc35fa4644f Mon Sep 17 00:00:00 2001 From: Trevor Date: Thu, 13 Jun 2024 14:51:21 -0700 Subject: [PATCH] Minor sub-folder documentation updates (#906) --- README.md | 2 +- docs/specs/subblocks.md | 25 ++++++++++++++----------- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 0a678014fd..6063d77f49 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ management and operation of physical IoT systems. This data is typically exchang with a cloud entity that can maintain a "digital twin" or "shadow device" in the cloud. * [Core UDMI documentation](docs/) for tools and specifications -* [Message schema definition](https://github.com/faucetsdn/udmi/tree/master/schema) with ([_🧬Interactive Viewer_](http://faucetsdn.github.io/udmi/gencode/docs/))) +* [Message schema definition](https://github.com/faucetsdn/udmi/tree/master/schema) with ([_🧬Interactive Viewer_](gencode/docs/)) * [udmi-discuss@googlegroups.com](https://groups.google.com/forum/#!forum/udmi-discuss) email discussion list * Bi-weekly _UDMI Discuss_ video meeting open to all (join the mailing list to get an invite) diff --git a/docs/specs/subblocks.md b/docs/specs/subblocks.md index 70607e0d97..52c052673d 100644 --- a/docs/specs/subblocks.md +++ b/docs/specs/subblocks.md @@ -27,17 +27,18 @@ be ignored if received. If the _subType_ field is missing then it should default (See [pointset event](../../tests/schemas/events_pointset/example.json) as an example.) Messages with a defaulted `event` type represent raw telemetry from the device, while an explicit `event` type means the messages has been processed by the intermediate pipeline in some form. -* `state`: Device state for this subblock. Unlike a - [comprehensive device state message](../../tests/schemas/state/example.json) - this message contains information _only_ for a single subblock. Used for reporting any 'sticky' - state from a device that has been processed and separated out by the UDMIS pipeline. A special - _subFolder_ of `update` indicates a complete state message and should generally be ignored by - consuming applications. -* `config`: A confirmed device config update for this subblock. Unlike a - [comprehensive device config message](../../tests/schemas/config/example.json) - this message contains information _only_ for a single subblock. This message is injected after - the config update has been applied to the device as an effective confirmation of an applied - config change. +* `state`: The 'sticky' state of this device. `state` is idempotent with eventual consistency + semantics. Specifically, that means that any `state` update _completely_ overrides previous ones + (there is no _partial_ `state` update), and intermediate messages may be lost in favor of the + most recent one. Nominally, this will include only the `state` update for a particular `subFolder` + such as pointset, unless the `update` _subFolder_ is applied: + * `update` _subFolder_ ([comprehensive example](../../tests/schemas/state/example.json)): Each top-level + JSON property corresponds to a specific _subFolder_. This use-case is intended for administrative use-cases, + and a more specific _subFolder_ should be utilized whenever possible. + * Other _subFolder_: ([pointset example](../../tests/schemas/state_pointset/example.json)): State for + only the indicated _subFolder_. +* `config`: A confirmed device config update (actually sent to device). Similar to `state`, this is + 'sticky', and can be either _subFolder_ specific or a comprehensive update. * `model`: Model-based description of this device(so does not correspond to any to/from device message). This message is generated by various tools (such as `registrar`) that manipulate the cloud-based provisioning and setup of the device. Generally, this is a live reflection of the @@ -57,3 +58,5 @@ of interest (and values not relevant to any given application should be ignored) * [`discovery`](discovery.md): Raw information from on-prem discovery about on-prem configuration and setup. * `cloud`: How a device is represented or connects to cloud infrastructure (e.g. the authentication key type). +* `update`: This is a synthetic _subFolder_ that is used for `state`/`config` _subType_ that means + _all_ _subFolder_ entries combined together. See discussion above for the `state` and `config` _subTypes_.