Documentation Reference

Protocol

The Twinwright controller (kernel) speaks the Grbl 1.1 serial protocol, with the extensions that current Grbl senders use. A sender written for Grbl works with it. The senders that were checked, and their settings, are in G-code senders.

Connect

Where	How
The twin in Studio	TCP port 2323 on this computer, one sender at a time.
The MC-1	Its native USB port, a serial port (COMn on Windows). The baud rate does not matter; use 115200 where a sender asks for one. The controller answers once the sender raises DTR.

Lines and answers

Line ends: a line ends with LF or CR. A CR LF or LF CR pair counts once; two LFs are two lines.
Answers: the controller answers every line with ok or error:N, in the order the lines came. Error codes lists every N.
Line length: up to 256 characters. A longer line answers error:11.
Character counting: the receive buffer holds 1024 bytes. A sender may keep that many unanswered bytes in flight. Bf: in the status report gives the free space.
Planner: 100 blocks. Bf: gives the free blocks too.
Lines that wait: in a feed hold or with the door open, lines wait in the buffer. They are answered once the cycle starts again. A reset, 0x19 (stop), 0x03 or 0x85 (jog cancel) drops the lines still waiting.
After an error: the next G-code line does not run and answers the same error. This goes on until a $ command, an empty line or a reset.

Real-time commands

A real-time command is a single byte. The controller acts on it as it arrives, even in the middle of a line. It is not part of any line and gets no ok.

Byte	Command	What it does
`0x18` (Ctrl-X)	Reset	Stops everything at once and clears what is queued. A reset while the axes move raises `ALARM:3`: home again. Not taken while the E-stop is on.
`0x03` (Ctrl-C)	Reset, E-stop on	As Ctrl-X, also taken while the E-stop is on.
`0x19` (Ctrl-Y)	Stop	The axes slow down to a stop, and the lines still queued are dropped. The position is kept, and no alarm is raised.
`ESC`, then `0x14`	Reboot	Restarts the controller, on boards that can restart themselves.
`?`	Status report	One status report.
`0x80` (or `0x05`)	Status report	One status report, except while automatic reports are on.
`0x87`	Full status report	One status report with every field.
`~`, `0x81`	Cycle start	Resumes after a feed hold, the door, `M0`/`M1` or a tool change.
`!`, `0x82`	Feed hold	The axes slow down to a stop and hold. During a jog, it cancels the jog.
`0x83`	Parser state	Reports the modal state, as `$G` does.
`0x84`	Safety door	Acts as the door opening: hold, and park if parking is set up.
`0x85`	Jog cancel	Ends a jog and drops the jog lines still queued.
`0x88`	Optional stop	Switches `M1` pauses on or off.
`0x89`	Single block	Switches single block on or off.
`0x8B`	Handwheel mode	With a handwheel connected: switches its mode. Otherwise ignored.
`0x8C`	Automatic reports	Switches automatic status reports on or off, when `$481` sets their interval. Otherwise ignored.
`0x90`	Feed override 100 %
`0x91`, `0x92`	Feed override +10 %, −10 %	Range 10–200 %.
`0x93`, `0x94`	Feed override +1 %, −1 %	Range 10–200 %.
`0x95`, `0x96`, `0x97`, `0x98`	Rapid override	100 %, 50 %, 25 %, 5 %.
`0x99`	Spindle override 100 %
`0x9A`, `0x9B`	Spindle override +10 %, −10 %	Range 10–200 %.
`0x9C`, `0x9D`	Spindle override +1 %, −1 %	Range 10–200 %.
`0x9E`	Spindle stop	In a feed hold only: stops the spindle, or starts it again.
`0x9F`	Soft E-stop	Stops at once and raises the E-stop alarm.
`0xA0`	Coolant, flood	Switches flood coolant on or off.
`0xA1`	Coolant, mist	Switches mist coolant on or off.
`0xA3`	Tool change done	Confirms a manual tool change.

The controller drops other control bytes, and the bytes 0x80–0xBF that have no command.

