Voron V2.4 Quad Gantry Leveling — Complete Guide

V2.4 校准 Gantry

Quad Gantry Leveling (QGL) is the defining calibration feature of the Voron V2.4. Unlike any other consumer 3D printer, the V2.4 uses four independently controlled Z stepper motors — one at each corner of the flying gantry — to keep the print surface perfectly parallel to the toolhead's XY plane. When QGL is working correctly, your first layer is uniform across every corner of a 350mm build plate. When it fails, you get first-layer adhesion problems on one side of the bed, Z banding at specific heights, or in worst cases, the nozzle crashes into the bed. 最后更新：2025年5月。

本指南涵盖完整的 QGL 工作流程：为什么 V2.4 的四电机设计需要 QGL（以及 Trident 的三电机 Z_TILT_ADJUST 为何不同）、限位传感器类型及配置、printer.cfg 中的 QGL 设置、首次使用 force_move 运行 QGL、常见故障排除（限位触发问题、Z 电机卡死、龙门扭曲）、皮带同步技术、QGL 后的操作（Z 偏移和热床网格），以及推荐的每周维护计划。

为什么 QGL 是 V2.4 的独特功能

Voron V2.4 采用“飞行龙门”设计，整个 XY 龙门通过四个 Z 丝杠上下移动，每个丝杠由专用步进电机驱动。这与以下设计有根本不同：

• 床甩打印机（Prusa、Bambu）： The bed moves on Z, the gantry is fixed. Leveling means adjusting the bed, not the gantry.
• Voron Trident： The Trident uses three Z motors driving the print bed up and down against a fixed gantry. Its Z_TILT_ADJUST levels the bed, not the gantry. Three motors define a plane perfectly; four motors are over-constrained by nature.
• Voron V0.2： A single Z motor with a leadscrew and belt synchronization. No auto-leveling needed — the bed is manually leveled against a fixed gantry.

V2.4 的四个 Z 电机带来了一个关键挑战：系统是过约束的。如果框架不完美方正，或两侧皮带张力不同，龙门将“扭曲”——相对于框架旋转——并在某些 Z 高度卡死。QGL 通过使用 Z 限位作为参考点来解决此问题。它独立移动每个 Z 电机，直到所有四个限位同时触发，确保龙门在限位位置与框架平行。由此假设丝杠足够一致，以在所有高度保持平行。

QGL 与 Z_TILT_ADJUST (Trident) 的区别

虽然两个命令都针对工具头调平打印表面，但机械原理不同：

• QGL（V2.4）： QUAD_GANTRY_LEVEL uses the Z endstops — typically located on the gantry itself — as reference points. Each Z motor moves independently until the endstop at that corner triggers. QGL assumes the endstops are all at the same height relative to the frame. If one endstop is 0.1mm higher than the others, the gantry will be 0.1mm out of level. QGL runs in one pass typically under 20 seconds.
• Z_TILT_ADJUST（Trident）： Uses the print bed probe to measure bed tilt at multiple points, then adjusts the three Z motors to tilt the bed until it's parallel to the toolhead. Z_TILT_ADJUST doesn't care about endstop height accuracy — it measures the actual bed position and corrects to make it level. Z_TILT_ADJUST is more forgiving of endstop inaccuracies but requires a functioning probe and takes 2-3 minutes.

关键要点： QGL requires very accurate, consistent Z endstop installation. If your V2.4 won't level properly, the first things to check are endstop physical position and wiring, not the QGL configuration itself.

Z 限位类型及配置

V2.4 需要四个 Z 限位——每个 Z 电机一个。两种常见方法：

机械限位（标准 Voron 设计）

原始Voron V2.4设计使用安装在龙门架角落的机械微动开关。每个开关由水平螺丝（"限位螺丝"）触发，当龙门架降至最低位置时，该螺丝会接触Z轴承座上的金属片。

printer.cfg 中的配置：

[stepper_z]
endstop_pin: ^PC0
position_endstop: 0.0
position_min: -5
endstop_accuracy: 0.010

[stepper_z1]
endstop_pin: ^PC1
position_endstop: 0.0
position_min: -5

