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

Some further API documentation

Browse source
This commit is contained in:
Gina Häußge 2013-12-16 01:47:06 +01:00
parent 1c39555255
commit 755549a745
7 changed files with 593 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

120
docs/api/connection.rst Normal file
View file

@ -0,0 +1,120 @@
.. _sec-api-connection:
*******************
Connection handling
*******************
.. toctree::
:maxdepth: 2
.. _sec-api-connection-current:
Get connection settings
=======================
.. http:get:: /api/control/connection
Retrieve the current connection settings, including information regarding the available baudrates and
serial ports and the current connection state.
**Example Request**
.. sourcecode:: http
GET /api/control/connection HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...
**Example Response**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"current": {
"state": "Operational",
"port": "/dev/ttyACM0",
"baudrate": 250000
},
"options": {
"ports": ["/dev/ttyACM0", "VIRTUAL"],
"baudrates": [250000, 230400, 115200, 57600, 38400, 19200, 9600],
"portPreference": "/dev/ttyACM0",
"baudratePreference": 250000,
"autoconnect": true
}
}
:statuscode 200: No error
.. _sec-api-connection-command:
Issue a connection command
==========================
.. http:post:: /api/control/connection
Issue a connection command. Currently available command are:
connect
Instructs OctoPrint to connect to the printer. Additional parameters are:
* ``port``: Optional, specific port to connect to. If not set the current ``portPreference`` will be used, or if
no preference is available auto detection will be attempted.
* ``baudrate``: Optional, specific baudrate to connect with. If not set the current ``baudratePreference`` will
be used, or if no preference is available auto detection will be attempted.
* ``save``: Optional, whether to save the request's ``port`` and ``baudrate`` settings as new preferences. Defaults
to ``false`` if not set.
* ``autoconnect``: Optional, whether to automatically connect to the printer on OctoPrint's startup in the future.
If not set no changes will be made to the current configuration.
disconnect
Instructs OctoPrint to disconnect from the printer.
**Example Connect Request**
.. sourcecode:: http
POST /api/control/connection HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...
{
"command": "connect",
"port": "/dev/ttyACM0",
"baudrate": 115200,
"save": true,
"autoconnect": true
}
**Example Disconnect Request**
.. sourcecode:: http
POST /api/control/connection HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...
{
"command": "disconnect"
}
:json string command: The command to issue, either ``connect`` or ``disconnect``
:json string port: ``connect`` command: The port to connect to. If left out either the existing ``portPreference``
will be used, or if that is not available OctoPrint will attempt auto detection. Must be part
of the available ports.
:json number baudrate: ``connect`` command: The baudrate to connect with. If left out either the existing
``baudratePreference`` will be used, or if that is not available OctoPrint will attempt
autodetection. Must be part of the available baudrates.
:json boolean save: ``connect`` command: Whether to save the supplied connection settings as the new preference.
Defaults to ``false`` if not set.
:json boolean autoconnect: ``connect`` command: Whether to attempt to automatically connect to the printer on server
startup. If not set no changes will be made to the current setting.
:statuscode 200: No error
:statuscode 400: If the selected `port` or `baudrate` for a ``connect`` command are not part of the available
options.

293
docs/api/fileops.rst
View file

