UDMI / Docs / Specs / Subblocks
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.
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.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.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.