From 2c10442645c9f10f450f8cf4d40ff7a9f4d8fcc6 Mon Sep 17 00:00:00 2001 From: Andrew Fiddian-Green Date: Sun, 8 Dec 2024 14:51:12 +0000 Subject: [PATCH 1/6] Description of syntax for IP suggestion finder service Signed-off-by: Andrew Fiddian-Green --- developers/addons/addon.md | 111 ++++++++++++++++++++++++++++++++++++- 1 file changed, 109 insertions(+), 2 deletions(-) diff --git a/developers/addons/addon.md b/developers/addons/addon.md index 8cd749bc2c..9714376d31 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 meaning of the `match-property` `name` values are explained further as follows: | Name Value | Description | |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------| @@ -128,9 +130,64 @@ 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 meaning 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) | + +#### 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, and in addition to \, there are five XML special characters which need to 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 optionallly 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 +226,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 + .* + + + + + + +``` From b8bf1684077b30327defe2fd85c2770067a260b8 Mon Sep 17 00:00:00 2001 From: Andrew Fiddian-Green Date: Sun, 8 Dec 2024 15:01:16 +0000 Subject: [PATCH 2/6] escape escapes Signed-off-by: Andrew Fiddian-Green --- developers/addons/addon.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/developers/addons/addon.md b/developers/addons/addon.md index 9714376d31..f636ab64da 100644 --- a/developers/addons/addon.md +++ b/developers/addons/addon.md @@ -160,13 +160,13 @@ The `request` and `requestPlain` values may contain special tokens that are dyna In `requestPlain`standard backslash sequences will be translated, and in addition to \, there are five XML special characters which need to be escaped: -| Character | Replacement | -|-----------|-------------| -| & | & | -| < | < | -| > | > | -| " | " | -| ' | ' | +| Character | Replacement | +|-----------|--------------| +| & | && | +| < | &< | +| > | &> | +| " | &" | +| ' | &' | #### IP Discovery: Formatting of substituted MAC address (within `requestPlain`) From fde08b877803e02af254cf3eb694130737a5976a Mon Sep 17 00:00:00 2001 From: Andrew Fiddian-Green Date: Sun, 8 Dec 2024 15:03:52 +0000 Subject: [PATCH 3/6] again.. Signed-off-by: Andrew Fiddian-Green --- developers/addons/addon.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/developers/addons/addon.md b/developers/addons/addon.md index f636ab64da..a01944709f 100644 --- a/developers/addons/addon.md +++ b/developers/addons/addon.md @@ -162,11 +162,11 @@ In `requestPlain`standard backslash sequences will be translated, and in additio | Character | Replacement | |-----------|--------------| -| & | && | -| < | &< | -| > | &> | -| " | &" | -| ' | &' | +| & | \& | +| < | \< | +| > | \> | +| " | \" | +| ' | \' | #### IP Discovery: Formatting of substituted MAC address (within `requestPlain`) From 995d958354e8aa0a8b21b0f1a2eabbeccba5042f Mon Sep 17 00:00:00 2001 From: Andrew Fiddian-Green Date: Sun, 8 Dec 2024 15:09:32 +0000 Subject: [PATCH 4/6] typos and cosmetics Signed-off-by: Andrew Fiddian-Green --- developers/addons/addon.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/developers/addons/addon.md b/developers/addons/addon.md index a01944709f..9b0aaacd22 100644 --- a/developers/addons/addon.md +++ b/developers/addons/addon.md @@ -114,7 +114,7 @@ Notes: ### SDDP Discovery Service Syntax -For the `sddp` service type, the meaning of the `match-property` `name` values are explained further as follows: +For the `sddp` service type, the meanings of the `match-property` `name` values are explained further as follows: | Name Value | Description | |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------| @@ -132,7 +132,7 @@ For the `sddp` service type, the meaning of the `match-property` `name` values a ### IP Discovery Service Syntax -For the `ip` service type, the meaning of the `discovery-parameter` values are explained further as follows: +For the `ip` service type, the meanings of the `discovery-parameter` values are explained further as follows: | Name | Value | |----------------|--------------------------------------------------------------------------------------------------------------------------------------| @@ -158,7 +158,8 @@ The `request` and `requestPlain` values may contain special tokens that are dyna #### IP Discovery: Escaping (within `requestPlain`) -In `requestPlain`standard backslash sequences will be translated, and in addition to \, there are five XML special characters which need to be escaped: +In `requestPlain`standard backslash sequences will be translated. +Plus there are five XML special characters which must be escaped: | Character | Replacement | |-----------|--------------| @@ -172,7 +173,7 @@ In `requestPlain`standard backslash sequences will be translated, and in additio 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 optionallly a single delimiter character. +This comprises a standard Java format specifier string plus *optionally* a single delimiter character. Examples are as follows: | Format Specifier | Result (example) | From 4bd4afe9681652a6e3871d8efa75a4a3b2e71bc4 Mon Sep 17 00:00:00 2001 From: Andrew Fiddian-Green Date: Sun, 8 Dec 2024 17:42:34 +0000 Subject: [PATCH 5/6] fix markdown style warning Signed-off-by: Andrew Fiddian-Green --- developers/addons/addon.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developers/addons/addon.md b/developers/addons/addon.md index 9b0aaacd22..a3fc1a5dd5 100644 --- a/developers/addons/addon.md +++ b/developers/addons/addon.md @@ -173,7 +173,7 @@ Plus there are five XML special characters which must be escaped: 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. +This comprises a standard Java format specifier string plus _optionally_ a single delimiter character. Examples are as follows: | Format Specifier | Result (example) | From 2961984ef1f5412d5242f836da4505386fa5a123 Mon Sep 17 00:00:00 2001 From: Andrew Fiddian-Green Date: Sun, 8 Dec 2024 23:35:58 +0000 Subject: [PATCH 6/6] describe default Signed-off-by: Andrew Fiddian-Green --- developers/addons/addon.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developers/addons/addon.md b/developers/addons/addon.md index a3fc1a5dd5..ba8b5bf2cb 100644 --- a/developers/addons/addon.md +++ b/developers/addons/addon.md @@ -143,7 +143,7 @@ For the `ip` service type, the meanings of the `discovery-parameter` values are | `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) | +| `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`)