Add deCONZ component documentation (home-assistant#3967)

Kane610 · MartinHjelmare · commit 943b2e311923 · 2018-01-01T18:35:59.000+01:00
* Deconz hub documentation

* Add binary sensor documentation

* Add sensor documentation

* Add light documentation

* Improve description

* Add information about HASS events from ZHASwitch buttonpresses

* Added description about how entity id naming works

* Added links to dresden elektronik, deconz and deconz rest api
Added automation examples for a IKEA Trådfri dimmer and input number
Added list of supported device types
Added lists of verified to work devices
Removed references to Axis component

* Changed description of how to generate API key

* Added information about configuration variables username and password

* Updated lists of verified devices

* Links from list of supported device to sub modules

* Remove documentation for api_key_generation since functionality has been removed

* Add documentation for configure service

* Documentation for scenes

* Bumped HASS release version to 0.59

* Added Xiaomi Aqara Smart Wireless Switch to list of verified to work devices

* Added improved automation example by simonporter007

* Added information about deCONZ configurator

* Fix raw code

* Added more lights to supported list

* Make description about entity id same in all types

* Updated installation instructions

* Added Dresden Elektroniks logo

* Added Tseels verified to work devices

* Bump ha_release string

* Added information about groups
Added additional verified lights

* Link to information about switch not being an entity on main hub page

* Improved information about switches not being normal entities

* It should be api_key not api-key

* Removed specifying deconz version

* Bump version to 0.61

* Fix typos

* Use configuration tags to describe configuration parameters

* Fix martinhjelamares comments

* Rename parameter service data attribute
diff --git a/source/_components/binary_sensor.deconz.markdown b/source/_components/binary_sensor.deconz.markdown
@@ -0,0 +1,33 @@
+---
+layout: page
+title: "deCONZ Binary Sensor"
+description: "Instructions on how to integrate Zigbee binary sensors from deCONZ into Home Assistant."
+date: 2017-11-12 16:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: deconz.jpeg
+ha_category: Binary Sensor
+ha_release: "0.61"
+ha_iot_class: "Local Push"
+---
+
+See the [deCONZ main component](/components/deconz/) for configuration instructions.
+
+The following sensor types are supported:
+
+ * Open/Close detection
+ * Presence detection
+
+Entity ids will be binary_sensor.device_name, where device_name is defined in deCONZ.
+
+#### {% linkable_title Verified to be supported binary sensors %}
+
+- Open/Close Detection
+  - Xiaomi Smart Home Security Door & Window Contact Sensor
+- Presence Detection
+  - IKEA Trådfri Motion Sensor
+  - Philips Hue Motion Sensor
+  - Xiaomi Motion Sensor
+  - Xiaomi Smart Home Aqara Human Body Sensor
diff --git a/source/_components/deconz.markdown b/source/_components/deconz.markdown
@@ -0,0 +1,148 @@
+---
+layout: page
+title: "deCONZ"
+description: "Instructions on how to setup Conbee/Raspbee devices with deCONZ from Dresden Elektronik within Home Assistant."
+date: 2017-11-12 16:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: deconz.jpeg
+ha_category: Hub
+ha_release: "0.61"
+ha_iot_class: "Local Push"
+---
+
+[deCONZ](https://www.dresden-elektronik.de/funktechnik/products/software/pc/deconz/) by [Dresden Elektronik](https://www.dresden-elektronik.de) is a software that communicates with Conbee/Raspbee Zigbee gateways and exposes Zigbee devices that are connected to the gateway.
+
+[deCONZ REST API](http://dresden-elektronik.github.io/deconz-rest-doc/).
+
+Home Assistant will automatically discover deCONZ presence on your network, if `discovery:` is present in your `configuration.yaml` file.
+
+If you don't have the API key, you can generate an API key for deCONZ by using the one-click functionality similar to Philips Hue. Go to Menu->Settings->Unlock Gateway in deCONZ and then use the deCONZ configurator in Home Assistant GUI to create an API key. When you've generated the API key from Home Assistant, the API key will be stored in deconz.conf inside the home-assistant folder.
+
+You can add the following to your configuration.yaml file if you are not using the `discovery:` component:
+
+```yaml
+# Example configuration.yaml entry
+deconz:
+  host: IP ADDRESS
+```
+
+#### {% linkable_title Supported Device types %}
+
+- [Zigbee Lights](/components/light/deconz/)
+- [Humidity Sensors](/components/sensor/deconz/)
+- [Light Level Sensors](/components/sensor/deconz/)
+- [OpenClose Detectors](/components/binary_sensor/deconz/)
+- [Presence Detectors](/components/binary_sensor/deconz/)
+- [Pressure Sensors](/components/sensor/deconz/)
+- [Switches (Remote Controls)](/components/sensor/deconz/)
+- [Temperature Sensors](/components/sensor/deconz/)
+
+{% configuration %}
+host:
+  description: The IP address of your deCONZ web server.
+  required: false
+  type: string
+api_key:
+  description: The API key to access your deCONZ web server.
+  required: false
+  type: string
+port:
+  description: Configure port deCONZ web server is accessible from.
+  required: false
+  default: 80
+  type: int
+{% endconfiguration %}
+
+A full configuration could look like this:
+
+```yaml
+# Example configuration.yaml entry
+deconz:
+  host: 127.0.0.1
+  api_key: 0123456789
+  port: 80
+```
+
+## {% linkable_title Device services %}
+Available services: `configure`.
+
+#### {% linkable_title Service `deconz/configure` %}
+Set attribute of device in Deconz using [Rest API](http://dresden-elektronik.github.io/deconz-rest-doc/rest/).
+
+| Service data attribute | Optional | Description |
+|-----------|----------|-------------|
+| `field` | No | String representing a specific device in deCONZ. |
+| `data` | No | Data is a JSON object with what data you want to alter. |
+
+{ "field": "/lights/1", "data": {"name": "light2"} }
+
+{ "field": "/config", "data": {"permitjoin": 60} }
+
+## {% linkable_title Remote control devices%}
+
+Remote controls (ZHASwitch category) will be not be exposed as a regular entity, but as events named 'deconz_event' with a payload of 'id' and 'event'. Id will be the device name from deCONZ and Event will be the momentary state of the switch. However, a sensor entity will be created that shows the battery level of the switch as reported by deCONZ, named sensor.device_name_battery_level.
+
+Typical values for switches, the event codes are 4 numbers where the first and last number are of interest here.
+
+| Switch code | Description |
+|-------------|-------------|
+| 1XXX | Button #1 up to #8 |
+| XXX1 | Button hold |
+| XXX2 | Button short release |
+| XXX3 | Button long release |
+
+Where for example on a Philips Hue Dimmer, 2001 would be holding the dim up button.
+
+## {% linkable_title Examples %}
+
+### {% linkable_title Step up and step down input number with wireless dimmer %}
+
+```yaml
+automation:
+  - alias: 'Toggle lamp from dimmer'
+    initial_state: 'on'
+    trigger:
+      platform: event
+      event_type: deconz_event
+      event_data:
+        id: remote_control_1
+        event: 1002
+    action:
+      service: light.toggle
+      entity_id: light.lamp
+
+  - alias: 'Increase brightness of lamp from dimmer'
+    initial_state: 'on'
+    trigger:
+      platform: event
+      event_type: deconz_event
+      event_data:
+        id: remote_control_1
+        event: 2002
+    action:
+      - service: light.turn_on
+        data_template:
+          entity_id: light.lamp
+          brightness: {% raw %}>
+            {% set bri = states.light.lamp.attributes.brightness | int %}
+            {{ [bri+30, 249] | min }}{% endraw %}
+
+  - alias: 'Decrease brightness of lamp from dimmer'
+    initial_state: 'on'
+    trigger:
+      platform: event
+      event_type: deconz_event
+      event_data:
+        id: remote_control_1
+        event: 3002
+    action:
+      - service: light.turn_on
+        data_template:
+          entity_id: light.lamp
+          brightness: {% raw %}>
+            {% set bri = states.light.lamp.attributes.brightness | int %}
+            {{ [bri-30, 0] | max }}{% endraw %}
+```
diff --git a/source/_components/light.deconz.markdown b/source/_components/light.deconz.markdown
@@ -0,0 +1,29 @@
+---
+layout: page
+title: "deCONZ lights"
+description: "Instructions on how to integrate Zigbee lights from deCONZ into Home Assistant."
+date: 2017-11-12 16:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: deconz.jpeg
+ha_category: Light
+ha_release: "0.61"
+ha_iot_class: "Local Push"
+---
+
+See the [deCONZ main component](/components/deconz/) for configuration instructions.
+
+Entity Ids names will be light.device_name, where device_name is defined in deCONZ. Light groups created in deCONZ will be created in Home Assistant as lights named light.group_name_in_deconz, allowing the user to control groups of lights with only a single API call to deCONZ.
+
+#### {% linkable_title Verified to be supported sensors %}
+
+- IKEA Trådfri bulb E14 WS opal 400lm
+- IKEA Trådfri Bulb E27 WS Opal 980lm
+- IKEA Trådfri Bulb E27 WS Opal 1000lm
+- IKEA Trådfri Bulb GU10 W 400lm
+- OSRAM Flex RGBW
+- OSRAM Gardenpole RGBW
+- Philips Hue White A19
+- Philips Hue White Ambiance A19
diff --git a/source/_components/scene.deconz.markdown b/source/_components/scene.deconz.markdown
@@ -0,0 +1,18 @@
+---
+layout: page
+title: "deCONZ scenes"
+description: "Instructions on how to integrate deCONZ scenes into Home Assistant."
+date: 2017-11-19 20:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: deconz.jpeg
+ha_category: Scene
+ha_release: "0.61"
+ha_iot_class: "Local Push"
+---
+
+See the [deCONZ main component](/components/deconz/) for configuration instructions.
+
+Entity Ids will be scene.group_scene_name, where group is which group the scene belongs to and the name of the scene, both group and name are defined in deCONZ.
diff --git a/source/_components/sensor.deconz.markdown b/source/_components/sensor.deconz.markdown
@@ -0,0 +1,45 @@
+---
+layout: page
+title: deCONZ Sensor
+description: "Instructions on how to integrate Zigbee sensors from deCONZ into Home Assistant."
+date: 2017-11-12 16:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: deconz.jpeg
+ha_category: Sensor
+ha_release: "0.61"
+ha_iot_class: "Local Push"
+---
+
+See the [deCONZ main component](/components/deconz/) for configuration instructions.
+
+The following sensor types are supported:
+
+ * Humidity sensor
+ * Light level sensor
+ * Pressure sensor
+ * Switches
+ * Temperature sensor
+
+Entity ids will be sensor.device_name, where device_name is defined in deCONZ. Switches aren't exposed as ordinary entities, see the [deCONZ main component](/components/deconz/) for more details.
+
+#### {% linkable_title Verified to be supported sensors %}
+
+- Humidity Sensor
+  - Xiaomi Aqara Humidity/Temperature Sensor
+  - Xiaomi MiJia Smart Temperature & Humidity Sensor
+- Light Level Sensor
+- Pressure Sensor
+- Switches
+  - IKEA Trådfri Wireless Dimmer
+  - Philips Hue Motion Sensor
+  - IKEA Trådfri Remote
+  - Philips Hue Dimmer Switch
+  - Xiaomi Cube
+  - Xiaomi Aqara Smart Light Switch
+  - Xiaomi Aqara Smart Wireless Switch
+  - Xiaomi Smart Home Wireless Switch
+- Temperature Sensor
+  - Xiaomi Temperature/Humidity Sensor
diff --git a/source/images/supported_brands/deconz.jpeg b/source/images/supported_brands/deconz.jpeg
