Protokoll

Twinwrights eigener Kernel (die Steuerung) spricht das serielle Protokoll von Grbl 1.1, mit den Erweiterungen, die aktuelle Grbl-Sender-Programme verwenden. Ein Sender-Programm, das für Grbl geschrieben wurde, funktioniert damit. Die geprüften Sender-Programme und ihre Einstellungen stehen in G-Code-Sender-Programme.

Verbinden

Wo	Wie
Der Zwilling in Studio	TCP-Port 2323 auf diesem Computer, jeweils ein Sender-Programm.
Die MC-1	Ihr nativer USB-Port, ein serieller Port (COMn unter Windows). Die Baudrate spielt keine Rolle; verwenden Sie 115200, wo ein Sender-Programm eine verlangt. Die Steuerung antwortet, sobald das Sender-Programm DTR setzt.

Zeilen und Antworten

Zeilenende: Eine Zeile endet mit LF oder CR. Ein Paar aus CR LF oder LF CR zählt einmal; zwei LF sind zwei Zeilen.
Antworten: Die Steuerung antwortet auf jede Zeile mit ok oder error:N, in der Reihenfolge, in der die Zeilen kamen. Fehlercodes listet jedes N auf.
Zeilenlänge: bis zu 256 Zeichen. Eine längere Zeile wird mit error:11 beantwortet.
Zeichenzählung: Der Empfangspuffer fasst 1024 Bytes. Ein Sender-Programm darf so viele unbeantwortete Bytes unterwegs haben. Bf: im Statusbericht gibt den freien Platz an.
Planer: 100 Blöcke. Bf: gibt auch die freien Blöcke an.
Wartende Zeilen: Bei Vorschub halt oder geöffneter Schutztür warten Zeilen im Puffer. Sie werden beantwortet, sobald der Zyklus wieder startet. Ein Reset, 0x19 (Stopp), 0x03 oder 0x85 (Tippen abbrechen) verwirft die Zeilen, die noch warten.
Nach einem Fehler: Der nächste G-Code-Satz wird nicht ausgeführt und mit demselben Fehler beantwortet. Das geht so weiter, bis ein $-Befehl, eine leere Zeile oder ein Reset kommt.

Echtzeitbefehle

Ein Echtzeitbefehl ist ein einzelnes Byte. Die Steuerung führt ihn sofort aus, sobald er eintrifft, auch mitten in einer Zeile. Er gehört zu keiner Zeile und bekommt kein ok.

Byte	Befehl	Was er bewirkt
`0x18` (Strg+X)	Reset	Hält sofort alles an und löscht, was in der Warteschlange steht. Ein Reset, während sich die Achsen bewegen, löst `ALARM:3` aus: Referenzieren Sie erneut. Wird bei aktivem Not-Halt nicht angenommen.
`0x03` (Strg+C)	Reset, Not-Halt aktiv	Wie Strg+X, wird aber auch bei aktivem Not-Halt angenommen.
`0x19` (Strg+Y)	Stopp	Die Achsen bremsen bis zum Stillstand ab, und die noch eingereihten Zeilen werden verworfen. Die Position bleibt erhalten, und es wird kein Alarm ausgelöst.
`ESC`, dann `0x14`	Neustart	Startet die Steuerung neu, auf Platinen, die sich selbst neu starten können.
`?`	Statusbericht	Ein Statusbericht.
`0x80` (oder `0x05`)	Statusbericht	Ein Statusbericht, außer solange automatische Berichte eingeschaltet sind.
`0x87`	Vollständiger Statusbericht	Ein Statusbericht mit allen Feldern.
`~`, `0x81`	Zyklusstart	Setzt nach Vorschub halt, Schutztür, `M0`/`M1` oder Werkzeugwechsel fort.
`!`, `0x82`	Vorschub halt	Die Achsen bremsen bis zum Stillstand ab und halten. Bei einer Tippbewegung bricht er diese ab.
`0x83`	Parserzustand	Meldet den modalen Zustand, wie es `$G` tut.
`0x84`	Schutztür	Wirkt wie das Öffnen der Tür: anhalten und, wenn das Parken eingerichtet ist, parken.
`0x85`	Tippen abbrechen	Beendet eine Tippbewegung und verwirft die noch eingereihten Tippzeilen.
`0x88`	Wahlweiser Halt	Schaltet den wahlweisen Halt (`M1`) ein oder aus.
`0x89`	Einzelsatz	Schaltet den Einzelsatz ein oder aus.
`0x8B`	Handradmodus	Mit angeschlossenem Handrad: schaltet dessen Modus um. Sonst wird er ignoriert.
`0x8C`	Automatische Berichte	Schaltet automatische Statusberichte ein oder aus, wenn `$481` deren Intervall festlegt. Sonst wird er ignoriert.
`0x90`	Vorschub-Override 100 %
`0x91`, `0x92`	Vorschub-Override +10 %, −10 %	Bereich 10–200 %.
`0x93`, `0x94`	Vorschub-Override +1 %, −1 %	Bereich 10–200 %.
`0x95`, `0x96`, `0x97`, `0x98`	Eilgang-Override	100 %, 50 %, 25 %, 5 %.
`0x99`	Spindel-Override 100 %
`0x9A`, `0x9B`	Spindel-Override +10 %, −10 %	Bereich 10–200 %.
`0x9C`, `0x9D`	Spindel-Override +1 %, −1 %	Bereich 10–200 %.
`0x9E`	Spindelstopp	Nur bei Vorschub halt: stoppt die Spindel oder startet sie wieder.
`0x9F`	Software-Not-Halt	Hält sofort an und löst den Not-Halt-Alarm aus.
`0xA0`	Kühlung, Flutkühlung	Schaltet die Flutkühlung ein oder aus.
`0xA1`	Kühlung, Sprühkühlung	Schaltet die Sprühkühlung ein oder aus.
`0xA3`	Werkzeugwechsel fertig	Bestätigt einen manuellen Werkzeugwechsel.

