UDMI / Docs / Specs / Sequences / Discovery
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.
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 theactive
astrue
. - 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 thegeneration
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.
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
orscan_interval_sec
parameter is removed from config.
- The
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.
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. Thescan_interval_sec
triggers the capability (see below). - start state: Indicates that scanning is
active
, but nogeneration
. - discovery events: 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 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 thesystem
block starts the self enumeration process (rather than thediscovery
block). - start state: The
system
block indicates thegeneration
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'sdeviceId
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 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.
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).