An advanced Home Assistant automation blueprint that uses excess photovoltaic production to run a reversible air conditioner (air-to-air heat pump) for cooling and heating, and to store heat or coolness in the building while the sun is shining.
The blueprint was generalized from a real installation and contains no device IDs, serial numbers, addresses, credentials, or vendor-specific entity names.
- Starts cooling when indoor comfort requires it and grid export exceeds a configurable threshold.
- Lowers the cooling setpoint when more surplus is available and raises it when the home imports power, up to the current indoor temperature.
- Stops cooling after sustained import at the comfort ceiling.
- Coolness storage: below the normal stop temperature, keeps cooling (by a configurable margin) as long as the unit does not import from the grid.
- Pre-cooling: on a day forecast to be hot, starts earlier (optional remaining-solar condition from a PV forecast, with a correction factor).
- High-heat mode: above a threshold, comfort takes priority over grid power.
- Optional humidity comfort correction and outdoor-air (open the windows) rule.
- Starts heating when the room is below the target minus a hysteresis and both smoothed and instantaneous export exceed their thresholds.
- Setpoint based on the room sensor, not on the unit's internal sensor: start = indoor temperature rounded down + offset; modulation down to the indoor temperature rounded down (unit near minimum power) and up to a maximum setpoint while surplus remains.
- Stops at the target. Heat storage: continues up to target + bonus while the unit does not import, only if the coming night is forecast to be cold.
- Never buys grid power on purpose. Another heating system (boiler, floor heating) is expected to provide comfort without sun; heat stored during the day delays its demand in the evening.
- Optional daytime-only restriction.
- Minimum on/off times and a delay between setpoint changes.
- Optional instantaneous grid sensor for import safety (both readings must exceed the threshold).
- Occupancy, post-departure grace period, and an optional inhibit entity for another priority load (water heater, EV charger, battery...).
- Detects manual HVAC mode, setpoint, or preset changes and starts an override timer instead of fighting the user.
- Sets a configured fan mode only on automatic start.
This automation controls equipment that can draw significant power. Test it while present, start with conservative thresholds, and keep the manufacturer's own temperature, electrical, and compressor protections enabled. Home Assistant must not be the only protection against overload or unsafe temperatures.
- a
climateentity supporting cooling (and heating if used); - an indoor temperature sensor, placed away from the indoor unit;
- a grid power sensor (a 2–5 minute filtered value is recommended);
- an occupancy binary sensor;
- the four helpers shown in
examples/helpers.yaml.
Optional: instantaneous grid sensor, humidity, outdoor temperature, inhibit
entity, today's maximum and tonight's minimum forecast
(examples/forecast_helpers.yaml), remaining solar production forecast.
Companion projects, both optional:
- Bbox Presence can provide the occupancy entity, but the blueprint works with any binary sensor;
- AROME Solar Forecast provides a free remaining-production forecast for pre-cooling (France and neighbouring areas), but any forecast sensor in kWh works.
Import the blueprint in one click, from a browser where your Home Assistant is open:
Then continue at step 3. Or by hand:
- Copy
blueprints/automation/solar_surplus_climate_control.yamltoconfig/blueprints/automation/<your_name>/solar_surplus_climate_control.yaml. - Reload automations or restart Home Assistant.
- Create the four helpers from
examples/helpers.yaml, either as a package or through the Home Assistant helper UI. - Optional: add
examples/forecast_helpers.yamlfor pre-cooling and night-conditioned heat storage. - Open Settings → Automations & scenes → Blueprints.
- Create an automation from Solar surplus climate control and select your entities. Heating is disabled by default.
- Turn on the automatic-control helper only after checking the power sign, unit, thresholds, setpoints, and climate fan-mode spelling.
Users can also import the blueprint from its GitHub URL through the Home Assistant blueprint UI:
https://github.com/MariusTechLab/solar-surplus-climate-control/blob/main/blueprints/automation/solar_surplus_climate_control.yaml
Upgrading from v1: re-import the blueprint. Existing automations keep working; cooling storage and pre-cooling use their defaults (storage 1 °C; pre-cooling only acts when a forecast entity is selected). Set the storage margin to 0 to keep the v1 behaviour.
Internally, the blueprint normalizes power so that:
- positive values mean grid import;
- negative values mean grid export.
Select the actual sign convention and unit of your sensor in the blueprint form. Threshold fields are always entered in watts, even when the sensor reports kilowatts.
| Cooling | Heating | |
|---|---|---|
| Temperature used | indoor + humidity correction | indoor sensor only |
| Start | comfort ≥ start (start − advance on a hot day) and smoothed export ≥ threshold | indoor ≤ target − hysteresis, smoothed and instantaneous export ≥ thresholds, daytime |
| Start setpoint | unit internal temperature − step | indoor rounded down + offset |
| More surplus | setpoint down (not below minimum) | setpoint up (not above maximum) |
| Import | setpoint up (to indoor rounded down), then stop after minimum on | setpoint down (to indoor rounded down), then stop after minimum on |
| Normal stop | comfort ≤ start − hysteresis | indoor ≥ target |
| Storage | down to stop − margin while not importing | up to target + bonus while not importing, if a cold night is forecast |
| Immediate stops | — | safety import, grid sensor lost, invalid settings |
Heating settings are only accepted if target + storage stays below the cooling stop temperature, so heating and cooling cannot chase each other.
| Failure | Heating | Cooling |
|---|---|---|
| Air conditioner unreachable | no command possible | no command possible |
| Indoor sensor | stopped, no start | stopped, no start (including high heat) |
| Grid sensor | stopped immediately | solar stopped after minimum on time; high heat still possible |
| Outdoor sensor | — | outdoor-air rule ignored (use the fallback in the example) |
| Daily maximum forecast | — | pre-cooling disabled (reset to 0 every night) |
| Night minimum forecast | storage allowed (surplus only) | — |
| Remaining solar forecast | — | condition ignored |
examples/degraded_mode_notification.yaml raises a persistent notification
listing current failures (and a phone notification for the important ones).
If the air conditioner becomes unreachable after a power or network outage,
check whether its IP address changed; a DHCP reservation prevents this.
These observations shaped v2; check them on your own equipment.
- The indoor unit's own temperature reading is biased in heating mode: it read 3–5 °C above a room sensor while heating (warm air near the ceiling), yet the unit regulated close to the real room temperature. Setpoints derived from the internal reading were far too low or too high; setpoints based on the room sensor work. Rounded-down room temperature ≈ minimum power.
- An outdoor unit in direct sun reads too warm: about +0.5 °C at night and
up to +4 °C in full sun versus a weather model. A linear correction with PV
power as a sun proxy cut the mean error from 1.9 °C to 1.25 °C
(
examples/sun_corrected_outdoor_temperature.yaml). - PV forecasts can be optimistic: one forecast ran about 30 % high over ten days while ranking sunny and cloudy days correctly. Use the correction factor.
- Coarse power readings: some integrations report power in 100 W steps,
show 100 W while off, or stay at 0 while running. Estimate power from the
compressor frequency instead (
examples/compressor_power_estimate.yaml). - A three-sample "3 minute" average reacts fast: a cycling 2 kW cooking load can flip it from import to export within two minutes. Prefer a longer window for start decisions if you see false starts.
- Most surplus is exported between 10:00 and 16:00; heat or coolness stored then is the cheapest flexible load for a building without a battery.
examples/dashboard_temperature_gauge.yaml draws an indoor-temperature gauge
with graduations, the value with its unit, and colour zones that follow the
heating and cooling thresholds (requires the HACS config-template-card).
- Confirm grid power unit and sign.
- Set safe minimum, maximum and high-heat setpoints for the climate device.
- Set minimum on/off times according to the manufacturer.
- Choose conservative export-to-start thresholds.
- Tune the export target and deadband after observing several sunny cycles.
- Enable heating, storage and forecasts once basic cycles behave well.
- Enable optional humidity, outdoor temperature, and inhibit inputs last.
The GitHub workflow parses the YAML, checks that every !input is declared and
used, rejects installation-specific tokens (private addresses, MAC addresses,
e-mails, coordinates, long serial numbers), and runs scenario tests of the
decision logic (scripts/test_blueprint_logic.py) with a mock of the Home
Assistant template helpers.
- 2.0.0 – optional solar heating with room-based setpoints and night-conditioned heat storage; coolness storage; forecast-based pre-cooling; degraded-mode documentation and examples (forecasts, sun-corrected outdoor temperature, compressor power estimate, notifications, dashboard gauge); scenario tests and privacy checks.
- 1.0.0 – initial public release (solar cooling).
MIT