Initial commit

2018-09-24 00:37:59 +08:00
commit f3c152e76b
106 changed files with 10005 additions and 0 deletions
@@ -0,0 +1,154 @@
+# KLF-200 Adapter Dokumentation
+
+Dieser Adapter dient zur Steuerung einer VELUX® KLF-200-Schnittstelle. Dieser Adapter ist weder ein offizielles VELUX Produktnoch wird er von der Firma unterstützt, die die VELUX-Produkte besitzt.
+
+Der Hauptzweck dieses Adapters ist die Steuerung von elektrischen Dachfenstern und / oder elektrischen Jalousien oder Rollläden.
+Die Schnittstelle KLF-200 ist jedoch in der Lage, weitere Geräte wie Lampen, Schalter, Jalousien etc. anzuschließen.
+Ich habe den Adapter nicht für die Verwendung mit diesen Geräten entwickelt. So könnte es möglich sein,
+dass diese Geräte auch von diesem Adapter gesteuert werden können.
+
+Der Adapter arbeitet mit der internen REST-API der KLF-200-Schnittstelle und Sie müssen weder die Eingänge noch die Ausgänge anschließen, obwohl es immer noch möglich ist, diese parallel zu verwenden.
+
+---
+
+## Bereiten Sie Ihre KLF-200-Schnittstelle vor
+
+Um diesen Adapter verwenden zu können, müssen Sie Ihre KLF-200 Box im **Schnittstellenmodus** einrichten. Es funktioniert nicht, wenn Sie Ihre Box als Repeater verwenden.
+
+> Für eine detaillierte Erklärung der folgenden Aufgaben lesen Sie bitte die mit der Box mitgelieferten Handbücher.
+>
+> Es wird davon ausgegangen, dass Sie sich in einem Webbrowser erfolgreich bei Ihrer Box angemeldet haben.
+
+### Produkte einrichten
+
+Jedes Produkt, das Sie mit diesem Adapter steuern möchten, muss auf der Seite "Meine Produkte" registriert sein.
+Sie können neue Produkte registrieren entweder durch
+
+- Kopieren von einer anderen Fernbedienung
+- Suche nach Produkten
+
+Wenn alle Ihre Produkte registriert sind, sollten Sie eine Liste wie die folgende sehen:
+
+![Screenshot of "My products" of the KLF-200 interface](img/ProductList.PNG)
+
+### Szenen einrichten
+
+Um eine Szene aufzunehmen, klicken Sie auf die Schaltfläche
+
+![Record program button](img/RecordProgramButton.PNG)
+
+Dies öffnet das Fenster *Programmerstellung in Bearbeitung*. Verwenden Sie jetzt die mit Ihrem Produkt gelieferte Fernbedienung, um etwas zu ändern, z.B. öffne das Fenster zu 40%. Geben Sie dann einen Namen für das Programm ein und klicken Sie auf *Programm speichern*.
+
+![Screenshot of Recording in progress](img/RecordingInProgress.PNG)
+
+> TIPP:
+> - Benennen Sie Ihr Programm nach Produkt und Öffnungsgrad, zum Beispiel Fenster Badezimmer 40%. Der Adapter verwendet allerdings keine Namenskonventionen.
+> - Wenn Ihr Fenster geschlossen ist, beginnen Sie mit einem Öffnungsgrad von 100% und gehen Sie mit jedem weiteren Programm weiter nach unten bis Sie 0% erreichen.
+> - Sie haben maximal 32 Programme, die Sie in der Box speichern können.Planen Sie daher Ihre Anzahl an Schritten, da es keinen wirklichen Unterschied zwischen einem zu 30% oder zu 40% geöffnetem Fenster gibt.
+
+Wenn Sie mit der Aufnahme von Programmen fertig sind, erhalten Sie eine Liste wie folgt:
+
+![Screenshot of the program list](img/ProgramList.PNG)
+
+### Verbindungen einrichten
+
+Dieser letzte Schritt ist optional. Wenn Sie die Eingangs- und Ausgangsleitungen nicht verwenden, haben Sie vielleicht bemerkt, dass die kleine LED an der Box ständig blinkt. Um das lästige Blinken loszuwerden, müssen Sie mindestens eine Verbindung einrichten.
+
+Sie müssen es nur in der Box einrichten, Sie müssen nichts verkabeln! Wählen Sie einfach irgendetwas aus.
+
+---
+
+## Konfigurieren Sie den Adapter
+
+![Screenshot of the adapter configuration](img/AdapterConfiguration.PNG)
+
+### Host
+
+Hostname Ihrer KLF-200-Schnittstelle. Dies ist die gleiche Adresse, die Sie in der Adressleiste Ihres Webbrowsers zum Verbinden mit Ihrer Box eintragen.
+
+### Passwort
+
+Das Passwort, das Sie für die Verbindung mit Ihrer KLF-200-Schnittstelle benötigen. Es ist das gleiche, das Sie bei der Verbindung in Ihrem Webbrowser verwenden.
+
+> Das Standardpasswort des KLF-200 ist `velux123`, aber Sie sollten es trotzdem geändert haben!
+
+### Abfragehäufigkeit in Minuten
+
+<span style="color: #ff0000"><strong><em>Diese Option ist für eine zukünftige Version geplant. Wenn Sie die Konfiguration neu laden möchten, müssen Sie den Adapter neu starten.</em></strong></span>
+
+Die Anzahl der Minuten, nach der der Adapter die Konfiguration erneut von der KLF-200-Schnittstelle lädt.
+
+---
+
+## Benutzung des Adapters
+
+Nachdem der Adapter die Metadaten von der KLF-200-Schnittstelle gelesen hat, finden Sie die folgenden Zustände
+im Objektbaum:
+
+Gerät | Kanal | Zustand | Datentyp | Beschreibung
+--- | --- | --- | --- | ---
+products |  |  |  | Hat für jedes Produkt in der Produktliste des KLF-200 einen Untereintrag.
+products |  | productsFound | value | Die Anzahl der Produkte in der Liste. Schreibgeschützt.
+products | 0..n | category | text | Produktkategorie. Schreibgeschützt.
+products | 0..n | level | level | Aktueller Stand des Produkts Setzen Sie diesen Wert, damit die entsprechende Szene ausgeführt wird. Lesen / Schreiben.
+products | 0..n | scenesCount | value | Anzahl der Szenen, in denen das Produkt verwendet wird. Schreibgeschützt.
+scenes |  |  |  | Hat für jedes Produkt in der Produktliste des KLF-200 einen Untereintrag.
+scenes |  | scenesFound | value | Die Anzahl der Szenen in der Liste. Schreibgeschützt.
+scenes | 0..n | productsCount | value | Anzahl der Produkte in dieser Szene. Schreibgeschützt.
+scenes | 0..n | run | button.play | Zeigt an, ob die Szene läuft. Setzen Sie diesen Wert, damit die Szene ausgeführt wird. Lesen / Schreiben.
+scenes | 0..n | silent | indicator.silent | Gibt an, ob die Szene im leisen Modus ausgeführt wird (sofern dies von den Produkten der Szene unterstützt wird). Schreibgeschützt.
+
+> **WICHTIG:**
+>
+> Die IDs, die in den Kanälen verwendet werden, sind die IDs, die von der KLF-200-Schnittstelle kommen. Wenn Sie Änderungen an der Produktliste oder an der Programmliste in Ihrem KLF-200 vornehmen, können sich die IDs ändern.
+
+Um eine Szene auszuführen, können Sie den Status `run` der Szene auf `true` setzen oder den Status `level` des Produkts auf einen Wert setzen, der einer Szene entspricht, die das Produkt auf dieses Level setzt.
+
+### Beispiel
+
+Angenommen, Ihr Badezimmerfenster liegt auf Kanal `0`. Sie haben eine Szene auf Kanal `10`, die das Badezimmerfenster zu 40% öffnet.
+
+```javascript
+// Variant 1: Open the bathroom window at 40% using the scenes run state:
+setState('klf200.0.scenes.10.run', true);
+/* 
+    The following will happen:
+    1. Your window will start to move to 40% opening level.
+    2. After your window has stopped, klf200.0.scenes.10.run will be set to 'false' again.
+    3. klf200.0.products.0.level will be set to 40%.
+*/
+
+// Variant 2: Open the bathroom window at 40% using the products level state:
+setState('klf200.0.products.0.level', 40);
+/*
+    The following will happen:
+    1. Your window will start to move to 40% opening level.
+    2. klf200.0.scenes.10.run will be set to true.
+    3. After your window has stopped, klf200.0.scenes.10.run will be set to 'false' again.
+*/
+
+// What happens, if we don't have a scene for that level?
+setState('klf200.0.products.0.level', 41);
+/*
+    The following will happen:
+    1. Your window won't move at all!
+    2. klf200.0.products.0.level will be reset to the previous value, e.g. 40
+*/
+
+```
+
+---
+
+## Bekannte Einschränkungen
+
+Der Adapter steuert das KLF-200 mithilfe der internen REST-API, die von der Webschnittstelle der Box verwendet wird.
+Obwohl wir nur eine Teilmenge der API verwenden, gibt es einige Einschränkungen:
+
+- Der Adapter kann den aktuellen Öffnungsgrad eines Fensters nicht lesen. Wenn Sie es mit Ihrer Fernbedienung steuern oder es aufgrund von Regen geschlossen wird, weiß der Adapter nichts davon und es wird immer noch der letzte bekannte Wert angezeigt.
+- Die KLF-200-Schnittstelle ist auf maximal 32 Szenen beschränkt.
+- Der Adapter weiß nicht, wann eine Aktion beendet wurde. Der Zustand bleibt für mindestens 30 Sekunden `true`.
+- Führen Sie Szenen nicht zu schnell hintereinander aus. Der KLF-200 kann dann Fehler melden. (Sie finden die Fehler im Protokoll.)
+
+---
+
+VELUX und das VELUX-Logo sind eingetragene Warenzeichen der VKR Holding A/S.
@@ -0,0 +1,151 @@
+# KLF-200 adapter documentation
+
+This adapter is for controlling a VELUX® KLF-200 interface. This adapter is neither an official VELUX product nor is it supported by the company that owns the VELUX products.
+
+The main intention of this adapter is to control electric roof windows and/or electric blinds or roller shutters. Though the KLF-200 interface is able to connect to further devices like lights, switches, canvas blinds etc. I haven't developed the adapter for use with these kind of devices. Thus, it could be possible, that these devices could be controlled by this adapter, too.
+
+The adapter works with the internal REST API of the KLF-200 interface and you don't need to wire the inputs and outputs of the box, though it's still possible to use them in parallel.
+
+----------------------------------------------------------------------------------------------------------------
+
+## Prepare your KLF-200 interface
+
+To use this adapter you have to setup your KLF-200 box in the **interface mode**. It doesn't work if you use your box as a repeater.
+
+> For a detailed explanation of how to accomplish the following tasks please read the manuals that came with your box.
+>
+> It is assumed that you have successfully logged into your box in a web browser.
+
+
+### Setup products
+
+Each product that you want to control by this adapter has to be registered on the "My products" page. You can register new products either by
+- Copy from another remote control
+- Search for products
+
+If all of your products are registered you should see a list like the following:
+
+![Screenshot of "My products" of the KLF-200 interface](img/ProductList.PNG)
+
+
+### Setup scenes
+
+To record a scene you have to click on the button
+
+![Record program button](img/RecordProgramButton.PNG)
+
+This will open the *Recording in progress* window. Now, use your remote control that comes with your product to change something, e.g. open the window to 40%. Then type in a name for the program and click on *Save program*.
+
+![Screenshot of Recording in progress](img/RecordingInProgress.PNG)
+
+> HINT:
+> * Name your program after product and opening level, e.g. Window bathroom 40%, though the adapter doesn't use any naming conventions.
+> * If your window is closed start with an opening level of 100% and go down with each subsequent program until you reach 0%.
+> * You have a maximum of 32 programs you can save in the box. Therefore, plan your number of steps as there is no real difference in a window opened 30% or 40%.
+
+If you have finished recording programs you will end with a list like the following:
+
+![Screenshot of the program list](img/ProgramList.PNG)
+
+
+### Setup connections
+
+This last step is optional. If you don't use the input and output wires you may have noticed that the tiny LED on the box is flashing all the time. To get rid of the annoying flashing you have to setup at least one connection.
+
+You only have to set it up in the box you don't need to wire anything! Just choose anything you like.
+
+----------------------------------------------------------------------------------------------------------------
+
+## Configure the adapter
+
+![Screenshot of the adapter configuration](img/AdapterConfiguration.PNG)
+
+### Host
+
+Host name of your KLF-200 interface. This is the same you type into the address bar of your web browser to connect to your box.
+
+### Password
+
+The password you need to connect to your KLF-200 interface. It's the same you use when connecting to your box in your web browser.
+
+> The default password of the KLF-200 is `velux123`, but you should have changed it, anyway!
+
+### Polling interval in minutes
+
+<span style="color: #ff0000">**_This option is planned for a future release. If you want to reload the configuratio you have to restart the adapter._**</span>
+
+The number of minutes after which the adapter reloads the configuration from the KLF-200 interface again.
+
+----------------------------------------------------------------------------------------------------------------
+
+## Use the adapter
+
+After the adapter has read the meta data from the KLF-200 interface you will find the following states in the object tree:
+
+Device   | Channel | State         | Data type        | Description
+---------|---------|---------------|------------------|------------------------------------------------------
+products |         |               |                  | Has a sub-entry for each product found in the product list of the KLF-200.
+products |         | productsFound | value            | The number of products in the list. Read-only.
+products | 0..n    | category      | text             | Category of the product. Read-only.
+products | 0..n    | level         | level            | Current level of the product. Set to run the corresponding scene. Read/write.
+products | 0..n    | scenesCount   | value            | Number of scenes in which the product is used. Read-only.
+scenes   |         |               |                  | Has a sub-entry for each scene found in the program list of the KLF-200.
+scenes   |         | scenesFound   | value            | The number of scenes in the list. Read-only.
+scenes   | 0..n    | productsCount | value            | Number of products in this scene. Read-only.
+scenes   | 0..n    | run           | button.play      | Indicates if the scene is running. Set to run the scene. Read/write.
+scenes   | 0..n    | silent        | indicator.silent | Indicates if the scene is run in silent mode (if supported by the products of the scene). Read-only.
+
+> **IMPORTANT:**
+>
+> The IDs that are used in the channels are the IDs coming from the KLF-200 interface. If you make changes at the products list or at the program list in your KLF-200 the IDs may change.
+
+To run a scene you can either set the `run` state of the scene to `true` or you can set the `level` state of the product to a value that corresponds to a scene that sets the product to that level.
+
+### Example
+
+Assuming your bathroom window is channel `0`. You have a scene on Channel `10` that opens the bathroom window at 40%.
+
+````javascript
+// Variant 1: Open the bathroom window at 40% using the scenes run state:
+setState('klf200.0.scenes.10.run', true);
+/* 
+    The following will happen:
+    1. Your window will start to move to 40% opening level.
+    2. After your window has stopped, klf200.0.scenes.10.run will be set to 'false' again.
+    3. klf200.0.products.0.level will be set to 40%.
+*/
+
+// Variant 2: Open the bathroom window at 40% using the products level state:
+setState('klf200.0.products.0.level', 40);
+/*
+    The following will happen:
+    1. Your window will start to move to 40% opening level.
+    2. klf200.0.scenes.10.run will be set to true.
+    3. After your window has stopped, klf200.0.scenes.10.run will be set to 'false' again.
+*/
+
+// What happens, if we don't have a scene for that level?
+setState('klf200.0.products.0.level', 41);
+/*
+    The following will happen:
+    1. Your window won't move at all!
+    2. klf200.0.products.0.level will be reset to the previous value, e.g. 40
+*/
+
+````
+
+
+----------------------------------------------------------------------------------------------------------------
+
+## Known limitations
+
+The adapter controls the KLF-200 using the internal REST API that is used by the web interface of the box. Though we use only a subset of the API there are some restrictions:
+
+* The adapter can't read the current opening level of a window. If you control it with your remote control or it will be closed due to rain the adapter doesn't know about it and it will still show the last known value.
+* The KLF-200 interface is limited to a maximum of 32 scenes.
+* The adapter doesn't know, when an action has finished. The running state will stay `true` for at least 30 seconds.
+* Don't run scenes to fast after each other. The KLF-200 may throw errors. (You will find the errors in the log.)
+
+----------------------------------------------------------------------------------------------------------------
+
+VELUX and the VELUX logo are registered trademarks of VKR Holding A/S.
@@ -0,0 +1,3 @@
+# KLF-200 adapter documentation
+
+Please help me translating the documentation into your language. Details can be found at [issue #9](https://github.com/MiSchroe/yunkong2.klf200/issues/9).
@@ -0,0 +1,3 @@
+# KLF-200 adapter documentation
+
+Please help me translating the documentation into your language. Details can be found at [issue #9](https://github.com/MiSchroe/yunkong2.klf200/issues/9).
@@ -0,0 +1,3 @@
+# KLF-200 adapter documentation
+
+Please help me translating the documentation into your language. Details can be found at [issue #9](https://github.com/MiSchroe/yunkong2.klf200/issues/9).
@@ -0,0 +1,3 @@
+# KLF-200 adapter documentation
+
+Please help me translating the documentation into your language. Details can be found at [issue #9](https://github.com/MiSchroe/yunkong2.klf200/issues/9).
@@ -0,0 +1,3 @@
+# KLF-200 adapter documentation
+
+Please help me translating the documentation into your language. Details can be found at [issue #9](https://github.com/MiSchroe/yunkong2.klf200/issues/9).
@@ -0,0 +1,3 @@
+# KLF-200 adapter documentation
+
+Please help me translating the documentation into your language. Details can be found at [issue #9](https://github.com/MiSchroe/yunkong2.klf200/issues/9).
@@ -0,0 +1,3 @@
+# KLF-200 adapter documentation
+
+Please help me translating the documentation into your language. Details can be found at [issue #9](https://github.com/MiSchroe/yunkong2.klf200/issues/9).