文档接口参考

协议

同匠自研内核说 Grbl 1.1 的串口协议，带现在的 Grbl 发送软件用的那些扩展。为 Grbl 写的发送软件都能连。验过的发送软件和它们的设置见 G 代码发送软件。

连接

连哪里	怎么连
Studio 里的孪生	本机的 TCP 端口 2323，一次一个发送软件。
MC-1	它的原生 USB 口，是一个串口（Windows 上是 COMn）。波特率不起作用；发送软件要填时填 115200。发送软件拉高 DTR 以后控制器才应答。

行和应答

行尾： LF 或 CR 结束一行。CR LF 或 LF CR 连着只算一个行尾；两个 LF 是两行。
应答： 每一行控制器都答 ok 或 error:N，按行来的顺序。每个 N 见错误码。
行长： 最多 256 个字符。更长的行答 error:11。
字符计数： 接收缓冲区 1024 字节。发送软件最多可以有这么多字节已发出、还没得到应答。状态报告里的 Bf: 给出剩下的空间。
规划器： 100 个块。Bf: 也给出空着的块数。
等着的行： 进给保持或开门时，行在缓冲区里等着，循环再启动后才得到应答。复位、0x19（停止）、0x03 或 0x85（取消点动）会扔掉还在等的行。
出错之后： 下一行 G 代码不执行，照答同一个错误，直到来一条 $ 命令、一个空行或复位。

实时命令

实时命令是单个字节。控制器一收到就执行，哪怕正在一行的中间。它不属于任何一行，也没有 ok。

字节	命令	做什么
`0x18`（Ctrl-X）	复位	立刻全部停下，清掉排着的东西。轴在走时复位会报 `ALARM:3`：要重新回零。急停按着时不接受。
`0x03`（Ctrl-C）	复位（急停按着时也行）	同 Ctrl-X，急停按着时也接受。
`0x19`（Ctrl-Y）	停止	轴减速停下，扔掉还排着的行。位置不丢，不报警。
`ESC` 再 `0x14`	重启	重启控制器，只在能自己重启的板子上。
`?`	状态报告	一份状态报告。
`0x80`（或 `0x05`）	状态报告	一份状态报告；自动报告开着时不答。
`0x87`	完整的状态报告	一份带全部字段的状态报告。
`~`、`0x81`	循环启动	从进给保持、安全门、`M0`/`M1` 或换刀之后接着走。
`!`、`0x82`	进给保持	轴减速停下并保持。点动中则取消点动。
`0x83`	解析器状态	报出模态，同 `$G`。
`0x84`	安全门	当作安全门打开：保持，设了停车就停车。
`0x85`	取消点动	结束点动，扔掉还排着的点动行。
`0x88`	选择停止	打开或关掉 `M1` 的停止。
`0x89`	单段	打开或关掉单段。
`0x8B`	手轮方式	接了手轮时切换它的方式；没接时不理。
`0x8C`	自动报告	`$481` 设了间隔时，打开或关掉自动状态报告；否则不理。
`0x90`	进给倍率 100 %
`0x91`、`0x92`	进给倍率 +10 %、−10 %	范围 10–200 %。
`0x93`、`0x94`	进给倍率 +1 %、−1 %	范围 10–200 %。
`0x95`、`0x96`、`0x97`、`0x98`	快移倍率	100 %、50 %、25 %、5 %。
`0x99`	主轴倍率 100 %
`0x9A`、`0x9B`	主轴倍率 +10 %、−10 %	范围 10–200 %。
`0x9C`、`0x9D`	主轴倍率 +1 %、−1 %	范围 10–200 %。
`0x9E`	主轴停	只在进给保持时：停主轴，或再开起来。
`0x9F`	软急停	立刻停下，报急停的报警。
`0xA0`	冷却：浇注	打开或关掉浇注。
`0xA1`	冷却：喷雾	打开或关掉喷雾。
`0xA3`	换刀完成	确认手动换刀做完了。

别的控制字节，以及 0x80–0xBF 里没有命令的字节，控制器都扔掉。

注释和消息里的 UTF-8 文字 当文字读。属于这种字的 0x80–0xBF 字节，从不当成实时命令。
$39=0（关掉老式实时字符）：?、!、~ 在 $ 行和注释里是文字，在别处照常是命令。$39=1（默认）时它们总是命令。

