klipper-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: klipper-manager

技能：klipper-manager

Klipper Manager — Full AI-Driven Printer Configuration & Diagnostics

Klipper Manager — 全AI驱动的打印机配置与诊断

Manages any Klipper printer via Moonraker API: reads and edits printer.cfg, runs diagnostics, executes calibration sequences, monitors live status, and fixes issues with full config-awareness.

通过Moonraker API管理任意Klipper打印机：读取和编辑printer.cfg、运行诊断、执行校准序列、监控实时状态，并结合完整的配置感知能力修复问题。

Activation

触发条件

When the user asks to:

Connect to / manage a Klipper printer
Read, change, or fix any printer.cfg setting
Diagnose a Klipper error or warning
Run calibration (bed mesh, probe, PID, resonances, pressure advance, axis twist, screws, etc.)
Monitor temperatures, positions, or print status
Send GCode commands
Restart firmware or Klipper

Always start by reading
state/printer_context.json
— if it exists, greet the user with a summary of the known printer. If it is missing or the user provides a new IP, run Phase 1.

当用户提出以下需求时激活：

连接/管理Klipper打印机
读取、修改或修复printer.cfg中的任意设置
诊断Klipper错误或警告
执行校准（床网、探针、PID、共振、压力补偿、轴扭转、螺丝调平等）
监控温度、位置或打印状态
发送GCode命令
重启固件或Klipper

始终先读取
state/printer_context.json
—— 如果文件存在，向用户展示已知打印机的摘要信息；如果文件不存在或用户提供了新IP，则执行阶段1。

Phase 1: Printer Discovery

阶段1：打印机发现

Step 1 — Connect to Moonraker

步骤1 — 连接Moonraker

Ask for the printer IP if not already known. Then verify connectivity:

bash

curl -s "http://<IP>:7125/printer/info"

Expected response contains:

state

hostname

software_version

config_file

state

is not

"ready"

, report it and ask the user to resolve before continuing.

若未知打印机IP，先向用户询问。然后验证连通性：

bash

curl -s "http://<IP>:7125/printer/info"

预期响应应包含：

state

、

hostname

、

software_version

、

config_file

。

如果

state

不是

"ready"

，则向用户报告该状态，并请用户解决后再继续。

Step 2 — Fetch printer.cfg

步骤2 — 获取printer.cfg

bash

curl -s "http://<IP>:7125/server/files/config/printer.cfg"

Also fetch any included files referenced with

[include ...]

bash

curl -s "http://<IP>:7125/server/files/config/<included_file>"

Common includes to auto-fetch:

mainsail.cfg

