ESPHome ALPHA HWR + DHW Demand

ESPHome repository for two custom components:

• alpha_hwr — BLE telemetry and control for the Grundfos ALPHA HWR pump
• dhw_demand — on-device DHW demand detection using pump telemetry and/or Home Assistant sensors

The repo also ships reusable package YAML so an external ESPHome config can pull in the component stack directly from GitHub.

What each package does

Package	Purpose	Notes
packages/alpha_hwr_base.yaml	Basic ALPHA HWR telemetry without BLE pairing	Good starting point for read-only monitoring
packages/alpha_hwr_pairing.yaml	Full telemetry, diagnostics, schedules, and paired BLE access	Required for controls and schedule editing
packages/alpha_hwr_controls.yaml	Recommended control UI	Adds pump enable, remote mode, schedule toggle, mode select, and setpoint controls
packages/alpha_hwr_schedule.yaml	Lighter schedule/remote/mode UI	Simpler alternative to alpha_hwr_controls.yaml; avoid combining both unless you want duplicate controls
packages/alpha_hwr_schedule_editor.yaml	ESPHome services and helper entities for weekly/single-event editing	Pair with alpha_hwr_pairing.yaml
packages/dhw_demand_detector.yaml	DHW detector outputs plus Home Assistant supplementary sensors	Works standalone or alongside alpha_hwr

Requirements

• alpha_hwr: ESP32-class board with BLE (ESP32, ESP32-C3, ESP32-S3)
• dhw_demand standalone: any ESPHome-capable board if you only use Home Assistant-fed sensors
• substitutions.mac_address for the pump packages
• api: enabled if you want Home Assistant services/entities
• framework.type: esp-idf is strongly recommended for BLE-based ALPHA HWR nodes

Basic vs paired alpha_hwr

Feature	alpha_hwr_base.yaml	alpha_hwr_pairing.yaml
Flow, head, water temperature, RPM, power	Yes	Yes
AC/DC voltage, motor current	No	Yes
Inlet pressure	No	Yes
PCB and control-box temperatures	No	Yes
Pairing status	No	Yes
Control mode text sensor	No	Yes
Schedule and single-event text sensors	No	Yes
Start/stop, remote control, schedule toggle, mode/setpoint UI	No	Add alpha_hwr_controls.yaml or alpha_hwr_schedule.yaml
Device info, history, event log, statistics	No	Yes

Using these packages from an external ESPHome config

The package URLs below are meant to be used from another ESPHome project. The package files already pull the required external components for alpha_hwr.

1. Basic read-only pump telemetry

esphome:
  name: hwr-pump
  friendly_name: HWR Pump

substitutions:
  mac_address: "AA:BB:CC:DD:EE:FF"

packages:
  alpha_hwr: github://eman/esphome-alpha-hwr/packages/alpha_hwr_base.yaml@main

esp32:
  board: esp32-c3-devkitm-1
  variant: esp32c3
  framework:
    type: esp-idf

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
  encryption:
    key: !secret api_key

ota:
  - platform: esphome
    password: !secret ota_password

2. Full telemetry plus control UI

esphome:
  name: hwr-pump
  friendly_name: HWR Pump

substitutions:
  mac_address: "AA:BB:CC:DD:EE:FF"

packages:
  alpha_hwr: github://eman/esphome-alpha-hwr/packages/alpha_hwr_pairing.yaml@main
  alpha_hwr_controls: github://eman/esphome-alpha-hwr/packages/alpha_hwr_controls.yaml@main

esp32:
  board: esp32-c3-devkitm-1
  variant: esp32c3
  framework:
    type: esp-idf

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
  encryption:
    key: !secret api_key

ota:
  - platform: esphome
    password: !secret ota_password

3. Add schedule editor services

Add the schedule editor package on top of the paired pump config:

packages:
  alpha_hwr: github://eman/esphome-alpha-hwr/packages/alpha_hwr_pairing.yaml@main
  alpha_hwr_controls: github://eman/esphome-alpha-hwr/packages/alpha_hwr_controls.yaml@main
  alpha_hwr_schedule_editor: github://eman/esphome-alpha-hwr/packages/alpha_hwr_schedule_editor.yaml@main

alpha_hwr_schedule_editor.yaml exposes ESPHome services such as set_schedule_entry and set_single_event.

4. Standalone dhw_demand

When you use dhw_demand without alpha_hwr, declare the component explicitly with external_components:

esphome:
  name: dhw-detector
  friendly_name: DHW Detector

substitutions:
  flow_entity: sensor.droplet_flow_rate
  tank_lower_temp_entity: sensor.tank_lower_temperature
  dhw_charge_entity: sensor.dhw_charge

external_components:
  - source: github://eman/esphome-alpha-hwr@main
    components: [dhw_demand]

packages:
  dhw_demand: github://eman/esphome-alpha-hwr/packages/dhw_demand_detector.yaml@main

esp32:
  board: esp32dev

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
ota:
  - platform: esphome

5. Combined alpha_hwr + dhw_demand

If you want pump telemetry plus DHW demand detection, combine the packages and wire the pump sensors into the detector:

