📚 课程目录第4章 Klipper核心架构

4、Klipper核心架构：Klipper的组成（Klipper主机、Klipper固件、Moonraker、前端界面）、通信机制（USB/GPIO）、宏与配置系统

Klipper 并非一个单一的固件程序，而是一套由多个独立组件协同工作的分布式系统。理解其核心架构是进行二次开发、性能调优和故障排查的基础。与传统的 Marlin 固件（所有逻辑都在单片机内运行）不同，Klipper 将复杂的运动规划和 G 代码解析任务从 MCU 中剥离出来，交由性能强大的上位机（通常是树莓派或老旧 PC）处理，而 MCU 仅负责执行高频的、实时的硬件脉冲输出。这种架构设计使得 Klipper 能够实现极高的打印速度和精度，同时降低对硬件算力的依赖。本章将深入拆解 Klipper 的四大核心组件、通信机制以及宏与配置系统，帮助你建立完整的系统认知。

4.1 Klipper 四大核心组件及其职责

Klipper 系统由四个关键部分组成，它们各司其职，通过标准化的接口进行通信。理解每个组件的边界和职责，是后续进行配置修改和故障定位的前提。

4.1.1 Klipper 主机（Klipper Host）

这是运行在 Linux 上位机上的核心 Python 程序（通常由 klipper.service 系统服务管理）。它负责所有复杂的计算任务：读取 G 代码文件、解析 G 代码命令、执行运动学规划（如直线插补、圆弧插补）、生成步进电机的步进时间表、管理加热器 PID 控制逻辑、处理限位开关和传感器输入。主机通过标准 USB 或 UART 串口与下位机通信，将计算好的运动指令打包发送给 MCU。由于主机拥有强大的 CPU 和内存，它可以运行复杂的算法（如输入整形 Input Shaping、压力提前 Pressure Advance），而不会影响 MCU 的实时性。

4.1.2 Klipper 固件（Klipper Firmware）

这是烧录在打印机主板 MCU（如 STM32、RP2040、AVR）上的底层固件。它不负责解析 G 代码，而是作为一个“实时执行器”。固件的主要任务包括：接收主机发送的指令队列，根据精确的定时器中断，在极其准确的时间点（微秒级）产生步进电机脉冲、读取温度传感器 ADC 值、控制加热器 PWM 输出、监测限位开关状态。Klipper 固件通过一个简单的、基于文本的协议与主机通信，该协议定义了命令和响应的格式。这种设计使得 MCU 的负载极低，从而允许使用更便宜的芯片，同时获得更高的步进频率。

4.1.3 Moonraker（API 服务器）

Moonraker 是一个独立的 Python 进程，作为 Klipper 主机与外部世界（尤其是 Web 前端）之间的桥梁。它基于 WebSocket 和 JSON-RPC 协议，提供了一套完整的 HTTP API。Moonraker 负责管理打印机状态（如打印进度、温度、位置）、文件管理（上传/下载 G 代码文件）、切片器集成、以及向 Klipper 主机发送控制命令。它还提供了插件系统，允许扩展功能（如连接摄像头、智能家居集成）。如果没有 Moonraker，Klipper 主机仍然可以运行，但将失去所有现代 Web 界面控制能力。

4.1.4 前端界面（Frontend）

前端是用户直接交互的界面，常见的有 Mainsail、Fluidd（基于 Web 的现代界面）和 KlipperScreen（用于触摸屏）。前端通过 WebSocket 连接 Moonraker，实时显示打印机状态，并提供按钮和输入框来发送 G 代码命令、调整温度、控制风扇、管理打印任务。前端本身不包含任何打印逻辑，它只是 Moonraker API 的一个图形化客户端。这意味着你可以使用手机浏览器、平板或桌面浏览器访问同一个打印机，且界面完全一致。

  核心原理总结：Klipper 的架构核心是“分离”。将计算密集型的任务（运动规划）放在上位机，将时间敏感型的任务（脉冲生成）放在下位机。这种分离使得系统整体性能取决于上位机的计算能力，而 MCU 仅需专注于执行，从而突破了传统固件在 8 位 MCU 上的性能瓶颈。

4.2 通信机制：USB 与 GPIO

Klipper 主机与 MCU 之间的通信链路是系统的“血管”。目前最主流、最稳定的连接方式是 USB 串口，但在某些特定场景下（如使用树莓派 GPIO 直连），也会采用 GPIO 通信。

4.2.1 USB 串口通信（标准方式）

