Python Plugin: Luxtronik Heat Pump Controller Plugin v2

[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 (142.45 KiB) Viewed 70 times

Temperature sensors

Temperature.png (64.94 KiB) Viewed 70 times

Control switches and selectors

LightSwitches.png (26.69 KiB) Viewed 70 times

Link
GitHub Repository

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

[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.