Command Line Interface (CLI) Guide

The alpha-hwr command-line tool for interacting with Grundfos ALPHA HWR pumps. Built on Typer and Rich.

Installation

The CLI is automatically installed with the alpha-hwr package:

pip install alpha-hwr

Verify installation:

alpha-hwr --version

Get help:

alpha-hwr --help

Configuration

Device Address

The CLI needs your pump's Bluetooth address. You can provide it in two ways:

1. Command-line option (recommended for scripts):

alpha-hwr monitor live --device "YOUR-DEVICE-ADDRESS"

2. Configuration file (recommended for interactive use):

Create ~/.config/alpha-hwr/config.json:

{
  "device_address": "YOUR-DEVICE-ADDRESS"
}

Address Format:

macOS: UUID format (e.g., A1B2C3D4-E5F6-7890-1234-567890ABCDEF)
Linux/Windows: MAC address (e.g., 00:11:22:33:44:55)

Finding Your Pump's Address

Use a BLE scanner app (nRF Connect, LightBlue) or run this Python snippet:

python -c "
import asyncio
from bleak import BleakScanner

async def scan():
    devices = await BleakScanner.discover(timeout=10.0)
    for d in devices:
        if d.name and 'ALPHA' in d.name:
            print(f'{d.address} - {d.name}')

asyncio.run(scan())
"

Basic Usage

All commands follow this pattern:

alpha-hwr [GROUP] [COMMAND] [OPTIONS]

Command Groups:

monitor - Real-time telemetry monitoring
history - Historical trends and timestamps
events - Event log access
control - Pump control operations
device - Device information and statistics
clock - Real-time clock management
schedule - Schedule management
config - Configuration backup/restore

Global Options:

--device/-d ADDRESS - Device address (overrides config file)
--help - Show help message
--version - Show version

Get help for any command:

alpha-hwr monitor --help
alpha-hwr control start --help

Monitoring Commands

Live Monitoring

Continuously display real-time telemetry data:

# Default: table format, 1-second updates
alpha-hwr monitor live

# Custom update interval
alpha-hwr monitor live --interval 2.0

# JSON output (for automation)
alpha-hwr monitor live --format json

# Specify device explicitly
alpha-hwr monitor live --device "AA:BB:CC:DD:EE:FF"

Example Output (Table):

┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Metric         ┃ Value    ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ Flow Rate      │ 2.5 m³/h │
│ Head Pressure  │ 1.5 m    │
│ Power          │ 50.0 W   │
│ Speed          │ 2500 RPM │
│ Water Temp     │ 45.5 °C  │
│ Electronics    │ 35.2 °C  │
│ Status         │ Running  │
└────────────────┴──────────┘

Press Ctrl+C to stop monitoring.

Single Snapshot

Take a one-time telemetry reading:

# Table format (default)
alpha-hwr monitor snapshot

# JSON format
alpha-hwr monitor snapshot --format json

Example JSON Output:

{
  "timestamp": "2026-01-30T12:00:00Z",
  "flow_m3h": 2.5,
  "head_m": 1.5,
  "power_w": 50.0,
  "speed_rpm": 2500,
  "media_temp_c": 45.5,
  "pcb_temp_c": 35.2,
  "running": true
}

History and Events

Historical Trends

View historical trend data for flow, head, temperature, and power-on time:

# Show last 10 cycles (high resolution)
alpha-hwr history trends

# Show last 100 cycles (full history)
alpha-hwr history trends --detailed

Event Log

View the pump's event log (last 20 entries):

# List all events
alpha-hwr events list

# Show specific entry details
alpha-hwr events show 0

# Show event metadata
alpha-hwr events metadata

Cycle Timestamps

View timestamps for recent pump cycles:

# Show last 10 cycle timestamps
alpha-hwr history timestamps

# Show last 100 cycle timestamps
alpha-hwr history timestamps --count 100

Control Commands

Start and Stop

# Start the motor in whatever mode the pump is already in
alpha-hwr control start

# Stop the pump
alpha-hwr control stop

start takes no mode and no setpoint: it changes the run state and nothing else. To change the mode as well, run control set-mode first.

A running pump with the weekly schedule enabled circulates only inside its scheduled windows, so control start alone does not necessarily move water — check schedule list.

Set Control Mode

The pump supports multiple control modes specifically optimized for hot water recirculation.

Temperature Control

Maintains temperature within a specified range (Mode 27):

# Set range 35-39°C with AUTOADAPT enabled (default)
alpha-hwr control set-temperature --min 35 --max 39

# Set custom range with no autoadapt and a flow limit
alpha-hwr control set-temperature --min 40 --max 45 --no-autoadapt

Cycle Time Control

Operates the pump in on/off cycles (Mode 25):

# Set 5 minutes ON, 15 minutes OFF
alpha-hwr control set-cycle-time --on 5 --off 15

# View current cycle times
alpha-hwr control get-cycle-time

Constant Speed

Runs at fixed RPM (Mode 2):

# Set to 2500 RPM with 2.3 GPM flow limit
alpha-hwr control set-speed 2500

Constant Pressure

Maintains fixed head pressure (Mode 0):

