Minor sub-folder documentation updates (#906)

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/))
 * [[email protected]](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)
 

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