udmi

UDMI / Docs / Specs / Sequences / Discovery

Discovery Sequences

The basic discovery device message sequence follows a standard config/state call/response mechanism, with slightly different parameters for each different mode of operation. During the process, there’s two major devices involved: the enumerated node (the thing with the points that are being described), and the discovery node (the thing that is doing the scan, which does not exist in the self enumeration case).

There’s a few basic modes for the discovery scan capability:

• Sporadic Scan: A single scan request to discover potentially unknown on-network devices.
• Periodic Scan: Periodically scan for unknown devices on the network.
• Continuous Scan: Passively look for discovery information and report as noticed.

Likewise, a few different ways discovery enumeration can happen:

• Self Enumeration: An enumeration request for a single directly connected device.
• Scan Enumeration: Enumerate device capabilities as part of a discovery scan.

These represent the most common use cases, but they are not necessarily mutually exclusive, e.g. a continuous scan may or may not include implicit enumeration results.

Sporadic Scan

a sporadic scan is used to trigger an on-prem agent (often an IoT Gateway) to scan the local network for devices. Depending on the system, this might encompass a number of different network protocols (e.g. BACnet, IPv4, etc…).

• start config: Starts a discovery scan, triggered by the generation timestamp (defined and not-the-same as the previous scan generation).
• start state: Indicates the device is actively scanning, with generation should match that of config, and the active as true.
• discovery event: Streaming results for scanned devices (keyed by matching generation field): one event for each unique device scanned.
• stop state: Once complete, the active field is false (or removed). Ideally the generation field would remain to indicate the last scan performed.

At this point, the config generation entry can be removed with no effect, or updated to initiate a new scan.

Periodic Scan

A periodic scan is like a sporadic scan except that the scan automatically occurs due to a predefined interval (rather than individual trigger config_s). This allows for repeated scans without any _config changes.

• start config: Sets up a periodic scan, as defined by the scan_interval_sec parameter.
• Loop over the { start, discovery, stop } sequence as per a sporadic scan:
  • The generation value each loop will be updated to uniquely identify the current loop.
  • Unlike the sporadic case, the generation field will be greater than or equal to the config specification.
  • Loop terminates when either the generation or scan_interval_sec parameter is removed from config.

Note that the scanning should occur at intervals directly determined by the config generation timestamp plus integral increments of the scan interval, i.e. Ts = Tc + N*Ti, so that there is no clock drift. E.g., it should be possible to setup a schema to scan every day exactly at midnight.

Continuous Scan

A continuous scan is the mode for a system that can passively monitor traffic and deduce scan results, so there is no need for a sporadic/periodic scan. This might be a system that monitors network ARP requests, or transient BACnet traffic.

• start config: There is no generation marker, since scanning is always happening. The scan_interval_sec triggers the capability (see below).
• start state: Indicates that scanning is active, but no generation.
• discovery event: Events as per normal, except no generation.

For this case, there is no stop state message since the scan never stops: The process silently stops when the scan_interval_sec parameter is removed from the config. Additionally, the scan_interval_sec field indicates the duration within which a scan result for a given device should not be repeated. E.g., if a device is passively detected every 30 sec, but the scan interval is 60 sec, then the result would only be reported for (approximately) every other detection.

Self Enumeration

Self enumeration is used for a device that is already registered in the cloud systems (no scan required), and can be explicitly directed to enumerate itself. This also applies to all direct-connect (not proxy) devices (which likely can’t be scanned anyway)

• start config: generation parameter in the system block starts the self enumeration process (rather than the discovery block).
• start state: The system block indicates the generation of enumeration that is currently being processed.
• discovery event: The results do not have a family block, rather, the device id is determined from the envelope’s deviceId field.

With self enumeration there is no specific stop state, as the system deterministically sends a single device’s discovery event corresponding to the config trigger.

Scan Enumeration

Scan enumeration comes bundled with a discovery scan of some kind, triggered by the enumeration field in the start config indicates that the system should also then automatically enumerates each device encountered.

• start config: Initiates the scan, along with an added enumerate field indicating that the system should enumerate each device it encounters.
• start state: Same as base scan case.
• discovery event: Same as scan result, except includes enumeration fields (typically discovered points).
• stop state: Same as base scan case.

Error Handling

There’s different ways to report errors, depending on the scope of the error.

• scan error: Exemplifies how a device should report an error potentially affecting all devices or points during a scan.
• self error: Details status while processing self enumeration that potentially affects all points.
• point error: Details how an individual point error should be reported during (self or scan) enumeration.
• scan enumeration error: Details how a scan enumeration error that affects all points should be reported (i.e. while trying to enumerate the scanned device).

This site is open source. Improve this page.