Die Steuerung verwirft andere Steuerbytes und die Bytes 0x80–0xBF, die keinen Befehl haben.

UTF-8-Text in Kommentaren und Meldungen wird als Text gelesen. Ein Byte im Bereich 0x80–0xBF, das zu einem solchen Zeichen gehört, wird nie als Echtzeitbefehl aufgefasst.
$39=0 (herkömmliche Echtzeitzeichen aus): ?, ! und ~ sind in $-Zeilen und Kommentaren Text und überall sonst Befehle. Mit $39=1 (dem Standardwert) sind sie immer Befehle.

Begrüßung und Kennung

Nach dem Einschalten und nach jedem Reset meldet sich die Steuerung mit:

Grbl 1.1f ['$' or '$HELP' for help]

Sender-Programme werten eine Zeile, die mit „Grbl“ beginnt, als Neustart.

$I antwortet mit diesen Zeilen und dann mit ok:

Zeile	Was sie sagt
`[VER:Twinwright 1.1f.<date>:<text>]`	Die Protokollversion und ihr Erstellungsdatum. `<text>` ist das, was `$I=<text>` gespeichert hat.
`[OPT:…]`	Optionsbuchstaben, die Planerblöcke (100) und der Empfangspuffer (1024).
`[NEWOPT:…]`	Optionsnamen: `ENUMS`, `RT+` oder `RT-` (`$39`), `HOME`, `ES`, `MPG`, `LATHE`, `REBOOT`, `TC`, `SS` (Spindelsynchronisation), `SED`, `RTC`, `SD`, `FS`, `YM`.
`[FIRMWARE:Twinwright]`	Der Name der Firmware.
`[SIGNALS:…]`	Die Steuereingänge, die die Platine hat, als Buchstaben.
`[NVS STORAGE:…]`	Wo die Einstellungen gespeichert sind.
`[DRIVER:…]`, `[DRIVER VERSION:…]`, `[DRIVER OPTIONS:…]`, `[BOARD:…]`	Die Platine.
`[KERNEL:<version>+<build>]`	Die Version und der Build der Steuerung: der Commit eines Releases oder `dev`.
`[KNCAP:…]`	Was die Platine hat (siehe unten).
`[PLUGIN:…]`	Funktionen unter den Namen, unter denen Sender-Programme sie kennen: `MODBUS` und `HUANYANG VFD` für den Spindelantrieb.

Was die Platine hat: KNCAP

[KNCAP:] ist eine Zeile aus key=value-Paaren, durch Kommas getrennt. Schlüssel werden immer nur am Ende ergänzt und ändern nie ihre Bedeutung. Lesen Sie die Zeile nach Schlüsseln, nicht nach Positionen. Ein fehlender Schlüssel bedeutet „nicht bekannt“.

