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發送命令。

See the Moonraker project for a popular tool that can forward HTTP requests to Klipper's API Server Unix Domain Socket.

請求格式¶

套接字進出的數據包應使用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」而定。

請求字典可能包含一個“id”參數，它可以是任何 JSON 類型。如果存在“id”，那麼 Klipper 將使用包含該“id”的響應消息來響應請求。如果省略“id”（或設置為 JSON“null”值），則 Klipper 不會對請求提供任何響應。響應消息是包含“id”和“result”的 JSON 字典。 “結果”始終是一個字典 - 它的內容特定於處理請求的“端點”。

如果處理的請求造成了錯誤，則響應訊息將包含"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 請求的處理。

訂閱¶

一些 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 將在響應模板中添加一個包含具有“端點”特定內容的字典的“參數”字段，然後發送該模板。如果未提供“response_template”字段，則默認為空字典（{}）。

可用的“端點”¶

按照慣例，Klipper “端點”的格式為 <module_name>/<some_name>。向“端點”發出請求時，必須在請求字典的“方法”參數中設置全名（例如，{"method"="gcode/restart"}）。

信息¶

“info”端點用於從 Klipper 獲取系統和版本信息。它還用於向 Klipper 提供客戶端的版本信息。例如：{"id": 123, "method": "info", "params": { "client_info": { "version": "v1"}}}

如果存在，“client_info”參數必須是字典，但該字典可能具有任意內容。鼓勵客戶端在首次連接到 Klipper API 服務器時提供客戶端名稱及其軟件版本。

emergency_stop¶

“emergency_stop”端點用於指示 Klipper 轉換到“關閉”狀態。它的行為類似於 G-Code M112 命令。例如：{"id": 123, "method": "emergency_stop"}

register_remote_method¶

此端點允許客戶端註冊可以從 klipper 調用的方法。成功後將返回一個空對象。

例如：{"id": 123, "method": "register_remote_method", "params": {"response_template": {"action": "run_paneldue_beep"}, "remote_method": "paneldue_beep"}} 將返回：{“id”：123，“結果”：{}}

現在可以從 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" , “加熱器”, “gcode_move”, “query_endstops”, “idle_timeout”, “toolhead”, “extruder”]}}

objects/query¶

該端點允許從打印機對像中查詢信息。例如：{"id": 123, "method": "objects/query", "params": {"objects": {"toolhead": ["position"], "webhooks": null}}}可能返回：{"id": 123, "result": {"status": {"webhooks": {"state": "ready", "state_message": "Printer is ready"}, "toolhead": { “位置”：[0.0, 0.0, 0.0, 0.0]}}，“事件時間”：3051555.377933684}}

請求中的“objects”參數必須是包含要查詢的打印機對象的字典 - 鍵包含打印機對象名稱，值為“null”（查詢所有字段）或字段名稱列表。

響應消息將包含一個“狀態”字段，其中包含帶有查詢信息的字典 - 鍵包含打印機對象名稱，值是包含其字段的字典。響應消息還將包含一個“eventtime”字段，其中包含進行查詢時的時間戳。

可用字段記錄在 Status Reference 文檔中。

objects/subscribe¶

該端點允許查詢然後訂閱來自打印機對象的信息。端點請求和響應與“對象/查詢”端點相同。例如：{"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": {“狀態”：“關機”}}，“事件時間”：3052165.418815847}}

gcode/help¶

該端點允許查詢已定義幫助字符串的可用 G 代碼命令。例如：{"id": 123, "method": "gcode/help"} 可能會返回：{"id": 123, "result": {"RESTORE_GCODE_STATE": "恢復以前保存的 G-Code state", "PID_CALIBRATE": "運行 PID 校準測試", "QUERY_ADC": "報告模擬引腳的最後值", ...}}

gcode/script¶

該端點允許運行一系列 G 代碼命令。例如：{"id": 123, "method": "gcode/script", "params": {"script": "G90"}}

如果提供的 G 代碼腳本引發錯誤，則會生成錯誤響應。但是，如果 G 代碼命令產生終端輸出，則該終端輸出不會在響應中提供。（使用“gcode/subscribe_output”端點獲取 G-Code 終端輸出。）

如果收到此請求時正在處理 G-Code 命令，則提供的腳本將排隊。這種延遲可能很明顯（例如，如果 G 代碼等待溫度命令正在運行）。當腳本處理完全完成時發送 JSON 響應消息。

gcode/restart¶

該端點允許請求重新啟動 - 它類似於運行 G 代碼“RESTART”命令。例如：{"id": 123, "method": "gcode/restart"}

