homebridge-luxtronik2

This plugin for Homebridge adds temperature sensors for Luxtronik2-based heat pump controllers (Siemens, Novelan, Wolf, Alpha Innotec).

The plugin reads data over the Luxtronik2 TCP API on port 8888.

Newer Luxtronik devices use a different API and are not supported. For those devices, use this plugin.

Install

Install and configure Homebridge and Homebridge Config UI X.

Open the configuration UI, search for "Luxtronik2", and install the plugin.

Restart Homebridge after configuration changes.

If this plugin is useful, please star the repository on GitHub. Stars help others discover the plugin and show support for continued maintenance. You will also see a link at the bottom of the plugin settings screen in Homebridge Config UI.

Usage

Each configured sensor appears as a separate Temperature Sensor accessory in the Home app.

The plugin exposes:

• CurrentTemperature — updated when HomeKit polls the accessory
• StatusActive — false until the first successful controller read, then false again after connection failures

All sensors on the same controller share one TCP client. Requests are serialized so multiple sensors do not open overlapping connections.

Configuration

Version 2.0.0 is a platform plugin. Add one entry under "platforms" in config.json (not under "accessories").

Platform plugins are required for child-bridges and for Homebridge 2.0 Matter support. See Why migrate to a platform plugin? below.

Examples:

• sample-config.json — multi-sensor platform
• sample-config.single-sensor.json — single sensor

Example

{
  "platforms": [
    {
      "platform": "homebridge-luxtronik2",
      "name": "Luxtronik2 Heat Pump",
      "IP": "192.168.1.10",
      "Port": 8888,
      "sensors": [
        {
          "name": "Outdoor Temperature",
          "channel": 5
        },
        {
          "name": "Flow Temperature",
          "channel": 0
        }
      ]
    }
  ]
}

For one sensor, use a sensors array with a single entry. See sample-config.single-sensor.json.

Configuration reference

Field	Required	Type	Default	Description
platform	yes	string	—	Must be homebridge-luxtronik2
name	yes	string	Luxtronik2	Platform label in Homebridge
IP	yes	string	—	Controller IP address
Port	yes	integer	8888	Controller TCP port
sensors	yes	array	—	One or more sensors to expose
sensors[].name	yes	string	—	HomeKit accessory name
sensors[].channel	yes	integer	—	Compacted temperature channel index

Channel numbers

channel values are compacted indices produced by the plugin decoder. They are not the raw keys from lib/channellist.json.

The config UI and schema list the most common temperature channels. Names come from the Luxtronik2 firmware (German abbreviations). Not every sensor is present on every heat pump — pick the channel that matches a value you see on the controller display or web interface.

Channel	Sensor name	Meaning
0	Temperatur_TVL	Heating circuit flow (supply) temperature — Vorlauf
1	Temperatur_TRL	Heating circuit return temperature — Rücklauf
2	Sollwert_TRL_HZ	Heating circuit return setpoint — Sollwert (target), HZ (heating)
3	Temperatur_TRL_ext	Buffer/storage tank return temperature
4	Temperatur_THG	Compressor hot-gas temperature — Heißgas
5	Temperatur_TA	Outdoor air temperature — Außen (most common choice)
6	Mitteltemperatur	24-hour average outdoor temperature (used for heating curve/limit)
7	Temperatur_TBW	Domestic hot water temperature (actual) — Brauchwasser
8	Einst_BWS_akt	Domestic hot water target temperature (active setpoint) — Brauchwasser Sollwert
9	Temperatur_TWE	Heat source inlet temperature (e.g. brine or intake air) — Wärmequelle Ein
10	Temperatur_TWA	Heat source outlet temperature — Wärmequelle Aus
11	Temperatur_TFB1	Mixing circuit 1 flow temperature — FB (floor/mixing circuit)
12	Sollwert_TVL_MK	Mixing circuit 1 flow setpoint — MK (mixing circuit)
13	Temperatur_RFV	Room temperature from room station 1 — Raumfühler
14	Temperatur_TFB2	Mixing circuit 2 flow temperature
15	Sollwert_TVL_MK2	Mixing circuit 2 flow setpoint
16	Temperatur_TSK	Solar collector temperature — Solar Kollektor
17	Temperatur_TSS	Solar storage tank temperature — Solar Speicher
18	Temperatur_TEE	External heat source temperature — externe Energiequelle

Additional temperature channels from channellist.json can be used manually in config.json if needed.

Why migrate to a platform plugin?

Version 1.x registered each sensor as a standalone accessory plugin ("accessory": "homebridge-luxtronik2.temperature"). That worked for HomeKit, but it cannot participate in newer Homebridge features that rely on platform plugins and child-bridges.

Child-bridges

A child-bridge lets a platform plugin run as its own separate Homebridge bridge instead of sharing the main bridge. Each child-bridge gets its own pairing PIN, accessory cache, and (optionally) its own Matter endpoint. That keeps your main bridge uncluttered and avoids HomeKit's per-bridge accessory limit.

Child-bridges are configured on a platform entry with a _bridge block in config.json. Only platform plugins support this — legacy accessory plugins cannot run as child-bridges.

Homebridge Matter support

Homebridge 2.0 can expose accessories over Matter in addition to HomeKit. Matter is opt-in per bridge: you add a matter block to the main bridge config and/or to a platform's _bridge (child-bridge) config. Each Matter-enabled bridge advertises separately and is paired with its own QR code.

Because Matter is configured at the bridge level, platform plugins that can run as child-bridges are the natural way to expose plugin accessories to Matter controllers (Apple Home, Google Home, Alexa, SmartThings, and others). Legacy single-accessory plugins do not fit this model.

Migrating from 1.x accessory entries to a 2.x platform entry is therefore required — not just a config tidy-up — if you want this plugin to work with child-bridges and future Homebridge Matter support.

Migrating from 1.x

Version 2.x is a platform-only plugin. It does not load "accessory": "homebridge-luxtronik2.temperature" entries.

If your config.json still shows the old accessory block, the plugin auto-migrates legacy homebridge-luxtronik2.temperature entries to platform config on startup and logs a message asking you to restart Homebridge. Until that restart, a compatibility shim prevents the recurring startup error. You can also migrate manually with the script below. After migrating, you can optionally enable a child-bridge by adding a _bridge block to your platform config.

Migrate with the included script

Run this once against your Homebridge config:

npm run migrate-config -- /path/to/homebridge/config.json

Or:

node scripts/migrate-config.js /path/to/homebridge/config.json

For Docker/Portainer setups, the path is often /homebridge/config.json inside the container, or ~/docker/homebridge/config.json on the host.

The script:

• Finds "accessory": "homebridge-luxtronik2.temperature" entries
• Creates equivalent "platform": "homebridge-luxtronik2" blocks
• Groups multiple old accessories on the same IP/port into one platform with a sensors array
• Removes the migrated accessory entries
• Leaves unrelated accessories untouched

Restart Homebridge after migrating.

Manual migration

Before (1.x)

{
  "accessories": [
    {
      "accessory": "homebridge-luxtronik2.temperature",
      "name": "Luxtronik2",
      "IP": "192.168.1.10",
      "Port": 8888,
      "Channel": 5
    }
  ]
}

After (2.x)

{
  "platforms": [
    {
      "platform": "homebridge-luxtronik2",
      "name": "Luxtronik2",
      "IP": "192.168.1.10",
      "Port": 8888,
      "sensors": [
        { "name": "Luxtronik2", "channel": 5 }
      ]
    }
  ]
}

Manual migration steps:

1. Remove the old "accessories" entry with "accessory": "homebridge-luxtronik2.temperature".
2. Add the equivalent "platforms" entry shown above.
3. Restart Homebridge.
4. Remove stale accessories from the Home app if Homebridge shows duplicates.

To expose multiple temperatures from one controller, add more entries to sensors.

Homebridge Config UI still shows the old accessory?

The UI reads the installed plugin files, not just config.json.

If you still see homebridge-luxtronik2.temperature as an accessory option, one of these is usually the cause:

1. Stale plugin code in node_modules — an older build that still registered the legacy accessory type
2. Old version pin — ~/docker/homebridge/package.json still listing "homebridge-luxtronik2": "1.6.1"
3. Cached UI metadata — restart Homebridge after updating the plugin

After upgrading, confirm the installed plugin contains:

• config.schema.json with "pluginType": "platform"
• index.js that only calls registerPlatform(...)

Then restart Homebridge (and refresh the Config UI).

Troubleshooting

• Confirm the controller is reachable on port 8888.
• Enable Homebridge debug logging with homebridge -D.
• Check that StatusActive becomes true after the first successful read.
• Verify IP, Port, and channel values. Port and channel must be numbers, not strings.

Support

• Star on GitHub — the quickest way to support the project
• Report issues or ask questions on the issue tracker
• Sponsor the maintainer (optional)

Development

npm test

Tests run JSON validation and Node.js unit tests for:

• Luxtronik2 protocol parsing and TCP client (test/luxtronik2-client.test.js)
• Platform config normalization (test/config.test.js)
• Legacy config migration (test/migrate-config.test.js)
• Channel metadata (test/channels.test.js)
• Platform accessory discovery (test/platform.test.js)
• Accessory service wiring (test/accessory.test.js)
• Temperature sensor handler behavior (test/sensor-handler.test.js)
• Shared utilities (test/tools.test.js)

See CHANGELOG.md for release notes.