Schlüssel	Werte	Bedeutung
`port`	`teensy41`, `stm32h7`, `stm32f4`, `twin`, `host`, `sim`, `unknown`	Welcher Build der Steuerung das ist.
`pv`	eine Zahl	Die Version der Port-Schnittstelle der Steuerung.
`view`	eine Zahl	Die Version der Zustandsansicht der Steuerung.
`spindle`	`vfd`, `pwm`, `none`	Der Spindelantrieb: Modbus, ein PWM-Ausgang oder keiner.
`encoder`	`0`, `1`	Ein Spindel-Encoder ist verbaut.
`sd`	`0`, `1`	Die Platine hat einen SD-Kartenschacht.
`mpg`	`0`, `2`	Ein Handradanschluss, nach seiner Modusnummer.
`aux`	`di/do/ai/ao`	Zusatzeingänge und -ausgänge: digitale Eingänge, digitale Ausgänge, analoge Eingänge, analoge Ausgänge.
`axes`	Buchstaben	Die Achsen, zum Beispiel `XYZ`.
`probe`	`0`, `1`	Ein Messtastereingang. An der MC-1 nutzt ihn auch der Werkzeuglängensensor.
`link`	`usb`, `uart`, `tcp`, `none`	Die Verbindung zum Sender-Programm. `usb` ist ein serieller USB-Port, der antwortet, sobald DTR gesetzt ist.

Der Schattenmodus vergleicht [KERNEL:] und [KNCAP:] zwischen einer realen Maschine und ihrem Zwilling (siehe Echte Maschine und Schattenmodus).

Statusberichte

Ein Statusbericht kommt nach ?, 0x80 oder 0x87. Sind automatische Berichte eingeschaltet ($481, 0x8C), kommt er auch von selbst. Er ist eine einzelne Zeile:

<Idle|MPos:0.000,0.000,0.000|Bf:100,1023|FS:0,0|Pn:XYZ>

Zuerst kommt der Zustand:

Idle, Run, Jog, Home, Check (Prüfmodus), Sleep, Tool (ein Werkzeugwechsel);
Hold:0 (gehalten) und Hold:1 (bremst ab);
Door:0 (geschlossen, bereit zum Fortsetzen), Door:1 (angehalten, noch offen), Door:2 (geöffnet: hält an oder parkt) und Door:3 (geschlossen, stellt wieder her);
Alarm.

Die Felder danach hängen von $10 und von der Situation ab:

Feld	Bedeutung
`MPos:` oder `WPos:`	Maschinen- oder Werkstückposition (`$10`, Bit 0).
`Bf:`	Freie Planerblöcke, freie Bytes im Empfangspuffer.
`Ln:`	Die Satznummer des laufenden Satzes.
`FS:`	Vorschub, die angeforderte Spindeldrehzahl und die Drehzahl, die der Antrieb meldet. Eine Spindel, die nur ein- und ausgeschaltet wird, meldet `F:`. Bei Vorschub halt ist der Vorschub 0.
`Pn:`	Aktive Eingänge: Endschalter mit dem Buchstaben ihrer Achse, `P` Messtaster, `D` Tür, `H` Vorschub halt, `S` Zyklusstart, `R` Reset, `E` Not-Halt.
`WCO:`	Die Nullpunktverschiebung: alle paar Berichte und nach einer Änderung.
`Ov:`	Vorschub-, Eilgang- und Spindel-Override in %: alle paar Berichte und nach einer Änderung.
`A:`	Zubehör: `S` oder `C` Spindel im Uhrzeigersinn oder gegen den Uhrzeigersinn, `F` Flutkühlung, `M` Sprühkühlung.
`Sl:`	Die Last des Spindelantriebs.
`DTG:`	Der Restweg, bis die Achsen anhalten (`$10`, Bit 13).
`H:`	Referenziert oder nicht.
`T:`	Das Werkzeug, während eines Werkzeugwechsels.
`TLR:`	Eine Referenz-Werkzeuglänge ist gesetzt (`$TLR`).
`MPG:`	Das Handrad hat die Kontrolle (1) oder nicht (0).
`In:`	Das Ergebnis des letzten `M66`.
`WCS:`, `Sc:`, `D:`	Das Werkstückkoordinatensystem, die Skalierung, der Durchmessermodus der Drehmaschine (vollständige Berichte).
`AR`, `AR:`	Automatische Berichte aus oder ein, mit ihrem Intervall (vollständige Berichte).
`FW:`	Der Name der Firmware (vollständige Berichte).
`SD:`	Wie weit ein Programm gekommen ist, das aus dem Dateisystem der Steuerung ausgeführt wird.

