Two chapters that end in paper, with nothing plugged in

Chapter 15 takes about twenty minutes and produces a small stack of classification cards. Chapter 16 takes about twenty minutes and produces one classification ticket. Neither creates a Home Assistant entity, neither changes a group setting, and neither runs a test. That is the entire system change for this part: none.

The bottom line of Chapter 15 is that label cards are used only to distinguish the roles of a Home Assistant entity, a KNX individual address, and a KNX group address. Each card records field roles and categories. It does not record values, mappings, payloads, service calls, or control examples. The bottom line of Chapter 16 is that you classify everything before you do anything: the proposal is divided into safe, isolated-test, approval-required and never-automate work, and where a gate is incomplete you stop on paper.

You have commissioned buildings. You already know what a group address does when something writes to it, which is exactly why this part is aimed at you rather than around you. The risk here is not that you will misunderstand KNX. It is that Home Assistant hands you a second vocabulary — entities, states, service calls — that looks like it maps onto the first one, and reads as though it were describing the same wire. It is not describing the wire at all.

What you need in front of you

For Chapter 15: a few blank cards and the offline worksheet from Chapter 14. No Home Assistant material and no KNX material are required, and you should not go and fetch any. For Chapter 16: a blank classification ticket, and a description of the proposal written entirely in placeholders. No test environment is required, because no test is run.

One piece of honesty about the material, because it governs every sentence below. Chapter 15 is bounded by the pinned Home Assistant KNX documentation snapshot and by a separately locked Core manifest. Chapter 16 is bounded by the pinned KNXD 0.14.72 upstream files and the KNXD Add-on 0.6.1 files. Pinned sources support the documented scope, and nothing more. Publication is not validation of any local environment, hardware, network or KNX bus, and it is not authorization to operate anything.

Three roles that will not stand in for one another

A Home Assistant entity is a user-facing semantic object. A KNX individual address identifies a KNX device. A KNX group address is a shared communication topic defined by the KNX design. Three roles, three different jobs, and no two of them are the same kind of thing.

They can appear in the same classification system, and in a real project they do. That is what makes them easy to blur. It does not make them interchangeable fields. How an actual project associates the semantic object with the KNX design has to be determined separately by that project and its authorization evidence. This chapter records the classification only — entity role, device identity role, shared communication topic role — and records no values and no mappings at all.