绝大多数主板（如 BTT Octopus、SKR 系列）都通过 USB 连接到上位机。Klipper 使用 Linux 下的串口设备（如 /dev/serial/by-id/ 或 /dev/ttyACM0）。通信采用 Klipper 自定义的二进制协议，该协议在串口帧中封装了命令和响应。关键参数是波特率，通常设置为 250000 或 500000，但 Klipper 会自动协商，无需手动配置。USB 通信的优势在于：即插即用、速度快（USB 2.0 全速即可满足）、电气隔离性好（通过 USB 隔离器可避免地环路干扰）。

4.2.2 GPIO 通信（树莓派直连）

对于树莓派 + 步进电机驱动板的组合（如 Klipper 官方推荐的 RP2040 或使用树莓派 GPIO 直接控制步进电机），通信通过 GPIO 引脚进行。这通常涉及两种模式：SPI（用于连接外部 ADC 或特定驱动芯片）和简单的 GPIO 脉冲（直接控制步进电机的 STEP/DIR 引脚）。在 Klipper 配置中，你需要指定 [mcu] 部分的 serial: 参数为 /dev/ttyAMA0（UART）或使用 spi: 参数。GPIO 通信延迟更低，但布线复杂，且容易受到电磁干扰，一般仅用于特定 DIY 场景。

通信方式	典型场景	优点	缺点	Klipper 配置要点
USB 串口	绝大多数成品主板	即插即用、稳定、速率高	需要 USB 线缆，可能存在供电干扰	`serial: /dev/serial/by-id/usb-...`
GPIO UART	树莓派直连主板（无 USB）	减少线缆，延迟低	需配置 UART 引脚，易受干扰	`serial: /dev/ttyAMA0`
GPIO SPI	连接外部 ADC（如 MAX31865）	高速数据传输	引脚占用多，协议复杂	`[mcu]` 下定义 `spi_bus:`

