This is the manual of Studio 1.1.0, an earlier version. The manual of the latest version

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.