From 88bbd66a3bee6a1e7dc7e480ac50b57042425c19 Mon Sep 17 00:00:00 2001 From: Arksine Date: Sun, 16 Aug 2020 14:06:59 -0400 Subject: [PATCH] docs: document latest API changes Signed-off-by: Eric Callahan --- docs/api_changes.md | 90 ++++++++++++++++++++++++++++++++++++++++++++ docs/installation.md | 31 +++++++++++++++ docs/web_api.md | 30 +++++++-------- 3 files changed, 134 insertions(+), 17 deletions(-) create mode 100644 docs/api_changes.md diff --git a/docs/api_changes.md b/docs/api_changes.md new file mode 100644 index 0000000..ba2e052 --- /dev/null +++ b/docs/api_changes.md @@ -0,0 +1,90 @@ +This document keeps a record of all changes to Moonraker's remote +facing APIs. + +### August 16 2020 +- The structure of data returned from `/printer/info` (`get_printer_info`) + has changed to the following format: + ```json + { + state: "", + state_message: "", + hostname: "", + software_version: "", + cpu_info: "", + klipper_path: "", + python_path: "", + log_file: "", + config_file: "", + } + ``` + The "state" item can be one of the following: + - "startup" - Klippy is in the process of starting up + - "ready" - Klippy is ready + - "shutdown" - Klippy has shutdown + - "error" - Klippy has experienced an error during startup + + The message from each state can be found in the `state_message`. +- A `webhooks` printer object has been added, available for subscription or + query. It includes the following items: + - `state` - Printer state identical to that returned from `/printer/info` + - `state_message` - identical to that returned from `/printer/info` +- `/printer/objects/status` (`get_printer_objects_status`) has been renamed to + `/printer/objects/query` (`get_printer_objects_query`). The format of the + websocket request has changed, it should now look like the following: + ```json + { + jsonrpc: "2.0", + method: "get_printer_objects_query", + params: { + objects: { + gcode: null, + toolhead: ["position", "status"] + } + }, + id: + } + ``` + As shown above, printer objects are now wrapped in an "objects" parameter. + When a client wishes to subscribe to all items of a printer object, they + should now be set to `null` rather than an empty array. + The return value has also changed: + ```json + { + eventtime: , + status: { + gcode: { + busy: true, + gcode_position: [0, 0, 0 ,0], + ...}, + toolhead: { + position: [0, 0, 0, 0], + status: "Ready", + ...}, + ...} + } + ``` + The `status` item now contains the requested status. +- `/printer/objects/subscription` (`post_printer_objects_subscription`) is now + `printer/objects/subscribe` (`post_printer_objects_subscribe`). This + request takes parameters in the same format as the `query`. It now returns + state for all currently subscribed objects (in the same format as a `query`). + This data can be used to initialize all local state after the request + completes. +- Subscriptions are now pushed as "diffs". Clients will only recieve updates + for subscribed items when that data changes. This requires that clients + initialize their local state with the data returned from the subscription + request. +- The structure of data returned from `/printer/objects/list` has changed. It + now returns an array of available printer objects: + ```json + { objects: ["gcode", "toolhead", "bed_mesh", "configfile",....]} + ``` +- The `notify_klippy_state_changed` notification has been removed. Clients + can subscribe to `webhooks` and use `webhooks.state` to be notified of + transitions to the "ready" and "shutdown" states +- A `notify_klippy_disconnected` event has been added to notify clients + when the connection between Klippy and Moonraker has been terminated. + This event is sent with no parameters: + ```json + {jsonrpc: "2.0", method: "notify_klippy_disconnected"} + ``` diff --git a/docs/installation.md b/docs/installation.md index 7c6f9f3..7406ac6 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -10,6 +10,37 @@ Klipper should be installed prior to installing Moonraker. Please see [Klipper's Documention](https://github.com/KevinOConnor/klipper/blob/master/docs/Installation.md) for instructions on how to do this. +After Klipper is installed, you need to modify its "default" file. This file +contains klipper's command line arguments, and you must add an argument that +instructs Klippy to create a Unix Domain socket: +``` +sudo nano /etc/default/klipper +``` +You should see a file that looks something like the following: +``` +# Configuration for /etc/init.d/klipper + +KLIPPY_USER=pi + +KLIPPY_EXEC=/home/pi/klippy-env/bin/python + +KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg -l /tmp/klippy.log" +``` + +You need to add `-a /tmp/klippy_uds` to KLIPPY_ARGS: +``` +# Configuration for /etc/init.d/klipper + +KLIPPY_USER=pi + +KLIPPY_EXEC=/home/pi/klippy-env/bin/python + +KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg -l /tmp/klippy.log -a /tmp/klippy_uds" +``` +You may also want to take this opportunity to change the location of +printer.cfg if you enable Moonraker's "config_path" option (see the +[configuration section](#moonraker-configuration-moonrakerconf) for more information). + You can now install the Moonraker application: ``` cd ~ diff --git a/docs/web_api.md b/docs/web_api.md index d5694d8..fa35aa0 100644 --- a/docs/web_api.md +++ b/docs/web_api.md @@ -100,7 +100,7 @@ that uses promises to return responses and errors (see json-rcp.js). or subscription. This list will be passed in an "objects" parameter. ```json - { objects: [gcode, toolhead, bed_mesh, configfile...]} + { objects: ["gcode", "toolhead", "bed_mesh", "configfile",....]} ``` ### Query the a status for an object, or group of objects: @@ -671,11 +671,16 @@ Printer generated events are sent over the websocket as JSON-RPC 2.0 notifications. These notifications are sent to all connected clients in the following format: -`{jsonrpc: "2.0", method: , params: []}` +`{jsonrpc: "2.0", method: }` -It is important to keep in mind that the `params` value will always be +OR + +`{jsonrpc: "2.0", method: , params: []}` + +If a notification has parameters, the `params` value will always be wrapped in an array as directed by the JSON-RPC standard. Currently -all notifications available are broadcast with a single parameter. +all notifications available are broadcast with either no parameters +or a single parameter. ### Gcode response: All calls to gcode.respond() are forwarded over the websocket. They arrive @@ -689,21 +694,12 @@ Status Subscriptions arrive as a "notify_status_update" notification: `{jsonrpc: "2.0", method: "notify_status_update", params: []}` The structure of the status data is identical to the structure that is -returned from a status request. +returned from an object query's "status" attribute. -### Klippy Process State Changed: -The following Klippy state changes are broadcast over the websocket: -- ready -- disconnect -- shutdown +### Klippy Disconnected: +Notify clients when Moonraker's connection to Klippy has terminated -Note that Klippy's "ready" is different from the Printer's "ready". The -Klippy "ready" state is broadcast upon startup after initialization is -complete. It should also be noted that the websocket will be disconnected -after the "disconnect" state, as that notification is broadcast prior to a -restart. Klippy State notifications are broadcast in the following format: - -`{jsonrpc: "2.0", method: "notify_klippy_state_changed", params: []}` +`{jsonrpc: "2.0", method: "notify_klippy_disconnected"}` ### File List Changed When a client makes a change to the virtual sdcard file list