ioBroker.luxtronik2-controller

Tests:

luxtronik2-controller adapter for ioBroker

This ioBroker adapter enables the local control and monitoring of heat pumps with Luxtronik 2.x controllers (e.g., Alpha Innotec, Novelan). The adapter is written entirely in TypeScript.

Acknowledgements & History

This project builds upon the preliminary work of existing open-source projects. Special thanks go to:

Bouni Whose pioneering work and code developments form the essential foundation for communication with Luxtronik controllers.

Coolchip: For the fundamental reverse engineering of the Luxtronik network protocol.

UncleSamSwiss: For the original ioBroker adapter.

Innovations in this version: The luxtronik2-controller natively integrates TCP communication (Port 8888 / 8889) and does not rely on external libraries. Additionally, controlling macros, a logic for compressor protection, and automated datapoint management were implemented.

Features

• Native TCP Communication: Direct connection to the heat pump without any additional overhead.
• Compressor Protection (Cycle Optimization): Intelligent merging of heating and domestic hot water (DHW) cycles to significantly reduce compressor starts.
• Dynamic HUP Control: Automatic voltage adjustment of the heating circulation pump (HUP) based on the flow and return temperature spread for maximum efficiency.
• Integrated Actions (Macros): Pre-defined control logic for forced heating, DHW requests, and the circulation pump (ZIP) – including an automatic fallback to safe default values.
• Demand-Driven Circulation (ZIP): Control your circulation pump via existing ioBroker motion sensors or directly via external actuators (e.g., Shelly) – entirely without hardware modifications to the heat pump.
• Custom Datapoints: Measured values (Index 3004) and parameters (Index 3003) can be flexibly added via the adapter configuration. Unix timestamps are automatically parsed into human-readable formats.
• Extended Status Texts & Calculations: Live calculation of temperature spread, thermal energy, and detailed text outputs of current system states (including offsets, frost protection, and cooling status).
• Intelligent Notification System: Send error codes and critical shutdowns (like flow rate issues) directly to Telegram or the ioBroker notification system – complete with cooldown spam protection.
• Automated DTA Backup: Scheduled downloads of DTA diagnostic logs directly from the heat pump to your ioBroker storage for easy analysis (e.g., in OpenDTA).
• Automatic Object Management: Deselected or deleted datapoints, as well as empty folder structures, are automatically and cleanly removed from ioBroker upon an adapter restart.
• Broad Compatibility: Full support for older (V2.x) and newer (V3.x) firmware generations (e.g., Alpha Innotec, Novelan) utilizing dynamic scaling factors.

⚠️ Warning

Some settings provided by this integration can affect the performance of your heat pump. Misconfigurations can cause the controller to enter a fault state, which requires a manual on-site reset.

This project aims to protect your heat pump by restricting the configuration options to safe values. However, no guarantees can be made. Please be careful, consult your Luxtronik manual, and do not change any settings that you do not fully understand.

🔧 Compatibility

The integration allows you to monitor and control heat pumps with a Luxtronik2 controller. It works locally without internet access. It was and is being tested with an LWD50A (LD5) from Alpha Innotec. It is used by manufacturers such as:

• Alpha Innotec,
• Siemens,
• Novelan,
• Roth,
• Elco,
• Buderus,
• Nibe,
• Wolf Heiztechnik.

⚠️ Disclaimer ⚠️

This project is not affiliated with Alpha Innotec, Novelan, ait-deutschland GmbH, or any other company. It is a personal project that is maintained in spare time. Use at your own risk.

Reporting Bugs & Contributing

Bug reports, compatibility notes for specific firmware versions, or feature requests can be submitted via the issue tracker in the GitHub-Repository.

Information

Info Deutsch

Info English

Changelog

// ### WORK IN PROGRESS

0.13.1 (2026-10-02)

• Fix (Circulation/ZIP): Fixed a bug where the Virtual_ZIP_Status datapoint would remain stuck on true when using external relays (e.g., Shelly), even though the hardware relay was correctly turned off. The state reset logic has been decoupled and is now guaranteed to execute, ensuring the ioBroker interface stays perfectly synchronized with the actual hardware state.

