Package org.openhab.core.config.discovery

Interface DiscoveryService

All Known Implementing Classes:
AbstractDiscoveryService, AbstractThingHandlerDiscoveryService, SddpDiscoveryService
@NonNullByDefault public interface DiscoveryService
The DiscoveryService is a service interface which each binding can implement to provide an auto discovery process for one or more Thing s.

As an example, a typical discovery mechanism could scan the network for UPnP devices, if requested.

A DiscoveryService must be able to finish its discovery process without any user interaction.

There are two different kind of executions:

  • Background discovery: If this mode is enabled, the discovery process should run in the background as long as this mode is not disabled again. Background discovery can be enabled and disabled and is configured through the configuration admin. The implementation class that registers an OSGi service must define a PID and has to react on configuration changes for it. See also CONFIG_PROPERTY_BACKGROUND_DISCOVERY.
  • Active scan: If an active scan is triggered, the the service should try to actively query for new devices and should report new results within the defined scan timeout. An active scan can be aborted.
Author:
Michael Grammling - Initial contribution, Kai Kreuzer - Refactored API, Dennis Nobel - Added background discovery configuration through Configuration Admin, Laurent Garnier - Added discovery with an optional input parameter
See Also:

  • Field Details

    • CONFIG_PROPERTY_BACKGROUND_DISCOVERY

      static final String CONFIG_PROPERTY_BACKGROUND_DISCOVERY
      Configuration property for enabling the auto discovery feature of a DiscoveryService.
      See Also:

  • Method Details

    • getSupportedThingTypes

      Collection<ThingTypeUID> getSupportedThingTypes()
      Returns the list of Thing types which are supported by the DiscoveryService.
      Returns:
      the list of Thing types which are supported by the discovery service (not null, could be empty)

    • isScanInputSupported

      boolean isScanInputSupported()
      Returns true if the discovery supports an optional input parameter to run, otherwise false.
      Returns:
      true if the discovery supports an optional input parameter to run, otherwise false

    • getScanInputLabel

      @Nullable String getScanInputLabel()
      Returns the label of the supported input parameter to start the discovery.
      Returns:
      the label of the supported input parameter to start the discovery or null if input parameter not supported

    • getScanInputDescription

      @Nullable String getScanInputDescription()
      Returns the description of the supported input parameter to start the discovery.
      Returns:
      the description of the supported input parameter to start the discovery or null if input parameter not supported

    • getScanTimeout

      int getScanTimeout()
      Returns the amount of time in seconds after which an active scan ends.
      Returns:
      the scan timeout in seconds (>= 0).

    • isBackgroundDiscoveryEnabled

      boolean isBackgroundDiscoveryEnabled()
      Returns true if the background discovery mode is enabled, otherwise false.
      Returns:
      true if the background discovery mode is enabled, otherwise false

    • startScan

      void startScan(@Nullable ScanListener listener)
      Triggers this service to start an active scan for new devices.
      This method must not block any calls such as abortScan() and must return fast.

      If started, any registered DiscoveryListener must be notified about DiscoveryResults.

      If there is already a scan running, it is aborted and a new scan is triggered.

      Parameters:
      listener - a listener that is notified about errors or termination of the scan

    • startScan

      void startScan(String input, @Nullable ScanListener listener)
      Triggers this service to start an active scan for new devices using an input parameter for that.
      This method must not block any calls such as abortScan() and must return fast.

      If started, any registered DiscoveryListener must be notified about DiscoveryResults.

      If there is already a scan running, it is aborted and a new scan is triggered.

      Parameters:
      input - an input parameter to be used during discovery scan
      listener - a listener that is notified about errors or termination of the scan

    • abortScan

      void abortScan()
      Stops an active scan for devices.
      This method must not block any calls such as startScan(org.openhab.core.config.discovery.ScanListener) and must return fast.

      After this method returns, no further notifications about DiscoveryResults are allowed to be sent to any registered listener, exceptional the background discovery mode is active.

      This method returns silently, if the scan has not been started before.

    • addDiscoveryListener

      void addDiscoveryListener(@Nullable DiscoveryListener listener)
      Adds a DiscoveryListener to the listeners' registry.

      Directly after registering the listener, it will receive DiscoveryListener.thingDiscovered(DiscoveryService, DiscoveryResult) notifications about all devices that have been previously discovered by the service already (tracker behaviour). This is also done, if the listener has already been registered previously.

      When a DiscoveryResult is created while the discovery process is active (e.g. by starting a scan or through the enabled background discovery mode), the specified listener is notified.

      This method returns silently if the specified listener is null.

      Parameters:
      listener - the listener to be added (could be null)

    • removeDiscoveryListener

      void removeDiscoveryListener(@Nullable DiscoveryListener listener)
      Removes a DiscoveryListener from the listeners' registry.

      When this method returns, the specified listener is no longer notified about a created DiscoveryResult while the discovery process is active (e.g. by forcing the startup of the discovery process or while enabling the auto discovery mode)

      This method returns silently if the specified listener is null or has not been registered before.

      Parameters:
      listener - the listener to be removed (could be null)