Weitere Zeilen, die die Steuerung sendet

Zeile	Wann
`ALARM:N`	Ein Alarm. Alarmcodes listet jedes N auf.
`[MSG:…]`	Eine Meldung: die der Steuerung selbst oder das `(MSG,…)`, `(PRINT,…)` oder `(DEBUG,…)` eines Programms.
`[GC:…]`	Der modale Zustand, nach `$G` oder `0x83`. Mit `$10` Bit 9 einmal nach jeder Änderung.
`[PRB:x,y,z:1]`	Der Punkt, an dem der Messtaster ausgelöst hat, und ob er berührt hat (1) oder nicht (0).
`[TLO:…]`	Die Werkzeuglängenkorrektur.
`[PARAM:n=value]`	Nach `$#=n`.
`[G54:…]` … `[G59.3:…]`, `[G28:…]`, `[G30:…]`, `[G92:…]`, `[T:…]`	Nach `$#`: Nullpunktverschiebungen, gespeicherte Positionen, die Werkzeugtabelle.
`>line:ok`, `>line:error:N`	Ein Startsatz (`$N0`, `$N1`) wurde beim Start ausgeführt.

`$`-Befehle

$HELP Commands listet sie auf der Steuerung selbst auf.

Befehl	Was er bewirkt
`$`, `$HELP`, `$HELP <group>`	Hilfe; die Befehle; eine Einstellungsgruppe mit Details.
`$$`, `$<n>`, `$<n>=<value>`, `$$=<n>`, `$+`	Alle Einstellungen; eine Einstellung; sie ändern; die Details einer Einstellung; noch einmal alle Einstellungen.
`$SED=<n>`	Eine Einstellung beschreiben.
`$#`, `$#=<n>`, `$#=<name>`	Nullpunktverschiebungen, das Antastergebnis, gespeicherte Positionen; ein Parameter.
`$G`	Der modale Zustand.
`$I`, `$I+`, `$I=<text>`	Was die Steuerung ist (siehe oben); alles; einen Text dazu speichern.
`$N`, `$N0=<line>`, `$N1=<line>`	Die Startsätze anzeigen oder speichern.
`$C`	Prüfmodus: Der G-Code wird geprüft, und nichts bewegt sich. Ein Reset beendet ihn.
`$X`	Nach einem Alarm entsperren.
`$H`, `$HX`, `$HY`, `$HZ`	Alle Achsen oder eine Achse referenzieren.
`$J=<G-code>`	Tippbewegung.
`$B`, `$S`, `$O`	Satzausblendung, Einzelsatz, wahlweiser Halt: ein oder aus.
`$SLP`	Ruhezustand.
`$TLR`, `$TPW`	Die letzte Antastung als Referenz-Werkzeuglänge übernehmen; das neue Werkzeug auf der Messplatte messen.
$RST=$ , `$RST=#`, `$RST=*`	Die Werkseinstellungen der MC-1 (Referenzfahrt und Endlagen an, ihre Verfahrwege); die Nullpunktverschiebungen löschen; beides sowie die Startsätze.
`$EA`, `$EAG`, `$EE`, `$EEG`, `$EG`, `$ES`, `$ESG`, `$ESH`, `$E*`	Die Alarme, Fehlercodes, Einstellungsgruppen und Einstellungen auflisten, als Zeilen oder als CSV.
`$SPINDLES`, `$SPINDLESH`	Die Spindeln.
`$PINS`, `$PINSTATE`, `$PORTS`	Die Pins der Platine; die Zusatzeingänge und -ausgänge; die seriellen Ports.
`$LIM`, `$HSS`, `$LEV`	Die Endschaltereingänge, die Referenzschalter, die letzten Eingangsereignisse.
`$RTC`, `$RTC=<date and time>`	Die Uhr der Steuerung (ISO 8601).
`$REBOOT`	Die Steuerung neu starten.
`$F`, `$F+`, `$F=<file>`, `$F<=<file>`, `$FR`	Die Programme im Dateisystem der Steuerung auflisten, eines ausführen, eines zurücksenden, von vorn beginnen.
`$FD=`, `$FMD=`, `$FRD=`, `$FF=yes`, `$FI`, `$FM`, `$FU`, `$CWD=`, `$PWD`	Löschen, einen Ordner anlegen oder entfernen, formatieren, Informationen, einbinden, trennen, Arbeitsordner.

Jede Einstellung steht unter Einstellungen.