From ff44c289271338fdabed532a356a0b3ab5f07d5d Mon Sep 17 00:00:00 2001 From: Andrew Fiddian-Green Date: Tue, 7 Mar 2023 22:17:52 +0000 Subject: [PATCH] [velux] Update documentation (#14478) * [velux] update documentation Signed-off-by: Andrew Fiddian-Green --- bundles/org.openhab.binding.velux/README.md | 120 ++++++++++---------- 1 file changed, 63 insertions(+), 57 deletions(-) diff --git a/bundles/org.openhab.binding.velux/README.md b/bundles/org.openhab.binding.velux/README.md index d9c892c17f24b..ea7c8a561600e 100644 --- a/bundles/org.openhab.binding.velux/README.md +++ b/bundles/org.openhab.binding.velux/README.md @@ -42,7 +42,7 @@ The binding supports the following types of Thing. | information | A Thing that provides overall information about the binding itself. | | 1. Only supported in hubs with firmware v0.2.x.x or above -2. Only needed in hubs with firmware v0.1.x.x (due to note 1. above) +1. Only needed in hubs with firmware v0.1.x.x (due to note 1. above) ## Discovery @@ -95,7 +95,7 @@ For your convenience you'll see a log entry for the recognized configuration wit ### Thing Configuration for "actuator", "window", "rollershutter" -These types of Thing only supported in the Velux Bridge in API version two or higher (firmware version > 0.2.*.*). +These types of Thing only supported in the Velux Bridge in API version two or higher (firmware version > 0.2.\*.\*). These types of Thing are configured by means of their serial number in the hub. In addition there are some optional Configuration Parameters. @@ -107,15 +107,21 @@ In addition there are some optional Configuration Parameters. Notes: -1. To enable a complete inversion of all parameter values (i.e. for Velux windows), use the property `inverted` or add a trailing star to the eight-byte serial number. - For an example, see the Thing definition for 'Bathroom_Roof_Window' below. +1. To enable a complete inversion of all parameter values use the property `inverted` or add a trailing star to the eight-byte serial number. -2. Somfy devices do not provide a valid serial number to the Velux KLF200 Bridge. +1. Somfy devices do not provide a valid serial number to the Velux KLF200 Bridge. For such devices you have to enter the special all-zero serial number 00:00:00:00:00:00:00:00 in the `serial` parameter. This special serial number complies with the serial number validation checks, but also makes the binding use the `name` parameter value instead of the `serial` parameter value when it communicates with the KLF Bridge. The `name` parameter must therefore contain the name that you gave to the actuator when you first registered it in the KLF200 Bridge. For an example, see the Thing definition for 'Living_Room_Awning' below. +The impact of the `inverted` parameter on the open/close position of the device, when a command is sent, is shown in the table below.. + +| Inverted Parameter | UP Button Pressed | DOWN Button Pressed | Slider Position 0% | Slider Position 100% | Switch Command OFF | Switch Command ON | +|--------------------|-------------------|---------------------|--------------------|----------------------|--------------------|-------------------| +| `inverted` = false | Device is open | Device is closed | Device is open | Device is closed | Device is open | Device is closed | +| `inverted` = true | Device is closed | Device is open | Device is closed | Device is open | Device is closed | Device is open | + ### Thing Configuration for "scene" The Velux Bridge in API version one (firmware version 0.1.1.*) allows activating a set of predefined actions, so called scenes. @@ -260,10 +266,10 @@ The bridge Thing provides the following properties. ```java Bridge velux:klf200:g24 "Velux KLF200 Hub" @ "Under Stairs" [ipAddress="192.168.1.xxx", password="secret"] { - // Velux (standard) window (with serial number) - Thing window Bathroom_Roof_Window "Bathroom Roof Window" @ "Bathroom" [serial="56:36:13:5A:11:2A:05:70", inverted=true] + // Velux (standard) window (with serial number) + Thing window Bathroom_Roof_Window "Bathroom Roof Window" @ "Bathroom" [serial="56:36:13:5A:11:2A:05:70"] - // Somfy (non-standard) rollershutter (without serial number) + // Somfy (non-standard) rollershutter (without serial number) Thing rollershutter Living_Room_Awning "Living Room Awning" @ "Living Room" [serial="00:00:00:00:00:00:00:00", name="Living Room Awning"] } ``` @@ -282,7 +288,7 @@ See [items.md](doc/items.md) for more examples. ```perl Frame label="Velux Windows" { - Slider item=Bathroom_Roof_Window_Position + Slider item=Bathroom_Roof_Window_Position } ``` @@ -314,13 +320,13 @@ Example: ```java rule "Simultaneously Move Main and Vane Positions" when - ... + ... then // note: "velux:klf200:hubid" shall be the thing name of your KLF 200 hub - val veluxActions = getActions("velux", "velux:klf200:hubid") - if (veluxActions !== null) { - val succeeded = veluxActions.moveMainAndVane("velux:rollershutter:hubid:thingid", 75, 25) - } + val veluxActions = getActions("velux", "velux:klf200:hubid") + if (veluxActions !== null) { + val succeeded = veluxActions.moveMainAndVane("velux:rollershutter:hubid:thingid", 75, 25) + } end ``` @@ -335,28 +341,28 @@ Example: ```java rule "V_WINDOW_changed" when - Item V_WINDOW changed + Item V_WINDOW changed then - logInfo("rules.V_WINDOW", "V_WINDOW_changes() called.") - // Get the sensor value - val Number windowState = V_WINDOW.state as DecimalType - logWarn("rules.V_WINDOW", "Window state is " + windowState + ".") - if (windowState < 80) { - if (windowState == 0) { - logWarn("rules.V_WINDOW", "V-WINDOW changed to fully open.") - var int interval = 1 - createTimer(now.plusMinutes(interval)) [ | - logWarn("rules.V_WINDOW:event", "event-V_WINDOW(): setting V-WINDOW to 100.") - sendCommand(V_WINDOW, 100) - V_WINDOW.postUpdate(100) - logWarn("rules.V_WINDOW:event", "event-V_WINDOW done.") - ] - } else { - logWarn("rules.V_WINDOW", "V-WINDOW changed to partially open.") - } - } - // Check type of item - logDebug("rules.V_WINDOW", "V_WINDOW_changes finished.") + logInfo("rules.V_WINDOW", "V_WINDOW_changes() called.") + // Get the sensor value + val Number windowState = V_WINDOW.state as DecimalType + logWarn("rules.V_WINDOW", "Window state is " + windowState + ".") + if (windowState < 80) { + if (windowState == 0) { + logWarn("rules.V_WINDOW", "V-WINDOW changed to fully open.") + var int interval = 1 + createTimer(now.plusMinutes(interval)) [ | + logWarn("rules.V_WINDOW:event", "event-V_WINDOW(): setting V-WINDOW to 100.") + sendCommand(V_WINDOW, 100) + V_WINDOW.postUpdate(100) + logWarn("rules.V_WINDOW:event", "event-V_WINDOW done.") + ] + } else { + logWarn("rules.V_WINDOW", "V-WINDOW changed to partially open.") + } + } + // Check type of item + logDebug("rules.V_WINDOW", "V_WINDOW_changes finished.") end ``` @@ -375,15 +381,15 @@ Example: ```java rule "Reboot KLF 200" when - ... + ... then - val veluxActions = getActions("velux", "velux:klf200:myhubname") - if (veluxActions !== null) { - val isRebooting = veluxActions.rebootBridge() - logWarn("Rules", "Velux KLF 200 rebooting: " + isRebooting) - } else { - logWarn("Rules", "Velux KLF 200 actions not found, check thing ID") - } + val veluxActions = getActions("velux", "velux:klf200:myhubname") + if (veluxActions !== null) { + val isRebooting = veluxActions.rebootBridge() + logWarn("Rules", "Velux KLF 200 rebooting: " + isRebooting) + } else { + logWarn("Rules", "Velux KLF 200 actions not found, check thing ID") + } end ``` @@ -395,18 +401,18 @@ You can exploit this behaviour in a rule to check regularly if a window has been ```java rule "Every 10 minutes, check if window is in manual mode" when - Time cron "0 0/10 * * * ?" // every 10 minutes + Time cron "0 0/10 * * * ?" // every 10 minutes then - if (Velux_Window.state != UNDEF) { - // command the window to its actual position; this will either - // - succeed: the actual position will not change, or - // - fail: the position becomes UNDEF (logged next time this rule executes) - Velux_Window.sendCommand(Velux_Window.state) - } else { - logWarn("Rules", "Velux in Manual mode, trying to close again") - // try to close it - Velux_Window.sendCommand(0) - } + if (Velux_Window.state != UNDEF) { + // command the window to its actual position; this will either + // - succeed: the actual position will not change, or + // - fail: the position becomes UNDEF (logged next time this rule executes) + Velux_Window.sendCommand(Velux_Window.state) + } else { + logWarn("Rules", "Velux in Manual mode, trying to close again") + // try to close it + Velux_Window.sendCommand(0) + } end ``` @@ -446,9 +452,9 @@ This, of course, is possible on command line with the commands: On the other hand, if you prefer a textual configuration, you can append the logging definition with: ```text - - - + + + ``` During startup of normal operations, there should be only some few messages within the logfile, like: