@slycke/homebridge-xcomfort-shc

Homebridge 2 platform plugin for Eaton Xcomfort Smart Home Controller devices.

This is a maintained fork and successor of moritzw1/homebridge-xcomfort. It keeps the Xcomfort Homebridge platform alias for easier migration.

Repository: slycke/homebridge-xcomfort-shc

This project is not affiliated with Eaton.

Requirements

• Homebridge 2
• Node.js 22.12 or newer, or Node.js 24
• Eaton Xcomfort Smart Home Controller (SHC) on the same local network
• An SHC zone with the devices you want to expose to Homebridge

The round Xcomfort bridge is not supported, only SHC.

Supported Devices

• CRCA-00 Room Controller Touch: humidity, temperature, ambient light
• CDAx-01/0x dimming actuators: on/off and brightness
• CSAU-01/01-1x switch actuators: on/off
• Light actuators: on/off as HomeKit lights

Installation

Install through the Homebridge UI by searching for @slycke/homebridge-xcomfort-shc, or install manually:

npm install -g @slycke/homebridge-xcomfort-shc

Configuration

Example Homebridge platform config:

{
  "platform": "Xcomfort",
  "ip": "192.168.2.100",
  "user": "admin",
  "password": "password",
  "zone": "14",
  "intervalActive": 15,
  "intervalSleep": 60,
  "step": 1
}

Fields:

• platform: must remain Xcomfort.
• ip: IPv4 address of the SHC.
• user: SHC user with access to the configured zone.
• password: SHC user password.
• zone: numeric part of the SHC zone, for example 14 for hz_14. Existing configs using hz_14 are also accepted.
• intervalActive: polling interval in seconds while Home has recently interacted with an accessory. Default: 15.
• intervalSleep: polling interval in seconds after five minutes without Home app activity. Default: 60.
• step: brightness step size for dim actuators. Default: 1.

Migrating From homebridge-xcomfort

Do not run the original homebridge-xcomfort package and this package at the same time. Both use the Xcomfort platform alias during the migration period.

Recommended migration:

1. Back up your Homebridge config.
2. Install @slycke/homebridge-xcomfort-shc.
3. Remove homebridge-xcomfort.
4. Keep your existing platform: "Xcomfort" config.
5. Restart Homebridge once.
6. Verify that the cached accessories restored and that each device responds.

The plugin preserves accessory UUID generation from the SHC device id, so existing HomeKit rooms, scenes, and automations have the best chance of surviving the package transition.

If you restarted with both packages installed and see duplicate or no-response accessories, remove the original homebridge-xcomfort package, restart Homebridge, and then check the cached accessories again.

Development

npm install
npm run build
npm run lint
npm test

For final local testing, use an ignored Homebridge profile with Homebridge, Homebridge UI, and this plugin installed into that profile. This keeps the test environment close to a real UI-managed install without adding UI packages to this plugin's published dependencies.

cp -R test/hbConfig test/hbConfig.local
$EDITOR test/hbConfig.local/config.json
npm install --prefix ./test/hbConfig.local homebridge@^2.0.0
npm install --prefix ./test/hbConfig.local homebridge-config-ui-x@latest
npm install --prefix ./test/hbConfig.local .
./test/hbConfig.local/node_modules/.bin/hb-service run -U ./test/hbConfig.local -P ./test/hbConfig.local/node_modules --strict-plugin-resolution --stdout

Then open http://localhost:8581. This supervised UI test mode supports UI-managed restart paths, child bridge controls, logs, accessories, and the plugin config form.

Never put real SHC credentials in test/hbConfig/config.json; it is the committed template. test/hbConfig.local/ is ignored by git and is the place for hardware credentials, pairing data, and cached accessories. The committed smoke-test bridge is named Xcomfort SHC Test; update test/hbConfig.local/config.json manually if you already copied the template.

The hb-service run command looks for homebridge in the same node_modules directory as homebridge-config-ui-x before falling back to a global install. The local-profile install above is preferred for development, but a global Homebridge/Homebridge UI install can also be used for manual testing if that matches your production setup.

For a faster CLI-only smoke test without Homebridge UI:

npx homebridge -D -U ./test/hbConfig.local -P . --strict-plugin-resolution

Homebridge UI v5 does not start its web server just because the config platform is present in config.json. If you only need to inspect the UI while running Homebridge manually, start the standalone UI server in a second terminal:

node ./test/hbConfig.local/node_modules/homebridge-config-ui-x/dist/bin/standalone.js -U ./test/hbConfig.local -P ./test/hbConfig.local/node_modules -I

In this two-terminal standalone UI setup, the UI is not supervising the Homebridge process. UI features that require Homebridge service IPC, such as restart buttons, child bridge restart controls, and Matter monitoring, may report that the Homebridge service is unavailable.

Use a child bridge for production installs when possible. This keeps Homebridge itself available if a plugin-specific SHC connection issue occurs.

Known Limitations

• The plugin depends on xcomfort-shc-api, which is a CommonJS library last published several years ago. The dependency is isolated behind an adapter so it can be replaced later without changing accessory code.
• Xcomfort dimmers can emit many brightness commands while dragging the Home app slider. The plugin clamps and coalesces rapid brightness updates before sending them to the SHC, then reports SHC failures back to HomeKit. Very fast slider movement may still be constrained by the SHC.
• Shutter actuators are discovered but not exposed yet. HomeKit supports window coverings, but this plugin still needs a verified SHC command/value mapping for ShutterActuator before enabling control.
• Matter-specific accessory registration is not implemented yet. The plugin is safe to run on Homebridge 2 with Matter enabled.

Credits

This project builds on the earlier open source work in moritzw1/homebridge-xcomfort.

The SHC communication layer currently uses oanylund/xcomfort-shc-api.