macros/*.cfg

KAMP/*.cfg

bash

curl -s "http://<IP>:7125/server/files/config/printer.cfg"

同时获取所有通过

[include ...]

引用的关联文件：

bash

curl -s "http://<IP>:7125/server/files/config/<included_file>"

自动获取的常见关联文件：

mainsail.cfg

、

macros/*.cfg

、

KAMP/*.cfg

。

Step 3 — Parse and Inventory Config

步骤3 — 解析并整理配置

Parse ALL sections from the fetched config. Extract and store in

state/printer_context.json

json

{
  "version": 1,
  "updated": "ISO-8601",
  "moonraker_url": "http://<IP>:7125",
  "klipper_version": "v0.13.x",
  "hostname": "mainsailos",
  "config_file": "/home/pi/printer_data/config/printer.cfg",

  "kinematics": "cartesian | corexy | corexz | delta | ...",
  "build_volume": {"x": 235, "y": 235, "z": 250},

  "steppers": {
    "stepper_x": {"position_max": 246, "position_min": 0, "rotation_distance": 40, "microsteps": 16},
    "stepper_y": {"position_max": 235, "position_min": 0},
    "stepper_z": {"position_max": 250, "position_min": -2}
  },

  "probe": {
    "type": "bltouch | probe | smart_effector | probe_eddy_current | none",
    "x_offset": -62,
    "y_offset": -12,
    "z_offset": 3.439
  },

  "bed_mesh": {
    "mesh_min": [60, 30],
    "mesh_max": [170, 220],
    "probe_count": [5, 5]
  },

  "axis_twist_compensation": {
    "calibrate_start_x": 20,
    "calibrate_end_x": 183,
    "calibrate_y": 117.5
  },

  "safe_z_home": {
    "home_xy_position": [108.5, 117.5]
  },

  "extruder": {
    "nozzle_diameter": 0.4,
    "rotation_distance": 7.687,
    "pressure_advance": null
  },

  "tmc_drivers": {
    "stepper_x": {"driver": "tmc2209", "run_current": 0.750, "stealthchop_threshold": 999999},
    "stepper_y": {"driver": "tmc2209", "run_current": 0.750, "stealthchop_threshold": 999999},
    "stepper_z": {"driver": "tmc2209", "run_current": 0.580, "stealthchop_threshold": 0},
    "extruder": {"driver": "tmc2209", "run_current": 0.580, "stealthchop_threshold": 0}
  },

  "input_shaper": {
    "x": {"type": "3hump_ei", "freq": 66.2},
    "y": {"type": "ei", "freq": 45.0}
  },

  "printer_limits": {
    "max_velocity": 300,
    "max_accel": 7000,
    "max_z_velocity": 15,
    "max_z_accel": 100
  },

  "installed_sections": [],
  "save_config_block": {},

  "known_issues": [],
  "last_diagnostic": null
}

解析所有获取到的配置内容，并将提取的信息存储到

state/printer_context.json

中：

json

{
  "version": 1,
  "updated": "ISO-8601",
  "moonraker_url": "http://<IP>:7125",
  "klipper_version": "v0.13.x",
  "hostname": "mainsailos",
  "config_file": "/home/pi/printer_data/config/printer.cfg",

  "kinematics": "cartesian | corexy | corexz | delta | ...",
  "build_volume": {"x": 235, "y": 235, "z": 250},

  "steppers": {
    "stepper_x": {"position_max": 246, "position_min": 0, "rotation_distance": 40, "microsteps": 16},
    "stepper_y": {"position_max": 235, "position_min": 0},
    "stepper_z": {"position_max": 250, "position_min": -2}
  },

  "probe": {
    "type": "bltouch | probe | smart_effector | probe_eddy_current | none",
    "x_offset": -62,
    "y_offset": -12,
    "z_offset": 3.439
  },

  "bed_mesh": {
    "mesh_min": [60, 30],
    "mesh_max": [170, 220],
    "probe_count": [5, 5]
  },

  "axis_twist_compensation": {
    "calibrate_start_x": 20,
    "calibrate_end_x": 183,
    "calibrate_y": 117.5
  },

  "safe_z_home": {
    "home_xy_position": [108.5, 117.5]
  },

  "extruder": {
    "nozzle_diameter": 0.4,
    "rotation_distance": 7.687,
    "pressure_advance": null
  },

  "tmc_drivers": {
    "stepper_x": {"driver": "tmc2209", "run_current": 0.750, "stealthchop_threshold": 999999},
    "stepper_y": {"driver": "tmc2209", "run_current": 0.750, "stealthchop_threshold": 999999},
    "stepper_z": {"driver": "tmc2209", "run_current": 0.580, "stealthchop_threshold": 0},
    "extruder": {"driver": "tmc2209", "run_current": 0.580, "stealthchop_threshold": 0}
  },

  "input_shaper": {
    "x": {"type": "3hump_ei", "freq": 66.2},
    "y": {"type": "ei", "freq": 45.0}
  },

  "printer_limits": {
    "max_velocity": 300,
    "max_accel": 7000,
    "max_z_velocity": 15,
    "max_z_accel": 100
  },

  "installed_sections": [],
  "save_config_block": {},

  "known_issues": [],
  "last_diagnostic": null
}

Step 4 — Run Auto-Diagnostic

步骤4 — 运行自动诊断

After parsing, always run the full diagnostic (see Phase 3) and report any issues found.

解析完成后，始终运行完整诊断（见阶段3）并报告发现的所有问题。

Step 5 — Present Summary

步骤5 — 展示摘要

Show the user a table:

Printer    : mainsailos (Klipper v0.13.x)
Kinematics : Cartesian  |  Build: 246 × 235 × 250 mm
Probe      : BLTouch    |  x_offset: -62  y_offset: -12  z_offset: 3.439
Sections   : [printer] [extruder] [heater_bed] [bltouch] [bed_mesh] [axis_twist_compensation]
             [input_shaper] [firmware_retraction] [safe_z_home] [screws_tilt_adjust] ...
Issues     : (list any found by diagnostic, or "None detected")

向用户展示如下表格：

打印机    : mainsailos (Klipper v0.13.x)
运动学类型 : Cartesian  |  打印体积: 246 × 235 × 250 mm
探针      : BLTouch    |  x偏移: -62  y偏移: -12  z偏移: 3.439
配置段   : [printer] [extruder] [heater_bed] [bltouch] [bed_mesh] [axis_twist_compensation]
             [input_shaper] [firmware_retraction] [safe_z_home] [screws_tilt_adjust] ...
问题     : (列出诊断发现的问题，或显示"未检测到问题")

Phase 2: Configuration Management

阶段2：配置管理

Reading a Setting

读取设置

To read any setting, look up the parsed

printer_context.json

or re-fetch the file:

bash

curl -s "http://<IP>:7125/server/files/config/printer.cfg"

要读取任意设置，可查询已解析的

printer_context.json

或重新获取文件：

bash

curl -s "http://<IP>:7125/server/files/config/printer.cfg"

Editing a Setting

修改设置

Workflow for every config change:

Fetch the CURRENT file (never edit a stale copy)
Make the targeted change
Validate the change (see Phase 3 validation rules)

Save to a temp file

C:/Users/<user>/Documents/printer_fix.cfg

Upload via Moonraker:

bash

curl -s -X POST "http://<IP>:7125/server/files/upload" \
  -F "root=config" \
  -F "file=@C:/Users/<user>/Documents/printer_fix.cfg;filename=printer.cfg"

Firmware restart to apply:

bash

curl -s -X POST "http://<IP>:7125/printer/firmware_restart"

Wait 5 seconds, verify

state: ready

bash

curl -s "http://<IP>:7125/printer/info"

Update
```
state/printer_context.json
```
Clean up temp file

CRITICAL: Never edit the SAVE_CONFIG block by hand. Only Klipper's

SAVE_CONFIG

command should modify that block. When uploading a modified config, preserve the entire

#*# <--- SAVE_CONFIG --->

block exactly as-is unless explicitly removing stale calibration data.

所有配置修改的工作流程：

获取当前最新的文件（绝不要修改过期副本）
执行目标修改
验证修改内容（见阶段3的验证规则）

保存到临时文件

C:/Users/<user>/Documents/printer_fix.cfg

通过Moonraker上传：

bash

curl -s -X POST "http://<IP>:7125/server/files/upload" \
  -F "root=config" \
  -F "file=@C:/Users/<user>/Documents/printer_fix.cfg;filename=printer.cfg"

重启固件以应用修改：

bash

curl -s -X POST "http://<IP>:7125/printer/firmware_restart"

等待5秒，验证

state: ready

：

bash

curl -s "http://<IP>:7125/printer/info"

更新
```
state/printer_context.json
```
清理临时文件

重要提示：绝不要手动修改SAVE_CONFIG块。 只有Klipper的

SAVE_CONFIG

命令才能修改该块。上传修改后的配置时，需完全保留整个

#*# <--- SAVE_CONFIG --->

块，除非明确需要移除过期的校准数据。

Multiple Config Files

多配置文件

If the printer uses

[include]

sections, list all config files:

bash

curl -s "http://<IP>:7125/server/files/list?root=config"

Fetch and edit the correct file — do not modify

printer.cfg

when the target section lives in an included file.

如果打印机使用了

[include]

段，列出所有配置文件：

bash

curl -s "http://<IP>:7125/server/files/list?root=config"

获取并编辑正确的文件 —— 当目标配置段存在于关联文件中时，不要修改

printer.cfg

。

Phase 3: Diagnostics & Validation

阶段3：诊断与验证

Auto-Diagnostic Checklist

自动诊断检查清单

Run this every time a config is loaded or after any change. Check ALL rules:

每次加载配置或修改配置后，都要运行此检查清单，验证所有规则：

1. Probe Offset Bounds

1. 探针偏移范围

For every calibration section that uses probe coordinates, the nozzle must stay within

[position_min, position_max]

accounting for probe offsets.

Section	Coord params	Nozzle position formula
`[axis_twist_compensation]`	`calibrate_start_x` , `calibrate_end_x` , `calibrate_y`	`nozzle_x = coord_x - probe.x_offset` ; `nozzle_y = coord_y - probe.y_offset`
`[bed_mesh]`	`mesh_min` , `mesh_max`	`nozzle_x = mesh_x - probe.x_offset` ; `nozzle_y = mesh_y - probe.y_offset`
`[screws_tilt_adjust]`	`screw1..N` (x,y)	`nozzle_x = screw_x - probe.x_offset` ; `nozzle_y = screw_y - probe.y_offset`
`[safe_z_home]`	`home_xy_position`	These are NOZZLE coords directly (no offset subtraction needed)
`[delta_calibrate]`	`radius`	probe must land within radius from center accounting for offset

Validate for each axis:

nozzle_x >= stepper_x.position_min  AND  nozzle_x <= stepper_x.position_max
nozzle_y >= stepper_y.position_min  AND  nozzle_y <= stepper_y.position_max

Fix formula:

max_coord_x = stepper_x.position_max + probe.x_offset   (when x_offset is negative)
min_coord_x = stepper_x.position_min - probe.x_offset   (when x_offset is positive)

对于所有使用探针坐标的校准段，喷嘴必须在

[position_min, position_max]

范围内（需考虑探针偏移）。

配置段	坐标参数	喷嘴位置计算公式
`[axis_twist_compensation]`	`calibrate_start_x` , `calibrate_end_x` , `calibrate_y`	`nozzle_x = coord_x - probe.x_offset` ; `nozzle_y = coord_y - probe.y_offset`
`[bed_mesh]`	`mesh_min` , `mesh_max`	`nozzle_x = mesh_x - probe.x_offset` ; `nozzle_y = mesh_y - probe.y_offset`
`[screws_tilt_adjust]`	`screw1..N` (x,y)	`nozzle_x = screw_x - probe.x_offset` ; `nozzle_y = screw_y - probe.y_offset`
`[safe_z_home]`	`home_xy_position`	这些直接是喷嘴坐标（无需减去偏移）
`[delta_calibrate]`	`radius`	探针必须在考虑偏移后，落在中心半径范围内

对每个轴进行验证：

nozzle_x >= stepper_x.position_min  AND  nozzle_x <= stepper_x.position_max
nozzle_y >= stepper_y.position_min  AND  nozzle_y <= stepper_y.position_max

修复公式：

max_coord_x = stepper_x.position_max + probe.x_offset   (当x_offset为负数时)
min_coord_x = stepper_x.position_min - probe.x_offset   (当x_offset为正数时)

2. Bed Mesh Bounds

2. 床网范围

mesh_min

and

mesh_max

must be within the reachable probe area:

mesh_min.x >= stepper_x.position_min - probe.x_offset
mesh_max.x <= stepper_x.position_max + probe.x_offset  (when x_offset < 0)
mesh_min.y >= stepper_y.position_min - probe.y_offset
mesh_max.y <= stepper_y.position_max + probe.y_offset  (when y_offset < 0)

mesh_min

和

mesh_max

必须在探针可触及的范围内：

mesh_min.x >= stepper_x.position_min - probe.x_offset
mesh_max.x <= stepper_x.position_max + probe.x_offset  (当x_offset < 0时)
mesh_min.y >= stepper_y.position_min - probe.y_offset
mesh_max.y <= stepper_y.position_max + probe.y_offset  (当y_offset < 0时)

3. Safe Z Home Position

3. 安全Z归位位置

home_xy_position

must be reachable for the NOZZLE:

home_xy.x >= stepper_x.position_min AND home_xy.x <= stepper_x.position_max
home_xy.y >= stepper_y.position_min AND home_xy.y <= stepper_y.position_max

Also validate that at the home position, the PROBE is over the bed (not hanging off the edge).

home_xy_position

必须是喷嘴可触及的位置：

home_xy.x >= stepper_x.position_min AND home_xy.x <= stepper_x.position_max
home_xy.y >= stepper_y.position_min AND home_xy.y <= stepper_y.position_max

同时验证在归位位置时，探针位于打印床上（未超出床边缘）。

4. SAVE_CONFIG / Calibration Consistency

4. SAVE_CONFIG / 校准一致性

After a config change, check if saved calibration data in

#*# SAVE_CONFIG

is still valid:

axis_twist_compensation

bounds changed → old

z_compensations

compensation_start_x

compensation_end_x

may be stale → warn user to re-run

AXIS_TWIST_COMPENSATION_CALIBRATE

If
```
bltouch.z_offset
```
or
```
probe.z_offset
```
was manually changed → warn that
```
PROBE_CALIBRATE
```
should be re-run
If
```
bed_mesh
```
bounds changed → existing mesh profiles may be out of bounds → warn to re-run
```
BED_MESH_CALIBRATE
```

修改配置后，检查

#*# SAVE_CONFIG

中保存的校准数据是否仍有效：

如果

axis_twist_compensation

范围已更改 → 旧的

z_compensations

compensation_start_x

compensation_end_x

可能已过期 → 提醒用户重新运行

AXIS_TWIST_COMPENSATION_CALIBRATE

如果手动修改了
```
bltouch.z_offset
```
或
```
probe.z_offset
```
→ 提醒用户应重新运行
```
PROBE_CALIBRATE
```
如果
```
bed_mesh
```
范围已更改 → 现有网格配置文件可能超出范围 → 提醒用户重新运行
```
BED_MESH_CALIBRATE
```

5. TMC Driver Warnings

5. TMC驱动器警告

```
stealthchop_threshold: 999999
```
on extruder with pressure advance → warn (reduced torque, but often acceptable)
```
hold_current
```
configured → warn (can cause vibration, Klipper docs recommend omitting)
```
run_current
```
> rated motor current × 0.85 → warn (thermal risk)
```
interpolate: True
```
with high-precision requirements → note positional deviation (~0.006mm at 16 microsteps)

启用pressure advance的挤出机设置了
```
stealthchop_threshold: 999999
```
→ 发出警告（扭矩降低，但通常可接受）
配置了
```
hold_current
```
→ 发出警告（可能导致振动，Klipper文档建议省略该设置）
```
run_current
```
> 电机额定电流 × 0.85 → 发出警告（存在过热风险）
高精度需求下设置了
```
interpolate: True
```
→ 提示位置偏差（16微步时约0.006mm）

6. Input Shaper

6. 输入整形器

```
shaper_type: 3hump_ei
```
or
```
2hump_ei
```
→ complex resonance signature → recommend belt tension check
No
```
[input_shaper]
```
section → recommend running
```
SHAPER_CALIBRATE
```
Shaper frequency < 20Hz → likely miscalibrated or very heavy toolhead

```
shaper_type: 3hump_ei
```
或
```
2hump_ei
```
→ 复杂共振特征 → 建议检查皮带张力
无
```
[input_shaper]
```
段 → 建议运行
```
SHAPER_CALIBRATE
```
整形器频率 < 20Hz → 可能校准错误或打印头过重

7. Pressure Advance

7. 压力补偿

```
pressure_advance
```
not set (0 or absent) in
```
[extruder]
```
→ recommend calibration
```
pressure_advance > 1.0
```
→ unusually high, check rotation_distance and extruder type

```
[extruder]
```
中未设置
```
pressure_advance
```
（为0或不存在） → 建议校准
```
pressure_advance > 1.0
```
→ 数值异常高，检查rotation_distance和挤出机类型

8. Rotation Distance Sanity

8. 旋转距离合理性

For extruder:

Direct drive:
```
rotation_distance
```
should be 4–10 (typical 7–8 for BMG-style)
Bowden:
```
rotation_distance
```
should be 20–40

For motion axes:

GT2 belt, 20-tooth pulley:
```
rotation_distance = 40
```
GT2 belt, 16-tooth pulley:
```
rotation_distance = 32
```
T8 leadscrew (2mm pitch, 4 starts):
```
rotation_distance = 8
```
T8 leadscrew (2mm pitch, 1 start):
```
rotation_distance = 2
```

对于挤出机：

直接驱动：
```
rotation_distance
```
应为4–10（BMG风格通常为7–8）
远程驱动（Bowden）：
```
rotation_distance
```
应为20–40

对于运动轴：

GT2皮带、20齿滑轮：
```
rotation_distance = 40
```
GT2皮带、16齿滑轮：
```
rotation_distance = 32
```
T8丝杠（2mm导程，4头）：
```
rotation_distance = 8
```
T8丝杠（2mm导程，1头）：
```
rotation_distance = 2
```

9. PID Tuning

9. PID调优

```
control: watermark
```
→ old method, recommend PID calibration
```
pid_Kp
```
,
```
pid_Ki
```
,
```
pid_Kd
```
absent → heater has no PID, may be unstable

```
control: watermark
```
→ 旧方法，建议进行PID校准
缺少
```
pid_Kp
```
,
```
pid_Ki
```
,
```
pid_Kd
```
→ 加热器无PID控制，可能不稳定

10. Missing Recommended Sections

10. 缺失推荐配置段

Flag as warnings (not errors):

No
```
[exclude_object]
```
→ object cancellation unavailable
No
```
[firmware_retraction]
```
→ runtime retraction tuning unavailable
No
```
[gcode_arcs]
```
→ arc support unavailable
No
```
[respond]
```
→ macro feedback may be silent
No
```
[pause_resume]
```
→ pause/cancel prints may not work

标记为警告（非错误）：

无
```
[exclude_object]
```
→ 无法取消单个对象打印
无
```
[firmware_retraction]
```
→ 无法在运行时调整回抽参数
无
```
[gcode_arcs]
```
→ 不支持圆弧指令
无
```
[respond]
```
→ 宏指令反馈可能无输出
无
```
[pause_resume]
```
→ 暂停/取消打印可能无法正常工作

Phase 4: Live Status Monitoring

阶段4：实时状态监控

Query Printer Objects

查询打印机对象

Klipper exposes live state via Moonraker's objects API:

bash

undefined

Klipper通过Moonraker的对象API暴露实时状态：

bash

undefined

Query everything

查询所有对象

curl -s "http://<IP>:7125/printer/objects/query?toolhead&extruder&heater_bed&bed_mesh&probe&print_stats"

Query specific fields

查询特定字段

curl -s "http://<IP>:7125/printer/objects/query?toolhead=position,max_velocity,max_accel&extruder=temperature,target,pressure_advance"


Key objects and fields:

| Object | Key fields |
|--------|-----------|
| `toolhead` | `position`, `homed_axes`, `max_velocity`, `max_accel`, `stalls` |
| `extruder` | `temperature`, `target`, `pressure_advance`, `can_extrude` |
| `heater_bed` | `temperature`, `target`, `power` |
| `probe` or `bltouch` | `last_query`, `last_probe_position` |
| `bed_mesh` | `profile_name`, `mesh_min`, `mesh_max`, `probed_matrix` |
| `print_stats` | `state`, `filename`, `total_duration`, `filament_used` |
| `idle_timeout` | `state`, `printing_time` |
| `motion_report` | `live_position`, `live_velocity` |
| `firmware_retraction` | `retract_length`, `retract_speed` |
| `input_shaper` | (queried from configfile) |
| `tmc2209 stepper_x` | `run_current`, `hold_current`, `drv_status`, `temperature` |
| `configfile` | `save_config_pending`, `settings.<section>.<key>` |
| `webhooks` | `state`, `state_message` |
| `system_stats` | `sysload`, `cputime`, `memavail` |

curl -s "http://<IP>:7125/printer/objects/query?toolhead=position,max_velocity,max_accel&extruder=temperature,target,pressure_advance"


关键对象及字段：

| 对象 | 关键字段 |
|--------|-----------|
| `toolhead` | `position`, `homed_axes`, `max_velocity`, `max_accel`, `stalls` |
| `extruder` | `temperature`, `target`, `pressure_advance`, `can_extrude` |
| `heater_bed` | `temperature`, `target`, `power` |
| `probe`或`bltouch` | `last_query`, `last_probe_position` |
| `bed_mesh` | `profile_name`, `mesh_min`, `mesh_max`, `probed_matrix` |
| `print_stats` | `state`, `filename`, `total_duration`, `filament_used` |
| `idle_timeout` | `state`, `printing_time` |
| `motion_report` | `live_position`, `live_velocity` |
| `firmware_retraction` | `retract_length`, `retract_speed` |
| `input_shaper` | (从configfile查询) |
| `tmc2209 stepper_x` | `run_current`, `hold_current`, `drv_status`, `temperature` |
| `configfile` | `save_config_pending`, `settings.<section>.<key>` |
| `webhooks` | `state`, `state_message` |
| `system_stats` | `sysload`, `cputime`, `memavail` |

Send GCode

发送GCode

bash

curl -s -X POST "http://<IP>:7125/printer/gcode/script" \
  -H "Content-Type: application/json" \
  -d '{"script": "QUERY_ENDSTOPS"}'

bash

curl -s -X POST "http://<IP>:7125/printer/gcode/script" \
  -H "Content-Type: application/json" \
  -d '{"script": "QUERY_ENDSTOPS"}'

Query Endstops

查询限位开关

bash

curl -s "http://<IP>:7125/printer/query_endstops/status"

bash

curl -s "http://<IP>:7125/printer/query_endstops/status"

Phase 5: Calibration Sequences

阶段5：校准序列

Probe Z-Offset (PROBE_CALIBRATE)

探针Z偏移校准（PROBE_CALIBRATE）

Verify printer is homed: send
```
G28
```
Start calibration:
```
PROBE_CALIBRATE
```
Guide user through paper test at nozzle
Accept:
```
TESTZ Z=-0.1
```
(adjust in steps)
Finalize:
```
ACCEPT
```
Save:
```
SAVE_CONFIG
```
(triggers firmware restart automatically)

验证打印机已归位：发送
```
G28
```
开始校准：
```
PROBE_CALIBRATE
```
引导用户在喷嘴处进行纸片测试
调整：
```
TESTZ Z=-0.1
```
（逐步调整）
确认：
```
ACCEPT
```
保存：
```
SAVE_CONFIG
```
（会自动触发固件重启）

Bed Mesh Calibration

床网校准

Home all axes:
```
G28
```
Optional: heat bed to print temp first
Run:
```
BED_MESH_CALIBRATE
```
Save profile:
```
BED_MESH_PROFILE SAVE=default
```
Save to config:
```
SAVE_CONFIG
```

所有轴归位：
```
G28
```
可选：先将床加热到打印温度
运行：
```
BED_MESH_CALIBRATE
```
保存配置文件：
```
BED_MESH_PROFILE SAVE=default
```
保存到配置：
```
SAVE_CONFIG
```

Axis Twist Compensation

轴扭转补偿

Before running, always validate calibrate_end_x:

max_safe_end_x = stepper_x.position_max + probe.x_offset

calibrate_end_x > max_safe_end_x

→ fix it first (see Phase 2 edit workflow)

Then:

Home:
```
G28
```
Run:
```
AXIS_TWIST_COMPENSATION_CALIBRATE
```
Follow prompts for paper test at each probe point
Save:
```
SAVE_CONFIG
```

运行前，务必验证calibrate_end_x：

max_safe_end_x = stepper_x.position_max + probe.x_offset

如果

calibrate_end_x > max_safe_end_x

→ 先修复该值（见阶段2的修改流程）

然后：

归位：
```
G28
```
运行：
```
AXIS_TWIST_COMPENSATION_CALIBRATE
```
按照提示在每个探针点进行纸片测试
保存：
```
SAVE_CONFIG
```

PID Tuning

PID调优

Hotend:

gcode

PID_CALIBRATE HEATER=extruder TARGET=200
SAVE_CONFIG

Bed:

gcode

PID_CALIBRATE HEATER=heater_bed TARGET=60
SAVE_CONFIG

热端：

gcode

PID_CALIBRATE HEATER=extruder TARGET=200
SAVE_CONFIG

热床：

gcode

PID_CALIBRATE HEATER=heater_bed TARGET=60
SAVE_CONFIG

Pressure Advance

压力补偿

Method 1 — Tuning tower (manual):

gcode

SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500
TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005

Print a tuning tower model. Measure optimal layer. Calculate:

PA = START + FACTOR × best_layer_height_mm

Method 2 — Set directly after finding value:

gcode

SET_PRESSURE_ADVANCE ADVANCE=0.04

Then add to

[extruder]

in config and

SAVE_CONFIG

方法1 — 调优塔（手动）：

gcode

SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500
TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005

打印调优塔模型，测量最优层。计算：

PA = START + FACTOR × best_layer_height_mm

方法2 — 找到值后直接设置：

gcode

SET_PRESSURE_ADVANCE ADVANCE=0.04

然后将该值添加到

[extruder]

配置段并执行

SAVE_CONFIG

。

Resonance / Input Shaper Calibration

共振/输入整形器校准

Verify
```
[adxl345]
```
or other accelerometer configured
Home:
```
G28
```
Test accelerometer:
```
ACCELEROMETER_QUERY
```
Measure noise baseline:
```
MEASURE_AXES_NOISE
```
Calibrate X:
```
SHAPER_CALIBRATE AXIS=X
```
Calibrate Y:
```
SHAPER_CALIBRATE AXIS=Y
```
Review results and apply recommended shaper
```
SAVE_CONFIG
```

验证已配置
```
[adxl345]
```
或其他加速度计
归位：
```
G28
```
测试加速度计：
```
ACCELEROMETER_QUERY
```
测量噪声基线：
```
MEASURE_AXES_NOISE
```
校准X轴：
```
SHAPER_CALIBRATE AXIS=X
```
校准Y轴：
```
SHAPER_CALIBRATE AXIS=Y
```
查看结果并应用推荐的整形器
```
SAVE_CONFIG
```

Screws Tilt Adjust

螺丝调平

Home:
```
G28
```
Run:
```
SCREWS_TILT_CALCULATE
```
Read output — each screw shows turn direction (CW/CCW) and amount (HH:MM)
Re-run until all screws show < 0:05 deviation

归位：
```
G28
```
运行：
```
SCREWS_TILT_CALCULATE
```
读取输出 —— 每个螺丝显示转动方向（顺时针/逆时针）和转动量（HH:MM）
重新运行直到所有螺丝的偏差小于0:05

TMC Driver Diagnostics

TMC驱动器诊断

Dump driver state:

gcode

DUMP_TMC STEPPER=stepper_x
DUMP_TMC STEPPER=stepper_y
DUMP_TMC STEPPER=stepper_z
DUMP_TMC STEPPER=extruder

Adjust current at runtime (test only — add to config to persist):

gcode

SET_TMC_CURRENT STEPPER=stepper_x CURRENT=0.8 HOLDCURRENT=0.5

导出驱动器状态：

gcode

DUMP_TMC STEPPER=stepper_x
DUMP_TMC STEPPER=stepper_y
DUMP_TMC STEPPER=stepper_z
DUMP_TMC STEPPER=extruder

运行时调整电流（仅测试 —— 需添加到配置中才能持久生效）：

gcode

SET_TMC_CURRENT STEPPER=stepper_x CURRENT=0.8 HOLDCURRENT=0.5

Phase 6: Troubleshooting

阶段6：故障排除

Use

references/troubleshooting.md

for the full error → cause → fix database.

Workflow for any error message the user pastes:

Extract the error pattern (error type + coordinates/values if present)
Match against known patterns in the troubleshooting reference
Pull the relevant config sections from
```
printer_context.json
```
Compute the specific fix values using the validation formulas
Present the diagnosis with the exact lines to change
Offer to apply the fix automatically (Phase 2 edit workflow)

Common error patterns (quick reference):

Error	Cause	Fix
`Move out of range: X Y Z [step]`	Nozzle would exceed axis limit; often probe offset not accounted in calibration coords	Reduce `calibrate_end_x` / `mesh_max` by `abs(probe.x_offset)`
`Must home axis first`	Axes not homed before move command	Run `G28`
`Endstop stepper_x still triggered`	Endstop stuck or wiring fault	Check `QUERY_ENDSTOPS` , check endstop pin polarity
`Unable to read tmc uart ... IFCNT`	TMC UART comms failure	Check motor power and UART wiring; power cycle
`TMC reports error: ... OvertempError`	TMC driver too hot	Reduce `run_current` , improve cooling
`TMC reports error: ShortToGND`	Shorted motor wire	Check motor wiring
`TMC reports error: Undervoltage`	PSU voltage dip	Check PSU and wiring connections
`Heater extruder not heating at expected rate`	PID tuning needed or heater/sensor issue	Run `PID_CALIBRATE HEATER=extruder TARGET=200`
`Probe triggered prior to movement`	BLTouch in wrong state or z_offset too high	Run `BLTOUCH_DEBUG COMMAND=reset` then re-home
`Timeout on connect`	Moonraker not running or wrong IP	Verify printer IP and that Moonraker is running
`Lost communication with MCU`	USB disconnect or firmware crash	Run `FIRMWARE_RESTART` ; check USB cable

使用

references/troubleshooting.md

获取完整的错误→原因→修复数据库。

处理用户粘贴的任意错误信息的工作流程：

提取错误模式（错误类型 + 坐标/数值（如果有））
与故障排除参考中的已知模式匹配
从
```
printer_context.json
```
中提取相关配置段
使用验证公式计算具体的修复值
展示诊断结果及需修改的具体行
提供自动应用修复的选项（阶段2的修改流程）

常见错误模式（快速参考）：

错误	原因	修复
`Move out of range: X Y Z [step]`	喷嘴将超出轴限制；通常是校准坐标未考虑探针偏移	将 `calibrate_end_x` / `mesh_max` 减少 `abs(probe.x_offset)`
`Must home axis first`	执行移动命令前未归位轴	运行 `G28`
`Endstop stepper_x still triggered`	限位开关卡住或接线故障	检查 `QUERY_ENDSTOPS` ，检查限位开关引脚极性
`Unable to read tmc uart ... IFCNT`	TMC UART通信失败	检查电机电源和UART接线；重启电源
`TMC reports error: ... OvertempError`	TMC驱动器过热	降低 `run_current` ，改善散热
`TMC reports error: ShortToGND`	电机接线短路	检查电机接线
`TMC reports error: Undervoltage`	电源电压下降	检查电源和接线连接
`Heater extruder not heating at expected rate`	需要PID调优或加热器/传感器故障	运行 `PID_CALIBRATE HEATER=extruder TARGET=200`
`Probe triggered prior to movement`	BLTouch状态错误或z_offset过高	运行 `BLTOUCH_DEBUG COMMAND=reset` 然后重新归位
`Timeout on connect`	Moonraker未运行或IP错误	验证打印机IP及Moonraker是否运行
`Lost communication with MCU`	USB断开或固件崩溃	运行 `FIRMWARE_RESTART` ；检查USB线缆

Phase 7: Config Section Reference

阶段7：配置段参考

Use

references/config_sections.md

for the complete parameter reference.

Key sections and their most commonly tuned parameters:

使用

references/config_sections.md

获取完整的参数参考。

关键配置段及其最常调整的参数：

[printer]

ini

kinematics: cartesian          # cartesian|corexy|corexz|delta|deltesian|polar
max_velocity: 300              # mm/s — runtime tunable via SET_VELOCITY_LIMIT
max_accel: 7000                # mm/s² — runtime tunable
max_z_velocity: 15             # mm/s (cartesian only)
max_z_accel: 100               # mm/s² (cartesian only)
minimum_cruise_ratio: 0.5      # 0.0–1.0, reduces top speed of short moves
square_corner_velocity: 5.0    # mm/s, higher = less deceleration at corners

ini

kinematics: cartesian          # cartesian|corexy|corexz|delta|deltesian|polar
max_velocity: 300              # 毫米/秒 — 可通过SET_VELOCITY_LIMIT在运行时调整
max_accel: 7000                # 毫米/秒² — 可在运行时调整
max_z_velocity: 15             # 毫米/秒（仅笛卡尔式）
max_z_accel: 100               # 毫米/秒²（仅笛卡尔式）
minimum_cruise_ratio: 0.5      # 0.0–1.0，降低短距离移动的最高速度
square_corner_velocity: 5.0    # 毫米/秒，值越高，拐角处减速越少

[stepper_x/y/z]

ini

rotation_distance: 40          # mm per full motor rotation
microsteps: 16                 # 8|16|32|64|128
position_min: 0                # soft limit minimum
position_max: 246              # soft limit maximum — CRITICAL for range checks
position_endstop: 0            # endstop position (must match position_min or position_max)
homing_speed: 80               # mm/s

ini

rotation_distance: 40          # 电机每转一圈的毫米数
microsteps: 16                 # 8|16|32|64|128
position_min: 0                # 软限位最小值
position_max: 246              # 软限位最大值 —— 范围检查的关键参数
position_endstop: 0            # 限位开关位置（必须与position_min或position_max匹配）
homing_speed: 80               # 毫米/秒

[extruder]

ini

rotation_distance: 7.687       # mm per motor rotation (direct drive ~7-8, bowden ~20-40)
nozzle_diameter: 0.400
pressure_advance: 0.04         # 0 = disabled; typical range 0.02–0.12 for direct
pressure_advance_smooth_time: 0.04
max_extrude_cross_section: 5   # max mm² cross section (4 × nozzle_diameter² is safe default)

ini

rotation_distance: 7.687       # 电机每转一圈的毫米数（直接驱动约7-8，远程驱动约20-40）
nozzle_diameter: 0.400
pressure_advance: 0.04         # 0=禁用；直接驱动典型范围0.02–0.12
pressure_advance_smooth_time: 0.04
max_extrude_cross_section: 5   # 最大挤出横截面积（4 × nozzle_diameter²是安全默认值）

[bltouch] / [probe]

ini

x_offset: -62                  # probe X position relative to nozzle (negative = left of nozzle)
y_offset: -12                  # probe Y position relative to nozzle (negative = in front)

ini

x_offset: -62                  # 探针相对于喷嘴的X位置（负数=在喷嘴左侧）
y_offset: -12                  # 探针相对于喷嘴的Y位置（负数=在喷嘴前方）

z_offset: stored in SAVE_CONFIG block

z_offset: 存储在SAVE_CONFIG块中

samples: 3 # number of probe samples samples_result: median # average|median sample_retract_dist: 5.0 samples_tolerance: 0.01 # max deviation between samples (mm) samples_tolerance_retries: 3

undefined

samples: 3 # 探针采样次数 samples_result: median # average|median sample_retract_dist: 5.0 samples_tolerance: 0.01 # 采样间的最大偏差（毫米） samples_tolerance_retries: 3

undefined

[bed_mesh]

ini

mesh_min: 60, 30               # PROBE coordinates (not nozzle!)
mesh_max: 170, 220             # PROBE coordinates
probe_count: 5, 5              # grid points per axis
algorithm: bicubic             # lagrange (≤3×3) | bicubic (≥4×4 recommended)
fade_start: 1                  # mm height to start fading mesh correction
fade_end: 10                   # mm height where mesh correction reaches zero (0=disabled)

ini

mesh_min: 60, 30               # 探针坐标（不是喷嘴！）
mesh_max: 170, 220             # 探针坐标
probe_count: 5, 5              # 每个轴的网格点数
algorithm: bicubic             # lagrange（≤3×3）| bicubic（推荐≥4×4）
fade_start: 1                  # 开始衰减网格补偿的高度（毫米）
fade_end: 10                   # 网格补偿完全消失的高度（毫米，0=禁用）

[axis_twist_compensation]

ini

calibrate_start_x: 20         # PROBE X coordinate — nozzle = start_x - x_offset
calibrate_end_x: 183          # PROBE X coordinate — nozzle = end_x - x_offset
calibrate_y: 117.5            # PROBE Y coordinate — nozzle = calibrate_y - y_offset

ini

calibrate_start_x: 20         # 探针X坐标 —— 喷嘴位置 = start_x - x_offset
calibrate_end_x: 183          # 探针X坐标 —— 喷嘴位置 = end_x - x_offset
calibrate_y: 117.5            # 探针Y坐标 —— 喷嘴位置 = calibrate_y - y_offset

Rule: nozzle must be within [position_min, position_max]

规则：喷嘴必须在[position_min, position_max]范围内

Formula: calibrate_end_x <= position_max + x_offset (when x_offset < 0)

公式：calibrate_end_x <= position_max + x_offset (当x_offset < 0时)

undefined

undefined

[safe_z_home]

ini

home_xy_position: 108.5, 117.5  # NOZZLE position for Z homing (not probe!)
speed: 120
z_hop: 10
z_hop_speed: 5

ini

home_xy_position: 108.5, 117.5  # Z归位时的喷嘴位置（不是探针！）
speed: 120
z_hop: 10
z_hop_speed: 5

[tmc2209 stepper_x]

ini

run_current: 0.750             # Amps RMS — start at 70% rated current
hold_current: 0.500            # Optional — Klipper docs recommend omitting
stealthchop_threshold: 999999  # 999999=always stealthChop; 0=always spreadCycle
interpolate: True              # micro-step interpolation (small positional error)
driver_SGTHRS: 255             # stallGuard threshold for sensorless homing (if used)

ini

run_current: 0.750             # RMS电流 —— 从额定电流的70%开始
hold_current: 0.500            # 可选 —— Klipper文档建议省略
stealthchop_threshold: 999999  # 999999=始终使用stealthChop；0=始终使用spreadCycle
interpolate: True              # 微步插值（存在微小位置误差）
driver_SGTHRS: 255             # 无传感器归位的stallGuard阈值（如果使用）

[input_shaper]

ini

shaper_type_x: 3hump_ei        # mzv|ei|2hump_ei|3hump_ei|zv|zvd
shaper_freq_x: 66.2            # Hz — from SHAPER_CALIBRATE
shaper_type_y: ei
shaper_freq_y: 45.0

ini

shaper_type_x: 3hump_ei        # mzv|ei|2hump_ei|3hump_ei|zv|zvd
shaper_freq_x: 66.2            # 赫兹 —— 来自SHAPER_CALIBRATE
shaper_type_y: ei
shaper_freq_y: 45.0

[firmware_retraction]

ini

retract_length: 0.5            # mm — direct drive: 0.4–1.0; bowden: 4–7
retract_speed: 60              # mm/s
unretract_extra_length: 0
unretract_speed: 60

ini

retract_length: 0.5            # 毫米 —— 直接驱动：0.4–1.0；远程驱动：4–7
retract_speed: 60              # 毫米/秒
unretract_extra_length: 0
unretract_speed: 60

Moonraker API Quick Reference

Moonraker API快速参考

Base URL:

http://<IP>:7125

Method	Endpoint	Purpose
GET	`/printer/info`	Klipper state, version, hostname
GET	`/server/files/config/printer.cfg`	Read printer.cfg
GET	`/server/files/list?root=config`	List all config files
POST	`/server/files/upload` (multipart)	Upload/overwrite a config file
POST	`/printer/firmware_restart`	Firmware restart (apply config changes)
POST	`/printer/gcode/script`	Send GCode command (JSON body: `{"script":"..."}` )
GET	`/printer/objects/list`	List all queryable printer objects
GET	`/printer/objects/query?<obj>=<fields>`	Query live printer state
GET	`/printer/query_endstops/status`	Endstop states
POST	`/printer/gcode/script` `{"script":"SAVE_CONFIG"}`	Persist calibration data
GET	`/server/info`	Moonraker version, registered components
POST	`/machine/reboot`	Reboot the host (Pi)
POST	`/machine/shutdown`	Shutdown the host

基础URL:

http://<IP>:7125

方法	端点	用途
GET	`/printer/info`	Klipper状态、版本、主机名
GET	`/server/files/config/printer.cfg`	读取printer.cfg
GET	`/server/files/list?root=config`	列出所有配置文件
POST	`/server/files/upload` (multipart)	上传/覆盖配置文件
POST	`/printer/firmware_restart`	重启固件（应用配置更改）
POST	`/printer/gcode/script`	发送GCode命令（JSON体： `{"script":"..."}` ）
GET	`/printer/objects/list`	列出所有可查询的打印机对象
GET	`/printer/objects/query?<obj>=<fields>`	查询打印机实时状态
GET	`/printer/query_endstops/status`	限位开关状态
POST	`/printer/gcode/script` `{"script":"SAVE_CONFIG"}`	持久化校准数据
GET	`/server/info`	Moonraker版本、已注册组件
POST	`/machine/reboot`	重启主机（树莓派）
POST	`/machine/shutdown`	关闭主机

File Upload (curl)

文件上传（curl）

bash

curl -X POST "http://<IP>:7125/server/files/upload" \
  -F "root=config" \
  -F "file=@/path/to/printer.cfg;filename=printer.cfg"

bash

curl -X POST "http://<IP>:7125/server/files/upload" \
  -F "root=config" \
  -F "file=@/path/to/printer.cfg;filename=printer.cfg"

GCode Send (curl)

GCode发送（curl）

bash

curl -X POST "http://<IP>:7125/printer/gcode/script" \
  -H "Content-Type: application/json" \
  -d '{"script": "G28"}'

bash

curl -X POST "http://<IP>:7125/printer/gcode/script" \
  -H "Content-Type: application/json" \
  -d '{"script": "G28"}'

Object Query (curl)

对象查询（curl）

bash

curl "http://<IP>:7125/printer/objects/query?extruder&heater_bed&toolhead"

bash

curl "http://<IP>:7125/printer/objects/query?extruder&heater_bed&toolhead"

Platform Notes

平台说明

The AI performs all config fetching, parsing, and editing inline using

curl

(available on both Windows and Linux) and direct text analysis. The scripts in

scripts/

are provided as reference implementations and work on Linux/macOS (require

python3

). On Windows, the AI executes the equivalent logic directly — do not rely on the shell scripts.

When running on the Klipper host directly (via SSH), the scripts work without modification.

AI使用

curl

（Windows和Linux均支持）和直接文本分析，在线完成所有配置获取、解析和编辑操作。

scripts/

中的脚本是参考实现，适用于Linux/macOS（需要

python3

）。在Windows上，AI直接执行等效逻辑 —— 请勿依赖shell脚本。

如果直接在Klipper主机上运行（通过SSH），脚本无需修改即可使用。

File Structure

文件结构

klipper-manager/
├── SKILL.md                         # This file
├── references/
│   ├── config_sections.md           # Full parameter reference for all config sections
│   ├── gcodes.md                    # All supported G-codes and extended commands
│   ├── troubleshooting.md           # Error patterns → causes → fixes
│   └── moonraker_api.md             # Full Moonraker API reference
├── scripts/
│   ├── fetch_config.sh              # Fetch printer.cfg from Moonraker
│   ├── upload_config.sh             # Upload modified config
│   ├── send_gcode.sh                # Send a GCode command
│   ├── query_status.sh              # Query printer status objects
│   └── diagnose.sh                  # Full diagnostic run
└── state/
    └── printer_context.json         # Persisted printer state (auto-created)

Base directory:

file:///C:/Users/santi/.config/opencode/skills/klipper-manager

klipper-manager/
├── SKILL.md                         # 本文件
├── references/
│   ├── config_sections.md           # 所有配置段的完整参数参考
│   ├── gcodes.md                    # 所有支持的G代码和扩展命令
│   ├── troubleshooting.md           # 错误模式→原因→修复
│   └── moonraker_api.md             # 完整Moonraker API参考
├── scripts/
│   ├── fetch_config.sh              # 从Moonraker获取printer.cfg
│   ├── upload_config.sh             # 上传修改后的配置
│   ├── send_gcode.sh                # 发送GCode命令
│   ├── query_status.sh              # 查询打印机状态对象
│   └── diagnose.sh                  # 完整诊断运行
└── state/
    └── printer_context.json         # 持久化打印机状态（自动创建）

基础目录:

file:///C:/Users/santi/.config/opencode/skills/klipper-manager