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

title, description, logo, ha_category, ha_release, ha_iot_class

title	description	logo	ha_category	ha_release	ha_iot_class
Genius Hub	Instructions on how to integrate a Genius Hub with Home Assistant.	geniushub.png	Climate Water Heater Sensor Binary Sensor Switch	0.92	Local Polling

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

It uses the geniushub 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 Assisatnt schemas (e.g. HA has no Footprint mode) - see below for more details.

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

Note that Boost mode may

Note that 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)

If you turn a Switch entity Off via HA, it will revert to Timer mode.

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 %}

- alias: GeniusHub Error Alerts
  trigger:
    platform: numeric_state
    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.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 %}

- 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 the corresponding entity's state attributes. For example, in the case of Radiator-derived Climate entities (note 'status'):

{
  "status": {
    "type": "radiator",
    "mode": "off",
    "temperature": 19,
    "occupied": False,
    "override": {
      "duration": 0,
      "setpoint": 16
    }
  }
}

... and for Genius Valve-derived Sensor entities (note 'state'):

{
  "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 %}

value_template: "{{ state_attr('water_heater.genius_zone_2', 'status').override.setpoint }}"

{% endraw %}

In the specific case of Radiator zones with room sensors:

{% raw %}

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

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

# Example configuration.yaml entry, using a Hub Token
geniushub:
  token: GENIUS_HUB_TOKEN
  mac : GENIUS_HUB_MAC

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