Skip to content

Discovery

Dynamic Device Discovery

Overview

Some device protocols allow for devices to be discovered automatically. A Device Service may include a capability for discovering devices and creating the corresponding Device objects within EdgeX. A framework for doing so will be implemented in the Device Service SDKs.

The discovery process will operate as follows:

  • Discovery is triggered either on an internal timer or by a call to a REST endpoint
  • The SDK will call a function provided by the DS implementation to request a device scan
  • The implementation calls back to the SDK with details of devices which it has found
  • The SDK filters these devices against a set of acceptance criteria
  • The SDK adds accepted devices in core-metadata. These are now available in the EdgeX system

Triggering Discovery

A boolean configuration value Device/Discovery/Enabled defaults to false. If this value is set true, and the DS implementation supports discovery, discovery is enabled.

The SDK will respond to POST requests on the the /discovery endpoint. No content is required in the request. This call will return one of the following codes:

  • 202: discovery has been triggered or is already running. The response should indicate which, and contain the correlation id that will be used by any resulting requests for device addition
  • 423: the service is locked (admin state) or disabled (operating state)
  • 500: unknown or unanticipated issues exist
  • 501: discovery is not supported by this protocol implementation
  • 503: discovery is disabled by configuration

In each of the failure cases a meaningful error message should be returned.

In the case where discovery is triggered, the discovery process will run in a new thread or goroutine, so that the REST call may return immediately.

An integer configuration value Device/Discovery/Interval defaults to zero. If this value is set to a positive value, and discovery is enabled, the discovery process will be triggered at the specified interval (in seconds).

Finding Devices

When discovery is triggered, the SDK calls the implementation function provided by the Device Service. This should perform whatever protocol-specific procedure is necessary to find devices, and pass these devices into the SDK by calling the SDK's filtered device addition function.

Note: The implementation should call back for every device found. The SDK is to take responsibility for filtering out devices which have already been added.

The information required for a found device is as follows:

  • An autogenerated device name
  • The Protocol Properties of the device
  • Optionally, a description string
  • Optionally, a list of label strings

The filtered device addition function will take as an argument a collection of structs containing the above data. An implementation may choose to make one call per discovered device, but implementors are encouraged to batch the devices if practical, as in future EdgeX versions it will be possible for the SDK to create all required new devices in a single call to core-metadata.

Rationale: An alternative design would have the implementation function return the collection of discovered devices to the SDK. Using a callback mechanism instead has the following advantages:

  • Allows for asynchronous operation. In this mode the DS implementation will intiate discovery and return immediately. For example discovery may be initiated by sending a broadcast packet. Devices will then send return packets indicating their existence. The thread handling inbound network traffic can on receipt of such packets call the filtered device addition function directly.
  • Allows DS implementations where devices self-announce to call the filtered device addition function independent of the discovery process

Filtered Device Addition

The filter criteria for discovered devices are represented by Provision Watchers. A Provision Watcher contains the following fields:

  • Identifiers: A set of name-value pairs against which a new device's ProtocolProperties are matched
  • BlockingIdentifiers: A further set of name-value pairs which are also matched against a new device's ProtocolProperties
  • Profile: The name of a DeviceProfile which should be assigned to new devices which pass this ProvisionWatcher
  • AdminState: The initial Administrative State for new devices which pass this ProvisionWatcher

A candidate new device passes a ProvisionWatcher if all of the Identifiers match, and none of the BlockingIdentifiers.

For devices with multiple Device.Protocols, each Device.Protocol is considered separately. A pass (as described above) on any of the protocols results in the device being added.

The values specified in Identifiers are regular expressions.

Note: If a discovered Device is manually removed from EdgeX, it will be necessary to adjust the ProvisionWatcher via which it was added, either by making the Identifiers more specific or by adding BlockingIdentifiers, otherwise the Device will be re-added the next time Discovery is initiated.

Note: ProvisionWatchers are stored in core-metadata. A facility for managing ProvisionWatchers is needed, eg edgex-cli could be extended