udmi

UDMI / Docs / Specs / Discovery

Discovery

Discovery consists of two related processes for describing the ‘as built’ state of a system: scanning and enumeration. For devices, the overall discovery sequence describes the exact sequence of device messages employed in each case. Each process can be executed independently, or together (known as scan enumeration):

• scanning scans for existing devices, and returns information about their discovered address families. This is information about how the device is indexed in the world around it.

• enumeration lists the properties of a given target device. Providing information intrinsic to a device and the capabilities it provides.

Backend services will receive a streaming set of discovery enumeration messages that follow the appropriate discovery event schema.

Sequence Diagram

The overall discovery 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.
• Agent: Cloud-based agent responsible for managing the overall discovery and mapping process (how often, what color, etc…).
• 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 Agent as Agent<br/>(w/ Mapping)
  participant Pipeline
  Note over Devices, Agent: Discovery Start
  activate Agent
  Agent->>Spotter: DISCOVERY CONFIG<br/>()
  loop
    Devices-->Spotter: fieldbus
    Spotter->>Agent: DISCOVERY EVENT<br/>(*scan_id)<br/><properties: *uniqs>
  end
  Note over Agent: Provisioning<br/>& Mapping
  Agent ->> Pipeline: (config device)
  deactivate Agent
  Devices->>Pipeline: POINTSET EVENT<br/>(device_id, device_num_id, points)<br/><pointset>

Scanning

Scanning is the process of scanning a network and identifying the various entities thereof. Often (but not always), this comes along with a correlation of various address families (e.g. IPv4 address associated with a particular MAC):

• ethmac (82:CC:18:9A:45:1C): Ethernet mac address for low-level networking
• ipv4 (10.27.38.123): Assigned IPv4 device network address
• ipv6 (FE80::8E8C:BC72): Assigned IPv6 device network address
• bacnet (92EA09): The device’s BACnet mac-address
• iot (AHU-32): Device designation as used in cloud-native processing
• host (AHU-32.ACME.COM): DNS hostname for a device

Scanning results can only describe a subset of the complete picture (e.g. only the ETHMAC and IPv4 address), and it is up to the back-end systems to properly link/infer complete relationships. Some systems may only care about singular entries (e.g. just discovering what IoT devices are there, but not caring about any association).

Discovery is a process that can be explicitly requested through UDMI for on-prem devices that support the capability (e.g. an IoT Gateway), or it can be done automatically by a device itself (e.g. on a predefined interval). Depending on device capabilities and system configuration, the scanning process may also trigger discovered device enumeration.

Enumeration

Enumeration is the process for listing all the parameters available from a device (rather than just the ones in its designated reporting set). This information can either come directly from a device (self enumeration) or as the result of a discovery scan (scan enumeration). Both report the same kind of content, but the mechanism (and message source) are different: one comes from the device itself, the other by proxy.

Within an enumeration message, there’s a number of different kinds of information that can be reported:

• refs: A listing of all the data points that a device has to offer, indexed by their protocol-specific reference. References are curated into named points, which forms the foundation of the pointset messages.
• blobs: A listing of all the data blobs that a device knows how to handle. This could be components like firmware updates, key rotation, etc… Some blobs will be standardized across the system, while others will be device-specific.

This site is open source. Improve this page.