Protocole

Le noyau propre à Twinwright (le contrôleur) parle le protocole série Grbl 1.1, avec les extensions qu’utilisent les logiciels d’envoi Grbl actuels. Un logiciel d’envoi écrit pour Grbl fonctionne avec lui. Les logiciels d’envoi qui ont été vérifiés, et leurs réglages, sont décrits dans Logiciels d’envoi de G-code.

Connexion

Où	Comment
Le jumeau dans Studio	Port TCP 2323 sur cet ordinateur, un seul logiciel d’envoi à la fois.
La MC-1	Son port USB natif, un port série (COMn sous Windows). Le débit en bauds est sans importance ; utilisez 115 200 là où un logiciel d’envoi en demande un. Le contrôleur répond dès que le logiciel d’envoi lève DTR.

Lignes et réponses

Fins de ligne : une ligne se termine par LF ou CR. Une paire CR LF ou LF CR compte pour une seule fin ; deux LF font deux lignes.
Réponses : le contrôleur répond à chaque ligne par ok ou error:N, dans l’ordre d’arrivée des lignes. Codes d’erreur donne la liste de tous les N.
Longueur de ligne : jusqu’à 256 caractères. Une ligne plus longue reçoit la réponse error:11.
Comptage de caractères : le tampon de réception contient 1 024 octets. Un logiciel d’envoi peut avoir autant d’octets en transit sans réponse. Bf: dans le rapport d’état donne l’espace libre.
Planificateur : 100 blocs. Bf: donne aussi le nombre de blocs libres.
Lignes en attente : pendant un arrêt d’avance ou avec la porte ouverte, les lignes attendent dans le tampon. Elles reçoivent leur réponse quand le cycle redémarre. Une réinitialisation, 0x19 (arrêt), 0x03 ou 0x85 (annulation du déplacement manuel) abandonne les lignes encore en attente.
Après une erreur : la ligne de G-code suivante ne s’exécute pas et reçoit la même erreur. Cela dure jusqu’à une commande $, une ligne vide ou une réinitialisation.

Commandes temps réel

Une commande temps réel est un seul octet. Le contrôleur agit dessus dès son arrivée, même au milieu d’une ligne. Elle ne fait partie d’aucune ligne et ne reçoit pas de ok.

Octet	Commande	Effet
`0x18` (Ctrl-X)	Réinitialisation	Arrête tout aussitôt et vide ce qui est en file d’attente. Une réinitialisation pendant que les axes se déplacent déclenche `ALARM:3` : refaites la prise d’origine. Non prise en compte tant que l’arrêt d’urgence est actif.
`0x03` (Ctrl-C)	Réinitialisation, arrêt d’urgence actif	Comme Ctrl-X, prise en compte aussi quand l’arrêt d’urgence est actif.
`0x19` (Ctrl-Y)	Arrêt	Les axes ralentissent jusqu’à l’arrêt et les lignes encore en file d’attente sont abandonnées. La position est conservée et aucune alarme n’est déclenchée.
`ESC`, puis `0x14`	Redémarrage	Redémarre le contrôleur, sur les cartes capables de redémarrer d’elles-mêmes.
`?`	Rapport d’état	Un rapport d’état.
`0x80` (ou `0x05`)	Rapport d’état	Un rapport d’état, sauf quand les rapports automatiques sont activés.
`0x87`	Rapport d’état complet	Un rapport d’état avec tous les champs.
`~`, `0x81`	Départ cycle	Reprend après un arrêt d’avance, une ouverture de porte, `M0`/`M1` ou un changement d’outil.
`!`, `0x82`	Arrêt d’avance	Les axes ralentissent jusqu’à l’arrêt et restent à l’arrêt. Pendant un déplacement manuel (jog), il l’annule.
`0x83`	État de l’analyseur	Renvoie l’état modal, comme le fait `$G`.
`0x84`	Porte de sécurité	Agit comme l’ouverture de la porte : arrêt d’avance et, si le stationnement est configuré, stationnement.
`0x85`	Annulation du déplacement manuel	Met fin à un déplacement manuel et abandonne les lignes de déplacement manuel encore en file d’attente.
`0x88`	Arrêt optionnel	Active ou désactive les pauses `M1`.
`0x89`	Bloc à bloc	Active ou désactive le bloc à bloc.
`0x8B`	Mode manivelle	Avec une manivelle connectée : change son mode. Sinon, ignoré.
`0x8C`	Rapports automatiques	Active ou désactive les rapports d’état automatiques, lorsque `$481` en fixe l’intervalle. Sinon, ignoré.
`0x90`	Correction d’avance 100 %
`0x91`, `0x92`	Correction d’avance +10 %, −10 %	Plage de 10 à 200 %.
`0x93`, `0x94`	Correction d’avance +1 %, −1 %	Plage de 10 à 200 %.
`0x95`, `0x96`, `0x97`, `0x98`	Correction de rapide	100 %, 50 %, 25 %, 5 %.
`0x99`	Correction de broche 100 %
`0x9A`, `0x9B`	Correction de broche +10 %, −10 %	Plage de 10 à 200 %.
`0x9C`, `0x9D`	Correction de broche +1 %, −1 %	Plage de 10 à 200 %.
`0x9E`	Arrêt broche	Pendant un arrêt d’avance seulement : arrête la broche, ou la relance.
`0x9F`	Arrêt d’urgence logiciel	Arrête aussitôt et déclenche l’alarme d’arrêt d’urgence.
`0xA0`	Refroidissement, arrosage	Active ou désactive l’arrosage.
`0xA1`	Refroidissement, pulvérisation	Active ou désactive la pulvérisation.
`0xA3`	Changement d’outil terminé	Confirme un changement d’outil manuel.

