Klipper 调平全指南从纸张测试到自动探针的床面校准实战【免费下载链接】klipperKlipper is a 3d-printer firmware项目地址: https://gitcode.com/GitHub_Trending/kl/klipper导读床面调平Bed Leveling有时也称 bed tramming是 Klipper 获得高质量打印件的关键前置步骤床面未校准会直接导致首层附着不良、翘边warping以及贯穿整个打印过程的隐性缺陷。本文以 Klipper 官方文档 docs/Bed_Level.md 为骨架系统讲解床面调平的目标与精度要求、最核心的纸张测试paper test操作流程并结合仓库内 manual_probe.py、probe.py、bed_screws.py、screws_tilt_adjust.py 等源码揭示 TESTZ 二分逼近、探针校准与重复性验证等底层原理帮助你掌握从手动调平到自动探针调平的完整实战方案。调平的本质目标精度 25 微米理解调平目标比执行操作更重要。如果打印过程中给打印机下发了X0 Y0 Z10的指令那么目标是让喷嘴距离床面恰好 10mm当继续下发X50 Z10时目标是在整段水平运动中喷嘴与床面的距离始终保持在 10mm。Klipper 要求 Z 轴距离的校准精度达到约25 微米0.025mm以内。这是一个远小于人类头发直径的尺度无法用肉眼测量且热膨胀等细微效应都会影响该尺度下的测量。获得高精度的秘诀在于使用可重复的过程并借助打印机自身运动系统的高精度来完成调平。第一步选择合适的校准机制不同结构的打印机采用不同的调平方法但它们都最终依赖于下文描述的纸张测试。在运行任何校准工具之前必须先完成 Config_checks.md 中描述的检查流程验证温度、加热器、步进电机使能脚、限位开关、电机方向与运动等确认基础运动正常后再进行床面调平。按打印机类型选择对应文档配有自动 Z 探针的打印机先按 Probe_Calibrate.md 校准探针Delta 打印机参见 Delta_Calibrate.md带床面调平螺丝与常规 Z 限位开关的打印机参见 Manual_Level.md。校准期间可能需要把 Z 轴的position_min设为负数例如position_min -2。打印机即使在校准例程中也会强制执行边界检查设置为负数允许喷嘴移动到标称床面位置之下有助于确定床面的实际位置。这一点在源码中也有呼应probe.py中的HINT_TIMEOUT提示明确指出——如果探针移动距离不足而未触发请考虑降低 Z 轴最小位置Z 最小值可以为负以便探针走得更远。核心操作纸张测试Paper Test纸张测试是 Klipper 最主要的床面校准机制在喷嘴与床面之间放置一张普通复印纸命令喷嘴下降到不同 Z 高度直到来回推动纸张时感受到轻微摩擦。即使拥有自动 Z 探针也必须理解纸张测试——探针本身的校准恰恰依赖这个测试完成。测试准备用剪刀裁一小块矩形纸例如 5×3 cm。纸张厚度通常约 100 微米0.100mm精确厚度并不重要。检查喷嘴与床面确保没有塑料残留若喷嘴上有塑料先加热挤出机用金属镊子清除等挤出机完全冷却到室温再继续冷却期间用镊子随时清除溢出的塑料。必须在喷嘴与床面均为室温时进行纸张测试喷嘴加热后热膨胀会使喷嘴相对床面的位置发生变化典型膨胀量约 100 微米与一张纸的厚度相当。先在两者相等的假设下开始校准后续再精确测定二者的差值见下文确定热膨胀量一节。为何不在热态校准热态校准会把少量熔融塑料粘到纸上改变摩擦手感使校准更难做好同时大幅增加烫伤风险。热膨胀量是稳定值可轻易在校准后期被补偿。如果始终在某一种胶带或打印表面上打印可以直接带着该表面做测试。但要注意胶带本身有厚度不同胶带/打印表面会影响 Z 测量每种在用的表面都应重新做一次纸张测试。使用自动化工具确定精确 Z 高度务必使用自动化工具来获取精确 Z 高度Klipper 提供了多个辅助脚本MANUAL_PROBE、Z_ENDSTOP_CALIBRATE、PROBE_CALIBRATE、DELTA_CALIBRATE按上文选择合适的校准机制一节挑选即可。在 OctoPrint 终端窗口运行相应命令脚本会在终端输出中提示用户交互类似Recv: // Starting manual Z probe. Use TESTZ to adjust position. Recv: // Finish with ACCEPT or ABORT command. Recv: // Z position: ?????? -- 5.000 -- ??????当前喷嘴高度打印机当前理解的值显示在-- --之间右侧数字是最后一次大于当前高度的探测尝试高度左侧是最后一次小于当前高度的探测尝试高度若尚未尝试则显示??????。TESTZ 命令移动与二分将纸放在喷嘴与床面之间可折起纸的一角方便拿取来回推纸时尽量不要向下压床面然后用TESTZ命令让喷嘴向纸靠近TESTZ Z-.1TESTZ按相对距离移动喷嘴Z-.1即向床面靠近 0.1mm。移动停止后来回推纸感受摩擦反复执行TESTZ直到感受到轻微摩擦。若摩擦过大可用正值让喷嘴向上也支持TESTZ Z或TESTZ Z-做二分——移动到两次位置的中点。例如收到如下提示Recv: // Z position: 0.130 -- 0.230 -- 0.280执行TESTZ Z-会把喷嘴移到 Z0.1800.130 与 0.230 的中点可快速逼近一致的摩擦手感。Z与Z--则直接回到过去某次测量位置——上例中TESTZ Z--会把喷嘴移回 Z0.130。从源码看TESTZ的二分与跳跃逻辑实现在 manual_probe.py 的cmd_TESTZ第 255-283 行/-取相邻历史位置的中点同时受BISECT_MAX 0.200mm 单步上限约束/--直接跳到相邻历史位置每次测试的位置会插入有序列表past_positions因此report_z_status总能给出上一/下一参考值。此外move_z中Z_BOB_MINIMUM 0.500会在每次测试前先把喷嘴抬到目标高度以上 0.5mm 再下落保证运动方向一致、减少背隙误差。接受与中止找到轻微摩擦后执行ACCEPT即接受当前 Z 高度并继续对应的校准工具。摩擦的精确大小并不关键与热膨胀量、纸张厚度一样只需每次测试尽量保持相同的手感。若测试过程出错用ABORT命令退出校准工具。确定热膨胀量微调 Z 偏移完成调平后可以进一步精确计算热膨胀 纸张厚度 纸张测试摩擦量的综合影响。这种计算通常并非必需——多数用户发现简单的纸张测试已足够但需要时可按以下方法操作打印一个四壁笔直的测试件可使用 docs/prints/square.stl大型空心方块。切片时确保首层与后续层使用相同的层高和挤出宽度使用较粗的层高约为喷嘴直径的 75%不要使用裙边brim或筏层raft。打印完成后等其冷却取下检查最底层也可用手指/指甲沿底边划过。若底层沿四周轻微外鼓说明喷嘴离床面偏近可执行SET_GCODE_OFFSET Z.010抬升高度在后续打印中继续观察调整。此类调整通常以 10 微米0.010mm为单位。若底层持续比后续层窄则用SET_GCODE_OFFSET做负 Z 调整拿不准时先减小 Z 调整直到底层出现轻微外鼓再回退到外鼓消失。SET_GCODE_OFFSET的实现位于 gcode_move.py 的cmd_SET_GCODE_OFFSET第 208-226 行它同时支持Zpos绝对偏移与Z_ADJUSTadjust在现有偏移上累加两种参数并可选MOVE1立即移动喷嘴到新偏移位置。其语义在 G-Codes.md 中有详细说明例如SET_GCODE_OFFSET Z0.2后后续 G-Code 的 Z 高度都会加上 0.2mm。最稳妥的应用方式是在切片器中设置一个START_PRINTG-Code 宏让切片器在每次打印开始时调用该宏并在宏内加入SET_GCODE_OFFSET命令。详见 Slicers.md。各调平工具的源码级解析Z 限位开关校准Z_ENDSTOP_CALIBRATE对带独立 Z 轴的笛卡尔打印机Manual_Level.md 建议先归零home把喷嘴移到床面上方至少 5mm 处并移动到床面中心附近然后在终端运行Z_ENDSTOP_CALIBRATE随后按纸张测试步骤确定该位置喷嘴与床面的实际距离ACCEPT后执行SAVE_CONFIG把结果写回配置文件。其核心逻辑在 manual_probe.py 的z_endstop_finalize第 96-107 行新position_endstop等于当前 position_endstop - 纸张测试得到的床面 Z 值并通过configfile.set()暂存等待SAVE_CONFIG写入。工程建议尽量把 Z 限位开关装在 Z 轴远离床面的一端远离床面归零更稳健Z 归零总是安全的。若必须向床面方向归零建议把限位开关调整到在床面上方约 0.5mm 处触发——几乎所有限位开关都能安全地被按压超过触发点一小段距离。此时Z_ENDSTOP_CALIBRATE会报告一个小的正值约 0.5mmposition_endstop可降低意外撞床的风险。物理开关位置合适后后续微调都应在软件中完成再次运行Z_ENDSTOP_CALIBRATE或直接改配置中的 Zposition_endstop。床面螺丝手动调整BED_SCREWS_ADJUST利用床面螺丝调平的诀窍是在调平过程中借助打印机的高精度运动系统命令喷嘴移动到每颗螺丝附近然后调整螺丝直到床面与喷嘴距离一致。Klipper 的[bed_screws]工具需要指定每颗螺丝的 XY 位置[bed_screws] screw1: 100, 50 screw2: 100, 150 screw3: 150, 100若螺丝位于床面下方则指定其正上方的 XY 位置若螺丝在床面外则指定床面范围内离螺丝最近的位置。改完配置后执行RESTART加载然后运行BED_SCREWS_ADJUST该工具会把喷嘴移到每颗螺丝的 XY 位置并下降到 Z0此时用纸张测试调整喷嘴正下方的床面螺丝调整螺丝而非命令喷嘴移动直到推纸有轻微摩擦。之后运行ACCEPT或ADJUSTEDADJUSTED螺丝需要明显调整时使用通常超过约 1/8 圈工具会额外安排一轮螺丝调整ACCEPT无需明显调整时使用ABORT提前退出工具。工具在所有螺丝都验证为无需明显调整时才算成功完成。该方法最适合平面度好的打印面如玻璃与笔直导轨的打印机。源码层面bed_screws.py 的cmd_ACCEPT维护accepted_screws计数全部螺丝ACCEPT后若配置了_fine_adjust坐标则进入精调阶段否则输出 Bed screws tool completed successfully 结束。支持speed、probe_speed、horizontal_move_z、probe_height等配置参数。三螺丝高精度精调screwN_fine_adjust若打印机使用三颗螺丝且全部位于床面下方可进行第二阶段的高精度调平命令喷嘴移动到床面因单颗螺丝调整而位移更大的位置。例如螺丝位于 A、B、C 三点时调整 C 处螺丝会让床面沿 A、B 两点定义的摆线摆动图中绿线此时在 D 位置调整 C 螺丝可获得比 C 点直接调整更大的位移杠杆。启用方法是在[bed_screws]中添加额外坐标[bed_screws] screw1: 100, 50 screw1_fine_adjust: 0, 0 screw2: 100, 150 screw2_fine_adjust: 300, 300 screw3: 150, 100 screw3_fine_adjust: 0, 100启用后BED_SCREWS_ADJUST会先在每颗螺丝正上方做粗调全部接受后再在附加位置做精调每个位置继续使用ACCEPT/ADJUSTED。用探针计算螺丝调整量SCREWS_TILT_CALCULATE这是另一种借助 Z 探针BL Touch、电感传感器等校准床面水平的方法。需要确定探针位于螺丝正上方时对应的喷嘴坐标并写入配置[screws_tilt_adjust] screw1: -5, 30 screw1_name: front left screw screw2: 155, 30 screw2_name: front right screw screw3: 155, 190 screw3_name: rear right screw screw4: -5, 190 screw4_name: rear left screw horizontal_move_z: 10. speed: 50. screw_thread: CW-M3screw1始终是其他螺丝的参考基准系统假定它高度正确。先运行G28归零再运行SCREWS_TILT_CALCULATE输出类似Send: G28 Recv: ok Send: SCREWS_TILT_CALCULATE Recv: // 01:20 means 1 full turn and 20 minutes, CWclockwise, CCWcounter-clockwise Recv: // front left screw (base) : x-5.0, y30.0, z2.48750 Recv: // front right screw : x155.0, y30.0, z2.36000 : adjust CW 01:15 Recv: // rear right screw : y155.0, y190.0, z2.71500 : adjust CCW 00:50 Recv: // read left screw : x-5.0, y190.0, z2.47250 : adjust CW 00:02 Recv: ok含义解读front left screw 是参考点不要改动它front right screw 需顺时针转动 1 整圈又 1/4 圈CW 01:15rear right screw 需逆时针转动 50 分钟CCW 00:50rear left screw 需顺时针转动 2 分钟CW 00:02可忽略。注意这里的分钟指钟表表盘的分钟15 分钟即 1/4 圈。反复执行直到床面水平良好——通常以所有调整量低于 6 分钟为标准。若探针装在热端侧面带 X/Y 偏移请注意调整床面倾斜会使之前在有倾斜床面上做的探针校准失效务必在调整完螺丝后重新运行 Probe_Calibrate.md。MAX_DEVIATION 参数配合已保存的床面网格bed mesh使用用于确保床面水平没有偏离创建网格时的状态太远。例如把SCREWS_TILT_CALCULATE MAX_DEVIATION0.01加入切片器自定义启动 G-Code在加载网格之前若偏差超过限制此处 0.01mm将中止打印给用户调整螺丝并重新打印的机会。对应实现在 screws_tilt_adjust.py 的probe_finalize第 123-127 行任一螺丝与基准的偏差超过MAX_DEVIATION时抛出 bed level exceeds configured limits 错误。DIRECTION 参数当调平螺丝只能单向转动时使用。例如螺丝起始于最低或最高位置、只能单向转动来抬高或降低床面只能顺时针转则运行SCREWS_TILT_CALCULATE DIRECTIONCW只能逆时针则用DIRECTIONCCW。工具会选择合适的参考点使所有螺丝都能朝给定方向转动来完成调平。源码中该逻辑位于probe_finalize第 76-85 行有方向约束时以最高/最低螺丝为基准从而保证调整方向一致。自动探针校准与精度验证探针 X/Y 偏移校准对配置了[probe]或[bltouch]的打印机先归零并把喷嘴移到床面中心附近在探针下方贴一块美纹胶带在终端执行PROBE在胶带上探针正下方做标记用GET_POSITION记录工具头 XY例如X:46.5 Y:27再用一系列G1命令把喷嘴移到标记正上方并用GET_POSITION记录喷嘴位置。则x_offset 喷嘴X - 探针X y_offset 喷嘴Y - 探针Y把值写入 printer.cfg移除胶带RESTART生效。PROBE与GET_POSITION的输出格式可对照 G-Codes.md。探针 Z 偏移校准PROBE_CALIBRATEz_offset是探针触发时喷嘴与床面的距离对高质量打印至关重要。运行PROBE_CALIBRATE工具会先自动探测一次然后抬升喷嘴、移动到探测点上方的喷嘴位置并启动手动探针——若喷嘴没有移到自动探测点上方先ABORT并重新校准 XY 偏移。手动探针启动后按纸张测试确定实际距离ACCEPT后用SAVE_CONFIG保存。源码中 probe.py 的cmd_PROBE_CALIBRATE第 107-123 行先执行run_single_probe获得探针触发位置再抬升 5mm 并把喷嘴移动到ppos.bed_x/bed_y最后启动ManualProbeHelperprobe_calibrate_finalize第 94-105 行按公式z_offset 原z_offset - 纸张测试床面Z 探针触发床面Z计算并暂存新值。失效条件改动打印机运动系统、热端位置或探针位置都会使PROBE_CALIBRATE结果失效探针带 X/Y 偏移时任何床面倾斜调整调螺丝、DELTA_CALIBRATE、Z_TILT_ADJUST、QUAD_GANTRY_LEVEL等同样使其失效之后必须重新校准。一旦PROBE_CALIBRATE失效之前用探针获得的 Bed_Mesh.md 结果也随之失效需要在校准探针后重跑BED_MESH_CALIBRATE。探针重复性检查PROBE_ACCURACY校准完成后建议验证探针的可重复性归零、移到床面中心附近运行PROBE_ACCURACY。命令默认探测 10 次输出类似Recv: // probe accuracy: at X:0.000 Y:0.000 Z:10.000 Recv: // and read 10 times with speed of 5 mm/s Recv: // probe at -0.003,0.005 is z2.506948 ... Recv: // probe accuracy results: maximum 2.519448, minimum 2.506948, range 0.012500, average 2.513198, median 2.513198, standard deviation 0.006250判定标准理想情况最大值与最小值完全相同正常情况二者相差一个 Z 步距step distance或最多 5 微米0.005mm。步距 rotation_distance / (full_steps_per_rotation × microsteps)。上例中 Z 步距为 0.0125因此 range 0.012500 属正常。若 range 大于 25 微米0.025mm探针精度不足以支撑常规调平流程。可尝试调整探针速度PROBE_SPEED与探测起始高度来改善PROBE_ACCURACY支持用不同参数反复测试详见 G-Codes.md。若探针总体可重复但偶有离群值可通过 Config_Reference.md 中的samples参数让每次探测多次采样取均值/中位数来抵消。修改probe_speed、samples等设置后需RESTART并建议重新校准z_offset。如果始终无法获得可重复结果就不要用该探针做床面调平——Klipper 提供了多种手动探测工具见本文与 Manual_Level.md可以替代。从源码看PROBE_ACCURACY的统计实现在 probe.py 的cmd_PROBE_ACCURACY第 125-169 行探测SAMPLES次默认 10后计算最大值、最小值、range、平均值、中位数与标准差多采样平均由SampleAveragingHelper.run_probe第 374-403 行与calc_probe_z_average第 17-31 行支持average/median两种方式完成samples_tolerance与samples_tolerance_retries负责异常样本的重试判定。位置偏差与温度偏差检查部分探针存在系统性位置偏差例如探针支架沿 Y 轴移动时轻微倾斜导致不同 Y 位置结果偏移这在 Delta 打印机上较常见但所有打印机都可能出现。用PROBE_CALIBRATE在不同 XY 位置测量z_offsetDelta 打印机在 A/B/C 塔附近各测一次笛卡尔/CoreXY 打印机在床面四角附近测量。若最小与最大z_offset之差超过 25 微米0.025mm该探针不适合常规调平流程。温度也会造成系统性偏差探针温度更高时可能一致地在更低高度触发。建议在一致的温度下运行调平工具要么始终在室温下运行要么始终在达到稳定打印温度后运行无论哪种都应在达到目标温度后等待几分钟让机器整体温度一致。检查方法是室温下归零、移到床面中心运行PROBE_ACCURACY记录结果不重新归零、不断开步进电机使能的情况下把喷嘴和床加热到打印温度再运行一次理想情况两次结果一致。补充建议与文档地图使用 Trinamic 步进驱动时可启用 Endstop_Phase.md 的限位相位检测来提高开关触发精度从而提升 Z 限位校准质量。所有校准命令的完整参数MANUAL_PROBE [SPEEDspeed]、TESTZ Zvalue等见 G-Codes.md[bed_screws]、[screws_tilt_adjust]、[probe]的完整配置项speed、probe_speed、horizontal_move_z、probe_height、samples、sample_retract_dist、screw_thread等见 Config_Reference.md。床面网格补偿保存/加载网格、BED_MESH_CALIBRATE见 Bed_Mesh.mdDelta 专用校准见 Delta_Calibrate.md。总体而言Klipper 的调平体系遵循纸张测试建立基准 → 手动/探针工具接力校准 → 探针精度与偏差验证 → 打印测试件微调 Z 偏移的完整链路。无论使用哪种调平机制保持过程可重复、温度一致并善用TESTZ的二分逼近与各工具的ACCEPT/ADJUSTED流程就能稳定地把 Z 距离精度收敛到 25 微米量级为首层质量打下坚实基础。【免费下载链接】klipperKlipper is a 3d-printer firmware项目地址: https://gitcode.com/GitHub_Trending/kl/klipper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考