pingu_98/MrDraw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

More documentation

Browse source
This commit is contained in:
Gina Häußge 2013-12-21 13:01:18 +01:00
parent 792299537d
commit b6cdc5803b
7 changed files with 457 additions and 171 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/api/connection.rst
View file

@ -4,8 +4,7 @@
Connection handling
*******************
.. toctree::
:maxdepth: 2
.. contents::
.. _sec-api-connection-current:

332
docs/api/fileops.rst
View file

@ -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 <sec-api-fileops-datamodel-retrieveresponse>`.
@ -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 <sec-api-fileops-datamodel-uploadresponse>` 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 <sec-api-fileops-datamodel-uploadresponse>` 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 <sec-api-fileops-datamodel-fileinfo>`
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/<filename>``
: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 <sec-api-fileops-datamodel-retrieveresponse>` 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 <sec-api-fileops-datamodel-fileinfo>`
- 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 <sec-api-fileops-datamodel-fileinfo>`
- 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:`<sec-api-fileops-datamodel-ref>`
- References relevant to this file
* - ``gcodeAnalysis``
- 0..1
- :ref:`GCODE analysis information <sec-api-fileops-datamodel-gcodeanalysis>`
@ -458,10 +468,6 @@ File information
- :ref:`Print information <sec-api-fileops-datamodel-prints>`
- 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)

5
docs/api/general.rst
View file

@ -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.

1
docs/api/index.rst
View file

@ -11,4 +11,5 @@ API Documentation
fileops.rst
connection.rst
printer.rst
jobs.rst

91
docs/api/jobs.rst Normal file
View file

@ -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 <sec-api-fileops-filecommand>`.
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.

186
docs/api/printer.rst
View file

@ -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.
: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 <sec-api-fileops-retrieveorigin>` 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 <sec-api-printer-sdstate>`).
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 <sec-api-printer-sdstate>`).
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 <sec-api-printer-datamodel-sdstate>` 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``).

10
docs/index.rst
View file

@ -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`