initial commit (#11798)

source/_integrations/geniushub.markdown

@@ -30,7 +30,13 @@ Each zone controlled by your Genius Hub will be exposed as either a:
 
 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.
+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_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
 
@@ -43,18 +49,17 @@ GH mode | HA Operation | HA Preset
 **Override** | Heat | Boost
 **Footprint** | Heat | Activity
 
-Note that `Boost` mode may 
+**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.
 
 ### 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:
+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.
+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 behaviour 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
 
@@ -158,7 +163,7 @@ value_template: "{{ state_attr('climate.genius_zone_12', 'status').occupied }}"
 
 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.
+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
 
@@ -173,7 +178,7 @@ 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.
+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/tokens](https://my.geniushub.co.uk/tokens).
 - Uses the v1 API - which is well-documented.