欢迎行和身份

开机以后、每次复位以后，控制器都说：

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

发送软件把以 “Grbl” 开头的行当作控制器重启了。

$I 答下面这些行，最后是 ok：

行	说什么
`[VER:Twinwright 1.1f.<日期>:<文字>]`	协议版本和它的构建日期。`<文字>` 是 `$I=<文字>` 存的。
`[OPT:…]`	选项字母、规划器的块数（100）和接收缓冲区（1024）。
`[NEWOPT:…]`	选项名：`ENUMS`、`RT+` 或 `RT-`（`$39`）、`HOME`、`ES`、`MPG`、`LATHE`、`REBOOT`、`TC`、`SS`（主轴同步）、`SED`、`RTC`、`SD`、`FS`、`YM`。
`[FIRMWARE:Twinwright]`	固件的名字。
`[SIGNALS:…]`	板子有的控制输入，用字母表示。
`[NVS STORAGE:…]`	设置存在哪里。
`[DRIVER:…]`、`[DRIVER VERSION:…]`、`[DRIVER OPTIONS:…]`、`[BOARD:…]`	板子。
`[KERNEL:<版本>+<构建>]`	控制器的版本和构建：发布版是提交号，开发版是 `dev`。
`[KNCAP:…]`	板子有什么（见下）。
`[PLUGIN:…]`	用发送软件认得的名字说的功能：主轴驱动是 `MODBUS` 和 `HUANYANG VFD`。

板子有什么：KNCAP

[KNCAP:] 是一行 键=值，用逗号分开。键只往后加，意思永远不变。按键名读，不要按位置读。缺了某个键表示“不知道”。

键	值	意思
`port`	`teensy41`、`stm32h7`、`stm32f4`、`twin`、`host`、`sim`、`unknown`	这是控制器的哪一种构建。
`pv`	一个数	控制器端口接口的版本。
`view`	一个数	控制器状态视图的版本。
`spindle`	`vfd`、`pwm`、`none`	主轴驱动：Modbus、一路 PWM 输出，或者没有。
`encoder`	`0`、`1`	装了主轴编码器。
`sd`	`0`、`1`	板子有 SD 卡槽。
`mpg`	`0`、`2`	手轮口，按它的方式号。
`aux`	`di/do/ai/ao`	辅助输入输出：数字入、数字出、模拟入、模拟出。
`axes`	字母	轴，比如 `XYZ`。
`probe`	`0`、`1`	测头输入。MC-1 的对刀仪也用它。
`link`	`usb`、`uart`、`tcp`、`none`	发送软件那条链路。`usb` 是 USB 串口，DTR 拉高后才应答。

影子模式拿真机和它的孪生的 [KERNEL:]、[KNCAP:] 对比（见真机和影子模式）。

状态报告

收到 ?、0x80 或 0x87 时发一份状态报告。自动报告开着时（$481、0x8C）也自己发。它是一行：

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

最前面是状态：

Idle（空闲）、Run（运行）、Jog（点动）、Home（回零）、Check（检查模式）、Sleep（休眠）、Tool（换刀）；
Hold:0（已停住）和 Hold:1（正在减速）；
Door:0（门关了，可以接着走）、Door:1（停住了，门还开着）、Door:2（门开了：保持或停车中）、Door:3（门关了，正在恢复）；
Alarm（报警）。

后面的字段看 $10 和当时的情况：