[stepper_z2]
endstop_pin: ^PC2
position_endstop: 0.0
position_min: -5

[stepper_z3]
endstop_pin: ^PC3
position_endstop: 0.0
position_min: -5
    

The position_min: -5 is critical — it allows each Z motor to move 5mm below the nominal endstop position. QGL needs this negative range because it moves motors downward to find the endstop trigger point. Without it, QGL will hit the software limit and abort.

限位开关精度： Mechanical microswitches typically have 0.01-0.03mm repeatability. This is adequate for QGL (which targets ±0.02mm leveling tolerance), but the switches must be clean and debris-free. A grain of filament dust under the switch lever can shift the trigger point by 0.1mm.

基于探针的限位（Klicky、Unklicky、Voron Tap）

一些V2.4构建使用打印床探针作为Z限位，用从单次探针测量得出的虚拟限位替代四个机械开关。这种方法提高了精度（如Voron Tap等探针具有0.005mm重复性），但增加了复杂性：你需要在四个床位置进行探测、计算偏移并配置虚拟限位。

For probe-based setups, add [quad_gantry_level] to your config:

[quad_gantry_level]
gantry_corners:
  -50, -50
  -50, 350
  350, -50
  350, 350
  ; Adjust coordinates to match your build plate corners
probe_offsets:
  0, 25, 0.5
  ; Offset is X, Y, Z from probe to nozzle
speed: 200
horizontal_move_z: 10
retry_tolerance: 0.02
max_adjust: 2.0
    

The gantry_corners define where the gantry is probed. The coordinates should place the probe at approximately the same XY positions as the four Z leadscrews. The retry_tolerance of 0.02mm means QGL will repeat the adjustment until all four corners are within 0.02mm of the same height. max_adjust: 2.0 prevents QGL from making extreme adjustments — if needed movement exceeds 2mm, it aborts. This protects against a misconfigured system damaging itself.

在 printer.cfg 中配置 QGL

For the standard mechanical endstop setup, you don't need a [quad_gantry_level] section at all — Klipper uses the four [stepper_z] sections automatically. However, adding the explicit section gives you finer control:

[quad_gantry_level]
gantry_corners:
  0, 0
  0, 300
  300, 0
  300, 300
  ; Match your build plate XY bounds
speed: 100
horizontal_move_z: 5
retry_tolerance: 0.02
max_adjust: 2.0
    

参数说明：

• gantry_corners: XY coordinates of the Z endstop positions. For mechanical switches, these are the XY positions of the endstop triggers on the gantry. For probe-based, these are the probe XY positions corresponding to each Z motor. List them in the same order as your [stepper_z], [stepper_z1], etc.
• speed: Speed of Z movement during leveling (mm/min). 100 is slow and safe for initial calibration. After verification, you can increase to 200-300mm/min.
• horizontal_move_z: Lift height before moving XY between corners. 5mm is safe — high enough to clear any bed clips or PEI sheet edges.
• retry_tolerance: Acceptable deviation in mm. 0.02mm is the standard for Voron — tighter than most printers need, but achievable with careful endstop setup.
• max_adjust: Maximum adjustment per motor per retry. If the gantry is 5mm out of level, it would take multiple QGL cycles to correct. 2.0mm prevents aggressive corrections that could bind the gantry.

首次运行 QGL — Force_Move 初始调平

When you first assemble a V2.4, or after major disassembly, the gantry may be far from level — sometimes 5-10mm off between corners. QGL's max_adjust of 2mm will abort before fully correcting this. You need to manually rough-level the gantry first using Klipper's FORCE_MOVE or manual paper/feeler gauge method.

初始粗调平步骤

1. 归位龙门架： Run G28 to home all axes. The gantry will move down until each Z endstop triggers. Since the gantry is out of level, some endstops will trigger before others. This is expected.
2. 检查哪些限位开关触发： Run QUERY_ENDSTOP for each Z endstop:

   QUERY_ENDSTOP NAME=stepper_z
   QUERY_ENDSTOP NAME=stepper_z1
   QUERY_ENDSTOP NAME=stepper_z2
   QUERY_ENDSTOP NAME=stepper_z3

   Note which endstops show "triggered" and which show "open." The triggered ones are the lowest corners.

