Python Plugin: Luxtronik Heat Pump Controller Plugin

[Ragdag]

Luxtronik Heat Pump Controller plugin for Domoticz connects Luxtronik 2.0/2.1 based heat pump controllers (Alpha Innotec, Siemens Novelan, Roth, Elco, Buderus, Nibe, Wolf Heiztechnik and others) to Domoticz, for monitoring and control of your heating system.

Documentation (installation, settings, all devices, troubleshooting) | GitHub repository (releases and issues)

The repository was renamed from luxtronik-domoticz-plugin-v2 to luxtronik-domoticz-plugin. Old links and existing git clones keep working through GitHub's redirect, but please use the new address.

This plugin is a rewrite of my original Luxtronik plugin on the DomoticzEx framework. The original had a 256-device limit, device IDs that could change and leave orphaned devices, COP values logged while idle that skewed the statistics, and no support for more than one heat pump. This version fixes all of these.

Features

• Stable device IDs: tied to the Domoticz hardware entry, so they survive restarts, IP changes, folder changes and upgrades
• COP tracking: separate COP for heating, DHW and combined, only reported during steady-state operation
• Pump power compensation: the controller only measures compressor power. Pick your WZSV model (62, 92, 122, 162) or enter your own pump values, and the plugin adds the estimated circulation and brine pump power for a true system COP
• Gated sensors: pressure, superheat, ΔT and the refrigerant diagnostics only update while the compressor runs, keeping your statistics clean
• Refrigerant diagnostics: condensing temperature, refrigerant lift, condensing-supply ΔT, discharge headroom and compression ratio
• Your device names are kept: a device you renamed is never renamed back, also not when you change the plugin language
• Update check: once a day the plugin checks GitHub and announces a new release once, in the log and through your Domoticz notification systems. It sends nothing about you or your heat pump, never installs anything, and can be limited to stable releases or turned off
• Multi-instance: one hardware entry per heat pump
• Write protection: every write is checked against an explicit allowlist of safe addresses
• Languages: English, Polish, Dutch, German and French; by default device names follow the Domoticz interface language

Requirements

• Domoticz 2026.1 or newer (the settings page uses named plugin settings)
• Python 3.11 or newer
• A Luxtronik-based controller reachable on your network (port 8889 by default)

Still on an older Domoticz? Stay on version 2.2.0 until you upgrade Domoticz.

Installation
Pick one; all of them install into plugins/luxtronikex. Keep only one copy of the plugin, because Domoticz loads every plugins/*/plugin.py it finds.

Release zip (no git needed): download luxtronikex-vX.Y.Z.zip from the Releases page of the repository and extract it into your plugins folder.

Git, with easy updates:

Code: Select all

cd /path/to/domoticz/plugins
git clone -b dist https://github.com/Rouzax/luxtronik-domoticz-plugin.git luxtronikex
# update later with: cd luxtronikex && git pull

Plugin manager: the plugin is listed in PyPluginStore and pp-manager as luxtronikex.

Then restart Domoticz, go to Setup → Hardware, add Luxtronik Heat Pump Controller v2 and enter the IP address of your heat pump. The other settings work as they are; if you have a WZSV, set Pump power compensation to your model.

Upgrading from 2.2.x or older
Version 3.0.0 moved the settings to new fields. Your previous values stay in use until you next save the hardware page, but that page shows the defaults. Choose your values again before pressing Update; the plugin lists your old values in the log at every start until you do. IP address and port are not affected. Devices and history are kept.

Devices
The plugin creates 68 devices in 14 groups. Some are created as unused; enable them in Domoticz if you want them.

Code: Select all

Group              | Units     | Description
-------------------|-----------|---------------------------------------------
Status             | 1         | Working mode (Heating/DHW/Cooling/Idle)
Controls           | 10-16     | Heating mode, DHW mode, cooling, setpoints
Power Input        | 30-32     | Electrical consumption (total, heating, DHW)
Heat Output        | 40-42     | Thermal energy produced (total, heating, DHW)
Efficiency         | 50-52     | COP (total, heating, DHW), gated
Heating Circuit    | 60-67     | Supply/return temps, ΔT, pump speed, flow
DHW                | 80        | Hot water tank temperature
Environment        | 90-93     | Outside temp, room temp and targets
Source Circuit     | 100-106   | Brine/ground loop temps, ΔT, pump, flow
Mixing Circuits    | 120-131   | MC1 and MC2 temperatures
Compressor         | 140-145   | Frequency, targets, capacity, freq headroom
Refrigerant        | 160-174   | Temps, pressures, superheat, diagnostics
Statistics         | 180-185   | Runtime hours, start count, last cycle
Diagnostics        | 200-202   | Error count, cooling permitted, cooling release

Migrating history from the original plugin
The two plugins use different keys (luxtronik and luxtronikex), so they can run side by side while you migrate. SQL scripts copy temperature history, energy meters, percentages and switch logs to the new devices. They match devices by unit number, not by name, so your language setting does not matter.

The migration folder is not in the release zip or the lean branch; download it from the repository's main branch. Then, from the folder that holds domoticz.db:

Code: Select all

sudo systemctl stop domoticz
cp domoticz.db domoticz.db.backup
sqlite3 domoticz.db < migration/discover.sql   # optional preview
sqlite3 domoticz.db < migration/migrate.sql
sudo systemctl start domoticz

Full instructions are on the documentation site under Migrating from v1.

Tip for accurate COP averages
Enable Setup → Settings → Log History → "Only add newly received values to the Log". Otherwise Domoticz repeats the last value every 5 minutes while the heat pump is idle, which dilutes your daily and monthly COP. This setting affects all devices, not just this plugin.

Troubleshooting
The documentation has a troubleshooting page organised by symptom. For logs, set Debug level on the hardware page: Basic (lifecycle and summaries), Basic + Device (adds device updates), Basic + Comms (adds connection and protocol details), Basic + Device + Comms, or All (also adds conversions and gating decisions, and fills the log quickly). Set it back to None afterwards. When reporting a problem, please include the log lines and your plugin version, either here or as a GitHub issue.

Screenshots

Power, heat output, COP, circuits and pumps

Utility.png (169.51 KiB) Viewed 1164 times

Temperature sensors

Temperature.png (78.73 KiB) Viewed 1164 times

Working mode, controls and setpoints

Controls.png (86.33 KiB) Viewed 1164 times

[Ragdag]

v2.0.1 Released

Quick update pushed to the repository.

The main addition is a configurable max COP limit. Some of you may have noticed occasional COP spikes during transient conditions — brief moments where the power/heat ratio produces unrealistically high values (COP 8, 12, or even higher) before the system settles. These spikes, even if they only last a few seconds, can pull your daily and monthly averages up and make your efficiency stats unreliable.

You can now set a max COP threshold in the hardware configuration (Mode1 field). Any COP value exceeding the limit is gated and not logged. Set it to 0 or leave it empty to disable filtering. A value around 10–15 is sensible for most ground-source systems, but you know your setup best.

The gating works together with the existing steady-state filter (compressor must be at or above minimum frequency), so between the two you should get clean COP history that actually reflects real operating efficiency.

Other fixes in this release:

• Single-connection refactor — heartbeat reads (READ_CALCUL + READ_PARAMS) now share one TCP connection instead of opening two per cycle
• Fixed a partial TCP read vulnerability that could silently corrupt data under poor network conditions
• Fixed retry logic — the old MAX_RETRIES=1 actually meant zero retries
• Cleaner plugin teardown on stop

Update:

Code: Select all

cd /path/to/domoticz/plugins/luxtronik-domoticz-plugin-v2
git pull
sudo systemctl restart domoticz

No migration needed, no device changes — just pull and restart.

[Ragdag]

v2.0.3 Released

Two new features in this release: pump power compensation and refrigerant diagnostics.

Pump Power Compensation

The controller's power reading (and therefore COP) only measures compressor power — confirmed by the manual footnote "alleen compressor". Circulation pumps (HUP and VBO) run
on separate electrical feeds and are not included. For my WZSV 92K3M at typical operating points (HUP 68%, VBO 12%), that's roughly 30W of unaccounted pump power, making
COP about 15% too optimistic.

You can now enable pump power compensation in the hardware configuration. It estimates pump power from the speed percentages already available in the protocol, using a
quadratic model, and adds it to the compressor reading before any power or COP device sees the data. All your existing power and COP devices automatically show corrected
values — no new devices needed.

Settings:

• Pump Power Compensation — On/Off (default: Off)
• Pump Power Ranges (W) — HUP min, HUP max, VBO min, VBO max (default: 2,60,3,140 for WZSV 92K3M)

Check your manual's technical data table for the "Opgenomen vermogen circulatiepomp" line to find the correct values for your model.

Refrigerant Diagnostics

Four new devices for those who want deeper insight into the refrigerant circuit. All are created as unused by default — enable the ones you want in Setup → Devices:

• Condensing temperature — from firmware calculation (gated)
• Subcooling — condensing temp minus liquid line temp, indicates refrigerant charge health (gated)
• Condensing pressure — from firmware calculation (gated)
• Cooling release timer — countdown until cooling mode is permitted (HH:MM:SS)

The gated devices only update during steady-state operation, so you won't get meaningless readings when the compressor is off.

Update:

Code: Select all

cd /path/to/domoticz/plugins/luxtronik-domoticz-plugin-v2
git pull
sudo systemctl restart domoticz

No migration needed, no device changes — just pull and restart. New devices appear as unused; enable what you want.

[Ragdag]

Luxtronik heat pump plugin v3.0.0 is out

The Luxtronik plugin for Domoticz (Alpha Innotec and other Luxtronik 2 based heat pumps) has a new major release. It brings a reworked settings page, pump power compensation by model, and a daily check for new versions.

Release notes and download

Before you upgrade

• Requires Domoticz 2026.1 or newer and Python 3.11 or newer. The new settings page uses named plugin settings, which older Domoticz versions do not have. On an older Domoticz, stay on 2.2.0.
• Your settings move to new fields. Your previous values keep working until you next save the plugin's hardware page, but that page shows the defaults, not your values. Before pressing Update, choose your values again. The plugin lists them in the Domoticz log at every start until you do, and sends the same list once through your Domoticz notification systems. Saving without choosing them again resets them to the defaults shown. IP address and port are not affected.

The log line looks like this:

Settings moved to new fields in this version. Until you save the hardware page, the plugin keeps using your previous values. ... Previous values: Max COP value = 30; Update interval = 20 seconds; Language = Nederlands; Pump power compensation = WZSV 92; Debug level = None

New settings page

• Pump power compensation by model. The controller only measures compressor power, which makes COP look better than it is. Choose WZSV 62, 92, 122 or 162 and the plugin adds the estimated power of the heating and brine circulation pumps, with values from the WZSV technical data. Choose Custom to enter the four pump power values yourself, for another heat pump or different pumps. An invalid value is reported by field, for example "Brine pump min 200 W is above max 140 W".
• Language "Same as Domoticz" is the new default. Device names follow the Domoticz interface language when it is English, Polish, Dutch, German or French, otherwise English. Names you changed yourself are kept.
• Update interval is now a choice of 10, 15, 20 or 30 seconds. A previous interval above 30 seconds is limited to 30.

Update check
Once a day the plugin asks GitHub whether a newer release exists, and announces each new version once, in the Domoticz log and through every notification system you have set up in Domoticz. The new Update check setting offers Automatic (the default), Stable releases only, Including betas, or Off. The check sends nothing about you or your heat pump, and it never installs anything.

Fixes

• The description of the "Cooling release" device was English in every language; it is now translated. Existing devices pick it up on the next start, unless you edited the description yourself.

Install or upgrade
Your devices and history are unaffected: nothing is re-created or renamed, because device identity is based on the Domoticz hardware ID.

• Plugin manager: update the plugin as usual.
• Release zip: download luxtronikex-v3.0.0.zip from the release page and replace the contents of your plugins/luxtronikex folder.
• Git: if you cloned the lean dist branch, pull and restart Domoticz:

Code: Select all

cd /path/to/domoticz/plugins/luxtronikex
git pull
sudo systemctl restart domoticz.service

After restarting, open Setup > Hardware, select the plugin, choose your settings again (check the log for your previous values) and press Update.

Project page with the full README

Questions, problems or translation fixes are welcome here or as a GitHub issue.

[imautohuttraeger]

In the initial post one year ago, you mention, that Wolf heat pumps are base on Luxtronic 2. But it seems, that this was only valid for older models - right?

I have a Wolf CHA07 and at least AI tells me, that it is not Luxtronic based. Background: I would love to see all data in Domoticz but haven't found an easy way for the time beeing.

[Ragdag]

In the initial post one year ago, you mention, that Wolf heat pumps are base on Luxtronic 2. But it seems, that this was only valid for older models - right?

I have a Wolf CHA07 and at least AI tells me, that it is not Luxtronic based. Background: I would love to see all data in Domoticz but haven't found an easy way for the time beeing.

You're right, and I should have been more precise in that first post. Only some Wolf heat pumps have a Luxtronik controller: the BWL and BWS series. The CHA uses Wolf's own control system on eBUS, so this plugin can't connect to it. The plugin only speaks the Luxtronik protocol (TCP port 8889).

I don't own a CHA, so I can't give you a tested recipe. From what other CHA owners report, these are the routes people use:

1. ISM7 / Link Home + ism7mqtt: several CHA owners read their data this way and publish it to MQTT. From MQTT you can get it into Domoticz, for example via the MQTT Auto Discovery gateway (if discovery messages are available) or with dzVents/Node-RED.
2. Wolf ISM8 module: Wolf's local interface; the CHA is listed as supported in the openHAB ISM8 binding docs. Which data points you get depends on the ISM8 and heat pump firmware. You would still need a bridge into Domoticz.
3. eBUS + ebusd: possible, but owners describe it as fiddly: the adapter receives data, decoding the CHA messages is the hard part. Check the ebusd-configuration repo for current CHA support before buying an adapter.

Note that EEBUS (firmware 5.0+) is something different from eBUS: it is aimed at energy management, not full monitoring.

If you get one of these working, please share it here; I'm sure other CHA owners would like to know.

[imautohuttraeger]

[...]
You're right, and I should have been more precise in that first post
[...]

Oh no - this was not meant by me to complain. Thank you very much for the detailed description of possible solutions. Indeed I was trying ism7mqtt a while ago, but I have it up without success (I am just a "copy - paste - hoping it works - guy )

[Ragdag]

No worries, without any physical hardware it would be very difficult for me to develop anything.
Will have a think if I could do anything some way

[Ragdag]

[...]
You're right, and I should have been more precise in that first post
[...]

Oh no - this was not meant by me to complain. Thank you very much for the detailed description of possible solutions. Indeed I was trying ism7mqtt a while ago, but I have it up without success (I am just a "copy - paste - hoping it works - guy )

I had that think, and did some digging. Short version first: this plugin can't be used for a CHA, because only the Wolf BWL and BWS have a Luxtronik controller. The CHA has Wolf's own control system, so it would need a separate plugin. These are the ways a CHA can be read:

• ISM8 module: Wolf's local network interface. It sends its data straight to a server you choose, no cloud involved, and Wolf publishes the data list for it: temperatures, heating and cooling power, power consumption, pump and valve status, system pressure, operating mode and fault codes. If I ever build a plugin, this is the only route where I think that's realistic.
• Link Home / ISM7: what newer CHA units usually come with. It mainly talks to Wolf's cloud (the Smartset app), and its local protocol is not documented. ism7mqtt works around that by reverse-engineering it, which is also why setting it up can be fiddly. A plugin built on that could break with any Wolf firmware update, so I'd rather not go there.
• eBUS: the internal bus between the Wolf components. It needs an extra adapter, and other CHA owners say turning the raw messages into usable values is the hard part. Not a good base for a plugin.
• EEBUS: despite the name, not the same as eBUS. It came with controller firmware 5.0 and is meant for energy management (solar and grid signals), not for monitoring.

To see whether anything is possible, it would help to know a bit more about your setup:

1. Which Wolf network modules do you have: Link Home, ISM7i, ISM8i, or none? If you're not sure, the model name is usually printed on the module itself.
2. Which CHA do you have (07 or 10), with or without cooling, and are there other Wolf parts connected (BM-2 control module, mixer modules, solar, ventilation)?
3. Which values would you most like to see in Domoticz?
4. Which Domoticz version are you running?
5. When you tried ism7mqtt, do you remember where it got stuck? That might still be the quickest way to get your data in.

No promises, but your answers will tell me whether this is worth pursuing.

[imautohuttraeger]

Which Wolf network modules do you have: Link Home, ISM7i, ISM8i, or none?
->> ISM7i

Which CHA do you have (07 or 10), with or without cooling, and are there other Wolf parts connected (BM-2 control module, mixer modules, solar, ventilation)?
--> CHA07 with BM-2 controll display module

Which values would you most like to see in Domoticz?
--> actual power, consumed energy, amount of heat produced, number of cycles (compressor starts).

Which Domoticz version are you running?
--> always latest beta

When you tried ism7mqtt, do you remember where it got stuck?
--> Not really, it is more than one year ago. There where error messages in Linux (Raspi) even before I could get further

[Ragdag]

Good news: the ISM7i turns out to be the better module for what you want. I looked at the list of values ism7mqtt can read from a CHA, and all four of yours are in there:

• Actual power: power consumption (heat pump + electric heater), heating output and compressor frequency.
• Consumed energy: electrical energy counters (previous day, heating period, previous year).
• Heat produced: heat amounts for heating, hot water and cooling, plus per day, month and year.
• Compressor starts: the start counter, plus compressor run hours.

For comparison, the ISM8 I mentioned earlier has no energy counters and no compressor starts, so for your wishes the ISM7i is actually the better module.

So instead of a new plugin, I think the quickest way is to get ism7mqtt working after all. It sends the values to an MQTT broker, and Domoticz has a hardware type, "MQTT Auto Discovery Client Gateway", that can create the devices from that automatically. It has improved since you last tried: there are now ready-made Raspberry Pi versions and a Docker image, so no programming tools are needed. One thing to know: the ISM7i accepts only one connection at a time, so while ism7mqtt runs, the Wolf Smartset app can't connect.

Since this has nothing to do with Luxtronik anymore, could you open a new topic for it? That keeps this thread about the plugin, and makes it easier for other Wolf owners to find. I'll follow you there. I haven't tested this combination myself, so before writing step-by-step instructions it would help if you answer these in the new topic:

1. Do you already have an MQTT broker running (for example Mosquitto)?
2. What does your Raspberry Pi show when you run this command in a terminal? That tells me which version you need.

   Code: Select all

   uname -m

3. Is Docker installed on it? (No problem if not.)
4. Do you use the Wolf Smartset app regularly, or could you live without it?
5. Do you know the password of the ISM7i?

[imautohuttraeger]

Wow! Thanks for your support. Very good idea. Will create a new topic and link it here. I will be traveling from tomorrow Sunday 25th untill Saturday 31st. So maybe it will last a week - let's see.

[imautohuttraeger]

I have created the separate topic:
viewtopic.php?t=45279

[Ragdag]

Version 3.2.0 is out: run time per day, week and month, and health bars
Release notes and download | Devices documentation

Same requirements as 3.0: Domoticz 2026.1 or newer and Python 3.11 or newer. Settings, devices and history are kept. Seven new devices are created on the first start; if Accept new devices is off, the plugin names the ones it could not create and tells you how to allow them.

Run time and starts per day, week and month
Until now the run-time devices only showed lifetime totals, so you could not see how long the hot water ran yesterday. Units 186 to 192 read the same controller totals as Domoticz counters. The card shows today's value with the lifetime total below it, and the device log has bar charts per day, week, month and year.

• 186 Compressor run time
• 187 Compressor start counter (a quick check on cycling)
• 188 Heating run time
• 189 Hot water run time
• 190 Backup heater run time (handy to spot the days the electric heater came on)
• 191 Cooling run time and 192 Heat pump run time (created as unused)

On Domoticz 2026.4 the run times are shown in minutes. I added an option to Domoticz that lets a plugin set a counter's divider (domoticz#7169, merged); on beta build 18539 and newer the counters are created in hours instead. You can switch an existing counter yourself: edit it and set Counter Divider to 60 and Unit to h. The plugin never changes those fields after creating the device. History starts on the day the counters are created.

Run time.png (52.22 KiB) Viewed 1046 times

Health bars
On Domoticz 2026.4 and newer, eight cards get a green, amber or red bar. Every edge comes from your own controller (read live), the WZSV or Luxtronik manual, or Alpha Innotec; I did not make up any limits.

• Hot gas: red from your controller's own cut-off (T-HG max, 115 °C on my unit)
• Heat supply: red from your controller's Vorlauf max, and below 16 °C (the cooling fault limit)
• Hot water: amber below 50 °C (legionella growth range), red above 65 °C
• Superheat: red below 2 K (fault 765)
• COP total, heating and hot water: red below 1
• Compressor last cycle: red under 6 minutes, amber up to 30, green from 30 (Alpha Innotec's own guidance on cycling)

A bar you change or remove in the edit dialog is kept, and so is a bar you drew before this version. Return temperature, brine temperatures and source flow deliberately have no bar: in testing, return was red on every hot water run, Domoticz draws an axis that crosses 0 °C from its centre, and the flow sensor reads below the manual's minimum in normal operation.

Health bars.png (74.85 KiB) Viewed 1046 times

Updating
Release zip: extract the new zip over your plugins/luxtronikex folder. Git on the dist branch: git pull in that folder. Plugin managers pick it up from the dist branch. Then restart Domoticz.