Voron 的 Klipper 设置 — 完整配置指南

固件 Klipper Tutorial

Klipper 固件让 Voron 打印机脱颖而出。与传统的基于 Marlin 的固件（所有计算都在主板的微控制器上进行）不同，Klipper 将运动规划卸载到单板计算机（Raspberry Pi、CB1、BTT Pi 等），并仅向主板发送低级步进命令。这可以实现更高的步进速率、更复杂的运动算法（输入整形器、压力提前）以及实时调整，而无需重新刷新固件。

最后更新时间：2025 年 5 月。 This guide covers the complete Klipper setup process for Voron printers: installing on various SBC options, flashing the controller board, building the printer.cfg from official Voron templates, calculating stepper rotation distances, configuring endstops, running PID auto-tuning, calibrating input shaper (with and without an accelerometer), setting up pressure advance, bed mesh, and creating useful macros. We also include troubleshooting for the most common errors.

运行 Klipper 的硬件选项

小型计算机公司	中央处理器	内存	价格（中国直达）	笔记
树莓派 4B 2GB	BCM2711（4核）	2GB	$45-60	最受支持，很容易找到
树莓派 5 4GB	BCM2712（4核）	4GB	$60-80	矫枉过正但面向未来
BTT CB1 (v2.2)	全志H616（4核）	1GB	$15-25	直接替换 Pi，预算选项
BTT Pi V1.2	全志H616（4核）	1GB	$30-40	集成CB1，物超所值
橙子圆周率零2	全志H616（4核）	1GB	$20-30	需要手动操作系统设置

对于大多数 Voron 构建者来说，Raspberry Pi 4B 2GB 或 BTT CB1/Pi 组合是最佳选择。 Pi 4B 拥有最好的社区支持和文档。 CB1 更便宜且运行良好，但马力稍低 — 对于单个打印机来说还好，但在相机或多个 Klipper 实例上可能会遇到困难。

专业提示： If you're going the China-direct route, the BTT CB1 + BTT Pi V1.2 combination is hard to beat at $30-40 total. It provides the same functionality as a Pi 4B at half the price.

安装 Klipper — 一步一步

选项 A：Raspberry Pi 操作系统上的 Klipper（推荐 Pi 用户）：

Flash Raspberry Pi OS (64-bit, Lite) to an SD card using Raspberry Pi Imager
在闪烁期间启用 SSH 和 WiFi（Imager 中的齿轮图标）
SSH into the Pi: ssh pi@voron-printer.local
Run the KIAUH installer (Klipper Installation And Update Helper): cd ~ && git clone https://github.com/dw-0/kiauh.git && ./kiauh/kiauh.sh
在 KIAUH 中选择 Klipper、Moonraker (API)、Mainsail (Web UI) 和 KlipperScreen（可选）
KIAUH 自动处理所有依赖项和配置

选项B：CB1 / BTT Pi上的Klipper：

从 BTT GitHub 页面下载 CB1 特定的 Armbian 版本
使用 balenaEtcher 闪存至 eMMC 或 SD 卡
SSH 输入（默认：root@192.168.x.x，密码：pi）
以与上面选项 A 相同的方式运行 KIAUH
注意：CB1 需要特定的内核构建 - 不要使用标准的 Raspberry Pi 操作系统映像

选项 C：MainsailOS（一体化解决方案）： Download the MainsailOS image for your SBC platform. It comes pre-configured with Klipper, Moonraker, and Mainsail. This is the easiest option for beginners — just flash and go. You'll still need to flash the controller board firmware and configure printer.cfg manually.

刷新控制器板

Klipper 在 SBC 上运行后，您需要将 Klipper 固件刷新到您的控制器板（BTT Octopus、SKRat、Fysetc Spider 等）。

一般流程（适用于大多数主板）：

cd ~/klipper and run make menuconfig
选择您的微控制器架构（例如，Octopus 的 STM32F407）
设置通信接口（USB 或 CAN 总线，具体取决于您的设置）
设置波特率（USB 或 CAN 总线速度为 250000）
Run make to build the firmware binary
For USB: copy out/klipper.bin to an SD card (rename to firmware.bin), insert into board, power on. The board will auto-flash on boot.
For CAN bus: flash via the bootloader using make flash FLASH_DEVICE=/dev/serial/by-id/...

常见板卡配置：

BTT 八达通专业版（STM32F446）： Use STM32F446, 256K bootloader offset, USB DFU interface
BTT SKRat（STM32F405）： Use STM32F405, USB, 250000 baud
Fysetc Spider v2.2（STM32F407）： Use STM32F407, USB, 250000 baud
曼塔M8P（STM32H723）： Use STM32H723, USB DFU, requires DFU mode jumper

排除闪存故障： If the board doesn't appear after flashing, check: (1) correct microcontroller selected in menuconfig, (2) correct bootloader offset, (3) SD card formatted as FAT32 with MBR partition table, (4) board is in DFU/bootloader mode (some boards require a jumper or button press).

