Skip to content

Home Assistant

How bussard ha-config turns your project into Home Assistant KNX integration YAML: which entities it derives, how your ha.toml overrides apply, and how to check the result. The steps to generate and install the config are on Generate the Home Assistant config.

The output

bussard ha-config prints a complete knx: document with a generated-by header and a summary footer. Example output:

# generated by bussard ha-config — do not hand-edit; use ha.toml overrides
knx:
  switch:
  - name: Kitchen Light Switch
    address: 0/0/6
    state_address: 0/0/7
  cover:
  - name: Living Room Blind
    move_long_address: 0/1/0
    move_short_address: 0/1/1
    position_address: 0/1/2
    position_state_address: 0/1/3
    device_class: blind
  climate:
  - name: Living Room Operating Mode
    temperature_address: 0/2/0
    command_value_state_address: 0/2/2
    operation_mode_address: 0/2/3
    operation_mode_state_address: 0/2/4
  sensor:
  - name: Outside Temperature
    state_address: 2/0/0
    type: temperature

# summary
# entities: 6 switch, 1 light, 3 cover, 2 climate, 9 sensor, 4 binary_sensor
# group addresses: 30/33 mapped
# unmapped: 3 group addresses (no-dpt: 1, dpt 1: 1, dpt 20: 1)
# note: climate 'Living Room': forced-mode (Zwang, DPT 20.102) recognised but unwired (no HA KNX schema key); left unmapped

The output is deterministic. Entities are sorted by platform, then name, then primary group address, and every optional field is omitted when empty, so re-running produces a minimal diff. Copy the knx: block into your Home Assistant configuration, or !include the file.

How entities are derived

bussard has devices, communication objects and group addresses; Home Assistant wants entities. Derivation works per device:

  1. walk each device's objects;
  2. resolve each object to the group address it sends or listens to, from the device file;
  3. group related objects into a cluster, by channel where the project records one, otherwise one object per cluster;
  4. emit one entity per cluster.

Roles come from the object flags:

  • an object with the W flag receives commands, so its listened address is a command address, the one Home Assistant sends to;
  • an object with the T flag transmits status, so its sent address is a state address, the one Home Assistant reads.

Mapping rules

Project shape Home Assistant entity
1.008 up/down [+ 1.007 step/stop, 5.001 position ± status] cover (move_long / move_short / position / position_state)
1.001 switch (has a W command object) switch (or light)
1.001 switch + 5.001 brightness on the same channel light with brightness_address
9.xxx value a sensor sends sensor with type per DPT sub
other numeric value (7/12/13/14/5) a sensor sends sensor with the matching type
1.xxx a sensor sends (T flag): presence, contacts, alarms binary_sensor
a per-room heating cluster anchored by a 20.102 operation-mode command climate (see Climate)

device_class is inferred from the group address or device name and the DPT sub, where it is unambiguous:

Platform Hint device_class
cover Raffstore, Jalousie, blind blind
cover Rolllade, shutter shutter
cover Markise, awning awning
binary_sensor DPT 1.005 (alarm) problem
binary_sensor DPT 1.019 window
binary_sensor name hints motion, window, door, moisture, safety

1.019 is 0 = closed, 1 = open; 1.009 is the inverse, 0 = open, 1 = close (KNX 03_07_02 Datapoint Types §3.1). Home Assistant reads a binary_sensor's "on" as open for the window, door, opening and garage_door classes, so a 1.009 contact under one of them gets invert: true (#496). A 1.019 contact needs none.

Sensor type per DPT sub:

DPT type
5.001, 5.004 percent, percentU8
7.001 pulse_2byte
7.002, 7.003, 7.004 time_period_msec, time_period_10msec, time_period_100msec
7.005, 7.006, 7.007 time_period_sec, time_period_min, time_period_hrs
7.011, 7.012, 7.013 length_mm, current, brightness
7.600 color_temperature (K)
other 7.x 2byte_unsigned
9.001, 9.002, 9.003 temperature, temperature_difference_2byte, temperature_a
9.004, 9.005, 9.006, 9.007, 9.008 illuminance, wind_speed_ms, pressure_2byte, humidity, ppm
9.009, 9.010, 9.011 air_flow, time_1, time_2
9.020, 9.021, 9.022, 9.023, 9.024 voltage, curr, power_density, kelvin_per_percent, power_2byte
9.025, 9.026, 9.027, 9.028 volume_flow, rain_amount, temperature_f, wind_speed_kmh
9.029, 9.030 absolute_humidity, concentration_ugm3
other 9.x 2byte_float
12.001 pulse_4_ucount
12.100, 12.101, 12.102 long_time_period_sec, long_time_period_min, long_time_period_hrs
12.1200, 12.1201 volume_liquid_litre, volume_m3
other 12.x 4byte_unsigned
13.001, 13.002 pulse_4byte, flow_rate_m3h
13.010, 13.011, 13.012 active_energy, apparant_energy, reactive_energy
13.013, 13.014, 13.015, 13.016 active_energy_kwh, apparant_energy_kvah, reactive_energy_kvarh, active_energy_mwh
13.100 long_delta_timesec (s)
13.1200, 13.1201 delta_volume_liquid_litre, delta_volume_m3
other 13.x 4byte_signed
14.000-14.080, 14.1200, 14.1201 the integration's name for the sub-type, e.g. 14.019 electric_current, 14.033 frequency, 14.056 power, 14.057 powerfactor, 14.068 common_temperature, 14.080 apparent_power
other 14.x 4byte_float

