Hive heating

Read this part before you connect anything

Hive has no public API. British Gas publishes no developer documentation, issues no API keys and offers no way to authorise an application. Every integration that talks to Hive — ours, Home Assistant's, and every other one — does it by signing in as you, with the same email address and password you use in the Hive app.

That means Mirra has to store your actual Hive password rather than a token you could revoke. We encrypt it, we never send it to a screen, and nothing in the product will display it back to you. It is still your password, and that is a genuinely different bargain from every other integration here.

• Stored encrypted, and only ever decrypted on our servers to talk to Hive.
• Never sent to a screen. A mirror on a wall does not hold your Hive credentials.
• Changing your Hive password disconnects Mirra rather than silently failing — the Hive page says the sign-in was rejected.

If you would rather not do that, do not. Home Assistant's Hive integration makes exactly the same trade — your password ends up on your own server instead of ours, which some people reasonably prefer. Either way, use a password you have not used anywhere else.

Two-factor authentication

If your Hive account has two-factor authentication turned on, this cannot work. There is no way for a background service to answer a code sent to your phone every time it needs to talk to Hive, and there is no application-password mechanism to use instead.

That is not a limitation we can engineer around, and turning 2FA off to make a wall display work is a bad trade. If your account has it, connect Hive through Home Assistant instead, or leave the heating off the mirror.

Mirra will tell you this at the point of connecting rather than accepting the details and failing quietly afterwards.

What appears on a screen

Hive devices arrive as the same climate and state entities Home Assistant produces, so they use the tiles that already exist. There is no separate Hive widget.

• Thermostat — the room temperature, the target, and controls to change it.
• State — a reading on its own, for a wall where a full thermostat tile is too much. "Hallway 19.5°" and nothing else.
• Hot water appears as its own entity where your system has it, with on, off and boost.
• Radiator valves appear individually, so a room with a valve can be shown and set separately from the main thermostat.

Connecting

1. Open Integrations, then Hive

   The page is at /integrations/hive.

2. Enter the email address and password you use in the Hive app

   Not your British Gas energy account, if those are different — it is the Hive app's own sign-in.

3. Press Connect

   Mirra signs in to Hive there and then. If the details are wrong you are told immediately, rather than saving them and leaving a thermostat that never updates.

4. Your devices appear

   Thermostats, hot water and any radiator valves. They are now in the entity pickers for the thermostat and state widgets.

Boost, and the thing it does to the display

Boost is the button everybody actually uses: heating on for an hour regardless of the schedule. It is worth knowing what Hive does internally, because it explains something you would otherwise think was a bug.

While a boost is running, Hive stops reporting the real mode. A thermostat on its schedule reports SCHEDULE; press boost and it reports BOOST, with the mode it was in kept somewhere else entirely. An integration that reads the mode naively shows the heating as "boosting" and, when the boost ends, has no idea what to go back to.

Mirra reads the mode underneath the boost, so a tile shows "Schedule — boosting until 15:20" rather than losing the schedule for an hour and then appearing to change its mind.

What Mirra does not do

• Editing schedules. Hive's own app is where a heating schedule is built. Mirra shows what the schedule is doing and lets you override it; it does not try to be a second place to write one.
• Holiday mode. Readable, not settable. Turning the heating off for a fortnight from a wall display somebody walks past is an easy accident.
• Hive's cameras, plugs and sensors. This integration is the heating. If you have the rest of the Hive range, Home Assistant covers it properly.

When something is not working

• "Sign-in was rejected." The password changed, or 2FA was turned on. Reconnect with the current details.
• A temperature is stale. Hive reports on its own schedule, not instantly. A minute or two behind the app is normal; an hour is not.
• A valve is missing. Radiator valves report through the hub. If the valve is offline in the Hive app it will be absent here too.
• The target will not change. Check the thermostat is not in holiday mode, which Hive treats as overriding everything and Mirra will not turn off for you.