• 嵌入式
• 硬件开发
• 物联网
• 工业制造

Grbl_ESP32 是将经典 CNC 控制固件 Grbl 移植到 ESP32 平台的开源实现，凭借 ESP32 的双核性能与无线能力，在保持与原版 Grbl GCode 完全兼容的同时，扩展出 6 轴 12 电机驱动、WebUI 浏览器控制、蓝牙/Wi-Fi 通信、SD 卡作业等远超 8 位 AVR 控制器能力范围的特性。本文以仓库 README 为主线，结合 机器定义文件、全局配置、平台构建配置 与核心源码，完整讲清该固件的功能边界、配置机制与编译部署路径，读完你可以独立完成：选定机器定义、裁剪功能宏、编译固件并烧录验证（含无硬件 Test Drive 模式）。

需要先说明的一点：README 明确指出该项目后续演进为新一代项目 FluidNC（README 顶部有说明），本仓库当前处于“仅维护既有功能”阶段，所有新特性均已转向 FluidNC。对于已有硬件的用户，Grbl_ESP32 仍然是完整可用且与 Grbl 生态兼容的固件。

一、功能全景：Motors / Peripherals / Job Control / Spindles / Connectivity

README 将固件能力划分为五大类，下面逐项说明并给出仓库内的实现落点。

1.1 电机系统（Motors）

README 列出的电机能力：

• 支持最多 6 根协调轴（XYZABC），每轴可接 1 或 2 台电机，总计最多 12 台电机；
• 双电机轴可借助回零开关自动对正（auto square），且两台电机可独立控制；
• 电机驱动可动态绑定到轴——例如 4 电机 XYZA 配置可改造成 XYYZ（双电机 Y 轴）而无需任何硬件改动；
• 步进频率最高可达 120,000 step/s；
• 支持 Trinamic（SPI 控制）驱动，包含 StealthChop、CoolStep、StallGuard 模式，并可用无感回零；
• 可直接驱动单极性（Unipolar）步进电机；
• 舵机（RC hobby servos）可作为协调轴电机使用，并受加速度与速度控制。

在仓库中这些能力由 Grbl_Esp32/src/Motors 目录下的驱动类实现：

• StandardStepper（StandardStepper.h）：通用双极性步进；
• TrinamicDriver（TrinamicDriver.h）：继承自 StandardStepper，叠加 SPI 配置的 TMC 系列驱动特性；
• UnipolarMotor、RcServo（舵机步进）、Dynamixel2（总线舵机）：对应 README 中列出的其他驱动形态。

轴数上限在 Config.h 中约束：MAX_N_AXIS = 6，而N_AXIS取值范围为 3 到 6，机器定义文件可覆盖N_AXIS。

1.2 外设（Peripherals）

• 限位/回零开关，带消抖处理；
• 用户输入按钮（hold、resume、reset）；
• 冷却液控制（Mist 与 Flood 双路）；
• Z 探针（可绑定任意轴）；
• 安全门（Safety Door）：开门时安全回撤并停主轴，关门后可继续加工；
• 移位寄存器与 I/O 扩展器支持（README 注明在开发分支提供）。

冷却液引脚并非固定：Config.h 注释明确说明，ESP32 版本中 M7/M8 通过机器定义文件分配 GPIO，而不是像 Arduino 版 Grbl 那样固定模拟引脚。3axis_v4.h 中即可看到COOLANT_MIST_PIN与COOLANT_FLOOD_PIN的 GPIO 分配示例。

1.3 作业控制（Job Control）

• 瞬时进给保持与恢复；
• 进给倍率（feed rate override）；
• 主轴速度倍率（spindle speed override）。

这些实时命令在 Config.h 中以Cmd枚举定义，直接从串口数据流中“摘取”，不进入 GCode 解析器：

