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.

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.

Once completed, Onboarding enables the flow of Pointset data, the ‘phase’ of actually sending pointset telemetry from the on-prem devices to the actual pipeline. The ultimate goal!

Architectural Flow

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]
  M[Mapping]
  P[Pipeline]
  D -. "Pointset\n(Telemetry)" .-> P
  D -- Discovery --> M
  M -- Provisioning --> P

• 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.

Sequence Diagram

The overall onboarding sequence involves multiple components that work together to provide the overall flow:

• Devices: The target things that need to be discovered, configured, and ultimately communicate point data.
• Spotter: Operative node that performs discovery, scanning local networks and producing observations.
• Butler: Cloud-based agent/service responsible for managing the overall discovery and mapping process (how often, what color, etc…).
• Model: Central repository / source of truth containing device configurations and metadata.
• Mapper: Used at the spotter to coordinate on-prem discovery.
• Pipeline: Ultimate recipient of pointset information, The thing that cares about ‘temperature’ in a room.

(The * prefixing a *term means that this id/property is being sourced/created at that step.)

sequenceDiagram
  %%{wrap}%%
  participant Devices
  participant Spotter
  participant Butler
  participant Model
  participant Mapper
  participant Pipeline
  Note over Devices, Butler: Discovery
  Butler->>Spotter: Discovery Config
  Devices<<-->>Spotter: fieldbus scan
  Spotter->>Butler: Discovery Events
  Note over Butler, Mapper: Mapping
  Butler->>Mapper: Discovery Scan
  Model->>Mapper: Current Model
  Mapper->>Mapper: Map
  Mapper->>Butler: Proposed Model
  Note over Butler, Pipeline: Provisioning
  Butler->>Butler: Approve
  Butler->>Model: Update Model
  Model->>Pipeline: Provision Pipeline
  Note over Devices, Pipeline: Operational
  Devices-->>Pipeline: Pointset (Telemetry)

This site is open source. Improve this page.