Two chapters where the output is a sheet of paper

Chapters 7 and 8 both take about fifteen minutes, and neither one produces a working configuration. Chapter 7 produces a four-column responsibility sheet. Chapter 8 produces a four-box responsibility map. That is the whole deliverable.

The bottom line of Chapter 7 is that configuration fields, placeholders, ports and network exposure are four distinct concepts, and you are to create only a responsibility list — not enter live values, not open ports, not change networks. The bottom line of Chapter 8 is that a listener is a role that waits to receive work: its presence in a configuration proves neither endpoint reachability nor an established connection or tunnel, and it says nothing about KNX bus status.

You have used ETS. You know what a group address does when you send to it. That is exactly why this matters: on the bus side you have decades of tooling that tells you the truth about the wire, and on the IP side you are about to start reading status text that looks equally authoritative and is not about the wire at all.

Chapter 7 hands you the vocabulary for the doorway — fields, placeholders, ports, exposure — and Chapter 8 stacks those into the four layers you are allowed to make claims about, in order and one at a time.

What you need in front of you

A blank responsibility sheet. No ETS project, no host information, no network settings. If the numbers you are tempted to write down came out of a log or a screenshot, stop sharing that material and follow the guide's safe log-sharing guidance instead. Do not go and read the live environment merely to fill in a form.

One more piece of honesty about what this guide is. Every claim in it is bounded by two pinned commits: the KNXD Add-on 0.6.1 source and the KNXD 0.14.72 source. Pinned sources support the documented scope and nothing else. Publication is not validation of any local environment, hardware, network or KNX bus, and it is not authorization to operate anything.

What the pinned options schema declares, and what it refuses to declare

The pinned Add-on 0.6.1 schema treats address as a required string, client_address as a required range string, ip_address as an optional string, and dest_port as an optional port. That is a field contract. It describes the shape of what may be typed, and stops there.

The pinned sources do define defaults for some of those fields. This guide does not disclose the values, and the reason is the one you will meet again in the FAQ: a value printed in a tutorial gets pasted into a real installation by somebody who is in a hurry.

Notice that “required” and “optional” are statements about the form, not about your building. A required field with nothing in it is a form that will not submit. It is not a bus that will not run.