flowchart TD
  C["One classification card
paper only, no values"] --> E["Entity role
a user-facing semantic
object in Home Assistant"]
  C --> I["Device identity role
a KNX individual address
identifies one KNX device"]
  C --> G["Shared topic role
a KNX group address is a
topic defined by KNX design"]
  E --> EX["Off the card:
entity id, state, service call"]
  I --> IX["Off the card:
address value, device identifier"]
  G --> GX["Off the card:
address value, payload, direction"]

There is a second habit to break, and it is the one that survives longest in people who are good at their job. A clear label is not evidence. Even when the label text is unambiguous, you cannot guess the field value, the mapping, the data direction, the type or the state from the name. In the absence of authorization evidence, the honest entry is always pending confirmation — and leaving it there is the whole skill.

Four spaces on a blank card, and nothing else on it

Draw only four spaces on each blank card. Do not imitate the settings screen of Home Assistant or of ETS, and do not lay the fields out in the order a real form uses them. A card that looks like a form invites somebody to fill it in like one, and the first thing they will reach for is a value.

At the end of the card page, write one more line, outside the four spaces:

You do not need to add examples to make the card look complete. A card with three fields answered and one honestly marked as pending is finished. A card padded out with a plausible-looking illustration is worse than an empty one, because the illustration is the part that gets copied.

The six steps

1. Step 1

   Create the purpose cards

   One general purpose per card, and one only. Avoid family names, room names, equipment names and people's names. If two purposes want to share a card, they are two cards.

2. Step 2

   Add the data semantics

   Record the type of meaning the model needs. If there is no support for it in the pinned source, the entry is to be confirmed by the source. Nobody is scored on how many blanks they filled.

3. Step 3

   Add the field-role section

   Classify as entity, device identity, or shared communication topic. Do not write any value, mapping, direction, content or format into this section. This is the section that leaks first, and it leaks because the classification feels incomplete without an example beside it.

4. Step 4

   Add the evidence-status field

   Mark the documentation concept and the Core version metadata separately. They are two different sources with two different scopes, and writing the two of them down as though they were one piece of execution evidence is precisely the error this field exists to catch.

5. Step 5

   Run a de-identification check

   Go back over the finished cards and remove identification strings, home contexts, payloads, calls, configuration structures, and any control hints. Do this as a separate pass. Things that looked harmless while you were writing them read differently when you are only looking for them.

6. Step 6

   Close the card set

   Write across the whole stack: Only for paper review; physical, integration, and bus status unknown. The stack now says what it is, to anybody who finds it on a desk six months from now without you standing next to it.

Completion check

You are done when you can distinguish the entity, the device identity, the shared communication topic and the evidence at a glance. Anything that needed a guess stays marked pending confirmation.

• You can state the three roles without reaching for an example: the entity is the user-facing record card, the individual address is the identity of a KNX device, the group address is the shared communication topic that KNX is designed around.
• You can say why they are not interchangeable, and each card carries only purpose, data semantics, field role and evidence status.
• All purposes use de-identified, general labels.
• No card carries an address value, a mapping, an identifier, a payload, a service call, a configuration structure, or a control example.
• No name is being relied on as evidence of data direction, type, or site status.
• No entity was created, and no group action, telegram transmission or device control was performed or is permitted.

Four trays, and the strictest one always wins

The four names are the safe, isolated-test, approval-required and never-automate action matrix. What follows is what each tray will hold and, more importantly, what it refuses to hold.

Two rules make the matrix work, and both of them are about how you cut up the proposal before you start sorting. Classification considers atomic actions, not proposal titles. And when a proposal contains several actions, it is split, and the strictest category among them is the one that governs.

flowchart TD
  A["One atomic action from the proposal"] --> B{"Group read or write, telegram,
ETS programming or download,
bus connection, physical control?"}
  B -->|"yes"| NA["NEVER AUTOMATE
Remove it. No gate reopens this"]
  B -->|"no"| C{"Does it touch the live or running
environment, read-only included?"}
  C -->|"yes"| AR["APPROVAL REQUIRED
Written approval, limited
scope, de-identification"]
  C -->|"no"| D{"Does it start, install, add a
repository, or reach the
execution environment?"}
  D -->|"yes"| IT["ISOLATED TEST candidate
Check every gate first"]
  D -->|"no"| SF["SAFE
Offline read-only pinned sources,
or a stub with no side effects"]

The classification ticket, and the five gates it has to check

The ticket is completely offline. It carries seven fields, and any field you cannot answer gets the same entry:

The seven steps

1. Step 1

   Write down the smallest question

   Strip out every sentence that presets a live-environment outcome. What is left should be a question you want reviewed, not a result you are expecting to confirm.

2. Step 2

   Break it into atomic actions

   Separate reading, viewing, changing, starting and sending. If an action is not clearly one of those, stop rather than guess — an action you cannot name is an action you cannot classify.

3. Step 3

   Identify the never-automate actions first

   Group reading and writing, telegram transmission, ETS programming or downloads, and physical control are not allowed. Wherever any of these appear, mark them never automate and remove them. Doing this first means the rest of the sort happens on a proposal that no longer contains them.

4. Step 4

   Classify the approval-required actions

   Every view of, or change to, the live or running environment is marked approval required, and read-only viewing is no exception. Without clear written approval, a limited scope and de-identification, this is a stop.

5. Step 5

   Check the isolated-test gate, item by item

   Verify written approval, a non-production test environment, administrator presence, limited network exposure, and a proven stop-and-recovery plan — each one separately. For a lifecycle-only exercise, record that all KNX interfaces, device mappings, physical buses, production networks, ETS projects and physical loads remain disconnected. Adding a repository, installing, or starting software also requires approved immutable provenance.

6. Step 6

   Confirm the safe class

   Only offline read-only pinned sources, or placeholder work that never accesses the execution environment and has no side effects, may be marked safe. Anything that got into this tray by elimination rather than by qualifying goes back.

7. Step 7

   Seal the ticket

   Note the reasons for stopping, the evidence limit, and the items still pending. Mark the whole ticket not yet executed, because that is what it is.

flowchart TD
  G1["Clear written approval"] --> G2["Non-production test environment"]
  G2 --> G3["Administrator present"]
  G3 --> G4["Limited network exposure"]
  G4 --> G5["Proven stop and recovery plan"]
  G5 --> OK["Isolated-test candidate,
still not executed"]
  G1 -.-> X["Any one missing:
do not proceed.
Stop on paper"]
  G2 -.-> X
  G3 -.-> X
  G4 -.-> X
  G5 -.-> X

What a signed page proves, and exactly where it stops

Evidence has limits, and the limits are narrower than they feel when you are holding a folder of it. The document only proves the content of the document. The approval only proves the scope of the approval. The isolation plan only proves the preparation conditions.

flowchart TD
  D["The document"] --> DP["proves the content
of the document"]
  A["The approval"] --> AP["proves the scope
of the approval"]
  I["The isolation plan"] --> IP["proves the preparation
conditions"]
  DP --> N["None of the three proves a result for the daemon,
the listener, the KNX bus, the ETS project
or the Home Assistant integration"]
  AP --> N
  IP --> N

Completion check for the ticket

A valid classification ticket stops an unsafe action before it is executed. That is the test of it, and it is a test the ticket can pass while containing nothing interesting at all.

• It contains no commands, no test programs, and no execution results.
• Each atomic action carries exactly one of the four labels, and where two applied, the stricter one was taken.
• Every safe-class item is an offline read-only pinned source, or placeholder work that does not access the execution environment at all and has no side effects.
• Every isolated-test candidate shows explicit approval, a non-production environment, administrator presence, limited network exposure, disconnection conditions, stop conditions and recovery gates — all visible on the ticket.
• Every approval-required item has clear written approval, a limited scope, and de-identification requirements, and read-only viewing of a live or running environment is listed in that category.
• Every never-automate item has been removed, with no directives and no alternative testing methods left behind in its place.
• All environment, bus, ETS and Home Assistant integration results remain unproven, and the ticket says so.

The ways both exercises drift, and how to pull them back

On the cards

On the ticket

Questions that come up on both exercises

Where to go from here