HomeAssistant_Integrations/ha_boiler_aux_heater_3phase
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
934d7353a6e0a61a021aca3fb3bc3b95fc17e70d
ha_boiler_aux_heater_3phase/CLAUDE.md
T
Constantin Pascal 73d5b8aeca Initial push
2026-02-26 09:58:44 +02:00

13 KiB
Raw Blame History

CLAUDE.md - Boiler Auxiliary Heater Custom Integration

Purpose

Home Assistant custom integration (boiler_aux_heater_3phase) that manages an auxiliary electric heater mounted inside a DHW (Domestic Hot Water) boiler. The boiler's primary heat source is a heat pump; this integration controls a secondary resistive heater for:

  • PV excess utilization - diverts surplus solar export to the heater instead of feeding back to the grid
  • Boost heating - rapid hot water via bath boost timer with optional circulation pump control
  • Preset-based temperature control - Normal, Eco, Boost, Sleep, Away presets with adjustable target temperatures
  • All-modes boost - allow the aux heater to run whenever the thermostat demands heat (not just PV/bath boost)
  • Manual override - force heater ON for testing/emergency

Architecture Overview

The integration follows a coordinator pattern. BoilerAuxHeaterCoordinator is the central brain that:

  1. Listens to external entity state changes (boiler temp, grid power, relay state, heat pump aux heater)
  2. Reads internal entity states (switches, numbers) via direct references
  3. Runs decision logic to determine whether the heater relay should be ON or OFF
  4. Controls the physical relay via switch.turn_on/switch.turn_off service calls

