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 refs 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 two basic kinds of discovery scan capabilities:

• Passive Scan: Passively monitor the protocol channel to detect target nodes.
• Active Scan: Actively probe the protocol channel to find target nodes.
  • Sporadic Scan: A single scan request to discover potentially unknown on-network devices.
  • Periodic Scan: Periodically scan for unknown devices on the network.

The passive and active scan configurations are not mutually exclusive, and can be setup to, e.g., continually perform a passive scan of a network while periodically actively probing for devices.

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.

Scan State Phases

There are four phases that a discovery system can be in, as reported by the appropriate state block.

• stopped: There is no scan activity, either passive, active, or scheduled.
• passive: The system is passively monitoring for devices on the network.
• pending: The system has a future active scan scheduled.
• active: There is currently an active scan in progress.

If both an active and passive scan are configured, then the reported phase should be passive until the active phase applies (so there would be no pending phase indicated).

Passive Scan

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

• start config: There is no generation marker, since scanning is always happening. Specification of a passive_holdoff_sec value enables the passive scan.
• start state: Indicates that scanning is active, but no generation value.
• discovery events: Events as per normal, except no generation value.

The passive_holdoff_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.

Active Scans

(Note: the information below is provisional and known not accurate... pending a documentation update!)

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, not-the-same as the previous scan generation, and after the device's last start time).
• start state: Indicates the device is actively scanning, with generation should match that of config, and the phase is indicated as pending.
• discovery events: Streaming results for scanned devices (keyed by matching generation field): one events 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.

Enumeration Mechanisms

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 events: 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 events 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 events: 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).