Das CSV-Importformat für KNX-Gruppenadressen in ETS 6

Die Tabelle gibt es längst

Bis jemand die ETS öffnet, stehen die Adressen meist schon irgendwo geschrieben — in der Projekttabelle, in den Ausschreibungsunterlagen, in einer Liste, die der Kunde geschickt hat. Zweitausend davon von Hand einzutippen kostet einen Tag und produziert Fehler, die Monate später auf der Baustelle auftauchen.

Die ETS importiert sie in einer Sekunde aus einer CSV. Das Hindernis ist, dass die Datei genau die Form haben muss, die die ETS erwartet — und diese Form ist schlecht dokumentiert.

Neun Spalten

Die Datei ist semikolongetrennt und hat ein festes Layout aus neun Spalten:

Das eine Detail, das alle falsch machen

Die Ebene eines Eintrags wird dadurch kodiert, welche Spalte den Namen trägt. Nicht durch Einrückung, nicht durch ein eigenes Typfeld, nicht durch die Adresse allein. Drei Zeilen zeigen die ganze Regel:

Main group     "Lighting"; ; ;"1/-/-";"";"";"";"";"Off"
Middle group    ; "Switch"; ;"1/0/-";"";"";"";"";"Auto"
Group address   ; ;"Kitchen ceiling";"1/0/3";"";"";"";"";"Auto"

Steht der Name in der falschen Spalte, weist die ETS die Zeile entweder zurück oder legt sie auf einer Ebene an, die nicht gemeint war. Das ist der mit Abstand häufigste Grund, warum ein von Hand gebauter Export nicht sauber importiert.

Die Fallstricke, bevor Sie 2 000 Zeilen erzeugen

• Zeilenenden müssen CRLF sein. Eine Datei mit reinem LF wird nicht importiert.
• Anführungszeichen innerhalb eines Namens werden verdoppelt — die übliche CSV-Regel.
• Wertebereiche: Hauptgruppe 0–31, Mittelgruppe 0–7, Gruppenadresse 0–255. In einer Tabellenkalkulation warnt nichts, wenn Sie sie überschreiten.
• Den Datenpunkttyp beim Import setzen. Technisch ist er optional, doch ihn wegzulassen heißt, später jede Adresse in der ETS erneut anzufassen — ein leerer Typ ist ein Fehler auf Vorrat.
• Kodierung: Die Datei unten ist UTF-8 ohne Byte Order Mark. Bei reinen ASCII-Namen spielt das nie eine Rolle. Tragen die Namen Umlaute oder Gedankenstriche, importieren Sie zuerst eine kleine Probe und sehen Sie sich an, wie die Namen ankommen, bevor Sie die vollständige Datei erzeugen.

Den Baum einmal beschreiben, dann Adressen einspeisen

Der Generator teilt die Arbeit in zwei Teile. Ein Schema beschreibt die Gestalt des Gruppenadressbaums — welche Hauptgruppen es gibt, welche Mittelgruppen darin sitzen, welchen Datenpunkttyp jede trägt. Die Projekttabelle liefert dann die Adressen. Nichts am Baum wird pro Zeile wiederholt.

Genau diese Trennung macht die Benennung nebenbei konsistent: Jede Mittelgruppe behält ihre Bedeutung über das ganze Projekt, weil sie einmal deklariert wird.

const schema = [{
  index: 1,
  name: 'Lighting — ground floor',
  middle: [
    { index: 0, name: 'Switch',        field: 'switch',       dpt: 'DPST-1-1', suffix: 'On/Off' },
    { index: 1, name: 'Switch status', field: 'switchStatus', dpt: 'DPST-1-1', suffix: 'On/Off St' },
    { index: 2, name: 'Dimming',       field: 'dim',          dpt: 'DPST-3-7', suffix: 'Dim' },
  ],
}];

Prüfung ist das, was Handarbeit nicht hat

Die Datei zu erzeugen ist die leichte Hälfte. Die Hälfte, die sich bezahlt macht, ist die Weigerung, eine kaputte zu erzeugen. Vier Fehler in einer Quelltabelle — und was zurückkommt:

- Lighting / Switch / Hall downlights: address 1/0/1 already used by "Kitchen ceiling On/Off"
- Lighting / Switch / Terrace: address 1/9/3 sits in middle group 9, but the schema places it in 0
- Lighting / Switch / ?: missing device name
- Lighting / Switch / Study: address 1/0/999 exceeds the 0–255 sub range

Der erste davon ist der teure. Zwei Gruppenobjekte auf einer Adresse sind in KNX zulässig und gelegentlich gewollt, weit häufiger aber ein Copy-Paste-Rutscher in der Tabelle. Hier gefunden kostet er nichts. Auf der Baustelle gefunden kostet er eine Anfahrt, denn das Symptom sind zwei Kreise, die gemeinsam schalten, während im Projekt nichts falsch aussieht.

Der ganze Durchlauf

Eine Tabelle mit sieben Geräten, ein Befehl: Die Ausgabe unten ist genau das, was das veröffentlichte Beispiel erzeugt — 26 Adressen in zwei Hauptgruppen, Byte für Byte gegen die Beispieldatei im Repository geprüft.

"Lighting — ground floor"; ; ;"1/-/-";"";"";"";"";"Off"
 ;"Switch"; ;"1/0/-";"";"";"";"";"Auto"
 ; ;"Kitchen ceiling On/Off";"1/0/1";"";"";"";"DPST-1-1";"Auto"
 ; ;"Kitchen worktop On/Off";"1/0/2";"";"";"";"DPST-1-1";"Auto"
 ;"Switch status"; ;"1/1/-";"";"";"";"";"Auto"
 ; ;"Kitchen ceiling On/Off St";"1/1/1";"";"";"";"DPST-1-1";"Auto"

In der ETS: Gruppenadressen → Import → CSV.

Was das nicht leistet

Der Import legt Gruppenadressen an. Er verknüpft sie nicht mit den Kommunikationsobjekten Ihrer Geräte — das bleibt Handarbeit in der ETS, und Massenverknüpfung ist nur über die ETS-API erreichbar.

Das Format hier ist das, was ETS 6 annimmt. ETS 5 verwendet einen anderen Spaltensatz; gehen Sie also nicht davon aus, dass die Datei übertragbar ist.

Eine Grenze im Werkzeug selbst: Das Adressmuster akzeptiert Mittelgruppen von 0–9, KNX erlaubt 0–7. Eine falsche Mittelgruppe wird erkannt, wenn sie dem Schema widerspricht, wie im Beispiel oben — deklarieren Sie aber Index 8 im Schema selbst, protestiert nichts. Der Bereich 0–255 der Untergruppe wird explizit geprüft.

Nehmen Sie es mit

Keine Abhängigkeiten, Node 18 oder neuer, MIT-Lizenz. Passen Sie das Schema an Ihre eigene Benennung an, dann läuft es so, wie es ist.