From 833519ecc3ad5640ad78cd60361b98bf5a8a1ba3 Mon Sep 17 00:00:00 2001 From: Eric Callahan Date: Tue, 21 Feb 2023 08:21:50 -0500 Subject: [PATCH] docs: update file_manager documentation Signed-off-by: Eric Callahan --- docs/configuration.md | 9 +++ docs/web_api.md | 136 +++++++++++++++++++++++++++++++++++------- 2 files changed, 124 insertions(+), 21 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index cf26a62..50af795 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -94,7 +94,16 @@ enable_object_processing: False # "cancel object" functionality. Note that this process is file I/O intensive, # it is not recommended for usage on low resource SBCs such as a Pi Zero. # The default is False. +file_system_observer: inotify +# The observer used to monitor file system changes. May be inotify or none. +# When set to none file system observation is disabled. The default is +# inotify. +enable_observer_warnings: True +# When set to True Moonraker will generate warnings when an observer +# encounters an error. This may be useful to determine if the observer +# malfunctioning. The default is True. enable_inotify_warnings: True +# *** DEPRECATED - SEE "enable_observer_warnings" *** # When set to True Moonraker will generate warnings when inotify attempts # to add a duplicate watch or when inotify encounters an error. On some # file systems inotify may not work as expected, this gives users the diff --git a/docs/web_api.md b/docs/web_api.md index 16903d0..bff4344 100644 --- a/docs/web_api.md +++ b/docs/web_api.md @@ -1766,7 +1766,7 @@ A list of objects, where each object contains file data: ] ``` -#### Get gcode metadata +#### Get GCode Metadata Get metadata for a specified gcode file. @@ -1834,12 +1834,46 @@ modified time, and size. "filename": "3DBenchy_0.15mm_PLA_MK3S_2h6m.gcode" } ``` -!!! note +!!! Note The `print_start_time` and `job_id` fields are initialized to `null`. They will be updated for each print job if the user has the `[history]` component configured -#### Get Gcode Thumbnails +#### Scan GCode Metadata + +Initiate a metadata scan for a selected file. If the file has already +been scanned the endpoint will force a rescan + +HTTP request: +```http +GET /server/files/metascan?filename={filename} +``` + +JSON-RPC request: +```json +{ + "jsonrpc": "2.0", + "method": "server.files.metascan", + "params": { + "filename": "{filename}" + }, + "id": 3545 +} +``` + +Parameters: + +- `filename`: Path to the gcode file, relative to the `gcodes` root. + For example, if the file is located at + `http://host/server/files/gcodes/tools/drill_head.gcode`, + the `filename` should be specified as `tools/drill_head.gcode` + +Returns: + +- An object containing the metadata resulting from the scan, matching + the return value of the [Get Metdata Endpoint](#get-gcode-metadata). + +#### Get GCode Thumbnails Returns thumbnail information for a supplied gcode file. If no thumbnail information is available @@ -2012,7 +2046,11 @@ Returns: Information about the created directory { "item": { "path": "my_new_dir", - "root": "gcodes" + "root": "gcodes", + "modified": 1676983427.3732708, + "size": 4096, + "permissions": "rw" + }, "action": "create_dir" } @@ -2046,7 +2084,11 @@ Returns: Information about the deleted directory { "item": { "path": "my_subdir", - "root": "gcodes" + "root": "gcodes", + "modified": 0, + "size": 0, + "permissions": "" + }, "action": "delete_dir" } @@ -2068,7 +2110,9 @@ and `config`". This API may also be used to rename a file or directory. Be aware that an attempt to rename a directory to a directory that already exists will result -in *moving* the source directory into the destination directory. +in *moving* the source directory into the destination directory. Also be aware +that renaming a file to a file that already exists will result in overwriting +the existing file. HTTP request: ```http @@ -2093,17 +2137,26 @@ Returns: Information about the moved file or directory "result": { "item": { "root": "gcodes", - "path": "subdir/my_file.gcode" + "path": "subdir/my_file.gcode", + "modified": 1676940082.8595376, + "size": 384096, + "permissions": "rw" }, "source_item": { "path": "testdir/my_file.gcode", "root": "gcodes" }, - "action": "move_dir" + "action": "move_file" } } ``` +!!! Note + The `item` field contains file info for the destination. The `source_item` + contains the `path` and `root` the item was moved from. The `action` field + will be `move_file` if the source is a file or `move_dir` if the source is + a directory. + #### Copy a file or directory Copies a file or directory from one location to another. A successful copy has the prerequisites as a move with one exception, a copy may complete if the @@ -2132,12 +2185,20 @@ Returns: Information about the copied file or directory { "item": { "root": "gcodes", - "path": "subdir/my_file.gcode" + "path": "subdir/my_file.gcode", + "modified": 1676940082.8595376, + "size": 384096, + "permissions": "rw" }, "action": "create_file" } ``` +!!! Note + The `item` field contains file info for the destination. The `action` field + will be `create_file` if a new file was created, `modify_file` if an exiting + file was overwitten, or `create_dir` if an entire directory was copied. + #### Create a ZIP archive Creates a `zip` file consisting of one or more files. @@ -2199,7 +2260,10 @@ Returns: An object in the following format: { "destination": { "root": "config", - "path": "errorlogs.zip" + "path": "errorlogs.zip", + "modified": 1676984423.8892415, + "size": 420, + "permissions": "rw" }, "action": "zip_files" } @@ -2272,9 +2336,13 @@ is only included when the supplied root is set to `gcodes`. { "item": { "path": "Lock Body Shim 1mm_0.2mm_FLEX_MK3S_2h30m.gcode", - "root": "gcodes" + "root": "gcodes", + "modified": 1676984527.636818, + "size": 71973, + "permissions": "rw" }, "print_started": false, + "print_queued": false, "action": "create_file" } ``` @@ -2303,13 +2371,22 @@ Returns: Information about the deleted file { "item": { "path": "Lock Body Shim 1mm_0.2mm_FLEX_MK3S_2h30m.gcode", - "root": "gcodes" + "root": "gcodes", + "size": 0, + "modified": 0, + "permissions": "" }, "action": "delete_file" } ``` #### Download klippy.log +!!! Note + Logs are now available in the `logs` root. Front ends should consider + presenting all available logs using "file manager" type of UI. That said, + If Klipper has not been configured to write logs in the `logs` root then + this endpoint is available as a fallback. + HTTP request: ```http GET /server/files/klippy.log @@ -2321,6 +2398,12 @@ Returns: The requested file #### Download moonraker.log +!!! Note + Logs are now available in the `logs` root. Front ends should consider + presenting all available logs using "file manager" type of UI. That said, + If Moonraker has not been configured to write logs in the `logs` root then + this endpoint is available as a fallback. + HTTP request: ```http GET /server/files/moonraker.log @@ -5989,22 +6072,26 @@ to alert all connected clients of the change: { "action": "{action}", "item": { - "path": "{file or directory path}", + "path": "{file or directory path relative to root}", "root": "{root}", "size": 46458, - "modified": 545465 + "modified": 545465, + "permissions": "rw" }, "source_item": { - "path": "{file or directory path}", + "path": "{file or directory path relative to root}", "root": "{root_name}" } } ] } ``` -The `source_item` field is only present for `move_item` and -`copy_item` actions. The `action` field will be set -to one of the following values: + +!!! Note + The `source_item` field is only present for `move_file` and + `move_dir` actions. + +The `action` field will be set to one of the following values: - `create_file` - `create_dir` @@ -6016,9 +6103,16 @@ to one of the following values: - `root_update` Most of the above actions are self explanatory. The `root_update` -notification is sent when a `root` folder has changed its location, -for example when a user configures a different gcode file path -in Klipper. +notification is sent when a `root` folder has changed its location. +This should be a rare event as folders are now managed in using the +data folder structure. + +Notifications are bundled where applicable. For example, when a +directory containing children is deleted a single `delete_dir` notification +is pushed. Likewise, when a directory is moved or copied, a single +`move_dir` or `create_dir` notification is pushed. Children that are +moved, copied, or deleted as a result of a parent's action will +not receive individual notifications. #### Update Manager Response The update manager will send asynchronous messages to the client during an