home-assistant.io/source/_integrations/geniushub.markdown

---
title: Genius Hub
description: Instructions on how to integrate a Genius Hub with Home Assistant.
ha_category:
  - Binary sensor
  - Climate
  - Sensor
  - Switch
  - Water heater
ha_release: 0.92
ha_iot_class: Local Polling
ha_codeowners:
  - '@manzanotti'
ha_domain: geniushub
ha_platforms:
  - binary_sensor
  - climate
  - sensor
  - switch
  - water_heater
ha_integration_type: integration
---

The `geniushub` integration links Home Assistant with your Genius Hub CH/DHW system, including its zones, devices, and issues.

It uses the [geniushub](https://pypi.org/project/geniushub-client/) client library, which provides data compatible with the v1 API that _may not_ exactly match that of the official Web App.

### Zones

Each zone controlled by your Genius Hub will be exposed as either a:

- `Climate` entity, for **Radiator** and **Wet Underfloor** zones, and
- `Water heater` entity, for **Hot Water Temperature** zones and
- `Switch` entity, for **On/Off** zones

**Group** zones are not supported.

Currently, there is no support for altering zone schedules, although entities can be switched to/from geniushub modes that utilize schedules.

There are limitations due to the differences between the Genius Hub and Home Assistant schemas (e.g.,  HA has no **Footprint** mode) - use the service handlers, below, for this functionality.

### Service handlers

Home Assistant is obligated to place restrictions upon integrations such as **geniushub** to maintain compatibility with other ecosystems (e.g.,  Google Home) and so not all of the **geniushub** functionality is available via the web UI. Some of this missing functionality is exposed via integration-specific service handlers:

- `set_switch_override`: change the switches on time _for a specified duration_ (up to 24h),
- `set_zone_override`: change the zone's setpoint _for a specified duration_ (up to 24h), and
- `set_zone_mode`: change the zone's mode to one of `off`, `timer` or (if supported by the zone) `footprint`

### Climate and water heater entities

Climate and water heater entities will report their current temperature, setpoint and mode; other properties (e.g.,  occupied state) are available via their state attributes (see examples below). The Genius Hub mode will be reported as/set to:

|    GH mode    | HA Operation | HA Preset |
| :-----------: | :----------: | :-------: |
|    **Off**    |     Off      |    N/A    |
|   **Timer**   |     Heat     |   None    |
| **Override**  |     Heat     |   Boost   |
| **Footprint** |     Heat     | Activity  |

**Footprint** mode is only available to **Radiator** zones that have room sensors.

### Switch entities

Switch entities will report back their state; other properties are available via their state attributes. Currently, HA switches do not have modes/presets, so the Home Assistant `state` will be *reported* as:

- `On` for **Override** \ **On**, and
- `Off` otherwise (NB: the zone could still be 'on', e.g.,  with **Timer** mode)

Note: if you turn a Switch entity `Off` via Home Assistant's web UI, it will revert to **Timer** mode - this may not be the behavior you are expecting.

Individual smart plugs are not yet exposed as switches - you can create one zone per smart plug as a work-around.

### Devices

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., Smart Plugs, DCRs)

Such entities will report back their primary state and `assigned_zone`. If the Hub is directly polled using Option 1 (see below), then some additional state attributes such as `last_comms` (last communications time) are also available.

### Issues

There are three `Sensor` entities that will indicate the number of **Errors**, **Warnings** and **Information** issues.

Each such entity has a state attribute that will contain a list of any such issues which can be used in automations, etc. For example:

{% raw %}

```yaml
- alias: "GeniusHub Error Alerts"
  trigger:
    platform: numeric_state
    entity_id: sensor.geniushub_errors
    above: 0
  action:
  - service: notify.pushbullet_notifier
    data:
      title: "Genius Hub has errors"
      message: >-
        Genius Hub has the following {{ states('sensor.geniushub_errors') }} errors:
        {{ state_attr('sensor.geniushub_errors', 'error_list') }}
```

{% endraw %}

This alert may be useful to see if the CH is being turned on whilst you're on a holiday!

{% 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:
      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 the corresponding 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": {
      "duration": 0,
      "setpoint": 16
    }
  }
}
```

... 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.genius_zone_2', 'status').override.setpoint }}"
```

{% endraw %}

In the specific case of **Radiator** zones with room sensors:

{% raw %}

```yaml
value_template: "{{ state_attr('climate.genius_zone_12', 'status').occupied }}"
```

{% endraw %}

## Configuration

To set up this integration, add one of the following to your `configuration.yaml` file.

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.

### 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 (not recommended, see above).

The hub does not have to be in the same subnet as your Home Assistant instance.

### Option 2: hub token only

This option is recommended only if Option 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](https://my.geniushub.co.uk/).
- 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
```

```yaml
# Example configuration.yaml entry, directly polling the Hub
geniushub:
  host: IP_ADDRESS
  username: GENIUS_HUB_USERNAME
  password: GENIUS_HUB_PASSWORD
```

{% configuration %}
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
  type: string
username:
  description: Your Genius Hub username.
  required: false
  type: string
password:
  description: Your Genius Hub password.
  required: false
  type: string
{% endconfiguration %}

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.