A Python library for interfacing with the Hive smart home platform. Provides both async (apyhiveapi) and sync (pyhiveapi) APIs, and is designed primarily for use with Home Assistant — though it works standalone too.
Package rename notice: This package replaces the legacy
pyhiveapipackage. The module names, API, and functionality are identical — only the PyPI distribution name changed.
- Async-first design with a generated sync wrapper (no asyncio boilerplate needed in sync contexts)
- AWS Cognito SRP authentication with SMS two-factor authentication support
- Automatic token refresh at 90% of token lifetime with silent retry on expiry
- Polling-based device state with a smart cache to avoid stale reads during in-progress polls
- Full device discovery — returns a ready-to-use device list for Home Assistant entity creation
- File-based offline mode for development and testing without live credentials
| Device Type | Capabilities |
|---|---|
| Heating (thermostat, TRV) | Current / target temperature, mode (schedule / manual / off), boost on/off, heat-on-demand, min/max range, schedule now/next/later |
| Hot Water | Mode (schedule / on / off), boost on/off, state |
| Lights | On/off, brightness, colour temperature, full RGB colour, colour mode |
| Smart Plugs | On/off, power usage |
| Sensors | Motion, contact (open/close), battery level, online status |
| Hub / Sense | Smoke, CO, dog bark, glass break detection |
pip install pyhive-integrationRequires Python 3.10+.
importasynciofromapyhiveapiimportAuth, Hiveasyncdefmain():
auth=Auth(username="user@example.com", password="yourpassword")
tokens=awaitauth.login()
# If SMS 2FA is required:# tokens = await auth.sms_2fa("123456", tokens)hive=Hive(username="user@example.com", password="yourpassword")
awaithive.startSession({"tokens": tokens})
fordeviceinhive.session.data.devices.values():
print(device)
asyncio.run(main())frompyhiveapiimportAuth, Hiveauth=Auth(username="user@example.com", password="yourpassword")
tokens=auth.login()
hive=Hive(username="user@example.com", password="yourpassword")
hive.startSession({"tokens": tokens})
fordeviceinhive.session.data.devices.values():
print(device)Authentication uses the AWS Cognito SRP flow. If your account has SMS two-factor authentication enabled, login() will raise HiveSmsRequired — call sms_2fa(code, tokens) with the code sent to your phone.
fromapyhiveapiimportAuthfromapyhiveapi.helper.hive_exceptionsimportHiveSmsRequiredauth=Auth(username="user@example.com", password="yourpassword")
try:
tokens=awaitauth.login()
exceptHiveSmsRequired:
code=input("SMS code: ")
tokens=awaitauth.sms_2fa(code, tokens)Note: Only the Hive account owner is supported. Guest accounts cannot be used.
After startSession, device modules are available directly on the Hive instance:
# Heatingawaithive.heating.set_target_temperature(device, 21.0)
awaithive.heating.set_mode(device, "SCHEDULE")
awaithive.heating.set_boost_on(device, mins=30, temp=22.0)
awaithive.heating.set_boost_off(device)
# Hot waterawaithive.hotwater.set_mode(device, "ON")
awaithive.hotwater.set_boost_on(device, mins=60)
# Lightsawaithive.light.set_status_on(device)
awaithive.light.set_brightness(device, 80)
awaithive.light.set_color_temp(device, 4000)
awaithive.light.set_color(device, [255, 100, 0])
# Smart plugawaithive.switch.turn_on(device)
awaithive.switch.turn_off(device)
# Force a data refreshawaithive.force_update()Set username="use@file.com" to load device state from bundled JSON fixtures in src/data/ instead of making live API calls. Useful for development without real Hive credentials.
hive=Hive(username="use@file.com", password="")
awaithive.startSession({})The library exposes two packages built from the same source:
apyhiveapi— async package (source insrc/)pyhiveapi— sync package (auto-generated fromsrc/viaunasyncduring build)
Never edit the generated sync files — edit the async source in src/ only.
# Install dev dependencies
pip install -e ".[dev]"# Run linters
pre-commit run --all-files
# Run tests
pytest tests/
# Regenerate sync package
python setup.py build_pyMIT License — see LICENSE for details.