Grundfos ALPHA HWR Python Library

Python library and CLI for controlling Grundfos ALPHA HWR pumps via Bluetooth Low Energy.

Not affiliated with, endorsed by, or associated with Grundfos. This is an independent client, built by reverse-engineering the pump's BLE interface. Incorrect use of motor control commands could in principle damage hardware, though the pump's own firmware limits generally prevent it.

Features

• Automatic discovery and guidance for pairing/bonding ALPHA HWR pumps
• Stream telemetry data (flow, pressure, power, temperature)
• Set pump modes and setpoints, and find out what the pump actually stored
• Create and manage time-based operation schedules
• Save and restore complete pump configurations
• Full type hints and validation with Pydantic
• Built on async Python for efficient BLE communication
• Command-line interface for quick operations

Installation

pip install alpha-hwr

Requirements: Python 3.13+ with Bluetooth Low Energy support

Important: Most pumps require the host to be paired/bonded before telemetry and control work reliably. If your OS prompts for pairing on first connect, accept it before trying to read data.

Quick Start

Command Line

# Discover nearby pumps
alpha-hwr device scan

# Monitor telemetry in real-time
alpha-hwr monitor live --device AA:BB:CC:DD:EE:FF

# Check pump status
alpha-hwr control status --device AA:BB:CC:DD:EE:FF

# Set constant pressure mode (1.5 meters)
alpha-hwr control set-pressure 1.5 --device AA:BB:CC:DD:EE:FF

Python Library

import asyncio
from alpha_hwr import AlphaHWRClient, ControlMode


async def main():
    # Connect to pump (auto-discovery or specific address)
    async with AlphaHWRClient("AA:BB:CC:DD:EE:FF") as client:
        # Read telemetry
        telemetry = await client.telemetry.read_once()
        print(f"Flow: {telemetry.flow_m3h} m³/h")
        print(f"Head: {telemetry.head_m} m")
        print(f"Power: {telemetry.power_w} W")

        # Set constant pressure to 1.5 m, and see what the pump stored
        await client.wait_until_ready()
        result = await client.control.set_setpoint(
            ControlMode.CONSTANT_PRESSURE, 1.5
        )
        print(f"{result.status}: pump holds {result.value} m")

        # Read device info
        info = await client.device_info.read_info()
        print(f"Serial: {info.serial_number}")
        print(f"Software: {info.software_version}")


asyncio.run(main())

Supported Control Modes

The ALPHA HWR supports 5 primary modes optimized for domestic hot water recirculation:

Mode	Accepted range	Notes
Temperature Control	20-70 °C	Dual setpoints (min/max), AUTOADAPT flow adjustment, optional Flow Limit
Cycle Time Control	1-60 min	Configurable ON/OFF durations
Constant Speed	500-4500 RPM	Fixed speed with optional Flow Limit
Constant Pressure	0.5-10.0 m	Fixed head pressure
Constant Flow	0.1-10.0 m³/h	Fixed flow rate

Proportional Pressure (0.5-10.0 m) is also fully supported.

These are the ranges the client accepts, and they are not the pump's.

For the four scalar modes the pump has narrower limits of its own and clamps rather than refuses — ask for 600 RPM and it stores 1650; ask for 4400 and it stores 3671. A clamped write is a successful write; WriteResult.value tells you what was actually stored.

For the temperature range the pump validates nothing — measured, it stored −10 °C and 120 °C without complaint — so the client's bound is the only one there is. See Verified Writes.

Documentation

Complete documentation: https://eman.github.io/alpha-hwr/

• Installation Guide
• Quick Start Tutorial
• CLI Reference
• Python API Reference
• Verified Writes
• Run State & Schedules
• Control Modes Guide
• Protocol Documentation

Examples

Monitor Telemetry Stream

async with AlphaHWRClient(address) as client:
    # Stream telemetry updates
    async for telemetry in client.telemetry.monitor():
        print(
            f"Flow: {telemetry.flow_m3h:.2f} m³/h, "
            f"Head: {telemetry.head_m:.2f} m, "
            f"Power: {telemetry.power_w:.1f} W"
        )

Manage Schedules

from alpha_hwr.models import ScheduleEntry

async with AlphaHWRClient(address) as client:
    # Create a schedule entry for Monday 6:00 AM - 8:30 AM
    entry = ScheduleEntry(
        day="Monday",
        begin_hour=6,
        begin_minute=0,
        end_hour=8,
        end_minute=30,
        layer=0,
    )

    # Write schedule and enable it
    await client.schedule.write_entries([entry], layer=0)
    await client.schedule.enable()

Backup & Restore Configuration

async with AlphaHWRClient(address) as client:
    # Backup current configuration
    await client.config.backup("pump_backup.json")
    
    # Restore from backup
    await client.config.restore("pump_backup.json")

Project Status

Actively maintained and tested on real ALPHA HWR hardware.

Home Assistant

For Home Assistant integration, it is suggested to use the ESPHome component instead of this library: esphome-alpha-hwr. It runs on an ESP32 as a Bluetooth proxy, exposing the pump as native Home Assistant sensors without requiring a Python host.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE for details.

Links

• PyPI: https://pypi.org/project/alpha-hwr/
• Documentation: https://eman.github.io/alpha-hwr/
• Source Code: https://github.com/eman/alpha-hwr
• Issue Tracker: https://github.com/eman/alpha-hwr/issues