Extra fields for addon discovery in addon.xml (#2150)
* Add description of discovery-methods Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * Add description of discovery-methods Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> * [developers-addons-addon] fix markdown errors Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch> --------- Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>pull/2170/head
Andrew Fiddian-Green
GitHub
parent
b86d50201c
commit
ae491a7957
|
|
@ -38,6 +38,10 @@ If the add-on consists of more than one bundle, only one `addon.xml` is allowed
|
|||
OR
|
||||
<config-description-ref uri="{addon|thing-type|channel-type|any_other}:addonID:..." />
|
||||
|
||||
<discovery-methods>
|
||||
...
|
||||
</discovery-methods>
|
||||
|
||||
</addon:addon>
|
||||
```
|
||||
|
||||
|
|
@ -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.
|
|||
|
||||
<connection>local</connection>
|
||||
|
||||
<discovery-methods>
|
||||
<discovery-method>
|
||||
<serviceType>mdns</serviceType>
|
||||
<mdnsServiceType>_hue._tcp.local.</mdnsServiceType>
|
||||
</discovery-method>
|
||||
<discovery-method>
|
||||
<service-type>upnp</service-type>
|
||||
</match-properties>
|
||||
<match-property>
|
||||
<name>modelName</name>
|
||||
<regex>Philips hue bridge</regex>
|
||||
</match-property>
|
||||
</match-properties>
|
||||
</discovery-method>
|
||||
</discovery-methods>
|
||||
|
||||
</addon:addon>
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue