Page 1 of 1

Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Thursday 04 December 2025 14:45
by Ragdag
I'm excited to share Luxtronik Heat Pump Controller Plugin v2 for Domoticz! This is a complete rewrite of my original Luxtronik plugin, rebuilt from the ground up using the modern DomoticzEx framework.

The plugin integrates Luxtronik 2.0/2.1 based heat pump controllers (Alpha Innotec, Siemens Novelan, Roth, Elco, Buderus, Nibe, Wolf Heiztechnik, and others) with Domoticz, providing comprehensive monitoring and control of your heating system.

Why a New Plugin?
The original plugin served well, but had limitations that couldn't be fixed without a complete rewrite:
  • Legacy Domoticz framework with 256-device limit
  • Device IDs could change, causing orphaned devices
  • COP values logged during idle periods skewed efficiency statistics
  • No multi-instance support for multiple heat pumps
The v2 plugin addresses all of these with a clean, modern architecture.

Key Improvements
  • DomoticzEx Framework: Modern Device/Unit model with proper callback support
  • Stable Device IDs: HardwareID-based identifiers that never change across restarts or updates
  • Intelligent COP Tracking: Separate measurements for heating mode, DHW mode, and combined total — only logged during steady-state operation
  • Gated Sensors: Pressure, superheat, and ΔT values only update during active cycles, keeping your statistics clean
  • Multi-Instance Support: Run multiple plugin instances for homes with more than one heat pump
  • Secure Write Protection: All write commands validated against an explicit allowlist
  • Logical Device Organization: 62 devices organized into 14 functional groups with room for expansion
  • Multi-Language: English, Polish, Dutch, German, and French
