A running daemon is a statement about a process, not about a bus

The Add-on details page in Home Assistant can tell you a small number of things, and it is worth being precise about which ones. It can tell you the Add-on is installed. It can tell you the process is running or stopped. It can tell you the instance has been removed. And, in a future approved exercise, a briefly viewed log can tell you that a de-identified category of message appeared.

That is the whole list. None of it establishes a result for the KNX interface, the bus, ETS, the Home Assistant KNX integration, group operations, or physical control. A running Add-on does not prove the bus is connected.

flowchart LR
  subgraph OUT["Layers this part cannot reach"]
    direction LR
    O1["A driver is loaded"] --> O2["An interface answers"] --> O3["The KNX bus carries telegrams"] --> O4["A luminaire actually switches"]
  end
  subgraph IN["What the Add-on page can show"]
    direction LR
    I1["installed"] --> I2["running"] --> I3["stopped"] --> I4["removed"]
  end

Cross-layer inference is the mistake this part exists to prevent. Program state, driver, interface, listener and bus are separate evidence layers, and reading one of them upward into another is how an installer ends up telling a client the system is live when nothing has touched the bus at all.

The isolated-test gate, checked one item at a time

Before the repository is added and before the Add-on is installed, the administrator present verifies each of six conditions. Only a non-production Home Assistant test instance is eligible to continue. These are checked individually, not waved through as a group.

• A non-production test instance. Not a system providing service in a home, an office or a customer site. If it is doing a job for somebody right now, it is out of scope.
• No device paths mapped. The system has no KNX, USB or other device paths mapped into it.
• Interface and bus disconnected. The physical interface and the bus stay disconnected, and there is no alternative connection by which the test program could reach a field device.
• Bounded network scope. Any services that may be enabled stay inside the bounded network test scope the administrator approved, and cannot be reached inadvertently from a general local network or from the public internet.
• Backups and roles reviewed first. Pre-installation Home Assistant backups, a minimal recovery method, and the roles responsible for stopping, removing or restoring have all been reviewed before anything begins.
• An administrator present throughout. Someone with Add-on management rights stays present for the whole process and can stop immediately if anything behaves unexpectedly.

If any one of those cannot be proven, stop before adding the repository and before installing. A Home Assistant instance in production use cannot install Add-ons that have not passed this gate — there is no reduced version of it for a system that is only mostly idle.

Everything from here on is performed manually, step by step, by the administrator present. No shells, no APIs, no scripts, no automation. That constraint is not fussiness about tooling; it is what makes each step individually stoppable.

Eight fields, and the ones that must stay out of them

A privacy-safe change record is established before operation, not written up afterwards. It splits in two: only identifiers with no environmental clues go into public or educational records, while the private approval, the precise operating scope and the six pieces of isolation evidence stay in access-controlled records. If one of the eight fields is missing, the work does not continue.

That last field is worth spelling out, because it is the one people fill in from memory and get wrong. None of the following belongs in the record:

A pinned commit and a store version answer different questions

This series is built on a source lock. It pins da-anda/hass-io-addons at commit 60d4a702e2011e75c90a0f1012dfbd916eb24ce0, which declares Add-on version 0.6.1. That is a real and useful thing to have, and it proves exactly one thing: the content of the source at that commit.

It does not prove that the image Home Assistant would fetch and install was built from that commit. The 0.6.1 the store displays is mutable text on a page. It is not build evidence, and it cannot be promoted into build evidence by being read carefully.

Three conditions turn a mutable display into immutable build evidence, and all three have to hold at once.

Put the three gates in order and the decision has a fixed shape. It is not a scoring exercise where a strong pass on one gate compensates for a gap in another.

