Skip to Content

Triage on paper, before anybody reaches for the reset button

nothing gets rebooted
KNXD Guide · Part 8

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.

5 layers
Process, listener, driver, interface, bus — and each one has a ceiling
3 cards
Missing candidate, path category change, driver-category clue
0 live values
No device path, serial number, host, endpoint or time leaves either sheet
Two chapters that end on paper

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.

ChapterWhat you prepareWhat you finish withStop 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.

In plain terms

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.

These chapters are bounded by their pinned sources, and they say so. Chapter 19 works from 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.

Five layers, five ceilings

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.

LayerWhat its vocabulary can describeWhat it cannot prove
ProcessProcess concepts only — the daemon as a running or stopped thingThat anything is listening. Process-level wording does not reach the listener
ListenerThe listening responsibility only — who is waiting to receive workThat an endpoint is reachable, or that a driver, interface or bus is in any particular state
DriverThe driver family names and the file-level startup-failure concepts, which define the scope of the driver fileThat an interface works, or that the bus is operating. Driver wording does not reach either
InterfaceNothing in this chapter's evidence. It is a column you may need, kept empty and honestAnything at all here. Interface results are not part of the evidence in this chapter
KNX busNothing in this chapter's evidence, for the same reasonAnything 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
Five boxes, four dotted edges, one word repeatedThe five layers run top to bottom in the order you classify them, and every connection between them is dotted rather than solid, because none of them is a path evidence can travel. All four carry the same label. The bottom two boxes say the same sentence as each other: this chapter's two pinned files do not reach the interface or the bus.
In plain terms

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.

A driver family list is not a compatibility list. The pinned upstream file supports driver-family names such as 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.
Building the triage sheet

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.

Source — pinned source identification and version boundaries only. Not local data of any kind.
Layer — one of five: process, listener, driver, interface, bus.
Symptom — the abstract state concepts as the file words them. Not what you have seen in some environment.
Evidence limit — and before you fill in a single row, write into this column: 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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"]
Three diamonds, and each one has a left-hand exitWatch which answer takes the exit, because it changes. On the first two diamonds the left branch is the “no” — unknown source, then wording that matches no single responsibility. On the third it is the opposite: answering “yes” to the leak question sends you left, to delete the row and write it again from the source. Four boxes end the chart, and only the one at the bottom right is the finish.

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.
Three opaque inboxes

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.

In plain terms

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.

CardWhat you write on itWhat 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.

Initialization conversion is not device discovery evidence. The pinned initialization source describes how required USB values and interface settings are handled — that is the interface, USB value conversion and configuration preparation responsibility of the required device. It is a source-code responsibility. It does not confirm that a running environment found a candidate, and it does not prove that the converted values, the drivers or the interfaces are available. The upstream file, for its part, describes driver families and documented diagnostic concepts. Neither source supplies a candidate, a path, a serial number, or a result for any specific host.

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.

Walking the three branches

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
A gate, then a three-way splitThe unknown card is not one of the three. It hangs off the first gate, a full row above the others and on the far left, and no arrow leaves it — that branch ends where it starts. The three cards below sit side by side and all three funnel into the same closing sentence, which is the only box in the chart that more than one arrow points at.
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.
The things you say no to

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"]
Four ways out, and only the first is open todayThree diamonds, four terminal boxes. The paperwork box is the one at the top left, reached by answering “no” to the very first question, and it is the only exit these two chapters actually authorize. The other three — approval required, never automate, and the long isolated-test box at the bottom right — are all outside the scope of Chapters 19 and 20, which is why none of them comes with a procedure attached.
In plain terms

“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 upWhat you do
A symptom appears to fit two layersSplit it into two columns, or mark it unclassified. Do not choose the root cause by guesswork
Only generic error words are availableKeep the item as unclassified, pending precise documentary evidence
Someone posted an internal errorMove it out of the public form, stop sharing it, and return it to the controlled internal process
Someone asked for a rebootRefuse. There is no restart procedure in this chapter
Someone asked to switch driver or detect an endpointRefuse. There is no driver trial and no endpoint probe procedure in this chapter
Someone asked to connect or test the busRefuse. There is no bus procedure here, and nothing is verified by telegram or by physical control
The classification text leaks environment detailsRemove 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 upWhat you do
The narrative resembles both absence and change at onceMark 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 identifierStop copying it and stop sharing it, then return the material to the controlled privacy process
Someone asked for a list of devicesRefuse. There is no enumeration and no live viewing procedure in this chapter
Someone suggests trying drivers one by oneRefuse. A driver-family name is not a trial list
Someone suggested unplugging or rebootingRefuse. This chapter does not trigger hardware or service actions
Someone wants to use the bus to prove the classificationRefuse. Nothing here connects, reads, writes or transmits any bus data
The never-automate line is the same one you have been reading since Part 1, and it does not soften because something is broken. Do not read or write groups, do not send a KNX telegram, do not perform ETS programming or downloads, do not connect a KNX interface or bus, and do not control physical equipment. The test bus is no exception. An outage is exactly the moment this rule feels negotiable, which is exactly why it is written the same way in every chapter.
If the work is heading toward installing or starting something. Joining the repository, installing or starting also requires the full isolation gates, written approval, an approved immutable artifact or image digest, and source-to-build attestation. Stop if any one item is missing — not most of them, any of them.
Questions people ask

The objections these two chapters get

Can the listener vocabulary prove that the endpoint is reachable?
No. It only defines listener responsibilities. It does not prove endpoints, drivers, interfaces or buses. This is the single most useful sentence in Chapter 19, because listener wording is the wording that reads most like a working connection.
The file has a concept of a startup failure. Can that determine a hardware failure?
No. Documentation concepts are not sufficient to locate hardware, wiring, compatibility or environmental root causes. A documented failure state tells you the document has a name for that state. It does not tell you that state happened, or why.
Can masked internal errors be added to the sheet?
No. This work publishes classifications of pinned sources only, not internal or local results. Masking the text does not change what the item is. An internal error with the identifiers blacked out is still an internal result, and presenting it here would make this site the apparent source of an observation it never made.
Can I reboot just to check whether the classification is right?
No. Neither chapter provides or authorizes any restart, switch or detection action. And note what the question assumes — that the classification is a hypothesis about the live system. It is not. It is a statement about what two documents support, and a reboot cannot confirm or refute it.
Does finishing the classification mean the link is restored?
No. The classification table has no execution-environment evidence in it and no link results. It is finished when the paperwork is honest, which is a different event from the link coming back.
Does a missing candidate prove that the device does not exist?
No. It is a de-identified symptom category and nothing more. It cannot identify hardware, a connection, permissions, or an environmental cause. A missing candidate is a sentence about a category that produced nothing, and every explanation you can think of for that is still on the unknown list.
When the path category changes, can I at least record the old value and the new value?
No. Only the abstract relationship change is recorded. No actual values, and no device-specific differences. The pair of values is exactly the part that identifies the site, which is why the card is defined to exclude it rather than to be careful with it.
Can driver-category clues be used to select a driver?
No. The documented responsibility classification is not a compatibility list, and it is not a loading or trial recommendation. Names such as 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?
This chapter does not provide that procedure. Any read-only viewing of a live or running environment requires separate approval, and that approval does not extend the scope of this chapter. Read-only approval is also not approval for attempts or modifications.
Does completing the decision tree mean the USB problem is solved?
No. It completes a documentation classification. It proves nothing about the device, the driver, the interface or the bus, and the worksheet says so on every card.
Next

Where to go from here

two sheets down

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 guide

Part 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

in KNXD
A backup nobody has restored, and a door nobody remembers opening