diff --git a/docs/api/connection.rst b/docs/api/connection.rst index 2699655a..c0bc7537 100644 --- a/docs/api/connection.rst +++ b/docs/api/connection.rst @@ -81,6 +81,8 @@ Issue a connection command for the lost acknowledgment should always be properly investigated and removed instead of depending on this "symptom solver". + Requires user rights. + **Example Connect Request** .. sourcecode:: http @@ -152,4 +154,4 @@ Issue a connection command startup. If not set no changes will be made to the current setting. :statuscode 204: No error :statuscode 400: If the selected `port` or `baudrate` for a ``connect`` command are not part of the available - options. \ No newline at end of file + options. diff --git a/docs/api/fileops.rst b/docs/api/fileops.rst index c6b6806d..e5e79dc5 100644 --- a/docs/api/fileops.rst +++ b/docs/api/fileops.rst @@ -155,6 +155,8 @@ Upload file or create folder Returns a :http:statuscode:`201` response with a ``Location`` header set to the management URL of the uploaded file and an :ref:`Upload Response ` as the body upon successful completion. + Requires user rights. + **Example for uploading a file** .. sourcecode:: http @@ -443,6 +445,8 @@ Issue a file command Upon success, a status code of :http:statuscode:`201` and a :ref:`sec-api-datamodel-files-fileabridged` in the response body will be returned. + Requires user rights. + **Example Select Request** .. sourcecode:: http @@ -592,6 +596,8 @@ Delete file Returns a :http:statuscode:`204` after successful deletion. + Requires user rights. + **Example Request** .. sourcecode:: http @@ -609,8 +615,8 @@ Delete file .. _sec-api-fileops-datamodel: -Datamodel -========= +Data model +========== .. _sec-api-fileops-datamodel-retrieveresponse: diff --git a/docs/api/index.rst b/docs/api/index.rst index f0295e0e..6347254e 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -10,12 +10,19 @@ REST API general.rst version.rst apps.rst - fileops.rst connection.rst + fileops.rst + job.rst + languages.rst + logs.rst printer.rst printerprofiles.rst - job.rst - logs.rst + settings.rst slicing.rst + system.rst + timelapse.rst + users.rst + util.rst + wizard.rst push.rst datamodel.rst diff --git a/docs/api/job.rst b/docs/api/job.rst index aae6f863..5d727228 100644 --- a/docs/api/job.rst +++ b/docs/api/job.rst @@ -54,6 +54,8 @@ Issue a job command Upon success, a status code of :http:statuscode:`204` and an empty body is returned. + Requires user rights. + **Example Start Request** .. sourcecode:: http @@ -214,8 +216,8 @@ Retrieve information about the current job .. _sec-api-job-datamodel: -Datamodel -========= +Data model +========== .. _sec-api-job-datamodel-response: diff --git a/docs/api/languages.rst b/docs/api/languages.rst new file mode 100644 index 00000000..f1aede21 --- /dev/null +++ b/docs/api/languages.rst @@ -0,0 +1,11 @@ +.. _sec-api-languages: + +********* +Languages +********* + +.. todo:: + + Needs to be documented + +.. contents:: diff --git a/docs/api/logs.rst b/docs/api/logs.rst index 87542784..ee1c1956 100644 --- a/docs/api/logs.rst +++ b/docs/api/logs.rst @@ -97,8 +97,8 @@ Delete a specific logfile .. _sec-api-logs-datamodel: -Datamodel -========= +Data model +========== .. _sec-api-logs-datamodel-retrieveresponse: diff --git a/docs/api/printer.rst b/docs/api/printer.rst index f514a414..200f4210 100644 --- a/docs/api/printer.rst +++ b/docs/api/printer.rst @@ -232,6 +232,8 @@ Issue a print head command Upon success, a status code of :http:statuscode:`204` and an empty body is returned. + Requires user rights. + **Example Jog Request** Jog the print head by 10mm in X, -5mm in Y and 0.02mm in Z. @@ -347,6 +349,8 @@ Issue a tool command Upon success, a status code of :http:statuscode:`204` and an empty body is returned. + Requires user rights. + **Example Target Temperature Request** Set the target temperature for the printer's first hotend to 220°C and the printer's second extruder to 205°C. @@ -590,6 +594,8 @@ Issue a bed command If no heated bed is configured for the currently selected printer profile, the resource will return an :http:statuscode:`409`. + Requires user rights. + **Example Target Temperature Request** Set the target temperature for the printer's heated bed to 75°C. @@ -739,6 +745,8 @@ Issue an SD command Upon success, a status code of :http:statuscode:`204` and an empty body is returned. + Requires user rights. + **Example Init Request** Initialize the SD card. @@ -851,6 +859,8 @@ Send an arbitrary command to the printer If successful returns a :http:statuscode:`204` and an empty body. + Requires user rights. + **Example for sending a single command** .. sourcecode:: http @@ -894,8 +904,8 @@ Send an arbitrary command to the printer .. _sec-api-printer-datamodel: -Datamodel -========= +Data model +========== .. _sec-api-printer-datamodel-fullstate: diff --git a/docs/api/printerprofiles.rst b/docs/api/printerprofiles.rst index 63cd369f..8a18713a 100644 --- a/docs/api/printerprofiles.rst +++ b/docs/api/printerprofiles.rst @@ -139,6 +139,8 @@ Add a new printer profile Returns a :http:statuscode:`200` with the saved profile as property ``profile`` in the JSON body upon success. + Requires admin rights. + **Example 1** Creating a new profile ``some_profile`` based on the current default profile. @@ -306,6 +308,8 @@ Update an existing printer profile Returns a :http:statuscode:`200` with the saved profile as property ``profile`` in the JSON body upon success. + Requires admin rights. + **Example** .. sourcecode:: http @@ -389,6 +393,8 @@ Remove an existing printer profile Returns a :http:statuscode:`204` an empty body upon success. + Requires admin rights. + **Example** .. sourcecode:: http @@ -404,8 +410,8 @@ Remove an existing printer profile .. _sec-api-printerprofiles-datamodel: -Datamodel -========= +Data model +========== .. _sec-api-printerprofiles-datamodel-profilelist: diff --git a/docs/api/push.rst b/docs/api/push.rst index f8f93409..7d881386 100644 --- a/docs/api/push.rst +++ b/docs/api/push.rst @@ -67,8 +67,8 @@ Example for a ``throttle`` client-server-message: .. _sec-api-push-datamodel: -Datamodel -========= +Data model +========== .. _sec-api-push-datamodel-connected: diff --git a/docs/api/settings.rst b/docs/api/settings.rst new file mode 100644 index 00000000..265572d0 --- /dev/null +++ b/docs/api/settings.rst @@ -0,0 +1,237 @@ +.. _sec-api-settings: + +******** +Settings +******** + +.. contents:: + +.. _sec-api-settings-retrieve: + +Retrieve current settings +========================= + +.. http:get:: /api/settings + + Retrieves the current configuration of OctoPrint. + + Returns a :http:statuscode:`200` with the current settings as a JSON object in the + response body. + + The :ref:`data model ` is similar to what can be found in + :ref:`config.yaml `, see below for details. + +.. _sec-api-settings-save: + +Save settings +============= + +.. http:post:: /api/settings + + Saves the provided settings in OctoPrint. + + Expects a JSON object with the settings to change as request body. This can be either a + full settings tree, or only a partial tree containing only those fields that should + be updated. + + Returns the currently active settings on success, as part of a :http:statuscode:`200` response. + + Requires admin rights. + + **Example** + + Only change the UI color to black. + + .. sourcecode:: http + + POST /api/settings HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + Content-Type: application/json + + { + "appearance": { + "color": "black" + } + } + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "api": { + "enabled": true, + // ... + }, + // ... + } + +.. _sec-api-settings-datamodel: + +Data model +========== + +The data model on the settings API mostly reflects the contents of +:ref:`config.yaml `. The settings tree +returned by the API contains the following fields, which are directly +mapped from the same fields in ``config.yaml`` unless otherwise noted: + +.. list-table:: + :header-rows: 1 + + * - Field + - Notes + * - ``api.enabled`` + - + * - ``api.key`` + - Only maps to ``api.key`` in ``config.yaml`` if request is sent with admin rights, set to ``n/a`` otherwise. + * - ``api.allowCrossOrigin`` + - + * - ``appearance.name`` + - + * - ``appearance.color`` + - + * - ``appearance.colorTransparent`` + - + * - ``appearance.defaultLanguage`` + - + * - ``appearance.showFahrenheitAlso`` + - + * - ``feature.gcodeViewer`` + - Maps to ``gcodeViewer.enabled`` in ``config.yaml`` + * - ``feature.sizeThreshold`` + - Maps to ``gcodeViewer.sizeThreshold`` in ``config.yaml`` + * - ``feature.mobileSizeThreshold`` + - Maps to ``gcodeViewer.mobileSizeThreshold`` in ``config.yaml`` + * - ``feature.temperatureGraph`` + - + * - ``feature.waitForStart`` + - + * - ``feature.alwaysSendChecksum`` + - + * - ``feature.neverSendChecksum`` + - + * - ``feature.sdSupport`` + - + * - ``feature.sdReleativePath`` + - + * - ``feature.sdAlwaysAvailable`` + - + * - ``feature.swallowOkAfterResend`` + - + * - ``feature.repetierTargetTemp`` + - + * - ``feature.externalHeatupDetection`` + - + * - ``feature.keyboardControl`` + - + * - ``feature.pollWatched`` + - + * - ``feature.ignoreIdenticalResends`` + - + * - ``feature.modelSizeDetection`` + - + * - ``folder.uploads`` + - + * - ``folder.timelapse`` + - + * - ``folder.timelapseTmp`` + - Maps to ``folder.timelapse_tmp`` in ``config.yaml`` + * - ``folder.logs`` + - + * - ``folder.watched`` + - + * - ``plugins`` + - Plugin settings as available from ``config.yaml`` and :class:`~octoprint.plugin.SettingsPlugin` implementations + * - ``printer.defaultExtrusionLength`` + - Maps to ``printerParameters.defaultExtrusionLength`` in ``config.yaml`` + * - ``scripts.gcode`` + - Whole subtree of configured :ref:`GCODE scripts ` + * - ``serial.port`` + - Current serial port + * - ``serial.baudrate`` + - Current serial baudrate + * - ``serial.portOptions`` + - Available serial ports + * - ``serial.baudrateOptions`` + - Available serial baudrates + * - ``serial.autoconnect`` + - + * - ``serial.timeoutConnection`` + - Maps to ``serial.timeout.connection`` in ``config.yaml`` + * - ``serial.timeoutDetection`` + - Maps to ``serial.timeout.detection`` in ``config.yaml`` + * - ``serial.timeoutCommunication`` + - Maps to ``serial.timeout.communication`` in ``config.yaml`` + * - ``serial.timeoutTemperature`` + - Maps to ``serial.timeout.temperature`` in ``config.yaml`` + * - ``serial.timeoutTemperatureTargetSet`` + - Maps to ``serial.timeout.temperatureTargetSet`` in ``config.yaml`` + * - ``serial.timeoutSdStatus`` + - Maps to ``serial.timeout.sdStatus`` in ``config.yaml`` + * - ``serial.log`` + - + * - ``serial.additionalPorts`` + - + * - ``serial.additionalBaudrates`` + - + * - ``serial.longRunningCommands`` + - + * - ``serial.checksumRequiringCommands`` + - + * - ``serial.helloCommand`` + - + * - ``serial.ignoreErrorsFromFirmware`` + - + * - ``serial.disconnectOnErrors`` + - + * - ``serial.triggerOkForM29`` + - + * - ``serial.supportResendsWIthoutOk`` + - + * - ``serial.maxTimeoutsIdle`` + - Maps to ``serial.maxCommunicationTimeouts.idle`` in ``config.yaml`` + * - ``serial.maxTimeoutsPrinting`` + - Maps to ``serial.maxCommunicationTimeouts.printing`` in ``config.yaml`` + * - ``serial.maxTimeoutsLong`` + - Maps to ``serial.maxCommunicationTimeouts.long`` in ``config.yaml`` + * - ``server.commands.systemShutdownCommand`` + - + * - ``server.commands.systemRestartCommand`` + - + * - ``server.commands.serverRestartCommand`` + - + * - ``server.diskspace.warning`` + - + * - ``server.diskspace.critical`` + - + * - ``system.actions`` + - Whole subtree taken from ``config.yaml`` + * - ``system.events`` + - Whole subtree taken from ``config.yaml`` + * - ``temperature.profiles`` + - Whole subtree taken from ``config.yaml`` + * - ``temperature.cutoff`` + - + * - ``terminalFilters`` + - Whole subtree taken from ``config.yaml`` + * - ``webcam.streamUrl`` + - Maps to ``webcam.stream`` in ``config.yaml`` + * - ``webcam.snapshotUrl`` + - Maps to ``webcam.snapshot`` in ``config.yaml`` + * - ``webcam.ffmpegPath`` + - Maps to ``webcam.ffmpeg`` in ``config.yaml`` + * - ``webcam.bitrate`` + - + * - ``webcam.ffmpegThreads`` + - + * - ``webcam.watermark`` + - + * - ``webcam.flipH`` + - + * - ``webcam.flipV`` + - + * - ``webcam.rotate90`` + - diff --git a/docs/api/slicing.rst b/docs/api/slicing.rst index 5a56b960..ff3b1fc9 100644 --- a/docs/api/slicing.rst +++ b/docs/api/slicing.rst @@ -172,6 +172,8 @@ Add Slicing Profile Returns a :http:statuscode:`201` and an :ref:`abridged Profile ` in the body upon successful completion. + Requires admin rights. + **Example** .. sourcecode:: http @@ -218,6 +220,8 @@ Delete Slicing Profile Delete the slicing profile identified by ``key`` for the slicer ``slicer``. If the profile doesn't exist, the request will succeed anyway. + Requires admin rights. + :param slicer: The identifying key of the slicer for which to delete the profile :param key: The identifying key of the profile to delete :statuscode 204: No error @@ -225,8 +229,8 @@ Delete Slicing Profile .. _sec-api-slicing-datamodel: -Datamodel -========= +Data model +========== .. _sec-api-slicing-datamodel-slicerlist: diff --git a/docs/api/system.rst b/docs/api/system.rst new file mode 100644 index 00000000..78ea128f --- /dev/null +++ b/docs/api/system.rst @@ -0,0 +1,242 @@ +.. _sec-api-system: + +****** +System +****** + +.. note:: + + All system operations require admin rights. + +.. _sec-api-system-command-list: + +List all registered system commands +=================================== + +.. http:get:: /api/system/commands + + Retrieves all configured system commands. + + A :http:statuscode:`200` with a :ref:`List all response ` + will be returned. + + **Example** + + .. sourcecode:: http + + GET /api/system/commands/core HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + + .. sourcecode:: http + + HTTP/1.1 200 Ok + Content-Type: application/json + + { + "core": [ + { + "action": "shutdown", + "name": "Shutdown", + "command": "sudo shutdown -h now", + "confirm": "You are about to shutdown the system.", + "async": true, + "ignore": true, + "source": "core", + "resource": "http://example.com/api/system/commands/core/shutdown" + }, + { + "action": "reboot", + "name": "Reboot", + "command": "sudo reboot", + "confirm": "You are about to reboot the system.", + "async": true, + "ignore": true, + "source": "core", + "resource": "http://example.com/api/system/commands/core/reboot" + }, + { + "action": "restart", + "name": "Restart OctoPrint", + "command": "sudo service octoprint restart", + "confirm": "You are about to restart the OctoPrint server.", + "async": true, + "ignore": true, + "source": "core", + "resource": "http://example.com/api/system/commands/core/restart" + } + ], + "custom": [] + } + + :statuscode 200: No error + +.. _sec-api-system-command-listsource: + +List all registered system commands for a source +================================================ + +.. http:get:: /api/system/commands/(string:source) + + Retrieves the configured system commands for the specified source. + + The response will contain a list of :ref:`command definitions `. + + **Example** + + .. sourcecode:: http + + GET /api/system/commands/core HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + + .. sourcecode:: http + + HTTP/1.1 200 Ok + Content-Type: application/json + + [ + { + "action": "shutdown", + "name": "Shutdown", + "command": "sudo shutdown -h now", + "confirm": "You are about to shutdown the system.", + "async": true, + "ignore": true, + "source": "core", + "resource": "http://example.com/api/system/commands/core/shutdown" + }, + { + "action": "reboot", + "name": "Reboot", + "command": "sudo reboot", + "confirm": "You are about to reboot the system.", + "async": true, + "ignore": true, + "source": "core", + "resource": "http://example.com/api/system/commands/core/reboot" + }, + { + "action": "restart", + "name": "Restart OctoPrint", + "command": "sudo service octoprint restart", + "confirm": "You are about to restart the OctoPrint server.", + "async": true, + "ignore": true, + "source": "core", + "resource": "http://example.com/api/system/commands/core/restart" + } + ] + + :param source: The source for which to list commands, currently either ``core`` or ``custom`` + :statuscode 200: No error + :statuscode 404: If a ``source`` other than ``core`` or ``custom`` is specified. + +.. _sec-api-system-command-execute: + +Execute a registered system command +=================================== + +.. http:post:: /api/system/commands/(string:source)/(string:action) + + Execute the system command ``action`` on defined in ``source``. + + **Example** + + Restart OctoPrint via the core system command ``restart`` (which is available if the server + restart command is configured). + + .. sourcecode:: http + + POST /api/system/commands/core/restart HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + + .. sourcecode:: http + + 204 No Content + + :param source: The source for which to list commands, currently either ``core`` or ``custom`` + :param action: The identifier of the command, ``action`` from its definition + :statuscode 204: No error + :statuscode 400: If a ``divider`` is supposed to be executed or if the request is malformed otherwise + :statuscode 404: If the command could not be found for ``source`` and ``action`` + :statuscode 500: If the command didn't define a ``command`` to execute, the command returned a non-zero + return code and ``ignore`` was not ``true`` or some other internal server error occurred + +.. _sec-api-system-datamodel: + +Data model +========== + +.. _sec-api-system-commands-listall: + +List all response +----------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``core`` + - 0..n + - List of :ref:`command definitions ` + - List of all core commands defined. + * - ``custom`` + - 0..n + - List of :ref:`command definitions ` + - List of all custom commands defined in ``config.yaml``. + +.. _sec-api-system-commands-definiton: + +Command definition +------------------ + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``name`` + - 1 + - string + - The name of the command to display in the System menu. + * - ``command`` + - 1 + - string + - The full command line to execute for the command. + * - ``action`` + - 1 + - string + - An identifier to refer to the command programmatically. The special ``action`` string + ``divider`` signifies a divider in the menu. + * - ``confirm`` + - 0..1 + - string + - If present and set, this text will be displayed to the user in a confirmation dialog + they have to acknowledge in order to really execute the command. + * - ``async`` + - 0..1 + - bool + - Whether to execute the command asynchronously or wait for its result before responding + to the HTTP execution request. + * - ``ignore`` + - 0..1 + - bool + - Whether to ignore the return code of the command's execution. + * - ``source`` + - 1 + - string + - Source of the command definition, currently either ``core`` (for system actions defined by + OctoPrint itself) or ``custom`` (for custom system commands defined by the user through ``config.yaml``). + * - ``resource`` + - 1 + - string + - The URL of the command to use for executing it. diff --git a/docs/api/timelapse.rst b/docs/api/timelapse.rst new file mode 100644 index 00000000..ea9d5f36 --- /dev/null +++ b/docs/api/timelapse.rst @@ -0,0 +1,242 @@ +.. _sec-api-timelapse: + +********* +Timelapse +********* + +.. contents:: + +.. _sec-api-timelapse-list: + +Retrieve a list of timelapses and the current config +==================================================== + +.. http:get:: /api/timelapse + +.. _sec-api-timelapse-delete: + +Delete a timelapse +================== + +.. http:delete:: /api/timelapse/(string:filename) + + Delete the timelapse ``filename``. + + Requires user rights. + +.. _sec-api-timelapse-render: + +Issue a command for an unrendered timelapse +=========================================== + +.. http:post:: /api/timelapse/unrendered/(string:name) + + Current only supports to render the unrendered timelapse ``name`` via the + ``render`` command. + + Requires user rights. + +.. _sec-api-timelapse-delete-unrendered: + +Delete an unrendered timelapse +============================== + +.. http:delete:: /api/timelapse/unrendered/(string:name) + + Delete the unrendered timelapse ``name``. + + Requires user rights. + +.. _sec-api-timelapse-saveconfig: + +Change current timelapse config +=============================== + +.. http:post:: /api/timelapse + + Save a new :ref:`timelapse configuration ` to use for the next print. + +.. _sec-api-timelapse-datamodel: + +Data model +========== + +.. _sec-api-timelapse-datamodel-list: + +Timelapse list +-------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``config`` + - 1 + - :ref:`Timelapse config ` + - Current timelapse configuration + * - ``files`` + - 0..* + - List of :ref:`rendered timelapses ` + - List of rendered timelapse entries + * - ``unrendered`` + - 0..* + - List of :ref:`unrendered timelapses ` + - List of unrendered timelapse entries, only present if requested + +.. _sec-api-timelapse-datamodel-rendered: + +Rendered timelapse +------------------ + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``name`` + - 1 + - string + - Name of the timelapse file + * - ``size`` + - 1 + - string + - Formatted size of the timelapse file + * - ``bytes`` + - 1 + - int + - Size of the timelapse file in bytes + * - ``date`` + - 1 + - string + - Formatted timestamp of the the timelapse creation date + * - ``url`` + - 1 + - string + - URL for downloading the timelapse + +.. _sec-api-timelapse-datamodel-unrendered: + +Unrendered timelapse +-------------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``name`` + - 1 + - string + - Name of the unrendered timelapse job + * - ``size`` + - 1 + - string + - Formatted size of all files in the unrendered timelapse job + * - ``bytes`` + - 1 + - int + - Size of all files in the unrendered timelapse job in bytes + * - ``date`` + - 1 + - string + - Formatted timestamp of the the timelapse job creation date + * - ``recording`` + - 1 + - bool + - Whether the timelapse is still being recorded (true) or not (false) + * - ``rendering`` + - 1 + - bool + - Whether the timelapse is still being rendered (true) or not (false) + * - ``processing`` + - 1 + - bool + - Whether the timelapse is either still being recorded or rendered (true) or not (false) + + +.. _sec-api-timelapse-datamodel-config: + +Timelapse configuration +----------------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``type`` + - 1 + - string + - Type of the timelapse, either ``off``, ``zchange`` or ``timed``. + +Further fields are timelapse type specific, see below for details. + +.. _sec-api-timelapse-datamodel-config-off: + +Z-change-triggered timelapse +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For timelapse type ``zchange``. + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``postRoll`` + - 1 + - int + - Configured post roll in seconds + * - ``fps`` + - 1 + - int + - Frames per second to use for rendered video + * - ``retractionZHop`` + - 1 + - float + - Size of retraction Z hop to detect and ignore for z-based snapshots + +.. _sec-api-timelapse-datamodel-config-timed: + +Time triggered timelapse +~~~~~~~~~~~~~~~~~~~~~~~~ + +For timelapse type ``timed``. + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``postRoll`` + - 1 + - int + - Configured post roll in seconds + * - ``fps`` + - 1 + - int + - Frames per second to use for rendered video + * - ``interval`` + - 1 + - int + - Seconds between individual shots + diff --git a/docs/api/users.rst b/docs/api/users.rst new file mode 100644 index 00000000..d1809258 --- /dev/null +++ b/docs/api/users.rst @@ -0,0 +1,11 @@ +.. _sec-api-user: + +**** +User +**** + +.. todo:: + + Needs to be documented + +.. contents:: diff --git a/docs/api/util.rst b/docs/api/util.rst new file mode 100644 index 00000000..6654d5e2 --- /dev/null +++ b/docs/api/util.rst @@ -0,0 +1,295 @@ +.. _sec-api-util: + +**** +Util +**** + +.. _sec-api-util-test: + +Test paths or URLs +================== + +.. http:post:: /api/util/test + + Provides commands to test paths or URLs for correctness. + + Used by OctoPrint to validate paths or URLs that the user needs to enter in the + settings. + + The following commands are supported at the moment: + + .. _sec-api-util-test-path: + path + Tests whether or provided path exists and optionally if it also is either a file + or a directory and whether OctoPrint's user has read, write and/or execute permissions + on it. Supported parameters are: + + * ``path``: The file system path to test. Mandatory. + * ``check_type``: ``file`` or ``dir`` if the path should not only be checked for + existence but also whether it is of the specified type. Optional. + * ``check_access``: A list of any of ``r``, ``w`` and ``x``. If present it will also + be checked if OctoPrint has read, write, execute permissions on the specified path. + + The ``path`` command returns a :http:statuscode:`200` with a :ref:`path test result ` + when the test could be performed. The status code of the response does NOT reflect the + test result! + + .. _sec-api-util-test-url: + url + Tests whether a provided url responds. Request method and expected status codes can + optionally be specified as well. Supported parameters are: + + * ``url``: The url to test. Mandatory. + * ``method``: The request method to use for the test. Optional, defaults to ``HEAD``. + * ``timeout``: A timeout for the request, in seconds. If no reply from the tested URL has been + received within this time frame, the check will be considered a failure. Optional, defaults to 3 seconds. + * ``status``: The status code(s) or named status range(s) to test for. Can be either a single + value or a list of either HTTP status codes or any of the following named status ranges: + + * ``informational``: Status codes from 100 to 199 + * ``success``: Status codes from 200 to 299 + * ``redirection``: Status codes from 300 to 399 + * ``client_error``: Status codes from 400 to 499 + * ``server_error``: Status codes from 500 to 599 + * ``normal``: Status codes from 100 to 399 + * ``error``: Status codes from 400 to 599 + * ``any``: Any status code starting from 100 + + The test will past the status code check if the status returned by the URL is within any of + the specified ranges. + * ``response``: If set to either ``true``, ``json`` or ``bytes``, the response body and the response headers + from the URL check will be returned as part of the check result as well. ``json`` will attempt + to parse the response as json and return the parsed result. ``true`` or ``bytes`` will base64 encode the body + and return that. + + The ``url`` command returns :http:statuscode:`200` with a :ref:`URL test result ` + when the test could be performed. The status code of the response does NOT reflect the + test result! + + Requires admin rights. + + **Example 1** + + Test whether a path exists and is a file readable and executable by OctoPrint. + + .. sourcecode:: http + + POST /api/util/test HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + Content-Type: application/json + + { + "command": "path", + "path": "/some/path/to/a/file", + "check_type": "file", + "check_access": ["r", "x"] + } + + .. sourcecode:: HTTP + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "path": "/some/path/to/a/file", + "exists": true, + "typeok": true, + "access": true, + "result": true + } + + **Example 2** + + Test whether a path exists which doesn't exist. + + .. sourcecode:: http + + POST /api/util/test HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + Content-Type: application/json + + { + "command": "path", + "path": "/some/path/to/a/missing_file", + "check_type": "file", + "check_access": ["r", "x"] + } + + .. sourcecode:: HTTP + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "path": "/some/path/to/a/missing_file", + "exists": false, + "typeok": false, + "access": false, + "result": false + } + + **Example 3** + + Test whether a path exists and is a file which is a directory. + + .. sourcecode:: http + + POST /api/util/test HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + Content-Type: application/json + + { + "command": "path", + "path": "/some/path/to/a/folder", + "check_type": "file" + } + + .. sourcecode:: HTTP + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "path": "/some/path/to/a/folder", + "exists": true, + "typeok": false, + "access": true, + "result": false + } + + **Example 4** + + Test whether a URL returns a normal status code for a HEAD request. + + .. sourcecode:: http + + POST /api/util/test HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + Content-Type: application/json + + { + "command": "url", + "url": "http://example.com/some/url" + } + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "url": "http://example.com/some/url", + "status": 200, + "result": true + } + + **Example 5** + + Test whether a URL can be called at all via GET request, provide its raw body. Set a timeout of 1s. + + .. sourcecode:: http + + POST /api/util/test HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + Content-Type: application/json + + { + "command": "url", + "url": "http://example.com/some/url", + "method": "GET", + "timeout": 1.0, + "status": "any", + "response": true + } + + .. sourcecode:: HTTP + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "url": "http://example.com/some/url", + "status": 200, + "result": true, + "response": { + "headers": { + "content-type": "image/gif" + }, + "content": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" + } + } + +.. _sec-api-util-datamodel: + +Data model +========== + +.. _sec-api-util-datamodel-pathtestresult: + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``path`` + - 1 + - string + - The path that was tested. + * - ``exists`` + - 1 + - bool + - ``true`` if the path exists, ``false`` otherwise. + * - ``typeok`` + - 1 + - bool + - ``true`` if a type check was not requested or it passed, ``false`` otherwise + * - ``access`` + - 1 + - bool + - ``true`` if a permission check was not requested or it passed, ``false`` otherwise + * - ``result`` + - 1 + - bool + - ``true`` if the overall check passed, ``false`` otherwise + +.. _sec-api-util-datamodel-urltestresult: + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``url`` + - 1 + - string + - The URL that was tested. + * - ``status`` + - 1 + - int + - The status code returned by the URL, 0 in case of a timeout. + * - ``result`` + - 1 + - bool + - ``true`` if the check passed. + * - ``response`` + - 0..1 + - string or object + - If ``response`` in the request was set to ``bytes``: The base64 encoded body of the checked URL's response. + If ``response`` in the request was set to ``json``: The json decoded body of the checked URL's response. + Not present if ``response`` in the request was not set. + * - ``headers`` + - 0..1 + - object + - A dictionary with all headers of the checked URL's response. Only present if ``response`` in the + request was set. diff --git a/docs/api/wizard.rst b/docs/api/wizard.rst new file mode 100644 index 00000000..96a45f00 --- /dev/null +++ b/docs/api/wizard.rst @@ -0,0 +1,73 @@ +.. _sec-api-wizard: + +****** +Wizard +****** + +.. note:: + + All wizard operations require either admin rights or the ``firstRun`` flag to be ``true``. + +.. contents:: + +.. _sec-api-wizard-retrieve: + +Retrieve additional data about registered wizards +================================================= + +.. http:get:: /setup/wizard + + Retrieves additional data about the registered wizards. + + Returns a :http:statuscode:`200` with an object mapping wizard identifiers to :ref:`wizard data entries `. + +.. _sec-api-wizard-finish: + +Finish wizards +============== + +.. http:post:: /setup/wizard + + Inform wizards that the wizard dialog has been finished. + + Expects a JSON request body containing a property ``handled`` which holds a list of wizard identifiers + which were handled (not skipped) in the wizard dialog. + + Will call :func:`octoprint.plugin.WizardPlugin.on_wizard_finish` for all registered wizard plugins, + supplying the information whether the wizard plugin's identifier was within the list of ``handled`` + wizards or not. + +.. _sec-api-wizard-datamodel: + +Data model +========== + +.. _sec-api-wizard-datamodel-wizarddata: + +Wizard data entry +----------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``required`` + - 1 + - bool + - Whether the wizard needs to be run (true) or not (false) + * - ``details`` + - 1 + - object + - Details for the wizard's UI provided by the wizard plugin + * - ``version`` + - 1 + - int or null + - Version of the wizard + * - ``ignored`` + - 1 + - bool + - Whether the wizard has already been seen/is ignored (true) or not (false) diff --git a/docs/features/index.rst b/docs/features/index.rst index c4b1a713..4d1b9f1f 100644 --- a/docs/features/index.rst +++ b/docs/features/index.rst @@ -4,6 +4,10 @@ Features ******** +.. note:: + + This feature list is not exhaustive. This part of OctoPrint's documentation is sadly far from finished still. + .. toctree:: :maxdepth: 2 diff --git a/docs/jsclientlib/languages.rst b/docs/jsclientlib/languages.rst index dff94504..c2737589 100644 --- a/docs/jsclientlib/languages.rst +++ b/docs/jsclientlib/languages.rst @@ -7,10 +7,22 @@ Retrieves a list of available language packs. + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.languages.upload(file) Uploads a language pack. + :param object or string file: The file to upload, see :js:func:`OctoPrint.upload` for more details + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.languages.delete(locale, pack, opts) Deletes the language pack ``pack`` for the specified locale ``locale``. + + :param string locale: The locale for which to delete the language pack + :param string pack: The identifier of the pack to delete + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + diff --git a/docs/jsclientlib/printer.rst b/docs/jsclientlib/printer.rst index df55b0e4..f422e56a 100644 --- a/docs/jsclientlib/printer.rst +++ b/docs/jsclientlib/printer.rst @@ -202,7 +202,7 @@ .. code-block:: javascript - OctoPrint.printer.setToolTemperatureOffsets(-5); + OctoPrint.printer.setBedTemperatureOffset(-5); See the ``offset`` command in :ref:`Issue a bed command ` for more details. diff --git a/docs/jsclientlib/printerprofiles.rst b/docs/jsclientlib/printerprofiles.rst index 39fb04ec..fe0e11a1 100644 --- a/docs/jsclientlib/printerprofiles.rst +++ b/docs/jsclientlib/printerprofiles.rst @@ -3,16 +3,46 @@ :mod:`OctoPrint.printerprofiles` -------------------------------- -.. todo:: - - Needs to be documented - .. js:function:: OctoPrint.printerprofiles.list(opts) + Retrieves a list of all configured printer profiles. + + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.printerprofiles.get(id, opts) + :param string id: The identifier of the profile to retrieve + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.printerprofiles.add(profile, additional, opts) -.. js:function:: OctoPrint.printerprofiles.update(id, profile, additional, opts) + Adds a new profile to OctoPrint. + + :param string profile: The data of the profile to add + :param string basedOn: The identifier of the profile to base this profile on (optional) + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + +.. js:function:: OctoPrint.printerprofiles.update(id, profile, opts) + + Updates an existing profile in OctoPrint. + + :param string id: The identifier of the profile to update + :param string profile: The data of the profile to update + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: OctoPrint.printerprofiles.delete(id, opts) + + Deletes a profile in OctoPrint. + + :param string id: The identifier of the profile to delete + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + +.. seealso:: + + :ref:`Printer profile operations ` + The documentation of the underlying printer profile API. diff --git a/docs/jsclientlib/settings.rst b/docs/jsclientlib/settings.rst index da9a52ec..825d43ec 100644 --- a/docs/jsclientlib/settings.rst +++ b/docs/jsclientlib/settings.rst @@ -3,14 +3,34 @@ :mod:`OctoPrint.settings` ------------------------- -.. todo:: - - Needs to be documented - .. js:function:: OctoPrint.settings.get(opts) + Retrieves the current settings. + + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.settings.save(settings, opts) + Saves the provided ``settings``. + + :param object settings: The settings to save + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.settings.getPluginSettings(plugin, opts) + Retrieves the settings of the specified ``plugin``. + + :param string plugin: The plugin for which to retrieve the settings + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.settings.savePluginSettings(plugin, settings, opts) + + Saves the ``settings`` for the specified ``plugin``. + + :param string plugin: The plugin for which to save settings + :param object settings: The settings to save + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response diff --git a/docs/jsclientlib/slicing.rst b/docs/jsclientlib/slicing.rst index bbe1bd25..9d537775 100644 --- a/docs/jsclientlib/slicing.rst +++ b/docs/jsclientlib/slicing.rst @@ -3,18 +3,58 @@ :mod:`OctoPrint.slicing` ------------------------ -.. todo:: - - Needs to be documented - .. js:function:: OctoPrint.slicing.listAllSlicersAndProfiles(opts) + Retrieves a list of all slicers and their available slicing profiles. + + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.slicing.listProfilesForSlicer(slicer, opts) + Retrieves of all slicing profiles for the specified ``slicer``. + + :param string slicer: The identifier of the slicer for which to retrieve the profiles + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.slicing.getProfileForSlicer(slicer, profileId, opts) + Retrieves the slicing profile with ``profileId`` for the specified ``slicer``. + + :param string slicer: The slicer for which to retrieve the profile + :param string profileId: The identifier of the profile to retrieve + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.slicing.addProfileForSlicer(slicer, profileId, profile, opts) + Adds the profile with identifier ``profileId`` to the specified ``slicer``, using the provided ``profile`` data. + + :param string slicer: The slicer for which to add the profile + :param string profileId: The identifier for the profile to add + :param object profile: The data of the profile to add + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.slicing.updateProfileForSlicer(slicer, profileId, profile, opts) + Updates the profile ``profileId`` for ``slicer`` with the provided ``profile`` data. + + :param string slicer: The slicer for which to update the profile + :param string profileId: The identifier for the profile to update + :param object profile: The updated data of the profile + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.slicing.deleteProfileForSlicer(slicer, profileId, opts) + + Deletes the profile ``profileId`` for ``slicer``. + + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + +.. seealso:: + + :ref:`Slicing API ` + The documentation of the underlying slicing API. diff --git a/docs/jsclientlib/system.rst b/docs/jsclientlib/system.rst index 8d3e6a78..e313e27b 100644 --- a/docs/jsclientlib/system.rst +++ b/docs/jsclientlib/system.rst @@ -3,12 +3,36 @@ :mod:`OctoPrint.system` ----------------------- -.. todo:: +.. note:: - Needs to be documented + All methods here require that the used API token or a the existing browser session + has admin rights. .. js:function:: OctoPrint.system.getCommands(opts) + Retrieves a list of configured system commands for both ``core`` and ``custom`` sources. + + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.system.getCommandsForSource(source, opts) + Retrieves a list of system commands, limiting it to the specified ``source``, which might be + either ``core`` or ``custom``. + + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + .. js:function:: OctoPrint.system.executeCommand(source, action, opts) + + Executes command ``action`` on ``source``. + + :param string source: The source of the command to execute + :param string action: The action identifier of the command to execute + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + +.. seealso:: + + :ref:`System API ` + Documentation of the underlying system API diff --git a/docs/jsclientlib/util.rst b/docs/jsclientlib/util.rst index 9f9d91b4..ecc8246c 100644 --- a/docs/jsclientlib/util.rst +++ b/docs/jsclientlib/util.rst @@ -3,14 +3,157 @@ :mod:`OctoPrint.util` --------------------- -.. todo:: +.. note:: - Needs to be documented + All methods here require that the used API token or a the existing browser session + has admin rights. -.. js:function:: OctoPrint.util.test(command, data, opts) +.. js:function:: OctoPrint.util.test(command, parameters, opts) + + Execute a :ref:`test command `. + + See below for the more specialized versions of this. + + :param string command: The command to execute (currently either ``path`` or ``url``) + :param object parameters: The parameters for the command + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: OctoPrint.util.testPath(path, additional, opts) -.. js:function:: OctoPrint.util.testExecutable(path, additional, opts) + Test the provided ``path`` for existance. More test criteria supported by the :ref:`path test command ` + can be provided via the ``additional`` object. + + **Example 1** + + Test if ``/some/path/to/a/file`` exists. + + .. code-block:: javascript + + OctoPrint.util.testPath("/som/path/to/a/file") + .done(function(response) { + if (response.result) { + // check passed + } else { + // check failed + } + }); + + **Example 2** + + Test if ``/some/path/to/a/file`` exists, is a file and OctoPrint has read and executable rights on it. + + .. code-block:: javascript + + OctoPrint.util.testPath("/som/path/to/a/file", {"check_type": "file", "check_access": ["r", "x"]}) + .done(function(response) { + if (response.result) { + // check passed + } else { + // check failed + } + }); + + :param string path: Path to test + :param object additional: Additional parameters for the test command + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + +.. js:function:: OctoPrint.util.testExecutable(path, opts) + + Shortcut to test if a provided ``path`` exists and is executable by OctoPrint. + + **Example** + + Test if ``/some/path/to/a/file`` exists and can be executed by OctoPrint. + + .. code-block:: javascript + + OctoPrint.util.testExecutable("/some/path/to/a/file") + .done(function(response) { + if (response.result) { + // check passed + } else { + // check failed + } + }); + + This is equivalent to calling :js:func:`OctoPrint.util.testPath` like this: + + .. code-block:: javascript + + OctoPrint.util.testPath("/some/path/to/a/file", {"access": "x"}) + .done(function(response) { + if (response.result) { + // check passed + } else { + // check failed + } + }); + + :param string path: Path to test + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: OctoPrint.util.testUrl(url, additional, opts) + + Test if a URL can be accessed. More test criteria supported by the :ref:`URL test command ` + can be provided via the ``additional`` object. + + **Example 1** + + Test if ``http://octopi.local/online.gif`` can be accessed and returns a non-error status code within the default timeout. + + .. code-block:: javascript + + OctoPrint.util.testUrl("http://octopi.local/online.gif") + .done(function(response) { + if (response.result) { + // check passed + } else { + // check failed + } + }); + + **Example 2** + + Test if ``http://octopi.local/webcam/?action=snapshot`` can be accessed and returns a non-error status code. Return the + raw response data and headers from the check as well. + + .. code-block:: javascript + + OctoPrint.util.testUrl("http://octopi.local/webcam/?action=snapshot", {"response": "bytes", "method": "GET"}) + .done(function(response) { + if (response.result) { + // check passed + var image = $("#someimage"); + image. + } else { + // check failed + } + }); + + **Example 3** + + Test if a "GET" request against ``http://example.com/idonotexist`` returns either a :http:statuscode:`404` or a :http:statuscode:`400`. + + .. code-block:: javascript + + OctoPrint.util.testUrl("http://example.com/idonotexist", {"status": [400, 404], "method": "GET"}) + .done(function(response) { + if (response.result) { + // check passed + } else { + // check failed + } + }); + + :param string url: URL to test + :param object additional: Additional parameters for the test command + :param object opts: Additional options for the request + :returns Promise: A `jQuery Promise `_ for the request's response + +.. seealso:: + + :ref:`Util API ` + Documentation of the underlying util API diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index e04033b0..4977b892 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -12,7 +12,6 @@ Developing Plugins mixins.rst hooks.rst helpers.rst - injectedproperties.rst viewmodels.rst gettingstarted.rst distributing.rst diff --git a/docs/plugins/injectedproperties.rst b/docs/plugins/injectedproperties.rst deleted file mode 100644 index 308b9d9e..00000000 --- a/docs/plugins/injectedproperties.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _sec-plugins-injectedproperties: - -Injected Properties -=================== - -OctoPrint's plugin subsystem will inject a bunch of properties into each :ref:`mixin implementation `. -An overview of these properties follows. - -``self._identifier`` - The plugin's identifier. -``self._plugin_name`` - The plugin's name, as taken from either the ``__plugin_name__`` control property or the package info. -``self._plugin_version`` - The plugin's version, as taken from either the ``__plugin_version__`` control property or the package info. -``self._basefolder`` - The plugin's base folder where it's installed. Can be used to refer to files relative to the plugin's installation - location, e.g. included scripts, templates or assets. -``self._datafolder`` - The plugin's additional data folder path. Can be used to store additional files needed for the plugin's operation (cache, - data files etc). Plugins should not access this property directly but instead utilize :func:`~octoprint.plugin.types.OctoPrintPlugin.get_plugin_data_folder` - which will make sure the path actually does exist and if not create it before returning it. -``self._logger`` - A `python logger instance `_ logging to the log target - ``octoprint.plugin.``. -``self._settings`` - The plugin's personalized settings manager, injected only into plugins that include the :class:`~octoprint.plugin.SettingsPlugin` mixin. - An instance of :class:`octoprint.plugin.PluginSettings`. -``self._plugin_manager`` - OctoPrint's plugin manager object, an instance of :class:`octoprint.plugin.core.PluginManager`. -``self._printer_profile_manager`` - OctoPrint's printer profile manager, an instance of :class:`octoprint.printer.profile.PrinterProfileManager`. -``self._event_bus`` - OctoPrint's event bus, an instance of :class:`octoprint.events.EventManager`. -``self._analysis_queue`` - OctoPrint's analysis queue for analyzing GCODEs or other files, an instance of :class:`octoprint.filemanager.analysis.AnalysisQueue`. -``self._slicing_manager`` - OctoPrint's slicing manager, an instance of :class:`octoprint.slicing.SlicingManager`. -``self._file_manager`` - OctoPrint's file manager, an instance of :class:`octoprint.filemanager.FileManager`. -``self._printer`` - OctoPrint's printer management object, an instance of :class:`octoprint.printer.PrinterInterface`. -``self._app_session_manager`` - OctoPrint's application session manager, an instance of :class:`octoprint.server.util.flask.AppSessionManager`. -``self._user_manager`` - OctoPrint's user manager, an instance of :class:`octoprint.users.UserManager`. - -.. seealso:: - - :class:`~octoprint.plugin.core.Plugin` and :class:`~octoprint.plugin.types.OctoPrintPlugin` - Class documentation also containing the properties shared among all mixing implementations. - - :ref:`Available Mixins ` - Some mixin types trigger the injection of additional properties. - diff --git a/src/octoprint/server/api/__init__.py b/src/octoprint/server/api/__init__.py index 41b5a060..6f6f37d5 100644 --- a/src/octoprint/server/api/__init__.py +++ b/src/octoprint/server/api/__init__.py @@ -277,14 +277,14 @@ def utilTestPath(): if check_type: typeok = type_mapping[check_type](path) else: - typeok = True + typeok = exists # check if path allows requested access access_mapping = dict(r=os.R_OK, w=os.W_OK, x=os.X_OK) if check_access: access = os.access(path, reduce(lambda x, y: x | y, map(lambda a: access_mapping[a], check_access))) else: - access = True + access = exists return jsonify(path=path, exists=exists, typeok=typeok, access=access, result=exists and typeok and access) @@ -319,18 +319,23 @@ def utilTestPath(): success=StatusCodeRange(start=200,end=300), redirection=StatusCodeRange(start=300,end=400), client_error=StatusCodeRange(start=400,end=500), - server_error=StatusCodeRange(start=500), + server_error=StatusCodeRange(start=500,end=600), normal=StatusCodeRange(end=400), - error=StatusCodeRange(start=400), - any=StatusCodeRange(start=100) + error=StatusCodeRange(start=400,end=600), + any=StatusCodeRange(start=100), + timeout=StatusCodeRange(start=0, end=1) ) url = data["url"] - method = "HEAD" + method = data.get("method", "HEAD") + timeout = 3.0 check_status = [status_ranges["normal"]] - if "method" in data: - method = data["method"] + if "timeout" in data: + try: + timeout = float(data["timeout"]) + except: + return make_response("{!r} is not a valid value for timeout (must be int or float)".format(data["timeout"])) if "status" in data: request_status = data["status"] @@ -339,23 +344,26 @@ def utilTestPath(): check_status = [] for rs in request_status: - if rs in status_ranges: - check_status.append(status_ranges[rs]) + if isinstance(rs, int): + check_status.append([rs]) else: - code = requests.codes[rs] - if code is not None: - check_status.append([code]) + if rs in status_ranges: + check_status.append(status_ranges[rs]) + else: + code = requests.codes[rs] + if code is not None: + check_status.append([code]) try: - response = requests.request(method=method, url=url) - status = reduce(lambda x, y: x and response.status_code in y, check_status) + response = requests.request(method=method, url=url, timeout=timeout) + status = response.status_code except: - status = False + status = 0 result = dict( url=url, - status=response.status_code, - result=status.as_dict() if isinstance(status, StatusCodeRange) else status + status=status, + result=any(map(lambda x: status in x, check_status)) ) if "response" in data and (data["response"] in valid_boolean_trues or data["response"] in ("json", "bytes")): diff --git a/src/octoprint/server/api/settings.py b/src/octoprint/server/api/settings.py index c60e0c51..ac2c3fa6 100644 --- a/src/octoprint/server/api/settings.py +++ b/src/octoprint/server/api/settings.py @@ -48,6 +48,9 @@ def getSettings(): connectionOptions = printer.__class__.get_connection_options() + # NOTE: Remember to adjust the docs of the data model on the Settings API if anything + # is changed, added or removed here + data = { "api": { "enabled": s.getBoolean(["api", "enabled"]), @@ -215,6 +218,9 @@ def _saveSettings(data): s = settings() + # NOTE: Remember to adjust the docs of the data model on the Settings API if anything + # is changed, added or removed here + if "api" in data.keys(): if "enabled" in data["api"].keys(): s.setBoolean(["api", "enabled"], data["api"]["enabled"]) if "key" in data["api"].keys(): s.set(["api", "key"], data["api"]["key"], True) diff --git a/src/octoprint/server/api/system.py b/src/octoprint/server/api/system.py index 95341271..8af7a24c 100644 --- a/src/octoprint/server/api/system.py +++ b/src/octoprint/server/api/system.py @@ -29,7 +29,7 @@ def performSystemAction(): data = request.json if not "action" in data: - return make_response("action for perform is not defined", 400) + return make_response("action to perform is not defined", 400) return executeSystemCommand("custom", data["action"]) @@ -51,7 +51,7 @@ def retrieveSystemCommandsForSource(source): elif source == "custom": specs = _get_custom_command_specs() else: - return make_response("Unknown system command source: {}".format(source), 400) + return make_response("Unknown system command source: {}".format(source), 404) return jsonify(_to_client_specs(specs)) diff --git a/src/octoprint/static/js/app/client/printerprofiles.js b/src/octoprint/static/js/app/client/printerprofiles.js index 181eaa5e..40623ce6 100644 --- a/src/octoprint/static/js/app/client/printerprofiles.js +++ b/src/octoprint/static/js/app/client/printerprofiles.js @@ -16,12 +16,13 @@ return OctoPrint.get(url, opts); }, - add: function (profile, additional, opts) { + add: function (profile, basedOn, opts) { profile = profile || {}; - additional = additional || {}; - var data = $.extend({}, additional); - data.profile = profile; + var data = {profile: profile}; + if (basedOn) { + data.basedOn = basedOn; + } return OctoPrint.postJson(url, data, opts); }, @@ -30,12 +31,10 @@ return OctoPrint.get(profileUrl(id), opts); }, - update: function (id, profile, additional, opts) { + update: function (id, profile, opts) { profile = profile || {}; - additional = additional || {}; - var data = $.extend({}, additional); - data.profile = profile; + var data = {profile: profile}; return OctoPrint.patchJson(profileUrl(id), data, opts); }, diff --git a/src/octoprint/static/js/app/client/util.js b/src/octoprint/static/js/app/client/util.js index b06259fc..4c0845f0 100644 --- a/src/octoprint/static/js/app/client/util.js +++ b/src/octoprint/static/js/app/client/util.js @@ -8,8 +8,8 @@ var url = "api/util"; var testUrl = url + "/test"; - var test = function(command, data, opts) { - return OctoPrint.issueCommand(testUrl, command, data, opts); + var test = function(command, parameters, opts) { + return OctoPrint.issueCommand(testUrl, command, parameters, opts); }; OctoPrint.util = { diff --git a/src/octoprint/static/js/app/viewmodels/settings.js b/src/octoprint/static/js/app/viewmodels/settings.js index a1be680a..96381f30 100644 --- a/src/octoprint/static/js/app/viewmodels/settings.js +++ b/src/octoprint/static/js/app/viewmodels/settings.js @@ -244,7 +244,7 @@ $(function() { var errorText = gettext("Could not retrieve snapshot URL, please double check the URL"); var errorTitle = gettext("Snapshot test failed"); - OctoPrint.util.testUrl(self.webcam_snapshotUrl(), {method: "GET", response: true}) + OctoPrint.util.testUrl(self.webcam_snapshotUrl(), {method: "GET", response: "bytes"}) .done(function(response) { $("i.icon-spinner", target).remove(); @@ -260,8 +260,8 @@ $(function() { var mimeType = "image/jpeg"; var headers = response.response.headers; - if (headers && headers["mime-type"]) { - mimeType = headers["mime-type"]; + if (headers && headers["content-type"]) { + mimeType = headers["content-type"].split(";")[0]; } var text = gettext("If you see your webcam snapshot picture below, the entered snapshot URL is ok.");