# 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`:
   ```yaml
   homeassistant:
     packages: !include_dir_named packages
   ```
3. Ensure all external entities exist (see [External Dependencies](#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](https://www.home-assistant.io/integrations/generic_thermostat/)
- [Home Assistant Packages](https://www.home-assistant.io/docs/configuration/packages/)
- [Home Assistant Automations](https://www.home-assistant.io/docs/automation/)
- [Home Assistant Scripts](https://www.home-assistant.io/integrations/script/)
- [Home Assistant Timer](https://www.home-assistant.io/integrations/timer/)
- [Input Select](https://www.home-assistant.io/integrations/input_select/)
- [Input Number](https://www.home-assistant.io/integrations/input_number/)