A deterministic, fail-safe Smart Grid (SG-Ready) controller for heat pumps.

This project converts photovoltaic (PV) surplus into usable thermal energy using:
Home Assistant, ESPHome, Shelly relays, and a HomeWizard P1 meter
Fully local, vendor-neutral, and without proprietary cloud EMS systems.

Designed by a hands-on mechanical engineer with a focus on:

• Stability over aggression
• Electrical correctness
• Compressor protection
• Transparent logic
• Long-term reliability

Many modern heat pumps support SG-Ready, but lack intelligent surplus control unless paired with expensive vendor ecosystems.

This project provides:

✔ Export-only activation (never triggers on grid import)
✔ Smoothed power filtering to prevent compressor oscillation
✔ Deterministic state transitions
✔ Hardware and software watchdog protection
✔ Test mode for commissioning
✔ Fully local operation
✔ Vendor-neutral architecture

flowchart TD
    PG[Power grid]
    I[Inverter]
    SM[Smart Meter]
    P1[HomeWizard P1 Meter]
    HA[Home Assistant]
    ESP[ESP32 + ESPHome<br/>SG Pulse Meter]
    SH[Shelly Plus 1 Gen3<br/>SG Operation Mode]
    HP[SG-Ready Heat Pump]
    TS[Thermal Storage]

    I --> SM --> P1 --> HA
    PG <-->|Import / Export| SM
    HA --> ESP
    HA --> SH
    ESP --> HP
    SH --> HP
    HP --> TS

Follow this order to prevent configuration deadlocks:

1. Create required Home Assistant helpers (see /HomeAssistant/README.md)
2. Import all automation blueprints /HomeAssistant
3. Flash the ESPHome firmware from /ESPHome
4. Install the Shelly watchdog script /Shelly
5. Verify correct SG contact switching and pulse generation
6. Only then connect SG contacts to the heat pump
7. Monitor live export behavior after installation

⚠ Always validate correct relay switching and pulse generation before connecting to the heat pump.

SG-Ready uses two potential-free contacts.

⚠ Always verify the SG-Ready mapping in your heat pump manual.

This project implements each transition as a separate automation blueprint,
forming a deterministic finite state machine (FSM).

This project is intentionally conservative.

Free Running ↔ Recommended ON ↔ Forced ON

• No undefined transitions
• No direct jumps
• No ambiguous states

Escalation requires significantly more surplus than de-escalation requires import.

Prevents:

• Mode bouncing
• Compressor short cycling
• Instability during passing clouds

Each state requires minimum time-in-state before transition.

Protects:

• Compressor lifetime
• Relay contacts
• Thermal stability

Safe fallback state:

Free Running (SG1 = OFF, SG2 = OFF)

If:

• Home Assistant restarts
• Power data becomes unavailable
• Grid import persists
• Watchdog triggers

The system de-escalates automatically.

The heat pump will never remain forced due to automation failure.

No single device failure can lock the heat pump in Forced ON.

• HomeWizard P1 meter
• Raspberry Pi 3B running Home Assistant
• Raspberry Pi 3B case by Malolo (printables.com)

• ESP32 D1 mini running ESPHome
• Optocoupler module (PC817, connected via GPIO25 and GND to the ESP32) for dry-contact S0 output
• ESP32 D1 Mini with optocoupler module case by ShortyMF (printables.com)

• Shelly plus 1 Gen 3 controlling the SG-Ready contact 1
• Shelly plus 1 Gen 3 controlling the SG-Ready contact 2
• Shelly case by wolf3D (printables.com)

• Daikin Altherma 3 (EHVX08S23EJ9W + ERGA08EAV3H7) since start 2025

Expected to work with any SG-Ready heat pump that accepts dry-contact inputs.
Always verify manufacturer documentation.

This project switches dry-contacts only.

Always verify electrical compatibility with your heat pump before connecting.
If you are not comfortable working with electrical systems, consult a qualified professional.

Incorrect wiring may damage your heat pump or void warranty.
Use this project at your own risk.

Possible upgrades:

• Dynamic tariff optimization
• Direct EMS integration

This project is licensed under the GNU General Public License v3.0 (GPLv3).

Copyright (c) 2026 S.J.H. Hermans

You are free to:

• ✔ Use the software for private or commercial purposes
• ✔ Study and modify it
• ✔ Distribute original or modified versions

Under the following conditions:

• Proper attribution must be given
• Modified versions must remain licensed under GPLv3
• Source code must be made available when distributing changes

This ensures that improvements remain open and accessible to the community.

Full license text:
https://www.gnu.org/licenses/gpl-3.0.en.html

Contributions, field reports, and improvements are welcome.

If you deploy this system on another heat pump brand,
please open an issue or pull request.

By contributing, you agree that your work will be licensed under GPLv3.