构建 Printer.cfg

The official Voron Klipper configurations are maintained in the Voron GitHub repository. Start by copying the template for your printer model and size.

需要定制的关键部分：

[单片机]： Set the serial path to your controller board. Find it with ls /dev/serial/by-id/*. It should look like /dev/serial/by-id/usb-Klipper_stm32f446xx_12345-if00.

[步进器_x]、[步进器_y]、[步进器_z]： Set endstop pins, position endpoints, and homing speed. The Voron templates have correct values for standard builds. Only change if you've modified your printer geometry.

旋转距离——最常见的配置错误： This value tells Klipper how far a linear axis moves per full motor rotation. Get it wrong and your printer will be dimensionally inaccurate. Calculate it:

X/Y（皮带驱动）： rotation_distance = belt_pitch × pulley_teeth. For GT2 belts (2mm pitch) with a 20-tooth pulley: 2 × 20 = 40
Z（丝杠驱动）： rotation_distance = lead_pitch × number_of_starts. For T8 leadscrew (2mm pitch, 4-start): 2 × 4 = 8
挤出机（齿轮）： Must be measured empirically. Mark the filament 120mm above the extruder, extrude 100mm, measure actual extrusion. Formula: actual_rotation_distance = rotation_distance × (actual_extruded / requested_extruded). Start with the value from the Voron template (~22.678 for CW2).

终点挡板和探头配置

物理终点站： X and Y endstops on the Voron are mechanical switches or optical sensors. Configure them in the [stepper_x] and [stepper_y] sections with endstop_pin pointing to the correct pin on your board. Set homing_speed: 20 and position_endstop to match your printer's corner dimensions.

Z 探针（虚拟终点挡块）： Vorons use the nozzle probe method — the nozzle touches a switch or uses an inductive probe (Omron TL-Q5MC2 or PL-08N) to detect the bed surface. Configure the probe in Klipper as a virtual endstop:

[stepper_z] section: endstop_pin: probe:z_virtual_endstop
[probe] section: configure the specific probe type, x_offset, y_offset, and z_offset
For the Omron/PL-08N inductive probe: sensor_type: hall, verify the probe's trigger distance (typically 2-4mm for inductive probes)
Run PROBE_ACCURACY to verify the probe is repeatable (should be ±0.01mm or better)

PID自整定

PID（比例-积分-微分）调节可优化打印机维持目标温度的方式。 Klipper 的自动调整非常出色。

挤出机PID校准： Run PID_CALIBRATE HEATER=extruder TARGET=245 (use 250 for ABS, 220 for PLA). The process takes about 10 minutes and cycles the heater on/off to measure thermal response.

床PID校准： Run PID_CALIBRATE HEATER=heater_bed TARGET=100 (or 110 for PC/PA prints). Bed PID tuning takes longer (15-20 minutes) because of the larger thermal mass.

保存结果： After each calibration, Klipper shows the PID values. Use SAVE_CONFIG to write them to your printer.cfg. Typical values for a Rapido UHF (50W): P=25-35, I=1.0-1.5, D=100-140. For a 350mm bed (500-800W): P=500-800, I=0.5-1.0, D=100-200.

输入整形器校准

输入整形器通过计算打印机的共振频率并过滤加速度曲线以避免激发振铃，从而消除振铃（重影）。

方法A：ADXL345加速度计（推荐）：

在工具头上安装 ADXL345（使用 GitHub 存储库中特定于 Voron 的安装）
通过 SPI（推荐）或 I2C 连接到 SBC
Add [adxl345] section to printer.cfg with the correct CS pin
Run ACCELEROMETER_MEASURE at 100 mm/s on X, then Y
Run ACCELEROMETER_GRAPH to visualize the frequency response
根据频率图选择整形器类型（ZV、MZV、ZVD、EI、2HUMP_EI、3HUMP_EI）
Set shaper_freq_x and shaper_freq_y to the measured resonant frequencies
运行振铃测试打印以验证

方法B：手动调谐（无加速度计）：

打印振铃测试塔（Thingiverse/Printables 上提供）
目视检查哪种整形器类型在每个频率下都能提供最干净的角落
Use the [input_shaper] section with trial-and-error frequency values, reprinting the test tower each time
此方法有效，但需要 5-10 次测试打印才能拨入。加速计的价格为 8 美元，并且可以节省时间。

推荐的 Voron 成型成型机轮廓：

V2.4 350mm：ZV 约为 50-55 Hz (X)、约为 45-50 Hz (Y)。最大加速度：8,000 mm/s²
Trident 300mm：MZV 约 55-65 Hz (X)、约 50-60 Hz (Y)。最大加速度：7,000 mm/s²
V0.2：~70-85 Hz 时为 2HUMP_EI（X 和 Y 类似）。最大加速度：10,000+ mm/s²

压力提前校准

压力提前通过在移动开始时稍微过度挤压和在结束时挤压不足来补偿热端中的细丝压缩。这消除了拐角处的凸出并提高了尺寸精度。

校准方法：

Enable pressure advance in printer.cfg: [pressure_advance] with a starting value of 0.04
打印 PA 调谐塔（PA 每隔 5mm 增加的空心方管）
检查拐角——在正确的 PA 值下，拐角是锐利的，没有凸出或挤压不足的情况
对于带有 CW2 挤出机的 Rapido/Dragon 热端：典型 PA 为 0.03-0.05
对于 Revo Voron：典型 PA 为 0.02-0.04（Revo 的集成隔热装置可减少压缩）
对于 Goliath：典型 PA 为 0.06-0.10（较大的熔化区 = 更多的压缩）

专业提示： Pressure advance is temperature-dependent. If you change materials or printing temperatures, re-run the PA calibration. Save different PA values in your START_PRINT macro based on the material being printed.

床网校准

床网格补偿映射床表面高度并在打印过程中调整 Z 轴移动，以保持整个床的第一层高度一致。

配置：

Add [bed_mesh] section to printer.cfg
设置probe_count：250mm床为5,5，350mm为7,7（更多点=更好的补偿但更慢）
设置 mesh_pps: 2,2（每段点数 — 插值质量）
设置算法：双三次（最佳质量）
Run BED_MESH_CALIBRATE before each print, or add it to your START_PRINT macro
View the mesh with BED_MESH_OUTPUT in the Mainsail console

解释床网格结果： A good bed mesh has a total variance (max - min) of 0.1mm or less. If you see 0.3mm+ variance, check: bed mounting screws tight? Bed thermal expansion (heat to printing temp before meshing)? Frame squareness? Z leadscrews properly aligned?

对 Voron 构建者有用的宏

宏自动执行重复性任务。以下是任何 Voron 人都必须具备的要素：

开始打印： Loads bed mesh, sets temperatures based on filament type, homes all axes, runs QGL (V2.4) or Z_TILT_ADJUST (Trident), primes the nozzle. This is the most important macro — get it right and every print starts consistently.
END_打印： Retracts filament, lifts toolhead, parks gantry, turns off heaters, turns off fans (after cool-down).
打印统计： Shows elapsed time, filament used, estimated time remaining on the Mainsail dashboard.
BED_SCREWS_ADJUST： For manual bed leveling on the Trident — probes each screw position and tells you how much to turn each knob.
Z_TILT_ADJUST： For the Trident — automatically adjusts the three Z motors to tram the bed to the gantry.
四龙门级： For the V2.4 — levels all four gantry corners. Run before every print.
灯丝_更改： Pauses print, retracts filament, waits for user to load new filament, purges, resumes.
取消_打印： Emergency stop macro that parks the toolhead, turns off heaters, and aborts the print cleanly.

排除常见 Klipper 错误

“MCU 已断开连接” — Check USB cable, power cycle the controller board, check for loose CAN bus connections. Most common cause: the controller board power supply is marginal or the USB port is dropping power.
“无法连接到 Moonraker” — Moonraker service not running. Check sudo systemctl status moonraker. Look for port conflicts or incorrect config file path.
“运动前触发终点停止装置” — An endstop switch is stuck or incorrectly wired. Use QUERY_ENDSTOPS to check each endstop's state. If triggered when not pressed, the switch is shorted or the wiring is reversed.
“移出范围” — Your position_max or position_min values don't match your printer geometry. Double-check that your position_endstop + homing direction is consistent with the axis orientation.
“归位期间触发探头” — The probe is triggering prematurely. Check that the probe's trigger distance is set correctly and that it's not hitting the bed edge during XY moves.
“加热器未启动” — Check your heater_pin and max_power settings. Use a multimeter to verify the heater cartridge has continuity and is getting power. The SSR or MOSFET may be faulty.
“步数时间太长” — Your microstepping or acceleration is too high for the MCU's step rate. Reduce max_accel or increase microstepping from 256 to 128 or 64.
“计时器太近了” — Similar to above — the MCU can't generate steps fast enough. Reduce acceleration or check that your stepper driver is not overheating (thermal throttling).

最终配置清单

在宣布 Klipper 设置完成之前，请验证以下各项：

所有轴均正确归位（X、Y、Z）
终点限位器可靠触发（每个测试 5 次）
探头精度测试通过（±0.01mm 或更好）
床网格会在 START_PRINT 中自动加载
挤出机和床的PID调节完成
输入整形器启用正确的频率
压力提前校准
挤出机旋转距离验证（标记和测量测试）
所有更改后已调用 SAVE_CONFIG
紧急停止（M112）工作正常

Klipper 使 Voron 从一台优秀的打印机变成了一台卓越的打印机。初始设置需要几个小时，但一旦拨通，您将拥有一台能够以最少的维护生产一致、高质量打印的机器。输入整形器、压力推进和床网的组合——所有这些都由 Klipper 实现——赋予了 Voron 打印机传奇的高速打印质量。