字段	意思
`MPos:` 或 `WPos:`	机床坐标或工件坐标（`$10` 第 0 位）。
`Bf:`	空着的规划块，接收缓冲区剩下的字节。
`Ln:`	正在执行的那一段的行号。
`FS:`	进给速度、要的主轴转速、驱动报回来的转速。只能开关的主轴报 `F:`。进给保持时进给是 0。
`Pn:`	有信号的输入：限位按轴的字母，`P` 测头、`D` 安全门、`H` 进给保持、`S` 循环启动、`R` 复位、`E` 急停。
`WCO:`	工件坐标的偏置：隔几份报告一次，变了以后一次。
`Ov:`	进给、快移、主轴的倍率（%）：隔几份报告一次，变了以后一次。
`A:`	附件：`S` 或 `C` 主轴正转或反转，`F` 浇注，`M` 喷雾。
`Sl:`	主轴驱动的负载。
`DTG:`	剩余距离，一直报到轴停下（`$10` 第 13 位）。
`H:`	回过零没有。
`T:`	换刀时的刀号。
`TLR:`	设了参考刀长（`$TLR`）。
`MPG:`	手轮在控制（1）还是没有（0）。
`In:`	上一个 `M66` 的结果。
`WCS:`、`Sc:`、`D:`	工件坐标系、缩放、车床直径方式（完整报告里有）。
`AR`、`AR:`	自动报告关着，或开着和它的间隔（完整报告里有）。
`FW:`	固件的名字（完整报告里有）。
`SD:`	从控制器文件系统跑的程序走到哪了。

控制器发的别的行

行	什么时候
`ALARM:N`	报警。每个 N 见报警码。
`[MSG:…]`	消息：控制器自己的，或者程序里的 `(MSG,…)`、`(PRINT,…)`、`(DEBUG,…)`。
`[GC:…]`	模态，在 `$G` 或 `0x83` 之后。`$10` 第 9 位打开时，每变一次发一行。
`[PRB:x,y,z:1]`	测头触发的那一点，以及碰到了（1）还是没碰到（0）。
`[TLO:…]`	刀长补偿。
`[PARAM:n=值]`	在 `$#=n` 之后。
`[G54:…]` … `[G59.3:…]`、`[G28:…]`、`[G30:…]`、`[G92:…]`、`[T:…]`	在 `$#` 之后：各偏置、存的位置、刀具表。
`>行:ok`、`>行:error:N`	开机时跑了一条开机行（`$N0`、`$N1`）。

`$` 命令

$HELP Commands 在控制器上列出它们。

命令	做什么
`$`、`$HELP`、`$HELP <组>`	帮助；命令；一组设置和它们的详细说明。
`$$`、`$<n>`、`$<n>=<值>`、`$$=<n>`、`$+`	全部设置；一个设置；改它；一个设置的详细说明；再列一遍全部设置。
`$SED=<n>`	说明一个设置。
`$#`、`$#=<n>`、`$#=<名字>`	各偏置、探测结果、存的位置；一个参数。
`$G`	模态。
`$I`、`$I+`、`$I=<文字>`	控制器是什么（见上）；全部；和它一起存一段文字。
`$N`、`$N0=<行>`、`$N1=<行>`	看或存开机行。
`$C`	检查模式：只检查 G 代码，什么也不动。复位退出。
`$X`	报警后解锁。
`$H`、`$HX`、`$HY`、`$HZ`	全部轴回零，或一根轴回零。
`$J=<G 代码>`	点动。
`$B`、`$S`、`$O`	跳段、单段、选择停止：开或关。
`$SLP`	休眠。
`$TLR`、`$TPW`	把上一次探测当作参考刀长；在对刀板上量新刀。
$RST=$ 、`$RST=#`、`$RST=*`	设置回 MC-1 的出厂值（回零和限位都开、它的行程）；清掉偏置；两样都做，并清掉开机行。
`$EA`、`$EAG`、`$EE`、`$EEG`、`$EG`、`$ES`、`$ESG`、`$ESH`、`$E*`	列出报警、错误码、设置分组和设置，按行或按 CSV。
`$SPINDLES`、`$SPINDLESH`	主轴。
`$PINS`、`$PINSTATE`、`$PORTS`	板子的引脚；辅助输入输出；串口。
`$LIM`、`$HSS`、`$LEV`	限位输入、回零开关、最近的输入事件。
`$RTC`、`$RTC=<日期和时间>`	控制器的时钟（ISO 8601）。
`$REBOOT`	重启控制器。
`$F`、`$F+`、`$F=<文件>`、`$F<=<文件>`、`$FR`	列出控制器文件系统里的程序，跑一个，送回一个，从头再来。
`$FD=`、`$FMD=`、`$FRD=`、`$FF=yes`、`$FI`、`$FM`、`$FU`、`$CWD=`、`$PWD`	删除，建或删文件夹，格式化，信息，挂载，卸载，工作文件夹。

全部设置见设置。

协议

连接