Le contrôleur écarte les autres octets de contrôle, ainsi que ceux de 0x80 à 0xBF qui n’ont pas de commande.

Le texte UTF-8 dans les commentaires et les messages est lu comme du texte. Un octet de 0x80 à 0xBF qui appartient à un tel caractère n’est jamais pris pour une commande temps réel.
$39=0 (anciens caractères temps réel désactivés) : ?, ! et ~ sont du texte dans les lignes $ et les commentaires, et des commandes partout ailleurs. Avec $39=1 (la valeur par défaut), ce sont toujours des commandes.

Accueil et identité

Après la mise sous tension et après chaque réinitialisation, le contrôleur annonce :

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

Les logiciels d’envoi prennent une ligne qui commence par « Grbl » pour un redémarrage.

$I répond par ces lignes, puis ok :

Ligne	Ce qu’elle indique
`[VER:Twinwright 1.1f.<date>:<text>]`	La version du protocole et sa date de compilation. `<text>` est ce qu’a enregistré `$I=<text>`.
`[OPT:…]`	Les lettres d’options, les blocs du planificateur (100) et le tampon de réception (1 024).
`[NEWOPT:…]`	Les noms d’options : `ENUMS`, `RT+` ou `RT-` (`$39`), `HOME`, `ES`, `MPG`, `LATHE`, `REBOOT`, `TC`, `SS` (synchronisation de broche), `SED`, `RTC`, `SD`, `FS`, `YM`.
`[FIRMWARE:Twinwright]`	Le nom du micrologiciel.
`[SIGNALS:…]`	Les entrées de commande que la carte possède, sous forme de lettres.
`[NVS STORAGE:…]`	L’endroit où les réglages sont conservés.
`[DRIVER:…]`, `[DRIVER VERSION:…]`, `[DRIVER OPTIONS:…]`, `[BOARD:…]`	La carte.
`[KERNEL:<version>+<build>]`	La version et la compilation du contrôleur : le commit d’une version publiée, ou `dev`.
`[KNCAP:…]`	Ce que comporte la carte (ci-dessous).
`[PLUGIN:…]`	Des fonctions nommées comme les connaissent les logiciels d’envoi : `MODBUS` et `HUANYANG VFD` pour le variateur de broche.

Ce que comporte la carte : KNCAP

[KNCAP:] est une ligne de paires key=value, séparées par des virgules. Des clés ne sont ajoutées qu’à la fin, et aucune ne change jamais de sens. Lisez la ligne par clé, non par position. Une clé absente signifie « non connu ».