@ -4,14 +4,17 @@
File operations
***************
.. toctree::
:maxdepth: 5
.. _sec-api-fileops-retrieveall:
Retrieve all files
==================
.. http:get:: /api/gcodefiles
.. http:get:: /api/files
Retrieve information regarding all GCODE files currently available and regarding the disk space still available
Retrieve information regarding all files currently available and regarding the disk space still available
locally in the system.
Returns a :ref:`Retrieve response <sec-api-fileops-datamodel-retrieveresponse>`.
@ -20,8 +23,9 @@ Retrieve all files
.. sourcecode:: http
GET /api/gcodefiles?apikey=abcdef HTTP/1.1
GET /api/files HTTP/1.1
Host: example.com
X-Api-Key: abcdef...
**Example response**:
@ -37,7 +41,7 @@ Retrieve all files
"bytes": 1468987,
"size": "1.4MB"
"date": "2013-05-21 23:15",
"origin": "local"
"origin": "local",
"gcodeAnalysis": {
"estimatedPrintTime": "00:31:40",
"filament": "0.79m"
@ -62,20 +66,16 @@ Retrieve all files
"free": "3.2GB"
}
:query apikey: The API key to use for the request, either the global one or a user specific one (see
:ref:`Authorization <sec-api-general-authorization>` for more details)
:statuscode 200: No error
:statuscode 401: If the API key is missing
:statuscode 403: If the API key is invalid
.. _sec-api-fileops-retrievetarget:
Retrieve files from specific origin
===================================
.. http:get:: /api/gcodefiles/(string:origin)
.. http:get:: /api/files/(string:origin)
Retrieve information regarding the GCODE files currently available on the selected `origin` and regarding the
Retrieve information regarding the files currently available on the selected `origin` and regarding the
disk space still available locally in the system.
Returns a :ref:`Retrieve response <sec-api-fileops-datamodel-retrieveresponse>`.
@ -84,8 +84,9 @@ Retrieve files from specific origin
.. sourcecode:: http
GET /api/gcodefiles/local?apikey=abcdef HTTP/1.1
GET /api/files/local HTTP/1.1
Host: example.com
X-Api-Key: abcdef...
**Example response**:
@ -101,7 +102,7 @@ Retrieve files from specific origin
"bytes": 1468987,
"size": "1.4MB"
"date": "2013-05-21 23:15",
"origin": "local"
"origin": "local",
"gcodeAnalysis": {
"estimatedPrintTime": "00:31:40",
"filament": "0.79m"
@ -119,15 +120,244 @@ Retrieve files from specific origin
"free": "3.2GB"
}
:param target: The target location from which to retrieve the files. Currently only ``local`` and ``sdcard`` are
: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).
:query apikey: The API key to use for the request, either the global one or a user specific one (see
:ref:`Authorization <sec-api-general-authorization>` for more details)
:statuscode 200: No error
:statuscode 400: If `origin` is neither ``local`` nor ``sdcard``
:statuscode 401: If the API key is missing
:statuscode 403: If the API key is invalid
:statuscode 400: If `origin` is neither ``local`` nor ``sdcard`` or the request is otherwise invalid.
.. _sec-api-fileops-uploadfile:
Upload file
===========
.. http:post:: /api/files/(string:target)
Upload a file to the selected `target`.
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.
**Example request**
.. sourcecode:: http
POST /api/files/local HTTP/1.1
Host: example.com
X-Api-Key: abcdef...
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryDeC2E3iWbTv1PwMC
------WebKitFormBoundaryDeC2E3iWbTv1PwMC
Content-Disposition: form-data; name="file"; filename="whistle_v2.gcode"
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
...
------WebKitFormBoundaryDeC2E3iWbTv1PwMC
Content-Disposition: form-data; name="select"
true
------WebKitFormBoundaryDeC2E3iWbTv1PwMC
Content-Disposition: form-data; name="print"
true
------WebKitFormBoundaryDeC2E3iWbTv1PwMC--
**Example response**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"files": [
...
{
"name": "whistle_v2.gcode",
"bytes": 1468987,
"size": "1.4MB"
"date": "2013-05-21 23:15",
"origin": "local"
},
...
],
"done": true,
"filename": "whistle_v2.gcode"
}
: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
:statuscode 500: If the upload failed internally
.. _sec-api-fileops-retrievefile:
Retrieve a file's contents
==========================
.. http:get:: /api/files/local/(path:filename)
Downloads the selected file's contents. Only available for locally stored files, hence no `target` parameter.
Will actually redirect to serve the download via a static context directly from the filesystem.
**Example Request**
.. sourcecode:: http
GET /api/files/local/whistle_v2.gcode HTTP/1.1
Host: example.com
**Example Response**
.. sourcecode:: http
HTTP/1.1 302 Found
Location: /downloads/files/whistle_v2.gcode
**Redirect Request**
.. 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
.. _sec-api-fileops-filecommand:
Issue a file command
====================
.. http:post:: /api/files/(string:target)/(path:filename)
Issue a file command to an existing file. Currently supported commands are:
load
Selects a file for printing. Additional parameters are:
* ``print``: Optional, if set to ``true`` the file will start printing directly after selection.
**Example Request**
.. sourcecode:: http
POST /api/files/local/whistle_v2.gcode HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...
{
"command": "load",
"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,
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
.. _sec-api-fileops-delete:
Delete file
===========
.. http:post:: /api/files/(string:target)/(path:filename)
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.
**Example Request**
.. sourcecode:: http
DELETE /api/files/local/whistle_v2.gcode HTTP/1.1
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
.. _sec-api-fileops-datamodel:
@ -156,6 +386,33 @@ Retrieve response
- String
- The amount of disk space available in the local disk space (refers to OctoPrint's ``uploads`` folder)
.. _sec-api-fileops-datamodel-uploadresponse:
Upload response
---------------
.. list-table::
:widths: 15 5 10 30
:header-rows: 1
* - Name
- Multiplicity
- 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
* - ``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
.. _sec-api-fileops-datamodel-fileinfo:
File information

36
docs/api/general.rst
View file

@ -10,19 +10,28 @@ Authorization
=============
OctoPrint's API expects an API key to be supplied with each request. This API key can be either the globally
configured one (compare :ref:`fig-api-general-globalapikey`) or a user specific one if "Access Control" is enabled
(compare :ref:`fig-api-general-userapikey`). Users are able to generate and revoke their custom API key via the
"Change password" dialog (compare :ref:`fig-api-general-changepassword`).
configured one or a user specific one if "Access Control" is enabled. Users are able to generate and revoke their
custom API key via the "Change password" dialog.
The API key must be supplied as query parameter ``apikey`` to each request, e.g.
The API key must be supplied in the custom HTTP header ``X-Api-Key``, e.g.
.. sourcecode:: http
GET /api/gcodefiles/local?apikey=abcdef HTTP/1.1
GET /api/files HTTP/1.1
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`.
For testing purposes it is also possible to supply the API key via a query parameter ``apikey``, e.g.
.. sourcecode:: http
GET /api/files?apikey=abcdef... HTTP/1.1
Host: example.com
.. todo::
Look into allowing to supply the API key as a custom ``Authorization`` scheme.
Please be advised that clients should use the header field variant if at all possible.
.. _fig-api-general-globalapikey:
.. figure:: ../images/settings-global-api-key.png
@ -45,3 +54,16 @@ The API key must be supplied as query parameter ``apikey`` to each request, e.g.
The API key options in the "Change password" dialog. Users can generate and revoke their custom API key here.
.. _sec-api-general-contenttype:
Content Type
============
If not otherwise stated OctoPrint's API expects request bodies and issues response bodies as ``Content-Type: application/json``.
.. _sec-api-general-encoding:
Encoding
========
OctoPrint uses UTF-8 as charset.

5
docs/api/index.rst
View file

@ -8,4 +8,7 @@ API Documentation
:maxdepth: 2
general.rst
fileops.rst
fileops.rst
connection.rst
printer.rst

147
docs/api/printer.rst Normal file
View file

@ -0,0 +1,147 @@
.. _sec-api-printer:
***************
Printer Control
***************
.. _sec-api-printer-printhead:
Issue a print head command
==========================
.. http:post:: /api/control/printer/printhead
Print head commands allow jogging and homing the print head in all three axes. Available commands are:
jog
Jogs the print head (relatively) by a defined amount in one or more axes. Additional parameters are:
* ``x``: Optional. Amount to jog print head on x axis, must be a valid number corresponding to the distance to travel in mm.
* ``y``: Optional. Amount to jog print head on y axis, must be a valid number corresponding to the distance to travel in mm.
* ``z``: Optional. Amount to jog print head on z axis, must be a valid number corresponding to the distance to travel in mm.
home
Homes the print head in all of the given axes. Additional parameters are:
* ``axes``: A list of axes which to home, valid values are one or more of ``x``, ``y``, ``z``.
**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
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...
{
"command": "jog",
"x": 10,
"y": -5,
"z": 0.02
}
**Example Home Request**
Home the X and Y axes.
.. sourcecode:: http
POST /api/printer/printhead HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...
{
"command": "home",
"axes": ["x", "y"]
}
:json string command: The command to issue, either ``jog`` or ``home``.
:json number x: ``jog`` command: The amount to travel on the X axis in mm.
: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 400: Invalid axis specified, invalid value for travel amount for a jog command or otherwise invalid
request.
.. _sec-api-printer-hotend:
Issue a heater command
======================
.. http:post:: /api/control/printer/heater
Heater commands allow setting the temperature and temperature offsets for the printer's hotend and bed. Available
commands are:
temp
Sets the given target temperature on the printer's hotend and/or bed. Additional parameters:
* ``temps``: Target temperature(s) to set, allowed properties are:
* ``hotend``: New target temperature of the printer's hotend in centigrade.
* ``bed``: New target temperature of the printer's bed in centigrade.
offset
Sets the given temperature offset on the printer's hotend and/or bed. Additional parameters:
* ``offsets``: Offset(s) to set, allowed properties are:
* ``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.
**Example Target Temperature Request**
Set the printer's hotend target temperature to 220°C and the bed target temperature to 75°C.
.. sourcecode:: http
POST /api/control/printer/heater HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...
{
"command": "temp",
"temps": {
"hotend": 220,
"bed": 75
}
}
**Example Offset Temperature Request**
Set the offset for hotend temperatures to +10°C and for bed temperatures to -5°C.
.. sourcecode:: http
POST /api/control/printer/heater HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...
{
"command": "offset",
"offsets": {
"hotend": 10,
"bed": -5
}
}
: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 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.
.. _sec-api-printer-feeder:
Feeder Control
==============

12
docs/conf.py
View file

@ -93,11 +93,17 @@ pygments_style = 'sphinx'
# -- Options for HTML output ---------------------------------------------------
import sphinx_rtd_theme
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = "sphinx_rtd_theme"
#html_theme = "sphinx_rtd_theme"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@ -105,7 +111,7 @@ html_theme = "sphinx_rtd_theme"
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
#html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".

10
docs/index.rst
View file

@ -11,9 +11,17 @@ This is a work in progress. The goal is to document OctoPrint's REST API, event
allows different documentation per development branch in Git, which so far did not scale well with the Github-Wiki-based
approach.
Contents:
Contents
========
.. toctree::
:maxdepth: 2
api/index.rst
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`
* :ref:`http-routingtable`