Home Assistant is the primary, actively maintained way to use this project. This repository ships a HACS custom integration that talks directly to Luxtronik 2.0 heat pump controllers and exposes them as Home Assistant entities. A separate legacy Modbus TCP proxy exists as an unmaintained byproduct for users who specifically need raw Modbus access.
If you own a Luxtronik 2.0 heat pump from Alpha Innotec, Novelan, Buderus, Nibe, Roth, Elco, or Wolf, install the HACS integration below — it is the supported path.
Deutsche Version → README.de.md
This project supports three integration paths with clearly different maturity levels. Pick the one that matches your setup.
This is the primary use case and the only actively maintained path.
- Install as a HACS Custom Repository pointing at
https://github.com/notDIRK/luxtronik2-hass - Config flow UI — enter your heat pump's IP address, no YAML
- 31+ entities exposed: temperatures, operating modes, power, status, setpoints, SG-Ready, heat quantity meters
- Works with Home Assistant 2024.1+ (tested on 2026.4.x)
- Python 3.12+ runtime (matches HA Core)
- Talks directly to the heat pump via the
luxtroniklibrary — no extra services, no Modbus layer
Installation:
- In Home Assistant → HACS → Integrations → ⋮ menu → Custom repositories
- Add
https://github.com/notDIRK/luxtronik2-hasswith category Integration - Install Luxtronik 2.0 (Home Assistant)
- Restart Home Assistant
- Settings → Devices & Services → Add Integration → search for Luxtronik 2.0
- Enter the IP address of your heat pump controller
Unmaintained legacy byproduct. This existed as a standalone proxy before the HACS integration. It is no longer actively maintained and lives in a separate archived repository.
Use this path only if you specifically need raw Modbus TCP access — for example to integrate with evcc or another Modbus-only tool that cannot call Home Assistant.
- Repository: notDIRK/luxtronik2-modbus-proxy (archived, read-only)
- Status:
⚠️ Experimental — no bug fixes, no new features, no support - Technology: Python proxy translating Luxtronik binary protocol (port 8889) → Modbus TCP (port 502)
If you are currently running this proxy together with the HACS integration, consider migrating fully to Path 1 — the integration covers every entity the proxy exposed and removes the single-connection bottleneck.
A first-class Home Assistant Add-on (for HA OS and Supervised installations) is planned for v1.3. It will package the integration as a supervisor add-on so users on HA OS can install it without HACS.
This path is not yet available. Track progress in the repository milestones.
- Read-only sensors: flow/return temperatures, outside temperature, hot water temperature, operating hours, heat quantity meters (heating, hot water, total kWh), power consumption, error states, SG-Ready status
- Control entities: heating mode, hot water mode, SG-Ready mode, temperature setpoints
- Bath Boost (Badebooster): on-demand hot water heating with progress tracking — details below
- Smart Energy: Solar Boost + Night Heating Pause — details below
- Write rate limiting to protect the controller from command floods
- Single-connection safe: respects the Luxtronik 2.0 one-TCP-connection constraint via connect-per-call + asyncio lock
- English + German translations built in
- Stable entity IDs: entities use the device-name prefix
luxtronik_2_0_*— they do not change if you rename the integration
A ready-to-use dashboard YAML is included in this repository. To set it up:
- In Home Assistant, go to Settings → Dashboards → Add Dashboard
- Choose a name (e.g. "Waermepumpe") and an icon (
mdi:heat-pump) - Open the new dashboard → click ⋮ (top right) → Edit Dashboard → ⋮ → Raw configuration editor
- Replace the entire content with the YAML from
docs/examples/dashboard-waermepumpe.yaml - Replace
your-heatpump-ipin line 11 with your actual heat pump IP address - Click Save, then Done
The dashboard shows operating status, temperatures, pump states, operating hours, setpoints, Smart Energy controls, and a 24-hour grid history graph — all using the stable luxtronik_2_0_* entity IDs.
Two dashboard languages are available:
| Language | File | Description |
|---|---|---|
| English | dashboard-heatpump-en.yaml | All labels and descriptions in English |
| Deutsch | dashboard-waermepumpe.yaml | Alle Beschriftungen auf Deutsch |
| Bath Boost | dashboard-bath-boost.yaml | Standalone card with progress display (add to any dashboard) |
Pick the one matching your Home Assistant language setting.
One button for a hot bath. Press the Bath Boost button and the heat pump immediately starts heating your hot water tank to a higher target temperature. Once reached, everything returns to normal automatically.
Quick start:
- Find the Badebooster button on your device page (Devices & Services > Luxtronik 2.0 > device)
- Press it — done. The heat pump starts heating immediately.
- Watch progress in the Badebooster Status sensor
How it works:
| Step | What happens |
|---|---|
| You press the button | Hot water mode switches to "Party" (forces immediate heating) and setpoint is raised to target temperature |
| Heating in progress | Status sensor shows "Active" with current temperature, progress %, and estimated remaining time |
| Target reached | Mode automatically returns to "Automatic", setpoint restored to normal |
Default temperatures:
| Setting | Default | Range | Where to change |
|---|---|---|---|
| Target temperature | 65.0 °C | 40–70 °C | Settings > Luxtronik 2.0 > Configure > Bath Boost |
| Normal temperature | 55.5 °C | 30–65 °C | Settings > Luxtronik 2.0 > Configure > Bath Boost |
Entities created:
| Entity | Type | Description |
|---|---|---|
button.luxtronik_2_0_badebooster |
Button | Press to start heating |
sensor.luxtronik_2_0_badebooster_status |
Sensor | Shows "Active" or "Idle" with progress attributes |
The status sensor provides these attributes while active: current_temperature, target_temperature, progress_percent, estimated_remaining_minutes, activated_at.
Dashboard card: A ready-to-use dashboard card is included at docs/examples/dashboard-bath-boost.yaml. See the Dashboard Setup section for how to add cards.
Note: Bath Boost takes priority over Solar Boost. If Solar Boost is active when you press Bath Boost, your manual request wins.
Two optional automation features for heat pumps with multi-layer buffer tanks and DHW (domestic hot water) heat exchangers. Both can be enabled independently via Settings → Devices & Services → Luxtronik 2.0 → Configure.
Automatically raises the hot water setpoint when your solar system feeds surplus power into the grid — storing free solar energy in the buffer tank instead of exporting it.
- Trigger: Grid feed-in exceeds a configurable threshold (default: 1500 W)
- Action: Hot water setpoint raised from normal (default: 55.5 °C) to boost temperature (default: 65.0 °C)
- Minimum runtime: Once activated, boost stays active for a configurable duration (default: 30 min) to prevent rapid cycling during cloud cover
- Grid sensor convention: Positive values = consumption (buying), negative values = feed-in (selling). Example:
sensor.grid_total = -2000means 2000 W feed-in - Spike protection: A 60-second debounce prevents false triggers from short grid spikes (e.g. when the compressor stops and briefly causes feed-in overshoot)
Your Luxtronik controller has a WW hysteresis setting (typically 5 K) that affects when hot water heating actually starts. The controller only begins heating when the tank temperature drops below the setpoint by the hysteresis amount.
Example: With a setpoint of 55.5 °C and 5 K hysteresis, the controller will not start heating until the temperature drops to 50.5 °C (55.5 - 5.0 = 50.5).
This matters for Solar Boost because:
- Solar Boost raises the setpoint (e.g. to 65 °C), but the heat pump will not actually start heating until the tank drops to 60 °C (with 5 K hysteresis)
- If your tank is already at 58 °C, Solar Boost will raise the setpoint but no heating occurs — the surplus solar energy is still exported to the grid
Automatic: The integration reads the WW hysteresis value directly from the controller (parameter 74, ID_Einst_BWS_Hyst_akt) — no manual configuration needed. The sensor sensor.luxtronik_2_0_luxtronik_ww_hysteresis updates every poll cycle (default: 30s). The dashboard calculates and displays the effective start temperature automatically.
Dashboard visualization:
| Symbol | Meaning |
|---|---|
| 🔌 Netzbezug: 1078 W | Consuming from grid (positive value) |
| ☀️ Einspeisung: 2000 W | Feeding into grid (negative value) |
| 🟢 Boost condition met | Feed-in > threshold |
| 🟡 Below threshold | Feed-in present but below threshold |
| 🔴 No solar surplus | Consuming from grid |
Automatically disables floor heating during night hours to prevent the heating circuit from cooling down the buffer tank overnight. This preserves hot water for the morning — critical for systems where the floor heating and DHW share the same buffer.
- Default window: 18:00 – 09:00 (configurable)
- Action: Heating mode set to "Off" during the window, restored to "Automatic" outside
- Why: In a multi-layer buffer tank with DHW heat exchanger, the floor heating loop can drain heat from the buffer overnight, leaving no hot water in the morning
All features are configured in the integration's options flow:
- Settings → Devices & Services → Luxtronik 2.0 → Configure
- Select Solar Boost, Night Heating Pause, or Bath Boost from the menu
- Enable the feature and adjust thresholds/temperatures/times
- The dashboard shows toggle switches, grid status, and a 24-hour history graph
Smart Energy switches can also be toggled at runtime via the switch entities (switch.luxtronik_2_0_solar_boost, switch.luxtronik_2_0_night_heating_pause).
Runtime status attributes: The switches expose live runtime information as state attributes:
| Switch | Attribute | Example | Description |
|---|---|---|---|
| Solar Boost | boost_active |
true |
Whether the boost is currently raising the setpoint |
| Solar Boost | boost_activated_at |
2026-04-13T09:19:06 |
When the system last activated the boost |
| Solar Boost | boost_running_since |
2h 15min |
How long the current boost has been active |
| Night Pause | pause_active |
true |
Whether floor heating is currently paused |
| Night Pause | pause_window |
18:00 – 09:00 |
The configured pause time window |
The integration reads the Luxtronik heat quantity meters (Waermemengenzaehler) directly from the controller. These sensors are enabled by default and show the total thermal energy delivered since commissioning.
| Sensor | Luxtronik Index | Description |
|---|---|---|
sensor.luxtronik_2_0_luxtronik_heat_quantity_heating |
calc 151 (ID_WEB_WMZ_Heizung) | Thermal energy delivered for space heating (kWh) |
sensor.luxtronik_2_0_luxtronik_heat_quantity_hot_water |
calc 152 (ID_WEB_WMZ_Brauchwasser) | Thermal energy delivered for hot water (kWh) |
sensor.luxtronik_2_0_luxtronik_heat_quantity_total |
calc 154 (ID_WEB_WMZ_Seit) | Total thermal energy since commissioning (kWh) |
These values use the ENERGY device class with TOTAL_INCREASING state class, making them compatible with the HA Energy Dashboard for long-term tracking.
The dashboard includes a dedicated card showing all three meters.
- Home Assistant 2024.1 or newer
- A Luxtronik 2.0 heat pump controller reachable on your LAN
- The heat pump's IP address
Any heat pump with a Luxtronik 2.0 controller, including models from:
- Alpha Innotec
- Novelan
- Buderus (selected models)
- Nibe (selected models)
- Roth
- Elco
- Wolf
If your unit predates Luxtronik 2.1 and has no firmware upgrade path, this integration is for you.
If you previously used the old luxtronik2_modbus_proxy HACS integration (v1.1), see MIGRATION.md for the step-by-step upgrade path. Your user-visible entity IDs stay stable across the upgrade because they derive from the device-name slug, not the integration domain.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
MIT — matching the luxtronik library ecosystem.
luxtroniklibrary by Bouni — the binary protocol client this integration depends on- The Home Assistant community