Configuration Backup and Restore Guide

This guide explains how to backup and restore the complete configuration of your Grundfos ALPHA HWR pump using the alpha-hwr library.

Overview

The backup and restore functionality allows you to:

Save your pump configuration to a JSON file for safekeeping
Restore configuration from a backup file
Transfer settings between pumps (with caution)
Version control your pump configuration using git or other tools
Quickly recover from configuration mistakes

What Gets Backed Up

A configuration backup includes:

Device Information
Serial number
Product name (ALPHA HWR)
Hardware version
Software version
Control Mode Configuration
Active control mode (e.g., Constant Pressure)
Setpoint value
Dual setpoints (e.g., Min/Max Temperature for Range Control)
Unit of measurement
Schedule Configuration
Global schedule enabled/disabled state
All schedule entries for all days
All 5 schedule layers (0-4)

Backup File Format

Backups are stored as human-readable JSON files:

{
  "version": "1.0",
  "timestamp": "2026-01-29T12:00:00Z",
  "device": {
    "serial_number": "12345678",
    "product_name": "ALPHA HWR",
    "hardware_version": "1.0",
    "software_version": "2.0"
  },
  "control_mode": {
    "mode_name": "Constant Pressure",
    "setpoint": 3.5,
    "setpoint_unit": "m"
  },
  "schedule": {
    "enabled": true,
    "days": [
      {
        "day": "Monday",
        "enabled": true,
        "action": 2,
        "begin_hour": 6,
        "begin_minute": 0,
        "end_hour": 8,
        "end_minute": 0,
        "begin_time": "06:00",
        "end_time": "08:00",
        "layer": 0
      }
    ]
  }
}

Using the CLI

Backup Configuration

The simplest way to backup your pump configuration:

# Backup to a file
alpha-hwr backup pump_backup.json

# Backup with timestamp in filename
alpha-hwr backup "pump_backup_$(date +%Y%m%d_%H%M%S).json"

The backup will be saved to the specified file. Parent directories will be created automatically if they don't exist.

Restore Configuration

To restore a previously saved configuration:

# Full restore (will prompt for confirmation)
alpha-hwr restore pump_backup.json

# Restore only control mode (skip schedule)
alpha-hwr restore pump_backup.json --skip-schedule

# Restore only schedule (skip control mode)
alpha-hwr restore pump_backup.json --skip-mode

# Restore to different pump (skip serial number verification)
alpha-hwr restore pump_backup.json --no-verify

Important: The restore command will show you what will be changed and ask for confirmation before proceeding.

Using the Python API

Basic Backup

import asyncio
from alpha_hwr import AlphaHWRClient

async def backup_config():
    async with AlphaHWRClient("YOUR-DEVICE-UUID") as client:
        await client.authenticate(fast_mode=True)

        # Backup current configuration
        success = await client.config.backup("pump_backup.json")
        if success:
            print(" Configuration backed up successfully")
        else:
            print(" Backup failed")

asyncio.run(backup_config())

Basic Restore

import asyncio
from alpha_hwr import AlphaHWRClient

async def restore_config():
    async with AlphaHWRClient("YOUR-DEVICE-UUID") as client:
        await client.authenticate(fast_mode=True)

        # Restore configuration with all safety checks
        success = await client.config.restore("pump_backup.json")
        if success:
            print(" Configuration restored successfully")
        else:
            print(" Restore failed")

asyncio.run(restore_config())

Selective Restore

You can restore only specific parts of the configuration:

async def selective_restore():
    async with AlphaHWRClient("YOUR-DEVICE-UUID") as client:
        await client.authenticate(fast_mode=True)

        # Restore only control mode (skip schedule)
        await client.config.restore(
            "pump_backup.json",
            restore_mode=True,
            restore_schedule=False
        )

        # Or restore only schedule (skip control mode)
        await client.config.restore(
            "pump_backup.json",
            restore_mode=False,
            restore_schedule=True
        )

Device Verification

By default, the restore process verifies that the serial number in the backup matches the connected pump. This prevents accidentally restoring to the wrong device.

async def restore_with_verification():
    async with AlphaHWRClient("YOUR-DEVICE-UUID") as client:
        await client.authenticate(fast_mode=True)

        # Restore with device verification (default)
        success = await client.config.restore(
            "pump_backup.json",
            verify_device=True  # This is the default
        )

        if not success:
            print("Restore failed - serial number mismatch")

