OpenHAB
/
openhab-addons
mirror of https://github.com/openhab/openhab-addons.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[velux] Update documentation (#14478) 

* [velux] update documentation

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
pull/14603/head
Andrew Fiddian-Green 2023-03-07 22:17:52 +00:00 committed by GitHub
parent dba5550ae6
commit c9d5784d36
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 63 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
bundles/org.openhab.binding.velux/README.md
View File

@ -42,7 +42,7 @@ The binding supports the following types of Thing.
| information | A Thing that provides overall information about the binding itself. | | | information | A Thing that provides overall information about the binding itself. | |
1. Only supported in hubs with firmware v0.2.x.x or above 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 ## 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" ### 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. These types of Thing are configured by means of their serial number in the hub.
In addition there are some optional Configuration Parameters. In addition there are some optional Configuration Parameters.
@ -107,15 +107,21 @@ In addition there are some optional Configuration Parameters.
Notes: 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. 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.
For an example, see the Thing definition for 'Bathroom_Roof_Window' below.
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. 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. 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. 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. 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" ### 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. 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 ```java
Bridge velux:klf200:g24 "Velux KLF200 Hub" @ "Under Stairs" [ipAddress="192.168.1.xxx", password="secret"] { Bridge velux:klf200:g24 "Velux KLF200 Hub" @ "Under Stairs" [ipAddress="192.168.1.xxx", password="secret"] {
// Velux (standard) window (with serial number) // 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] 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"] 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 ```perl
Frame label="Velux Windows" { Frame label="Velux Windows" {
Slider item=Bathroom_Roof_Window_Position Slider item=Bathroom_Roof_Window_Position
} }
``` ```
@ -314,13 +320,13 @@ Example:
```java ```java
rule "Simultaneously Move Main and Vane Positions" rule "Simultaneously Move Main and Vane Positions"
when when
... ...
then then
// note: "velux:klf200:hubid" shall be the thing name of your KLF 200 hub // note: "velux:klf200:hubid" shall be the thing name of your KLF 200 hub
val veluxActions = getActions("velux", "velux:klf200:hubid") val veluxActions = getActions("velux", "velux:klf200:hubid")
if (veluxActions !== null) { if (veluxActions !== null) {
val succeeded = veluxActions.moveMainAndVane("velux:rollershutter:hubid:thingid", 75, 25) val succeeded = veluxActions.moveMainAndVane("velux:rollershutter:hubid:thingid", 75, 25)
} }
end end
``` ```
@ -335,28 +341,28 @@ Example:
```java ```java
rule "V_WINDOW_changed" rule "V_WINDOW_changed"
when when
Item V_WINDOW changed Item V_WINDOW changed
then then
logInfo("rules.V_WINDOW", "V_WINDOW_changes() called.") logInfo("rules.V_WINDOW", "V_WINDOW_changes() called.")
// Get the sensor value // Get the sensor value
val Number windowState = V_WINDOW.state as DecimalType val Number windowState = V_WINDOW.state as DecimalType
logWarn("rules.V_WINDOW", "Window state is " + windowState + ".") logWarn("rules.V_WINDOW", "Window state is " + windowState + ".")
if (windowState < 80) { if (windowState < 80) {
if (windowState == 0) { if (windowState == 0) {
logWarn("rules.V_WINDOW", "V-WINDOW changed to fully open.") logWarn("rules.V_WINDOW", "V-WINDOW changed to fully open.")
var int interval = 1 var int interval = 1
createTimer(now.plusMinutes(interval)) [ | createTimer(now.plusMinutes(interval)) [ |
logWarn("rules.V_WINDOW:event", "event-V_WINDOW(): setting V-WINDOW to 100.") logWarn("rules.V_WINDOW:event", "event-V_WINDOW(): setting V-WINDOW to 100.")
sendCommand(V_WINDOW, 100) sendCommand(V_WINDOW, 100)
V_WINDOW.postUpdate(100) V_WINDOW.postUpdate(100)
logWarn("rules.V_WINDOW:event", "event-V_WINDOW done.") logWarn("rules.V_WINDOW:event", "event-V_WINDOW done.")
] ]
} else { } else {
logWarn("rules.V_WINDOW", "V-WINDOW changed to partially open.") logWarn("rules.V_WINDOW", "V-WINDOW changed to partially open.")
} }
} }
// Check type of item // Check type of item
logDebug("rules.V_WINDOW", "V_WINDOW_changes finished.") logDebug("rules.V_WINDOW", "V_WINDOW_changes finished.")
end end
``` ```
@ -375,15 +381,15 @@ Example:
```java ```java
rule "Reboot KLF 200" rule "Reboot KLF 200"
when when
... ...
then then
val veluxActions = getActions("velux", "velux:klf200:myhubname") val veluxActions = getActions("velux", "velux:klf200:myhubname")
if (veluxActions !== null) { if (veluxActions !== null) {
val isRebooting = veluxActions.rebootBridge() val isRebooting = veluxActions.rebootBridge()
logWarn("Rules", "Velux KLF 200 rebooting: " + isRebooting) logWarn("Rules", "Velux KLF 200 rebooting: " + isRebooting)
} else { } else {
logWarn("Rules", "Velux KLF 200 actions not found, check thing ID") logWarn("Rules", "Velux KLF 200 actions not found, check thing ID")
} }
end end
``` ```
@ -395,18 +401,18 @@ You can exploit this behaviour in a rule to check regularly if a window has been
```java ```java
rule "Every 10 minutes, check if window is in manual mode" rule "Every 10 minutes, check if window is in manual mode"
when when
Time cron "0 0/10 * * * ?" // every 10 minutes Time cron "0 0/10 * * * ?" // every 10 minutes
then then
if (Velux_Window.state != UNDEF) { if (Velux_Window.state != UNDEF) {
// command the window to its actual position; this will either // command the window to its actual position; this will either
// - succeed: the actual position will not change, or // - succeed: the actual position will not change, or
// - fail: the position becomes UNDEF (logged next time this rule executes) // - fail: the position becomes UNDEF (logged next time this rule executes)
Velux_Window.sendCommand(Velux_Window.state) Velux_Window.sendCommand(Velux_Window.state)
} else { } else {
logWarn("Rules", "Velux in Manual mode, trying to close again") logWarn("Rules", "Velux in Manual mode, trying to close again")
// try to close it // try to close it
Velux_Window.sendCommand(0) Velux_Window.sendCommand(0)
} }
end 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: On the other hand, if you prefer a textual configuration, you can append the logging definition with:
```text ```text
<logger name="org.openhab.binding.velux" level="TRACE"> <logger name="org.openhab.binding.velux" level="TRACE">
<appender-ref ref="FILE" /> <appender-ref ref="FILE" />
</logger> </logger>
``` ```
During startup of normal operations, there should be only some few messages within the logfile, like: During startup of normal operations, there should be only some few messages within the logfile, like: