Client API

The AlphaHWRClient is the main entry point for interacting with Grundfos ALPHA HWR pumps. It provides a service-oriented architecture where specialized services handle different aspects of pump communication.

Overview

The client acts as a facade and coordinator for specialized services:

• Telemetry - Real-time sensor data and monitoring
• Control - Pump control operations (start, stop, mode changes)
• Schedule - Weekly schedule management across 5 layers
• Device Info - Device identification and statistics
• Configuration - Backup and restore operations
• Time - Real-time clock management
• History - Historical trend data (100 cycles)
• Event Log - Pump event history (20 entries)

Basic Usage

import asyncio
from alpha_hwr import AlphaHWRClient

async def main():
    # Connect using context manager (automatic disconnect)
    async with AlphaHWRClient("AA:BB:CC:DD:EE:FF") as client:
        # Read telemetry
        data = await client.telemetry.read_once()
        print(f"Flow: {data.flow_m3h} m³/h")

        # Control pump
        await client.control.set_constant_pressure(1.5)

        # Manage schedules
        entries = await client.schedule.read_entries()

asyncio.run(main())

API Reference

alpha_hwr.client.AlphaHWRClient

Main client for Grundfos ALPHA HWR pump interaction.

Provides a unified API for all pump operations through specialized services. Manages BLE connection, authentication, and service lifecycle.

Services

telemetry: Read sensor data (flow, pressure, power, temperature) control: Start/stop pump, set modes and setpoints schedule: Manage weekly pump schedules device_info: Read device identification and statistics config: Backup and restore pump configuration time: Read and synchronize pump real-time clock history: Read historical trend data (flow, head, temperature) event_log: Read pump event log entries and metadata

Attributes:

Name	Type	Description
address	str | None	BLE device address (UUID on macOS, MAC on Linux/Windows)
adapter	str | None	Optional BLE adapter identifier
session	Session | None	Session manager (tracks authentication state)
transport	Transport | None	BLE transport layer
auth	AuthenticationHandler | None	Authentication handler

Example

async with AlphaHWRClient("DEVICE_ADDRESS") as client: ... # Telemetry ... data = await client.telemetry.read_once() ... print(f"Flow: {data.flow_m3h} m³/h") ... ... # Control ... await client.control.start() ... await client.control.set_constant_pressure(1.5) ... ... # Schedule ... await client.schedule.enable() ... ... # Backup ... await client.config.backup("pump.json")

Implementation Notes

The client is a thin orchestration layer. All business logic lives in the service modules. This makes the code: - Easier to understand (single responsibility per service) - Easier to test (mock services independently) - Easier to port (services are self-contained)

telemetry = None instance-attribute

control = None instance-attribute

device_info = None instance-attribute

schedule = None instance-attribute

history = None instance-attribute

config = None instance-attribute

__init__(address=None, adapter=None, auto_authenticate=True)

Initialize the ALPHA HWR client.

Parameters:

Name	Type	Description	Default
address	str | None	BLE device address (UUID on macOS, MAC on Linux/Windows). If None, reads from ALPHA_HWR_DEVICE_ADDRESS env variable.	None
adapter	str | None	Optional BLE adapter identifier (platform-specific)	None
auto_authenticate	bool	Automatically authenticate after connection (default True)	True

Example

Use address from environment

client = AlphaHWRClient()

Use specific address

client = AlphaHWRClient("A1B2C3D4-E5F6-7890-1234-567890ABCDEF")

Specify adapter (Linux)

client = AlphaHWRClient(address="00:11:22:33:44:55", adapter="hci1")

connect(timeout=60.0, fast_mode=False) async

Connect to the pump via BLE.

Establishes BLE connection, initializes transport layer, and sets up all service modules. If auto_authenticate is enabled, also performs authentication handshake.

If no address is configured, automatically attempts to discover a nearby ALPHA HWR pump.

Parameters:

Name	Type	Description	Default
timeout	float	Connection timeout in seconds (default 60s)	60.0
fast_mode	bool	If True, skips authentication delays (for testing)	False

Raises:

Type	Description
ConnectionError	If connection fails or no device found during discovery
ValueError	If discovery fails

Example

Connect to specific address

client = AlphaHWRClient("DEVICE_ADDRESS") await client.connect()

Connect using automatic discovery

client = AlphaHWRClient() await client.connect()

Implementation Notes

Connection sequence: 1. Resolve address (discovery if needed) 2. Scan for advertisement data before connecting 3. Create BleakClient with device address ...

disconnect() async

Disconnect from the pump.

Cleanly shuts down all services, stops BLE notifications, and disconnects from the device.

Example

await client.disconnect() print(f"Connected: {client.is_connected}") # False

Implementation Notes

Disconnect sequence: 1. Stop BLE notifications 2. Clear service references 3. Disconnect BLE client 4. Reset all state

Safe to call multiple times (idempotent).

authenticate(fast_mode=False) async

Authenticate with the pump.

Performs the authentication handshake to enable control operations. Read-only operations (telemetry, device info) don't require authentication, but control operations (start, stop, mode changes) do.

Parameters:

Name	Type	Description	Default
fast_mode	bool	If True, skips delays for testing purposes.	False

Returns:

Type	Description
bool	True if authentication successful, False otherwise

Example

success = await client.authenticate() if success: ... print("Authenticated successfully") ... await client.control.start()

__aenter__() async

Async context manager entry - connects to pump.

__aexit__(exc_type, exc_val, exc_tb) async

Async context manager exit - disconnects from pump.