0.13.0 (2026-10-02)

• Bugfixes:
  • Critical DHW Target Fix: Fixed an issue where the hot water target temperature was incorrectly written to parameter 2 instead of 105. This resolves unexpected temperature jumps (e.g., to 65°C) and socket timeouts on various heat pump models.
  • Write Queue Timeout: Added a maximum wait timeout to the write queue lock for legacy V1.x firmware to prevent potential infinite loops during read-write collisions.
  • Backup Manager Multi-Instance Fix: The automated DTA backup cron job is now safely scoped to the specific adapter instance, preventing conflicts when running multiple heat pumps on the same ioBroker host.
• Under the Hood / Refactoring:
  • Centralized Typings: Completely refactored the TypeScript architecture by introducing a centralized LuxtronikAdapter interface (types.ts). Replaced all fragmented, local interfaces across sub-modules to ensure strict, project-wide type safety and better maintainability.

0.12.1 (2026-09-30)

• Bugfixes:
  • Fixed Null-Values on Startup: Virtual states for the circulation pump logic (Actions.Activate_Zip and 03_Outputs.Virtual_ZIP_Status) are now explicitly initialized to false during adapter startup. This prevents undefined null values in the object tree, ensuring immediate compatibility with visualizations and logic scripts (like Blockly) right from the first second.

0.12.0 (2026-09-30)

• ⚠️ BREAKING CHANGE:

  • The datapoint to manually trigger the circulation pump macro (Activate_Zip) has been moved from the Settings folder to the Actions folder for better UX. If you use this state in your scripts or visualizations, please update the datapoint path!

• Features & Improvements:

  • Virtual Circulation Pump (ZIP) Status: Added a new read-only indicator datapoint (Virtual_ZIP_Status) in the 03_Outputs folder. This datapoint mirrors the true state of the adapter's intelligent circulation pump macro in real-time. This is highly beneficial for users controlling the ZIP via external smart relays (e.g., Shelly) to avoid controller flash-wear, as it provides an accurate status even when the heat pump's internal display is bypassed.

0.11.2 (2026-09-30)

• Features & Improvements:

  • Smart Parameter Filtering: Added full support for the Luxtronik visibility registry (Network Command 3005). The adapter now automatically hides parameters in the ioBroker object tree that are physically not supported by your specific heat pump model (e.g., hiding defrost valves on brine-to-water pumps). This dramatically declutters the system.
  • Added an "Expert Mode" toggle in the adapter configuration to optionally disable the visibility filter and force-show all parameters.
  • Extended the "Dump Raw to Log" feature to include the visibility matrix (Command 3005).
  • Legacy Write-Mode (V1.x): Added a new connection setting for older heat pumps (Firmware V1.x). This "Fire-and-Forget" mode prevents Timeout writing TCP parameter errors on controllers that do not send network acknowledgments after receiving a write command.
  • Dynamic Hardware Protection: The adapter now automatically detects your firmware version and adjusts network write delays dynamically (500ms for V1.x vs. 100ms for modern firmwares) to ensure maximum responsiveness without sacrificing stability.
  • Safe Payload Rounding: Enforced strict integer rounding (Math.round) for all numeric write payloads to prevent memory faults and crashes on older Luxtronik controllers.
  • Visibility Filter UX: Added a warning to the visibility filter configuration (Command 3005) to clarify that this feature requires Firmware V3.x and should be disabled on older systems to avoid startup timeouts.

• Bugfixes:

  • Fixed Heat Pump Crashes / Reboots: Implemented a global mutex lock between the polling cycle (updateData) and the write queue. This guarantees that read and write operations never overlap, preventing fatal network socket collisions that caused V1.x controllers to freeze and reboot.
  • Fixed Object Cleanup: Changed the mass deletion of orphaned objects and empty folders during adapter startup from parallel to sequential execution. This prevents the ioBroker database from being overloaded and silently dropping delete commands.

License

MIT License

Copyright (c) 2026 TbsJah [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Older changelogs can be found there