From f91615cbb6b991c428713e52ae8328d26ae9e58e Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 30 Oct 2017 07:54:34 +0100 Subject: [PATCH] Fix samples, add title and other changes (#3828) --- source/_components/binary_sensor.knx.markdown | 64 ++++++++++--------- source/_components/climate.knx.markdown | 41 ++++++------ source/_components/cover.knx.markdown | 36 ++++++----- source/_components/knx.markdown | 39 +++++------ source/_components/light.knx.markdown | 18 +++--- source/_components/notify.knx.markdown | 6 +- source/_components/sensor.knx.markdown | 19 +----- 7 files changed, 106 insertions(+), 117 deletions(-) diff --git a/source/_components/binary_sensor.knx.markdown b/source/_components/binary_sensor.knx.markdown index 3b8ed2ec28f..73c747601ad 100644 --- a/source/_components/binary_sensor.knx.markdown +++ b/source/_components/binary_sensor.knx.markdown @@ -18,43 +18,49 @@ The `knx` sensor platform allows you to monitor [KNX](http://www.knx.org) binary The `knx` component must be configured correctly, see [KNX Component](/components/knx). ```yaml +# Example configuration.yaml entry binary_sensor: - - platform: knx - name: "Entrance.Motion.Sensor" - address: '6/0/2' - device_class: 'motion' - #significant_bit: 2 + - platform: knx + name: "Entrance.Motion.Sensor" + address: '6/0/2' + device_class: 'motion' + #significant_bit: 2 ``` -* **name** (*Optional*): A name for this device used within Home Assistant. -* **address**: KNX group address of the binary sensor -* **device_class**: (Optional) HASS device class e.g. "motion" -* **significant_bit**: (Optional) Specify which significant bit of the KNX value should be used. Default is 1. +Configuration variables: + +- **name** (*Optional*): A name for this device used within Home Assistant. +- **address**: KNX group address of the binary sensor. +- **device_class** (Optional): HASS device class e.g. "motion". +- **significant_bit** (Optional): Specify which significant bit of the KNX value should be used. Default is 1. You can also attach actions to binary sensors (e.g., to switch on a light when a switch was pressed). In this example, one light is switched on when the button was pressed once and two others when the button was pressed a second time. ```yaml +# Example configuration.yaml entry binary_sensor: - - platform: knx - name: Livingroom.3Switch3 - address: '5/0/26' - automation: - - counter: 1 - hook: 'on' - action: - - entity_id: light.hue_color_lamp_1 - service: homeassistant.turn_on - - counter: 2 - hook: 'on' - action: - - entity_id: light.hue_bloom_1 - service: homeassistant.turn_on - - entity_id: light.hue_bloom_2 - service: homeassistant.turn_on + - platform: knx + name: Livingroom.3Switch3 + address: '5/0/26' + automation: + - counter: 1 + hook: 'on' + action: + - entity_id: light.hue_color_lamp_1 + service: homeassistant.turn_on + - counter: 2 + hook: 'on' + action: + - entity_id: light.hue_bloom_1 + service: homeassistant.turn_on + - entity_id: light.hue_bloom_2 + service: homeassistant.turn_on ``` -- **name** (*Optional*): A name for this device used within Home Assistant. -- **counter**: (*Optional*) Set to 2 if your only want the action to be executed if the button was pressed twice. To 3 for three times button pressed. Defaults to 1. -- **hook**: (Optional): Indicates if the automation should be executed on what state of the binary sensor. Values: "on" or "off". Defaults to "on". -- **action**: Specify a list of actions analog to the [HASS automation rules](https://home-assistant.io/docs/automation/action/). +Configuration variables: + +- **name** (*Optional*): A name for this device used within Home Assistant. +- **counter** (*Optional*): Set to 2 if your only want the action to be executed if the button was pressed twice. To 3 for three times button pressed. Defaults to 1. +- **hook** (Optional): Indicates if the automation should be executed on what state of the binary sensor. Values: "on" or "off". Defaults to "on". +- **action**: Specify a list of actions analog to the [automation rules](/docs/automation/action/). diff --git a/source/_components/climate.knx.markdown b/source/_components/climate.knx.markdown index c2ce30a811c..1c740bba30c 100644 --- a/source/_components/climate.knx.markdown +++ b/source/_components/climate.knx.markdown @@ -21,6 +21,7 @@ The `knx` component must be configured correctly, see [KNX Component](/component To use your KNX thermostats in your installation, add the following lines to your `configuration.yaml` file: ```yaml +# Example configuration.yaml entry climate: - platform: knx name: HASS-Kitchen.Temperature @@ -33,31 +34,33 @@ climate: Alternatively, if your device has dedicated binary group addresses for frost/night/comfort mode: ```yaml +# Example configuration.yaml entry climate: - - platform: knx - name: HASS-Kitchen.Temperature - temperature_address: '6/2/1' - setpoint_address: '5/1/2' - target_temperature_address: '5/1/1' - operation_mode_frost_protection_address: '5/1/3' - operation_mode_night_address: '5/1/4' - operation_mode_comfort_address: '5/1/5' + - platform: knx + name: HASS-Kitchen.Temperature + temperature_address: '6/2/1' + setpoint_address: '5/1/2' + target_temperature_address: '5/1/1' + operation_mode_frost_protection_address: '5/1/3' + operation_mode_night_address: '5/1/4' + operation_mode_comfort_address: '5/1/5' ``` +Configuration variables: -* **name** (*Optional*): A name for this device used within Home Assistant. -* **temperature_address**: KNX group address for reading current room temperature from KNX bus. -* **target_temperature_address**: KNX group address for reading current target temperature from KNX bus. -* **setpoint_address**: KNX group address for basis setpoint +- **name** (*Optional*): A name for this device used within Home Assistant. +- **temperature_address**: KNX group address for reading current room temperature from KNX bus. +- **target_temperature_address**: KNX group address for reading current target temperature from KNX bus. +- **setpoint_address**: KNX group address for basis setpoint -* **operation_mode_address** (*Optional*) KNX address for operation mode (Frost protection/night/comfort). -* **operation_mode_state_address** (*Optional*) Explicit KNX address for reading operation mode -* **controller_status_address** (*Optional*) KNX address for HVAC controller status (in accordance with KNX AN 097/07 rev 3) -* **controller_status_state_address** (*Optional*) Explicit KNX address for reading HVAC controller status +- **operation_mode_address** (*Optional*): KNX address for operation mode (Frost protection/night/comfort). +- **operation_mode_state_address** (*Optional*): Explicit KNX address for reading operation mode +- **controller_status_address** (*Optional*): KNX address for HVAC controller status (in accordance with KNX AN 097/07 rev 3) +- **controller_status_state_address** (*Optional*): Explicit KNX address for reading HVAC controller status -* **operation_mode_frost_protection_address** (*Optional*) KNX address for switching on/off frost/heat protection mode. -* **operation_mode_night_address** (*Optional*) KNX address for switching on/off night mode. -* **operation_mode_comfort_address** (*Optional*) KNX address for switching on/off comfort mode. +- **operation_mode_frost_protection_address** (*Optional*): KNX address for switching on/off frost/heat protection mode. +- **operation_mode_night_address** (*Optional*): KNX address for switching on/off night mode. +- **operation_mode_comfort_address** (*Optional*): KNX address for switching on/off comfort mode. `operation_mode_frost_protection_address` / `operation_mode_night_address` / `operation_mode_comfort_address` are not necessary if `operation_mode_address` was specified. diff --git a/source/_components/cover.knx.markdown b/source/_components/cover.knx.markdown index a5a6bf65ac7..cd620f15634 100644 --- a/source/_components/cover.knx.markdown +++ b/source/_components/cover.knx.markdown @@ -23,25 +23,27 @@ To use your KNX covers in your installation, add the following to your `configur ```yaml # Example configuration.yaml entry cover: - - platform: knx - name: "Kitchen.Shutter" - move_long_address: '3/0/0' - move_short_address: '3/0/1' - position_address: '3/0/3' - position_state_address: '3/0/2' - travelling_time_down: 51 - travelling_time_up: 61 + - platform: knx + name: "Kitchen.Shutter" + move_long_address: '3/0/0' + move_short_address: '3/0/1' + position_address: '3/0/3' + position_state_address: '3/0/2' + travelling_time_down: 51 + travelling_time_up: 61 ``` +Configuration variables: + - **name** (*Optional*): A name for this device used within Home Assistant. - **move_long_address**: KNX group address for moving the cover full up or down. -- **move_short_address**: (*Optional*) KNX group address for moving the cover short time up or down. -- **position_address**: (*Optional*) KNX group address for moving the cover to the dedicated position. -- **position_state_address**: (*Optional*) Separate KNX group address for requesting the current position of the cover. -- **angle_address**: (*Optional*) KNX group address for moving the cover to the dedicated angle. -- **angle_state_address**: (*Optional*) Separate KNX group address for requesting the current angle of cover. -- **travelling_time_down**: (*Optional*) Time cover needs to travel down in seconds. Needed to calculate the intermediate positions of cover while traveling. Defaults to 25. -- **travelling_time_up**: (*Optional*) Time cover needs to travel up in seconds. Needed to calculate the intermediate positions of cover while traveling. Defaults to 25. -- **invert_position**: (*Optional*) Set this to true if your actuator report fully closed as 100% -- **invert_angle**: (*Optional*) Set this to true if your actuator reports tilt fully closed as 100% +- **move_short_address** (*Optional*): KNX group address for moving the cover short time up or down. +- **position_address** (*Optional*): KNX group address for moving the cover to the dedicated position. +- **position_state_address** (*Optional*): Separate KNX group address for requesting the current position of the cover. +- **angle_address** (*Optional*): KNX group address for moving the cover to the dedicated angle. +- **angle_state_address** (*Optional*): Separate KNX group address for requesting the current angle of cover. +- **travelling_time_down** (*Optional*): Time cover needs to travel down in seconds. Needed to calculate the intermediate positions of cover while traveling. Defaults to 25. +- **travelling_time_up** (*Optional*): Time cover needs to travel up in seconds. Needed to calculate the intermediate positions of cover while traveling. Defaults to 25. +- **invert_position** (*Optional*): Set this to true if your actuator report fully closed as 100%. +- **invert_angle** (*Optional*): Set this to true if your actuator reports tilt fully closed as 100%. diff --git a/source/_components/knx.markdown b/source/_components/knx.markdown index 0143b2302e8..b813ac3aee4 100644 --- a/source/_components/knx.markdown +++ b/source/_components/knx.markdown @@ -13,8 +13,6 @@ ha_release: 0.24 ha_iot_class: "Local Polling" --- -Overview --------- The [KNX](http://www.knx.org) integration for Home Assistant allows you to connect to a KNX/IP devices. @@ -30,8 +28,7 @@ There is currently support for the following device types within Home Assistant: - [Thermostat](/components/climate.knx) - [Notify](/components/notify.knx) -Configuration --------------- +### {% linkable_title Configuration %} To use your KNX in your installation, add the following lines to your `configuration.yaml` file: @@ -39,13 +36,14 @@ To use your KNX in your installation, add the following lines to your `configura knx: ``` -Optional, recommended for large KNX installations (>100 devices) and/or if you want to use the XKNX abstraction also for other scripted tools outside HASS: +Optional, recommended for large KNX installations (>100 devices) and/or if you want to use the XKNX abstraction also for other scripted tools outside of Home Assistant: ```yaml knx: config_file: '/path/to/xknx.yaml' ``` -* **config_file**: (*Optional*) path for xknx configuration file. + +- **config_file** (*Optional*): The path for XKNX configuration file. If the auto detection of the KNX/IP device does not work you can specify ip/port of the tunneling device: @@ -56,9 +54,10 @@ knx: port: 3671 local_ip: '192.168.2.109' ``` -* **host**: Host of the KNX/IP tunneling device -* **port**: Port of the KNX/IP tunneling device -* **local_ip**: IP of the local interface + +- **host**: Host of the KNX/IP tunneling device. +- **port**: Port of the KNX/IP tunneling device. +- **local_ip**: IP of the local interface. Explicit connection to a KNX/IP routing device: @@ -68,7 +67,8 @@ knx: routing: local_ip: '192.168.2.109' ``` -* **local_ip**: local ip of interface (which should be used for multicasting) + +- **local_ip**: The local IP address of interface (which should be used for multicasting). ```yaml knx: @@ -76,13 +76,11 @@ knx: fire_event_filter: ["1/0/*", "6/2,3,4-6/*"] ``` -* **fire_event** (*Optional*): If set to True, platform will write all received KNX messages to event bus -* **fire_event_filter** (*Optional*): If `fire_event` is set `fire_event_filter` has to be specified. `fire_event_filter` defines a list of patterns for filtering KNX addresses. Only telegrams which match this pattern are sent to the HASS event bus. +- **fire_event** (*Optional*): If set to True, platform will write all received KNX messages to event bus +- **fire_event_filter** (*Optional*): If `fire_event` is set `fire_event_filter` has to be specified. `fire_event_filter` defines a list of patterns for filtering KNX addresses. Only telegrams which match this pattern are sent to the HOme Assistant event bus. +- **state_updater** (*Optional*): The component will collect the current state of each configured device from the KNX bus to display it correctly within Home-Assistant. Set this option to False to prevent this behaviour. -* **state_updater** (*Optional*): The component will collect the current state of each configured device from the KNX bus to display it correctly within Home-Assistant. Set this option to False to prevent this behaviour. - -Service -------- +### {% linkable_title Services %} In order to directly interact with the KNX bus, you can now use the following service: @@ -96,12 +94,7 @@ Service Data: {"address": "1/0/15", "payload": 0} * **payload**: Payload, either an integer or an array of integers +### {% linkable_title Known issues %} -Known issues: -------------- - -Due to lame multicast support the routing abstraction and the gateway scanner -only work with python >=3.5. - - +Due to lame multicast support the routing abstraction and the gateway scanner only work with Python >=3.5. diff --git a/source/_components/light.knx.markdown b/source/_components/light.knx.markdown index 36aac8596b0..b3cf614a1c9 100644 --- a/source/_components/light.knx.markdown +++ b/source/_components/light.knx.markdown @@ -21,23 +21,21 @@ The `knx` component must be configured correctly, see [KNX Component](/component To use your KNX light in your installation, add the following lines to your `configuration.yaml` file: ```yaml +# Example configuration.yaml entry light: - platform: knx name: Kitchen-Light-1 address: '1/0/9' brightness_address: '1/0/11' - - - platform: knx - name: Kitchen-Light-2 - address: '1/0/12' - brightness_address: '1/0/14' ``` -* **name** (*Optional*): A name for this device used within Home Assistant. -* **address**: KNX group address for switching the light on and off -* **brightness_address**: (Optional) KNX group address for dimming light. -* **state_address**: (*Optional*) separate KNX group address for retrieving the switch state of the light. -* **brightness_state_address**: (*Optional*) separate KNX group address for retrieving the dimmed state of the light. +Configuration variables: + +- **name** (*Optional*): A name for this device used within Home Assistant. +- **address**: KNX group address for switching the light on and off. +- **brightness_address** (Optional): KNX group address for dimming light. +- **state_address** (*Optional*): separate KNX group address for retrieving the switch state of the light. +- **brightness_state_address** (*Optional*): separate KNX group address for retrieving the dimmed state of the light. Some KNX devices can change their state internally without any messages on the KNX bus, e.g., if you configure a timer on a channel. The optional `state_address` can be used to inform Home Assistant about these state changes. If a KNX message is seen on the bus addressed to the given state address, this will overwrite the state of the switch object. For switching/light actuators that are only controlled by a single group address and can't change their state internally, you don't have to configure the state address. diff --git a/source/_components/notify.knx.markdown b/source/_components/notify.knx.markdown index 9456df55e11..78945fc3761 100644 --- a/source/_components/notify.knx.markdown +++ b/source/_components/notify.knx.markdown @@ -21,9 +21,9 @@ To use your KNX switch in your installation, add the following lines to your `co ```yaml notify: - - platform: knx - name: Alarm - address: '5/1/10' + - platform: knx + name: Alarm + address: '5/1/10' ``` * **name** (*Optional*): A name for this device used within Home Assistant. diff --git a/source/_components/sensor.knx.markdown b/source/_components/sensor.knx.markdown index e543f4c6ee7..d44e76e2e30 100644 --- a/source/_components/sensor.knx.markdown +++ b/source/_components/sensor.knx.markdown @@ -26,26 +26,13 @@ sensor: name: Heating.Valve1 address: '2/0/0' type: 'percent' - - platform: knx name: Kitchen.Temperature address: '6/2/1' type: 'temperature' - - - platform: knx - name: Wind speed - type: speed_ms - address: 1/0/0 - - - platform: knx - name: Lux - type: illuminance - address: 1/0/1 ``` -* **name** (*Optional*): A name for this device used within Home Assistant. -* **address**: KNX group address of the sensor -* **type**: (Optional) "percent", "temperature", "illuminance", "speed_ms", "current" - - +- **name** (*Optional*): A name for this device used within Home Assistant. +- **address**: KNX group address of the sensor. +- **type** (Optional): "percent", "temperature", "illuminance", "speed_ms", "current".