Klipper API服务器详解：3D打印控制与监控接口指南

Klipper API服务器详解：3D打印控制与监控接口指南

klipper Klipper is a 3d-printer firmware 项目地址: https://gitcode.com/gh_mirrors/kl/klipper

概述

Klipper API服务器是Klipper固件提供的一个强大接口，允许外部应用程序通过Unix域套接字与Klipper主机软件进行交互。这个接口为开发者提供了丰富的功能，包括打印机状态查询、G代码执行、运动控制等。

API服务器启用方法

要启用Klipper API服务器，需要在启动klippy.py时添加-a参数指定Unix域套接字路径：

~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -a /tmp/klippy_uds -l /tmp/klippy.log

这条命令会在指定路径创建Unix域套接字，客户端可以通过这个套接字与Klipper通信。

通信协议详解

消息格式

Klipper API使用JSON格式的消息，每条消息以ASCII 0x03字符(ETX)作为结束符：

<json_object_1><0x03><json_object_2><0x03>...

Klipper提供了一个方便的测试工具whconsole.py，可以用于发送和接收这种格式的消息：

~/klipper/scripts/whconsole.py /tmp/klippy_uds

请求-响应模式

API采用类似JSON-RPC的协议：

• 请求示例：

{"id": 123, "method": "info", "params": {}}

• 成功响应示例：

{"id": 123, "result": {"state_message": "Printer is ready", "software_version": "v0.8.0"}}

• 错误响应示例：

{"id": 123, "error": {"message": "Must home axis first", "error": "WebRequestError"}}

订阅机制

某些端点支持订阅功能，可以接收异步更新消息。例如：

请求：

{"id": 123, "method": "gcode/subscribe_output", "params": {"response_template":{"key": 345}}}

后续可能收到：

{"params": {"response": "ok B:22.8 /0.0 T0:22.4 /0.0"}, "key": 345}

核心API端点详解

1. 系统信息端点

info - 获取系统信息：

{"id": 123, "method": "info", "params": {"client_info": {"version": "v1"}}}

返回内容包括Klipper版本、配置文件路径、主机状态等。

2. 紧急控制端点

emergency_stop - 紧急停止（等效于M112命令）：

{"id": 123, "method": "emergency_stop"}

3. 远程方法注册

register_remote_method - 注册可从Klipper调用的远程方法：

{"id": 123, "method": "register_remote_method", "params": {"remote_method": "paneldue_beep"}}

注册后可以在G代码宏中调用：

{action_call_remote_method("paneldue_beep", frequency=300, duration=1.0)}

4. 对象查询端点

objects/list - 列出可查询对象：

{"id": 123, "method": "objects/list"}

objects/query - 查询对象状态：

{"id": 123, "method": "objects/query", "params": {"objects": {"toolhead": ["position"]}}}

objects/subscribe - 订阅对象状态变化：

{"id": 123, "method": "objects/subscribe", "params": {"objects": {"toolhead": ["position"]}}}

5. G代码相关端点

gcode/help - 获取G代码帮助信息

gcode/script - 执行G代码脚本：

{"id": 123, "method": "gcode/script", "params": {"script": "G28"}}

gcode/subscribe_output - 订阅G代码终端输出

6. 运动系统监控端点

motion_report/dump_stepper - 获取步进电机运动数据

motion_report/dump_trapq - 获取梯形运动队列数据

7. 传感器数据端点

adxl345/dump_adxl345 - 获取加速度计数据

angle/dump_angle - 获取角度传感器数据

load_cell/dump_force - 获取称重传感器数据

8. 打印控制端点

pause_resume/pause - 暂停打印

pause_resume/resume - 恢复打印

pause_resume/cancel - 取消打印

9. 床面调平端点

bed_mesh/dump_mesh - 获取床面网格数据：

{"id": 123, "method": "bed_mesh/dump_mesh"}

返回详细网格信息，包括探测点数据、网格参数等。

最佳实践与注意事项

1. 性能考虑：订阅大量数据或高频数据（如传感器数据）会增加系统负载，应根据实际需求谨慎使用。

2. 错误处理：所有API调用都应处理可能的错误响应，特别是G代码相关操作。

3. 异步特性：Klipper会按顺序处理请求，但某些操作可能需要较长时间才能完成响应。

4. 安全考虑：确保API套接字有适当的权限设置，防止未授权访问。

5. 调试工具：开发过程中可以利用whconsole.py工具进行API测试和调试。

Klipper API服务器为开发者提供了强大的打印机控制和监控能力，通过合理利用这些接口，可以构建功能丰富的3D打印管理应用和自动化流程。

klipper Klipper is a 3d-printer firmware 项目地址: https://gitcode.com/gh_mirrors/kl/klipper