UTF-8 text in comments and messages is read as text. A byte in 0x80–0xBF that belongs to such a character is never taken as a real-time command.
$39=0 (legacy real-time characters off): ?, ! and ~ are text inside $ lines and comments, and commands everywhere else. With $39=1 (the default) they are always commands.

Welcome and identity

After power-on and after every reset, the controller says:

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

Senders take a line that starts with "Grbl" as a restart.

$I answers with these lines, then ok:

Line	What it says
`[VER:Twinwright 1.1f.<date>:<text>]`	The protocol version and its build date. `<text>` is what `$I=<text>` stored.
`[OPT:…]`	Option letters, the planner blocks (100) and the receive buffer (1024).
`[NEWOPT:…]`	Option names: `ENUMS`, `RT+` or `RT-` (`$39`), `HOME`, `ES`, `MPG`, `LATHE`, `REBOOT`, `TC`, `SS` (spindle sync), `SED`, `RTC`, `SD`, `FS`, `YM`.
`[FIRMWARE:Twinwright]`	The firmware's name.
`[SIGNALS:…]`	The control inputs the board has, as letters.
`[NVS STORAGE:…]`	Where the settings are kept.
`[DRIVER:…]`, `[DRIVER VERSION:…]`, `[DRIVER OPTIONS:…]`, `[BOARD:…]`	The board.
`[KERNEL:<version>+<build>]`	The controller's version and build: the commit of a release, or `dev`.
`[KNCAP:…]`	What the board has (below).
`[PLUGIN:…]`	Functions named as senders know them: `MODBUS` and `HUANYANG VFD` for the spindle drive.

What the board has: KNCAP

[KNCAP:] is one line of key=value pairs, separated by commas. Keys are only ever added at the end and never change their meaning. Read the line by key, not by position. A key that is missing means "not known".

Key	Values	Meaning
`port`	`teensy41`, `stm32h7`, `stm32f4`, `twin`, `host`, `sim`, `unknown`	Which build of the controller this is.
`pv`	a number	The version of the controller's port interface.
`view`	a number	The version of the controller's state view.
`spindle`	`vfd`, `pwm`, `none`	The spindle drive: Modbus, a PWM output, or none.
`encoder`	`0`, `1`	A spindle encoder is fitted.
`sd`	`0`, `1`	The board has an SD card slot.
`mpg`	`0`, `2`	A handwheel port, by its mode number.
`aux`	`di/do/ai/ao`	Auxiliary inputs and outputs: digital in, digital out, analog in, analog out.
`axes`	letters	The axes, for example `XYZ`.
`probe`	`0`, `1`	A probe input. On the MC-1 the tool setter uses it too.
`link`	`usb`, `uart`, `tcp`, `none`	The sender's link. `usb` is a USB serial port that answers once DTR is up.

Shadow mode compares [KERNEL:] and [KNCAP:] between a real machine and its twin (see Real machine and shadow mode).

Status reports

A status report comes after ?, 0x80 or 0x87. With automatic reports on ($481, 0x8C), it also comes by itself. It is one line:

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

The state comes first:

Idle, Run, Jog, Home, Check (check mode), Sleep, Tool (a tool change);
Hold:0 (held) and Hold:1 (slowing down);
Door:0 (closed, ready to resume), Door:1 (stopped, still open), Door:2 (opened: holding or parking) and Door:3 (closed, restoring);
Alarm.

The fields after it depend on $10 and on the situation:

