Skip to content

Update opentherm_gw docs to reflect config entry support. #10584

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
frenck merged 3 commits into from
Oct 16, 2019
Merged

Update opentherm_gw docs to reflect config entry support. #10584

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
45d5b8c
Update opentherm_gw docs to reflect config entry support.
mvn23 Oct 3, 2019
1ba124d
Update to reflect requested changes on parent PR
mvn23 Oct 4, 2019
db2de22
Add remark to gw_id
mvn23 Oct 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 25 additions & 56 deletions source/_integrations/opentherm_gw.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."
required: false
path:
description: "Path to the OpenTherm Gateway device as supported by [PySerial](https://pythonhosted.org/pyserial/url_handlers.html)."
required: true
type: string
default: "The `gateway_id` of the gateway."
climate:
description: "Settings for the `opentherm_gw` climate entity."
id:
description: "The `gateway_id` for this OpenTherm Gateway's entity IDs and services. The entered value will be slugified."
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
type: string
default: "The slugified `name` of this OpenTherm Gateway."
{% endconfiguration %}

<div class='note'>
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.
</div>


## Services

### Service `opentherm_gw.reset_gateway`
Expand All @@ -71,15 +58,15 @@ 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`

Provide the time and day of week to the OpenTherm Gateway. The value provided here will be forwarded to the thermostat on the next date/time request from the thermostat. The OpenTherm Gateway does not have the ability to accurately keep track of time, so it will only retain the information provided here for a maximum of about 61 seconds.

| 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.

Expand All @@ -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.

<div class='note'>
Expand All @@ -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`
Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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.

<div class='note'>
Expand All @@ -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`
Expand All @@ -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
Expand Down Expand Up @@ -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
```