Triage on paper, before anybody reaches for the reset button
Something has stopped working, and every instinct you have built on site says to try the next thing — restart the service, swap the driver, unplug the interface and put it back. Chapters 19 and 20 ask you to do none of that. Chapter 19 sorts link symptoms into five evidence layers and writes down, next to each one, exactly what that evidence cannot prove. Chapter 20 does the same job for USB and serial interfaces with three de-identified symptom cards. Both finish on paper, both take about twenty minutes, and neither one restarts a service, enumerates a device, tries a driver or goes anywhere near the bus. The whole point is that a fault report which has already been fixed is a fault report about a different machine.
The deliverable is a table, and that is not a consolation prize
Chapter 19 produces a symptom triage sheet. Chapter 20 produces an anonymous offline decision tree. Neither produces a working link, and neither claims one. Both are budgeted at about twenty minutes, and both list, in their own words, a set of stop conditions that fire the moment the work starts to want a live system.
| Chapter | What you prepare | What you finish with | Stop conditions |
|---|---|---|---|
| 19 — Link failures | A blank symptom triage sheet and two pinned sources. No logs and no execution environment | Symptoms classified by process, listener, driver, interface and bus layer, with no diagnostic attempt presented as a success | The task requires restarting a driver, service, interface or KNX connection. Or a log still contains a host, endpoint, device path, serial number or secret |
| 20 — USB failures | A blank three-branch worksheet with pinned sources. No USB device, no logs, no execution environment | Evidence of a missing device, a changed path and a driver failure told apart — without claiming that any interface or hardware works | Do not copy the actual device path, USB serial number or host data. Stop if the task would require reconnecting hardware, loading a driver, restarting a service or accessing the bus |
Read the second column of that table again. Chapter 20's bottom line is blunt about what you do not do: you do not look at the device list, you do not copy paths or serial numbers, and you do not try the driver, reboot, or touch the bus. Chapter 19's is the same shape: you put only the symptom concepts that appear in the pinned source into the offline triage table, and you do not restart the service, try changing drivers, probe endpoints, connect to the bus, or post any previous internal errors.
A shop is burgled on a Friday night. The manager arrives first, tidies the broken glass, resets the alarm panel and reboots the camera recorder so the system is back up before opening. By the time the insurer arrives on Monday, everything works. There is also nothing left to look at. The claim is now about a shop that has already been put right, which is not the shop that was burgled. Restarting a knxd service, swapping a driver or replugging an interface does exactly that to a fault: it may well fix the symptom, and it definitely destroys the evidence of what the symptom was.
knxd-addon-0.6.1's knxd/rootfs/etc/knxd.ini and knxd-upstream-0.14.72's doc/inifile.rst. Chapter 20 works from the add-on's initialization script at knxd/rootfs/etc/s6-overlay/s6-rc.d/init-knxd-config/run and the same upstream doc/inifile.rst. Pinned sources support only the documented scope. Nothing here represents validation of any local environment, hardware, network, or KNX bus — and that sentence is not throat-clearing, it is the reason the two sheets are built the way they are.There is one more thing both chapters refuse, and it is the one that catches teams out. Earlier internal link errors are not a public result of this work. Even with the text obscured, an internal error cannot be rewritten as something this site observed, reproduced or verified. If the material in front of you came from a real incident, it stays inside the controlled internal process it came from.
The layer a symptom belongs to, and the layer it says nothing about
The formal name for what Chapter 19 asks you to build is a documented symptom classification for the process layer, the listener layer, the driver layer, the interface layer and the KNX bus layer. The informal name is a triage desk. A file arrives, the desk reads the symptoms on the outside of it and sends it to one of five desks. The reviewer at that desk does not decide the equipment inside the box is broken because of what is written on the box, and does not announce that the whole road is open because one document turned up.
What makes this more than filing is the second half of every row: the evidence ceiling. Each layer's vocabulary describes that layer and stops there.
| Layer | What its vocabulary can describe | What it cannot prove |
|---|---|---|
| Process | Process concepts only — the daemon as a running or stopped thing | That anything is listening. Process-level wording does not reach the listener |
| Listener | The listening responsibility only — who is waiting to receive work | That an endpoint is reachable, or that a driver, interface or bus is in any particular state |
| Driver | The driver family names and the file-level startup-failure concepts, which define the scope of the driver file | That an interface works, or that the bus is operating. Driver wording does not reach either |
| Interface | Nothing in this chapter's evidence. It is a column you may need, kept empty and honest | Anything at all here. Interface results are not part of the evidence in this chapter |
| KNX bus | Nothing in this chapter's evidence, for the same reason | Anything at all here. Bus results are not part of the evidence in this chapter |
flowchart TD P["Process layer
Words about the daemon being up or down"] L["Listener layer
Words about who waits to receive work"] D["Driver layer
Driver family names and documented failure states"] I["Interface layer
Neither pinned source reaches this far"] B["KNX bus layer
Neither pinned source reaches this far"] P -. "cannot prove" .-> L L -. "cannot prove" .-> D D -. "cannot prove" .-> I I -. "cannot prove" .-> B
A parcel goes out by four couriers in a relay, and each one signs a receipt when they hand it on. You have the first courier's receipt in your hand. It is a genuine document, correctly signed, and it proves the parcel left the depot. It says nothing whatever about whether the fourth courier ever found the address, because that courier had not been handed the parcel yet when the receipt was written. Reading a process-level status and concluding that the bus is fine is holding up the first receipt and describing the front door of the house.
tpuart, ft12 and ft12cemi, along with documented diagnostic-state concepts. That the names exist in a document does not prove that an adapter is compatible with any of them, and it does not prove that any of those states occurred in any environment. The names belong in your driver-layer column as vocabulary. They are not a shortlist to work through.Four columns, six steps, and a sentence you write before anything else
Set the sheet up before you have a symptom to put in it. Four columns, and the discipline lives in what each one is allowed to hold.
Only supports documentation classification, not local results.A column stops the work rather than getting filled in whenever it has an unknown source, whenever it makes a cross-layer inference, whenever it asks for a live-environment action, or whenever it still contains identifying information. Those four are stop conditions, not warnings.
What you bring to the desk matters as much as the columns. Two pinned sources and a blank table. No internal logs, no screenshots, and nothing you remember an error saying.
-
Step 1
Pin the source
Confirm that the symptom concept in front of you comes from one of the pinned versions this chapter lists. If the source is unknown, stop. Not “write it down and check later” — stop.
-
Step 2
Choose a layer
Put the concept into the process, listener, driver, interface or bus column according to the responsibility the document gives it. Where there is not enough information to place it, mark it unclassified and leave it there.
-
Step 3
Write an evidence limit
On the same row, in your own words for that concept: process vocabulary cannot prove the listener, listener vocabulary cannot prove the endpoint, and driver vocabulary cannot prove the interface or the bus. This is the column people skip, and it is the column the sheet exists for.
-
Step 4
List the unknown items
Compatibility, hardware, wiring, endpoint reachability and bus status all stay unknown. Do not pick the most plausible root cause among them. A plausible cause written into a triage sheet becomes, three days later, a cause somebody remembers being told.
-
Step 5
Exclude internal results
Delete anything reading “seen”, “reproduced” or “displayed locally”, and any wording like it. What is left is the abstract classification the document supports, and nothing else.
-
Step 6
Submit to independent review
A second reader checks that every column carries a source, a layer, an evidence limit and its unknown items, and that there is no prompt anywhere in the sheet to go and do something live.
flowchart TD
A["One symptom concept in hand"] --> B{"Is the wording from one of
the two pinned files?"}
B -->|"no"| S1["Stop. Unknown source"]
B -->|"yes"| C{"Does it match exactly one
documented responsibility?"}
C -->|"no"| U["Mark it unclassified"]
C -->|"yes"| D["Write the layer, then the evidence
limit, on the same row"]
D --> E{"Does the row still name a host, endpoint,
path, serial number or time?"}
E -->|"yes"| S2["Delete the row. Rewrite it from
the source abstraction"]
E -->|"no"| F["Leave hardware, wiring, compatibility,
reachability and bus status unknown"]
F --> G["Hand it to a second reader"]
The sheet is done when all six of these are true of it.
- Each symptom concept corresponds to a pinned source and to a single primary layer.
- Programs, listeners, drivers, interfaces and buses are not mixed together into one conclusion about success or failure.
- Each column states clearly what it supports and what it does not support.
- Hardware, wiring, compatibility, endpoint reachability and bus status remain unknown.
- Earlier internal bugs have not been published as observations, reproductions or verification results.
- There are no hosts, endpoints, paths, serial numbers, accounts, secrets, addresses, ranges or times anywhere in the table.
USB and serial, with the identifying half of every symptom removed
Chapter 20 narrows to USB and serial interfaces, and it narrows the evidence with it. The formal name is anonymous symptom classification for missing candidate, path-change and driver-category. Three symptom cards, none of which carries a live-environment value.
A sorting office receives three notices, and every one of them has had the name and address cut out before it arrived. The first says an expected package never appeared among the candidates. The second says the package's path category is not the one on the earlier record. The third carries a clue about which category of driver was responsible. The desk sorts them into three trays. It does not open a package, does not trace one, and does not tell anybody the package is ready for collection — because with the names cut out, it could not tell you which package that would be.
Each card has a strict definition and, more importantly, a strict list of what may not go on it.
| Card | What you write on it | What must not appear on it |
|---|---|---|
| Missing candidate | Only that the expected category did not produce a candidate | The candidate content, the enumeration results, or where it occurred |
| Candidate path category change | Only that the reference type is different from the original record | The old value, the new value, or the device relationship |
| Driver-category clue | Only the responsibility categories that the pinned source names | A trial order, a list of compatible models, or a loading method |
| Unknown | Used when information is mixed, from unknown sources, or would need a live-environment value. You stop classifying and leave it unknown | A best guess. An unknown card that has been narrowed down to something is no longer an unknown card |
Three of those are branches; the fourth is what you reach for when a statement does not qualify as a branch. Read the three terms literally, because each is smaller than it sounds. A candidate is only an abstract item that the source describes for configuration preparation. A path change indicates only that a category relationship changed. A driver category indicates only a documented responsibility. None of the three prove anything about USB, about a serial interface, or about hardware status.
The worksheet inherits the same prohibition as the triage sheet, extended to hardware identity. No device paths, no USB serial numbers, no hosts, no endpoints, no addresses, no accounts, no secrets, no environment names, and no times that can be tied back to a site. If the material handed to you contains any of that, you do not copy it across — you return it to the controlled privacy process it should have stayed in.
Draw the tree before you go looking for a device
The order here is the safety measure. You draw the decision tree first, while there is nothing to be tempted by. The root node asks one question and only one: which symptom matches the existing de-identified description? Every branch other than the three is marked insufficient information.
flowchart TD
R["A de-identified symptom statement"] --> G{"Sourced, single, and free
of live-environment values?"}
G -->|"no"| D["Unknown card.
Stop classifying"]
G -->|"yes"| Q{"Which description does it match?"}
Q -->|"no candidate"| A["Missing candidate card
No candidate appeared
for the expected category"]
Q -->|"category changed"| B["Path change card
The reference type
differs from before"]
Q -->|"driver wording"| C["Driver clue card
A documented
responsibility, no more"]
A --> E["Only document classification supported.
Live availability not confirmed"]
B --> E
C --> E
-
Step 1
Confirm the source boundaries
Accept only the initialization responsibilities and the documented driver concepts described in the pinned version. No source means insufficient information, and insufficient information means the unknown card.
-
Step 2
Remove the live-site details
Keep abstract descriptions — “missing”, “different reference categories”, “driver responsibility category”. If what you are left with could still identify the environment, stop there rather than trimming further.
-
Step 3
Evaluate the first branch
If the description says only that the expected category was not a candidate, add a missing-candidate card. Do not guess at hardware, at permissions, or at reasons. “Probably the cable” is a reason.
-
Step 4
Evaluate the second branch
If the description says only that the reference category differs before and after, add a path-category-change card. Do not record the old value, the new value, or the enumeration method that produced either.
-
Step 5
Evaluate the third branch
If the description can only correspond to a driver responsibility or a failure concept in the document, it goes on the driver-category clue card. Do not generate trial suggestions from it.
-
Step 6
Limit the conclusions
Every card carries the same closing sentence:
Only document classification supported; all live-environment availability not confirmed.On every card, not once at the bottom of the page. -
Step 7
Independent review
A second reader confirms that each branch is single, that it comes from a pinned source, that it holds no identifying values, and that there are no commands, enumerations, tryouts, restarts or bus actions anywhere in it.
The finished worksheet is an anonymous offline decision tree. It is not a diagnosis, and it does not indicate that any device has been viewed, detected or verified. Six things have to be true of it.
- The root node accepts only de-identified symptom statements that pinned sources support.
- The three branches are precisely the lack of candidate items, candidate path category changes, and driver-category clues.
- Each card carries a source category, a symptom category, an evidence limit, its unknown items, and a responsible role.
- There is no device path, USB serial number, host, endpoint, address, environment name or time to associate.
- There are no commands, no device enumeration, no driver testing, no hardware plugging, no service restarting and no bus actions.
- USB, serial interface, driver, KNX bus, ETS, integration, group and physical control results all remain unconfirmed.
Both chapters spend half their length refusing requests
Look at the troubleshooting lists in these two chapters and you notice something unusual: most of the entries are not faults in the sheet. They are people asking you to do the sensible next thing. Both chapters answer the same way, and it helps to know where the line falls before somebody is standing over you asking.
flowchart TD
R["Someone asks for the next obvious thing"] --> Q1{"Does it touch a running
environment at all?"}
Q1 -->|"no"| P["Safe. It is paperwork"]
Q1 -->|"yes"| Q2{"Is it read-only viewing?"}
Q2 -->|"yes"| AP["Approval required. Neither chapter
supplies a viewing method"]
Q2 -->|"no"| Q3{"Group read or write, telegram, ETS
programming, interface or bus, or
physical equipment?"}
Q3 -->|"yes"| N["Never automate.
The test bus is no exception"]
Q3 -->|"no"| IT["Isolated test only, behind written approval,
a non-production rig, an administrator present,
limited network exposure and a proven
stop-and-recovery plan"]
“I only want to look, I will not touch anything” sounds like it should be free. It is not, and the reason is the doorway rather than the looking. To read the meter cupboard in somebody else's building you first have to be let into the building, and being let in is precisely the permission you were not given. That is why read-only viewing of a running environment sits in the approval-required box rather than the safe one, and why neither chapter even prints the steps for it. Approval to read is also not approval to try something, and the moment reading turns into trying, you are in a different box again.
The refusals from Chapter 19, with what to do instead.
| What comes up | What you do |
|---|---|
| A symptom appears to fit two layers | Split it into two columns, or mark it unclassified. Do not choose the root cause by guesswork |
| Only generic error words are available | Keep the item as unclassified, pending precise documentary evidence |
| Someone posted an internal error | Move it out of the public form, stop sharing it, and return it to the controlled internal process |
| Someone asked for a reboot | Refuse. There is no restart procedure in this chapter |
| Someone asked to switch driver or detect an endpoint | Refuse. There is no driver trial and no endpoint probe procedure in this chapter |
| Someone asked to connect or test the bus | Refuse. There is no bus procedure here, and nothing is verified by telegram or by physical control |
| The classification text leaks environment details | Remove the column and rebuild it from the abstraction in the source |
And the same list from Chapter 20, where the temptations are hardware-shaped.
| What comes up | What you do |
|---|---|
| The narrative resembles both absence and change at once | Mark it insufficient information. Do not select a root cause for it |
| The description says only “USB is broken” | That is a conclusion, not a classifiable symptom. Ask for an anonymous symptom category instead |
| Someone provides a real path or hardware identifier | Stop copying it and stop sharing it, then return the material to the controlled privacy process |
| Someone asked for a list of devices | Refuse. There is no enumeration and no live viewing procedure in this chapter |
| Someone suggests trying drivers one by one | Refuse. A driver-family name is not a trial list |
| Someone suggested unplugging or rebooting | Refuse. This chapter does not trigger hardware or service actions |
| Someone wants to use the bus to prove the classification | Refuse. Nothing here connects, reads, writes or transmits any bus data |
The objections these two chapters get
Can the listener vocabulary prove that the endpoint is reachable?
The file has a concept of a startup failure. Can that determine a hardware failure?
Can masked internal errors be added to the sheet?
Can I reboot just to check whether the classification is right?
Does finishing the classification mean the link is restored?
Does a missing candidate prove that the device does not exist?
When the path category changes, can I at least record the old value and the new value?
Can driver-category clues be used to select a driver?
tpuart, ft12 and ft12cemi appear as documented families. Reading them as a sequence to attempt is the single most common misuse of this chapter.Can I view the list of running devices and come back to fill in the form?
Does completing the decision tree mean the USB problem is solved?
Where to go from here
You can now say what a symptom is, and what it is not.
Part 9 closes the guide with Chapters 21 and 22: turning offline source review, approval boundaries and evidence notes into a maintenance rhythm you can keep, and then the incident runbook — whose steps, and whose order, exist for the days when the triage in this part is the only thing standing between a bad symptom and a bad write.
Open the full guidePart 8 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