udmi

UDMI / Docs / Specs / Onboarding

Onboarding

Onboarding is defined as the overall flow required to have on-prem building devices properly feeding telemetry into a backend data pipeline. This consists of three main separable phases, each with a distinct role and function:

• Discovery: Discovering what devices are actually on-prem, and what capabilities they have.
• Mapping: Figuring out how actual on-prem components should be mapped into higher-level semantic concepts.
• Provisioning: Setting up various system registries and device configuration to operate properly within the target system.
• Pointset: The ‘phase’ of actually sending pointset telemetry from the on-prem devices to the actual pipeline. The ultimate goal of onboarding!

As an analogy, these phases correspond to biological eyes (discovery), brain (mapping), and arms (provisioning), and fall into the simple see, think, do adage: First you see something, then you think about it, and then you do something about it.

Each of these steps can be applied individually, and the continuous application of all of them together constitutes automation, which is a key step towards enabling highly maintainable systems. The absence of each is also indicative of certain specific failure modes:

flowchart LR
  D[Devices]
  A[Agent]
  P[Pipeline]
  D -- Pointset --> P
  D -- Discovery --> A
  A -- Provisioning --> P
  A -- Mapping --> A

• Without discovery, the backend system might not actually reflect reality. The on-prem devices and capabilities might be different than what is expected to be there!
• Without mapping, the whole system is formulaic and is only exactly what it’s told to be. This means at some point, somebody needs to type in exactly what everything is.
• Without provisioning, nothing can change in the system, and essentially requires again somebody to go around and manually do things to make it all work.

Terms and Definitions

Throughout the UDMI (and beyond) framework, there are several different key concepts that tie everything together. Unfortunately, due to cross-systems and legacy reasons there aren’t unique terms for everything (sometimes the same thing has multiple names), but they do ultimately constitute a coherent system.

• site (e.g. US-MTV-BRX423):
  • Standardized location-code
  • site_name (UDMI): term for the building
  • registryId (IoT Core): Convention (although not universal) of having the registry be the designated site
• entity (e.g. AHU-1): Identifier that nominally refers to the device across the entire ‘IoT’ domain, from physical device through to a virtual back-end representation.
  • deviceId (IoT Core)
  • entity (DBP)
  • deviceId (UDMI)
• subsystem: Subsystem identifiers are generally created/managed by various individual subsystems, and often only have significance with a limited scope. E.g., a cloud-based pipeline does/should not care about the local IP address of a device.
  • localnet (UDMI): Specifies various local addresses (IP, bacnet, etc…) for a device
    • bacnet:
    • IPv4:
    • macaddr:
    • iot: Entity type as per above.
  • deviceNumId (IoT Core): Generated by IoT core when a device is instantiated
  • cloud_device_id (DBP): How the DBP refers to the deviceNumId
  • guid (DBP): Uniquely defines an entity within the scope of the data pipeline
• points (e.g. room_temp_sensor): Names a specific data point for the device. Ideally the names would be the same, and a translation is needed/required when they are not.
  • local point name: The name used by the physical device itself
  • iot point name: The name used by the cloud for structurally defined data
  • point reference:

Legacy IoT Gateway Discovery

Actors:

• Devices: On-prem IoT devices (e.g. AHU)
• Gateway: On-prem node, acting as both a discovery node and gateway
• Registry: Cloud-based device registry
• Agent: Controlling agent (either manual or programmatic)
• Pipeline: Cloud-based data pipeline

The device id used in this mode is in an implicit form of bacnet-ABCDEF that encodes both the iot id (as seen in the cloud), and the fieldbus id (as used by bacnet).

%%{wrap}%%
sequenceDiagram
  participant Devices
  participant Gateway
  participant Registry
  participant Agent
  participant Pipeline
  Agent->>Gateway: Start Discovery Sequence
  Gateway-->Devices: Fieldbus Discovery
  Gateway->>Pipeline: Discovery Result
  Pipeline->>Registry: Ensure Device entry
  Pipeline->>Gateway: Gateway Config
  Pipeline->>Devices: Device Config
  loop Quiescent
    Devices->>Pipeline: Point Telemetry Event<br/>(via gateway)
  end

This site is open source. Improve this page.