Skip to content

Latest commit

 

History

History
62 lines (52 loc) · 4.11 KB

subblocks.md

File metadata and controls

62 lines (52 loc) · 4.11 KB
Raw

UDMI / Docs / Specs / Subblocks

Subblocks API

The Subblocks API defines a high-level interface between UDMI core services and ancillary applications. These messages are similar to those used for device communication, but are Specifically segmented by designated subblocks that partition functionality into atomic chunks. Specifically, the subblock state/config are a limited form of the overall device state/config, and only expose the relevant pieces.

The basic mode of this interface is a "read only" subscription to a PubSub topic (normally udmi_target) that then provides a complete view of updates as they flow through the system. This level of visibility should be sufficient to completely mirror the visible state of the system (barring issues like loss-of-message etc...).

Messages are typed by their subType and subFolder (named so because of legacy integrations). The subType field specifies generic message semantics, while the subFolder specifies the semantic interpretation.

subType attribute values

Several main subType values cover normal system operations. Other values not specified here should be ignored if received. If the subType field is missing then it should default to event.

  • event: Streaming telemetry from the device, representing changes to metrics or other values that change frequently. (See pointset event 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: 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): 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): 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 device's site_model contents.

subFolder attribute values

The subFolder attribute describes the semantic category for the message. There's many potential values for this field (and it can be easily extended), but there are some primary values commonly of interest (and values not relevant to any given application should be ignored).

  • system: High level information about a device as an overall entity, independent of specific functional blocks.
  • pointset: Relating to point (value reading) telemetry and values.
  • gateway: How devices are connected together in a logical structure to proxy information from legacy (non-UDMI) fieldbus protocols.
  • discovery: 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.