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:
- walk each device's objects;
- resolve each object to the group address it sends or listens to, from the device file;
- group related objects into a cluster, by channel where the project records one, otherwise one object per cluster;
- 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, plusoperation_mode_state_addresswhere the room has aVorgabe 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.001Stellgröß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. TheSollwertverschiebungandSoll-Temperatur aktuelladdresses 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:
- Exclusions win over everything. An excluded address never produces an entity and is not counted as unmapped.
- An explicit
platformoverrides the heuristic. Only theswitchandlightpromotion is offered; cover, sensor, binary_sensor and climate are structural. - An explicit
nameordevice_classoverrides the derived value. For aclimateentity, key the override by its operation-mode command address;platformanddevice_classdo not apply, butnameandmergedo. mergeadds the listed addresses to the entity's extra addresses. On aclimateentity, 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.
Related¶
- Generate the Home Assistant config: the task, step by step.
- ha.toml: every override key.
- Server commands:
bussard ha-configand its flags. - MCP tools: the Home Assistant tier that writes this YAML for Home Assistant.