flowchart TD
  A["A lifecycle action is proposed:
add repository, install, start,
restart, stop, remove, restore"] --> B{"All six isolation
conditions proven?"}
  B -->|"no, or unknown"| S["Stop before the change.
Record it as blocked"]
  B -->|"yes"| C{"Privacy-safe approval
record complete?"}
  C -->|"a field is missing"| S
  C -->|"yes"| D{"Artifact digest and
source-to-build attestation
approved and verifiable?"}
  D -->|"no. This site has neither"| S
  D -->|"yes"| E{"Administrator present
for the whole action?"}
  E -->|"no"| S
  E -->|"yes"| F["One approved action,
by hand, confirmed step by step"]

What each lifecycle step would look like, and where it stops

What follows describes interface landmarks, the observable state you would expect, and the point at which you stop — deliberately written to survive version differences in the Home Assistant interface. An administrator may perform these manually, using the then-current Home Assistant documentation, and only once the controlled records satisfy every gate above. Seven actions, in this order.

1. 1

   Add the repository

   With the approval record and the artifact digest evidence both valid, find the Add-on management landmark from the Home Assistant configuration area, then follow the official documentation into repository management. Once added, accept only the list of approved repository identities. Stop if the items differ from what was approved, if the source is unrecognizable, or if the interface makes you guess. This site currently lacks an approved digest, so do not execute it.

2. 2

   Install, manually, into a clean instance

   With both proofs still valid, find the KNXD details page for the approved source in the add-on store. After installation the page should let you distinguish the installed state from the lifecycle control area. Do not read the store version as a statement about which commit you got. If it starts automatically, or if it asks for real KNX values, stop immediately. This site currently lacks an approved digest, so do not execute it.

3. 3

   Start, once

   While both proofs remain valid, the administrator present may use the start control on the details page once. The expected observation is narrow: the Add-on process moves from a stopped state to a running state, in whatever wording that version uses. That is the entire observation, and it does not prove the bus is operational. This site currently lacks an approved digest, so do not perform this step.

4. 4

   Restart, once

   Use the restart control once, and only while both proofs remain valid and you can explain the previous state. Expect a brief transition and a return to the running state. If the state is unclear afterwards, stop rather than retry — a second restart to see whether it looks better the second time is a change made without an explanation. This site currently lacks an approved digest, so do not perform this step.

5. 5

   Stop

   Use the stop control when the controlled approval scope includes stopping and the preceding evidence is still valid. The expected state is no longer running, but stopped. Do not repeat the operation because the screen has not changed — stay isolated and fall back to the stop-and-restore guidance instead. No operation has been performed on this site, so there is nothing here to stop.

6. 6

   Remove

   Only when the approval scope includes removal and the Add-on has already been stopped, identify the removal or uninstall action from the details page. Expect the installed state and the lifecycle controls for that instance to disappear, or the page to return to an installable state. That does not prove Home Assistant as a whole has been restored. Nothing has been installed through this site, so there is nothing here to remove.

7. 7

   Restore

   Only when backup coverage is fully consistent with the controlled approval, the administrator selects the pre-verified recovery point from the Home Assistant backup management landmark, reviews the scope of impact first, and then confirms. Expect to return only to the state that backup covers. Recheck the Add-ons and any other affected items afterwards. This site currently has no lifecycle changes that need restoring.

Stop, remove, restore: take the smallest response that fits

When something does need undoing, the instinct to reach for the backup first is the expensive one. Narrow the scope of the change before you choose the response.

flowchart TD
  A["Something has to be undone"] --> B{"Did the change involve
only the Add-on?"}
  B -->|"yes"| C["Stop the Add-on"]
  C --> D["Remove the Add-on"]
  D --> E["Confirm only: process not running,
instance gone. Not the same as
Home Assistant restored"]
  B -->|"no, other changes happened"| F{"Does a pre-approved backup
cover exactly that scope?"}
  F -->|"no"| G["Stay isolated and stop.
Do not widen the restore"]
  F -->|"yes"| H["Administrator reviews backup time,
content and what else it covers,
then confirms by hand"]
  H --> I["Recheck afterwards, by hand:
Home Assistant in range, Add-on in the
expected state, no unintended effects"]

Three things about the right-hand route are worth stating on their own. The administrator checks the backup time, the content, and what other changes that backup may quietly cover, before confirming. The Home Assistant official backup and restore process is followed as documented for that version. And after restoring, it is the administrator who confirms Home Assistant is back within the expected range, that the KNXD Add-on is in the expected stopped or removed state, and that there are no unintended effects. If any result is unclear, stay isolated and stop rather than continuing.

The three failures you are most likely to hit here

What a finished pass through this section looks like

• You can state what a pinned commit proves. Source content, and nothing further. A store version does not stand in for an artifact digest with source-to-build attestation.
• You checked the six isolation conditions and the complete approval record before adding a repository or installing. The digest is missing, so no change was made.
• You can describe the observable scope of installed, running, stopped, removed and restored separately, without reading one of them into another.
• You did not connect the interface or the bus, did not send telegrams, did not perform group operations, did not perform ETS programming or downloads, and did not control physical equipment.

Next step from here: keep every KNX interface, device mapping and bus disconnected. When you need to interpret process status, interpret it as process status. Without artifact provenance, the only record you keep is the blocked one.

Classifying interface candidates without writing down a single device path

This is a paper exercise, and it takes about fifteen minutes. You are producing one thing: a candidate-classification table with no identifying information in it. You are not listing the devices a computer can see, and you are not identifying suitable hardware. Filling the sheet in completely still establishes nothing about hardware compatibility.

There is no live enumeration step in this chapter and none is provided. Do not prepare terminal commands, device lists or screenshots. Do not view real device paths and do not copy serial numbers. If existing material already contains any of that, stop transferring it and handle it under the safe log-sharing rules from the previous section.

The sheet has five columns and starts empty. Create the fields; do not fill in any environment values.

Six steps, all of them on offline paper. You do not need to touch the execution environment for any of them.

1. 1

   Write the shared conclusion at the top first

   Put it in the header, before any rows exist: this list is for candidate classification only; hardware compatibility, driver operation and bus status have not been confirmed. Writing it first means every row inherits it, rather than each row having to earn a caveat later.

2. 2

   Create neutral codenames

   When you need to distinguish between de-identified records you already hold, label them Candidate A and Candidate B in order. Do not generate a code from a path, a serial number, a model or a location — a codename that encodes any of those is still the thing it encodes.

3. 3

   Classify each record by role

   Each item goes into one of three buckets: documented fact, pending manual review, or must not be disclosed. If there is not enough content to place it, mark it unknown and leave it there.

4. 4

   Write down what is not proven

   For every candidate, mark hardware identity, driver family, usability and KNX bus status as unconfirmed. Four marks, on every row, every time.

5. 5

   Apply the stop condition

   If classifying a record would require looking at an actual path, a serial number, a host or a live device list, stop. Do not work toward the answer in small probing steps — a sequence of small lookups is the same disclosure as one large one.

6. 6

   Hand it to somebody else to review

   Deliver only the de-identified classification sheet. Ask the reviewer to confirm two things: that there is no environment-identifying information in it, and that it makes no compatibility claims.

flowchart LR
  A["One de-identified record
in front of you"] --> B["Label it Candidate A,
Candidate B, in order"]
  B --> C{"Which category
does it fall into?"}
  C --> D["Documented fact"]
  C --> E["Pending manual review"]
  C --> F["Must not be disclosed"]
  D --> G["Conclusion column, every row:
hardware suitability unproven"]
  E --> G
  F --> G

Three judgments exist in this table and no others: the source document has explained it, it needs manual review, or it is beyond this chapter. When you see that a candidate exists, the strongest thing you may write is “there is a record to classify.” Not “interface found.” Not “available.”

When the sheet starts drifting

Choosing a driver family from documentation, not from the connector

A driver family is the set of rules by which the software and the interface talk to each other. The temptation, with hardware in front of you, is to pick one from the product name, the shape of the connector or an article somebody linked to. That is exactly the inference this chapter refuses.

So there are two questions, and a candidate needs a yes to both.

The Add-on 0.6.1 schema accepts nine interface names. These are allowed values, not recommendations, and the presence of a default among them is a schema fact rather than an endorsement:

In the upstream KNXD 0.14.72 INI documentation pinned for this chapter, the driver-family terms that can be compared directly are three:

That supports terminology and documentation coverage. It supports nothing about actual hardware compatibility. A name appearing in both places makes a documented candidate for manual review, and that is the whole of what it makes.

The decision card you fill in is offline and carries no product name, device path, serial number, host, IP address or endpoint. Five fields:

• Requirement category. Only the role — something like a device-type input or an endpoint-type input. Not the make, not the model, not the value.
• Add-on name evidence. Yes, no, or unknown.
• Upstream file documentation. Yes, no, or unknown.
• Manual review status. Pending review, or stopped.
• Non-conclusion. Local hardware compatibility, driver startup and bus status have not been confirmed. This field is not optional and it does not get shortened.

Then work through it in order. Write the required role first. Check the candidate name against the pinned enumeration for Add-on 0.6.1, and if it is not there, stop rather than adjusting the name yourself. Check that upstream 0.14.72 explicitly describes a driver family of the same name; similar names do not count. Keep at most one candidate — when both documents are clear, write “documented candidate, pending manual review,” and when two candidates remain or no answer is clear, make no selection at all. Add the non-conclusion in full: hardware compatibility has not been proven, drivers have not been loaded, services have not been started, and the bus has not been contacted. Then stop at the file level and submit the card to the approval process. Do not attempt a start, and do not use live logs to favor one candidate over another.

flowchart TD
  A["A driver-family name
somebody wants to use"] --> B{"Is the name in the Add-on 0.6.1
schema enumeration?"}
  B -->|"no"| X["No selection.
Write down the documentation gap
and send it to manual review"]
  B -->|"yes"| C{"Does upstream 0.14.72
document a family with
exactly that name?"}
  C -->|"no, or only a similar name"| X
  C -->|"yes"| D{"Is exactly one
candidate left?"}
  D -->|"no, two or more"| X
  D -->|"yes"| E["Documented candidate,
pending manual review.
Hardware compatibility still unproven"]

The five arguments that will be made to you

The ones that come up on every job

Where to go from here