Add-on suggestion finder revised schema (#2174)

* Add-on suggestion finder revised schema Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * Adopt reviewer suggestions Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> --------- Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
openhab · Dec 16, 2023 · 1156252 · 1156252
1 parent f6b87ec
commit 1156252
Showing 1 changed file with 20 additions and 11 deletions.
diff --git a/developers/addons/addon.md b/developers/addons/addon.md
@@ -73,21 +73,25 @@ The full XML schema for add-on definitions is specified in the [Add-on XSD](http
 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`.   |
+| 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. e.g. `upnp` or `mdns` etc.                      | Mandatory one per `discovery-method`.              |
+| `discovery-parameters` | Wrapper for `discovery-parameter` elements (see below).                       | Zero or one instances per `discovery-method`.      |
+| `discovery-parameter`  | A parameter name and value used for settings of the add-on finder process.    | Zero or more instances per `discovery-parameters`. |
+| `name`                 | A settings parameter name.                                                    | Mandatory one instance per `discovery-parameter`.  |
+| `value`                | A settings parameter value.                                                   | Mandatory one instance per `discovery-parameter`.  |
+| `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 `match-properties`.     |
+| `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.
+- Different add-on discovery finders may need different `discovery-parameters`. Check the JavaDoc of the respective finder. See the `mdns` example below.
 
 ## Example
 
@@ -110,7 +114,12 @@ The following code gives an example for an add-on definition used in bindings.
   <discovery-methods>
     <discovery-method>
       <serviceType>mdns</serviceType>
-      <mdnsServiceType>_hue._tcp.local.</mdnsServiceType>
+      <discovery-parameters>
+        <discovery-parameter>
+          <name>mdnsServiceType</name>
+          <value>_hue._tcp.local.</value>
+        </discovery-parameter>
+      </discovery-parameters>
     </discovery-method>
     <discovery-method>
       <service-type>upnp</service-type>