# Set to 1.5 meters head
alpha-hwr control set-pressure 1.5

Constant Flow

Maintains specific flow rate (Mode 8):

# Set to 0.5 m³/h
alpha-hwr control set-flow 0.5

Proportional Pressure

Adjusts pressure based on flow rate (Mode 1):

# Set proportional pressure with 1.2m base
alpha-hwr control set-proportional 1.2

Flow Limitation

Set a global maximum flow limit to prevent corrosion:

# Set 1.5 GPM limit (recommended for 1/2" pipe)
alpha-hwr control limiters

Device Information

Scan for Pumps

Scan for nearby ALPHA HWR pumps advertising on BLE:

# Default: 10-second scan
alpha-hwr device scan

# Custom timeout
alpha-hwr device scan --timeout 5.0

Basic Information

Display pump identification and firmware details:

alpha-hwr device info

Example Output:

┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field              ┃ Value                ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ Product Name       │ ALPHA HWR            │
│ Product Family     │ ALPHA (52)           │
│ Product Type       │ HWR (7)              │
│ Serial Number      │ 12345678             │
│ Software Version   │ 2.34.0               │
│ Hardware Version   │ 1.5.2                │
│ BLE Version        │ 1.2.3                │
└────────────────────┴──────────────────────┘

Device Statistics

View cumulative operating statistics:

alpha-hwr device stats

Example Output:

Operating Time: 1,234 hours
Start Count: 5,678 starts
Average Runtime: 13 minutes per cycle

Active Alarms

Check for active alarms and warnings:

alpha-hwr device alarms

Clock Management

View Clock

Check the pump's internal real-time clock (RTC) and compare it with system time:

alpha-hwr clock view

Synchronize Clock

Synchronize the pump's clock with your computer's time:

alpha-hwr clock sync

Note: Correct clock time is essential for accurate scheduling and event logging.

Schedule Management

The pump supports weekly schedules across 5 independent layers (0-4).

View Schedule

alpha-hwr schedule list

Example Output:

Schedule: Enabled

  Monday     06:00 - 08:00
  Tuesday    06:00 - 08:00
  Wednesday  06:00 - 08:00
  Thursday   06:00 - 08:00
  Friday     06:00 - 08:00

Enable/Disable Schedule

# Enable the schedule globally
alpha-hwr schedule enable

# Disable the schedule globally
alpha-hwr schedule disable

A schedule over a stopped pump never runs

With the schedule enabled and the pump stopped, every window opens with the motor idle and nothing reports a fault — the water simply goes cold. Enabling a schedule is not the same as starting the pump; do both.

Add and Remove Entries

Day, start time, end time — all positional:

# Monday 06:00-08:30
alpha-hwr schedule add monday 06:00 08:30

# Remove Monday's entry
alpha-hwr schedule remove monday

Clear Schedule

# Remove every entry (prompts unless -f is given)
alpha-hwr schedule clear
alpha-hwr schedule clear -f

Configuration Backup & Restore

Backup Configuration

Save the current pump configuration to a file:

# Backup to an auto-named file under ~/.config/alpha-hwr/backups/
alpha-hwr config backup

# Backup to a specific file
alpha-hwr config backup my_backup.json

# Overwrite an existing file without prompting
alpha-hwr config backup my_backup.json -f

The output path is a positional argument. With none given, the filename is built from the pump's serial number and the local time.

Restore Configuration

alpha-hwr config restore my_backup.json

# Skip the confirmation prompt
alpha-hwr config restore my_backup.json -f

The input path is required — there is no default-backup lookup, no dry run, and no way to restore one component in isolation.

Restore reports success before the pump has agreed

Restore drives the unverified setters, so a value the pump clamps is still reported as restored. Read the state back with control status afterwards.

Output Formats

The two monitor commands take --format. Everything else prints a table.

Table Format (Default)

alpha-hwr monitor snapshot
alpha-hwr device info
alpha-hwr schedule list

JSON Format

Machine-readable output for scripts — monitor live and monitor snapshot only:

alpha-hwr monitor snapshot --format json
alpha-hwr monitor live --format json

Use cases: - Automation scripts - Integration with other tools - Data logging and analysis

Example: Log telemetry to file

while true; do
  alpha-hwr monitor snapshot --format json >> telemetry.log
  sleep 60
done

Troubleshooting

Connection Issues

Symptom: Failed to connect to device

Solutions:

Verify device address:

# Scan for devices
python -m alpha_hwr.utils.scan

Check Bluetooth is enabled:
macOS: System Preferences → Bluetooth
Linux: sudo systemctl status bluetooth
Windows: Settings → Bluetooth
Disconnect from other apps:
Ensure no other applications are connected to the pump
Disconnect from other BLE connections
Increase connection timeout:
```
alpha-hwr monitor live --interval 2
```

Authentication Failed

Symptom: Authentication failed

Solutions:

Restart pump: Power cycle the pump
Reset BLE: Restart Bluetooth adapter
Clear pairing: Re-pair the device

Command Not Found

Symptom: alpha-hwr: command not found

Solutions:

Verify installation:
```
pip show alpha-hwr
```
Check PATH:
```
echo $PATH
```

