glp/0/:/ev/discovery/device glp/0/{SID}/ev/discovery/device |
Device discovery is a method of discovering edge devices and selecting the most appropriate edge server for the discovered device.
The segment controller (edge server) generally becomes aware of newly attached edge devices through active or passive discovery methods, subject to the edge protocol and other circumstances. The exact method of discovery depends on the edge protocol and edge server implementation.
One edge processor might implement a passive discovery method, relying on new devices to announce themselves in a suitable manner. Another edge processor might implement an active discovery method, periodically scanning or querying the network for new arrivals upon request. Yet another edge processor might support a number of hardwired peripheral I/O components and “discover” these instantaneously upon startup.
Discovery Capability
The segment controller indicates support for manual device discovery for the segment when at least one protocol engine supports this method, and reports this capability for each protocol engine that supports the discoverDevices action. For information on limitations with discoverDevices, see discoverDevices.
Discovery Methods
Automatic Device Discovery
A segment controller (edge server) and edge processor can automatically create logical representations of the discovered devices in IAP/MQ by creating the relevant device configuration, status, and interface object, as described in Device.
This is called automatic discovery.
Automatic discovery can be implicit or explicit. Implicit automatic discovery occurs when a protocol engine automatically detects and creates discovered devices. These can be built-in devices such as those used to manage aspects of that edge protocol, or can be devices that are discovered through other means. Explicit automatic discovery occurs when the protocol engines discover devices through automatic periodic scanning, which occurs in the background. This behavior is controlled with the segment configuration object (see the discovery property).
Automatically discovered devices can be created as IAP/MQ devices automatically, provided that the discovering engine can be certain that the discovered device belongs to that instance of the engine. In general, automatically discovered devices are reported with the 2293062, described below.
The edge server suggests a handle for the discovered device, which is unique within the segment and in the device’s protocol. This handle can be used when creating the device in this segment, but it is not required to be used. Creating and deleting devices is discussed in Device Do Action.
Manual Device Discovery
Segment controllers that support manual device discovery accept the discoverDevices action on the glp/0/SID/rq/do action endpoint.
The discoverDevices action supports the options described in Manual Device Discovery Options below.
The discoverDevices action supports an optional response. The response indicates the completion of the search and provides simple statistics. See Device Discovery Completion Object, below.
Manual Device Discovery Options
Field Name | Type | Description |
|---|---|---|
policy | String | (Optional) Can be either fast or slow. The default is fast. The slow policy can enable more time-consuming but more thorough algorithms, and is recommended when the edge network is expected to yield many discovered devices. |
protocols | List of Strings | (Optional) A list of protocol names where device discovery will be performed. When the protocols list is not provided, or empty, device discovery is attempted by all protocol engines that support this method. |
provisioned | Boolean | (Optional) Indicates whether the search looks for provisioned devices. Can be either true or false. The default is false. |
unprovisioned | Boolean | (Optional) Indicates whether the search includes unprovisioned devices. Can be either true or false. The default is true. |
respond | String | (Optional) Indicates where the device discovery completion object will be published at the end of the discovery process. See 2293062. |
meta | Any valid JSON | (Optional) A correlator. When present, this correlator will be included with the device discovery completion object. See 2293062. |
option | Object | (Optional) An object with protocol-specific options. |
Device Discovery Completion Object
When requested, a device discovery completion object is published to the topic specified with the respond argument, once the process is complete. The device discovery completion object is always published with MQTT options qos: 1, and retain: false.
The device discovery completion object has the following properties:
Field Name | Type | Description | |
|---|---|---|---|
meta | Any | A verbatim copy of the meta argument received with the request, if any. | |
discovered | Number | Total number of devices discovered. | |
errors | List of error event objects | A list of error event objects, one for each error encountered. Device discovery errors can be operational errors and logical errors. All are reported with the list of errors within the device discovery completion object. Operational errors are also reported through the IAP/MQ event channel and standard error event reporting procedures. A device discovery operational error is one that relates to the ability, or inability, to execute the requested discovery. Error conditions such as no gateway or no carrier fall into this category. Logical errors are those that arise during successful device discovery. For example, one protocol engine might discover a device but be unable to manage it. Error conditions such as device type unknown or device protocol version unknown fall into this category. | |
protocols | Object | Device discovery summary per protocol. Provisioned and unprovisioned report numbers of successfully discovered and recognized devices. Example:
|
Device Discovery Event Properties
The edge server publishes discovered devices with a device discovery event object on the glp/0/{SID}/ev/discovery/device topic. The device discovery event object is always published with MQTT options qos: 1, and retain: false.
Field Name | Type | Description | |
|---|---|---|---|
cost | Number | An optional cost specified as 0...1, where 0 is best (lowest cost) and 1 is worst. Cost is an abstraction for resources and effort necessary to communicate with the discovered device. The IAP server for a protocol is not required to provide a cost value. For IAP servers that support a cost value, the value may be computed based on the number of networking hops or transmit power required, for example. The value can be used by IAP clients to select the best segment, if more than one segment discovers the same device, by selecting the segment that reports the smallest cost. Example: 0.32 | |
handle | string | A handle for the discovered device. The handle must be unique in the segment. Example: "z3" | |
hops | List | An optional list of LQI (line quality indicator) values for each hop. Values range from 0 to 1, where 1 is best. Can be null. This provides additional information to the "cost" number calculation. The IAP server for a protocol is not required to provide a hops value. For IAP servers that support a hops value, an intelligent algorithm may prefer a higher cost if the LQI across the trip is more leveled, as opposed to one with 2 superb and one poor hop. Example: [ 0.8, 0.7 ] | |
loc | object | An optional location object, if geographical location is known. Can be null. See Location Object for a description. Example:
| |
protocol | string | The device’s Edge Protocol Identifier. See Edge_Protocol_ID in IAP/MQ Topic Syntax. | |
state | string | The device state, as described in the Device Status Object properties table. Example: "unprovisioned" | |
type | string | Device type, as described in type in the Device Status Object properties table. Example: "8000112345604" | |
unid | string | Unique ID, as described in unid in the Device Status Object properties table. Example: "0503C0123451" |