跳转至

API 服务器

该文档介绍Klipper的应用开发者接口(API)功能。该接口允许外部应用程序访问和控制Klipper主机。

启用API套接字

要启用API服务器,klipper.py运行时应加上 -a 参数。例如:

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

上述操作会使主机创建一个Unix本地套接字。之后,客户应用程序可以创建一个套接字链接,从而给Klipper发送命令。

参见Moonraker项目,该项目是一个流行的工具,可以将HTTP请求转发到Klipper的API服务器Unix域插座。

请求格式

套接字进出的数据包应使用JSON编码的字符串,并以ASCII字符0x03作为结尾:

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

Klipper使用scripts/whconsole.py的代码进行上述的数据帧打包。例如:

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

该工具会从stdin中读取一系列的JSON命令,发送到Klipper执行,并将结果送出。该工具默认输入的每条Json命令中不存在换行,并自动地在发送命令时在结尾附上0x03。(Klipper API服务器没有换行符要求。)

API协议

套接字的命令协议受 json-rpc 启发。

一个请求命令类似:

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

一个回应帧类似:

{"id": 123, "result": {"state_message": "Printer is ready", "klipper_path": "/home/pi/klipper", "config_file": "/home/pi/printer.cfg", "software_version": "v0.8.0-823-g883b1cb6", "hostname": "octopi", "cpu_info": "4 core ARMv7 Processor rev 4 (v7l)", "state": "ready", "python_path": "/home/pi/klippy-env/bin/python", "log_file": "/tmp/klippy.log"}}

每个请求应为一个JSON字典。(本文档使用Python中的术语“字典”描述以{}为边界的“键-值”JSON对象。)

请求字典中必须包含一个”method”字段,其值应包含一个可用的Klipper端点”endpoint”名称字符串。

请求字典可能包含”params”参数,并其值应为一个字典类型。”params”提供Klipper”endpoint”处理请求所需的额外数据,其内容依”endpoint”而定。

请求的字典可以包含一个可以是任何 JSON类型的"id"参数。如果"id"存在,那么 Klipper 将用一个包含该"id"的响应信息来回应请求。如果"id"被省略(或设置为 JSON 的 "null" 值),那么 Klipper 将不会对该请求进行任何响应。响应信息是一个 包含 "id" 和 "result"的 JSON 字典。"result"总是一个字典--它的内容是特定于处理请求的"endstop"。

如果处理的请求造成了错误,则响应消息将包含"error"字段,而不是"result"字段。例如,请求: {"id": 123, "method": "gcode/script", "params": {"script": "G1 X200"}} 可能会返回错误响应,例如: {"id": 123, "error": {"message": "Must home axis first: 200.000 0.000 0.000 [0.000]", "error": "WebRequestError"}}

Klipper 会按照收到请求的顺序依次处理请求。然而,一些请求可能不会立即完成,这可能会导致相关的响应与其他请求的响应不按顺序发送。一个 JSON 请求永远不会暂停对未来JSON 请求的处理。

订阅(Subscriptions)

一些 Klipper 的"endpoint"可以以 "订阅" 的形式接收未来的异步更新消息。

例如:

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

可能会返回一个初始回应:

{"id": 123, "result": {}}

并导致 Klipper 在未来发送类似于以下内容的消息:

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

订阅请求接受请求的“params”字段中的“response_template”字典。“response_template”字典被用作未来异步消息的模板——它可能包含任意的键/值对。当发送这些未来的异步消息时,Klipper将在响应模板中添加一个“params”字段,该字段包含一个具有“端点”特定内容的字典,然后发送该模板。如果没有提供“response_template”字段,则默认为空字典({})。

可用的"endpoint"

按照惯例,Klipper“端点”的形式为“/'”。当向“端点”发出请求时,必须在请求字典的“方法”参数中设置全名(例如,{“方法”=“gcode/restart”})。

info

“info” 用于从Klipper获取系统和版本信息。同时也被用来向Klipper提供客户端的版本信息。比如说{"id": 123, "method": "info", "params": { "client_info": { "version": "v1"}}}

如果存在,“client_info”参数必须是一个字典,但该字典可能具有任意内容。鼓励客户端在首次连接到Klipper API服务器时提供客户端名称及其软件版本。

emergency_stop

"emergency_stop"端点用于指示 Klipper 过渡到 "shutdown"状态。它的行为类似于 G 代码 "M112 "命令。例如:{"id": 123, "method": "emergency_stop"}

register_remote_method

该端点允许客户端注册可从 klipper 调用的方法。成功后将返回一个空对象。

