From 226acf805342e08a44a203392d356b0391e4bb44 Mon Sep 17 00:00:00 2001 From: mvn23 Date: Wed, 16 Oct 2019 22:27:25 +0200 Subject: [PATCH] Update opentherm_gw docs to reflect config entry support. (#10584) * Update opentherm_gw docs to reflect config entry support. * Update to reflect requested changes on parent PR * Add remark to gw_id --- source/_integrations/opentherm_gw.markdown | 81 +++++++--------------- 1 file changed, 25 insertions(+), 56 deletions(-) diff --git a/source/_integrations/opentherm_gw.markdown b/source/_integrations/opentherm_gw.markdown index e4ba6feb5f3..9be3e2cd154 100644 --- a/source/_integrations/opentherm_gw.markdown +++ b/source/_integrations/opentherm_gw.markdown @@ -27,42 +27,29 @@ The OpenTherm protocol is based on polling. The thermostat sends requests to the # Configuration -In this example, one gateway is configured with `gateway_id` `living_room`. -```yaml -# Example configuration.yaml entry -opentherm_gw: - living_room: - device: /dev/ttyUSB0 -``` - -Each configured gateway accepts the following configuration options. +The OpenTherm Gateway can be added to Home Assistant through the `Integrations` panel in the `Configuration` page of the web interface. +The following configuration options are available: {% configuration %} -device: - description: "Path to OpenTherm Gateway device as supported by [PySerial](https://pythonhosted.org/pyserial/url_handlers.html)." +name: + description: "The friendly name used for the OpenTherm Gateway and its entities." required: true type: string -name: - description: "The friendly name used for the entities added for the gateway." +path: + description: "Path to the OpenTherm Gateway device as supported by [PySerial](https://pythonhosted.org/pyserial/url_handlers.html)." + required: true + type: string +id: + description: "The `gateway_id` for this OpenTherm Gateway's entity IDs and services. The entered value will be slugified." required: false type: string - default: "The `gateway_id` of the gateway." -climate: - description: "Settings for the `opentherm_gw` climate entity." - required: false - type: map - keys: - precision: - description: "The desired precision for this device. Can be used to match your actual thermostat's precision. Supported values are `0.1`, `0.5` and `1.0`." - required: false - type: float - default: "`0.5` for Celsius and `1.0` for Fahrenheit." - floor_temperature: - description: "Some thermostats round all temperatures down to the lower value according to their precision. Default behavior for Home Assistant is to round temperatures to the nearest value. Set this to `true` to override this behavior and round to the lower value according to the configured `precision`." - required: false - type: boolean - default: false + default: "The slugified `name` of this OpenTherm Gateway." {% endconfiguration %} +
+The precision and floor_temperature settings that were supported in configuration.yaml entries have been temporarily removed. The values will be lost upon import of the configuration.yaml entry into the Integrations panel. These features will be re-added soon. +
+ + ## Services ### Service `opentherm_gw.reset_gateway` @@ -71,7 +58,7 @@ Reset the OpenTherm Gateway. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `gateway_id` | no | The `gateway_id` as specified in `configuration.yaml`. +| `gateway_id` | no | The `gateway_id` as specified during configuration. ### Service `opentherm_gw.set_clock` @@ -79,7 +66,7 @@ Provide the time and day of week to the OpenTherm Gateway. The value provided he | Service data attribute | Optional | Default | Description | | ---------------------- | -------- | ------- | ----------- | -| `gateway_id` | no | N/A | The `gateway_id` as specified in `configuration.yaml`. +| `gateway_id` | no | N/A | The `gateway_id` as specified during configuration. | `date` | yes | Today's date | Date from which the day of week will be extracted. Format: `YYYY-MM-DD`. | `time` | yes | Current time | Time in 24h format. @@ -95,7 +82,7 @@ In a normal situation, the thermostat will calculate and control the central hea | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `gateway_id` | no | The `gateway_id` as specified in `configuration.yaml`. +| `gateway_id` | no | The `gateway_id` as specified during configuration. | `temperature` | no | The central heating setpoint. Values between `0.0` and `90.0` are accepted, but your boiler may not support the full range. Set to `0` to disable the override.
@@ -114,7 +101,7 @@ that. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `gateway_id` | no | The `gateway_id` as specified in `configuration.yaml`. +| `gateway_id` | no | The `gateway_id` as specified during configuration. | `dhw_override` | no | The domestic hot water override state. Value should be 0 or 1 to enable the override in off or on state, or "A" to disable the override. ### Service `opentherm_gw.set_gpio_mode` @@ -124,7 +111,7 @@ For an explanation of the possible modes, see [GPIO modes](#gpio-modes) | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `gateway_id` | no | The `gateway_id` as specified in `configuration.yaml`. +| `gateway_id` | no | The `gateway_id` as specified during configuration. | `id` | no | The GPIO ID, `A` or `B`. | `mode` | no | The GPIO mode to be set. @@ -135,7 +122,7 @@ For a list of possible modes with explanation, see [LED modes](#led-modes) | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `gateway_id` | no | The `gateway_id` as specified in `configuration.yaml`. +| `gateway_id` | no | The `gateway_id` as specified during configuration. | `id` | no | The LED ID, accepted values are `A` through `F`. | `mode` | no | The LED mode to be set. @@ -151,7 +138,7 @@ In a normal situation, the thermostat will control the maximum modulation level | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `gateway_id` | no | The `gateway_id` as specified in `configuration.yaml`. +| `gateway_id` | no | The `gateway_id` as specified during configuration. | `level` | no | The maximum modulation level. Accepted values are `-1` through `100`. Set to `-1` to disable the override.
@@ -167,7 +154,7 @@ If your thermostat is unable to display an outside temperature and does not supp | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `gateway_id` | no | The `gateway_id` as specified in `configuration.yaml`. +| `gateway_id` | no | The `gateway_id` as specified during configuration. | `temperature` | no | The outside temperature to provide to the thermostat. Accepted values are `-40.0` through `64.0`. Any value above `64.0` will clear a previously configured value (suggestion: `99`). ### Service `opentherm_gw.set_setback_temperature` @@ -177,7 +164,7 @@ The value you provide here will be used with the GPIO `home` (5) and `away` (6) | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `gateway_id` | no | The `gateway_id` as specified in `configuration.yaml`. +| `gateway_id` | no | The `gateway_id` as specified during configuration. | `temperature` | no | The setback temperature. Accepted values are `0.0` through `30.0`. ## Sensors @@ -521,21 +508,3 @@ Possible LED modes and their meaning are listed here: * X. Transmission error has been detected. * M. Boiler requires maintenance. * P. Raised power mode active on thermostat interface. - -# Example - -A full configuration example with two configured OpenTherm Gateways - one connected via USB, the other over the network - looks like the one below. - -```yaml -# Full example configuration.yaml entry -opentherm_gw: - living_room: - device: /dev/ttyUSB0 - name: "Living" - holiday_home: - device: socket://otgw.example.org:2345 - name: "Holiday Home" - climate: - precision: 0.5 - floor_temperature: true -```