All entities register themselves with the coordinator on async_added_to_hass and receive updates via a listener callback pattern (not HA's DataUpdateCoordinator).

External sensors (boiler temp, CT power x1-3, HP aux heater, relay state)
    |
    v  (async_track_state_change_event + debounce)
BoilerAuxHeaterCoordinator._recalculate()
    |
    +-- reads switch states (manual_override, allow_usage, pv_excess_mode, boost_all_modes)
    +-- reads number values (cut_off_temp, heater_power, pv_buffer, pv_target_temp, etc.)
    +-- runs PV state machine (idle -> waiting_start -> active -> waiting_stop)
    +-- computes main thermostat heating (hysteresis against climate target temp)
    +-- computes all-modes heating demand (separate larger hysteresis + recovery offset)
    +-- computes final decision = manual_override OR (safety_ok AND (pv_heating OR bath_boost OR all_modes_boost))
    |
    v
Controls physical relay + notifies all entity listeners to update HA state

File Structure

File Purpose
__init__.py Entry setup/unload, service registration (start_bath_boost, stop_bath_boost), options update listener
const.py All constants: domain, config keys, presets, number/switch definitions, tolerances
coordinator.py BoilerAuxHeaterCoordinator - central logic, PV state machine, bath boost timer, relay control
config_flow.py 3-step config flow (core hardware, solar sensors, optional devices) + options flow
climate.py BoilerAuxHeaterClimate - climate entity with presets, reads boiler temp from external sensor
binary_sensor.py 5 binary sensors: decision, pv_sufficient, running_on_pv, running_on_grid, bath_boost_active
sensor.py Power sensors (total/pv/grid), energy sensors (Riemann sum), bath boost remaining timer, decision_reason, pv_state
switch.py 4 config switches: manual_override, allow_usage, pv_excess_mode, boost_all_modes
number.py 15 configurable number entities (temperatures, thresholds, delays, power rating, etc.)
button.py Bath boost start + cancel buttons (only created if circulation pump is configured)
services.yaml Service definitions for start_bath_boost and stop_bath_boost
strings.json UI strings for config flow and entity names
translations/en.json English translations (mirrors strings.json + entity translations)
manifest.json Integration manifest: domain=boiler_aux_heater_3phase, version=1.0.0, iot_class=local_push
dashboard.yaml Ready-to-import Lovelace dashboard for monitoring and control

Key Classes

BoilerAuxHeaterCoordinator (coordinator.py)

Central state manager. Not a subclass of HA's DataUpdateCoordinator - uses a custom listener pattern instead.

State tracked:

  • pv_state - PV state machine: idle / waiting_to_start / active / waiting_to_stop
  • bath_boost_active - whether bath boost is running
  • decision - final ON/OFF decision for the relay
  • decision_reason - human-readable string explaining the current decision
  • pv_sufficient - whether PV export exceeds heater power needs
  • relay_is_on - current physical relay state (read from external entity)
  • pv_shadow_heating - whether PV shadow thermostat logic wants heating

Entity registration: Internal entities call register_number(key, entity), register_switch(key, entity), register_climate(entity) during setup. The coordinator reads their values directly via get_number_value(key) and get_switch_state(key).

External state listening: Tracks state changes on configured external entities (boiler temp sensor, 1-3x CT power sensors, heater relay, optionally HP aux heater). Changes are debounced (1s) before triggering _recalculate().

PV State Machine:

  • idle -> waiting_to_start when PV is sufficient (starts delay timer)
  • waiting_to_start -> active when start delay elapses and PV still sufficient
  • waiting_to_start -> idle if PV drops before delay
  • active -> waiting_to_stop when PV drops (starts stop delay timer)
  • waiting_to_stop -> active if PV recovers before stop delay
  • waiting_to_stop -> idle when stop delay elapses

Bath Boost Flow:

  1. async_start_bath_boost() stores pre-boost preset, turns on circulation pump, sets climate to Boost preset, starts countdown timer
  2. async_stop_bath_boost() can be called manually (cancel button / service) to end early
  3. _bath_boost_finished() callback fires when timer expires - turns off boost, restores pump schedule, restores previous preset, fires HA event

Boost State Persistence: Bath boost state (active, end_time, pre_boost_preset) is persisted to HA storage so it survives HA restarts.

BoilerAuxHeaterClimate (climate.py)

Single climate entity with:

  • HVAC modes: heat, off
  • Presets: Normal, Eco, Boost, Sleep, Away
  • Uses RestoreEntity to persist state across restarts
  • current_temperature reads from external boiler temp sensor
  • hvac_action reports HEATING when relay is on, IDLE when off
  • Setting a preset reads the target temp from the corresponding number entity
  • Setting Boost preset activates bath_boost_active on coordinator; any other preset deactivates it (calls async_stop_bath_boost)

Energy Sensors (sensor.py)

BoilerEnergySensor uses internal Riemann sum integration (not HA's integration platform). It accumulates energy by multiplying the heater power rating by elapsed time on each coordinator update. Uses RestoreEntity + SensorStateClass.TOTAL_INCREASING for long-term tracking. Tracks total, PV-only, and grid-only energy separately.

A periodic 60-second energy tick (async_track_time_interval) notifies listeners to accumulate energy during steady state when no external events fire.

PvTargetTempNumber (number.py)

Special subclass of BoilerAuxHeaterNumber whose native_max_value is dynamically capped at cut_off_temp - 1, preventing the PV target from exceeding the safety cut-off.

Decision Logic (coordinator.py:_recalculate)

The heater relay is turned ON when (evaluated in priority order):

1. manual_override                                          → ON (bypasses everything)
2. NOT allow_usage                                          → OFF
3. hp_aux_heater sensor unavailable                        → OFF (safety)
4. hp_aux_on                                               → OFF (interlock)
5. boiler_temp >= cut_off_temp                             → OFF (safety)
6. hvac_mode == "off"                                      → OFF
7. pv_excess_mode AND pv_shadow_heating                    → ON (PV excess)
8. bath_boost_active AND main_thermostat_heating            → ON (bath boost)
9. boost_all_modes AND all_modes_heating_demand             → ON (all-modes boost)
10. otherwise                                              → OFF

Safety defaults for unavailable sensors:

  • Boiler temperature: defaults to 100.0 (heater stays OFF - above any cut-off)
  • CT power sensors: default to 0.0 (no export detected - PV won't trigger)
  • HP aux heater: treated as ON (heater disabled) if unavailable - SAFETY interlock

PV sufficient calculation (supports 1 or 3 phases):

  • When relay is OFF: each active CT phase must export more than (buffer + heater_power) / phase_count
  • When relay is ON (hysteresis): each active phase must still be exporting (value <= 0)

Main thermostat heating (hysteresis):

  • Turns ON when boiler_temp < target - temp_hysteresis
  • Turns OFF when boiler_temp >= target + MAIN_HOT_TOLERANCE (0.0)

All-modes heating demand (separate, larger hysteresis):

  • Turns ON when boiler_temp < target - boost_all_modes_hysteresis
  • Turns OFF when boiler_temp >= target - boost_recovery_offset

Config Flow (config_flow.py)

3-step wizard:

  1. Core Hardware: boiler temp sensor (temperature device class) + heater relay switch
  2. Solar Monitoring: phase count (1 or 3) + CT power sensors (power device class) for grid monitoring
  3. Optional Devices: HP aux heater sensor (interlock), circulation pump switch (enables bath boost), pump schedule entity

Uses async_set_unique_id(DOMAIN) + _abort_if_unique_id_configured() - only one instance allowed.

Options flow allows reconfiguring all entity references post-setup.

Configurable Parameters (number entities, defined in const.py)

Key Default Range Purpose
cut_off_temp 60 40-85 °C Hard safety limit - heater stops above this
temp_hysteresis 4 1-15 °C Hysteresis for main thermostat and PV shadow thermostat
pv_target_temp 55 40-70 °C Target temp for PV shadow thermostat (max capped at cut_off - 1)
pv_buffer 100 0-1000 W Extra export required before PV triggers
heater_power 4500 1500-9000 W Heater wattage (used for PV threshold + energy calc)
pv_start_delay 60 1-300 s Delay before activating PV mode
pv_stop_delay 60 1-300 s Delay before deactivating PV mode
temp_normal 44 30-65 °C Normal preset target
temp_eco 40 30-60 °C Eco preset target
temp_boost 50 40-70 °C Boost preset target
temp_sleep 38 25-55 °C Sleep preset target
temp_away 35 20-50 °C Away preset target
bath_boost_duration 30 5-120 min How long bath boost runs
boost_all_modes_hysteresis 10 3-20 °C How far below target before all-modes boost activates
boost_recovery_offset 3 0-15 °C How close to target before all-modes boost deactivates

Mode Switches (switch entities, defined in const.py)

Key Default Purpose
manual_override OFF Bypass all logic, force relay ON
allow_usage ON Master enable for aux heater
pv_excess_mode ON Enable PV excess diversion
boost_all_modes OFF Allow main thermostat to trigger relay outside PV/bath boost modes

Known Issues / Design Notes

  1. Custom coordinator pattern - Does not extend homeassistant.helpers.update_coordinator.DataUpdateCoordinator. Uses its own listener list and manual _notify_listeners(). This means no built-in polling fallback.

  2. Energy sensors use time.monotonic() - Energy integration accuracy depends on how frequently _recalculate fires (debounced to 1s on external state changes) plus the 60s periodic tick. Long periods without either would not accumulate energy.

  3. Single instance only - Config flow enforces one instance via unique_id. Multiple boiler setups would need code changes.

  4. 3-phase assumption for full accuracy - PV calculation with 3 phases requires all 3 phases to independently meet the threshold. Single-phase mode supported (only CT1 used).

  5. Bath boost button conditional - button.py only creates the bath boost buttons if circulation_pump is configured. The start_bath_boost/stop_bath_boost services are always registered regardless.

  6. Relay control via service calls - The coordinator calls switch.turn_on/turn_off services to control the relay rather than directly setting state. Failure is caught and logged but doesn't retry.

  7. _enable_turn_on_off_backwards_compat = False in climate - opts out of HA 2024.x backwards compatibility for turn_on/turn_off.

  8. No async_setup (YAML config) - Integration only supports config entries (UI setup), not YAML configuration.

Patterns Used

  • RestoreEntity on climate, switch, number, and energy sensors for state persistence across restarts
  • Persistent storage (homeassistant.helpers.storage.Store) for bath boost state across restarts
  • Entity registration with coordinator via register_*() methods during async_added_to_hass
  • Data-driven entity creation from NUMBER_DEFINITIONS, SWITCH_DEFINITIONS, BINARY_SENSOR_DEFINITIONS dicts
  • Debounced state change handling with async_call_later (1s debounce)
  • Translation keys (_attr_translation_key) for all entities with translations in translations/en.json
  • DeviceInfo with shared identifiers groups all entities under one device in HA
Reference in New Issue View Git Blame Copy Permalink