Reinstall:

pip uninstall alpha-hwr
pip install alpha-hwr

No Telemetry Data

Symptom: Telemetry shows all zeros or times out

Solutions:

Check pump is running: Pump must be started
Wait after start: Allow 2-3 seconds for telemetry to stabilize
Verify authentication: Ensure authentication succeeded

Advanced Usage

Scripting Examples

Log telemetry every minute:

#!/bin/bash
while true; do
    timestamp=$(date -Iseconds)
    telemetry=$(alpha-hwr monitor snapshot --format json)
    echo "$timestamp $telemetry" >> pump_log.jsonl
    sleep 60
done

Set mode based on time of day:

#!/bin/bash
hour=$(date +%H)

if [ $hour -ge 6 ] && [ $hour -lt 9 ]; then
    # Morning: high pressure
    alpha-hwr control set-mode constant-pressure 3.0
elif [ $hour -ge 18 ] && [ $hour -lt 22 ]; then
    # Evening: medium pressure
    alpha-hwr control set-mode constant-pressure 2.0
else
    # Off hours: stop
    alpha-hwr control stop
fi

Monitor and alert on low flow:

#!/bin/bash
while true; do
    flow=$(alpha-hwr monitor snapshot --format json | jq -r '.flow_m3h')
    if (( $(echo "$flow < 0.5" | bc -l) )); then
        echo "ALERT: Low flow detected: $flow m³/h"
        # Send notification (e.g., via email, SMS, webhook)
    fi
    sleep 10
done

Environment Variables

Configure via environment variables:

# Set device address
export ALPHA_HWR_DEVICE_ADDRESS="AA:BB:CC:DD:EE:FF"

# Set Bluetooth adapter (Linux)
export ALPHA_HWR_ADAPTER="hci0"

# Enable debug logging
export ALPHA_HWR_DEBUG=1

# Now use CLI without --device flag
alpha-hwr monitor live

Command Reference

Monitor Commands

Command	Description
`monitor live`	Continuous real-time monitoring
`monitor snapshot`	Single telemetry reading

History Commands

Command	Description
`history trends`	Show historical trend data
`history timestamps`	Show cycle timestamps

Event Commands

Command	Description
`events list`	List event log entries
`events show`	Show entry details
`events metadata`	Show event log metadata

Control Commands

Command	Description
`control start`	Start pump
`control stop`	Stop pump
`control set-temperature`	Set temperature range control (Mode 27)
`control set-cycle-time`	Set DHW cycle time control (Mode 25)
`control get-cycle-time`	Get DHW cycle time configuration
`control set-pressure`	Set constant pressure mode (Mode 0)
`control set-speed`	Set constant speed mode (Mode 2)
`control set-flow`	Set constant flow mode (Mode 8)
`control set-proportional`	Set proportional pressure mode (Mode 1)
`control limiters`	Show the MaxFlow and MinFlow limiters
`control set-mode <mode> <setpoint>`	Set control mode and setpoint together

Device Commands

Command	Description
`device scan`	Scan for nearby pumps
`device info`	Show device information
`device stats`	Show operating statistics
`device alarms`	Show active alarms

Clock Commands

Command	Description
`clock view`	View pump clock
`clock sync`	Sync pump clock with system

Schedule Commands

Command	Description
`schedule list`	Display current schedule
`schedule enable`	Enable schedule globally
`schedule disable`	Disable schedule globally
`schedule add`	Add an entry (`add monday 06:00 08:30`)
`schedule remove`	Remove a day's entry
`schedule clear`	Clear every entry

Config Commands

Command	Description
`config backup`	Backup pump configuration to a file
`config restore`	Restore from a backup file

Getting Help

For command-specific help, use --help:

alpha-hwr --help
alpha-hwr monitor --help
alpha-hwr control set-mode --help
alpha-hwr schedule add --help

For issues or questions: - GitHub Issues: https://github.com/eman/alpha-hwr - Documentation: See docs/ directory - Protocol Reference: See docs/protocol/

Command Line Interface (CLI) Guide

Table of Contents

Installation

Configuration

Device Address

Finding Your Pump's Address

Basic Usage

Monitoring Commands

Live Monitoring

Single Snapshot

History and Events

Historical Trends

Event Log

Cycle Timestamps

Control Commands

Start and Stop

Set Control Mode

Temperature Control

Cycle Time Control

Constant Speed

Constant Pressure

Constant Flow

Proportional Pressure

Flow Limitation

Device Information

Scan for Pumps

Basic Information

Device Statistics

Active Alarms

Clock Management

View Clock

Synchronize Clock

Schedule Management

View Schedule

Enable/Disable Schedule

Add and Remove Entries

Clear Schedule

Configuration Backup & Restore

Backup Configuration

Restore Configuration

Output Formats

Table Format (Default)

JSON Format

Troubleshooting

Connection Issues

Authentication Failed

Command Not Found

No Telemetry Data

Advanced Usage

Scripting Examples

Environment Variables

Command Reference

Monitor Commands

History Commands

Event Commands

Control Commands

Device Commands

Clock Commands

Schedule Commands

Config Commands

Getting Help