Device Overview
The plugin creates 62 devices organized into logical groups:

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 values (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-144   | Frequency, target/min/max freq, capacity %
Refrigerant        | 160-167   | Hot gas, suction, discharge, evap/cond temps
Statistics         | 180-185   | Runtime hours, start count, cycle duration
Diagnostics        | 200-201   | Error count, cooling permitted status
Each group has reserved unit ranges for future expansion without breaking existing installations.

New Sensors in v2
  • Compressor runtime hours and start count
  • Last cycle duration
  • Capacity utilization percentage
  • Discharge, evaporating, and condensing temperatures
  • Controller spread targets (heating and source ΔT setpoints)
  • Heating and source flow rates
  • Mode-specific runtimes (heating, DHW, cooling hours)
Installation

Code: Select all

cd /path/to/domoticz/plugins
git clone https://github.com/Rouzax/luxtronik-domoticz-plugin-v2.git luxtronik-domoticz-plugin-v2
sudo systemctl restart domoticz
In Domoticz: Setup → Hardware → Add, select "Luxtronik Heat Pump Controller v2", enter your heat pump's IP address and port (default 8889).

Migration from v1
The new plugin uses a different key (luxtronikex vs luxtronik), so both can run simultaneously. Migration scripts are included to transfer your historical data:

Code: Select all

# 1. Backup first!
sudo systemctl stop domoticz
cp domoticz.db domoticz.db.backup

# 2. Preview what will be migrated
sqlite3 domoticz.db < plugins/luxtronik-domoticz-plugin-v2/migration/discover.sql

# 3. Run migration
sqlite3 domoticz.db < plugins/luxtronik-domoticz-plugin-v2/migration/migrate.sql
sudo systemctl start domoticz
The migration uses Unit ID mapping (not device names), so it works regardless of your language setting. All temperature history, energy meters, percentages, and switch logs are migrated.

COP Accuracy Recommendation
For meaningful efficiency statistics, enable Settings → Log History → "Only add newly received values to the Log" in Domoticz.

The plugin only reports COP during steady-state operation (compressor running at or above minimum frequency, not during startup or idle). Combined with the Domoticz setting, this ensures your monthly/yearly COP averages reflect actual operating efficiency rather than being diluted by idle periods.

Debug Levels
Configurable logging for troubleshooting:
  • None: Errors only
  • Basic: Lifecycle events, connection status, update summaries
  • Device: Individual device updates and state changes
  • Comms: Socket communication details
  • Verbose: Detailed value conversions and gating decisions
  • All: Everything (generates a lot of output!)
Example Log Output

Code: Select all

2025-12-04 14:20:25.100 HP: [VERBOSE] Heartbeat triggered
2025-12-04 14:20:25.100 HP: [VERBOSE] Full update starting
2025-12-04 14:20:25.101 HP: [COMMS] Connected to 192.168.2.63:8889
2025-12-04 14:20:25.105 HP: [COMMS] READ_CALCUL: Received 272 values
2025-12-04 14:20:25.105 HP: [VERBOSE] Fetched READ_CALCUL: 272 values
2025-12-04 14:20:25.106 HP: [COMMS] Connected to 192.168.2.63:8889
2025-12-04 14:20:25.321 HP: [COMMS] READ_PARAMS: Received 1162 values
2025-12-04 14:20:25.321 HP: [VERBOSE] Fetched READ_PARAMS: 1162 values
2025-12-04 14:20:25.321 HP: [VERBOSE] Updating devices for READ_CALCUL
2025-12-04 14:20:25.321 HP: [VERBOSE] working_mode: No changes
2025-12-04 14:20:25.321 HP: [VERBOSE] power_total: Next update in 285s
2025-12-04 14:20:25.323 HP: [VERBOSE] Skipping cop_dhw: gated - mode filtered (mode=0, allowed=[1])
2025-12-04 14:20:25.336 HP: [DEVICE] Updated heating_flow: Values changed - sValue: 300.0 -> 400.0
2025-12-04 14:20:25.357 HP: [DEVICE] Updated evaporating_temp: Values changed - sValue: 6.4 -> 6.5
2025-12-04 14:20:25.396 HP: [VERBOSE] Skipping last_cycle: gated - cycle in progress
2025-12-04 14:20:25.396 HP: [VERBOSE] cooling_permitted: No changes
2025-12-04 14:20:25.396 Status: HP: READ_CALCUL: Updated 7, unchanged 46, gated 2
2025-12-04 14:20:25.397 HP: [VERBOSE] Updating devices for READ_PARAMS
2025-12-04 14:20:25.397 HP: [VERBOSE] heating_mode: No changes
2025-12-04 14:20:25.397 HP: [VERBOSE] hot_water_mode: No changes
2025-12-04 14:20:25.397 HP: [VERBOSE] dhw_power_mode: No changes
2025-12-04 14:20:25.397 HP: [VERBOSE] cooling_enabled: No changes
2025-12-04 14:20:25.397 HP: [VERBOSE] temp_offset: Next update in 285s
2025-12-04 14:20:25.397 HP: [VERBOSE] dhw_temp_target: Next update in 285s
2025-12-04 14:20:25.397 HP: [VERBOSE] room_temp_setpoint: Next update in 285s
2025-12-04 14:20:25.397 Status: HP: READ_PARAMS: Updated 0, unchanged 7, gated 0
2025-12-04 14:20:25.397 HP: [VERBOSE] Full update complete 
Screenshots

Utility devices (power, energy, COP)
Utility.png
Utility.png (142.45 KiB) Viewed 4350 times
Temperature sensors
Temperature.png
Temperature.png (64.94 KiB) Viewed 4350 times
Control switches and selectors
LightSwitches.png
LightSwitches.png (26.69 KiB) Viewed 4350 times
Link
GitHub Repository

Credits
This project builds upon the excellent work of ajarzyn, whose plugin served as the original foundation.

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Monday 09 February 2026 9:29
by 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.

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Friday 13 March 2026 17:10
by 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.

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Saturday 24 October 2026 14:12
by 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.

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Saturday 24 October 2026 14:29
by 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.

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Saturday 24 October 2026 14:44
by Ragdag
imautohuttraeger wrote: Saturday 24 October 2026 14:29 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.

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Saturday 24 October 2026 16:01
by imautohuttraeger
Ragdag wrote: Saturday 24 October 2026 14:44 [...]
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 😉)

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Saturday 24 October 2026 16:09
by 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

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Saturday 24 October 2026 16:42
by Ragdag
imautohuttraeger wrote: Saturday 24 October 2026 16:01
Ragdag wrote: Saturday 24 October 2026 14:44 [...]
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.

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Saturday 24 October 2026 20:10
by 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

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Saturday 24 October 2026 20:32
by 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?

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Saturday 24 October 2026 21:12
by 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.

Re: Python Plugin: Luxtronik Heat Pump Controller Plugin v2

Posted: Sunday 25 October 2026 0:19
by imautohuttraeger
I have created the separate topic:
viewtopic.php?t=45279