To transfer a backup to a different pump, you must explicitly skip device verification:

async def transfer_to_different_pump():
    async with AlphaHWRClient("DIFFERENT-PUMP-UUID") as client:
        await client.authenticate(fast_mode=True)

        # Skip device verification to restore to different pump
        success = await client.config.restore(
            "pump_backup.json",
            verify_device=False  # Allow restoring to different device
        )

        if success:
            print(" Configuration transferred to new pump")

Common Use Cases

1. Before Making Changes

Always backup before experimenting with settings:

# Backup current working configuration
alpha-hwr backup pump_working.json

# Make experimental changes...
alpha-hwr control set-pressure 5.0

# If something goes wrong, restore
alpha-hwr restore pump_working.json

2. Configuration Versioning

Store backups in a git repository for version control:

# Create dated backup
alpha-hwr backup "backups/pump_$(date +%Y%m%d).json"

# Commit to git
git add backups/
git commit -m "Pump configuration backup - $(date)"

# Later, restore specific version
git log --oneline backups/
git checkout <commit> -- backups/pump_20260115.json
alpha-hwr restore backups/pump_20260115.json

3. Scheduled Backups

Automate regular backups with a cron job or systemd timer:

# Create backup script
cat > /usr/local/bin/backup-pump.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/var/backups/alpha-hwr"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"
alpha-hwr backup "$BACKUP_DIR/pump_$DATE.json"
# Keep only last 30 days
find "$BACKUP_DIR" -name "pump_*.json" -mtime +30 -delete
EOF

chmod +x /usr/local/bin/backup-pump.sh

# Add to crontab (daily at 2am)
# 0 2 * * * /usr/local/bin/backup-pump.sh

4. Deployment Across Multiple Pumps

Transfer a tested configuration to multiple identical pumps:

import asyncio
from alpha_hwr import AlphaHWRClient

async def deploy_config_to_pumps():
    pump_addresses = [
        "PUMP-UUID-1",
        "PUMP-UUID-2",
        "PUMP-UUID-3"
    ]

    for address in pump_addresses:
        print(f"Deploying to {address}...")
        async with AlphaHWRClient(address) as client:
            await client.authenticate(fast_mode=True)

            # Skip device verification for deployment
            success = await client.config.restore(
                "standard_config.json",
                verify_device=False
            )

            if success:
                print(f"   {address} configured")
            else:
                print(f"   {address} failed")

asyncio.run(deploy_config_to_pumps())

Safety Features

Version Checking

The restore process verifies that the backup file format version is supported. If you try to restore an incompatible backup:

ERROR: Unsupported backup version: 2.0

Device Serial Number Verification

By default, the restore process checks that the backup was created from the same pump:

ERROR: Device serial number mismatch
  Backup:    12345678
  Connected: 87654321
Use --no-verify to restore anyway

Validation

All restored values are validated before being applied to the pump.

Logging

All backup and restore operations are logged for troubleshooting:

import logging
logging.basicConfig(level=logging.INFO)

# You'll see detailed logs like:
# INFO: Reading device information...
# INFO: Reading control mode...
# INFO: Reading schedule configuration...
# INFO: Configuration backed up successfully

Troubleshooting

"Backup failed"

Check: - Pump is connected and authenticated - You have write permissions to the output directory - Disk space is available

"Restore failed - version mismatch"

The backup file was created with a newer version of the library. Update alpha-hwr:

pip install --upgrade alpha-hwr

"Device serial number mismatch"

You're trying to restore a backup from a different pump. Either: - Use the correct backup file for this pump - Use --no-verify flag if you intentionally want to transfer settings

"Restore succeeded but pump didn't change"

Check the logs to see if specific restore steps were skipped (e.g., using --skip-mode or --skip-schedule).

Best Practices

Backup before changes: Always create a backup before modifying pump settings
Label backups: Use descriptive filenames with dates and descriptions
Test restores: Periodically test that your backups can be restored
Store safely: Keep backups in a safe location (e.g., version control, cloud storage)
Document changes: Add comments in commit messages when storing backups in git
Verify after restore: Check that the pump is operating correctly after restoration

API Reference

For complete API documentation, see: - ConfigurationService