Quick Spec für KI-Agenten

Kompakte, normative Regeln zum Erzeugen einer DDF. MUSS = zwingend, SOLL = dringend empfohlen.

Dateiformat

1. MUSS: CSV, Trenner ;, Kodierung wie die Quelldateien (die Beispiele verwenden ANSI/Windows-1252 für Umlaute und °; zu klären, ob UTF-8 akzeptiert wird).
2. MUSS: Blockzeilen beginnen mit *NAME;SPALTE;…. Datenzeilen beginnen mit ; (erste Spalte leer).
3. MUSS: Felder mit ;, Zeilenumbrüchen oder Formeln in "…" einschließen. Im Feld niemals ein nacktes " verwenden: "" wird zu ', """ wird zu ".
4. MUSS: SVG in Feldern verwendet für Attribute einfache Hochkommas.
5. MUSS: logische Zeile ≤ 10000 Zeichen.
6. SOLL: Kommentare in eigenen Zeilen mit #, in Formeln /* … */.
7. MUSS: Argumentzeilen mit dem Kopf ;*ARGS;METHOD;ALIAS;TYPE;NAME;VALUE;ITEM;FORMAT;. Die Spalte nach ARGS ist der Funktions-Alias.

Pflichtinhalt *GENERAL

*GENERAL
;DEVICE;<Name>
;MANUFACTURER;<Hersteller>
;TYPE;<Kategorie>
;PROTOCOL;<MODBUS TCP (DDF)|MODBUS RTU (DDF)|REST-API (DDF)|MQTT (DDF)|OCPP (DDF)|SERCOM|DMX512|SVG (DDF)|LIBRARY>
;VERSION_NR;1
;MODEL_NR;<n>
;ID;0x<PP><HHHHHH><MMMM><VVVV>
;MIN_CONTROL_VERSION;V<xxxxx>-<yy>

• MUSS: ID mit 16 Hex-Ziffern, eindeutig. PP = Protokollcode (0A TCP, 0B RTU, 0D REST, 10 MQTT, 12 OCPP, 09 SERCOM, 0F DMX, 11 SVG, C8 LIBRARY).
• MUSS: keine echten Passwörter, Tokens, IPs oder Seriennummern. Setzen Sie Platzhalter oder überlassen Sie die Werte dem Benutzer.

Protokollregeln (Kurzform)

Formelregeln

• MUSS: Jede einzelne Formel muss mit ; abgeschlossen sein. Das gilt für jede Zuweisung, jeden Funktionsaufruf (DEBUG(…);, GUI.…(…);), ENDIF;, ENDSWITCH;, ENDFOR; und auch für die letzte Anweisung einer einzeiligen Zelle ("""SUBSCRIBE.F:=1;"""). Kein ; nach IF … THEN, ELSE, ELSE IF … THEN, SWITCH x, CASE n:, DEFAULT:, FOR … DO. Zeilenumbrüche trennen keine Anweisungen.
• Zuweisung :=, Vergleich ==, logisch && / || (kein AND).
• IF … THEN … [ELSE IF … THEN …] [ELSE …] ENDIF;, SWITCH … CASE n: … DEFAULT: … ENDSWITCH;, FOR i := a TO b BY s DO …; ENDFOR;.
• Strings in '…'. Verketten mit CONCAT, formatieren mit PRINT(FLOAT,'%.1f',v).
• Rohdaten nur übernehmen, wenn A.Q wahr ist.
• Schreiben: In der WFORMULA des Items Rohdaten/Argumente setzen, danach A.F := 1;. Die Schreibfunktion hat POLLING 0.
• Items: ITEM.<ALIAS> bzw. ITEM.<grp>.<ALIAS>, wenn GROUP gesetzt ist.

GUI-Regeln

