docs(update): Documentation up to date

xaviml · Feb 7, 2020 · 86de1d2 · 86de1d2
1 parent f608f20
commit 86de1d2
Show file tree

Hide file tree

Showing 30 changed files with 327 additions and 123 deletions.
diff --git a/README.md b/README.md
@@ -13,93 +13,25 @@
 
 _Bring full functionality to light and media player controllers. From turning devices on/off to changing the color lights._
 
-This automation brings the following functionalities for different [devices](https://github.com/xaviml/controllerx/wiki/Supported-controllers):
+## Quick example
 
-- Turn on/Turn off light(s)
-- Toggle light(s)
-- Manual increase/decrease of brightness and color temperature
-- Smooth increase/decrease (holding button) of brightness and color temperature
-- Color loop changing if the light supports xy color.
-- Play/pause music
-- Volume up/down for a media player.
-
-This project gives support now to controllers integrated with zigbee2mqtt, deCONZ and ZHA.
-
-## Installation
-
-### HACS
-
-The easiest way to add this to your Homeassistant installation is using HACS with Appdaemon enabled. And then follow the instructions under Configuration below.
-
-### Manual
-
-Download the `controllerx` directory from inside the `apps` directory here to your local `apps` directory, then add the configuration to enable the `controllerx` module.
-
-## Update
-
-Note that AppDaemon will need to be restarted when installing a new version of ControllerX. This is due to AppDaemon not reimporting the modules again. If AppDaemon server is not restarted, then it will keep executing the old version.
-
-## Configuration
-
-This is an example configuration template:
-
-```yaml
-nameOfYourInstanceApp:
-  module: controllerx
-  class: <class of your controller>
-  controller: <controller entity id>
-  integration: <z2m | deconz | zha>
-  light: <light, group entity id>
-```
-
-or:
-
-```yaml
-nameOfYourInstanceApp:
-  module: controllerx
-  class: <class of your controller>
-  controller: <controller entity id>
-  integration: <z2m | deconz | zha>
-  light:
-    name: <light, group entity id>
-    color_mode: auto | xy_color | color_temp
-```
-
-This is a real example for E1524/E1810 controller with z2m that controls all the livingroom lights.
+With just this configuration, you can have the E1810 controller from IKEA (5 buttons one) connected to the bedroom light and be able to change the brightness and color temperature or color.
 
 ```yaml
 livingroom_controller:
   module: controllerx
   class: E1810Controller
   controller: sensor.livingroom_controller_action
   integration: z2m
-  light: group.livingroom_lights
-```
-
-This is a real example to control a media player with E1744 with deCONZ:
-
-```yaml
-bedroom_speaker:
-  module: controllerx
-  class: E1744MediaPlayerController
-  controller: symfonisk_controller
-  integration: deconz
-  media_player: media_player.bedroom_speaker
+  light: light.bedroom
 ```
 
-These are the generic app parameters for all type of controllers. You can see the rest in [here](https://github.com/xaviml/controllerx/wiki/Controller-types)
+## Documentation
 
-| key            | optional | type           | default     | example                                           | description                                                                                                                                                                                                                                                                            |
-| -------------- | -------- | -------------- | ----------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `module`       | False    | string         | -           | `controllerx`                                     | The Python module                                                                                                                                                                                                                                                                      |
-| `class`        | False    | string         | -           | `E1810Controller`                                 | The Python class. Check the classes for each controller on the [supported controllers](https://github.com/xaviml/controllerx/wiki/Supported-controllers) page.                                                                                                                         |
-| `controller`   | False    | string \| list | -           | `sensor.controller` or `hue_switch1, hue_switch2` | This is the controller id. This will change depending on the integration. In case of `z2m` is the name of the sensor in HA, it normally finishes with `_action`. For `deconz` is the device name given on the phoscon app. And finally, for `zha` is the device IEEE.                  |
-| `integration`  | False    | string         | -           | `z2m`, `deconz` or `zha`                          | This is the integration that the device was integrated.                                                                                                                                                                                                                                |
-| `actions`      | True     | list           | All actions |                                                   | This is a list of actions to be included and controlled by the app. To see which actions has each controller check the [supported controllers](https://github.com/xaviml/controllerx/wiki/Supported-controllers) page                                                                  |
-| `action_delta` | True     | int            | 300         |                                                   | This is the threshold time between the previous action and the next one (being the same action). If the time difference between the two actions is less than this attribute, then the action won't be called. I recommend changing this if you see the same action being called twice. |
+You can check the documentation in [here](https://xaviml.github.io/controllerx/).
 
 ## Contributing
 
 If you want to contribute to this project, check [CONTRIBUTING.md](/CONTRIBUTING.md).
 
-_Note: The code does not use any MQTT calls, just the Home Assistant API from AppDaemon._
+_Note: The code does not use any MQTT calls, just the Home Assistant plugin from AppDaemon._
diff --git a/docs/_data/controllers/E1524_E1810.yml b/docs/_data/controllers/E1524_E1810.yml
@@ -49,4 +49,3 @@ integrations:
       - "hold_3328_0 🠖 Hold >"
       - "stop 🠖 Release 🔆 or 🔅"
       - "release 🠖 Release < or >"
-img: https://www.zigbee2mqtt.io/images/devices/E1524-E1810.jpg
diff --git a/docs/_data/controllers/E1743.yml b/docs/_data/controllers/E1743.yml
@@ -27,4 +27,3 @@ integrations:
       - "move_with_on_off_0_83 🠖 Hold \"I\""
       - "move_1_83 🠖 Hold \"O\""
       - "stop 🠖 Release \"I\" or \"O\"" 
-img: https://www.zigbee2mqtt.io/images/devices/E1743.jpg
diff --git a/docs/_data/controllers/E1744.yml b/docs/_data/controllers/E1744.yml
@@ -0,0 +1,33 @@
+name: E1744 (IKEA)
+device_support: 
+  - Light (E1744LightController; 1200ms delay)
+  - Media Player (E1744MediaPlayerController; 1000ms delay)
+integrations:
+  - name: Zigbee2mqtt
+    codename: z2m
+    actions:
+      - "rotate_left 🠖 Left turn"
+      - "rotate_right 🠖 Right turn"
+      - "rotate_stop 🠖 Stop rotation"
+      - "play_pause 🠖 1 click"
+      - "skip_forward 🠖 3 click"
+      - "skip_backward 🠖 3 click"
+  - name: deCONZ
+    codename: deconz
+    actions:
+      - "2001 🠖 Left turn"
+      - "3001 🠖 Right turn"
+      - "2003 🠖 Stop left rotation"
+      - "3003 🠖 Stop right rotation"
+      - "1002 🠖 1 click"
+      - "1004 🠖 3 click"
+      - "1005 🠖 3 click"
+  - name: ZHA
+    codename: zha
+    actions:
+      - "move_1_195 🠖 Left turn"
+      - "move_0_195 🠖 Right turn"
+      - "stop 🠖 Stop rotation"
+      - "toggle 🠖 1 click"
+      - "step_0_1_0 🠖 3 click"
+      - "step_1_1_0 🠖 3 click"
diff --git a/docs/_data/controllers/ICTCG1.yml b/docs/_data/controllers/ICTCG1.yml
@@ -20,4 +20,3 @@ integrations:
       - "move_with_on_off_0_195 🠖 Faster right turn"
       - "move_to_level_with_on_off_255_1 🠖 Quick right turn"
       - "stop 🠖 Stop rotation, either direction (except after quick right/left turns)"
-img: https://www.zigbee2mqtt.io/images/devices/ICTC-G-1.jpg
diff --git a/docs/_data/controllers/double-key-wireless.yml b/docs/_data/controllers/double-key-wireless.yml
@@ -0,0 +1,21 @@
+name: Double key wireless (Aqara)
+device_support: 
+  - Light (E1810Controller; 350ms delay)
+integrations:
+  - name: Zigbee2mqtt
+    codename: z2m
+    actions:
+      - "both 🠖 Click on both"
+      - "both_double 🠖 Double click on both"
+      - "both_long 🠖 Long click on both"
+      - "left 🠖 Click on left"
+      - "left_double 🠖 Double click on left"
+      - "left_long 🠖 Long click on left"
+      - "right 🠖 Click on right"
+      - "right_double 🠖 Double click on right"
+      - "right_long 🠖 Long click on right"
+note: >-
+  Note that all actions related to both, left and right, do the same. 
+  This is because ControllerX is design to control just one entity (light or media player).
+  So you can include the `actions` parameter to include the actions needed.
+  You can check <a href="https://github.com/xaviml/controllerx/issues/18#issuecomment-582535634">here</a> for reference.
diff --git a/docs/_data/controllers/hue-dimmer-switch.yml b/docs/_data/controllers/hue-dimmer-switch.yml
@@ -0,0 +1,34 @@
+name: Hue Dimmer switch (Philips)
+device_support: 
+  - Light (E1744LightController; 350ms delay)
+integrations:
+  - name: Zigbee2mqtt
+    codename: z2m
+    actions:
+      - "on-press 🠖 Click \"I\""
+      - "on-hold 🠖 Hold \"I\""
+      - "on-hold-release 🠖 Release \"I\""
+      - "up-press 🠖 Click 🔆"
+      - "up-hold 🠖 Hold 🔆"
+      - "up-hold-release 🠖 Release 🔆"
+      - "down-press 🠖 Click 🔅"
+      - "down-hold 🠖 Hold 🔅"
+      - "down-hold-release 🠖 Release 🔅"
+      - "off-press 🠖 Click \"O\""
+      - "off-hold 🠖 Hold \"O\""
+      - "off-hold-release 🠖 Release \"O\""
+  - name: deCONZ
+    codename: deconz
+    actions:
+      - "1000 🠖 Click \"I\""
+      - "1001 🠖 Hold \"I\""
+      - "1003 🠖 Release \"I\""
+      - "2000 🠖 Click 🔆"
+      - "2001 🠖 Hold 🔆"
+      - "2003 🠖 Release 🔆"
+      - "3000 🠖 Click 🔅"
+      - "3001 🠖 Hold 🔅"
+      - "3003 🠖 Release 🔅"
+      - "4000 🠖 Click \"O\""
+      - "4001 🠖 Hold \"O\""
+      - "4003 🠖 Release \"O\""
diff --git a/docs/_layouts/controller.html b/docs/_layouts/controller.html
@@ -5,14 +5,16 @@
 {% assign controller = site.data.controllers[page.device] %} {% assign
 integration_names = controller.integrations | map: "codename" | join: ", " %}
 <div>
-  <img src="{{ controller.img }}" />
-
   <table>
     <tr>
-      <th>Device support</th>
+      <th>Picture</th>
+      <th>
+        <a href="/controllerx/start/type-configuration">Controller types</a>
+      </th>
       <th>Integrations</th>
     </tr>
     <tr>
+      <td><img src="/controllerx/assets/img/{{ page.device }}.jpeg" /></td>
       <td>
         <ul>
           {% for device_support in controller.device_support %}
@@ -25,6 +27,9 @@
   </table>
 
   <div>
+    {% if controller.note %}
+    <h3>Note</h3>
+    {{controller.note}} {% endif %}
     <h3>Integrations</h3>
     Here you will see the actions that the controller fires when pressing or
     holding the buttons. In case of z2m it shows the state that the sensor

diff --git a/docs/assets/img/E1524_E1810.jpeg b/docs/assets/img/E1524_E1810.jpeg
diff --git a/docs/assets/img/E1743.jpeg b/docs/assets/img/E1743.jpeg
diff --git a/docs/assets/img/E1744.jpeg b/docs/assets/img/E1744.jpeg
diff --git a/docs/assets/img/ICTCG1.jpeg b/docs/assets/img/ICTCG1.jpeg
diff --git a/docs/assets/img/double-key-wireless.jpeg b/docs/assets/img/double-key-wireless.jpeg
diff --git a/docs/assets/img/hue-dimmer-switch.jpeg b/docs/assets/img/hue-dimmer-switch.jpeg
diff --git a/docs/controllers/E1524_E1810.md b/docs/controllers/E1524_E1810.md
@@ -1,5 +1,5 @@
 ---
 layout: controller
-title: E1524/E1810
+title: E1524/E1810 (IKEA)
 device: E1524_E1810
 ---
diff --git a/docs/controllers/E1743.md b/docs/controllers/E1743.md
@@ -1,5 +1,5 @@
 ---
 layout: controller
-title: E1743
+title: E1743 (IKEA)
 device: E1743
 ---
diff --git a/docs/controllers/E1744.md b/docs/controllers/E1744.md
@@ -0,0 +1,5 @@
+---
+layout: controller
+title: E1744 (IKEA)
+device: E1744
+---
diff --git a/docs/controllers/ICTCG1.md b/docs/controllers/ICTCG1.md
@@ -1,5 +1,5 @@
 ---
 layout: controller
-title: ICTCG1
+title: ICTCG1 (IKEA)
 device: ICTCG1
 ---
diff --git a/docs/controllers/double-key-wireless.md b/docs/controllers/double-key-wireless.md
@@ -0,0 +1,5 @@
+---
+layout: controller
+title: Double key wireless (Aqara)
+device: double-key-wireless
+---
diff --git a/docs/controllers/hue-dimmer-switch.md b/docs/controllers/hue-dimmer-switch.md
@@ -0,0 +1,5 @@
+---
+layout: controller
+title: Hue Dimmer switch (Philips)
+device: hue-dimmer-switch
+---
diff --git a/docs/controllers/index.md b/docs/controllers/index.md
@@ -17,7 +17,7 @@ title: Supported controllers
     <tr>
             <td><a href="/controllerx/controllers/{{key}}">{{ controller.name }}</a></td>
             <td>{{ integration_names }}</td>
-            <td><img src="{{controller.img}}"></td>
+            <td><img src="/controllerx/assets/img/{{ key }}.jpeg" /></td>
     </tr>
     {% endfor %}
 </table>
diff --git a/docs/how-to/extract-controller-id.md b/docs/how-to/extract-controller-id.md
@@ -0,0 +1,16 @@
+---
+title: How to extract the controller parameter
+layout: page
+---
+
+### Zigbee2mqtt
+
+The name you need to add to the `controller` parameter can be found in `Configuration > Integrations > MQTT` and then select the controller. Then you will see the action sensor that by default finishes in `_action` or `_click`. The parameter you need is the entity id of the sensor.
+
+### deCONZ
+
+In case of deCONZ, you can go to `Developer Tools > Events` then down the bottom you can subscribe for `deconz_event` and start listening. Then press any button and you will see event of the button, you will need to copy the `id` inside the `data` object.
+
+### ZHA
+
+In case of ZHA, you can go to `Developer Tools > Events` then down the bottom you can subscribe for `zha_event` and start listening. Then press any button and you will see event of the button, you will need to copy the `device_ieee` inside the `data` object. It is a number like the following 00:67:88:56:06:78:9b:3f.
diff --git a/docs/how-to/run-appdaemon.md b/docs/how-to/run-appdaemon.md
@@ -0,0 +1,9 @@
+---
+title: What's AppDaemon and why I need it
+layout: page
+---
+
+AppDaemon let's you run Home Assistant automation with Python code, instead of yaml configuration.
+When it comes simple automations, yaml or the Automation editor are great, but if the automation gets more complicated, then it gets more difficult to control through yaml, this is where AppDaemon comes into place.
+
+This is the reason this project is built on top of AppDaemon. Now you might be convinced, but you have no idea of how to install it and set it up. If you are using Home Assistant (FKA hassio), you can install the addon called `AppDaemon 4`. You can follow then the instructions and once is up and running, you can check the [installation](../start/installation) page.
diff --git a/docs/how-to/update.md b/docs/how-to/update.md
@@ -0,0 +1,12 @@
+---
+layout: page
+title: Update
+---
+
+Note that AppDaemon will need to be restarted when installing a new version of ControllerX. This is due to AppDaemon not reimporting the modules again. If AppDaemon server is not restarted, then it will keep executing the old version.
+
+## Update from 2.1.X to 2.2.0
+
+If you are updating from 2.1.X to 2.2.0, you will need to change your configuration.
+- If you had `sensor` parameter, then you will need to change it to `controller` and add a new parameter `integration: z2m`
+- If you had `event_id` parameter, then you will need to change it to `controller` and add a new parameter `integration: deconz`
diff --git a/docs/index.md b/docs/index.md
@@ -36,6 +36,14 @@ livingroom_controller:
 
 ## How to start?
 
-- [Installation](/controllerx/start/installation) or [Update](/controllerx/start/update)
+- [Installation](/controllerx/start/installation)
 - [Configuration](/controllerx/start/configuration)
 - [Supported controllers](/controllerx/controllers)
+
+## Others
+
+- [Update instructions](/controllerx/how-to/update)
+- [Controller types](/controllerx/start/type-configuration)
+- [Real examples](/controllerx/start/examples)
+- [How to extract the controller parameter](how-to/extract-controller-id)
+- [What's AppDaemon and why I need it](how-to/run-appdaemon)