jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-28 03:37:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

update geniushub docs (#10443)

Browse Source 
* update geniushub docs

* add another example automation

* tweak

* small tweak

* small tweak

* update to reality

* small tweak

* ✏️ Tweaks
This commit is contained in:
David Bonnes 2019-10-02 21:49:09 +01:00 committed by Franck Nijhof
parent c12e1cc164
commit 9353e56d81
1 changed files with 82 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
source/_integrations/geniushub.markdown
View File

@ -1,6 +1,6 @@
--- ---
title: "Genius Hub" title: "Genius Hub"
description: "Instructions on how to integrate Genius Hub with Home Assistant." description: "Instructions on how to integrate a Genius Hub with Home Assistant."
logo: geniushub.png logo: geniushub.png
ha_category: ha_category:
- Climate - Climate
@ -11,22 +11,20 @@ ha_release: 0.92
ha_iot_class: Local Polling ha_iot_class: Local Polling
--- ---
The `geniushub` integration links Home Assistant with your Genius Hub CH/DHW system, including its Zones, Devices, and Issues. The `geniushub` integration links Home Assistant with your Genius Hub CH/DHW system, including its zones, devices, and issues.
Currently, there is no support for Zone schedules. It uses the [geniushub](https://pypi.org/project/geniushub-client/) client library, which provides data compatible with the v1 API that _may not_ necessarily match that of the official Web App.
It uses the [geniushub](https://pypi.org/project/geniushub-client/) client library.
### Zones ### Zones
Each Zone controlled by your Genius hub will be exposed as either a: Each zone controlled by your Genius Hub will be exposed as either a:
- `Climate` entity, for **Radiator** Zones, and - `Climate` entity, for **Radiator** and **Wet Underfloor** Zones, and
- `Water Heater`, for **Hot Water Temperature** Zones - `Water Heater` entity, for **Hot Water Temperature** Zones
Other Zone types, such as **On / Off** Zones, are not currently supported. Other zone types, such as **On/Off** zones, are not currently supported (although see `Binary Sensor`s, below).
Each such entity will report back its mode, state, setpoint and current temperature; other properties are available via its attributes (see below). The Zone's mode can changed as below. Each entity derived from a GH zone will report back its mode, setpoint and current temperature; other properties are available via its attributes (see below). The zone's mode can be changed as below.
GH mode | HA Operation | HA Preset GH mode | HA Operation | HA Preset
:---: | :---: | :---: :---: | :---: | :---:
@ -35,16 +33,18 @@ GH mode | HA Operation | HA Preset
**Override** | Heat | Boost **Override** | Heat | Boost
**Footprint** | Heat | Activity **Footprint** | Heat | Activity
Note that **Footprint** mode is only available to **Radiator** Zones that have room sensors. Note that **Footprint** mode is only available to **Radiator** zones that have room sensors.
Currently, there is no support for reading/altering zone schedules, although a zone can be switched to/from modes that utilize schedules.
### Devices ### Devices
If the Hub is directly polled using the v3 API (see below), then each Device controlled by your Genius hub will be exposed as either a: Each Device controlled by your Genius hub will be exposed as either a:
- `Sensor` entity with a % battery, for any Device with a battery (e.g. a Genius Valve), or - `Sensor` entity with a % battery, for any Device with a battery (e.g., a Genius Valve), or
- `Binary Sensor` entity with on/off state for any Device that is a switch (e.g. a Smart Plug) - `Binary Sensor` entity with on/off state for any Device that is a switch (e.g., Smart Plugs, DCRs)
Each such entity will report back its primary state; in addition, `assigned_zone` and `last_comms` (last communications time) are available via the entity's attributes. Each such entity will report back its primary state and `assigned_zone`. If the Hub is directly polled using Option 1 (see below), then some additional attributes such as `last_comms` (last communications time) are also available.
### Issues ### Issues
@ -57,26 +57,45 @@ Each such entity has a state attribute that will contain a list of any such issu
- alias: GeniusHub Error Alerts - alias: GeniusHub Error Alerts
trigger: trigger:
platform: numeric_state platform: numeric_state
entity_id: sensor.errors entity_id: sensor.geniushub_errors
above: 0 above: 0
action: action:
- service: notify.pushbullet_notifier - service: notify.pushbullet_notifier
data_template: data_template:
title: "Genius Hub has errors" title: "Genius Hub has errors"
message: >- message: >-
Genius Hub has the following {{ states('sensor.errors') }} errors: Genius Hub has the following {{ states('sensor.geniushub_errors') }} errors:
{{ state_attr('sensor.errors', 'error_list') }} {{ state_attr('sensor.geniushub_errors', 'error_list') }}
``` ```
{% endraw %} {% endraw %}
### State Attributes This alert may be useful to see if the CH is being turned on whilst you're on a holiday!
Other properties are available via each entity's state attributes. For example, in the case of **Radiator** Zones/`Climate` devices: {% raw %}
```yaml
- alias: GeniusHub CH State Change Alert
trigger:
platform: state
entity_id: binary_sensor.dual_channel_receiver_2_1
action:
- service: notify.pushbullet_notifier
data_template:
title: "Warning: CH State Change!"
message: >-
{{ trigger.to_state.attributes.friendly_name }} has changed
from {{ trigger.from_state.state }} to {{ trigger.to_state.state }}.
```
{% endraw %}
## State Attributes
Many zone/device properties are available via each entity's state attributes. For example, in the case of **Radiator**-derived `Climate` entities (note 'status'):
```json ```json
{ {
"status": { "status": {
"type": "radiator", "type": "radiator",
"mode": "off",
"temperature": 19, "temperature": 19,
"occupied": False, "occupied": False,
"override": { "override": {
@ -87,11 +106,24 @@ Other properties are available via each entity's state attributes. For example,
} }
``` ```
... and for **Genius Valve**-derived `Sensor` entities (note 'state'):
```json
{
"state": {
"set_temperature": 4.0,
"measured_temperature": 20.030000686645508,
"setback": 3.5,
"wakeup_interval": 450
}
}
```
This data can be accessed in automations, etc. via a value template. For example: This data can be accessed in automations, etc. via a value template. For example:
{% raw %} {% raw %}
```yaml ```yaml
value_template: "{{ state_attr('water_heater.boiler_h_w', 'status').override.setpoint }}" value_template: "{{ state_attr('water_heater.genius_zone_2', 'status').override.setpoint }}"
``` ```
{% endraw %} {% endraw %}
@ -99,7 +131,7 @@ In the specific case of **Radiator** zones with room sensors:
{% raw %} {% raw %}
```yaml ```yaml
value_template: "{{ state_attr('climate.main_room', 'status').occupied }}" value_template: "{{ state_attr('climate.genius_zone_12', 'status').occupied }}"
``` ```
{% endraw %} {% endraw %}
@ -107,26 +139,35 @@ value_template: "{{ state_attr('climate.main_room', 'status').occupied }}"
To set up this integration, add one of the following to your **configuration.yaml** file. To set up this integration, add one of the following to your **configuration.yaml** file.
### Option 1: hub token only If required, you can switch between one Option and the other and, as the `unique_id` remains consistent, state history will be preserved. This assumes that the correct MAC address is provided for Option 2, below. If a wrong MAC address was provided for Option 1, then the MAC address can be overridden for Option 1 to maintain these links within the entity registry.
- requires a **hub token** obtained from [my.geniushub.co.uk/tokens](https://my.geniushub.co.uk/tokens) ### Option 1: hub hostname/address with user credentials
- uses the v1 API - which is well-documented
- polls Heat Genius' own servers (so is slower, say ~5-10s response time) This is the recommended option.
- Requires your **username** & **password**, as used with [geniushub.co.uk/app](https://www.geniushub.co.uk/app).
- Uses the v3 API - unofficial, but there are additional features (e.g., battery levels).
- Polls the hub directly (so is faster, say ~1s response time).
- You have the option of specifying a MAC address.
The hub does not have to be in the same subnet as HA.
### Option 2: hub token only
This option is recommended only if Ootion 1 does not work. The MAC address should match that written on the back of the Hub.
- Requires a **hub token** obtained from [my.geniushub.co.uk/tokens](https://my.geniushub.co.uk/tokens).
- Uses the v1 API - which is well-documented.
- Polls Heat Genius' own servers (so is slower, say ~5-10s response time).
- You should use the Hub's MAC address (although any valid MAC will do).
```yaml ```yaml
# Example configuration.yaml entry, using a Hub Token # Example configuration.yaml entry, using a Hub Token
geniushub: geniushub:
token: GENIUS_HUB_TOKEN token: GENIUS_HUB_TOKEN
mac : GENIUS_HUB_MAC
``` ```
### Option 2: hub hostname/address with user credentials
- requires your **username** & **password**, as used with [www.geniushub.co.uk/app](https://www.geniushub.co.uk/app)
- uses the v3 API - unofficial, but there are additional features (e.g., battery levels)
- polls the hub directly (so is faster, say ~1s response time)
The hub does not have to be in the same network as HA.
```yaml ```yaml
# Example configuration.yaml entry, directly polling the Hub # Example configuration.yaml entry, directly polling the Hub
geniushub: geniushub:
@ -140,6 +181,10 @@ token:
description: The Hub Token of the Genius Hub. description: The Hub Token of the Genius Hub.
required: true required: true
type: string type: string
mac:
description: The MAC address of the Hub's ethernet port.
required: false
type: string
host: host:
description: The hostname/IP address of the Genius Hub. description: The hostname/IP address of the Genius Hub.
required: true required: true
@ -154,4 +199,6 @@ password:
type: string type: string
{% endconfiguration %} {% endconfiguration %}
Note that if a `host` is used instead of `token`, then the `username` and `password` are also required. Note: `username` and `password` are only required when `host` is used (instead of `token`).
Note: `mac` is required if `token` is used (instead of `host`) and is optional otherwise.