Clé	Valeurs	Signification
`port`	`teensy41`, `stm32h7`, `stm32f4`, `twin`, `host`, `sim`, `unknown`	De quelle compilation du contrôleur il s’agit.
`pv`	un nombre	La version de l’interface de portage du contrôleur.
`view`	un nombre	La version de la vue d’état du contrôleur.
`spindle`	`vfd`, `pwm`, `none`	Le variateur de broche : Modbus, une sortie PWM, ou aucun.
`encoder`	`0`, `1`	Un codeur de broche est installé.
`sd`	`0`, `1`	La carte a un emplacement pour carte SD.
`mpg`	`0`, `2`	Un port de manivelle, avec son numéro de mode.
`aux`	`di/do/ai/ao`	Entrées et sorties auxiliaires : entrées numériques, sorties numériques, entrées analogiques, sorties analogiques.
`axes`	des lettres	Les axes, par exemple `XYZ`.
`probe`	`0`, `1`	Une entrée de palpeur. Sur la MC-1, le capteur de longueur d’outil l’utilise aussi.
`link`	`usb`, `uart`, `tcp`, `none`	La liaison du logiciel d’envoi. `usb` est un port série USB qui répond dès que DTR est levé.

Le mode ombre compare [KERNEL:] et [KNCAP:] entre une machine réelle et son jumeau (voir Machine réelle et mode ombre).

Rapports d’état

Un rapport d’état arrive après ?, 0x80 ou 0x87. Quand les rapports automatiques sont activés ($481, 0x8C), il arrive aussi de lui-même. C’est une seule ligne :

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

L’état vient en premier :

Idle, Run, Jog, Home, Check (mode vérification), Sleep, Tool (un changement d’outil) ;
Hold:0 (suspendu) et Hold:1 (en train de ralentir) ;
Door:0 (fermée, prête à reprendre), Door:1 (arrêtée, encore ouverte), Door:2 (ouverte : arrêt d’avance ou stationnement) et Door:3 (fermée, rétablissement) ;
Alarm.

Les champs qui suivent dépendent de $10 et de la situation :

Champ	Signification
`MPos:` ou `WPos:`	Position machine ou position pièce (`$10` bit 0).
`Bf:`	Blocs libres du planificateur, octets libres du tampon de réception.
`Ln:`	Le numéro de ligne du bloc en cours d’exécution.
`FS:`	La vitesse d’avance, la vitesse de broche demandée et la vitesse que rapporte le variateur. Une broche à simple marche/arrêt rapporte `F:`. Pendant un arrêt d’avance, l’avance est de 0.
`Pn:`	Entrées actives : les fins de course par lettre d’axe, `P` palpeur, `D` porte, `H` arrêt d’avance, `S` départ cycle, `R` réinitialisation, `E` arrêt d’urgence.
`WCO:`	Le décalage d’origine : tous les quelques rapports, et après un changement.
`Ov:`	Les corrections d’avance, de rapide et de broche en % : tous les quelques rapports, et après un changement.
`A:`	Accessoires : `S` ou `C` broche tournant dans le sens horaire ou antihoraire, `F` arrosage, `M` pulvérisation.
`Sl:`	La charge du variateur de broche.
`DTG:`	La distance restante, jusqu’à l’arrêt des axes (`$10` bit 13).
`H:`	Prise d’origine faite ou non.
`T:`	L’outil, pendant un changement d’outil.
`TLR:`	Une longueur d’outil de référence est définie (`$TLR`).
`MPG:`	La manivelle a le contrôle (1) ou non (0).
`In:`	Le résultat du dernier `M66`.
`WCS:`, `Sc:`, `D:`	Le système de coordonnées pièce, la mise à l’échelle, le mode diamètre du tour (rapports complets).
`AR`, `AR:`	Rapports automatiques désactivés, ou activés avec leur intervalle (rapports complets).
`FW:`	Le nom du micrologiciel (rapports complets).
`SD:`	L’avancement d’un programme exécuté depuis le système de fichiers du contrôleur.

