KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #dsh-plugin #deepseek-harness #windows #open-source #agent-skills #ai

udmi

★ 68 Open GitHub ↗

Universal Device Management Interface (UDMI) provides a high-level specification for the management and operation of physical IoT systems.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[**UDMI**](#)

![UDMI Logo](https://raw.githubusercontent.com/faucetsdn/udmi/master/assets/udmi_logo.png)

# UDMI Overview

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.

* [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/))
* [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)

---

By design, this schema is intended to be:
* **U**niversal: Apply to all subsystems in a building, not a singular vertical solution.
* **D**evice: Operations on an IoT _device_, a managed entity in physical space.
* **M**anagement: Focus on device _management_, rather than command & control.
* **I**nterface: Define an interface specification, rather than a client-library or RPC mechanism.

See the associated [UDMI Tech Stack](docs/specs/tech_stack.md) for details about transport mechanism
outside of the core schema definition. Nominally meant for cloud-based MQTT-bridge providers, it can
also work locally with standard docker-hosted local MQTT brokers.

## Recommended Workflow

The [recommended workflow](docs/guides) 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_](docs/specs/gateway.md): 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](https://queue.acm.org/detail.cfm?id=2560327).
Once operational, the system should be able to operate completely autonomously 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 guidelines](https://cloud.google.com/apis/design/resource_names).

## 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_](docs/messages/system.md) messages about the base device itself.
* Device [_pointset_](docs/messages/pointset.md) for device telemetry organized by points.
* Optional [_gateway_](docs/specs/gateway.md) functionality for proxying device/MQTT connections.
* Local [_discover_](docs/specs/discovery.md) 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](tests/schemas/metadata/example.json)) stored in the cloud about a device,
but not directly available to or on the device, defined by [metadata.json](schema/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](tests/schemas/envelope/example.json)) for server-side
attributes of received messages, defined by [envelope.json](schema/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](tests/schemas/state/example.json)), sent from device to cloud,
defined by [state.json](schema/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](tests/schemas/config/example.json)), passed from cloud to device,
defined by [config.json](schema/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.

An interactive view of the schema is available at [gencode/docs/](gencode/docs/).

### 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](docs/tools/registrar.md)
tool and [validator](docs/tools/validator.md) tool provide a means to configure and check site
installations, respectively.

udmi

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README