HomeAssistant_Integrations/HA_Aux_Heater
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
This repository has been archived on 2026-04-06. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
c8d1e968d753dee352afad12ac7e335815fee668
HA_Aux_Heater/excess_pv_boiler/CLAUDE.md
T

9.3 KiB
Raw Blame History

CLAUDE.md - Development Context for Excess PV Boiler Control

Project Purpose

This Home Assistant package controls an auxiliary electric heater installed in a DHW (Domestic Hot Water) boiler. It works alongside a heat pump to provide:

  • Preset-based temperature control with user-adjustable temperatures per preset
  • PV excess utilization to use surplus solar power instead of exporting
  • Bath boost with configurable timer for rapid hot water
  • Manual override for emergency/testing scenarios

Architecture

[Solar Inverter] --> sensor.deye_12_external_ct*_power (3-phase grid power)
                          |
              [binary_sensor.dhw_pv_power_enough_for_aux_heater]
                          |
              [automation: DHW Manage PV Thermostat]
                          |
              [climate.dhw_pv_excess_heating] (shadow thermostat)
                          |
              [binary_sensor.dhw_use_boiler_aux_heater] <-- [manual override]
                          |                              <-- [boost modes]
              [automation: DHW Boiler Heater Relay]
                          |
              [switch.boiler_heater_relay_switch_0] (physical relay)

[input_select.dhw_boiler_preset] --> [automation: DHW Boiler Preset Manager]
[input_number.dhw_boiler_temp_*]          |
                                          v
                                [climate.boiler_temperature] (main thermostat)

[script.dhw_start_bath_boost] --> [timer.bath_time] --> [automation: DHW Bath Time]
[input_number.dhw_bath_boost_duration]                       |
                                                             v
                                              [input_boolean.dhw_bath_boost] + [switch.acm_pump_switch]

Key Entities

Input Booleans (Modes/Toggles)

Entity Purpose
input_boolean.dhw_aux_heater_manual_override Force heater ON regardless of conditions
input_boolean.dhw_allow_aux_heater_usage Master enable for aux heater
input_boolean.dhw_use_excess_pv_for_aux_heater Enable PV excess mode
input_boolean.dhw_allow_aux_heater_in_all_modes Allow boost in normal thermostat mode
input_boolean.boiler_pv_dummy_heater Virtual switch for shadow thermostat
input_boolean.dhw_bath_boost Bath boost active flag (managed by automations)

Input Select (Presets)

Entity Purpose
input_select.dhw_boiler_preset Active boiler preset: Normal, Eco, Boost, Sleep, Away, Off

Timer

Entity Purpose
timer.bath_time Countdown timer for bath boost duration

Input Numbers (Thresholds)

Entity Purpose Range
input_number.dhw_aux_heater_cut_off_temperature_threshold Max temp before heater stops 50-85°C
input_number.dhw_aux_heater_temperature_threshold Hysteresis threshold 1-15°C
input_number.dhw_pv_target_temperature Target temp for PV heating 40-70°C
input_number.dhw_pv_excess_usage_buffer Buffer power before triggering 0-1000W
input_number.dhw_aux_heater_power Heater power rating 500-9000W
input_number.dhw_pv_excess_usage_start_delay Delay before starting PV mode 1-300s
input_number.dhw_pv_excess_usage_stop_delay Delay before stopping PV mode 1-300s

Input Numbers (Preset Temperatures)

Entity Purpose Range
input_number.dhw_boiler_temp_normal Normal preset target temperature 30-65°C
input_number.dhw_boiler_temp_eco Eco preset target temperature 30-60°C
input_number.dhw_boiler_temp_boost Boost preset target temperature 40-70°C
input_number.dhw_boiler_temp_sleep Sleep preset target temperature 25-55°C
input_number.dhw_boiler_temp_away Away preset target temperature 20-50°C
input_number.dhw_bath_boost_duration Duration for bath boost timer 5-120 min

Scripts

Entity Purpose
script.dhw_start_bath_boost Starts timer.bath_time with duration from dhw_bath_boost_duration

Climate (Generic Thermostats)

Entity Purpose
climate.dhw_pv_excess_heating Shadow thermostat for PV excess mode
climate.boiler_temperature Main boiler thermostat (target set by preset manager)

Automations

Entity Purpose
DHW Boiler Heater Relay Automation Switches physical relay based on decision sensor
DHW Manage PV Thermostat Controls shadow thermostat based on PV availability
DHW Boiler Preset Manager Syncs preset selection + temperatures to thermostat, toggles bath boost
DHW Bath Time Manages bath boost lifecycle: pump + boost on/off with timer

