udmi

UDMI / Docs / Specs / UUFI

Unified UDMI Functional Interface (UUFI)

The Unified UDMI Functional Interface (UUFI) defines a standardized messaging mechanism for external applications (the Client) to integrate with a UDMI-managed system (the System). UUFI serves exclusively as an external-facing, application-side interface to UDMI, enabling management and control of devices.

As an external interface specification, this document focuses solely on the public-facing contract: the exchange message formats, connectivity schemas, and the tools available to start or stop test environments. It does not expose or document the underlying system internals or implementation mechanisms (such as process IDs, internal databases, or local host execution steps), which are treated as private implementation details.

System Interfaces

This document details the application-facing Applications (UUFI) interface, which represents one of three core system interfaces into the UDMIS ecosystem:

1. Architecture

UUFI utilizes a messaging transport where Clients and Systems interact via dedicated topics and subscriptions.

Message Flow

2. Connectivity

2.1. Connection String

UUFI interfaces use a URL-like connection string format. Supported schemes: mqtt://, mqtts://, and pubsub://.

Format: scheme://[user@]host[:port][/path]

2.2. Protocol Mapping

PubSub (pubsub://)

MQTT and MQTTS (mqtt://, mqtts://)

2.3. Resource Identifier Constraints

To ensure compatibility with MQTT topic parsing structures and PubSub attribute indexing, all identifier strings utilized in UUFI connection coordinates and paths MUST conform to the following character and length restrictions:

3. Handshake Protocol

Handshake is Client-initiated. The System MUST NOT initiate a handshake unless acting as a Client.

The handshake has a 60-second timeout. On timeout, the Client should handle the failure and retry or fail-fast.

3.1. Logical Handshake Separation Layers

The UUFI interface separates network-level presence mapping from device-level operational control. Every component on the bus operates across two logical protocol layers:

  1. Layer 1: Service Handshake (Infrastructure-Level):
    • Establishes communication presence and connection mapping on the bus between a Client and the Service.
    • Upon startup, every client MUST perform this handshake to verify connection integrity and register its active routing coordinates and prefix.
  2. Layer 2: Application Orchestration (Application-Level):
    • Represents functional interactions (such as cloud model queries, telemetry publishing, or software updates).
    • These operations MUST only occur after the Layer 1 Service Handshaking of all participating components is complete.

3.2. Single-Responder Standard

To guarantee deterministic state transitions on shared handshake channels:

3.3. Service Handshake for Application-Level Clients

All active application-layer clients (such as orchestrators, parsers, or compliance verifiers) MUST execute their own Layer 1 Service Handshake upon initialization. This ensures that:

3.4. Standard Handshake Flow and Payload Routing

For any client initializing on the bus, the handshake sequence MUST follow the Request-Reply pattern below:

 [ Client Entity ]                                                [ The Service ]
         │                                                            │
         │─── (1) Handshake Request (state/udmi) ────────────────────►│
         │    Topic: [/{prefix}]/uufi/c/state/udmi                    │
         │    Envelope:                                               │
         │      - transactionId: "UUID-A"                             │
         │      - principal: "{implementation_id}.{entity_suffix}"    │
         │    Payload:                                                │
         │      - setup: { "transaction_id": "UUID-A" }               │
         │                                                            │
         │◄── (2) Handshake Config Reply (config/udmi) ───────────────│
         │    Topic: [/{prefix}]/uufi/c/config/udmi                   │
         │    Envelope:                                               │
         │      - transactionId: "UUID-A" (Symmetric Match)           │
         │      - source: "udmis"                                     │
         │      - principal: "{implementation_id}.{entity_suffix}"    │
         │    Payload:                                                │
         │      - setup: { "deviceRegistryId": "testing" }            │
         │      - reply: { "transaction_id": "UUID-A" }               │
         ▼                                                            ▼

3.5. Symmetric Envelope Transaction ID Gating

To prevent packet collisions and support trace correlation across shared handshake channels:

  1. Symmetric Trace Propagation: The Service MUST copy the transactionId value from the incoming request envelope directly into the transactionId field of the outgoing reply envelope.
  2. Strict Request Gating: The client MUST discard any handshake replies whose envelope transactionId does not match its original request’s transactionId.
  3. Trace-Level Tracking: Clients and verifiers MUST track and propagate this transactionId across subsequent configurations and states to support end-to-end correlation.

3.6. Handshake Steps and Payload Standards

To guarantee parsing interoperability and avoid protocol timeouts, Handshake payloads and correlation MUST strictly adhere to the following rules:

Step 1: State Declaration (Handshake Request)

The Client publishes a UDMI state message to /uufi/c/state/udmi.

Step 2: Configuration Confirmation (Handshake Response)

The System publishes a UDMI config message to /uufi/c/config/udmi.

Retries: The Client SHOULD periodically republish the Step 1 state message (e.g., every 5 seconds) if a valid Step 2 confirmation has not been received, until the 60-second timeout.

Activation: The Client is Active when reply.transaction_id matches the original state.setup.transaction_id.

3.7. Registry ID Discovery

4. Message Encapsulation

All messages are wrapped in a UUFI Envelope.

Mandatory Payload Fields

Inner JSON payload object MUST include:

Transport Mapping

Transport Envelope Location Payload Location
PubSub Message Attributes Message Data (JSON)
MQTT JSON Wrapper Payload payload key

MQTT Constraints

4.1. Envelope Metadata and Configuration Attributes

To ensure protocol compatibility, data integrity, and protection against replay attacks, the following metadata policies are codified for UUFI message envelopes and payloads:

5. System Model Operations

5.1. Schema and Addressing

5.2. Update Semantics (Partial Merge)

The UPDATE operation for the system subfolder is a partial merge at the device subsystem level. Existing fields not in the payload MUST NOT be modified.

5.3. Device System Configuration

To configure a device’s expected or desired software subsystem version, implementations MUST adhere to exactly ONE standard schema:

5.4. Actual Version Reporting

To report a device’s actual or currently running software subsystem version, implementations MUST adhere strictly to the standard UDMI schema:

6. UDMI to UUFI Mapping

UDMI Operation Envelope subType Envelope subFolder Direction Note
Handshake State state udmi Publish Standard flat format (Step 1)
Handshake Config config udmi Receive Standard flat format (Step 2)
Config Update config varies Publish  
State Event state varies Receive  
Telemetry events pointset Receive  
Discovery events discovery Receive  
System Model Query query system Publish Registry and device-scoped
System Model Update model system Publish Registry and device-scoped
System Model Reply model system Receive Registry and device-scoped
State Query query state Publish  
Blobset Config config blobset Publish  
Blobset State state blobset Receive  

7. Reliability

MQTT QoS

Idempotency

8. Payload and Formatting Rules

8.1. Payload Structure

8.2. Timestamp Format

8.3. Type Safety and Fallbacks

8.4. MQTT Specific Rules

9. Test Setup for External Clients

This section specifies how external client developers (working outside the UDMI project codebase) can set up a local testing environment to build and verify custom UUFI Client implementations against a running System and Device Under Test (DUT).

9.1. Local System Infrastructure (bin/start_local)

To initialize the local System stack (Mosquitto broker, etcd, and UDMIS control plane), execute the local startup script with a designated target site model directory and connection spec:

bin/start_local [site_model_dir] //mqtt/localhost:$port

Example:

bin/start_local sites/udmi_site_model //mqtt/localhost:46432

Upon successful startup, the local environment exposes the following connection parameters:

9.2. Provisioning a Device Under Test (DUT) (bin/start_dut)

To emulate a managed device executing commands and reporting telemetry over UUFI, launch the DUT (Pubber) process targeting the site model and connection endpoint:

bin/start_dut <site_model_dir> //mqtt/localhost:$port [device_id] [serial_no]

Example:

bin/start_dut sites/udmi_site_model //mqtt/localhost:46432 AHU-1 uufi-serial

9.3. Database & Tagabase Registration (bin/registrar)

Prior to test execution, the database synchronization step must be executed using the standard registrar tool in full online mode:

bin/registrar <site_model_dir> //mqtt/localhost:$port

Example:

bin/registrar sites/udmi_site_model //mqtt/localhost:46432

9.4. Site Model Database Mutations (bin/site_trigger)

To trigger automated database mutations or field updates during testing, execute bin/site_trigger using explicit connection syntax:

bin/site_trigger update <site_path> <device_id> <blob_id> <version> //mqtt/localhost:$port

Example:

bin/site_trigger update sites/udmi_site_model AHU-1 system 1.0.0 //mqtt/localhost:46432

9.5. Hermetic Environment Teardown

To tear down or stop running test infrastructure and DUT simulations in isolated or non-privileged environments, use the provided high-level tool commands:

9.6. Non-Privileged Execution Trigger

9.7. Utility Usage Restrictions

9.8. Environment Variable Restrictions


Appendix A: Schemas and Examples

This appendix references the formal JSON schemas and provides message examples for the UUFI protocol. The UDMI Schema Repository is the authoritative source for all message structures.

A.1. Examples

A.1.1. Handshake (PubSub)

Attributes:

{
  "subFolder": "udmi",
  "subType": "state",
  "transactionId": "UUFI:sess123:001",
  "source": "client-id",
  "principal": "client-id@"
}

Data:

{
  "version": "1.5.2",
  "timestamp": "2026-04-29T10:00:00Z",
  "setup": {
    "functions_ver": 9,
    "transaction_id": "UUFI:sess123:001",
    "msg_source": "client-id"
  }
}

A.1.1.a. Handshake Response (PubSub)

Attributes:

{
  "subFolder": "udmi",
  "subType": "config",
  "transactionId": "UUFI:sess123:001",
  "source": "system-id",
  "principal": "client-id@"
}

Data:

{
  "version": "1.5.2",
  "timestamp": "2026-04-29T10:00:05Z",
  "setup": {
    "functions_ver": 9,
    "transaction_id": "UUFI:sess123:001",
    "msg_source": "client-id"
  },
  "reply": {
    "transaction_id": "UUFI:sess123:001"
  }
}

A.1.2. Handshake (MQTT)

Topic: /uufi/c/state/udmi

Payload:

{
  "subType": "state",
  "subFolder": "udmi",
  "projectId": "vibrant",
  "transactionId": "UUFI:sess123:001",
  "publishTime": "2026-04-29T10:00:00Z",
  "source": "client-id",
  "principal": "client-id",
  "payload": {
    "version": "1.5.2",
    "timestamp": "2026-04-29T10:00:00Z",
    "setup": {
      "functions_ver": 9,
      "transaction_id": "UUFI:sess123:001",
      "msg_source": "client-id"
    }
  }
}

A.1.2.a. Handshake Response (MQTT)

Topic: /uufi/c/config/udmi

Payload:

{
  "subType": "config",
  "subFolder": "udmi",
  "projectId": "vibrant",
  "transactionId": "UUFI:sess123:001",
  "publishTime": "2026-04-29T10:00:05Z",
  "source": "system-id",
  "principal": "client-id",
  "payload": {
    "version": "1.5.2",
    "timestamp": "2026-04-29T10:00:05Z",
    "setup": {
      "functions_ver": 9,
      "transaction_id": "UUFI:sess123:001",
      "msg_source": "client-id"
    },
    "reply": {
      "transaction_id": "UUFI:sess123:001"
    }
  }
}

A.1.3. Pointset Config (PubSub)

Attributes:

{
  "subFolder": "pointset",
  "subType": "config",
  "transactionId": "UUFI:sess123:002",
  "source": "client-id",
  "principal": "client-id@",
  "deviceRegistryId": "reg-1",
  "deviceId": "dev-1"
}

Data:

{
  "version": "1.5.2",
  "timestamp": "2026-04-29T10:05:00Z",
  "points": {
    "temp": { "set_value": 22.5 }
  }
}

A.1.4. Pointset Config (MQTT)

Topic: /uufi/r/reg-1/d/dev-1/c/config/pointset

Payload:

{
  "subType": "config",
  "subFolder": "pointset",
  "deviceRegistryId": "reg-1",
  "deviceId": "dev-1",
  "transactionId": "UUFI:sess123:002",
  "principal": "client-id",
  "payload": {
    "version": "1.5.2",
    "timestamp": "2026-04-29T10:05:00Z",
    "points": {
      "temp": { "set_value": 22.5 }
    }
  }
}

A.1.5. Blobset Config (PubSub)

Attributes:

{
  "subFolder": "blobset",
  "subType": "config",
  "transactionId": "UUFI:sess123:003",
  "source": "client-id",
  "principal": "client-id@",
  "deviceRegistryId": "reg-1",
  "deviceId": "dev-1"
}

Data:

{
  "version": "1.5.2",
  "timestamp": "2026-04-29T10:10:00Z",
  "blobset": {
    "blobs": {
      "system": {
        "phase": "apply",
        "url": "file:///path/to/bundle.bin",
        "sha256": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "generation": "2026-04-29T10:10:00Z"
      }
    }
  }
}

A.1.6. Blobset Config (MQTT)

Topic: /uufi/r/reg-1/d/dev-1/c/config/blobset

Payload:

{
  "subType": "config",
  "subFolder": "blobset",
  "deviceRegistryId": "reg-1",
  "deviceId": "dev-1",
  "transactionId": "UUFI:sess123:003",
  "principal": "client-id",
  "payload": {
    "version": "1.5.2",
    "timestamp": "2026-04-29T10:10:00Z",
    "blobset": {
      "blobs": {
        "system": {
          "phase": "apply",
          "url": "file:///path/to/bundle.bin",
          "sha256": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
          "generation": "2026-04-29T10:10:00Z"
        }
      }
    }
  }
}

A.1.7. System Model Update (PubSub)

Attributes:

{
  "subFolder": "system",
  "subType": "model",
  "transactionId": "UUFI:sess123:004",
  "source": "orchestrator",
  "principal": "orchestrator",
  "deviceRegistryId": "reg-1",
  "deviceId": "dev-1"
}

Data:

{
  "version": "1.5.2",
  "timestamp": "2026-04-29T10:15:00Z",
  "software": {
        "system": "2.1.0"
  }
}

A.1.8. System Model Update (MQTT)

Topic: /uufi/r/reg-1/d/dev-1/c/model/system

Payload:

{
  "subType": "model",
  "subFolder": "system",
  "deviceRegistryId": "reg-1",
  "deviceId": "dev-1",
  "projectId": "vibrant",
  "transactionId": "UUFI:sess123:004",
  "publishTime": "2026-04-29T10:15:00Z",
  "source": "orchestrator",
  "principal": "orchestrator",
  "payload": {
    "version": "1.5.2",
    "timestamp": "2026-04-29T10:15:00Z",
    "software": {
      "system": "2.1.0"
    }
  }
}

A.2. Authoritative Schemas

UUFI implementations MUST adhere to the following schemas from the UDMI repository:

UUFI Component Authoritative UDMI Schema
Message Envelope schema/envelope.json
Handshake State schema/state_udmi.json
Handshake Config schema/config_udmi.json
System Model schema/model_system.json
Blobset Config schema/config_blobset.json
Blobset State schema/state_blobset.json