Setup Guide

For installation steps, see the README. This guide covers details and background.

Connection verification

Check raw TCP from any machine on your network:

echo 'i' | nc <ebusd-host> 8888
# Expected: "version: ebusd 26.x.x.x"

If nc is not available, use telnet or the HA addon log.

Expected devices

| Device | Circuit | What you get | |--------|---------|--------------| | Vaillant aroTHERM heat pump | hmu | Temperatures, pressures, energy counters, runtime, errors | | Vaillant CTLV2 heating control | ctlv2 | Zone temps, DHW, heating curve, schedules, operation modes | | Vaillant VWZ00 ventilation | vwz00 | Ventilation status, fan speeds | | Vaillant system | Broadcast | Outdoor temperature, water pressure (system-wide values) |

Register discovery

• On first connect, the integration runs find to discover all registers ebusd knows about
• Each register becomes an entity: sensor, number, select, switch, etc.
• Some registers only return data when the compressor is running (heating/DHW active). They show "unavailable" or "no data stored" when idle
• Custom registers (like room humidity ctlv2.z1RoomHumidity) are defined at runtime via --enabledefine

YAML overrides

Create config/vaillant_ebus/entities.yaml to override auto-detected metadata:

hmu.CurrentConsumedPower:
  device_class: "power"
  unit: "W"
  entity_category: "diagnostic"

Available keys: friendly_name, icon, unit, device_class, entity_category, entity_type, enabled, writable, min, max, step, options, divisor.

divisor divides the reported numeric value before it reaches Home Assistant (reported / divisor). It corrects a register whose local ebusd definition already scales the raw bus value. The unit stays as declared; for example a b516 *ElecCons* day counter documented in Wh but whose ebusd definition reports in kWh — a 1.1 kWh reading that should display as 1100 Wh — use a divisor of 0.001:

hmu.HcElecConsDay:
  divisor: 0.001

Things to know when you write overrides:

• Use the circuit name that ebusd reports on your bus. The same controller is ctlv3 with the standard ebusd configuration and ctlv2 when a local configuration renames it, so the key is ctlv3.Z2OpMode in one setup and ctlv2.Z2OpMode in the other. Changing the ebusd configuration also changes the entity unique IDs, which creates duplicate _2 entities until the old ones are removed.
• A changed options list for an entity that already exists only takes effect after a full Home Assistant restart. Reloading the integration or calling vaillant_ebus.rediscover is not enough.
• The Yield sensors of the heat pump report the environmental yield (the heat taken from the air or ground). The heat that was produced is the yield plus the electricity used, so a COP that you calculate as yield divided by electricity comes out about 1 too low.
• When you change a heating circuit setting in the myVAILLANT app, the internet gateway writes all circuit settings from its own copy. This can silently undo values that you wrote through this integration.

Reload after changes: Settings → Devices & Services → Vaillant eBUS → Reload.