diff --git a/source/_integrations/geniushub.markdown b/source/_integrations/geniushub.markdown index 703ca7f966a..afea22c9b81 100644 --- a/source/_integrations/geniushub.markdown +++ b/source/_integrations/geniushub.markdown @@ -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.