apyhiveapi

An async Python library for the Hive smart home platform. It exists to power tomwilkie/ha-hive, a fork of the Hive integration for Home Assistant, and exposes exactly what that integration needs: Hive heating (thermostats and TRVs) and hot water.

This library is a hard fork of Pyhass/Pyhive, cut down to what the ha-hive integration needs and restarted at version 0.0.1. It was called pyhive-integration until v0.1.5; that name on PyPI belongs to the upstream project, so this one is published as apyhiveapi, which is also the import name.

Features

• Async only, built on aiohttp
• AWS Cognito SRP authentication with SMS two-factor authentication support
• Automatic token refresh at 90% of token lifetime, with a silent re-login when the refresh token is rejected
• Polling-based device state, rate limited to one poll per scan interval across all entities
• Full device discovery — returns a ready-to-use device list for the integration's entities
• File-based offline mode for development and testing without live credentials

Supported Devices

Lights, smart plugs, sensors and the hub are not supported: the ha-hive integration does not use them.

Installation

From PyPI, or the current main:

pip install apyhiveapi
pip install "apyhiveapi @ git+https://github.com/tomwilkie/apyhiveapi"

Every release is also attached to its GitHub Release as a wheel and sdist.

Requires Python 3.13+.

Quick Start

import asyncio
import getpass

from aiohttp import ClientSession
from apyhiveapi import SMS_REQUIRED, Auth, Hive


async def main():
    username = input("Hive email: ")
    password = getpass.getpass("Hive password: ")

    auth = Auth(username=username, password=password)
    tokens = await auth.login()
    if tokens.get("ChallengeName") == SMS_REQUIRED:
        tokens = await auth.sms_2fa(input("SMS code: "), tokens)
        await auth.device_registration()

    async with ClientSession() as websession:
        hive = Hive(websession)
        devices = await hive.start_session(
            {
                "username": username,
                "password": password,
                "tokens": tokens,
                "device_data": auth.get_device_data(),
            }
        )
        for climate in devices["climate"]:
            await hive.heating.get_climate(climate)
            print(climate.ha_name, climate.status)


asyncio.run(main())

Authentication

Authentication uses the AWS Cognito SRP flow. On the first login login() returns a ChallengeName of SMS_MFA (the SMS_REQUIRED constant) when the account has SMS two-factor authentication enabled; pass the code to sms_2fa(code, tokens). Then call device_registration() to register the machine as a trusted device and save the credentials get_device_data() returns, so later sessions can log in without an SMS.

Note: Only the Hive account owner is supported. Guest accounts cannot be used.

Standalone login example

examples/example_login.py is a complete runnable script. The first run asks for your email, password and SMS code, registers the machine as a trusted device and saves the device credentials to hive_device.json. Later runs log in with that file and skip the SMS. Both runs list every discovered device.

pip install apyhiveapi
python examples/example_login.py

Controlling Devices

After start_session, device modules are available directly on the Hive instance. Commands return nothing and raise a HiveError when the change could not be made; readers never raise and report unknown values as None.

# Heating
await hive.heating.set_target_temperature(device, 21.0)
await hive.heating.set_mode(device, "SCHEDULE")
await hive.heating.set_boost_on(device, 30, 22.0)
await hive.heating.set_boost_off(device)

# Hot water
await hive.hotwater.set_mode(device, "MANUAL")
await hive.hotwater.set_boost_on(device, 60)
await hive.hotwater.set_boost_off(device)

# Refresh state (rate limited to the configured scan interval)
await hive.update_data()
device = await hive.heating.get_climate(device)
print(device.status, device.device_data["online"])

Errors

Every exception the library raises is a subclass of HiveError, grouped by what the caller should do about it. aiohttp and botocore exceptions never escape the library.

Invalid arguments, such as a boost of zero minutes, raise ValueError. Polling through update_data logs transient failures, keeps the last known state and retries after 30 seconds; only HiveReauthRequired propagates from it.

Offline / File-Based Testing

Set username="use@file.com" to load device state from the bundled JSON fixture in src/apyhiveapi/data/ instead of making live API calls. Useful for development without real Hive credentials.

async with Hive(username="use@file.com", password="") as hive:
    await hive.start_session({})

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run linters
pre-commit run --all-files

# Run tests
pytest tests/

Links

• ha-hive, the Home Assistant integration this library powers
• Releases
• Source
• Issue Tracker

License

MIT License — see LICENSE for details. The original work is copyright Pyhive; the changes in this fork are copyright Tom Wilkie.