Skip to Content

Sort out who is responsible before KNXD goes anywhere near the bus

roles before values
KNXD Guide · Part 1

Sort out who is responsible before KNXD goes anywhere near the bus

You know the bus and you have used ETS. What this series adds is the piece in between: a daemon that translates between the IP side and the KNX side, run in Home Assistant as an Add-on. This first part installs nothing at all. It separates the four roles, puts the four responsibility stations in order, and then works through the eight-row safety preflight that decides whether an installation may begin — which, on the pinned sources this series is built from, it currently may not.

4 roles
Home Assistant, ETS, KNXD and the KNX device network — and the two pairs that get swapped
8 checks
The preflight that has to be classified before the repository is even added
1 blocked row
Source and version stays Unknown while no approved artifact digest exists
The four roles

Four names, and the two pairs that keep getting swapped

Nothing in this part needs hardware, an ETS project, a network parameter or a single address. This first section is about ten minutes of reading, and it changes nothing on any system. What it buys you is that later chapters can say KNX is the device communication path, ETS is the project planning tool and KNXD is the translation desk without you having to guess which one is meant.

The source guide hangs all four roles off one image: a building with a service counter. Everything downstream of that counter is equipment you already understand.

Formal termThink of it asWhat this part does with it
Home Assistant The control desk. It is where somebody asks for something to happen A familiar way in, but no integration and no entity is set up here
ETS The building drawings and the configuration tool. It records what rooms and equipment are in the building, and how the project was planned Recognize the role only. Do not open, download or modify any project
KNXD, the daemon — managed in Home Assistant by the KNXD Add-on The translation counter. It translates between the two sides and is responsible for handing the message to the correct one On the Add-on path this guide describes, all you need is that KNXD is neither a device nor ETS
The KNX device network, usually called the KNX bus The communication path the devices themselves use Used here only to mark where the safety boundary sits. Nothing is connected and nothing is tested

A daemon, if the word is new to you from the Linux side, is simply a program that runs continuously and waits for work. In the counter image it is the member of staff sitting at the translation desk. Staff being in place says nothing about the line to the rest of the building.

In plain terms

Think of a hotel front desk with an interpreter behind it. A guest asks for something in one language; the interpreter takes the request and telephones it through to the kitchen in another. Home Assistant is the guest at the desk. KNXD is the interpreter. The kitchen is the bus. The interpreter being at her desk, headset on, is not evidence that the phone line to the kitchen is up, and it is certainly not evidence that anybody has started cooking.

Two of those swaps come up on nearly every first read, and a third mistake — an evidence one rather than a naming one — comes up just as often. All three are worth saying out loud, because each sends you looking for a fault in the wrong component.

Said on site“ETS is the Home Assistant integration for KNX.” — It is not. ETS is the planning and setting tool for the KNX project. The integration is a different role, living inside Home Assistant.
Said on site“KNXD is the KNX device on the network.” — It is not. KNXD stays at the translation desk. The device network is downstream of it.
Said on site“It says Running, so the bus is up.” — That conclusion has to stop at the process layer. Bus status is still unconfirmed.
The role gets put in the wrong placePut it back like this
ETS is treated as a Home Assistant integration Separate the two. ETS plans and sets up the KNX project; an integration is another role inside Home Assistant
KNXD is treated as a KNX device Move KNXD back to the translation desk. The device network stays downstream of it
A Running state is read as a bus connection Limit the conclusion to process status. Bus status stays unconfirmed
“I need live-environment information before I can do this” Stop collecting. This part needs role names and nothing else — no hostname, no address, no identifier
The written exercise, if you want the version that actually sticks: take a sheet of paper, draw four boxes labeled Home Assistant, ETS, KNXD and KNX device network, and write a plain-language description of the role into each. Then say the whole thing in four sentences out loud. If you can get through all four without naming a single IP address, individual address or setting, you are done with this section.
The responsibility path

Four stations, and what a line between them means

Roles sorted, the next question is order. The guide uses four responsibility points, and one of them is not in the list from the previous section: the KNX interface, the gateway on the device side. Home Assistant, KNXD, the KNX interface, the KNX bus. That is the sequence, and it is a sequence of responsibilities, not of connections.

