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
b5fbca8453a3c046fdc863c63f480d18d2426d3d
HA_Aux_Heater/excess_pv_boiler/README.md
T

258 lines
11 KiB
Markdown
Raw Blame History

# 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/)
Reference in New Issue View Git Blame Copy Permalink