Home Assistant package for controlling an auxiliary electric heater in a DHW (Domestic Hot Water) boiler, designed to work alongside a heat pump system.

Features

Preset-based temperature control: Normal, Eco, Boost, Sleep, Away, Off - with user-adjustable temperatures per preset via dashboard sliders
PV Excess Utilization: Automatically uses surplus solar power to heat water instead of exporting to grid
Bath Boost with Timer: Timed rapid hot water heating with configurable duration
Manual Override: Emergency/testing control
Safety Interlocks: Prevents running both heat pump and boiler auxiliary heaters simultaneously
Energy Tracking: Runtime and energy consumption stats split by PV vs grid

System Architecture

                        SOLAR INVERTER
                              |
              sensor.deye_12_external_ct1/2/3_power
                     (3-phase grid power monitoring)
                              |
                              v
           binary_sensor.dhw_pv_power_enough_for_aux_heater
                 Checks: All 3 phases exporting enough?
                              |
                              v
              automation: DHW Manage PV Thermostat
                  (with configurable start/stop delays)
                              |
                              v
              climate.dhw_pv_excess_heating
                  (shadow thermostat for PV mode)
                              |
                              v
            binary_sensor.dhw_use_boiler_aux_heater
              MAIN DECISION: manual OR (allowed AND
                (pv_excess OR bath_boost OR normal_boost))
                              |
                              v
             automation: DHW Boiler Heater Relay
                              |
                              v
            switch.boiler_heater_relay_switch_0
                  (PHYSICAL RELAY - heater element)


     PRESET SYSTEM                    BATH BOOST
     --------------                   ----------
  input_select          -->   Preset   script.dhw_start_bath_boost
  dhw_boiler_preset           Manager        |
  input_number            -->    |      timer.bath_time
  dhw_boiler_temp_*              |            |
                                 v            v
                    climate.boiler_temperature    DHW Bath Time automation
                    (main thermostat)             (pump + boost on/off)

Installation

Copy use_excess_pv_in_boiler.yaml to your Home Assistant packages directory

Enable packages in configuration.yaml:

homeassistant:
  packages: !include_dir_named packages

Ensure all external entities exist (see External Dependencies)
Restart Home Assistant
Configure preset temperatures and thresholds via the UI

External Dependencies

These entities must already exist in your Home Assistant instance from other integrations or devices. They are not created by this package.

Sensors (from device integrations)

Entity	Source	Purpose
`sensor.boiler_temp`	Heat pump / temperature probe	Boiler water temperature
`sensor.deye_12_external_ct1_power`	Deye inverter integration	Phase 1 grid power (negative = export)
`sensor.deye_12_external_ct2_power`	Deye inverter integration	Phase 2 grid power
`sensor.deye_12_external_ct3_power`	Deye inverter integration	Phase 3 grid power
`sensor.heat_pump_auxiliary_heater`	Heat pump integration	HP aux heater state (interlock)

Switches (from device integrations)

Entity	Source	Purpose
`switch.boiler_heater_relay_switch_0`	Relay device (Shelly, etc.)	Physical heater control
`switch.acm_pump_switch`	Pump relay / smart plug	DHW circulation pump (used by bath boost)

Scheduler (optional integration)

Entity	Source	Purpose
`switch.schedule_f403a3`	Scheduler integration	Pump schedule restored after bath boost ends

Note

: If you don't use the Scheduler integration, remove the scheduler.run_action call from the DHW Bath Time automation.

Configuration

Boiler Temperature Presets

The preset system uses an input_select for mode selection and input_number entities for each preset's temperature. Users can adjust all temperatures from the dashboard without editing YAML.

Preset	Entity	Range	Intended Use
Normal	`input_number.dhw_boiler_temp_normal`	30-65°C	Everyday hot water
Eco	`input_number.dhw_boiler_temp_eco`	30-60°C	Energy saving mode
Boost	`input_number.dhw_boiler_temp_boost`	40-70°C	Rapid heating (also enables aux heater)
Sleep	`input_number.dhw_boiler_temp_sleep`	25-55°C	Nighttime lower temperature
Away	`input_number.dhw_boiler_temp_away`	20-50°C	Away from home
Off	—	—	Turns off the boiler thermostat

Selecting Boost also enables input_boolean.dhw_bath_boost, which allows the auxiliary heater to run (through the decision logic). All other presets disable it.

Bath Boost Timer

Entity	Purpose	Range
`input_number.dhw_bath_boost_duration`	Timer duration	5-120 min (step: 5)
`script.dhw_start_bath_boost`	Call to start the boost timer	—
`timer.bath_time`	Active countdown (shows remaining time)	—

