Skip to content

Commit 1855cbd

Browse files
andrewfgandrewfg
authored
Documentation for IP addon discovery service (#2422)
* Description of syntax for IP suggestion finder service Signed-off-by: Andrew Fiddian-Green <[email protected]> * escape escapes Signed-off-by: Andrew Fiddian-Green <[email protected]> * again.. Signed-off-by: Andrew Fiddian-Green <[email protected]> * typos and cosmetics Signed-off-by: Andrew Fiddian-Green <[email protected]> * fix markdown style warning Signed-off-by: Andrew Fiddian-Green <[email protected]> * describe default Signed-off-by: Andrew Fiddian-Green <[email protected]> --------- Signed-off-by: Andrew Fiddian-Green <[email protected]>
1 parent 9b148b7 commit 1855cbd

File tree

1 file changed

+110
-2
lines changed

1 file changed

+110
-2
lines changed

‎developers/addons/addon.md‎

Lines changed: 110 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,9 @@ Notes:
112112
| `upnp` | "deviceType", "manufacturer", "manufacturerURI", "modelName", "modelNumber", "modelDescription", "modelURI", "serialNumber", "friendlyName". |
113113
| `usb` | "product", "manufacturer", "chipId", "remote". |
114114

115-
For the `sddp` service type, the meaning of the `match-property` `name` values is explained further as follows:
115+
### SDDP Discovery Service Syntax
116+
117+
For the `sddp` service type, the meanings of the `match-property` `name` values are explained further as follows:
116118

117119
| Name Value | Description |
118120
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
@@ -128,9 +130,65 @@ For the `sddp` service type, the meaning of the `match-property` `name` values i
128130
| `port` | The port part of the 'from' field. For example: 1902 (a String value) |
129131
| `macAddress` | The MAC address of the device as derived from the last 12 characters of the host field. It is presented in lower-case, dash delimited, format. For example: e0-da-dc-15-28-02 Therefore it may be used as a (unique) sub- part of a Thing UID. |
130132

133+
### IP Discovery Service Syntax
134+
135+
For the `ip` service type, the meanings of the `discovery-parameter` values are explained further as follows:
136+
137+
| Name | Value |
138+
|----------------|--------------------------------------------------------------------------------------------------------------------------------------|
139+
| `type` | Either `ipMulticast` or `ipBroadcast` |
140+
| `destIp` | Destination IP address e.g. 192.168.1.1 |
141+
| `destPort` | Destination port e.g. 4000 |
142+
| `listenPort` | Port to use for listening to responses (optional) privileged ports (<1024) not allowed |
143+
| `request` | Description of request frame as hex bytes separated by spaces (e.g. 0x01 0x02 ...) with dynamic replacement of variables (see below) |
144+
| `requestPlain` | Description of request frame as plaintext string dynamic replacement of variables (see below) and escaped as required (see below) |
145+
| `timeoutMs` | Timeout to wait for answers |
146+
| `fmtMac` | Format specifier string for mac address (see below); if no parameter is defined the default is `%02X:` |
147+
148+
#### IP Discovery: Substitution Tokens (within `request` and `requestPlain`)
149+
150+
The `request` and `requestPlain` values may contain special tokens that are dynamically replaced by actual variables at runtime as follows:
151+
152+
| Token | Will Be Replaced By |
153+
|------------|-----------------------------------------------------------------------------------------------|
154+
| `$srcIp` | The actual source IP address |
155+
| `$srcPort` | The actual source port |
156+
| `$srcMac` | The actual source mac address formatted according to the `fmtMac` parameter value (see below) |
157+
| `$uuid` | String returned by java.util.UUID.randomUUID() |
158+
159+
#### IP Discovery: Escaping (within `requestPlain`)
160+
161+
In `requestPlain`standard backslash sequences will be translated.
162+
Plus there are five XML special characters which must be escaped:
163+
164+
| Character | Replacement |
165+
|-----------|--------------|
166+
| & | \&amp; |
167+
| < | \&lt; |
168+
| > | \&gt; |
169+
| " | \&quot; |
170+
| ' | \&apos; |
171+
172+
#### IP Discovery: Formatting of substituted MAC address (within `requestPlain`)
173+
174+
In `requestPlain` the `$srcMac` token will be converted to the actual source MAC address.
175+
It will be rendered according to the `fmtMac` parameter value.
176+
This comprises a standard Java format specifier string plus _optionally_ a single delimiter character.
177+
Examples are as follows:
178+
179+
| Format Specifier | Result (example) |
180+
|------------------|-------------------------|
181+
| %02X | 01020304AABBCCDD |
182+
| %02x- | 01-02-03-04-aa-bb-cc-dd |
183+
| %02X: | 01:02:03:04:AA:BB:CC:DD |
184+
| aardvark | throws exception |
185+
| %02Xaardvark | throws exception |
186+
131187
## Example
132188

133-
The following code gives an example for an add-on definition used in bindings.
189+
The following code gives examples for add-on definitions used in bindings.
190+
191+
### Example for mDNS Service
134192

135193
```xml
136194
<?xml version="1.0" encoding="UTF-8"?>
@@ -169,3 +227,53 @@ The following code gives an example for an add-on definition used in bindings.
169227

170228
</addon:addon>
171229
```
230+
231+
### Example for IP Service
232+
233+
```xml
234+
<?xml version="1.0" encoding="UTF-8"?>
235+
<addon:addon id="wiz" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
236+
xmlns:addon="https://openhab.org/schemas/addon/v1.0.0"
237+
xsi:schemaLocation="https://openhab.org/schemas/addon/v1.0.0 https://openhab.org/schemas/addon-1.0.0.xsd">
238+
239+
<type>binding</type>
240+
<name>WiZ Binding</name>
241+
<description>Binding for WiZ smart devices.</description>
242+
<connection>local</connection>
243+
244+
<discovery-methods>
245+
<discovery-method>
246+
<service-type>ip</service-type>
247+
<discovery-parameters>
248+
<discovery-parameter>
249+
<name>type</name>
250+
<value>ipBroadcast</value>
251+
</discovery-parameter>
252+
<discovery-parameter>
253+
<name>destPort</name>
254+
<value>38899</value>
255+
</discovery-parameter>
256+
<discovery-parameter>
257+
<name>requestPlain</name>
258+
<value>{"method":"registration","id":1,"params":{"phoneIp":"$srcIp","register":false,"phoneMac":"$srcMac"}}</value>
259+
</discovery-parameter>
260+
<discovery-parameter>
261+
<name>fmtMac</name>
262+
<value>%02X</value>
263+
</discovery-parameter>
264+
<discovery-parameter>
265+
<name>timeoutMs</name>
266+
<value>5000</value>
267+
</discovery-parameter>
268+
</discovery-parameters>
269+
<match-properties>
270+
<match-property>
271+
<name>response</name>
272+
<regex>.*</regex>
273+
</match-property>
274+
</match-properties>
275+
</discovery-method>
276+
</discovery-methods>
277+
278+
</addon:addon>
279+
```

0 commit comments

Comments
 (0)