简介：这是一份基于grbl v1.1的完整开源源码包，面向桌面级CNC雕刻机与3D打印机的嵌入式开发者、硬件爱好者和二次开发人员，用于在Arduino平台上实现高效率、低成本的G代码解释与运动控制。压缩包共69个文件，以C语言源码（18个.c、21个.h）为核心，辅以Arduino烧录所需的.ino工程文件、构建用的Makefile、配置说明文档（txt、md）以及用于自动化测试或脚本分析的Python脚本，整体包体约301KB，结构清晰，便于定位主控逻辑、驱动层与文档资料。该资源已被1390人浏览学习，说明了其在DIY数控领域的实用价值。通过阅读这份源码，用户可以深入理解grbl v1.1的实时运动规划、多轴插补、限位与冷却控制、串口通信及状态反馈机制，也可直接修改并烧录到Arduino板中，为自建雕刻机或3D打印机定制固件功能，适合希望从源码层面掌握CNC系统原理并开展二次开发的实践者。
1. 为什么桌面级 CNC 大多跑在 grbl v1.1 上
grbl v1.1 这个版本号在 CNC 圈子里几乎等同于“桌面级雕刻机的默认固件”。很多人以为它只是一个 G 代码解释器，实际上它内置了环形缓冲区、前瞻加减速规划和步进脉冲生成，是一个完整的硬实时运动控制内核。它跑在 Arduino Uno/Mega 这类 8 位 MCU 上，把上位机（如 Candle、LaserGRBL、OpenBuilds Control）发来的 G 代码解析成步进电机的方向脉冲和速度脉冲，直接驱动雕刻机或 3D 打印机的 XYZ 轴。如果你正在组装 3018、coreXY 三轴机，或者打算把手里的 Arduino 改造成 CNC 控制器，这篇内容会把 grbl v1.1 的源码结构、编译烧录、参数调优和常见报错一次讲透。
2. grbl v1.1 的运动控制核心：环形缓冲、前瞻规划与脉冲生成
2.1 环形缓冲区：串口接收与运动规划的松耦合
grbl 的实时性建立在一个关键设计上：串口中断接收 G 代码字符后，不直接执行，而是写入一个环形缓冲区。主循环从缓冲区读字节，拼成整行命令后交给协议层解析。这样可以避免在执行急停或 G94 切换进给模式时，因为串口超时丢数据。
// protocol.c 中串口接收环形缓冲区的核心参数 #define RX_BUFFER_SIZE 128 #define BLOCK_BUFFER_SIZE 16 // 串口接收中断服务，将字符存入环形缓冲区 ISR(USART_RX_vect) { uint8_t data = UDR0; // 从硬件寄存器读取一个字节 uint8_t next_head = (rx_buffer_head + 1) % RX_BUFFER_SIZE; if (next_head != rx_buffer_tail) { // 防止覆盖尚未取走的数据 rx_buffer[rx_buffer_head] = data; rx_buffer_head = next_head; } else { // 缓冲区满时置位溢出标志，上位机最终会收到 ! 或 ? 反馈 rx_buffer_overflow = true; } }这段代码说明了两件事：第一，串口中断只做“存字节”，不做 G 代码解析，保证 RX 不阻塞；第二，缓冲区大小只有 128 字节，所以上位机需要用 RTS/CTS 软件流控或等 grbl 的ok应答再发下一行。常见的 grbl 上位机都会主动维护发送窗口，如果你直接手动用串口调试工具刷G0 X10，会发现发太快会丢ok，这不是固件 bug，而是协议限制。
2.2 前瞻规划器：为什么每个运动块都有 entry_speed
grbl v1.1 的 planner 采用“梯形速度曲线 + 前瞻斜坡规划”。每一段 G 代码经解析后生成一个block_t运动块，planner 会检查前一个 block 的结束速度能否平滑过渡到当前 block 的起始速度。如果路径有 90 度折角，最大允许入口速度会被压低，防止角部过切。
// planner.h 中运动数据块结构（简化关键字段） typedef struct { uint32_t steps[3]; // 三轴步数，由毫米数乘以每毫米步数得到 uint32_t step_event_count; // 最长轴步数，插补时作为主参考计数 float acceleration; // 加速度 mm/s^2 float rate_delta; // 该 block 内每秒速度增量 float entry_speed; // 进入本段的转速 mm/s float max_entry_speed; // 前视限幅后的最大允许进入速度 float nominal_speed; // 本段稳定速度 mm/s uint8_t flag; // 方向与模式标志 } block_t;rate_delta由加速度和步进当量计算，max_entry_speed则由前后两段 V 形速度计算。要实现“不丢步”的雕刻，关键在于把$110/$111/$112（三轴最大速率）设定为电机实际能跟上的速度，而不是任意数值。如果看到留痕抖动或电机尖啸，多数是rate_delta太大，或者加速度$120超过电机扭矩。grbl 官方默认的1 轴加速度是 10 mm/s^2，对 3018 这类轻载机器够用，但换成龙门铣就需要降。
2.3 步进脉冲生成：定时器中断里的 step_pulse
运动规划在planner.c中完成，实时执行则在stepper.c。TIMER1被配置为比较匹配中断，每次中断选择一个 step 事件，拉高方向对应的脉冲引脚。脉冲宽度由STEP_PULSE_DELAY和STEP_PULSE_TIME宏控制，默认 10us，足以驱动常见 A4988 和 DRV8825。
| 宏名称 | 默认值 | 说明 |
|---|---|---|
STEP_PULSE_TIME_US | 10 | 步进脉冲高电平时间，单位微秒 |
STEP_PULSE_DELAY_US | 0 | 方向信号切换后到脉冲的延迟 |
DEFAULT_PULSE_MICROSECONDS | 10 | 老版本参数，v1.1 已改为宏 |
MAX_RATE_MM_S | 500 | 三轴最大速度限幅 |
如果在雕刻高速走曲线时发现 Z 轴窜动，先把$110/$111降到 300 再测试。grbl 对每个脉冲都实时计算，CPU 占用在 8MHz 下已经很高，盲目提最大速度会导致定时器中断间隔低于执行时间，结果就是上位机看到运动变慢甚至卡住。
3. 源码编译与烧录：使 grbl v1.1 正确跑在你的 Arduino 上
3.1 源码目录结构：先找对人再编译
下载的grbl-master压缩包解压后，第一层目录是grbl/，里面才是真正的固件源码。核心文件planner.c、stepper.c、gcode.c、protocol.c都在grbl/根目录，cpu_map.h负责处理器型号映射，config.h是全局配置入口。grbl/下有Makefile，这是 v1.1 与老 v0.8x 的区别，老版本要装 Arduino IDE，v1.1 可以用命令行工具链交叉编译。
cd grbl-master/grbl # 确认交叉编译器和串口工具已安装 # Ubuntu 下需要 gcc-avr avr-libc avrdude sudo apt install gcc-avr avr-libc avrdude # 根据板子修改 config.h 中的相关宏后执行 make make clean && make编译完成后会生成grbl.hex。烧录前先按住 Arduino Uno 的复位键，避免旧固件占用串口，然后执行：
avrdude -c arduino -p atmega328p -P /dev/ttyUSB0 -b 115200 -U flash:w:grbl.hex如果是 Mega 2560，处理器型号改成atmega2560，波特率-b一般用 115200。烧录后打开串口监控，波特率 115200，发送$回车，grbl 会返回版本号和参数列表，以Grbl 1.1h ['$' for help]开头。
3.2 config.h 中的关键配置：不是所有机器都能用默认参数
config.h里DEFAULTS_*决定了$$命令首次访问时的初始参数。常见做法是使用DEFAULTS_GENERIC，然后通过$命令覆盖，而不是反复改源码重编译。
// config.h 中与步进电机最相关的配置段 // 每毫米步数需要通过你的皮带轮或丝杆导程计算 #define X_STEPS_PER_MM 80.0 #define Y_STEPS_PER_MM 80.0 #define Z_STEPS_PER_MM 400.0 // 软件限位软限位坐标，单位 mm #define X_MIN_LIMIT 0.0 #define X_MAX_LIMIT 200.0 #define Y_MIN_LIMIT 0.0 #define Y_MAX_LIMIT 200.0很多新手直接把 3018 的默认数值当成物理真理，其实那只是某家制造商的电机细分配置。步进当量的精确公式是“驱动细分 × 步进角步数 ÷（减速比 × 丝杆导程）”，比如静音步进电机细分数 16、电机转一圈 3200 步、皮带 2mm 齿距 × 20 齿，那么每毫米步数就是 3200 / 40 = 80。改完这些值后，用JOG或手动输入G91 G0 X10测量真实移动距离，误差超过 2% 就要重新算。
3.3 用$$和$x=y调整运行时参数
编译烧录后，参数可以直接写进 EEPROM，重启不清零。常用参数请看下表：
| 参数 | 含义 | 典型值（3018） |
|---|---|---|
$0 | 步进脉冲时间 us | 10 |
$1 | 方向信号保持时间 us | 10 |
$5 | 反走样方向，1=SERVO 模式 | 0 |
$10 | 状态报告选项 | 1 |
$13 | 角度制做圆弧，1=度 | 0 |
$20 | 软限位使能，1=开 | 0 |
$21 | 硬限位使能，1=开 | 0 |
$22 | 回零使能，1=开 | 1 |
$27 | 回零拉回距离 mm | 1 |
$32 | 激光模式，1=奴役主轴激光 | 0 |
设置方法是在串口里发送$110=300，例如$110=300会把 X 轴最大速率改为 300 mm/min。注意，v1.1 速率单位是 mm/min，不是 mm/s。$110改变后要重新发送$20=1使软限位坐标，否则移动可能越界。
4. 雕刻机与 3D 打印机的 G 代码与 IO 控制实战
4.1 G 代码解析流程：从G0 X10到运动块
gcode.c是 v1.1 中最容易读的模块，它把 G 代码按字母分割成“Word + 值”的键值对，再丢给对应处理函数。比如G0 X10 F1000会被拆成G值 0、X值 10、F值 1000。G0调用mc_line()，后者入队block_t。
// gcode.c 中运动指令分发方法 case 0: // 快速定位 case 1: // 线性运动 // 把 X/Y/Z 轴移动到指定坐标，F 值决定进给速率 mc_line(parser_x_value, parser_y_value, parser_z_value, parser_f_value, false, false); break; case 2: // 顺时针圆弧 case 3: // 逆时针圆弧 mc_arc(parser_x_value, parser_y_value, parser_z_value, parser_i_value, parser_j_value, parser_f_value, (gcode->motion == 3)); break;关键点在于，grbl 的 G 代码解析是逐行阻塞的：一行的 G 代码解析完毕并确认参数合法后，planner 才会返回ok。如果上位机连续发两条指令，第二条必须等第一条的ok反馈。这也是 grbl 不会因为缓冲区溢出乱跑的原因。雕刻机调试时，我通常先发G21 G90绝对坐标，再发G0 X0 Y0 Z0回机器原点。
4.2 回零与限位：$H背后的顺序和逻辑
grbl v1.1 支持三个限位开关，接在 Arduino Uno 的 D9/D10/D12 对应 X/Y/Z 轴。回零时$H会先以低速向负方向找限位，碰到开关后反向以最低速度脱离，最后停在限位开关第一次松开的位置。这个“反向脱离”距离由$27控制，默认 1mm，如果你的限位开关触发片太短，可能需要调大到 2~3mm。
// limits.c 中回零状态机的启动阶段 switch (state) { case MACHINE_BOOT: // 先检查所有限位开关是否已经触发，若触发先手动移开 if (limits_get_state()) { // 没有空闲的空间，拒绝回零并提示 return(STATUS_CHECK_LIMITS); } // 打开步进使能，准备向负方向搜索 state = MACHINE_CYCLE_START; break; case MACHINE_CYCLE_START: // 通过 mc_line 向负方向移动，速度为 $24 回零速度 mc_line(axis_steps[X_AXIS] * homing_cycle_distance, axis_steps[Y_AXIS] * homing_cycle_distance, axis_steps[Z_AXIS] * homing_cycle_distance, homing_rate, true, true); break; }收到STATUS_CHECK_LIMITS错误码，说明已有其他限位被按住，grbl 拒绝执行回零。注意，如果 $22=0（回零禁用），发送$H会直接报 error。回零前必须确保限位开关用的 NC（常闭）接法，因为 NC 比 NO 在断线时更容易被发现。
4.3 主轴与冷却控制：M3、M4、M8 的软件实现逻辑
grbl v1.1 把主轴控制放在spindle_control.c，通过 PWM 输出控制雕刻机主轴调速。M3 是顺时针旋转，M4 逆时针，S 值指定转速百分比，比如M3 S5000。冷却泵用 D8 引脚控制，M8 开、M9 关。在 3D 打印机场景下，这部分常被改动：因为 3D 打印机需要加热床和热端，原始 grbl 并没有温度控制环，所以直接用 grbl 做 Megatronics 类联动并不合适。
// spindle_control.c 中主轴 PWM 占空比换算 void spindle_speed(uint16_t pwm_value){ // pwm_value 由 S 值映射到 0~SCALER_ACTIVE if (pwm_value == 0) { SPINDLE_PWM_OFF(); } else { SPINDLE_PWM_DDR |= (1 << SPINDLE_PWM_BIT); OCR5A = pwm_value; // 16 位 PWM 比较寄存器 SPINDLE_PWM_PORT |= (1 << SPINDLE_PWM_BIT); // 使能 PWM 输出 } }如果你把 M3 改成控制激光强度，需要把$32=1打开激光模式，这样 M3 会持续开启 PWM，而不是像铣刀主轴那样必须有 M5 才能关。烧录前看spindle_control.h中的SPINDLE_PWM_BIT对应的引脚，Arduino Uno 上是 D11，Mega 上是 D45。改完记得重新编译烧录。
5. 排错与进阶：grbl error1 的根源和自定义 M 命令的扩展点
5.1 最常见的error:1是怎么回事
grbl 返回的错误码采用“单词码+语义码”组合，error:1表示 G 代码单词或参数非法。最常见的情况有三种：坐标值写成了字符串、G 代码模式没有开启绝对坐标就输入 G92，或者同一行里同时出现互斥的 G 代码，例如G0 G1。还有一种是圆弧参数 I/J 与半径不匹配，grbl v1.1 拒绝执行半径超差超过 0.01% 的圆弧，此时error:1会伴随?状态报告中的GC行显示当前位置。上位机（如 grbl 控制器）收到 error 后通常会停止发送队列，所以你在重复发现某一行报错时，应该先从该指令中找G和X/Y/Z是否和前一行的模态冲突。
5.2 自定义 M 命令：从gcode.c的 switch 里加一个分支
grbl 允许你直接扩展控制逻辑。假设你的雕刻机需要一个真空泵，那么可以在gcode.c的case 7(M7 通常预留给冷却阀) 或自定义case 100处理中增加 IO 控制。注意，自定义 M 值不能和已有 G 代码冲突，M100 以上在没有标准定义前建议自己保留。
// 在 gcode.c 的 switch 中添加 M100 case 100: // 自定义真空泵 if (gcode->action == GC_MARK) { // 解析 S 值，0 关 1 开 if (value && value != 0) { VACUUM_PUMP_PORT |= (1 << VACUUM_PUMP_BIT); // 置位输出 } else { VACUUM_PUMP_PORT &= ~(1 << VACUUM_PUMP_BIT); } } break;修改后需要重新编译烧录。这里有个陷阱：grbl的解析器对M指令的S值最多只保存为 16 位整数，如果你要控制的是模拟量（比如真空泵调速），需要把它当成 PWM 输出，直接写入OCR5A，否则只能用开关量。扩展后最好在report.c中同时增加状态反馈，方便上位机判断 IO 是否成功。
5.3 进阶验证：用逻辑分析仪看步进脉冲
调试 grbl 最有效的方式不是看串口日志，而是用逻辑分析仪抓步进定时器的输出引脚。stepper.c在每个中断末尾调用tick()，所以直接用 saleae 抓 D2 步进引脚，就能看到脉冲宽度和相邻脉冲间隔是否符合$0和$120的设置。如果间隔抖动超过 20%，说明 MCU 的定时器周期被其他任务拖延，此时应当降低$110/$111最大速率，或是把 USB 转串口的缓冲设大。如果你手头没有逻辑分析仪，还可以把$10=2（实时状态报告）打开，grbl 会在到位后返回实时位置，通过对比移动量与实际位置的变化，基本能确认步进脉冲是否正确输出。这就是 grbl v1.1 从源码到实物的完整闭环：理解planner、配置config.h、用$参数调校、在gcode.c里做最后的 IO 扩展。
本文还有配套的精品资源，点击获取