Autres lignes envoyées par le contrôleur

Ligne	Quand
`ALARM:N`	Une alarme. Codes d’alarme donne la liste de tous les N.
`[MSG:…]`	Un message : celui du contrôleur, ou le `(MSG,…)`, `(PRINT,…)` ou `(DEBUG,…)` d’un programme.
`[GC:…]`	L’état modal, après `$G` ou `0x83`. Avec `$10` bit 9, une fois après chaque changement.
`[PRB:x,y,z:1]`	Le point où le palpeur s’est déclenché, et s’il a touché (1) ou non (0).
`[TLO:…]`	La correction de longueur d’outil.
`[PARAM:n=value]`	Après `$#=n`.
`[G54:…]` … `[G59.3:…]`, `[G28:…]`, `[G30:…]`, `[G92:…]`, `[T:…]`	Après `$#` : les décalages, les positions mémorisées, la table d’outils.
`>line:ok`, `>line:error:N`	Une ligne de démarrage (`$N0`, `$N1`) s’est exécutée au démarrage.

Commandes `$`

$HELP Commands les liste sur le contrôleur lui-même.

Commande	Effet
`$`, `$HELP`, `$HELP <group>`	L’aide ; les commandes ; un groupe de réglages avec détails.
`$$`, `$<n>`, `$<n>=<value>`, `$$=<n>`, `$+`	Tous les réglages ; un réglage ; le modifier ; les détails d’un réglage ; de nouveau tous les réglages.
`$SED=<n>`	Décrire un réglage.
`$#`, `$#=<n>`, `$#=<name>`	Les décalages, le résultat du palpage, les positions mémorisées ; un paramètre.
`$G`	L’état modal.
`$I`, `$I+`, `$I=<text>`	Ce qu’est le contrôleur (ci-dessus) ; tout ; enregistrer un texte qui l’accompagne.
`$N`, `$N0=<line>`, `$N1=<line>`	Afficher ou enregistrer les lignes de démarrage.
`$C`	Mode vérification : le G-code est vérifié et rien ne bouge. Une réinitialisation y met fin.
`$X`	Déverrouiller après une alarme.
`$H`, `$HX`, `$HY`, `$HZ`	Faire la prise d’origine de tous les axes, ou d’un seul.
`$J=<G-code>`	Déplacement manuel (jog).
`$B`, `$S`, `$O`	Saut de bloc, bloc à bloc, arrêt optionnel : activés ou désactivés.
`$SLP`	Veille.
`$TLR`, `$TPW`	Prendre le dernier palpage comme longueur d’outil de référence ; mesurer le nouvel outil sur la plaque de contact.
$RST=$ , `$RST=#`, `$RST=*`	Les réglages d’usine de la MC-1 (prise d’origine et fins de course actives, ses courses) ; effacer les décalages ; les deux, plus les lignes de démarrage.
`$EA`, `$EAG`, `$EE`, `$EEG`, `$EG`, `$ES`, `$ESG`, `$ESH`, `$E*`	Lister les alarmes, les codes d’erreur, les groupes de réglages et les réglages, en lignes ou en CSV.
`$SPINDLES`, `$SPINDLESH`	Les broches.
`$PINS`, `$PINSTATE`, `$PORTS`	Les pins de la carte ; les entrées et sorties auxiliaires ; les ports série.
`$LIM`, `$HSS`, `$LEV`	Les entrées de fin de course, les capteurs d’origine, les derniers événements d’entrée.
`$RTC`, `$RTC=<date and time>`	L’horloge du contrôleur (ISO 8601).
`$REBOOT`	Redémarrer le contrôleur.
`$F`, `$F+`, `$F=<file>`, `$F<=<file>`, `$FR`	Lister les programmes du système de fichiers du contrôleur, en exécuter un, en renvoyer un, recommencer.
`$FD=`, `$FMD=`, `$FRD=`, `$FF=yes`, `$FI`, `$FM`, `$FU`, `$CWD=`, `$PWD`	Supprimer, créer ou supprimer un dossier, formater, informations, monter, démonter, dossier de travail.

Chaque réglage figure dans Réglages.