From ae491a79574ff62c076f3ded6a21eaf5701c4d9c Mon Sep 17 00:00:00 2001 From: Andrew Fiddian-Green Date: Fri, 8 Dec 2023 17:10:13 +0000 Subject: [PATCH] Extra fields for addon discovery in addon.xml (#2150) * Add description of discovery-methods Signed-off-by: Andrew Fiddian-Green * Add description of discovery-methods Signed-off-by: Andrew Fiddian-Green * [developers-addons-addon] fix markdown errors Signed-off-by: Andrew Fiddian-Green --------- Signed-off-by: Andrew Fiddian-Green --- developers/addons/addon.md | 42 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/developers/addons/addon.md b/developers/addons/addon.md index c9ace3c938..3b47beaf30 100644 --- a/developers/addons/addon.md +++ b/developers/addons/addon.md @@ -38,6 +38,10 @@ If the add-on consists of more than one bundle, only one `addon.xml` is allowed OR + + ... + + ``` @@ -53,6 +57,7 @@ If the add-on consists of more than one bundle, only one `addon.xml` is allowed | config-description | The configuration description for the binding within the ConfigDescriptionRegistry (cf. [Configuration Description](config-xml.html)) | optional | | config-description-ref | The reference to a configuration description for the binding within the ConfigDescriptionRegistry | optional | | config-description-ref.uri | The URI of the configuration description for the binding within the ConfigDescriptionRegistry | mandatory | +| discovery-methods | A set of xml elements that describe how the system can scan the network to discover present devices | optional | The full XML schema for add-on definitions is specified in the [Add-on XSD](https://openhab.org/schemas/addon-1.0.0.xsd) file. @@ -63,6 +68,27 @@ The full XML schema for add-on definitions is specified in the [Add-on XSD](http - Normally the service id must not be defined, because it is implicitly set to "type.<addonId>". An add-on can register an OSGi service which implements the ManagedService interface and define the service.pid as e.g."binding.hue" to receive the configuration. +### Discovery Methods + +The system can scan the network for present devices to determine if it should suggest to install specific addons during setup. +Optionally, if you want the system to scan the user's network for your addon then you need to include additional `discovery-method` fields. + +| XML Element Name | Description | Instances | +|---------------------|-------------------------------------------------------------------------------|------------------------------------------------| +| `discovery-methods` | Wrapper for `discovery-method` elements (see below). | Zero or one instances per file. | +| `discovery-method` | Complex XML element describing an addon discovery method. | Zero or more instances per file. | +| `service-type` | The type of discovery method. May be `upnp` or `mdns`. | Mandatory one per `discovery-method`. | +| `mdns-service-type` | If `service-type` is `mdns`, contains the MDNS discovery service type. | Optional one per `discovery-method`. | +| `match-properties` | Wrapper for `match-property` elements (see below). | Zero or one instances per `discovery-method`. | +| `match-property` | A property name and regular expression used for matching discovery findings. | Zero or more instances per `discovery-method`. | +| `name` | A property name to search for. | Mandatory one instance per `match-property`. | +| `regex` | A regular expression (or plain string) that needs to match the property name. | Mandatory one instance per `match-property`. | + +Notes: + +- A `discovery-method` may contain multiple `match-property` entries, and in such a case **all** entries must match i.e. it a logical `AND` function is applied. +- If you want to apply a logical `OR` function you can define a second separate `discovery-method` containing the respective `match-property` entry. + ## Example The following code gives an example for an add-on definition used in bindings. @@ -81,5 +107,21 @@ The following code gives an example for an add-on definition used in bindings. local + + + mdns + _hue._tcp.local. + + + upnp + + + modelName + Philips hue bridge + + + + + ```