與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。

gcode/firmware_restart¶

這類似於“gcode/restart”端點——它實現了 G-Code“FIRMWARE_RESTART”命令。例如：{"id": 123, "method": "gcode/firmware_restart"}

與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。

gcode/subscribe_output¶

此端點用於訂閱由 Klipper 生成的 G-Code 終端消息。例如：{"id": 123, "method": "gcode/subscribe_output", "params": {"response_template":{}}} 可能稍後會產生異步消息，例如：{"params": { "response": "// Klipper 狀態：關機"}}

該端點旨在通過“終端窗口”界面支持人機交互。不鼓勵從 G 代碼終端輸出解析內容。使用“objects/subscribe”端點獲取 Klipper 狀態的更新。

motion_report/dump_stepper¶

此端點用於為步進器訂閱 Klipper 的內部步進器 queue_step 命令流。獲取這些低級運動更新可能對診斷和調試有用。使用此端點可能會增加 Klipper 的系統負載。

一個請求可能看起來像：{"id": 123, "method":"motion_report/dump_stepper", "params": {"name": "stepper_x", "response_template": {}}} 並且可能返回： {"id": 123, "result": {"header": ["interval", "count", "add"]}} 之後可能會產生異步消息，例如：{"params": {" first_clock”：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] , [9855, 5, 187], [11632, 4, 1534], [20756, 2, 9442]]}}

初始查詢響應中的“header”字段用於描述在以後的“data”響應中找到的字段。

motion_report/dump_trapq¶

該端點用於訂閱 Klipper 的內部“梯形運動隊列”。獲取這些低級運動更新可能對診斷和調試有用。使用此端點可能會增加 Klipper 的系統負載。

一個請求可能看起來像：{"id": 123, "method": "motion_report/dump_trapq", "params": {"name": "toolhead", "response_template":{}}} 並且可能返回： {"id": 1, "result": {"header": ["time", "duration", "start_velocity", "acceleration", "start_position", "direction"]}} 並且以後可能會產生異步消息，例如：{"params": {"data": [[4.05, 1.0, 0.0, 0.0, [300.0, 0.0, 0.0], [0.0, 0.0, 0.0]], [5.054, 0.001, 0.0, 3000.0 , [300.0, 0.0, 0.0], [-1.0, 0.0, 0.0]]]}}

初始查詢響應中的“header”字段用於描述在以後的“data”響應中找到的字段。

adxl345/dump_adxl345¶

該端點用於訂閱 ADXL345 加速度計數據。獲取這些低級運動更新可能對診斷和調試有用。使用此端點可能會增加 Klipper 的系統負載。

請求可能類似於：{"id": 123, "method":"adxl345/dump_adxl345", "params": {"sensor": "adxl345", "response_template": {}}} 並且可能返回： {"id": 123,"result":{"header":["time","x_acceleration","y_acceleration", "z_acceleration"]}} 並且可能稍後會產生異步消息，例如：{"params ":{"溢出":0,"數據":[[3292.432935,-535.44309,-1529.8374,9561.4], [3292.433256,-382.45935,-1606.32927,9561.48375]}}

初始查詢響應中的“header”字段用於描述在以後的“data”響應中找到的字段。

angle/dump_angle¶

This endpoint is used to subscribe to angle sensor data. Obtaining these low-level motion updates may be useful for diagnostic and debugging purposes. Using this endpoint may increase Klipper's system load.

A request may look like: {"id": 123, "method":"angle/dump_angle", "params": {"sensor": "my_angle_sensor", "response_template": {}}} and might return: {"id": 123,"result":{"header":["time","angle"]}} and might later produce asynchronous messages such as: {"params":{"position_offset":3.151562,"errors":0, "data":[[1290.951905,-5063],[1290.952321,-5065]]}}

初始查詢響應中的“header”字段用於描述在以後的“data”響應中找到的字段。

pause_resume/cancel¶

此端點類似於運行“PRINT_CANCEL”G 代碼命令。例如：{"id": 123, "method": "pause_resume/cancel"}

與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。

pause_resume/pause¶

此端點類似於運行“PAUSE”G 代碼命令。例如：{"id": 123, "method": "pause_resume/pause"}

與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。

pause_resume/resume¶

此端點類似於運行“RESUME”G 代碼命令。例如：{"id": 123, "method": "pause_resume/resume"}

與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。

query_endstops/status¶

該端點將查詢活動端點並返回它們的狀態。例如：{"id": 123, "method": "query_endstops/status"} 可能返回：{"id": 123, "result": {"y": "open", "x": “打開”，“z”：“觸發”}}

與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。