• *OBJECT;GROUP;ID;ALIAS;SVG;SVGANIMATE;SVGEVENT genügt für reine Widgets.
• Erstes Objekt einer Gruppe mit SVG/SVGANIMATE ersetzt die Standarddarstellung.
• Vorlagen: <svg alias='Name' viewBox='0 0 W H' width='W' height='H'>…</svg>, mehrere hintereinander erlaubt.
• Erlaubt: rect circle ellipse line polyline polygon path text style linearGradient radialGradient stop. Attribute: fill fill-opacity stroke stroke-opacity stroke-width visibility(Ausdruck) transform=rotate(a cx cy) class font-size font-weight text-anchor.
• Platzhalter $(KEY) in Text, Farben, Koordinaten (Ausdrücke erlaubt), transform, visibility. Nicht in d/points.
• Formel: SWITCH $.GUI.WIDGETTYPE (504/508/1004/1008/DEFAULT) → GUI.setWindow(0,0,w,h,1.0); → GUI.paintSVG('Name',x,y,w,h,0,'KEY',str,…);, mindestens 7 Argumente.
• Eingänge: $.CTRLVAR.<var>, $.CTRLROOTVAR.<pfad>, $.CTRLMAINVAR.<pfad> (direkt über getsetbyName, ohne Typpräfixe d/i/r/s), $.VAL.<alias> (vorher prüfen mit $.ISVAL.<alias>). Nicht mehr: $.VARLOCAL / $.VARGLOBAL / $.VARMAIN (entfernt). Display: $.GUI.SYSTEM, $.GUI.LANGUAGE, $.GUI.VERSION, $.GUI.HWID, $.GUI.LOGINLEVEL (0 nicht angemeldet, 1 User, 2 Techniker, 3 Installateur). Theme: $.GUI.COLORBKG/COLORFRG/COLORFNT, $.GUI.FONTLABEL.
• Event: $.MOUSE.X/Y/DOWN/UP/PRESSED/MOVING. $.MOUSE.HANDLED := 0|1; immer setzen.
• Farben in GUI.*: 0xFFRRGGBB.
• SOLL: Ausdrücke und PRINT(…) vor dem GUI.*-Aufruf einer Variable zuweisen (Auswertung von Ausdrücken als Argument ist zu klären).
• Eingabe: GUI.showInputDialog('alias'); öffnet den System-Eingabedialog. Parameter = varmap-Alias, relativ ('roomtemp') oder absolut ('systems.demo.roomtemp'); MUSS bereits geladen sein (z. B. nach $.ISVAL.… / $.VAL.…).

Vorlage (Geräte-DDF, MODBUS TCP)

*GENERAL
;DEVICE;<DEVICE>
;MANUFACTURER;<MANUFACTURER>
;TYPE;<TYPE>
;PROTOCOL;MODBUS TCP (DDF)
;VERSION_NR;1
;MODEL_NR;1
;ID;0x0A<HHHHHH><MMMM>0100
;MIN_CONTROL_VERSION;<Vxxxxx-yy>
;CONNECTION;IPADDRESS
;PORT;502
;SLAVE;1
;TIMEOUT;5000;ms
;WAIT_AFTER_CONNECT;2;s
;MIN_PAUSE;50;ms
;WORDORDER;BIG_ENDIAN
;BYTEORDER;BIG_ENDIAN
;ERROR_HANDLING;FLUSH_OR_RECONNECT_ON_ERROR
*READ;ALIAS;FUNCTION;ADDRESS;COUNT;POLLING;FORMULA
;R1;FC3;<ADDR>;<COUNT>;1000;"IF R1.Q THEN
  ITEM.<ALIAS1>:=R1.0.FLOAT;
ENDIF;"
*WRITE;ALIAS;FUNCTION;ADDRESS;COUNT;POLLING;FORMULA
;W1;FC16;<ADDR>;2;0;
*GROUP;ID;ALIAS;NAME
;0;MAIN;Main
*ITEM;GROUP;ALIAS;NAME;VISIBILITY;ID;UNIT;TYPE;DIR;DEFAULT;WFORMULA;RFORMULA;POLLING
;0;<ALIAS1>;<Name1>;;0;<Unit>;real;IN
;0;<ALIAS2>;<Name2>;;1;<Unit>;real;OUT;0;"W1.0.FLOAT:=x;
W1.F:=1;"

Selbstprüfung vor Ausgabe

• [ ] Jeder Block hat eine Kopfzeile, jede Datenzeile beginnt mit ;.
• [ ] Jede einzelne Formel ist mit ; abgeschlossen (auch ENDIF;, ENDSWITCH;, ENDFOR; und die letzte Anweisung einer Zelle).
• [ ] Anführungszeichen sind paarig, im SVG stehen nur '.
• [ ] Alle ITEM.-Referenzen existieren in *ITEM (inkl. Gruppenpräfix).
• [ ] Alle Funktions-Aliase in Formeln existieren.
• [ ] IDs sind eindeutig (Items, Objekte, Gerät).
• [ ] Keine Secrets oder Kundendaten.
• [ ] Unklare Punkte sind als Kommentar # zu klären: … markiert.