enum class Cmd : uint8_t { Reset = 0x18, // Ctrl-X StatusReport = '?', CycleStart = '~', FeedHold = '!', // ... FeedOvrReset = 0x90, // Restores feed override value to 100%. FeedOvrCoarsePlus = 0x91, // ... SpindleOvrReset = 0x99, // Restores spindle override value to 100%. // ... };

对应的倍率上下限与步进量同样在此文件中编译期配置（Config.h）：进给倍率默认 100%、上限 200%、下限 10%、粗调 10%、细调 1%；主轴倍率同规格。

1.4 主轴系统（Spindles）

README 列出的主轴形态：PWM、RS485 Modbus、0-10V DAC 模拟电压、继电器、用廉价 BESC 电调驱动的 RC 无刷电机、带功率/速度补偿的激光 PWM，并且“创建自定义主轴非常容易”。

仓库 Grbl_Esp32/src/Spindles 目录与SpindleType枚举一一对应（Spindle.h）：

enum class SpindleType : int8_t { NONE = 0, PWM, RELAY, LASER, DAC, HUANYANG, BESC, _10V, H2A, YL620, L510 };

Spindles::Spindle抽象基类定义了init()、set_rpm()、set_state()、stop()等纯虚接口，具体类（PWMSpindle、DacSpindle、Laser、HuanyangSpindle、BESCSpindle、VFDSpindle等）各自实现协议细节，机器定义文件中用一行#define SPINDLE_TYPE SpindleType::XXX完成选择。此外 Config.h 还保留了“分段线性主轴 PWM 拟合”模型（ENABLE_PIECEWISE_LINEAR_SPINDLE）的开关与参数占位，配套拟合脚本为仓库中的 fit_nonlinear_spindle.py，这是 README 未展开的进阶能力。

1.5 连接性（Connectivity）与 SD 卡

• USB/Serial：标准串口，波特率 115200（Config.h 的BAUD_RATE）；
• Bluetooth/Serial：在手机或 PC 上创建虚拟串口，标准串口应用可直接使用；
• WIFI：可自建热点（AP）也可连接既有网络（STA）；内置 Web 服务器提供功能完整的 CNC 控制应用，手机/PC 浏览器直接访问、无需安装 App；支持 Telnet 发送 GCode、推送通知（如“job done”时发文本/邮件）、OTA 空中固件升级；
• SD 卡：GCode 可加载并通过 Wi-Fi 远程执行。

WebUI 相关实现集中在 Grbl_Esp32/src/WebUI 目录：WebServer（HTTP + WebSocket）、TelnetServer、WifiConfig/BtConfig、NotificationsService、SDCard等。README 致谢部分说明该 Web 层基于 ESP3D-WEBUI 项目开发；其命令行接口完整保存在 doc/Commands.txt，例如[ESP111]查询当前 IP、[ESP100]<SSID>设置 STA 网络、[ESP210]列出 SD 卡内容、[ESP444]RESTART重启、[ESP600]msg发送通知等。启用认证（ENABLE_AUTHENTICATION）后，多数命令需附加pwd=admin形式的口令。

README 末尾还强调“快速启动”：约 2 秒完成启动，无需正式关机，可直接断电——这是相对树莓派等方案的显著差异。

二、自定义能力：机器文件机制与 RTOS

README 的 Customizable 一节指出：引脚可随意映射、自定义机器无需改动主代码、支持自定义初始化（运动学、自定义回零、换刀序列、按钮宏、作业结束序列），且 RTOS 实时操作系统允许后台监控/控制而不影响运动控制性能。

2.1 机器定义文件（Machines/）

核心机制在 Machine.h：它要么 include 某个机器定义文件，要么接受外部编译标志注入：

// 方式一：直接编辑 Machine.h，指定 #include "Machines/xxx.h" // 默认是 test_drive.h // // 方式二：外部定义 MACHINE_FILENAME（不写 Machines/ 前缀）， // 例如 PlatformIO 下： // PLATFORMIO_BUILD_FLAGS=-DMACHINE_FILENAME=3axis_v4.h platformio run // Windows PowerShell： // $env:PLATFORMIO_BUILD_FLAGS='-DMACHINE_FILENAME=3axis_v4.h'; platformio run

仓库 Grbl_Esp32/src/Machines 目录内置 25 个现成板卡/机器定义，涵盖 MPCNC、MPCNC 激光模块、atari_1020、fysetc、Tapster、6_Pack 系列、TMC2209_4x、RS485 主轴控制器等。以 3axis_v4.h 为例，机器定义文件就是“引脚表 + 主轴类型 + 轴数”：

#define MACHINE_NAME "ESP32_V4" #define X_STEP_PIN GPIO_NUM_12 #define X_DIRECTION_PIN GPIO_NUM_14 #define Y_STEP_PIN GPIO_NUM_26 #define Y_DIRECTION_PIN GPIO_NUM_15 #define Z_STEP_PIN GPIO_NUM_27 #define Z_DIRECTION_PIN GPIO_NUM_33 #define X_LIMIT_PIN GPIO_NUM_17 #define Y_LIMIT_PIN GPIO_NUM_4 #define Z_LIMIT_PIN GPIO_NUM_16 #define STEPPERS_DISABLE_PIN GPIO_NUM_13 #define SPINDLE_TYPE SpindleType::PWM #define SPINDLE_OUTPUT_PIN GPIO_NUM_2 #define SPINDLE_ENABLE_PIN GPIO_NUM_22 #define COOLANT_MIST_PIN GPIO_NUM_21 #define COOLANT_FLOOD_PIN GPIO_NUM_25 #define PROBE_PIN GPIO_NUM_32

MACHINE_NAME会在启动时通过report_machine_type()打印到串口（见下文启动流程）。所有机器共有的常量（SPI 引脚、定时器基准等）集中在 MachineCommon.h，一般无需改动。

2.2 自定义初始化代码（Custom/）

README 提到的“运动学、自定义回零、换刀序列、按钮宏、作业结束序列”等自定义点，落在 Grbl_Esp32/Custom 目录，包括CoreXY.cpp、parallel_delta.cpp（并联 Δ 运动学）、polar_coaster.cpp等现成定制，以及 custom_code_template.cpp 提供的模板；运行时钩子由 CustomCode.cpp 承载。结合 Grbl.cpp 中machine_init()的调用（源码注释说明其为 weak 弱定义，未定制时为空操作），可以看出定制代码通过弱符号钩子接入主流程，主代码无需修改。

2.3 功能宏裁剪（configure-features.py）

Wi-Fi/蓝牙/SD 等特性由 Config.h 中一对CONFIGURE_EYECATCH_BEGIN/END标记包裹的宏块控制：

#define ENABLE_BLUETOOTH // enable bluetooth #define ENABLE_SD_CARD // enable use of SD Card to run jobs #define ENABLE_WIFI // enable wifi #define ENABLE_HTTP // enable HTTP and all related services #define ENABLE_OTA // enable OTA #define ENABLE_TELNET // enable telnet #define ENABLE_TELNET_WELCOME_MSG #define ENABLE_MDNS // enable mDNS discovery #define ENABLE_SSDP // enable UPNP discovery #define ENABLE_NOTIFICATIONS // enable notifications #define ENABLE_SERIAL2SOCKET_IN #define ENABLE_SERIAL2SOCKET_OUT #define ENABLE_CAPTIVE_PORTAL // #define ENABLE_AUTHENTICATION

仓库根目录的 configure-features.py 可自动改写该宏块，例如：

python configure-features.py -e WIFI HTTP OTA python configure-features.py -d BLUETOOTH TELNET

脚本支持-e/--enable、-d/--disable、-c/--configfile、-v参数，合法特性名即上述validFeatureList中的 14 项。值得注意的两个默认细节：ENABLE_CAPTIVE_PORTAL使 AP 模式下浏览器自动弹出 WebUI 登录页；ENABLE_AUTHENTICATION默认注释关闭，且 Config.h 注释明确警告当前认证实现只宜作“防止误操作的友好建议”，并非真正的安全边界。

三、Test Drive：无硬件试用模式

README 的“Test Drive It”一节说明：直接编译烧录即可得到一台不映射任何引脚的虚拟机器，可安全试用全部功能（含 Wi-Fi 与 WebUI），唯一例外是回零这类依赖真实开关反馈的操作。

对应实现是默认机器定义 test_drive.h：

#define MACHINE_NAME "Test Drive - Demo Only No I/O!" #define N_AXIS 3 // This cannot use homing because there are no switches #ifdef DEFAULT_HOMING_CYCLE_0 #undef DEFAULT_HOMING_CYCLE_0 #endif #ifdef DEFAULT_HOMING_CYCLE_1 #undef DEFAULT_HOMING_CYCLE_1 #endif #define SPINDLE_TYPE SpindleType::NONE #ifdef USE_RMT_STEPS #undef USE_RMT_STEPS #endif

文件头注释进一步说明其用途：烧到未接线（或接了未知硬件）的 ESP32 上不会有引脚输出信号，可避免短路损伤；同时它是把程序先跑起来、再走 OTA 空中升级的理想入口。由于 Machine.h 默认 include 的正是它，README 建议的“编译即用”流程与源码默认值完全一致。

四、编译与部署

4.1 Arduino IDE（README 推荐路径）

README 的 Using It 一节指出：

• 应使用最新版 Arduino IDE 编译，按其指引安装 ESP32 板支持（即 Espressif 的 arduino-esp32 插件）；选择 Arduino IDE 而非 ESP-IDF 是为了降低初学者编译门槛；
• 未自备硬件时建议先购买 ESP32 Dev Module；
• 基本使用（GCode、设置命令等）沿用原版 Grbl 的 Wiki 约定，硬件接线需按 Arduino 版 Grbl 的思路理解。

实际操作即：把仓库 Grbl_Esp32 目录作为 Arduino 草图打开，在 Machine.h 中选择目标机器文件（替换默认的test_drive.h，或取消注释示例中的atari_1020.h/3axis_v4.h），选ESP32 Dev Module板卡后编译烧录。Arduino 方式难以向编译器传变量，因此MACHINE_FILENAME外部注入机制对其不实用（Machine.h 注释原文说明了这一点）。

4.2 PlatformIO（仓库自带构建配置）

仓库根目录的 platformio.ini 提供了免手写的构建环境，关键内容：

[platformio] src_dir = Grbl_Esp32 lib_dir = libraries data_dir = Grbl_Esp32/data default_envs = release [env] platform = espressif32@3.0.0 ; temporary fix for lost uart rx characters board = esp32dev framework = arduino upload_speed = 921600 board_build.partitions = min_spiffs.csv monitor_speed = 115200 board_build.f_cpu = 240000000L board_build.flash_mode = qio build_flags = ; -DMACHINE_FILENAME=test_drive.h ;去掉行首分号并指定机器文件 -DCORE_DEBUG_LEVEL=0 -Wno-unused-variable -Wno-unused-function

要点解读：

• default_envs = release，另有一个debug环境（build_type = debug）；
• 两个环境均依赖TMCStepper（0.7.x）与 SSD1306 OLED 驱动库，支撑 Trinamic 驱动与屏显；
• min_spiffs.csv分区表压缩了 SPIFFS 占用，为固件留出更多 Flash；
• 串口监视器--eol=CRLF --echo与esp32_exception_decoder过滤器，方便按 Grbl 习惯查看日志；
• 机器切换与 Machine.h 注释一致：Linux 下PLATFORMIO_BUILD_FLAGS=-DMACHINE_FILENAME=3axis_v4.h platformio run，或取消 ini 中build_flags里-DMACHINE_FILENAME=行的注释；
• 仓库附带 builder.py、debug.ini 等辅助脚本/配置，可用于批量构建与调试环境切换。

4.3 启动流程：入口只有 6 行

烧录后的运行入口即 Grbl_Esp32.ino：

void setup() { grbl_init(); } void loop() { run_once(); }

真正的初始化在 Grbl.cpp 的grbl_init()中按序完成：关闭 Wi-Fi 持久化 → 初始化串口 → 打印版本与MACHINE_NAME→settings_init()从非易失存储载入设置 →stepper_init()配置步进引脚与中断定时器 →system_ini()配置控制引脚与引脚变化中断 →init_motors()→machine_init()（自定义钩子）→ 依HOMING_INIT_LOCK决定是否进入 ALARM 强制回零状态 →Spindles::Spindle::select()按SPINDLE_TYPE选定主轴类 → 按启用宏分别启动 Wi-Fi/蓝牙服务与输入缓冲。此后loop()反复调用run_once()消化串口/网络输入与状态机——这正是 README 所说“RTOS 允许后台监控而不影响运动控制”的运行形态：运动由中断/任务保证，主循环只做协议与事件。

五、兼容性与生态

• GCode 兼容：README 声明 Grbl_ESP32 与 Grbl 完全向后兼容，可沿用所有 Grbl 生态的 GCode 发送端（sender）；
• 无线扩展命令：在标准 Grbl 命令之外，[ESP...]系列命令（完整参考见 doc/Commands.txt）负责 Wi-Fi/蓝牙参数、SD 卡管理、EEPROM 读写与通知配置；
• 致谢：核心引擎源自 Sonny (Sungeun) Jeon 的 Grbl 项目，“核心引擎设计几乎未作改动”；Wi-Fi 与 WebUI 层基于 ESP3D-WEBUI 项目开发；
• 后续演进：大规模升级版本以 FluidNC 之名独立发布，兼容全部 Grbl_ESP32 硬件；本仓库仅维护既有功能。

六、小结：如何快速上手

1. 无硬件：保持 Machine.h 默认的test_drive.h，用 PlatformIO（platformio run -t upload）或 Arduino IDE 直接烧录，通过串口/WebUI 体验全部功能（回零除外）；
2. 有硬件：将Machine.h指向 Machines/ 下匹配的板卡定义，或仿照 3axis_v4.h 自建定义文件；
3. 裁剪功能：用python configure-features.py -d BLUETOOTH等命令按需开关 Config.h 中的特性宏；
4. 无线配置：烧录后经 doc/Commands.txt 中的[ESP...]命令配置 AP/STA、Telnet、通知，作业可用 SD 卡 GCode + Wi-Fi 远程触发。

• 嵌入式
• 硬件开发
• 物联网
• 工业制造