External Entities (Not Defined in Package)

These must exist in your HA instance from other integrations or manual UI setup:

Entity Source Purpose Fallback if Unavailable
sensor.boiler_temp Heat pump / temperature probe Boiler water temperature 100 (prevents running)
sensor.deye_12_external_ct1_power Deye inverter integration Phase 1 grid power (negative = export) 0
sensor.deye_12_external_ct2_power Deye inverter integration Phase 2 grid power 0
sensor.deye_12_external_ct3_power Deye inverter integration Phase 3 grid power 0
sensor.heat_pump_auxiliary_heater Heat pump integration HP aux heater state treated as 'off'
switch.boiler_heater_relay_switch_0 Relay device (Shelly, etc.) Physical heater control N/A
switch.acm_pump_switch Pump relay/smart plug DHW circulation pump N/A
switch.schedule_f403a3 Scheduler integration Pump schedule to restore after boost N/A

Decision Logic

binary_sensor.dhw_use_boiler_aux_heater

This is the main decision sensor. It turns ON when:

  1. Manual override is ON, OR
  2. All conditions met:
    • Heat pump aux heater is OFF
    • Boiler aux usage is allowed
    • Boiler temp is below cut-off threshold
    • AND one of:
      • PV excess mode active AND shadow thermostat is heating
      • Bath boost active AND main thermostat is heating
      • All-modes boost enabled AND main thermostat is heating

binary_sensor.dhw_pv_power_enough_for_aux_heater

Determines if there's enough solar export to run the heater:

  • When heater is OFF: All 3 phases must export > (buffer + heater_power) / 3
  • When heater is ON: All 3 phases must still be exporting (<=0W import)

Preset Manager Flow

  1. User selects preset from input_select.dhw_boiler_preset
  2. Automation reads corresponding input_number.dhw_boiler_temp_<preset> value
  3. Sets climate.boiler_temperature to that target + heat mode (or off for "Off" preset)
  4. Toggles input_boolean.dhw_bath_boost on/off based on whether Boost is selected
  5. If user changes a preset temperature input_number, automation re-applies current preset

Bath Boost Flow

  1. User calls script.dhw_start_bath_boost (e.g., from a dashboard button)
  2. Script starts timer.bath_time with duration from input_number.dhw_bath_boost_duration
  3. DHW Bath Time automation detects timer active: turns on pump + bath boost
  4. Timer finishes: automation restores pump schedule + turns off boost

Common Modifications

Changing Preset Temperatures

Adjust via dashboard sliders at runtime (no YAML edit needed). The input_number.dhw_boiler_temp_* entities store each preset's temperature.

Adding New Presets

  1. Add option to input_select.dhw_boiler_preset
  2. Add corresponding input_number.dhw_boiler_temp_<name> (name must be lowercase match)
  3. The preset manager automation uses dynamic entity resolution, so no automation changes needed

Changing Power Thresholds

Adjust via dashboard at runtime:

  • dhw_pv_excess_usage_buffer: Increase for more conservative PV triggering
  • dhw_aux_heater_power: Match to actual heater rating

Adjusting Timing

Adjust via dashboard at runtime:

  • dhw_pv_excess_usage_start_delay: Increase to avoid rapid cycling
  • dhw_pv_excess_usage_stop_delay: Increase to ride through clouds
  • dhw_bath_boost_duration: Duration of bath boost timer

Adding New Heating Modes

Edit template section, add new condition in binary_sensor.dhw_use_boiler_aux_heater alongside pv_excess, thermostat_activity_boost, etc.

Testing/Validation

  1. YAML Syntax: Run yamllint *.yaml or use HA's configuration check
  2. Entity References: Ensure all states() calls reference defined entities
  3. Default Fallbacks: Verify all float() filters have appropriate defaults:
    • Temperature sensors: float(100) (fail-safe: heater OFF)
    • Power sensors: float(0) (fail-safe: no export detected)
    • Input numbers: float(<sensible_default>)

File Structure

File Purpose
use_excess_pv_in_boiler.yaml Main package file - install this in HA packages directory
CLAUDE.md Development context for AI assistants
README.md User-facing documentation

Safety Considerations

  1. Never run both heaters: Template checks sensor.heat_pump_auxiliary_heater != 'on'
  2. Temperature cut-off: Hard limit prevents overheating
  3. Unavailable sensors: Default to safe values (temp=100, power=0)
  4. Manual override: Bypasses all checks - use with caution
  5. Bath boost timer: Auto-disables boost when timer expires
Reference in New Issue View Git Blame Copy Permalink