排障提示：如果遇到“MCU 无法连接”的错误，首先检查 ls /dev/serial/by-id/* 是否能看到设备。如果看不到，检查 USB 线缆是否数据线（而非仅充电线），并确认主板供电正常。切勿在打印时热插拔 USB 线，这可能导致 MCU 固件崩溃。

4.3 宏与配置系统：print.cfg 与 gcode_macro

Klipper 的灵活性很大程度上归功于其强大的配置系统。所有硬件定义和行为逻辑都集中在 printer.cfg 文件中（或通过 [include] 引入的多个 cfg 文件）。宏（Macro）则允许你自定义 G 代码命令，实现复杂的自动化流程。

4.3.1 配置系统（print.cfg）

配置文件采用 INI 格式，由多个配置节（Section）组成。每个配置节以 [section_name] 开头，包含若干 key: value 参数。例如：

[stepper_x]
step_pin: PB13
dir_pin: !PB12
enable_pin: !PB14
microsteps: 16
rotation_distance: 40
endstop_pin: ^PC0
position_endstop: 0
position_max: 200
homing_speed: 50

[extruder]
step_pin: PB3
dir_pin: PB4
enable_pin: !PB5
microsteps: 16
rotation_distance: 33.5
nozzle_diameter: 0.400
filament_diameter: 1.750
heater_pin: PC8
sensor_type: NTC 100K
sensor_pin: PC4
control: pid
pid_Kp: 22.2
pid_Ki: 1.08
pid_Kd: 114

关键参数解释：step_pin 和 dir_pin 定义了 MCU 引脚；rotation_distance 是电机旋转一周移动的距离（mm），这是校准步进电机的核心参数；endstop_pin 前的 ^ 表示启用上拉电阻；! 表示低电平有效。配置错误是导致打印机不动作或异常发热的主要原因，修改配置后必须执行 FIRMWARE_RESTART 命令。

4.3.2 宏系统（gcode_macro）

宏允许你将一系列 G 代码命令封装成一个自定义命令。例如，常见的 START_PRINT 宏可以包含加热热床、加热喷头、自动调平、清理喷嘴等步骤。宏支持参数传递、变量、条件判断和循环，使其成为一个轻量级的编程语言。

[gcode_macro START_PRINT]
description: 开始打印前的初始化序列
gcode:
    # 获取切片器传入的参数
    {% set BED_TEMP = params.BED_TEMP|default(60)|float %}
    {% set EXTRUDER_TEMP = params.EXTRUDER_TEMP|default(200)|float %}
    # 加热热床和喷头
    M140 S{BED_TEMP}
    M104 S{EXTRUDER_TEMP}
    # 等待温度到达
    M190 S{BED_TEMP}
    M109 S{EXTRUDER_TEMP}
    # 执行自动调平
    G28
    BED_MESH_CALIBRATE
    # 清喷嘴
    G1 X10 Y10 Z10 F3000
    G1 X50 Y50 Z10 F3000

在切片器中，你可以通过 START_PRINT BED_TEMP=70 EXTRUDER_TEMP=210 调用此宏，实现不同材料不同温度的灵活控制。宏中使用了 Jinja2 模板语言，params 对象包含了调用时传入的所有参数。

实战建议：在编写宏时，务必使用 _EXCLUDE_OBJECT_DEFINE 和 EXCLUDE_OBJECT_START 等命令来支持多对象打印时的排除功能。同时，利用 SET_GCODE_VARIABLE 可以在宏之间共享变量，例如记录当前打印的层数。

4.4 案例拆解：从配置到打印的完整链路

为了将上述概念串联起来，我们以一个实际场景——“新主板首次通电并完成一次测试打印”——来演示 Klipper 各组件如何协同工作。

4.4.1 场景背景与初始状态

你有一台基于 BTT Octopus 主板的 CoreXY 打印机，已刷入 Klipper 固件，并连接至树莓派。此时，printer.cfg 文件为空（或仅有默认模板）。目标：完成步进电机方向校准、限位开关验证，并成功打印一个 20mm 的校准立方体。

4.4.2 操作流程与关键数据

硬件连接确认：通过 ls /dev/serial/by-id/ 确认 USB 设备识别为 usb-Klipper_stm32f446xx_...。在 printer.cfg 中写入 [mcu] serial: /dev/serial/by-id/usb-Klipper_stm32f446xx_...。
最小配置启动：仅配置 [mcu]、[printer]（设置 kinematics: corexy，max_velocity: 300，max_accel: 3000）和 [stepper_x]、[stepper_y]、[stepper_z]、[extruder] 的基本引脚定义。执行 FIRMWARE_RESTART，观察终端是否报错。
步进电机方向测试：在控制台发送 STEPPER_BUZZ STEPPER=stepper_x 命令。该命令会让 X 轴电机以特定模式振动。如果电机不振动或方向错误，需要修改 dir_pin 的值（添加或删除 !）。
限位开关验证：发送 QUERY_ENDSTOPS，手动按下 X 轴限位开关，观察状态是否从 open 变为 TRIGGERED。如果状态反转，调整 endstop_pin 前的 ^ 或 ! 参数。
配置宏与切片：在 printer.cfg 末尾添加 [gcode_macro START_PRINT] 和 [gcode_macro END_PRINT] 宏。在切片软件（如 SuperSlicer）中，将“开始 G 代码”设置为 START_PRINT BED_TEMP=[first_layer_bed_temperature] EXTRUDER_TEMP=[first_layer_temperature]。
执行打印：通过 Mainsail 上传 G 代码文件，点击“打印”。观察终端日志，可以看到：前端发送打印请求 → Moonraker 通知 Klipper 主机 → 主机解析 G 代码 → 执行 START_PRINT 宏（加热、调平）→ 开始运动规划 → 通过 USB 发送步进指令 → MCU 产生脉冲 → 打印机开始移动。

4.4.3 结果分析与复盘

打印完成后，测量立方体尺寸。如果 X 轴尺寸偏大（例如 20.4mm），说明 rotation_distance 偏大，需要按比例减小：新值 = 旧值 × (实际尺寸 / 目标尺寸)。如果出现层间错位，则可能是加速度过大导致失步，需要降低 max_accel。这个案例展示了 Klipper 配置的迭代过程：硬件定义 → 单项测试 → 宏逻辑 → 整体执行 → 参数校准。每一个环节都依赖于对核心架构的理解。

常见误区：很多初学者在修改 printer.cfg 后只发送 RESTART（仅重启主机进程），而忽略了 FIRMWARE_RESTART（会重新连接 MCU 并加载新配置）。如果修改了引脚定义，必须使用 FIRMWARE_RESTART。另外，宏中的 M140（设置热床温度）和 M104（设置喷头温度）是非阻塞的，而 M190 和 M109 是阻塞等待的，错误使用会导致打印流程卡死。

4.5 总结与复盘

Klipper 的架构设计哲学是“把复杂留给上位机，把简单留给 MCU”。通过本章学习，你应该掌握以下核心要点：

组件边界：Klipper 主机负责“思考”（规划），Klipper 固件负责“执行”（脉冲），Moonraker 负责“翻译”（API），前端负责“展示”（UI）。
通信链路：USB 是首选，GPIO 是补充。通信稳定性是打印质量的基础，排查问题时应首先确认 ls /dev/serial/by-id/ 是否正常。
配置与宏：printer.cfg 是硬件定义文件，gcode_macro 是行为定义文件。掌握 Jinja2 模板语法是进阶的关键。
调试方法论：使用 STEPPER_BUZZ 测试电机，使用 QUERY_ENDSTOPS 测试限位，使用 FIRMWARE_RESTART 重载配置。这些命令是日常维护的必备工具。