Field	Meaning
`MPos:` or `WPos:`	Machine or work position (`$10` bit 0).
`Bf:`	Free planner blocks, free receive buffer bytes.
`Ln:`	The line number of the block that runs.
`FS:`	Feed rate, the spindle speed asked for, and the speed the drive reports. A spindle that only goes on and off reports `F:`. In a feed hold the feed is 0.
`Pn:`	Active inputs: limits by axis letter, `P` probe, `D` door, `H` feed hold, `S` cycle start, `R` reset, `E` E-stop.
`WCO:`	The work coordinate offset: every few reports, and after a change.
`Ov:`	Feed, rapid and spindle overrides in %: every few reports, and after a change.
`A:`	Accessories: `S` or `C` spindle clockwise or counter-clockwise, `F` flood, `M` mist.
`Sl:`	The spindle drive's load.
`DTG:`	The distance to go, until the axes stop (`$10` bit 13).
`H:`	Homed or not.
`T:`	The tool, during a tool change.
`TLR:`	A reference tool length is set (`$TLR`).
`MPG:`	The handwheel has control (1) or not (0).
`In:`	The result of the last `M66`.
`WCS:`, `Sc:`, `D:`	The work coordinate system, the scaling, lathe diameter mode (full reports).
`AR`, `AR:`	Automatic reports off, or on with their interval (full reports).
`FW:`	The firmware's name (full reports).
`SD:`	How far a program run from the controller's file system has got.

Other lines the controller sends

Line	When
`ALARM:N`	An alarm. Alarm codes lists every N.
`[MSG:…]`	A message: the controller's own, or a program's `(MSG,…)`, `(PRINT,…)` or `(DEBUG,…)`.
`[GC:…]`	The modal state, after `$G` or `0x83`. With `$10` bit 9, once after each change.
`[PRB:x,y,z:1]`	The point where the probe triggered, and whether it touched (1) or not (0).
`[TLO:…]`	The tool length offset.
`[PARAM:n=value]`	After `$#=n`.
`[G54:…]` … `[G59.3:…]`, `[G28:…]`, `[G30:…]`, `[G92:…]`, `[T:…]`	After `$#`: offsets, stored positions, the tool table.
`>line:ok`, `>line:error:N`	A startup line (`$N0`, `$N1`) ran at start.

`$` commands

$HELP Commands lists them on the controller itself.

Command	What it does
`$`, `$HELP`, `$HELP <group>`	Help; the commands; a settings group with details.
`$$`, `$<n>`, `$<n>=<value>`, `$$=<n>`, `$+`	All settings; one setting; change it; one setting's details; all settings again.
`$SED=<n>`	Describe a setting.
`$#`, `$#=<n>`, `$#=<name>`	Offsets, the probe result, stored positions; one parameter.
`$G`	The modal state.
`$I`, `$I+`, `$I=<text>`	What the controller is (above); everything; store a text with it.
`$N`, `$N0=<line>`, `$N1=<line>`	Show or store the startup lines.
`$C`	Check mode: G-code is checked and nothing moves. A reset ends it.
`$X`	Unlock after an alarm.
`$H`, `$HX`, `$HY`, `$HZ`	Home all axes, or one axis.
`$J=<G-code>`	Jog.
`$B`, `$S`, `$O`	Block delete, single block, optional stop: on or off.
`$SLP`	Sleep.
`$TLR`, `$TPW`	Take the last probing as the reference tool length; measure the new tool on the touch plate.
$RST=$ , `$RST=#`, `$RST=*`	The MC-1's factory settings (homing and the limits on, its travel); clear the offsets; both, and the startup lines.
`$EA`, `$EAG`, `$EE`, `$EEG`, `$EG`, `$ES`, `$ESG`, `$ESH`, `$E*`	List the alarms, error codes, setting groups and settings, as lines or as CSV.
`$SPINDLES`, `$SPINDLESH`	The spindles.
`$PINS`, `$PINSTATE`, `$PORTS`	The board's pins; the auxiliary inputs and outputs; the serial ports.
`$LIM`, `$HSS`, `$LEV`	The limit inputs, the home switches, the last input events.
`$RTC`, `$RTC=<date and time>`	The controller's clock (ISO 8601).
`$REBOOT`	Restart the controller.
`$F`, `$F+`, `$F=<file>`, `$F<=<file>`, `$FR`	List the programs on the controller's file system, run one, send one back, start over.
`$FD=`, `$FMD=`, `$FRD=`, `$FF=yes`, `$FI`, `$FM`, `$FU`, `$CWD=`, `$PWD`	Delete, make or remove a folder, format, information, mount, unmount, working folder.

Every setting is in Settings.