From 1855cbd758b33cd5dce302ec281d74ca072c3e0b Mon Sep 17 00:00:00 2001 From: Andrew Fiddian-Green Date: Mon, 9 Dec 2024 21:25:50 +0000 Subject: [PATCH] Documentation for IP addon discovery service (#2422) * Description of syntax for IP suggestion finder service Signed-off-by: Andrew Fiddian-Green * escape escapes Signed-off-by: Andrew Fiddian-Green * again.. Signed-off-by: Andrew Fiddian-Green * typos and cosmetics Signed-off-by: Andrew Fiddian-Green * fix markdown style warning Signed-off-by: Andrew Fiddian-Green * describe default Signed-off-by: Andrew Fiddian-Green --------- Signed-off-by: Andrew Fiddian-Green --- developers/addons/addon.md | 112 ++++++++++++++++++++++++++++++++++++- 1 file changed, 110 insertions(+), 2 deletions(-) diff --git a/developers/addons/addon.md b/developers/addons/addon.md index 8cd749bc2..ba8b5bf2c 100644 --- a/developers/addons/addon.md +++ b/developers/addons/addon.md @@ -112,7 +112,9 @@ Notes: | `upnp` | "deviceType", "manufacturer", "manufacturerURI", "modelName", "modelNumber", "modelDescription", "modelURI", "serialNumber", "friendlyName". | | `usb` | "product", "manufacturer", "chipId", "remote". | -For the `sddp` service type, the meaning of the `match-property` `name` values is explained further as follows: +### SDDP Discovery Service Syntax + +For the `sddp` service type, the meanings of the `match-property` `name` values are explained further as follows: | Name Value | Description | |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------| @@ -128,9 +130,65 @@ For the `sddp` service type, the meaning of the `match-property` `name` values i | `port` | The port part of the 'from' field. For example: 1902 (a String value) | | `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. | +### IP Discovery Service Syntax + +For the `ip` service type, the meanings of the `discovery-parameter` values are explained further as follows: + +| Name | Value | +|----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Either `ipMulticast` or `ipBroadcast` | +| `destIp` | Destination IP address e.g. 192.168.1.1 | +| `destPort` | Destination port e.g. 4000 | +| `listenPort` | Port to use for listening to responses (optional) privileged ports (<1024) not allowed | +| `request` | Description of request frame as hex bytes separated by spaces (e.g. 0x01 0x02 ...) with dynamic replacement of variables (see below) | +| `requestPlain` | Description of request frame as plaintext string dynamic replacement of variables (see below) and escaped as required (see below) | +| `timeoutMs` | Timeout to wait for answers | +| `fmtMac` | Format specifier string for mac address (see below); if no parameter is defined the default is `%02X:` | + +#### IP Discovery: Substitution Tokens (within `request` and `requestPlain`) + +The `request` and `requestPlain` values may contain special tokens that are dynamically replaced by actual variables at runtime as follows: + +| Token | Will Be Replaced By | +|------------|-----------------------------------------------------------------------------------------------| +| `$srcIp` | The actual source IP address | +| `$srcPort` | The actual source port | +| `$srcMac` | The actual source mac address formatted according to the `fmtMac` parameter value (see below) | +| `$uuid` | String returned by java.util.UUID.randomUUID() | + +#### IP Discovery: Escaping (within `requestPlain`) + +In `requestPlain`standard backslash sequences will be translated. +Plus there are five XML special characters which must be escaped: + +| Character | Replacement | +|-----------|--------------| +| & | \& | +| < | \< | +| > | \> | +| " | \" | +| ' | \' | + +#### IP Discovery: Formatting of substituted MAC address (within `requestPlain`) + +In `requestPlain` the `$srcMac` token will be converted to the actual source MAC address. +It will be rendered according to the `fmtMac` parameter value. +This comprises a standard Java format specifier string plus _optionally_ a single delimiter character. +Examples are as follows: + +| Format Specifier | Result (example) | +|------------------|-------------------------| +| %02X | 01020304AABBCCDD | +| %02x- | 01-02-03-04-aa-bb-cc-dd | +| %02X: | 01:02:03:04:AA:BB:CC:DD | +| aardvark | throws exception | +| %02Xaardvark | throws exception | + ## Example -The following code gives an example for an add-on definition used in bindings. +The following code gives examples for add-on definitions used in bindings. + +### Example for mDNS Service ```xml @@ -169,3 +227,53 @@ The following code gives an example for an add-on definition used in bindings. ``` + +### Example for IP Service + +```xml + + + + binding + WiZ Binding + Binding for WiZ smart devices. + local + + + + ip + + + type + ipBroadcast + + + destPort + 38899 + + + requestPlain + {"method":"registration","id":1,"params":{"phoneIp":"$srcIp","register":false,"phoneMac":"$srcMac"}} + + + fmtMac + %02X + + + timeoutMs + 5000 + + + + + response + .* + + + + + + +```