UDMI / Docs / Specs / Discovery
Discovery is the first phase in the overall Onboarding flow, followed by Mapping.
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.
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):
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.
For details on how the generation field operates during different scan types, see the Discovery Generation documentation. For protocol-specific details on active BACnet discovery and scan depths, see the BACnet Discovery specification.
Discovery depth controls the level of detail collected during a scan. Each depth level is cumulative, building upon the preceding level:
buckets: High-level network segments or device groupings.entries: Individual discovered devices and cross-family address associations.system: Device identity and hardware information.details: Enumerated device points, objects, or services.depth |
Description | bacnet (Spec) |
iot |
ipv4 |
|---|---|---|---|---|
buckets |
Network or logical groupings | BACnet networks and UDP ports | Cloud registries or site groups | IPv4 subnets |
entries |
Device addresses and bindings | Device instances and IP/MAC bindings | IoT device IDs and gateway bindings | Host IP, MAC, and hostname bindings |
system |
Device identity and hardware | Device object identity and vendor info | Reported system hardware and software | Host OS and hardware fingerprint |
details |
Exposed points or services | BACnet objects and properties | Configured or self-enumerated points | Open ports and network services |
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.