flowchart LR
  subgraph P["Off this path: project planning"]
    direction LR
    ETS["ETS
records what the project is
and how it was planned"]
  end
  subgraph R["One outbound request, in order of responsibility"]
    direction LR
    HA["Home Assistant
the control desk
where the request starts"] --> KD["KNXD
the translation desk
between the two sides"]
    KD --> IF["KNX interface
the gate to the
device network"]
    IF --> BUS["KNX bus
the device
communication path"]
  end
Four stations, one directionThe upper lane is the request path, four stations wide. ETS sits by itself in the lower lane because it is not a station on that path at all. Each arrow marks the next point of responsibility for one outbound request — it is not evidence that any link is live, and the drawing deliberately shows this one direction of KNX data only, so do not read other directions out of it.

The reading rule matters more than the picture. A line means responsibility for one delivery request passes to the next station. It does not mean live data has passed. And because the drawing shows one direction only, it cannot be used to infer anything about the other directions KNX data travels in.

Why the KNX interface gets a station of its own. KNXD's responsibility is a process one; the interface's is a handover on the device side. Collapse them into a single box and the first thing that happens, the first time something breaks, is that a process state gets read as hardware or bus state. Keep them as two compartments: the translation desk, and the gate to the equipment.

Walking the four stations

This is an identification exercise on a drawing, not a wiring procedure. At each stop the question is who is responsible here — never what value goes in this field.

  1. Station 1

    Home Assistant

    The request starts here. All that establishes is where it started. Everything downstream is still unknown, and saying so out loud is the point of the exercise.

  2. Station 2

    KNXD

    The translator in the middle. Even when the process layer has a known state, that state declares nothing about the interface and nothing about the bus.

  3. Station 3

    The KNX interface

    The gate to the device network, responsible for the handover between KNXD and the device side. An interface name existing in a configuration is not evidence that the hardware behind it is ready.

  4. Station 4

    The KNX bus

    The device communication path, and the boundary this tutorial does not cross. The state of the previous three stations cannot establish the state of this one.

If you are drawing this out, put two boxes under each station: what can this station prove? and what can this station not prove? Leave the connection details off the drawing entirely — no IP, no address, no port, and no device data such as a device path, a serial number or a credential. None of those values is a prerequisite for understanding the hierarchy, and writing them down is how they end up in a screenshot later.

Write one sentence under the finished drawing: “Responsibility path, not evidence of success.” It is a small thing, and it is the sentence that stops a green status badge from being read as a working bus six months from now.
What a running process proves

The claim has to stop at the layer that produced it

This is the habit the whole series is built on, so it is worth stating in its blunt form. Evidence that one station exists, or is running, proves nothing about the next station. A running KNXD process establishes process-layer status. It does not establish that the KNX interface is available, and it is a long way from establishing that the bus is operational.

flowchart TD
  A["The KNXD Add-on shows a running state"] --> B["Established: the process layer, and no further"]
  B -.-> C["Not established: the KNX interface is available"]
  C -.-> D["Not established: the KNX bus is operational"]
  D -.-> E["Not established: any device received anything"]
Where the claim stopsOnly the top link is solid, because it is the only step the evidence actually carries. The three dotted hops below it are inferences the pinned sources refuse to make, and each one has to be confirmed separately at its own layer.
In plain terms

The van is parked outside the building at eight in the morning. That proves the van arrived. It does not prove anybody has been let into the riser cupboard, it does not prove the cupboard has the panel you were told about, and it certainly does not prove a single fitting has been switched. Four separate facts, four separate confirmations, and only the first one has happened.

The same discipline applies to the words you will meet in the Add-on's own material, which are easy to over-read.

What you haveWhat it establishesWhat it does not establish
The Add-on-managed configuration sheet — formally a managed INI file. The template shipped with Add-on 0.6.1 carries main, TCP-server and configured-interface sections That such a template exists, with those sections and placeholder content in it It is not a configuration generated or applied for any particular host
A listener — the counter being open and waiting to be asked Observation of the waiting layer, if that state exists Nothing downstream. It cannot prove the bus
An endpoint — the service's entrance address That endpoint-related wording appears in the source That the entrance is reachable from any environment
The pinned service script that starts the daemon The process responsibility: a daemon called from a generated configuration file It is not live-environment evidence that the procedure ran, that an endpoint is reachable, or that a bus is connected

Those two pinned files are worth knowing by name, because later parts keep coming back to them:

knxd/rootfs/etc/knxd.ini — the managed INI template, placeholder content, not a host's configuration
knxd/rootfs/etc/s6-overlay/s6-rc.d/svc-knxd/run — the service script the process responsibility is read from

Classifying a symptom before you chase it

When something does not look right, start from the responsibility layer closest to the symptom instead of guessing at the whole path. Four starting points cover most of it.

What you can seeWhich layer it belongs to
The Add-on management screen is not visible Home Assistant management, first. Do not read anything into KNXD from it
The KNXD process has no known state The KNXD process layer. No inference to the interface or the bus
The device gate has no status The KNX interface layer
It is unclear whether a device received the message The KNX bus and device layer — which is outside this part. Do not try to verify it by controlling physical equipment
Installation, process, connection and entity are four different levels. The question people ask first is whether KNX entities appear in Home Assistant once the KNXD Add-on is installed. The pinned sources carry no evidence for that, and this guide does not draw the inference. Each of the four has to be confirmed on its own terms, in its own layer.
The eight checks

Eight rows, marked Met, Not met or Unknown

Now the part that has consequences. Before the repository is added, before anything is installed and long before a value is typed anywhere, there is a preflight of eight checks. It takes about fifteen minutes, it changes nothing on the system, and it produces exactly one of two verdicts: you may read on into the lifecycle chapter, or stop and go and get the missing evidence first.

In plain terms

Nobody starts a commissioning visit by energizing the client's board to see what happens. You confirm who authorized the visit, that there is a way to put everything back as you found it, and where the stop point is — and only then do you touch anything. The preflight is that conversation, written down, for a piece of software that is about to sit between a control desk and a live building.

Build the checklist so it holds no live values

Eight rows. Each row gets one of three marks — Met, Not met or Unknown — plus a short description that contains no live values. “Administrative permissions: Met.” “Network planning: Unknown.” That is the whole vocabulary.

Installation type — records Supports Add-on management or Pending confirmation, never the host
Permissions — records whether the role can manage the Add-on, never the account or the login
Backup — records whether time range and coverage were verified, with no file names attached
Interface and network — record the type of scheme and whether the responsible person confirmed it, and no endpoint or identifying value
Do not invent an abbreviation that only looks anonymous. A shortened hostname, the last octet of an address, “the usual gateway” — anything that can be traced back to the environment is a live value, whatever it has been shortened to. The mark is Met, Not met or Unknown, and the description carries no value at all.

The eight, in order

  1. Check 1

    Confirm the Home Assistant installation type

    The only thing being decided is whether this environment offers an Add-on management interface. If you are unsure, or the screen in front of you does not look like the one described, mark it Unknown and stop. Do not work around it by another host method.

  2. Check 2

    Confirm administrative rights

    An authorized administrator verifies by hand that the Add-on can be installed, started and stopped. If the permissions are unclear, stop. Do not borrow a credential and do not share one.

  3. Check 3

    Confirm the backup, or the recovery point

    Verify by hand the timing of the Home Assistant backup, its coverage, and who is responsible for a restore. Without a backup whose scope is understood, the installation does not proceed. Note the scope, not the file name.

  4. Check 4

    Check the source and the version

    The heaviest row of the eight, and the one the next section is entirely about. It is not enough to check a version number: the row wants the repository identity, the exact commit the source lock is fixed at, the version boundary, and an approved artifact digest with a source-to-build attestation tying that digest to that commit.

  5. Check 5

    Confirm the interface category

    Only the responsible person picks a category, and the category is as far as it goes: USB, serial, network, or undecided. Do not select a driver at this stage, and leave the device, endpoint and KNX-address fields empty.

  6. Check 6

    Confirm the isolation plan

    Record only whether each of these is in place: a non-production Home Assistant test instance, no KNX, USB or device mapping, a physically disconnected bus, limited network exposure, backup and restore roles assigned, and an authorized administrator present. If any of that is unknown, stop before adding the repository and before installing. Do not scan the network, do not test an endpoint and do not log an IP address in order to fill in the form.

  7. Check 7

    Write down the stop conditions

    At a minimum: version inconsistencies, an unclear backup, identifying values appearing where they should not, an unexpected interface connection, unexpected program behavior, and any physical equipment reaction whatsoever.

  8. Check 8

    Write down the restore decision

    Distinguish Stop the Add-on from Restore the Home Assistant backup. Name who makes that call and what scope of change each one covers. Stopping is not restoring, and the moment to work out the difference is not the moment you need it.

flowchart LR
  R1["1 Installation type"] --> G{"Every row
marked Met?"}
  R2["2 Administrative rights"] --> G
  R3["3 Backup or recovery point"] --> G
  R4["4 Source and version"] --> G
  R5["5 Interface category"] --> G
  R6["6 Isolation plan"] --> G
  R7["7 Stop conditions"] --> G
  R8["8 Restore decision"] --> G
  G -->|"any Unknown"| S["Stop. Do not add the repository
and do not install
to find the answer"]
  G -->|"all eight Met"| C4["Read on into the
lifecycle chapter"]
One gate, eight ways to fail itAll eight rows feed the same decision, and a single Unknown or Not met on any of them sends you out of the top branch to Stop. Row 4 is the one that decides it today, for the reason the next section sets out.
The verdict is per-row, and the strictest row wins. Only when all eight are marked Met does the lifecycle chapter open. If any row reads Unknown or Not met, stop — and in particular, do not add the repository or attempt an installation in order to find out what the answer would have been.
The row that cannot pass

Row 4, and why this guide stops short of installing

Check 4 is where the honest answer is uncomfortable, so here it is in full. The source lock behind this material is precise:

da-anda/hass-io-addons — the expected repository identity, the designated software library
60d4a702e2011e75c90a0f1012dfbd916eb24ce0 — the commit the site's source lock is fixed at, the exact source revision
Add-on 0.6.1 — the source version boundary everything on this site is bounded by

That names the source. It does not name the thing you would actually install. Between a commit in a repository and an image landing on a Home Assistant machine there is a build, and the build has to be tied back to the source by two further pieces of evidence: an approved artifact or image digest, which is the fingerprint of the sealed box, and a source-to-build attestation, which is the paperwork tying that fingerprint to that exact commit.

Store version text cannot stand in for either — not for the immutable artifact digest and not for the attestation. The store showing 0.6.1 does not complete the proof — it is a label, and a label does not establish which source a build came from. This site currently has no approved digest. Row 4 is therefore recorded as Unknown, and the installation stays blocked.

In plain terms

A carton arrives with “0.6.1” written on the side in marker pen. The marker pen was applied by whoever packed it, and it tells you what they meant to put in. The seal number printed on the tamper strip, matched against the number on the packing note that came from the factory, tells you what is actually in there and where it was made. This guide has the marker pen. It does not have the seal number, so the carton stays unopened.

flowchart TD
  A["Repository identity
da-anda/hass-io-addons"] --> B["Source lock at one commit
60d4a702e2011e75c90a0f1012dfbd916eb24ce0"]
  B --> C["Source version boundary
Add-on 0.6.1"]
  C --> D{"Approved digest, attested
against that commit?"}
  D -->|"yes"| E["Row 4 could read Met"]
  D -->|"none approved on this site"| F["Row 4 stays Unknown.
Installation stays blocked"]
  S["Store version text
reading 0.6.1"] -.-> F
Where the chain from source to installed image breaksThe three boxes stacked down the left — repository, commit, version boundary — are what the pinned source establishes. The gate underneath them is what it cannot: the yes branch on the left is hypothetical, and the branch actually taken today is the one on the right. The dotted edge comes in from the store version text and lands on that same blocked box, never on the Met branch.
What this means in practice. You can read on into the lifecycle chapter and follow its conditional reasoning. You cannot perform lifecycle actions — no repository added, no installation, no start. That is not caution for its own sake: the artifact that would run between a control desk and a building's lighting, blinds and HVAC has not been tied back to the source this guide describes.

What the pinned files support, and what they do not

Three source chains sit behind this part. They are separate chains, and stacking them does not produce a compatibility claim or a deployment claim.

Pinned fileWhat it supportsWhat it does not support
knxd/config.yaml, at the pinned Add-on 0.6.1 commit The declared version, nine options, the interface enumeration and the shapes of the fields Where a control sits in the Home Assistant interface you are looking at, and the state of any local interface, network endpoint or KNX bus
knxd/build.yaml That KNXD Add-on 0.6.1 selects upstream version KNXD 0.14.72 Any statement about what was built, shipped or installed anywhere
homeassistant/components/knx/manifest.json, at Home Assistant Core 2025.1.0 The integration domain, its file targets and its declared dependencies Compatibility with the Add-on, or that any deployment works. It is a separate source chain
A pinned config.yaml cannot prove the build source of a store image. That single sentence is the reason the preflight reviews the source version, the artifact to be installed, and the classification as three separate things rather than one. Detailed options, INI content and driver choice are all later chapters, and none of them belongs in a preflight.
Masking, stopping, restoring

What never gets written down, and what happens when it stalls

Two categories of data stay out of every note, screenshot, chat message and issue you produce while working through this material. The first is anything that identifies an environment. The second is anything that identifies a device or a secret.

Environment-identifying

Hostnames, IP addresses, KNX individual addresses and group addresses. When one of these would go in a field, write masked or unknown instead.

Device and secret

USB serial numbers, device paths, accounts, passwords, tokens and certificates. Same rule, same two words. None of them is a prerequisite for anything in this part.

The reason the rule extends to something as harmless-looking as a backup file name is that names carry clues — a household name, a site name, a host. “Timing and coverage checked” is the entire record the checklist needs.

What this part does not do, at all

This is the ordering constraint that the rest of the series depends on, so it is worth reading as a list rather than as a paragraph.

  • No KNX telegram is sent and no group write is performed.
  • No group read either — reading is not a safe substitute here.
  • No ETS programming, and no download that writes an engineering design to devices.
  • No physical control of any equipment.
  • No check that needs wiring, powering on a device, or testing an equipment response. Anything of that shape is outside this part.
  • No network scanning, endpoint testing or IP logging carried out in order to complete a form.
Even the Add-on itself stays untouched. Do not start it to confirm the flow chart. A single process state cannot confirm a four-station path, so there is nothing to be gained, and understanding the diagram is an offline task. The same goes for the roles exercise in the first section: it is reading, not operating.

When the preflight gets stuck

Five stalls come up repeatedly. In every one of them the correct move is to stop and get the evidence, not to install something to find out.

  1. 1

    Nobody is sure of the installation type

    Ask a Home Assistant administrator for one thing only: whether the environment has Add-on management capability. Do not ask for a system screen and do not ask for host information.

  2. 2

    The backup cannot be found

    Stop everything downstream. Create and check the backup first, following the interface of the Home Assistant version actually in front of you — this guide does not guess at button positions in an interface it has not pinned.

  3. 3

    The source or version does not match

    Keep the row marked Not met and stop. Settings declared for 0.6.1 do not get applied to another version because they look similar.

  4. 4

    Somebody asks you for connection information

    Refuse the copy and answer with a category instead — “Network type, pending approval” is a complete answer. If the work genuinely cannot continue without real values, that is the end of this part, not a reason to hand them over.

  5. 5

    The stopping method is unclear

    Read the stop and restore material first, have the manager confirm who holds that responsibility, and then run the preflight again from the top.

The two stop conditions that end this part immediately are worth separating from the rest: a usable backup cannot be created or confirmed, and the task requires disclosure of a host, an address, a USB serial number, a credential or a device path. Either one, and you stop where you are.

Checking your own work

No screenshots and no logs are needed to finish this part. Five statements, and each of them should be true before you go further.

  • You can name Home Assistant, KNXD, the KNX interface and the KNX bus in order, and say what each one is responsible for.
  • You treat a connecting line as a handover of responsibility, not as evidence of live status.
  • You know that KNXD process-layer status cannot establish results for the interface or the bus.
  • All eight preflight rows are classified, with the source-and-version row left Unknown in the absence of an approved digest.
  • You have not filled in a connection value, started a service, operated ETS, sent a message or controlled any equipment.
Passing the preflight is a reading permit, not a readiness certificate. All it says is that you may work through the next chapter's conditional reasoning without connecting to the bus. It demonstrates nothing about ETS, nothing about the Home Assistant KNX integration, nothing about group operations and nothing about the state of any physical equipment. The pinned sources support only the documented scope; none of this represents validation of any local environment, hardware, network or KNX bus.
Questions people ask

The ones that come up on every first read

Are KNX and KNXD the same thing?
No. KNX is the device communication network. KNXD is the translator sitting in the middle of the path. The names are three characters apart and the responsibilities are not related, which is exactly why the four-role exercise comes before anything else.
Is ETS a Home Assistant Add-on?
No. In this guide ETS appears only as the planning and setting tool for the KNX project. No ETS operation is provided here, and no project should be opened, downloaded or modified while working through this part.
Will KNX entities appear once the KNXD Add-on is installed?
The pinned sources carry no evidence for that, and this guide does not draw the inference. Installation, process, connection and entity sit at four different levels, and each has to be confirmed separately at its own level.
Why is there no setting at all in this part?
Because the task is to get the roles right first. Fill in values before the role diagram is correct and two things follow: problems get attributed to the wrong component, and the safety boundary gets crossed while you are looking for somewhere to put a number.
Does a connecting line in the diagram mean a message has been sent?
No. The reading rule is fixed: a line marks the next responsibility point for one outbound request. It is not evidence of live transmission, and because the drawing shows a single direction it cannot be used to infer the other directions KNX data travels in.
Will this part tell me whether to use USB or another interface?
No. This part keeps KNX interface as a responsibility point and nothing more. Selection and inspection are handled in later chapters, and even in the preflight the furthest you go is a category — USB, serial, network or undecided — chosen by the responsible person.
Can I confirm the flow chart by launching the Add-on?
It is neither necessary nor possible. One process state cannot confirm a four-station path. Understanding the diagram is an offline task, and lifecycle actions should not be performed in order to check a drawing.
Why can I not even write down the backup's file name?
A backup name can carry host or household clues. Recording “timing and coverage checked” is enough to complete the row, and it is the only thing the checklist asks for.
Do I need IP addresses to do the network planning row?
No. That row confirms only whether an approved isolation plan exists. The actual values never enter the tutorial record, and going out to collect them — by scanning or by testing an endpoint — is itself one of the things this part prohibits.
Can the default interface just be used as it comes?
No inference about field applicability can be drawn from the source. The interface type has to be confirmed separately by the responsible person, on the basis of the actual hardware and the security plan.
If every check passes, is KNX ready?
No. It means only that you may enter the Add-on lifecycle exercise without connecting to the bus. It demonstrates nothing about ETS, the Home Assistant KNX integration, group operations or the state of any physical equipment.
Where does the version evidence in this part come from?
Two pinned chains. knxd/build.yaml at the pinned Add-on commit shows that KNXD Add-on 0.6.1 selects upstream version KNXD 0.14.72. Separately, the KNX integration metadata for Home Assistant Core 2025.1.0 — homeassistant/components/knx/manifest.json — identifies the integration domain, its file targets and its declared dependencies. They are separate chains, and putting them side by side does not prove compatibility or deployment.
Next

Where to go from here

part two of nine

The roles are sorted. The gates come next.

Part 2 stays on the same side of the boundary and works through the Add-on lifecycle gates, what a serial interface is and is not on this path, and how a driver gets chosen — still without a telegram going anywhere.

Open the full guide

Part 1 of the WoowTech KNXD Complete Tutorial series on the Apporo blog.

Adapted from the WoowTech KNXD complete tutorial, produced by WoowTech and republished by Apporo.

Versions and claims are bounded by the pinned sources. Publication does not represent validation of any live site, hardware, network or KNX bus, and is not an authorization to operate KNX, ETS, Home Assistant, group objects or physical control.

Light · Air · Water · Control · apporo

in KNXD
The last two forms: a change record, and a card for the day it goes wrong