Every name is a row of the "Value types" table of the Home Assistant KNX integration, which sets the unit and device class from it (apparant_energy is HA's spelling). A sub-type HA does not name gets the generic type of its family, which reads the right width without a unit.

The _2byte types matter: Home Assistant's plain power and temperature types decode four bytes, so a 2-byte KNX value mapped to them reads wrong.

Only an object that publishes a value becomes a sensor: one with the T flag, or a readable one that answers a GroupValueRead. A write-only command input, such as a setpoint an actuator receives, is skipped, because a read-only sensor on it would never update.

Climate

A heating cluster is not one device. The operation mode and setpoint come from a room controller, the valve position from a heating actuator, and the room temperature often from a third device, such as a presence detector or a thermostat. Because the addresses are spread across devices, climate is the one place derivation correlates by room name instead of by device channel: it reads the names from groups.toml, strips a known German heating suffix, and groups the remainder by the room prefix.

Suffix DPT Role
Isttemperatur 9.001 room temperature
Betriebsmodus Vorgabe 20.102 operation-mode command
Betriebsmodus Vorgabe Status 20.102 operation-mode status
Betriebsmodus Zwang 20.102 forced mode
Sollwertverschiebung, Sollwertverschiebung Status 9.002 setpoint shift
Stellgröße Heizen/Kühlen 5.001 valve position
Soll-Temperatur aktuell 9.001 current target

A suffix only matches when the DPT matches too, so a plain 9.001 temperature elsewhere is never pulled into a climate cluster.

The anchor rule. A room becomes a climate entity only if it has an operation-mode command (Betriebsmodus Vorgabe, 20.102). A room with just a temperature sensor, or just a valve, is not controllable and is left to the sensor pass. This keeps stray 9.001 temperatures, and rooms like a utility room that only report a temperature, from producing empty climate entities.

Central heating. When the flow temperature steers the whole house, a room is heated or not as a unit, and there is no per-room target temperature to set. Derivation reflects that:

  • the operation mode is the control: operation_mode_address, plus operation_mode_state_address where the room has a Vorgabe Status. In Home Assistant it surfaces as preset modes: comfort means the room is heated; standby, economy and frost protection mean off;
  • the room temperature (temperature_address) and the valve position (command_value_state_address, from the 5.001 Stellgröße) are wired as read-only telemetry;
  • setpoint shift (setpoint_shift_address, setpoint_shift_state_address) and target temperature (target_temperature_state_address) are deliberately not wired, because they would invite a temperature change the central system does not honour. The Sollwertverschiebung and Soll-Temperatur aktuell addresses fall through to the sensor pass as read-only values.

If your installation does per-room setpoint control, re-enable setpoint wiring per room with a merge on the climate entity's primary address, the operation-mode command. The mapped keys match the Home Assistant KNX climate schema exactly: temperature_address, operation_mode_address, operation_mode_state_address, command_value_state_address, target_temperature_state_address, setpoint_shift_address, setpoint_shift_state_address, setpoint_shift_mode.

Forced mode (Zwang). The Betriebsmodus Zwang (20.102) address overrides the operation mode, but the Home Assistant KNX climate schema has no key for it. Rather than guess, bussard leaves it unwired, counts it in the # unmapped: dpt-20 total, and emits a # note: line naming the room.

What does not map

An address that fits no rule is never silently dropped: it is counted in the # unmapped: footer, grouped by DPT main number. Typical unmapped addresses are forced HVAC-mode datapoints (20.102 Zwang), relative dimming (3.007), date and time (10.001, 11.001), and base setpoints the project does not tie to a controllable entity. Recognised but unwired addresses, such as the climate forced mode, also get a # note: line with the reason.

Deduplication

The same address is often touched by several devices: an actuator that switches it and the push buttons that command it.

  • Actuators are derived first and claim their addresses.
  • A later sensor pass maps only addresses no actuator claimed, and any entity whose addresses are already spoken for is dropped. The result is one entity per address.
  • Colliding entity names get their primary address appended (Name (1/2/3)), so names stay unique per platform, as Home Assistant requires.

Overrides

Put an optional ha.toml in the project folder to tune the result. Its keys are on ha.toml. They apply in this order:

  1. Exclusions win over everything. An excluded address never produces an entity and is not counted as unmapped.
  2. An explicit platform overrides the heuristic. Only the switch and light promotion is offered; cover, sensor, binary_sensor and climate are structural.
  3. An explicit name or device_class overrides the derived value. For a climate entity, key the override by its operation-mode command address; platform and device_class do not apply, but name and merge do.
  4. merge adds the listed addresses to the entity's extra addresses. On a climate entity, a merged address fills the first free state slot in this order: temperature_address, target_temperature_state_address, operation_mode_state_address, setpoint_shift_state_address, command_value_state_address. Command slots are never merge targets.

Quality check

Run bussard ha-config and read the footer: the entity counts and the # unmapped: line tell you how much of the project mapped and what remains. Spot-check a few entities, then adjust with ha.toml.

On one installation of 424 group addresses, 393 map (39 switch, 5 light, 26 cover, 10 climate, 135 sensor, 60 binary_sensor) and 31 are reported as unmapped. Ten of those are the 20.102 Zwang forced-mode addresses, one per heating room, each named in a # note: line; the rest are relative dimming (3.007), date and time, and a few one-offs.