跳轉至

# 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”響應中找到的字段。

### hx71x/dump_hx71x

This endpoint is used to subscribe to raw HX711 and HX717 ADC data. Obtaining these low-level ADC 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":"hx71x/dump_hx71x", "params": {"sensor": "load_cell", "response_template": {}}}` and might return: `{"id": 123,"result":{"header":["time","counts","value"]}}` and might later produce asynchronous messages such as: `{"params":{"data":[[3292.432935, 562534, 0.067059278], [3292.4394937, 5625322, 0.670590639]]}}`

### ads1220/dump_ads1220

This endpoint is used to subscribe to raw ADS1220 ADC data. Obtaining these low-level ADC 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":"ads1220/dump_ads1220", "params": {"sensor": "load_cell", "response_template": {}}}` and might return: `{"id": 123,"result":{"header":["time","counts","value"]}}` and might later produce asynchronous messages such as: `{"params":{"data":[[3292.432935, 562534, 0.067059278], [3292.4394937, 5625322, 0.670590639]]}}`

### 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 代碼命令完成後才會完成。

### bed_mesh/dump_mesh

Dumps the configuration and state for the current mesh and all saved profiles.

For example: `{"id": 123, "method": "bed_mesh/dump_mesh"}`

might return:

    {
        "current_mesh": {
            "name": "eddy-scan-test",
            "probed_matrix": [...],
            "mesh_matrix": [...],
            "mesh_params": {
                "x_count": 9,
                "y_count": 9,
                "mesh_x_pps": 2,
                "mesh_y_pps": 2,
                "algo": "bicubic",
                "tension": 0.5,
                "min_x": 20,
                "max_x": 330,
                "min_y": 30,
                "max_y": 320
            }
        },
        "profiles": {
            "default": {
                "points": [...],
                "mesh_params": {
                    "min_x": 20,
                    "max_x": 330,
                    "min_y": 30,
                    "max_y": 320,
                    "x_count": 9,
                    "y_count": 9,
                    "mesh_x_pps": 2,
                    "mesh_y_pps": 2,
                    "algo": "bicubic",
                    "tension": 0.5
                }
            },
            "eddy-scan-test": {
                "points": [...],
                "mesh_params": {
                    "x_count": 9,
                    "y_count": 9,
                    "mesh_x_pps": 2,
                    "mesh_y_pps": 2,
                    "algo": "bicubic",
                    "tension": 0.5,
                    "min_x": 20,
                    "max_x": 330,
                    "min_y": 30,
                    "max_y": 320
                }
            },
            "eddy-rapid-test": {
                "points": [...],
                "mesh_params": {
                    "x_count": 9,
                    "y_count": 9,
                    "mesh_x_pps": 2,
                    "mesh_y_pps": 2,
                    "algo": "bicubic",
                    "tension": 0.5,
                    "min_x": 20,
                    "max_x": 330,
                    "min_y": 30,
                    "max_y": 320
                }
            }
        },
        "calibration": {
            "points": [...],
            "config": {
                "x_count": 9,
                "y_count": 9,
                "mesh_x_pps": 2,
                "mesh_y_pps": 2,
                "algo": "bicubic",
                "tension": 0.5,
                "mesh_min": [
                    20,
                    30
                ],
                "mesh_max": [
                    330,
                    320
                ],
                "origin": null,
                "radius": null
            },
            "probe_path": [...],
            "rapid_path": [...]
        },
        "probe_offsets": [
            0,
            25,
            0.5
        ],
        "axis_minimum": [
            0,
            0,
            -5,
            0
        ],
        "axis_maximum": [
            351,
            358,
            330,
            0
        ]
    }

The `dump_mesh` endpoint takes one optional parameter, `mesh_args`. This parameter must be an object, where the keys and values are parameters available to BED_MESH_CALIBRATE. This will update the mesh configuration and probe points using the supplied parameters prior to returning the result. It is recommended to omit mesh parameters unless it is desired to visualize the probe points and/or travel path before performing `BED_MESH_CALIBRATE`.

Back to top