固件兼容性
此页面记录与 Rayforge 一起使用的激光控制器的固件兼容性。
概述
Rayforge 主要为基于 GRBL 的控制器设计，但也支持 Marlin、Smoothieware 和其他固件类型。
兼容性矩阵
| 固件 | 版本 | 状态 | 驱动程序 | 备注 |
|---|---|---|---|---|
| GRBL | 1.1+ | 完全支持 | GRBL 串口 | 推荐 |
| grblHAL | 2023+ | 兼容 | GRBL 串口 / GRBL Telnet | 现代 GRBL 分支 |
| GRBL | 0.9 | 有限 | GRBL 串口 | 较旧，可能有问题 |
| Smoothieware | 全部 | 兼容 | SmoothieDriver (Telnet) | 基于网络 |
| Marlin | 2.0+ | 兼容 | Marlin 串口 | 需要激光模式 |
| ESP3D | 全部 | 兼容 | GRBL Telnet | 基于网络 |
| OctoPrint | 全部 | 实验性 | OctoPrint | 见下方说明 |
| 其他 | - | 不支持 | - | 请求支持 |
GRBL 固件
状态： 完全支持 版本： 1.1+ 驱动程序： GRBL 串口
GRBL 1.1（推荐）
什么是 GRBL 1.1？
GRBL 1.1 是业余 CNC 和激光机器最常见的固件。2017 年发布， 它稳定、文档齐全且广泛支持。
Rayforge 支持的功能：
- 串口通信（USB）
- 实时状态报告
- 激光模式（M4 恒定功率）
- 设置读/写（$$、$X=value）
- 归零循环（$H）
- 工作坐标系（G54）
- 点动命令（$J=）
- 进给率覆盖
- 软限位
- 硬限位（终点开关）
已知限制：
- 功率范围：0-1000（S 参数）
- 无网络连接（仅 USB）
- 板载内存有限（小 G 代码缓冲区）
检查 GRBL 版本
查询版本：
连接到控制器并发送：
$I
响应示例：
[VER:1.1h.20190825:]
[OPT:V,15,128]
1.1h= GRBL 版本 1.1h- 日期表示构建
GRBL 0.9（较旧）
状态： 有限支持
GRBL 0.9 是较旧的版本，有一些兼容性问题：
差异：
- 状态报告格式不同
- 无激光模式（M4） - 仅使用 M3
- 设置较少
- 点动语法不同
如果您有 GRBL 0.9：
- 升级到 GRBL 1.1（如果可能）（推荐）
- 使用 M3 而不是 M4（功率不太可预测）
- 彻底测试 - 某些功能可能无法工作
升级说明： 参见 GRBL Wiki
grblHAL
状态： 兼容 版本： 2023+ 驱动程序： GRBL 串口
什么是 grblHAL？
grblHAL 是 GRBL 的现代分支，具有增强功能：
- 多控制器硬件支持（STM32、ESP32 等）
- 以太网/WiFi 网络
- SD 卡支持
- 更多 I/O 引脚
- 增强的激光支持
与 Rayforge 的兼容性：
- 完全兼容 - grblHAL 维护 GRBL 1.1 协议
- 所有 GRBL 功能都工作
- 额外功能（网络、SD）Rayforge 尚不支持
- 状态报告与 GRBL 相同
使用 grblHAL：
- 在 Rayforge 中选择"GRBL 串口"驱动程序
- 通过 USB 串口连接（就像 GRBL）
- 所有功能按 GRBL 记录工作
未来： Rayforge 可能会添加对 grblHAL 特定功能的支持（网络等）
GRBL Telnet 驱动
状态： 支持 固件： grblHAL、ESP3D 和其他网络化 GRBL 控制器 驱动程序： GRBL Telnet
关于 GRBL Telnet 驱动
GRBL Telnet 驱动通过网络 Telnet 接口连接基于 GRBL 的控制器。适用于内置 WiFi 或以太网的板子——无需 USB 电缆。
功能：
- 网络连接（以太网/WiFi）
- 兼容基于 grblHAL 和 ESP3D 的板子
- 与串口驱动相同的 GRBL 协议
使用 GRBL Telnet 驱动：
- 在控制器上配置网络（WiFi 或以太网）
- 在机器设置中**选择"GRBL Telnet"**驱动
- 输入 IP 地址和控制器的端口
- 连接 — 驱动通过 Telnet 通信
要求：
- 网络化 GRBL 兼容控制器（grblHAL、ESP3D 等）
- 控制器和计算机在同一网络
- 控制器上启用了 Telnet 接口
Smoothieware
驱动程序： GRBL 串口（兼容模式）
兼容性说明
Smoothieware 使用不同的 G 代码语法：
主要差异：
| 功能 | GRBL | Smoothieware |
|---|---|---|
| 激光开 | M4 S<value> | M3 S<value> |
| 功率范围 | 0-1000 | 0.0-1.0（浮点） |
| 状态 | <...> 格式 | 不同格式 |
在 Rayforge 中使用 Smoothieware：
- 在机器设置 > G 代码 > 方言中选择 Smoothieware 方言
- 首先用低功率测试
- 验证功率范围与您的配置匹配
- 无实时状态 - 反馈有限
限制：
- 状态报告不完全兼容
- 功率缩放可能不同
- 不支持设置（$$ 命令）
- 在真实硬件上未测试
建议： 如果可能，改用 GRBL 兼容固件。
Marlin
版本： 2.0+ 带激光支持 驱动程序： Marlin 串口
Marlin 串口驱动程序
Rayforge 包含一个专用的 MarlinSerialDriver，通过串口 (USB) 连接到 Marlin 固件。 Marlin 2.0+ 在正确配置时可以控制激光。
功能：
- 串口通信 (USB)
- Marlin 握手协议（等待 "start" 消息）
- 逐行 G 代码流式传输，带
ok确认 - M114 位置轮询
- 作业执行，带细粒度进度报告
- 归零 (G28)、点动、移动、换刀 (T)
- WCS 偏移设置 (G10 L2 P)
- 通过 Marlin G 代码方言控制激光功率
- 通过 M410 (Quick Stop) 取消
- 自动配置探测（查询 M115、M211、M503）
要求：
- Marlin 2.0 或更高版本固件
- 已启用激光功能：
#define LASER_FEATURE#define LASER_POWER_INLINE
- 配置正确的功率范围：
#define SPEED_POWER_MAX 1000
在 Rayforge 中使用 Marlin：
- 在机器设置中选择 "Marlin (Serial)" 驱动程序
- 设置串行端口和波特率（通常为 115200）
- 在机器设置 > G 代码 > 方言中选择 Marlin 方言
- 为激光使用配置 Marlin
- 测试功率范围（0-1000 或 0-255）
限制：
- 实验性 — 欢迎反馈
- 不支持读取/写入设置（如 GRBL 的
$$） - 无网络连接（仅 USB）
固件升级指南
升级到 GRBL 1.1
为什么要升级？
- 激光模式（M4）用于恒定功率
- 更好的状态报告
- 更可靠
- 更好的 Rayforge 支持
如何升级：
-
识别您的控制器板：
- Arduino Nano/Uno（ATmega328P）
- Arduino Mega（ATmega2560）
- 自定义板
-
下载 GRBL 1.1：
- GRBL Releases
- 获取最新的 1.1 版本（推荐 1.1h）
-
刷入固件：
使用 Arduino IDE：
1. 安装 Arduino IDE2. 打开 GRBL 草图（grbl.ino）3. 选择正确的板和端口4. 上传使用 avrdude：
avrdude -c arduino -p m328p -P /dev/ttyUSB0 \-U flash:w:grbl.hex:i -
配置 GRBL：
- 通过串口连接
- 发送
$$查看设置 - 为您的机器配置
升级前备份
保存您的设置：
- 连接到控制器
- 发送
$$命令 - 复制所有设置输出
- 保存到文件
升级后：
- 逐个恢复设置：
$0=10、$1=25等。 - 或使用默认值并重新配置
控制器硬件
常见控制器
| 板 | 典型固件 | Rayforge 支持 |
|---|---|---|
| Arduino CNC Shield | GRBL 1.1 | 优秀 |
| MKS DLC32 | grblHAL | 优秀 |
| Ruida | 专有 | 实验性 |
| OctoPrint (Pi) | 多种 | 实验性 |
推荐控制器
为了最佳的 Rayforge 兼容性：
-
Arduino Nano + CNC Shield（GRBL 1.1）
- 便宜（约 $10-20）
- 易于刷入
- 文档齐全
-
MKS DLC32（grblHAL）
- 现代（基于 ESP32）
- WiFi 功能
- 活跃开发
-
自定义 GRBL 板
- 市场上有很多可用
- 检查 GRBL 1.1+ 支持
固件配置
激光的 GRBL 设置
基本设置：
$30=1000 ; 最大主轴/激光功率（1000 = 100%）
$31=0 ; 最小主轴/激光功率
$32=1 ; 激光模式启用（1 = 开）
机器设置：
$100=80 ; X 步/mm（为您的机器校准）
$101=80 ; Y 步/mm
$110=3000 ; X 最大速率（mm/min）
$111=3000 ; Y 最大速率
$120=100 ; X 加速度（mm/sec）
$121=100 ; Y 加速度
$130=300 ; X 最大行程（mm）
$131=200 ; Y 最大行程（mm）
安全设置：
$20=1 ; 软限位启用
$21=1 ; 硬限位启用（如果您有终点开关）
$22=1 ; 归零启用
测试固件
基本测试序列：
-
连接测试：
发送: ?期望: <Idle|...> -
版本检查：
发送: $I期望: [VER:1.1...] -
设置检查：
发送: $$期望: $0=..., $1=..., 等。 -
移动测试：
发送: G91 G0 X10期望: 机器在 X 方向移动 10mm -
激光测试（极低功率）：
发送: M4 S10期望: 激光开启（暗）发送: M5期望: 激光关闭
固件问题故障排除
固件无响应
症状：
- 命令无响应
- 连接失败
- 不报告状态
诊断：
-
检查波特率：
- GRBL 1.1 默认：115200
- GRBL 0.9：9600
- 两者都尝试
-
检查 USB 电缆：
- 数据电缆，不是仅充电
- 用已知好的电缆更换
-
检查端口：
- Linux：
/dev/ttyUSB0或/dev/ttyACM0 - Windows：COM3、COM4 等。
- 在 Rayforge 中选择了正确的端口
- Linux：
-
用终端测试：
- 使用 screen、minicom 或 PuTTY
- 发送
?看是否得到响应
固件崩溃
症状：
- 控制器在作业期间锁定
- 随机断开连接
- 行为不一致
可能原因：
- 缓冲区溢出 - G 代码文件太复杂
- 电气噪声 - 接地不良或 EMI
- 固件错误 - 升级到最新版本
- 硬件问题 - 控制器故障
解决方案：
- 升级固件到最新稳定版本
- 简化 G 代码（降低精度，更少段）
- 在 USB 电缆上添加铁氧体磁珠
- 改善接地和电缆布线
固件错误
症状：
- 命令被拒绝
- 意外行为
- 错误消息
解决方案：
- 查询固件版本：
$I - 与 Rayforge 期望比较
- 升级或选择正确的方言
未来的固件支持
Ruida 控制器
Rayforge 包含对基于 Ruida 的控制器的实验性支持（例如 RDC6442、RDC6445、Ruida R5）。Ruida 驱动程序通过网络连接，支持点动、位置报告、气辅控制、图层选择、自动连接和状态轮询。
功能：
- 网络连接（以太网/WiFi）
- 位置报告
- 点动控制
- 气辅和图层选择
- 参考点支持
限制：
- 实验性 — 尚未完全稳定
- 不生成 G 代码；Ruida 使用自己的专有协议
- 尚不支持发送作业
OctoPrint
Rayforge 包含一个实验性的 OctoPrint 驱动程序，可通过网络直接向 OctoPrint 服务器提交 G 代码。如果您的激光器连接到运行 OctoPrint 的 Raspberry Pi 或其他 计算机上，这将非常有用。
功能：
- WebSocket 连接用于实时状态更新
- 当 WebSocket 不可用时回退到 REST 轮询
- 连接丢失时自动重连
- 提交作业并自动开始打印
- 点动、回零和暂停/恢复控制
- OctoPrint 应用密钥的"请求访问"流程
使用 OctoPrint 驱动程序：
- 在机器设置中选择"OctoPrint"驱动程序
- 输入您的 OctoPrint 服务器的主机名或 IP 地址
- 设置端口（默认：80）
- 点击"请求访问"通过 OctoPrint 的应用密钥系统获取 API 密钥
- 连接 — Rayforge 将建立 WebSocket 连接
限制：
- 实验性，未在真实硬件上测试 — 欢迎反馈
- 无法通过 OctoPrint 读取或写入固件设置
- OctoPrint 不报告探针结果
- 不支持读取 WCS 偏移
其他请求的功能
用户已请求支持：
- Trocen/AWC - 商业激光控制器
- ESP32 WiFi - grblHAL 的网络连接
- 激光 API - 直接机器 API（无 G 代码）
状态： 目前不支持。欢迎在 GitHub 上提交功能请求。
贡献
要添加固件支持：
- 在
rayforge/machine/driver/中实现驱动程序 - 在
rayforge/machine/models/dialect.py中定义 G 代码方言 - 在真实硬件上彻底测试
- 提交带有文档的拉取请求