UDMI Schema

The Universal Device Management Interface (UDMI) provides a high-level specification for the management and operation of physical IoT systems. This data is typically exchanged with a cloud entity that can maintain a "digital twin" or "shadow device" in the cloud. Please join the udmi-discuss@googlegroups.com mailing list for questions and discussion.

By design, this schema is intended to be:

Universal: Apply to all subsystems in a building, not a singular vertical solution.
Device: Operations on an IoT device, a managed entity in physical space.
Management: Focus on device management, rather than command & control.
Interface: Define an interface specification, rather than a client-library or RPC mechanism.

See the associated UDMI Tech Stack for details about transport mechanism outside of the core schema definition. Nominally meant for use with Googe's Cloud IoT Core, it can be applied to any set of data or hosting setup.

Recommended Workflow

The recommended workflow for UDMI covers using the registrar and validator tools to configure and test a cloud project. Additionally, the pubber tool is instrumental in setting up and testing the system independent of actual device setup.

Use Cases

The essence behind UDMI is an automated mechanism for IoT system management. Many current systems require direct-to-device access, such as through a web browser or telnet/ssh session. These techniques do not scale to robust managed ecosystems since they rely too heavily on manual operation (aren't automated), and increase the security exposure of the system (since they need to expose these management ports).

UDMI is intended to support a few primary use-cases:

Telemetry Ingestion: Ingest device data points in a standardized format.
Gateway Proxy: Proxy data/connection for non-UDMI devices, allowing adaptation to legacy systems.
On-Prem Actuation: Ability to effect on-prem device behavior.
Device Testability: e.g. Trigger a fake alarm to test reporting mechanisms.
Commissioning Tools: Streamline complete system setup and install.
Operational Diagnostics: Make it easy for system operators to diagnose basic faults.
Status and Logging: Report system operational metrics to hosting infrastructure.
Key Rotation: Manage encryption keys and certificates in accordance with best practice.
Credential Exchange: Bootstrap higher-layer authentication to restricted resources.
Firmware Updates: Initiate, monitor, and track firmware updates across an entire fleet of devices.
On-Prem Discovery: Enumerate any on-prem devices to aid setup or anomaly detection.

All these situations are conceptually about management of devices, which is conceptually different than the control or operation. These concepts are similar to the management, control, and data planes of Software Defined Networks. Once operational, the system should be able to operate completely autonomoulsy from the management capabilities, which are only required to diagnose or tweak system behavior.

Design Philosophy

In order to provide for management automation, UDMI strives for the following principles:

Secure and Authenticated: Requires a properly secure and authenticated channel from the device to managing infrastructure.
Declarative Specification: The schema describes the desired state of the system, relying on the underlying mechanisms to match actual state with desired state. This is conceptually similar to Kubernetes-style configuration files.
Minimal Elegant Design: Initially underspecified, with an eye towards making it easy to add new capabilities in the future. It is easier to add something than it is to remove it.
Reduced Choices: In the long run, choice leads to more work to implement, and more ambiguity. Strive towards having only one way of doing each thing.
Structure and Clarity: This is not a "compressed" format and not designed for very large structures or high-bandwidth streams.
Property Names:Uses snake_case convention for property names.
Resource Names: Overall structure (when flattened to paths), follows the API Resource Names guidline.

Subsystem Blocks

UDMI provides a means to multiplex multiple functional subsystems through the same shared communication channel. There are a number of subsystems that make up the core UDMI spec:

Core system messages about the base device itself.
Device pointset for device telemetry organized by points.
Optional gateway functionality for proxying device/MQTT connections.
Local discover for discovering device and network capabilities.

Schema Structure

Schemas are broken down into several top-level sub-schemas that are invoked for different aspects of device management:

Device metadata (example) stored in the cloud about a device, but not directly available to or on the device, defined by metadata.json. This is essentially a specification about how the device should be configured or expectations about what the device should be doing.
Message envelope (example) for server-side attributes of received messages, defined by envelope.json. This is automatically generated by the transport layer and is then available for server-side processing.
Streaming device telemetry, which can take on several different forms, depending on the intended use, e.g.:
Device state (example), sent from device to cloud, defined by state.json. There is one current state per device, which is considered sticky until a new state message is sent. is comprised of several subsections (e.g. system or pointset) that describe the relevant sub-state components.
Device config (example), passed from cloud to device, defined by config.json. There is one active config per device, which is considered current until a new config is received.

A device client implementation will typically only be aware of the state, config, and one or more telemetry messages (e.g. pointset), while all others are meant for the supporting infrastructure.

Metadata Registration and Validation

Using UDMI on a project entails not only the base device and server implementations, but also properly registering and validating device configuration. The registrar tool and validator tool provide a means to configure and check site installations, respectively.

State Message

See notes below about 'State status' fields.
There is an implicit minimum update interval of one second applied to state updates, and it is considered an error to update device state more often than that. If there are multiple state updates from a device in under a second they should be coalessed into one update (sent after an appropriate backoff timer) and not buffered (sending multiple messages).
last_config should be the timestamp from the timestamp field of the last successfully parsed config message (not the timestamp the message was received/processed).

Config Message

sample_rate_sec: Sampling rate for the system, which should proactively send an update (e.g. pointset, logentry, discover message) at this interval.
sample_limit_sec: Minimum time between sample updates. Updates that happen faster than this time (e.g. due to cov events) should be coalesced so that only the most recent update is sent.
set_value: Set a value to be used during diagnostics and operational use. Should override any operational values, but not override alarm conditions.
min_loglevel: Indicates the minimum loglevel for reporting log messages below which log entries should not be sent. See note below for a description of the level value.

linsong / udmi