How it works: Call script.dhw_start_bath_boost from a dashboard button. The timer starts, the automation turns on the circulation pump (switch.acm_pump_switch) and enables bath boost. When the timer expires, both are turned off and the pump schedule is restored.

Mode Toggles

Entity	Description
`input_boolean.dhw_aux_heater_manual_override`	Forces heater ON regardless of all other conditions
`input_boolean.dhw_allow_aux_heater_usage`	Master enable switch. Must be ON for any automatic operation
`input_boolean.dhw_use_excess_pv_for_aux_heater`	Enables PV excess utilization mode
`input_boolean.dhw_allow_aux_heater_in_all_modes`	Aux heater runs whenever main thermostat calls for heat (any preset)

PV Excess Thresholds

Entity	Description	Range
`input_number.dhw_aux_heater_cut_off_temperature_threshold`	Maximum temperature before heater stops	50-85°C
`input_number.dhw_pv_target_temperature`	Target temperature when using PV excess	40-70°C
`input_number.dhw_pv_excess_usage_buffer`	Extra export power required as safety margin	0-1000W
`input_number.dhw_aux_heater_power`	Rated power of your heater element	500-9000W
`input_number.dhw_pv_excess_usage_start_delay`	Seconds of stable export before starting	1-300s
`input_number.dhw_pv_excess_usage_stop_delay`	Seconds of insufficient export before stopping	1-300s

Usage Modes

1. Preset-Based Heating

Select a preset from input_select.dhw_boiler_preset. The thermostat target temperature is set automatically from the corresponding input_number. Adjust temperatures anytime via dashboard sliders.

2. PV Excess Mode

Automatically heats water when solar production exceeds consumption.

Enable: Turn ON input_boolean.dhw_use_excess_pv_for_aux_heater

Behavior:

Monitors 3-phase grid power (CT sensors)
Waits for start_delay seconds of sufficient export
Heats to dhw_pv_target_temperature
Stops after stop_delay seconds of insufficient export

3. Bath Boost (Timed)

Rapid heating with automatic timeout.

Trigger: Call script.dhw_start_bath_boost (e.g., from a dashboard button)

Behavior:

Starts timer for configured duration
Turns on circulation pump
Enables aux heater boost
Auto-disables everything when timer expires
Restores pump schedule

4. Normal Boost Mode

Aux heater supplements heat pump during any thermostat heating call.

Enable: Turn ON input_boolean.dhw_allow_aux_heater_in_all_modes

5. Manual Override

Direct control for testing or emergencies.

Enable: Turn ON input_boolean.dhw_aux_heater_manual_override

Warning: Bypasses all safety checks except physical relay. Use with caution.

Energy Tracking

The package includes sensors for monitoring heater usage:

Sensor	Purpose
`sensor.boiler_resistance_power`	Current power draw (0 or rated power)
`sensor.boiler_resistance_pv_power`	Power when running on PV excess
`sensor.boiler_resistance_grid_power`	Power when running on grid
`sensor.boiler_resistance_total_energy`	Cumulative total energy (kWh)
`sensor.boiler_resistance_pv_energy`	Cumulative PV energy (kWh)
`sensor.boiler_resistance_grid_energy`	Cumulative grid energy (kWh)

Runtime utility meters are provided with daily, weekly, and monthly cycles for both PV and grid usage.

Troubleshooting

Heater not turning on

Check binary_sensor.dhw_use_boiler_aux_heater state in Developer Tools
Verify input_boolean.dhw_allow_aux_heater_usage is ON
Check sensor.heat_pump_auxiliary_heater is not ON (interlock)
Verify sensor.boiler_temp is below cut-off threshold
Check automation trace in Automations panel

PV mode not activating

Check binary_sensor.dhw_pv_power_enough_for_aux_heater state
Verify all CT sensors show negative values (export)
Check if export exceeds (buffer + heater_power) / 3 per phase
Wait for start_delay seconds

Preset not applying

Verify input_select.dhw_boiler_preset has the expected value
Check that the corresponding input_number.dhw_boiler_temp_* entity exists and has a value
Check DHW Boiler Preset Manager automation trace

Heater cycling rapidly

Increase dhw_pv_excess_usage_stop_delay to ride through clouds
Increase dhw_pv_excess_usage_buffer for more margin
Check thermostat tolerance settings

Sensor unavailable errors

The templates include safe defaults:

Temperature sensors default to 100°C (heater stays OFF)
Power sensors default to 0W (no export detected)

File Structure

excess_pv_boiler/
├── use_excess_pv_in_boiler.yaml   # Main package file (install this)
├── CLAUDE.md                       # Development context for AI assistants
└── README.md                       # This file

README.md

Excess PV Boiler Auxiliary Heater Control