From 78acb0c6b6628154828d8967f6e4a84b550505a6 Mon Sep 17 00:00:00 2001 From: Andrew Fiddian-Green Date: Thu, 30 May 2024 16:20:54 +0100 Subject: [PATCH] Documentation for SDDP discovery (#2298) Signed-off-by: Andrew Fiddian-Green --- developers/addons/addon.md | 2 ++ developers/bindings/index.md | 22 +++++++++++++++++++--- 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/developers/addons/addon.md b/developers/addons/addon.md index 50ef9f252..495a2ce0a 100644 --- a/developers/addons/addon.md +++ b/developers/addons/addon.md @@ -92,6 +92,7 @@ Optionally, if you want the system to scan the user's network for your addon the | `ip` | Service to discover add-ons by scanning for devices via a UDP 'ping' broadcast on the LAN. | | `mdns` | Service to discover add-ons by scanning for devices using the mDNS discovery service. | | `processs` | Service to discover add-ons by checking processes running on the PC. | +| `sddp` | Service to discover add-ons by scanning for devices using the SDDP discovery service. | | `upnp` | Service to discover add-ons by scanning for devices using the UPnP discovery service. | | `usb` | Service to discover add-ons by scanning for USB devices attached to the PC. | @@ -107,6 +108,7 @@ Notes: | `ip` | "response". | | `mdns` | Frequently used properties are "name", and "application". But mDNS permits any property name depending on the service concerned. | | `process` | "command", "commandLine". | +| `sddp` | "driver", "host", "ipAddress", "macAddress", "manufacturer", "model", "port", "primaryProxy", "proxies", "type" | | `upnp` | "deviceType", "manufacturer", "manufacturerURI", "modelName", "modelNumber", "modelDescription", "modelURI", "serialNumber", "friendlyName". | | `usb` | "product", "manufacturer", "chipId", "remote". | diff --git a/developers/bindings/index.md b/developers/bindings/index.md index 2c94704da..84c8e5455 100644 --- a/developers/bindings/index.md +++ b/developers/bindings/index.md @@ -661,9 +661,9 @@ To simplify the implementation of custom discovery services, an abstract base cl Subclasses of `AbstractDiscoveryService` do not need to handle the `DiscoveryListeners` themselves, they can use the methods `thingDiscovered` and `thingRemoved` to notify the registered listeners. Most of the descriptions in this chapter refer to the `AbstractDiscoveryService`. -For UPnP and mDNS there already are generic discovery services available. -Bindings only need to implement a `UpnpDiscoveryParticipant` resp. `mDNSDiscoveryParticipant`. -For details refer to the chapters [UPnP Discovery](#upnp-discovery) and [mDNS Discovery](#mdns-discovery). +For UPnP, mDNS and SDDP there already are generic discovery services available. +Bindings only need to implement a `UpnpDiscoveryParticipant`, `mDNSDiscoveryParticipant` resp. `SddpDiscoveryParticipant`. +For details refer to the chapters [UPnP Discovery](#upnp-discovery), [mDNS Discovery](#mdns-discovery) and [SDDP Discovery](#sddp-discovery). The following example is taken from the `HueLightDiscoveryService`, it calls `thingDiscovered` for each found light. It uses the `DiscoveryResultBuilder` to create the discovery result. @@ -853,6 +853,7 @@ The developer has to take care about that. UPnP discovery is implemented in the framework as `UpnpDiscoveryService`. It is widely used in bindings. To facilitate the development, binding developers only need to implement a `UpnpDiscoveryParticipant`. +Additionally one must add `openhab-transport-upnp` to the binding's `feature.xml` file. Here the developer only needs to implement three simple methods, and may optionally implement a fourth: - `getSupportedThingTypeUIDs` - Returns the list of thing type UIDs that this participant supports. @@ -973,6 +974,21 @@ Here the developer only needs to implement four simple methods: To prevent this, a binding may OPTIONALLY implement this method to specify an additional delay period (grace period) to wait before the device is removed from the Inbox. See the example code for the `getRemovalGracePeriodSeconds()` method under the "UPnP Discovery" chapter above. +### SDDP Discovery + +SDDP discovery is implemented in the framework as `SddpDiscoveryService`. +To facilitate the development, binding developers only need to implement a `SddpDiscoveryParticipant`. +Additionally one must add `openhab-core-config-discovery-sddp` to the binding's `feature.xml` file. +Here the developer only needs to implement four simple methods: + +- `getSupportedThingTypeUIDs` - Returns the list of thing type UIDs that this participant supports. + The discovery service uses this method of all registered discovery participants to return the list of currently supported thing type UIDs. +- `getThingUID` - Creates a thing UID out of the SDDP service info or returns `null` if this is not possible. + This method is called from the discovery service during result creation to provide a unique thing UID for the result. +- `createResult` - Creates the `DiscoveryResult` out of the SDDP result. + This method is called from the discovery service to create the actual discovery result. + It uses the `getThingUID` method to create the thing UID of the result. + ### Discovery that is bound to a Bridge When the discovery process is dependent on a configured bridge the discovery service must be bound to the bridge handler.