例如:{“id”:123,“method”:“register_remote_method”,“params”:{“response_template”:{“action”:“run_paneldue_deep”},“remote_method“:”paneldue_beep

现在可以从Klipper调用远程方法 paneldue_beep。请注意,如果方法采用参数,则应将它们作为关键字参数提供。以下是如何从gcode_macro调用它的示例:

[gcode_macro PANELDUE_BEEP]
gcode:
  {action_call_remote_method("paneldue_beep", frequency=300, duration=1.0)}

当PANELDUE_BEEP gcode宏被执行时,Klipper将通过套接字发送类似以下内容:{"action": "run_paneldue_beep", "params": {"frequency": 300, "duration": 1.0}}

objects/list

该端点查询可用打印机“对象”的列表,可以查询(通过“对象/查询”端点)。例如:{“id”:123,“method”:“objects/list”}可能返回: {"id": 123, "result": {"objects": ["webhooks", "configfile", "heaters", "gcode_move", "query_endstops", "idle_timeout", "toolhead", "extruder"]}}

objects/query

这个endpoint允许从打印机对象中查询信息。比如说:{"id": 123, "method": "objects/query", "params": {"objects": {"toolhead": ["position"], "webhooks": null}}} 可能返回。{"id": 123, "result": {"status": {"webhooks": {"state": "ready", "state_message": "Printer is ready"}, "toolhead": {"position": [0.0, 0.0, 0.0, 0.0]}}, "eventtime": 3051555.377933684}}

请求中的 "objects "参数必须是一个包含要查询的打印机对象的字典 - 键包含打印机对象名称,值是 "null"(查询所有字段)或一个字段名的列表。

响应消息将包含一个 "status "字段,其中包含一个包含查询信息的字典 - 键包含打印机对象名称,值是一个包含其字段的字典。响应消息还将包含一个 "eventtime "字段,其中包含从查询开始的时间戳。

Status Reference 文档中定义了可用字段。

objects/subscribe

这个endpoint允许查询,然后subscribe打印机对象的信息。端点的请求和响应与 "objects/query" endpoint相同。例如。"id": 123, "method": "objects/subscribe", "params": {"objects":{"toolhead": ["position"], "webhooks": ["state"]}, "response_template":{}}} 可能返回:{"id": 123, "result": {"status": {"webhooks": {"state": "ready"}, "toolhead": {"position": [0.0, 0.0, 0.0, 0.0]}}, "eventtime": 3052153.382083195}} ,并导致随后的异步消息,例如:{"params": {"status": {"webhooks": {"state": "shutdown"}}, "eventtime": 3052165.418815847}}

gcode/help

这个endpoint允许查询有定义帮助字符串的可用G-Code命令。例如:{"id": 123, "method": "gcode/help"} 可能返回:{"id": 123, "result": {"RESTORE_GCODE_STATE": "Restore a previously saved G-Code state", "PID_CALIBRATE": "Run PID calibration test", "QUERY_ADC": "Report the last value of an analog pin", ...}}

gcode/script

这个endpoint允许运行一系列的G代码命令。比如说:{"id": 123, "method": "gcode/script", "params": {"script": "G90"}}

如果提供的G-Code脚本产生了错误,那么就会产生一个错误响应。然而,如果G-Code命令产生了终端输出,则该终端输出不会在响应中提供。(使用 "gcode/subscribe_output " endpoint 来获取G-Code终端输出。)

如果在收到这个请求时有一个G-Code命令正在处理,那么所提供的脚本将被排队。这个延迟可能很严重(例如,如果一个G-Code等待温度的命令正在运行)。当脚本的处理完全完成时,将发送JSON响应信息。

gcode/restart

该端点允许用户请求重新启动-它类似于运行G-Code“重新启动”命令。例如:{“id”:123,“方法”:“gcode/Restart”}

与“gcode/脚本”终结点一样,该终结点只有在所有挂起的G-Code命令完成后才会完成。

gcode/firmware_restart

这类似于“GCODE/RESTART”端点-它实现G-Code“Firmware_Restart”命令。例如:{“id”:123,“方法”:“gcode/Firmware_Restart”}

与“gcode/脚本”终结点一样,该终结点只有在所有挂起的G-Code命令完成后才会完成。

GCODE/订阅输出

此端点用于订阅由Klipper生成的G-Code终端消息。例如:{“id”:123,“Method”:“gcode/SUBSCRIBE_OUTPUT”,“PARAMS”:{“RESPONSE_TEMPLATE”:{}以后可能会产生异步消息,如:{“PARAMS”:{“RESPONSE”:“//Klipper STATE:Shutdown”}}

该端点旨在通过“终端窗口”界面支持人类交互。不鼓励解析来自G-Code终端输出的内容。使用“对象/订阅”终结点获取Klipper状态的更新。

motion_report/dump_stepper

此终结点用于订阅Klipper的内部Steper Queue_Step命令流以获取Steper。获取这些低级运动更新对于诊断和调试目的可能有用。使用此终结点可能会增加Klipper的系统负载。

请求可以看起来类似于:{“id”:123,“method”:“Motion_report/Dump_Steper”,“pars”{“name”:“Steper_x”,“Response_Template”:{},并且可以返回:{“id”:123,“Result”:{“Header”[“Interval”,“count”,“Add”]}},并且可以稍后产生诸如:{“paras”:{“first_lock”:179601081,“First_Time”:8.98,“First_Position”:0,“Last_Clock”:219686097,“Last_Time”:10.984,“DATA”:[[179601081,1,0],[29573,2,-8685],[16230,4-1525],[10559,6,-160],[10000,976,0],[10000,1000,0],[10000,1000,0],[10000,1000,0],[10.984,1000,0],[9855,5,187],[11632,4,1534],[20756,2,9442]}}

初始查询响应中的“Header”字段用于描述在随后的“数据”响应中找到的字段。

运动_报告/转储_陷阱

该端点用于订阅Klipper内部的“梯形运动队列”。获取这些低级运动更新对于诊断和调试目的可能有用。使用此终结点可能会增加Klipper的系统负载。

请求可能类似于:{“id”:123,“method”:“Motion_report/ump_trapq”,“pars”:{“name”:“工具头”,“Response_Template”:{},并可能返回:{“id”:1,“Result”:{“Header”:[“time”,“时长”,“Start_Velace”,“Acceleration”,“Start_Position”,并可能在以后产生异步消息,如:}`

初始查询响应中的“Header”字段用于描述在随后的“数据”响应中找到的字段。

adxl345/dump_adxl345

该端点用于订阅ADXL345加速度计数据。获取这些低级运动更新对于诊断和调试目的可能有用。使用此终结点可能会增加Klipper的系统负载。

请求可以看起来类似于:{“id”:123,“method”:“adxl345/ump_adxl345”,“params”:{“ensor”:“adxl345”,“Response_Template”:{},并且可以返回:{“id”:123,“Result”:{“Header”:[“time”,“x_acceleration”,“y_acceleration”,“z_acceleration”]}},并且稍后可能产生诸如:{“params”:{“overflow”:0,“数据”:[[3292.432935,-535.44309,-1529.8374,9561.4],[3292.433256,-382.45935,-1606.32927,9561.48375]]}}

初始查询响应中的“Header”字段用于描述在随后的“数据”响应中找到的字段。

角/转储角

该端点用于订阅角度传感器数据。获取这些低级运动更新对于诊断和调试目的可能有用。使用此终结点可能会增加Klipper的系统负载。

请求可能类似于:{“id”:123,“方法”:“角度/转储_角度”,“参数”:{“传感器”:“我的角度_传感器”,“响应模板”:{},并且可能返回:{“id”:123,“结果”:{“标题”:[“时间”,“角度”]}},并且可能稍后产生诸如:{“参数”:{“位置偏移量”:3.151562,“错误”:0,“data”:[[1290.951905,-5063],[1290.952321,-5065]}}

初始查询响应中的“Header”字段用于描述在随后的“数据”响应中找到的字段。

暂停_继续/取消

该端点类似于运行“PRINT_CANCEL”G-Code命令。例如:{“id”:123,“方法”:“PAUSE_RESUME/Cancel”}

与“gcode/脚本”终结点一样,该终结点只有在所有挂起的G-Code命令完成后才会完成。

暂停_恢复/暂停

此终结点类似于运行“暂停”G-Code命令。例如:{“id”:123,“方法”:“PAUSE_RESUME/PAUSE”}

与“gcode/脚本”终结点一样,该终结点只有在所有挂起的G-Code命令完成后才会完成。

暂停_恢复/恢复

此终结点类似于运行“Resume”G-Code命令。例如:{“id”:123,“方法”:“PAUSE_RESUME/RESUME”}

与“gcode/脚本”终结点一样,该终结点只有在所有挂起的G-Code命令完成后才会完成。

查询_结束停止/状态

此终结点将查询活动终结点并返回其状态。例如:{“id”:123,“Method”:“Query_endstopks/Status”}可能返回:{“id”:123,“Result”:{“y”:“Open”,“x”:“Open”,“z”:“Trigated”}

与“gcode/脚本”终结点一样,该终结点只有在所有挂起的G-Code命令完成后才会完成。

回到页面顶部