Grundfos ALPHA HWR Python Library

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

Features

• Automatic discovery and pairing with ALPHA HWR pumps
• Stream telemetry data (flow, pressure, power, temperature)
• Set pump modes and setpoints with automatic validation
• 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

Quick Start

Command Line

# Discover nearby pumps
alpha-hwr device scan

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

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

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

Python Library

import asyncio
from alpha_hwr import AlphaHWRClient

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 mode
        await client.control.set_constant_pressure(1.5)  # 1.5 meters
        
        # 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	Setpoint Range	Notes
Temperature Control	20-60°C	Dual setpoints (min/max), AUTOADAPT flow adjustment, optional Flow Limit
Cycle Time Control	1-60 min	Configurable ON/OFF durations
Constant Curve	1000-4500 RPM	Fixed speed with optional Flow Limit
Constant Pressure	0.5-6.0 m	Fixed head pressure
Constant Flow	0.1-3.0 m³/h	Fixed flow rate

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

Documentation

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

• Installation Guide
• Quick Start Tutorial
• CLI Reference
• Python API Reference
• 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.

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