diff --git a/docs/api/connection.rst b/docs/api/connection.rst index c4526b75..2f90fae3 100644 --- a/docs/api/connection.rst +++ b/docs/api/connection.rst @@ -4,8 +4,7 @@ Connection handling ******************* -.. toctree:: - :maxdepth: 2 +.. contents:: .. _sec-api-connection-current: diff --git a/docs/api/fileops.rst b/docs/api/fileops.rst index 0303e7fd..c782c4c0 100644 --- a/docs/api/fileops.rst +++ b/docs/api/fileops.rst @@ -4,8 +4,7 @@ File operations *************** -.. toctree:: - :maxdepth: 5 +.. contents:: .. _sec-api-fileops-retrieveall: @@ -25,7 +24,6 @@ Retrieve all files GET /api/files HTTP/1.1 Host: example.com - X-Api-Key: abcdef... **Example response**: @@ -39,9 +37,13 @@ Retrieve all files { "name": "whistle_v2.gcode", "bytes": 1468987, - "size": "1.4MB" + "size": "1.4MB", "date": "2013-05-21 23:15", "origin": "local", + "refs": { + "resource": "http://example.com/api/files/local/whistle_v2.gcode", + "download": "http://example.com/downloads/files/local/whistle_v2.gcode" + }, "gcodeAnalysis": { "estimatedPrintTime": "00:31:40", "filament": "0.79m" @@ -57,10 +59,10 @@ Retrieve all files }, { "name": "whistle_.gco", - "bytes": 0, - "size": "n/a", - "date": "n/a", - "origin": "sdcard" + "origin": "sdcard", + "refs": { + "resource": "http://example.com/api/files/sdcard/whistle_.gco" + } } ], "free": "3.2GB" @@ -68,15 +70,15 @@ Retrieve all files :statuscode 200: No error -.. _sec-api-fileops-retrievetarget: +.. _sec-api-fileops-retrievespecific: -Retrieve files from specific origin -=================================== +Retrieve files from specific location +===================================== -.. http:get:: /api/files/(string:origin) +.. http:get:: /api/files/(string:location) - Retrieve information regarding the files currently available on the selected `origin` and regarding the - disk space still available locally in the system. + Retrieve information regarding the files currently available on the selected `location` and -- if targeting + the ``local`` location -- regarding the disk space still available locally in the system. Returns a :ref:`Retrieve response `. @@ -86,7 +88,6 @@ Retrieve files from specific origin GET /api/files/local HTTP/1.1 Host: example.com - X-Api-Key: abcdef... **Example response**: @@ -103,6 +104,10 @@ Retrieve files from specific origin "size": "1.4MB" "date": "2013-05-21 23:15", "origin": "local", + "refs": { + "resource": "http://example.com/api/files/local/whistle_v2.gcode", + "download": "http://example.com/downloads/files/local/whistle_v2.gcode" + }, "gcodeAnalysis": { "estimatedPrintTime": "00:31:40", "filament": "0.79m" @@ -120,31 +125,32 @@ Retrieve files from specific origin "free": "3.2GB" } - :param origin: The origin location from which to retrieve the files. Currently only ``local`` and ``sdcard`` are - supported, with ``local`` referring to files stored in OctoPrint's ``uploads`` folder and ``sdcard`` - referring to files stored on the printer's SD card (if available). + :param location: The origin location from which to retrieve the files. Currently only ``local`` and ``sdcard`` are + supported, with ``local`` referring to files stored in OctoPrint's ``uploads`` folder and ``sdcard`` + referring to files stored on the printer's SD card (if available). :statuscode 200: No error - :statuscode 400: If `origin` is neither ``local`` nor ``sdcard`` or the request is otherwise invalid. + :statuscode 404: If `location` is neither ``local`` nor ``sdcard`` .. _sec-api-fileops-uploadfile: Upload file =========== -.. http:post:: /api/files/(string:target) +.. http:post:: /api/files/(string:location) - Upload a file to the selected `target`. + Upload a file to the selected `location`. Other than most of the other requests on OctoPrint's API which are expected as JSON, this request is expected as ``Content-Type: multipart/form-data`` due to the included file upload. - Returns an :ref:`Upload Response ` upon successful completion. + 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. **Example request** .. sourcecode:: http - POST /api/files/local HTTP/1.1 + POST /api/files/sdcard HTTP/1.1 Host: example.com X-Api-Key: abcdef... Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryDeC2E3iWbTv1PwMC @@ -182,48 +188,60 @@ Upload file HTTP/1.1 200 OK Content-Type: application/json + Location: { - "files": [ - ... - { + "files": { + "local": { "name": "whistle_v2.gcode", - "bytes": 1468987, - "size": "1.4MB" - "date": "2013-05-21 23:15", - "origin": "local" + "origin": "local", + "refs": { + "resource": "http://example.com/api/files/local/whistle_v2.gcode", + "download": "http://example.com/downloads/files/local/whistle_v2.gcode" + } }, - ... - ], - "done": true, - "filename": "whistle_v2.gcode" + "sdcard": { + "name": "whistle_.gco", + "origin": "sdcard", + "refs": { + "resource": "http://example.com/api/files/sdcard/whistle_.gco" + } + } + }, + "done": true } - :param target: The target location to which to upload the file. Currently only ``local`` and ``sdcard`` are supported - here, with ``local`` referring to OctoPrint's ``uploads`` folder and ``sdcard`` referring to - the printer's SD card. If an upload targets the SD card, it will also be stored locally first. - :form file: The file to upload, including a valid ``filename``. - :form select: Whether to select the file directly after upload (``true``) or not (``false``). Optional, defaults - to ``false``. - :form print: Whether to start printing the file directly after upload (``true``) or not (``false``). If set, `select` - is implicitely ``true`` as well. Optional, defaults to ``false``. - :statuscode 200: No error - :statuscode 400: If `target` is neither ``local`` nor ``sdcard``, no `file` is included in the request, the file is - neither a ``gcode`` nor an ``stl`` file (or it is an ``stl`` file but slicing support is - disabled) or the request is otherwise invalid. - :statuscode 403: If the upload of the file would override the file that is currently being printed + :param location: The target location to which to upload the file. Currently only ``local`` and ``sdcard`` are supported + here, with ``local`` referring to OctoPrint's ``uploads`` folder and ``sdcard`` referring to + the printer's SD card. If an upload targets the SD card, it will also be stored locally first. + :form file: The file to upload, including a valid ``filename``. + :form select: Whether to select the file directly after upload (``true``) or not (``false``). Optional, defaults + to ``false``. + :form print: Whether to start printing the file directly after upload (``true``) or not (``false``). If set, `select` + is implicitely ``true`` as well. Optional, defaults to ``false``. + :statuscode 201: No error + :statuscode 400: If no `file` is included in the request, or the request is otherwise invalid. + :statuscode 404: If `location` is neither ``local`` nor ``sdcard`` or trying to upload to SD card and SD card support + is disabled + :statuscode 409: If the upload of the file would override the file that is currently being printed or if an upload + to SD card was requested and the printer is either not operational or currently busy with a print job. + :statuscode 415: If the file is neither a ``gcode`` nor an ``stl`` file (or it is an ``stl`` file but slicing support + is disabled) :statuscode 500: If the upload failed internally -.. _sec-api-fileops-retrievefile: +.. _sec-api-fileops-retrievefileinfo: -Retrieve a file's contents -========================== +Retrieve a specific file's information +====================================== -.. http:get:: /api/files/local/(path:filename) +.. http:get:: /api/files/(string:location)/(path:filename) - Downloads the selected file's contents. Only available for locally stored files, hence no `target` parameter. + Retrieves the selected file's information. - Will actually redirect to serve the download via a static context directly from the filesystem. + If the file is unknown, a :http:statuscode:`404` is returned. + + On success, a :http:statuscode:`200` is returned, with a :ref:`file information item ` + as the response body. **Example Request** @@ -236,40 +254,38 @@ Retrieve a file's contents .. sourcecode:: http - HTTP/1.1 302 Found - Location: /downloads/files/whistle_v2.gcode + HTTP/1.1 200 Ok + Content-Type: application/json - **Redirect Request** + { + "name": "whistle_v2.gcode", + "bytes": 1468987, + "size": "1.4MB" + "date": "2013-05-21 23:15", + "origin": "local", + "refs": { + "resource": "http://example.com/api/files/local/whistle_v2.gcode", + "download": "http://example.com/downloads/files/local/whistle_v2.gcode" + }, + "gcodeAnalysis": { + "estimatedPrintTime": "00:31:40", + "filament": "0.79m" + }, + "print": { + "failure": 4, + "success": 23, + "last": { + "date": "2013-11-18 18:00", + "success": true + } + } + } - .. sourcecode:: http - - GET /downloads/files/whistle_v2.gcode HTTP/1.1 - Host: example.com - - **Redirect Response** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - ;Generated with Cura_SteamEngine 13.11.2 - M109 T0 S220.000000 - T0 - ;Sliced at: Wed 11-12-2013 16:53:12 - ;Basic settings: Layer height: 0.2 Walls: 0.8 Fill: 20 - ;Print time: #P_TIME# - ;Filament used: #F_AMNT#m #F_WGHT#g - ;Filament cost: #F_COST# - ;M190 S70 ;Uncomment to add your own bed temperature line - ;M109 S220 ;Uncomment to add your own temperature line - G21 ;metric values - G90 ;absolute positioning - ... - - :param filename: The filename of the file for which to retrieve the contents - :resheader Location: The statically served download location for the file of the format ``/downloads/files/`` - :statuscode 302: No error, regular redirect to statically served download location + :param location: The location of the file for which to retrieve the information, either ``local`` or ``sdcard``. + :param filename: The filename of the file for which to retrieve the information + :statuscode 200: No error + :statuscode 404: If `target` is neither ``local`` nor ``sdcard``, ``sdcard`` but SD card support is disabled or the + requested file was not found .. _sec-api-fileops-filecommand: @@ -280,12 +296,16 @@ Issue a file command Issue a file command to an existing file. Currently supported commands are: - load + select Selects a file for printing. Additional parameters are: - * ``print``: Optional, if set to ``true`` the file will start printing directly after selection. + * ``print``: Optional, if set to ``true`` the file will start printing directly after selection. If the printer + is not operational when this parameter is present and set to ``true``, the request will fail with a response + of ``409 Conflict``. - **Example Request** + Upon success, a status code of :http:statuscode:`204` and an empty body is returned. + + **Example Select Request** .. sourcecode:: http @@ -295,28 +315,20 @@ Issue a file command X-Api-Key: abcdef... { - "command": "load", + "command": "select", "print": true } - **Example Response** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - {} - :param target: The target location on which to delete the file, either ``local`` (for OctoPrint's ``uploads`` folder) or ``sdcard`` for the printer's SD card (if available) :param filename: The filename of the file for which to issue the command - :json string command: The command to issue for the file, currently only ``load`` is supported - :json boolean print: ``load`` command: Optional, whether to start printing the file directly after selection, + :json string command: The command to issue for the file, currently only ``select`` is supported + :json boolean print: ``select`` command: Optional, whether to start printing the file directly after selection, defaults to ``false``. :statuscode 200: No error - :statuscode 400: If `target` is neither ``local`` nor ``sdcard``, the `command` is unknown or the request is - otherwise invalid + :statuscode 400: If the `command` is unknown or the request is otherwise invalid + :statuscode 404: If `target` is neither ``local`` nor ``sdcard`` or the requested file was not found + :statuscode 409: If a selected file is supposed to start printing directly but the printer is not operational. .. _sec-api-fileops-delete: @@ -327,8 +339,9 @@ Delete file Delete the selected `filename` on the selected `target`. - Returns a :ref:`Retrieve Response ` corresponding to the updated - file list after successful deletion. + If the file to be deleted is currently being printed, a :http:statuscode:`409` will be returned. + + Returns a :http:statuscode:`204` after successful deletion. **Example Request** @@ -338,26 +351,12 @@ Delete file Host: example.com X-Api-Key: abcdef... - **Example Response** - - .. sourcecode:: http - - HTTP/1.1 200 Ok - Content-Type: application/json - - { - "files": [ - ... - ], - "free": "3.2GB" - } - :param target: The target location on which to delete the file, either ``local`` (for OctoPrint's ``uploads`` folder) or ``sdcard`` for the printer's SD card (if available) :param filename: The filename of the file to delete - :statuscode 200: No error - :statuscode 400: If `target` is neither ``local`` nor ``sdcard`` or the request is otherwise invalid - :statuscode 403: If the file to be deleted is currently being printed + :statuscode 204: No error + :statuscode 404: If `target` is neither ``local`` nor ``sdcard`` or the requested file was not found + :statuscode 409: If the file to be deleted is currently being printed .. _sec-api-fileops-datamodel: @@ -382,9 +381,10 @@ Retrieve response - Array of :ref:`File information items ` - The list of requested files. Might be an empty list if no files are available * - ``free`` - - 1 + - 0..1 - String - - The amount of disk space available in the local disk space (refers to OctoPrint's ``uploads`` folder) + - The amount of disk space available in the local disk space (refers to OctoPrint's ``uploads`` folder). Only + returned if file list was requested for origin ``local`` or all origins. .. _sec-api-fileops-datamodel-uploadresponse: @@ -400,18 +400,26 @@ Upload response - Type - Description * - ``files`` - - 0..* - - Array of :ref:`File information items ` - - The list of files available in the system. Might be an empty list if no files are available + - 1 + - Object + - Abridged information regarding the file that was just uploaded. If only uploaded to ``local`` this will only + contain the ``local`` property. If uploaded to SD card, this will contain both ``local`` and ``sdcard`` properties. + * - ``files.local`` + - 1 + - :ref:`sec-api-fileops-datamodel-fileinfo` + - The information regarding the file that was just uploaded to the local storage (only the fields ``name``, + ``origin`` and ``refs`` will be set). + * - ``files.sdcard`` + - 0..1 + - :ref:`sec-api-fileops-datamodel-fileinfo` + - The information regarding the file that was just uploaded to the printer's SD card (only the fields ``name``, + ``origin`` and ``refs`` will be set). * - ``done`` - 1 - Boolean - - Whether the file is directly available for printing after receiving the response (``true``) or not, e.g. due - to first needing to be sliced into GCODE (``false``) - * - ``filename`` - - 1 - - String - - The name of the file that was just uploaded + - Whether the file processing after upload has already finished (``true``) or not, e.g. due to first needing + to perform a slicing step (``false``). Clients may use this information to direct progress displays related to + the upload. .. _sec-api-fileops-datamodel-fileinfo: @@ -431,24 +439,26 @@ File information - String - The name of the file * - ``bytes`` - - 1 - - Number - - The size of the file in bytes. Only available for ``local`` files, always ``0`` for files stored on ``sdcard``. - * - ``size`` - - 1 - - String - - The size of the file in a human readable format. Only available for ``local`` files, set to ``n/a`` for files - stored on ``sdcard``. - * - ``date`` - - 1 - - String representing a date and time in the format ``YYYY-MM-DD HH:mm`` - - The date and time this files was uploaded. Only available for ``local`` files, - set to ``n/a`` for files stored on ``sdcard``. - * - ``origin`` - 0..1 + - Number + - The size of the file in bytes. Only available for ``local`` files. + * - ``size`` + - 0..1 + - String + - The size of the file in a human readable format. Only available for ``local`` files. + * - ``date`` + - 0..1 + - String representing a date and time in the format ``YYYY-MM-DD HH:mm`` + - The date and time this files was uploaded. Only available for ``local`` files. + * - ``origin`` + - 1 - String, either ``local`` or ``sdcard`` - The origin of the file, ``local`` when stored in OctoPrint's ``uploads`` folder, ``sdcard`` when stored on the printer's SD card (if available) + * - ``refs`` + - 0..1 + - :ref:`` + - References relevant to this file * - ``gcodeAnalysis`` - 0..1 - :ref:`GCODE analysis information ` @@ -458,10 +468,6 @@ File information - :ref:`Print information ` - Information regarding prints of this file, if available. -.. todo:: - Make fields which are not available for ``sdcard`` (``bytes``, ``size``, ``date``) optional and don't include them - in the output if not available. Clients should be able to decide on their own what to display in such a case. - .. _sec-api-fileops-datamodel-gcodeanalysis: GCODE analysis information @@ -519,3 +525,29 @@ Print information - 1 - Boolean - Whether the last print on record was a success (``true``) or not (``false``) + +.. _sec-api-fileops-datamodel-ref: + +References +---------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``resource`` + - 1 + - URL + - The resource that represents the file (e.g. for issuing commands to or for deleting) + * - ``download`` + - 0..1 + - URL + - The download URL for the file + * - ``model`` + - 0..1 + - URL + - The model from which this file was generated (e.g. an STL, currently not used) diff --git a/docs/api/general.rst b/docs/api/general.rst index af1c4644..1741361a 100644 --- a/docs/api/general.rst +++ b/docs/api/general.rst @@ -4,6 +4,8 @@ General information ******************* +.. contents:: + .. _sec-api-general-authorization: Authorization @@ -21,8 +23,7 @@ The API key must be supplied in the custom HTTP header ``X-Api-Key``, e.g. Host: example.com X-Api-Key: abcdef... -If it is missing, OctoPrint will directly return a response with status :http:statuscode:`401`. If it is included in -the request but invalid, OctoPrint will directly return a response with status :http:statuscode:`403`. +If it is missing or included but invalid, OctoPrint will directly return a response with status :http:statuscode:`401`. For testing purposes it is also possible to supply the API key via a query parameter ``apikey``, e.g. diff --git a/docs/api/index.rst b/docs/api/index.rst index 38412cad..e7808141 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -11,4 +11,5 @@ API Documentation fileops.rst connection.rst printer.rst + jobs.rst diff --git a/docs/api/jobs.rst b/docs/api/jobs.rst new file mode 100644 index 00000000..f990af6a --- /dev/null +++ b/docs/api/jobs.rst @@ -0,0 +1,91 @@ +.. _sec-api-jobs: + +*********** +Job Control +*********** + +.. contents:: + +.. _sec-api-jobs-command: + +Issue a job command +=================== + +.. http:post:: /api/control/job + + Job commands allow starting, pausing and cancelling print jobs. Available commands are: + + start + Starts the print of the currently selected file. For selecting a file, see :ref:`Issue a file command `. + If a print job is already active, a :http:statuscode:`409` will be returned. + + restart + Restart the print of the currently selected file from the beginning. There must be an active print job for this to work + and the print job must currently be paused. If either is not the case, a :http:statuscode:`409` will be returned. + + pause + Pauses/unpauses the current print job. If no print job is active (either paused or printing), a :http:statuscode:`409` + will be returned. + + cancel + Cancels the current print job. If no print job is active (either paused or printing), a :http:statuscode:`409` + will be returned. + + Upon success, a status code of :http:statuscode:`204` and an empty body is returned. + + **Example Start Request** + + .. sourcecode:: http + + POST /api/control/job HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "start" + } + + **Example Restart Request** + + .. sourcecode:: http + + POST /api/control/job HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "restart" + } + + **Example Pause Request** + + .. sourcecode:: http + + POST /api/control/job HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "pause" + } + + **Example Cancel Request** + + .. sourcecode:: http + + POST /api/control/job HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "cancel" + } + + :json string command: The command to issue, either ``start``, ``restart``, ``pause`` or ``cancel`` + :statuscode 204: No error + :statuscode 409: If the printer is not operational or the current print job state does not match the preconditions + for the command. diff --git a/docs/api/printer.rst b/docs/api/printer.rst index c4898026..94c1c732 100644 --- a/docs/api/printer.rst +++ b/docs/api/printer.rst @@ -4,7 +4,23 @@ Printer Control *************** -.. _sec-api-printer-printhead: +.. contents:: + +Printer control is mostly achieved through the use of commands, issued to resources reflecting components of the +printer. OctoPrint currently knows the following components: + +Print head + Print head commands allow jogging and homing the print head in all three axes. See :ref:`sec-api-printer-printheadcommand`. +Heater + Heater commands allow setting the temperature and temperature offsets for the printer's hotend and bed. Currently + OctoPrint only supports one hotend heater (this will change in the future). See :ref:`sec-api-printer-heatercommand`. +Feeder + Feeder commands allow extrusion/extraction of filament. Currently OctoPrint only supports one feeder (this will + change in a future version). See :ref:`sec-api-printer-feedercommand`. +SD card + SD commands allow initialization, refresh and release of the printer's SD card (if available). See :ref:`sec-api-printer-sdcommand`. + +.. _sec-api-printer-printheadcommand: Issue a print head command ========================== @@ -25,13 +41,18 @@ Issue a print head command * ``axes``: A list of axes which to home, valid values are one or more of ``x``, ``y``, ``z``. + All of these commands may only be sent if the printer is currently operational and not printing. Otherwise a + :http:statuscode:`409` is returned. + + Upon success, a status code of :http:statuscode:`204` and an empty body is returned. + **Example Jog Request** Jog the print head by 10mm in X, -5mm in Y and 0.02mm in Z. .. sourcecode:: http - POST /api/printer/printhead HTTP/1.1 + POST /api/control/printer/printhead HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: abcdef... @@ -49,7 +70,7 @@ Issue a print head command .. sourcecode:: http - POST /api/printer/printhead HTTP/1.1 + POST /api/control/printer/printhead HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: abcdef... @@ -64,12 +85,12 @@ Issue a print head command :json number y: ``jog`` command: The amount to travel on the Y axis in mm. :json number z: ``jog`` command: The amount to travel on the Z axis in mm. :json array axes: ``home`` command: The axes which to home, valid values are one or more of ``x``, ``y`` and ``z``. - :statuscode 200: No error + :statuscode 204: No error :statuscode 400: Invalid axis specified, invalid value for travel amount for a jog command or otherwise invalid request. - :statuscode 403: If the printer is not operational or currently printing. + :statuscode 409: If the printer is not operational or currently printing. -.. _sec-api-printer-hotend: +.. _sec-api-printer-heatercommand: Issue a heater command ====================== @@ -95,6 +116,11 @@ Issue a heater command * ``hotend``: New offset of the printer's hotend temperature in centigrade, max/min of +/-50°C. * ``bed``: New offset of the printer's bed temperature in centigrade, max/min of +/-50°C. + All of these commands may only be sent if the printer is currently operational and not printing. Otherwise a + :http:statuscode:`409` is returned. + + Upon success, a status code of :http:statuscode:`204` and an empty body is returned. + **Example Target Temperature Request** Set the printer's hotend target temperature to 220°C and the bed target temperature to 75°C. @@ -136,13 +162,13 @@ Issue a heater command :json string command: The command to issue, either ``temp`` or ``offset`` :json object temps: ``temp`` command: The target temperatures to set. Valid properties are ``hotend`` and ``bed`` :json object offsets: ``offset`` command: The offset temperature to set. Valid properties are ``hotend`` and ``bed`` - :statuscode 200: No error + :statuscode 204: No error :statuscode 400: If ``temps`` or ``offsets`` contains a property other than ``hotend`` or ``bed``, the target or offset temperature is not a valid number or outside of the supported range, or if the request is otherwise invalid. - :statuscode 403: If the printer is not operational. + :statuscode 409: If the printer is not operational. -.. _sec-api-printer-feeder: +.. _sec-api-printer-feedercommand: Issue a feeder command ====================== @@ -156,6 +182,11 @@ Issue a feeder command * ``amount``: The amount of filament to extrude in mm. May be negative to retract. + All of these commands may only be sent if the printer is currently operational and not printing. Otherwise a + :http:statuscode:`409` is returned. + + Upon success, a status code of :http:statuscode:`204` and an empty body is returned. + **Example Extrude Request** Extrudes 1mm of filament @@ -190,6 +221,139 @@ Issue a feeder command :json string command: The command to issue, only ``extrude`` is supported right now. :json number amount: ``extrude`` command: The amount of filament to extrude/retract in mm. - :statuscode 200: No error + :statuscode 204: No error :statuscode 400: If the value given for `amount` is not a valid number or the request is otherwise invalid. - :statuscode 403: If the printer is not operational or currently printing. \ No newline at end of file + :statuscode 409: If the printer is not operational or currently printing. + +.. _sec-api-printer-sdcommand: + +Issue a SD command +================== + +.. http:post:: /api/control/printer/sd + + SD commands allow initialization, refresh and release of the printer's SD card (if available). + + Available commands are: + + init + Initializes the printer's SD card, making it available for use. This also includes an initial retrieval of the + list of files currently stored on the SD card, so after issueing that command a :ref:`retrieval of the files + on SD card ` will return a successful result. + + .. note:: + If OctoPrint detects the availability of a SD card on the printer during connection, it will automatically attempt + to initialize it. + + refresh + Refreshes the list of files stored on the printer's SD card. Will return a :http:statuscode:`409` if the card + has not been initialized yet (see the ``init`` command and :ref:`SD state `). + + release + Releases the SD card from the printer. The reverse operation to ``init``. After issuing this command, the SD + card won't be available anymore, hence and operations targeting files stored on it will fail. Will return a :http:statuscode:`409` + if the card has not been initialized yet (see the ``init`` command and :ref:`SD state `). + + Upon success, a status code of :http:statuscode:`204` and an empty body is returned. + + **Example Init Request** + + .. sourcecode:: http + + POST /api/control/printer/sd HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "init" + } + + **Example Refresh Request** + + .. sourcecode:: http + + POST /api/control/printer/sd HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "refresh" + } + + **Example Release Request** + + .. sourcecode:: http + + POST /api/control/printer/sd HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "release" + } + + :json string command: The command to issue, either ``init``, ``refresh`` or ``release``. + :statuscode 204: No error + :statuscode 409: If a ``refresh`` or ``release`` command is issued but the SD card has not been initialized (e.g. + via ``init``. + +.. _sec-api-printer-sdstate: + +Retrieve the current SD state +============================= + +.. http:get:: /api/control/printer/sd + + Retrieves the current state of the printer's SD card. For this request no authentication is needed. + + If SD support has been disabled in OctoPrint's settings, a :http:statuscode:`404` is returned. + + Returns a :http:statuscode:`200` with an :ref:`SD State Response ` in the body + upon success. + + **Example Request** + + .. sourcecode:: http + + GET /api/control/printer/sd HTTP/1.1 + Host: example.com + + **Example Response** + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "ready": true + } + + :statuscode 200: No error + :statuscode 404: If SD support has been disabled in OctoPrint's config. + +.. _sec-api-printer-datamodel: + +Datamodel +========= + +.. _sec-api-printer-datamodel-sdstate: + +SD State Response +----------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``ready`` + - 1 + - Boolean + - Whether the SD card has been initialized (``true``) or not (``false``). \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 5151535b..87f940b4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,10 @@ Welcome to OctoPrint's documentation! ##################################### +.. image:: images/octoprint-logo.png + :alt: The OctoPrint Logo + :align: right + This is a work in progress. The goal is to document OctoPrint's REST API, event system, configuration etc in way that allows different documentation per development branch in Git, which so far did not scale well with the Github-Wiki-based approach. @@ -19,9 +23,3 @@ Contents api/index.rst -Indices and tables -================== - -* :ref:`genindex` -* :ref:`search` -* :ref:`http-routingtable` \ No newline at end of file