mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-24 09:46:59 +00:00
update geniushub docs (#10443)
* 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
Franck Nijhof
parent
c12e1cc164
commit
9353e56d81
@ -1,6 +1,6 @@
|
||||
---
|
||||
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
|
||||
ha_category:
|
||||
- Climate
|
||||
@ -11,22 +11,20 @@ ha_release: 0.92
|
||||
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.
|
||||
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.
|
||||
|
||||
### 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
|
||||
- `Water Heater`, for **Hot Water Temperature** Zones
|
||||
- `Climate` entity, for **Radiator** and **Wet Underfloor** Zones, and
|
||||
- `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
|
||||
:---: | :---: | :---:
|
||||
@ -35,16 +33,18 @@ GH mode | HA Operation | HA Preset
|
||||
**Override** | Heat | Boost
|
||||
**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
|
||||
|
||||
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
|
||||
- `Binary Sensor` entity with on/off state for any Device that is a switch (e.g. a Smart Plug)
|
||||
- `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., 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
|
||||
|
||||
@ -57,26 +57,45 @@ Each such entity has a state attribute that will contain a list of any such issu
|
||||
- alias: GeniusHub Error Alerts
|
||||
trigger:
|
||||
platform: numeric_state
|
||||
entity_id: sensor.errors
|
||||
entity_id: sensor.geniushub_errors
|
||||
above: 0
|
||||
action:
|
||||
- service: notify.pushbullet_notifier
|
||||
data_template:
|
||||
title: "Genius Hub has errors"
|
||||
message: >-
|
||||
Genius Hub has the following {{ states('sensor.errors') }} errors:
|
||||
{{ state_attr('sensor.errors', 'error_list') }}
|
||||
Genius Hub has the following {{ states('sensor.geniushub_errors') }} errors:
|
||||
{{ state_attr('sensor.geniushub_errors', 'error_list') }}
|
||||
```
|
||||
{% 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
|
||||
{
|
||||
"status": {
|
||||
"type": "radiator",
|
||||
"mode": "off",
|
||||
"temperature": 19,
|
||||
"occupied": False,
|
||||
"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:
|
||||
|
||||
{% raw %}
|
||||
```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 %}
|
||||
|
||||
@ -99,7 +131,7 @@ In the specific case of **Radiator** zones with room sensors:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
value_template: "{{ state_attr('climate.main_room', 'status').occupied }}"
|
||||
value_template: "{{ state_attr('climate.genius_zone_12', 'status').occupied }}"
|
||||
```
|
||||
{% 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.
|
||||
|
||||
### 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)
|
||||
- uses the v1 API - which is well-documented
|
||||
- polls Heat Genius' own servers (so is slower, say ~5-10s response time)
|
||||
### Option 1: hub hostname/address with user credentials
|
||||
|
||||
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
|
||||
# Example configuration.yaml entry, using a Hub Token
|
||||
geniushub:
|
||||
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
|
||||
# Example configuration.yaml entry, directly polling the Hub
|
||||
geniushub:
|
||||
@ -140,6 +181,10 @@ token:
|
||||
description: The Hub Token of the Genius Hub.
|
||||
required: true
|
||||
type: string
|
||||
mac:
|
||||
description: The MAC address of the Hub's ethernet port.
|
||||
required: false
|
||||
type: string
|
||||
host:
|
||||
description: The hostname/IP address of the Genius Hub.
|
||||
required: true
|
||||
@ -154,4 +199,6 @@ password:
|
||||
type: string
|
||||
{% 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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user