alpha-hwr 0.5.0

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

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