flowchart TD
  S["Add-on 0.6.1 options schema
knxd/config.yaml"] --> R["Required"]
  S --> O["Optional"]
  R --> R1["address
string"]
  R --> R2["client_address
range string"]
  O --> O1["ip_address
string"]
  O --> O2["dest_port
port"]
  R1 --> N["A field contract, nothing more.
Required or optional says nothing about
a configured project, an existing endpoint,
a created listener, or safe exposure"]
  R2 --> N
  O1 --> N
  O2 --> N

The six steps, in this order

Chapter 7's procedure is six steps and the order carries the safety. Each one closes off an inference the next one would otherwise let you make.

1. Step 1

   Mark the column role first

   Separate the address class, the range class, the endpoint-host class and the port class. Write categories only. No values of any kind, not even ones you consider harmless.

2. Step 2

   Use placeholder text instead of values

   In the public form, write only these four, and mark each one as not deployable:

   individual-address placeholder

   client-range placeholder

   endpoint-host placeholder

   endpoint-port placeholder

   The wording is deliberately semantic. It reads as a description of a role, and it does not read as something you could paste.

3. Step 3

   Separate the port from the listener

   A port is like a door number. A listener is a service waiting for work. Do not represent them as a single state. The next section is entirely about this step, because it is the one that gets collapsed most often.

4. Step 4

   List exposure responsibilities as separate review items

   Binding scopes, firewalls, routing and accessible networks are four independent review items, and every one of them is marked Not Evaluated. Section five of this article takes them one at a time.

5. Step 5

   Add the non-conclusion

   Write it out in full: the address has not been configured, the port has not been opened, the listener has not been established, the endpoint has not been verified, and the bus has not been certified. Five statements. A sheet without them will be read as a design by the next person who picks it up.

6. Step 6

   Remove live values before delivery

   If any numeric address, port, host, URL or environment name has appeared in the form — and one usually has, because somebody pasted it to “make it clearer” — delete it before the sheet goes anywhere.

Correctly formatted fields do not prove KNX bus, ETS, integration or device performance. A sheet that passes every format check is still a sheet.

A door number, somebody at the desk, and an outside line

Step 3 of the sheet deserves its own section, because collapsing a port into a listener is the single most common error in this whole area, and because it survives into every later part of the guide if you let it through here.

The four roles map onto each other cleanly once you have the analogy, so it is worth writing them side by side before you need them under pressure.

flowchart LR
  subgraph K["In knxd"]
    direction LR
    K1["A port field
in a form"] --> K2["A listener
waiting for work"] --> K3["An endpoint
that is reachable"] --> K4["The KNX bus
responds"]
  end
  subgraph B["In a building"]
    direction LR
    B1["A door number
on the plan"] --> B2["Someone sitting
at that desk"] --> B3["An outside line
to that desk"] --> B4["The work behind
the desk is done"]
  end

Chapter 8 states the responsibilities in the guide's own terms. The listener waits for requests from the network side. The network interface handles data entering and leaving. KNXnet/IP is the network-side communication context. The KNX bus is another layer of responsibility altogether.

There is a technical note behind Chapter 8 worth stating plainly. The managed INI template shipped with Add-on 0.6.1, at knxd/rootfs/etc/knxd.ini, contains TCP server and listener related configuration vocabulary. That demonstrates how the template expresses a server role. It does not demonstrate generated post-configuration settings, sockets, bind locations, routes, firewalls, or remote endpoints, and it is not evidence that any of those exist.

Four boxes, and a test for every sentence

Chapter 8 asks for four empty boxes, with no endpoints and no values filled in. What goes in each box is fixed before you start, which is the point — you are not investigating, you are recording what you are entitled to say.

This drawing limits what the document may claim. It is not a network topology, and it cannot be used to establish a connection. Nobody should be able to take this page and wire something from it.

The six steps, again in order

1. Step 1

   Write the document's conclusion first

   The sentence is: pinned template contains listener/server setting role. Not “monitored.” Not “listening.” Writing the permitted sentence before you look at anything else stops the stronger one from forming.

2. Step 2

   Put that sentence in the first box

   It belongs to the template layer, and only there. The remaining three boxes stay unestablished or unproven.

3. Step 3

   Separate the network interface

   Note that the interface is responsible only for data entering and leaving. It does not equal the listener, and it cannot represent the bus.

4. Step 4

   Block the reachability inference

   In the network box, write: no endpoint data, probes, connections, or tunnels. Writing the absence down is what stops somebody reading the empty box as an oversight and filling it in for you.

5. Step 5

   Block the bus inferences

   In the bus box, write all four separately:

   No evidence of telegrams

   No evidence of group operations

   ETS programming or downloads not executed

   No evidence of physical control

   Four statements, not one summary. Each of the four is a claim somebody will otherwise make on your behalf.

6. Step 6

   Limit every conclusion

   Go back through the document and replace any unsupported assertion about an endpoint, a connection, a tunnel or the bus with a statement grounded in the pinned template. This is a pass over what you already wrote, not a step you do while writing.

Step 6 is easier with a test you can apply to one sentence at a time.

flowchart TD
  A["A sentence you are about
to write on the sheet"] --> B{"Does it only describe what
the pinned file contains?"}
  B -->|"yes"| C["Layer 1, template.
Keep it as written"]
  B -->|"claims a listener"| D["Layer 2, process.
No independent
evidence"]
  B -->|"claims reachability"| E["Layer 3, network.
Not tested;
not established"]
  B -->|"claims the bus"| F["Layer 4, KNX bus.
Unconfirmed"]
  D --> G["Rewrite it, grounded
in the pinned template"]
  E --> G
  F --> G

Exposure is not one question

Step 4 of the Chapter 7 sheet lists exposure as four independent review items: binding scopes, firewalls, routing, and accessible networks. All four are marked Not Evaluated. That is not a placeholder for work you will do later in this part — it is the finished state of those boxes here.

flowchart TD
  Q["Can anything out there
reach this listener?"] --> A["Binding scope
not evaluated"]
  Q --> B["Firewall
not evaluated"]
  Q --> C["Routing
not evaluated"]
  Q --> D["Reachable network range
not evaluated"]
  A --> R["Answer for this chapter: unproven.
And nothing here authorizes opening
a port to go and find out"]
  B --> R
  C --> R
  D --> R

Two requests turn up at this point in almost every project, and both have the same answer in the source. Somebody asks you to open a port so the setup can be verified: stop, because this chapter does no live network changes or detection. Somebody asks you to probe whether the endpoint is reachable: stop, because there are no reachability, wiring or tunnel procedures here. Neither refusal is pedantry. Opening a port to check a document is how a documentation task turns into an unreviewed change on a building's network.

Before you call Chapter 7 done

Four checks, and the result is not a usable configuration.

• You can explain that a field is a space, placeholder text is a prompt, a port is like a door number, and network exposure decides who can reach that door.
• All placeholder text is clearly marked For document classification only; not deployable.
• The table contains no addresses, ranges, hosts, IPs, port numbers, URLs, or other context-identifying information.
• You did not modify Home Assistant, a listener, a firewall, routing or the network, and you did not operate ETS or the bus.

Before you call Chapter 8 done

Four more. The finished product is a four-layer responsibility map in which only the template roles have a direct origin; every other layer stays unconfirmed.

• You can explain that the listener is like a reception desk waiting for incoming calls, which does not prove the outside line is reachable.
• You divided templates, processes and listeners, reachability, and the KNX bus into four layers.
• Your drawing contains no host, IP, port, URL, interface name, credentials, or other environment-identifying information.
• You did not provide probing, wiring or tunneling procedures, and bus, ETS, integration and physical-control results all remain unconfirmed.

Ten ways a responsibility sheet turns back into a claim

Between the two chapters the source lists ten failure modes, five for each. They are all the same shape: a document that was careful when it was written gets read one layer stronger than it was meant.

The ten that come up every time

Where to go from here