3. 使用 FORCE_MOVE 抬高较低角落： For each motor whose endstop did NOT trigger, move it upward slightly:

   FORCE_MOVE STEPPER=stepper_z1 DISTANCE=2 SPEED=5
   FORCE_MOVE STEPPER=stepper_z2 DISTANCE=2 SPEED=5
   FORCE_MOVE STEPPER=stepper_z3 DISTANCE=2 SPEED=5

   The DISTANCE is a guess — start with 1-2mm. The slow speed (5mm/s) prevents the gantry from binding.

4. 重新归位并检查： Run G28 again. Check endstop status. Repeat steps 2-4 until all four endstops trigger on the same G28 cycle. When all four trigger, the gantry is roughly level within the endstop accuracy (±0.03mm for mechanical switches).
5. 运行 QGL： QUAD_GANTRY_LEVEL. It should complete in one pass. If it retries more than 3 times, your gantry still isn't level enough — go back to force_move.

替代方案：用于初始调平的胶带/纸片法。 If you don't want to use FORCE_MOVE, you can mechanically adjust the gantry using paper feeler gauges:

1. Home the gantry with G28
2. 在 Z 限位开关位置处的每个龙门架角落下放置一张标准打印机纸
3. 手动转动每个 Z 丝杠联轴器（用手，在断电状态下），直到所有四张纸具有相同的阻力
4. 通电，归位，并运行 QGL

常见 QGL 故障及解决方案

限位触发故障

症状: QGL reports "Endstop not triggered" or the same endstop fails to trigger across multiple attempts.

解决方案：

• 检查限位开关接线——Voron 上的微动开关在龙门架移动期间容易发生连接器移位
• 验证限位开关螺丝接触开关杆——如果螺丝太短，开关不会触发。稍微旋出螺丝
• 检查开关杆上的碎屑（耗材碎片、油脂）——用异丙醇和压缩空气清洁
• 用万用表测试限位开关：按下开关时，导通应断开
• 检查开关安装——V2.4 打印部件在热外壳中可能随时间变形。如果开关支架变形，开关可能无法与触发螺丝对齐

Z 电机在特定高度卡死

症状： QGL succeeds, but during a print, Z movement becomes rough or noisy at certain heights. The gantry appears to "stick" and then jump.

解决方案：

• 检查丝杠对齐——每个 Z 丝杠应与 Z 型材完美平行。在丝杠和型材之间使用直角尺。如果未对齐，松开 Z 电机支架并重新定位
• 验证 Z 电机联轴器——电机和丝杠之间的柔性联轴器中间应有 2-3mm 的垂直间隙。如果联轴器完全压缩或完全伸展，则丝杠长度与框架高度不匹配
• 检查 Z 螺母块——龙门架上的 POM（塑料）螺母块应在 Z 丝杠上自由滑动。如果卡住，则丝杠有毛刺或螺母块过度拧紧到龙门架型材上
• 润滑丝杠——在每个丝杠上涂抹少量 PTFE 或锂基润滑脂，并让 Z 全程运行 5-10 次以分布均匀

龙门扭曲（Racking）

症状： After QGL, the gantry appears level at the Z endstop position, but at mid-height or full height, one corner is higher than the others. Measured by moving the gantry to mid-height and measuring from gantry extrusion to top frame on each side.

解决方案：

• 皮带张力不均匀——使用张力计测量所有四个角落的 Z 皮带张力。任意两个角落之间的差异应小于 0.5 N/cm
• 检查所有四个 Z 皮带长度相同——如果您更换了一条皮带而未更换其他，张力和拉伸特性将不同
• 检查 Z 皮带路径——皮带摩擦打印部件或型材会产生不均匀负载。寻找皮带上表明摩擦的光亮区域
• 框架方正度——扭曲的框架会导致龙门架在上升时倾斜。检查框架对角线（左上到右下和右上到左下）。在 350mm V2.4 上，它们应在 0.5mm 内匹配
• 验证所有四个 Z 轴承（在 Z 轴承座中）正确就位。轴承在支架中倾斜会增加一侧的摩擦

皮带同步技术

