HA_Aux_Heater/excess_pv_boiler/README.md

Excess PV Boiler Auxiliary Heater Control

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

1. Copy use_excess_pv_in_boiler.yaml to your Home Assistant packages directory
2. Enable packages in configuration.yaml:

   homeassistant:
     packages: !include_dir_named packages
   

3. Ensure all external entities exist (see External Dependencies)
4. Restart Home Assistant
5. 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

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

PV mode not activating

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

Preset not applying

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

Heater cycling rapidly

1. Increase dhw_pv_excess_usage_stop_delay to ride through clouds
2. Increase dhw_pv_excess_usage_buffer for more margin
3. 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

Related Documentation

• Home Assistant Generic Thermostat
• Home Assistant Packages
• Home Assistant Automations
• Home Assistant Scripts
• Home Assistant Timer
• Input Select
• Input Number