{"id":26483538,"url":"https://github.com/faucetsdn/udmi","last_synced_at":"2025-04-07T15:10:44.734Z","repository":{"id":37081930,"uuid":"274303220","full_name":"faucetsdn/udmi","owner":"faucetsdn","description":"Universal Device Management Interface (UDMI) provides a high-level specification for the management and operation of physical IoT systems.","archived":false,"fork":false,"pushed_at":"2024-10-30T01:41:59.000Z","size":22915,"stargazers_count":49,"open_issues_count":25,"forks_count":48,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-10-30T03:59:15.129Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://faucetsdn.github.io/udmi/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faucetsdn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-23T03:51:36.000Z","updated_at":"2024-10-30T01:42:03.000Z","dependencies_parsed_at":"2022-07-14T04:30:35.558Z","dependency_job_id":"2a496532-bae7-4704-a5bd-f5f4eeb4d177","html_url":"https://github.com/faucetsdn/udmi","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faucetsdn%2Fudmi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faucetsdn%2Fudmi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faucetsdn%2Fudmi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faucetsdn%2Fudmi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faucetsdn","download_url":"https://codeload.github.com/faucetsdn/udmi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247675607,"owners_count":20977378,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-20T04:55:52.885Z","updated_at":"2025-04-07T15:10:44.707Z","avatar_url":"https://github.com/faucetsdn.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[**UDMI**](#)\n\n# UDMI Overview\n\nThe Universal Device Management Interface (UDMI) provides a high-level specification for the\nmanagement and operation of physical IoT systems. This data is typically exchanged\nwith a cloud entity that can maintain a \"digital twin\" or \"shadow device\" in the cloud.\n\n* [Core UDMI documentation](docs/) for tools and specifications\n* [Message schema definition](https://github.com/faucetsdn/udmi/tree/master/schema) with ([_🧬Interactive Viewer_](http://faucetsdn.github.io/udmi/gencode/docs/))\n* [udmi-discuss@googlegroups.com](https://groups.google.com/forum/#!forum/udmi-discuss) email discussion list\n* Bi-weekly _UDMI Discuss_ video meeting open to all (join the mailing list to get an invite)\n\n---\n\nBy design, this schema is intended to be:\n* **U**niversal: Apply to all subsystems in a building, not a singular vertical solution.\n* **D**evice: Operations on an IoT _device_, a managed entity in physical space.\n* **M**anagement: Focus on device _management_, rather than command \u0026 control.\n* **I**nterface: Define an interface specification, rather than a client-library or RPC mechanism.\n\nSee the associated [UDMI Tech Stack](docs/specs/tech_stack.md) for details about transport mechanism\noutside of the core schema definition. Nominally meant for cloud-based MQTT-bridge providers, it can\nalso work locally with standard docker-hosted local MQTT brokers.\n\n## Recommended Workflow\n\nThe [recommended workflow](docs/guides) for UDMI covers using the _registrar_ and\n_validator_ tools to configure and test a cloud project. Additionally, the _pubber_ tool\nis instrumental in setting up and testing the system independent of actual device setup.\n\n## Use Cases\n\nThe essence behind UDMI is an automated mechanism for IoT system management. Many current\nsystems require direct-to-device access, such as through a web browser or telnet/ssh session.\nThese techniques do not scale to robust managed ecosystems since they rely too heavily on\nmanual operation (aren't automated), and increase the security exposure of the system\n(since they need to expose these management ports).\n\nUDMI is intended to support a few primary use-cases:\n* _Telemetry Ingestion_: Ingest device data points in a standardized format.\n* [_Gateway Proxy_](docs/specs/gateway.md): Proxy data/connection for non-UDMI devices,\nallowing adaptation to legacy systems.\n* _On-Prem Actuation_: Ability to effect on-prem device behavior.\n* _Device Testability_: e.g. Trigger a fake alarm to test reporting mechanisms.\n* _Commissioning Tools_: Streamline complete system setup and install.\n* _Operational Diagnostics_: Make it easy for system operators to diagnose basic faults.\n* _Status and Logging_: Report system operational metrics to hosting infrastructure.\n* _Key Rotation_: Manage encryption keys and certificates in accordance with best practice.\n* _Credential Exchange_: Bootstrap higher-layer authentication to restricted resources.\n* _Firmware Updates_: Initiate, monitor, and track firmware updates across an entire fleet\nof devices.\n* _On-Prem Discovery_: Enumerate any on-prem devices to aid setup or anomaly detection.\n\nAll these situations are conceptually about _management_ of devices, which is conceptually\ndifferent than the _control_ or _operation_. These concepts are similar to the _management_,\n_control_, and _data_ planes of\n[Software Defined Networks](https://queue.acm.org/detail.cfm?id=2560327).\nOnce operational, the system should be able to operate completely autonomously from the\nmanagement capabilities, which are only required to diagnose or tweak system behavior.\n\n## Design Philosophy\n\nIn order to provide for management automation, UDMI strives for the following principles:\n* \u003cb\u003eSecure and Authenticated:\u003c/b\u003e Requires a properly secure and authenticated channel\nfrom the device to managing infrastructure.\n* \u003cb\u003eDeclarative Specification:\u003c/b\u003e The schema describes the _desired_ state of the system,\nrelying on the underlying mechanisms to match actual state with desired state. This is\nconceptually similar to Kubernetes-style configuration files.\n* \u003cb\u003eMinimal Elegant Design:\u003c/b\u003e Initially underspecified, with an eye towards making it easy to\nadd new capabilities in the future. \u003cem\u003eIt is easier to add something than it is to remove it.\u003c/em\u003e\n* \u003cb\u003eReduced Choices:\u003c/b\u003e In the long run, choice leads to more work\nto implement, and more ambiguity. Strive towards having only _one_ way of doing each thing.\n* \u003cb\u003eStructure and Clarity:\u003c/b\u003e This is not a \"compressed\" format and not designed for\nvery large structures or high-bandwidth streams.\n* \u003cb\u003eProperty Names:\u003c/b\u003eUses \u003cem\u003esnake_case\u003c/em\u003e convention for property names.\n* \u003cb\u003eResource Names:\u003c/b\u003e Overall structure (when flattened to paths), follows the\n[API Resource Names guidelines](https://cloud.google.com/apis/design/resource_names).\n\n## Subsystem Blocks\n\nUDMI provides a means to multiplex multiple functional subsystems through the same shared\ncommunication channel. There are a number of subsystems that make up the core UDMI spec:\n\n* Core [_system_](docs/messages/system.md) messages about the base device itself.\n* Device [_pointset_](docs/messages/pointset.md) for device telemetry organized by points.\n* Optional [_gateway_](docs/specs/gateway.md) functionality for proxying device/MQTT connections.\n* Local [_discover_](docs/specs/discovery.md) for discovering device and network capabilities.\n\n## Schema Structure\n\nSchemas are broken down into several top-level sub-schemas that are invoked for\ndifferent aspects of device management:\n* Device _metadata_ ([example](tests/schemas/metadata/example.json)) stored in the cloud about a device,\nbut not directly available to or on the device, defined by [\u003cem\u003emetadata.json\u003c/em\u003e](schema/metadata.json).\nThis is essentially a specification about how the device should be configured or\nexpectations about what the device should be doing.\n* Message _envelope_ ([example](tests/schemas/envelope/example.json)) for server-side\nattributes of received messages, defined by [\u003cem\u003eenvelope.json\u003c/em\u003e](schema/envelope.json). This is\nautomatically generated by the transport layer and is then available for server-side\nprocessing.\n* Streaming device telemetry, which can take on several different forms, depending on the intended\nuse, e.g.:\n* Device _state_ ([example](tests/schemas/state/example.json)), sent from device to cloud,\ndefined by [\u003cem\u003estate.json\u003c/em\u003e](schema/state.json). There is one current _state_ per device,\nwhich is considered sticky until a new state message is sent.\nis comprised of several subsections (e.g. _system_ or _pointset_) that describe the\nrelevant sub-state components.\n* Device _config_ ([example](tests/schemas/config/example.json)), passed from cloud to device,\ndefined by [\u003cem\u003econfig.json\u003c/em\u003e](schema/config.json). There is one active _config_ per device,\nwhich is considered current until a new config is received.\n\nA device client implementation will typically only be aware of the _state_, _config_, and\none or more _telemetry_ messages (e.g. _pointset_), while all others are meant for the supporting\ninfrastructure.\n\nAn interactive view of the schema is available at [gencode/docs/](gencode/docs/).\n\n### Metadata Registration and Validation\n\nUsing UDMI on a project entails not only the base device and server implementations, but also\nproperly registering and validating device configuration. The [registrar](docs/tools/registrar.md)\ntool and [validator](docs/tools/validator.md) tool provide a means to configure and check site\ninstallations, respectively.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaucetsdn%2Fudmi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaucetsdn%2Fudmi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaucetsdn%2Fudmi/lists"}