V2.4使用GT2皮带将Z电机连接到丝杆。四个Z电机是独立的。然而，它们应同步运动——当一个丝杆转动时，其他丝杆必须以相同速率转动，以使龙门架保持水平。皮带同步意味着确保所有四条皮带具有相同的张力且无松弛。

Z 轴皮带张紧步骤：

1. Home the gantry with G28 so all four endstops are triggered
2. 在每条皮带上相对于Z电机皮带轮的相同位置用白色标记笔做标记
3. 在每条皮带最长跨度的中心处拨动皮带。四条皮带的频率应相同。使用手机上的吉他调音器应用
4. V2.4 Z皮带的参考频率：55-70 Hz（比X/Y皮带低一个八度）。如果皮带声音偏低，则将其拧紧；如果偏高，则将其调松
5. 调整一条皮带后，重新检查所有四条——调整一条会略微影响张力分布
6. 皮带调整后重新归位并重新运行QGL

皮带更换： Always replace all four Z belts at the same time, even if only one is damaged. Old belts stretch differently from new belts, creating unequal tension that manifests as gantry racking at specific Z heights. Use genuine Gates PowerGrip GT2 belts for consistent stretch characteristics.

QGL 之后 — Z 偏移与热床网格

QGL确保龙门架与框架平行，但它不设置你的Z偏移——即喷嘴与床面之间的距离。接下来进行：

设置 Z 偏移

1. Run G28 and QUAD_GANTRY_LEVEL to prepare the printer
2. 将热床加热至打印温度（ABS为100°C），并等待5分钟使热膨胀稳定
3. 将热端加热至打印温度
4. Run PROBE_CALIBRATE if using a probe, or Z_ENDSTOP_CALIBRATE for endstop-based Z offset
5. 使用纸张法：在喷嘴和热床之间放置一张纸，使用TESTZ命令降低喷嘴，然后调整直到纸张有轻微阻力
6. Run ACCEPT and SAVE_CONFIG

QGL 后的热床网格

QGL完成后并设置Z偏移后，校准床网：

1. BED_MESH_CALIBRATE with a 7×7 grid (for 300mm+ beds) or 5×5 grid (for 250mm)
2. Output the mesh: BED_MESH_OUTPUT PGP=1 to get a visual representation
3. 经过正确QGL后的理想网格偏差：整个热床小于0.15mm。如果偏差超过0.3mm，检查热床是否翘曲或QGL是否存在问题
4. Save the profile: BED_MESH_PROFILE SAVE=default
5. In your PRINT_START macro, load the mesh: BED_MESH_PROFILE LOAD=default

重要顺序： Always run QGL before bed mesh calibration. QGL sets the gantry level relative to the frame. Bed mesh measures the bed surface relative to the gantry. If you mesh first and then QGL, the mesh compensation will be wrong because the gantry moved.

每周 QGL 维护计划

QGL不是一次性设置后就不再调整的校准。V2.4的龙门架会受到热循环、皮带拉伸和轴承磨损引起的机械漂移。遵循以下时间表：

• 每次打印前： QGL is typically included in your PRINT_START macro, so it runs automatically. This is ideal — each print starts with a freshly leveled gantry. The run takes only 10-20 seconds.
• 每周： Check Z belt tension with a tension gauge or frequency app. Record the frequency for each belt. If one belt has drifted more than 5 Hz from the others, retension all four.
• 每月： Run QGL manually and compare the adjustment values Klipper reports. If you see increasing adjustment values over time (e.g., one corner needs 0.5mm more correction each month), you have a developing mechanical issue — check for bearing wear, belt stretch, or leadscrew degradation.
• 每 6 个月： Perform the full initial-leveling procedure (force_move or paper method) to verify the gantry hasn't drifted mechanically. Clean all four Z endstops with contact cleaner. Inspect endstop mounts for warping.
• 机箱温度变化后： If you switch from printing PLA (enclosure open or cool) to ABS (enclosure hot at 50-60°C), the frame and gantry will expand differently. Run QGL after the enclosure has stabilized at the new temperature. A temperature change of 20°C can shift the gantry by 0.05-0.10mm on a 350mm V2.4.

故障排除快速参考