packages:
  alpha_hwr: github://eman/esphome-alpha-hwr/packages/alpha_hwr_pairing.yaml@main
  alpha_hwr_controls: github://eman/esphome-alpha-hwr/packages/alpha_hwr_controls.yaml@main
  dhw_demand: github://eman/esphome-alpha-hwr/packages/dhw_demand_detector.yaml@main

alpha_hwr:
  current:
    id: motor_current_sensor
  power:
    id: pump_power_sensor
  rpm:
    id: motor_speed_sensor
  flow:
    id: flow_rate_sensor
  inlet_pressure:
    id: inlet_pressure_sensor
  head_rate:
    id: pump_head_rate_sensor

sensor:
  - platform: copy
    source_id: flow_rate_sensor
    id: dhw_pump_flow_gpm
    internal: true
    unit_of_measurement: "GPM"
    filters:
      - multiply: 4.40287

  - platform: copy
    source_id: inlet_pressure_sensor
    id: dhw_inlet_pressure_psi
    internal: true
    unit_of_measurement: "PSI"
    filters:
      - multiply: 14.5038

dhw_demand:
  motor_speed: motor_speed_sensor
  motor_current: motor_current_sensor
  inlet_pressure: dhw_inlet_pressure_psi
  pump_flow: dhw_pump_flow_gpm
  pump_power: pump_power_sensor
  pump_head_rate: pump_head_rate_sensor

For a complete working version, see dhw-demand-example.yaml.

Local development override

When you are working from a local clone and want ESPHome to build the local component sources instead of the cached GitHub copy, add:

external_components:
  - source:
      type: local
      path: components
    components: [alpha_hwr, dhw_demand]

That is the pattern used in dhw-demand-example.yaml.

Schedule services and entity names

alpha_hwr_schedule_editor.yaml creates ESPHome services. Home Assistant sees them as:

• esphome.<node_name>_set_schedule_entry
• esphome.<node_name>_clear_schedule_entry
• esphome.<node_name>_set_schedule_enabled
• esphome.<node_name>_refresh_schedule
• esphome.<node_name>_set_single_event
• esphome.<node_name>_clear_single_event
• esphome.<node_name>_refresh_single_events

<node_name> comes from esphome.name with - converted to _. Example:

• esphome.name: hwr-pump
• Home Assistant service: esphome.hwr_pump_set_schedule_entry

The paired package also publishes schedule text sensors using the same node-name prefix, for example text_sensor.hwr_pump_weekly_schedule.

More detail and automation examples are in docs/schedule-management.md.

Pairing

alpha_hwr_pairing.yaml enables BLE pairing and stores the bond in NVS. Typical first-time flow:

1. Put the pump into Bluetooth pairing mode.
2. Flash the ESPHome node with the paired package.
3. Watch logs for the authentication/pairing sequence to complete.

After that, reconnects reuse the stored bond.

Examples in this repo

• hwr-pump-example.yaml — basic read-only alpha_hwr
• hwr-pairing-example.yaml — paired alpha_hwr
• hwr-pump-schedule-example.yaml — paired pump with schedule UI/services
• dhw-demand-example.yaml — combined alpha_hwr + dhw_demand with local component override
• hwr-pump.yaml — real hardware config used for local verification

Optional Lovelace schedule card

The schedule card source ships in this repo at homeassistant/www/alpha-hwr-schedule-card.js. It is a separate Home Assistant frontend resource, so ESPHome does not install it automatically.

Prerequisites

• Use alpha_hwr_pairing.yaml so Home Assistant gets the weekly schedule and single-event text sensors.
• Use alpha_hwr_schedule_editor.yaml so Home Assistant gets the esphome.<node_name>_* services the card calls when you edit schedules.

Install the card in Home Assistant

1. Copy homeassistant/www/alpha-hwr-schedule-card.js from this repo into your Home Assistant www directory.
   • Home Assistant OS / Supervised: usually /config/www/alpha-hwr-schedule-card.js
   • Container installs: copy it into the mounted config directory under www/
2. In Home Assistant, open Settings → Dashboards → Resources and add:
   • URL: /local/alpha-hwr-schedule-card.js
   • Resource type: JavaScript Module
3. Refresh the browser, or reload the frontend resources if Home Assistant does not pick up the new card immediately.

Lovelace example

type: custom:alpha-hwr-schedule-card
title: Pump Schedule
device: hwr_pump
entity: text_sensor.hwr_pump_weekly_schedule
single_events_entity: text_sensor.hwr_pump_single_events

Choosing the right names

• device must match the ESPHome node-derived service prefix: esphome.name with - converted to _.
• entity should point at the weekly schedule text sensor from the paired package.
• single_events_entity is optional, but enables the card's quick-run and single-event display features.

For example, if esphome.name: hwr-pump, then Home Assistant service names use hwr_pump, so the card config should use:

• device: hwr_pump
• entity: text_sensor.hwr_pump_weekly_schedule
• single_events_entity: text_sensor.hwr_pump_single_events

References

• Configuration: docs/configuration.md
• Protocol docs: https://eman.github.io/alpha-hwr/reimplementation/
• Python reference implementation: https://github.com/eman/alpha-hwr
• ESPHome BLE client docs: https://esphome.io/components/ble_client/
• Architecture notes: docs/architecture.md
• Schedule service usage: docs/schedule-management.md