Skip to content

Generate the Home Assistant config

Turn your project into the configuration of Home Assistant's KNX integration, so your lights, blinds and heating show up there with the names you gave them. For owners who run Home Assistant next to their KNX bus.

The generator reads only your project and never touches the bus.

Generate the file

Start the server with --allow-home-assistant and a [home_assistant] table in bussard.toml (MCP tools), then:

You:        Bring Home Assistant up to date with my project.
Assistant:  (calls knx_ha_plan)
            2 entities are added: Kitchen Light Switch and Living
            Room Blind. Write the file and reload the KNX integration?
You:        Yes.
Assistant:  (calls knx_ha_apply)
            Written and reloaded. The old file is backed up.

knx_ha_plan writes nothing. knx_ha_apply writes only after your yes, backs up the old file first, and reloads Home Assistant's KNX integration.

$ bussard ha-config --out ha-knx.yaml

Without --out the YAML goes to the terminal. ha-config never touches Home Assistant.

The file is a complete knx: document. The example below is illustrative and shortened:

# 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
    position_address: 0/1/2
    device_class: blind

# 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)

bussard walks each device's com objects (the inputs and outputs of a device) and makes one Home Assistant entity per channel (or per com object where your project records no channel): a switch, light, cover, climate, sensor or binary sensor. The output is sorted, so a rerun after a small change to your project gives a small diff.

Put it where Home Assistant reads it

In chat the assistant writes the file Home Assistant reads, so skip this step. At the terminal, copy the file into your Home Assistant configuration directory and include it from configuration.yaml, or paste the knx: block in directly. The header says not to hand-edit it: regenerate instead, and put your changes in ha.toml.

Check the result against your project

Read the footer first. It counts the entities per platform and the group addresses that mapped. Every address that fits no rule is counted on the # unmapped: line by DPT, the data type of the address, so nothing is dropped silently.

  • Typical unmapped addresses are relative dimming (3.007), date and time, and forced heating modes.
  • A # note: line names anything bussard recognised but could not wire, such as a room's forced heating mode.
  • Then spot-check a few entities: names, the right platform, the right device_class.

A room becomes a climate entity only when it has an operation-mode command address (DPT 20.102). For central heating, the setpoint shift and target temperature are deliberately not wired and appear as read-only sensors instead.

Tune it with ha.toml

Put an ha.toml next to your project files to change the result:

[global]
default_platform_for_switches = "switch"   # or "light"
exclude = [
  "0/0/1",   # a single group address
  "8/",      # every address under main group 8
]

[[entity]]
address = "1/0/1"
platform = "light"          # promote a derived switch to a light
name = "Kitchen ceiling"    # override the derived name
device_class = "outlet"

[[entity]]
address = "3/1/5"
merge = ["3/1/6"]           # add extra addresses to this entity

An entity is identified by its primary group address: the one Home Assistant sends to for a switch, light or cover, or reads for a sensor. For a climate entity, use its operation-mode address. To wire setpoint control on a room that does have it, merge the setpoint addresses onto that entity.

  • An excluded address produces no entity and is not counted as unmapped. Exclusions win over everything.
  • platform only switches between switch and light.
  • The file is parsed strictly: an unknown field or a duplicate address is an error, not a silent no-op.

Regenerate after every change to ha.toml and read the footer again.

Next steps