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

More work on the docs

Browse source
This commit is contained in:
Gina Häußge 2016-07-01 17:52:40 +02:00
parent 08de33e27d
commit 52d272bd24
4 changed files with 319 additions and 59 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
docs/api/datamodel.rst
View file

@ -232,7 +232,12 @@ File information
* - ``name``
- 1
- String
- The name of the file
- The name of the file without path. E.g. "file.gco" for a file "file.gco" located anywhere in the file system.
* - ``path``
- 1
- String
- The path to the file within the location. E.g. "folder/subfolder/file.gco" for a file "file.gco" located within
"folder" and "subfolder" relative to the root of the location.
* - ``type``
- 1
- String
@ -261,7 +266,13 @@ Folders
* - ``children``
- 0..*
- Array of :ref:`File information items <sec-api-datamodel-files-file>`
- Contained children for entries of type ``folder``
- Contained children for entries of type ``folder``. Will only include children in subfolders in recursive
listings. Not present in non recursive listings, this might be revisited in the future.
* - ``size``
- 0..1
- Number
- The size of all files contained in the folder and its subfolders. Not present in non recursive listings, this might
be revisited in the future.
Files
'''''
@ -301,6 +312,38 @@ Files
- :ref:`GCODE analysis information <sec-api-datamodel-files-gcodeanalysis>`
- Information from the analysis of the GCODE file, if available. Left out in abridged version.
.. _sec-api-datamodel-files-fileabridged:
Abridged file or folder information
-----------------------------------
.. list-table::
:widths: 15 5 10 30
:header-rows: 1
* - Name
- Multiplicity
- Type
- Description
* - ``name``
- 1
- String
- The name of the file or folder without path. E.g. "file.gco" for a file "file.gco" located anywhere in the file system.
* - ``path``
- 1
- String
- The path to the file or folder within the location. E.g. "folder/subfolder/file.gco" for a file "file.gco" located within
"folder" and "subfolder" relative to the root of the location.
* - ``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-datamodel-files-ref`
- References relevant to this file or folder, left out in abridged version
.. _sec-api-datamodel-files-gcodeanalysis:
GCODE analysis information
@ -348,13 +391,14 @@ References
* - ``resource``
- 1
- URL
- The resource that represents the file (e.g. for issuing commands to or for deleting)
- The resource that represents the file or folder (e.g. for issuing commands to or for deleting)
* - ``download``
- 0..1
- URL
- The download URL for the file
- The download URL for the file. Never present for folders.
* - ``model``
- 0..1
- URL
- The model from which this file was generated (e.g. an STL, currently not used)
- The model from which this file was generated (e.g. an STL, currently not used). Never present for
folders.

154
docs/api/fileops.rst
View file

@ -135,20 +135,27 @@ Retrieve files from specific location
.. _sec-api-fileops-uploadfile:
Upload file
===========
Upload file or create folder
============================
.. http:post:: /api/files/(string:location)
Upload a file to the selected `location`.
Upload a file to the selected ``location`` or create a new empty folder on it.
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.
To upload a file, the request body must at least contain the ``file`` form field with the
contents and file name of the file to upload.
To create a new folder, the request body must at least contain the ``foldername`` form field,
specifying the name of the new folder. Note that folder creation is currently only supported on
the ``local`` file system.
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**
**Example for uploading a file**
.. sourcecode:: http
@ -194,6 +201,7 @@ Upload file
"files": {
"local": {
"name": "whistle_v2.gcode",
"path": "whistle_v2.gcode",
"origin": "local",
"refs": {
"resource": "http://example.com/api/files/local/whistle_v2.gcode",
@ -202,6 +210,7 @@ Upload file
},
"sdcard": {
"name": "whistle_.gco",
"path": "whistle_.gco",
"origin": "sdcard",
"refs": {
"resource": "http://example.com/api/files/sdcard/whistle_.gco"
@ -211,35 +220,73 @@ Upload file
"done": true
}
: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``.
:form userdata: [Optional] An optional string that if specified will be interpreted as JSON and then saved along
with the file as metadata (metadata key ``userdata``)
:statuscode 201: No error
:statuscode 400: If no `file` is included in the request, `userdata` was provided but could not be parsed as JSON
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
**Example for creating a folder**
.. sourcecode:: http
POST /api/files/local HTTP/1.1
Host: example.com
X-Api-Key: abcdef...
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryDeC2E3iWbTv1PwMD
------WebKitFormBoundaryDeC2E3iWbTv1PwMD
Content-Disposition: form-data; name="foldername"
subfolder
------WebKitFormBoundaryDeC2E3iWbTv1PwMD
Content-Disposition: form-data; name="path"
folder/
------WebKitFormBoundaryDeC2E3iWbTv1PwMD--
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
Location: http://example.com/api/files/local/folder/subfolder
{
"folder": {
"name": "subfolder",
"path": "folder/subfolder",
"origin": "local"
},
"done": true
}
: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 path: The path within the ``location`` to upload the file to or create the folder in (without the future
filename or ``foldername`` - basically the parent folder). If unset will be taken from the provided
``file``'s name or ``foldername`` and default to the root folder of the ``location``.
:form select: Whether to select the file directly after upload (``true``) or not (``false``). Optional, defaults
to ``false``. Ignored when creating a folder.
: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``. Ignored when creating a folder.
:form userdata: [Optional] An optional string that if specified will be interpreted as JSON and then saved along
with the file as metadata (metadata key ``userdata``). Ignored when creating a folder.
:form foldername: The name of the folder to create. Ignored when uploading a file.
:statuscode 201: No error
:statuscode 400: If no ``file`` or ``foldername`` are included in the request, ``userdata`` was provided but could
not be parsed as JSON 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-retrievefileinfo:
Retrieve a specific file's information
======================================
Retrieve a specific file's or folder's information
==================================================
.. http:get:: /api/files/(string:location)/(path:filename)
Retrieves the selected file's information.
Retrieves the selected file's or folder's information.
If the file is unknown, a :http:statuscode:`404` is returned.
@ -287,8 +334,9 @@ Retrieve a specific file's information
: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
:param children: Whether to include children of folders (true, default) or not (false)
:statuscode 200: No error
:statuscode 404: If `target` is neither ``local`` nor ``sdcard``, ``sdcard`` but SD card support is disabled or the
: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:
@ -296,7 +344,7 @@ Retrieve a specific file's information
Issue a file command
====================
.. http:post:: /api/files/(string:target)/(path:filename)
.. http:post:: /api/files/(string:location)/(path:path)
Issue a file command to an existing file. Currently supported commands are:
@ -307,6 +355,8 @@ Issue a file command
is not operational when this parameter is present and set to ``true``, the request will fail with a response
of ``409 Conflict``.
Upon success, a status code of :http:statuscode:`204` and an empty body is returned.
slice
Slices an STL file into GCODE. Note that this is an asynchronous operation that will take place in the background
after the response has been sent back to the client. Additional parameters are:
@ -334,7 +384,8 @@ Issue a file command
also mean that if it was supposed to be directly selected and start printing after the slicing finished, this will not
take place anymore and whether this will happen with the new sliced file depends entirely on the new request!
Upon success, a status code of :http:statuscode:`204` and an empty body is returned, unless specified otherwise.
Upon success, a status code of :http:statuscode:`202` and a :ref:`sec-api-datamodel-files-fileabridged` in the response
body will be returned.
**Example Select Request**
@ -358,7 +409,7 @@ Issue a file command
.. sourcecode:: http
POST /api/files/local/some_model.stl HTTP/1.1
POST /api/files/local/some_folder/some_model.stl HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...
@ -383,16 +434,17 @@ Issue a file command
{
"origin": "local",
"name": "some_model.first_try.gcode",
"path": "some_folder/some_model.first_try.gcode",
"refs": {
"download": "http://example.com/downloads/files/local/some_model.first_try.gcode",
"resource": "http://example.com/api/files/local/some_model.first_try.gcode"
"download": "http://example.com/downloads/files/local/some_folder/some_model.first_try.gcode",
"resource": "http://example.com/api/files/local/some_folder/some_model.first_try.gcode"
}
}
:param target: The target location on which to delete the file, either ``local`` (for OctoPrint's ``uploads``
:param location: 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
:param path: The path of the file for which to issue the command
:json string command: The command to issue for the file, currently only ``select`` is supported
:json boolean print: ``select`` and ``slice`` command: Optional, whether to start printing the file directly after selection
or slicing, defaults to ``false``.
@ -410,7 +462,7 @@ Issue a file command
:statuscode 202: No error for a ``slice`` command.
:statuscode 400: If the ``command`` is unknown or the request is otherwise invalid
:statuscode 415: If a ``slice`` command was issued against something other than an STL file.
:statuscode 404: If `target` is neither ``local`` nor ``sdcard`` or the requested file was not found
:statuscode 404: If ``location`` 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 or
if a file to be sliced is supposed to be selected or start printing directly but the printer
is not operational or already printing.
@ -420,9 +472,9 @@ Issue a file command
Delete file
===========
.. http:delete:: /api/files/(string:target)/(path:filename)
.. http:delete:: /api/files/(string:location)/(path:path)
Delete the selected `filename` on the selected `target`.
Delete the selected ``path`` on the selected ``location``.
If the file to be deleted is currently being printed, a :http:statuscode:`409` will be returned.
@ -436,11 +488,11 @@ Delete file
Host: example.com
X-Api-Key: abcdef...
:param target: The target location on which to delete the file, either ``local`` (for OctoPrint's ``uploads``
:param location: 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
:param path: The path of the file to delete
:statuscode 204: No error
:statuscode 404: If `target` is neither ``local`` nor ``sdcard`` or the requested file was not found
:statuscode 404: If ``location`` 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:
@ -485,24 +537,28 @@ Upload response
- Type
- Description
* - ``files``
- 1
- 0..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.
Only contained if a file was uploaded, not present if only a new folder was created.
* - ``files.local``
- 1
- :ref:`sec-api-datamodel-files-file`
- The information regarding the file that was just uploaded to the local storage (only the fields ``name``,
``origin`` and ``refs`` will be set).
- :ref:`sec-api-datamodel-files-fileabridged`
- The information regarding the file that was just uploaded to the local storage.
* - ``files.sdcard``
- 0..1
- :ref:`sec-api-datamodel-files-file`
- 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).
- :ref:`sec-api-datamodel-files-fileabridged`
- The information regarding the file that was just uploaded to the printer's SD card.
* - ``folder``
- 0..1
- :ref:`sec-api-datamodel-files-fileabridged`
- Abridged information regarding the folder that was just created. Only contained if a folder
was created, not present if a file was uploaded.
* - ``done``
- 1
- Boolean
- Whether the file processing after upload has already finished (``true``) or not, e.g. due to first needing
- Whether any 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.

166
docs/jsclientlib/files.rst
View file

@ -5,26 +5,182 @@
.. js:function:: OctoPrint.files.get(location, filename, opts)
.. js:function:: OctoPrint.files.list(opts)
Retrieves information about the file ``filename`` at ``location``.
.. js:function:: OctoPrint.files.listForLocation(location, opts)
See :ref:`Retrieve a specific file's information <sec-api-fileops-retrievefileinfo>` for more details.
:param string location: The location of the file
:param string filename: The name of the file
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. js:function:: OctoPrint.files.list(recursively, opts)
Retrieves a list of all files from the server.
The response from the server will be preprocessed such that all contained entries (recursively)
will be guaranteed to have a ``parent``, ``size`` and ``date`` property set at least with a value
of ``undefined``.
For folders, all children will have their ``parent`` property set to the folder entry.
**Example:**
.. code-block:: javascript
var recursivelyPrintNames = function(entry, depth) {
depth = depth || 0;
var isFolder = entry.type == "folder";
var name = (isFolder ? "+ " + entry.name : entry.name);
console.log(_.repeat("| ", depth - 1) + (depth ? "|-" : "") + name);
if (isFolder) {
_.each(entry.children, function(child) {
recursivelyPrintNames(child, depth + 1);
});
}
};
OctoPrint.files.list(true)
.done(function(response) {
console.log("### Files:");
_.each(response.files, function(entry) {
recursivelyPrintNames(entry);
});
});
See :ref:`Retrieve all files <sec-api-fileops-retrieveall>` for more details.
:param boolean recursively: Whether to list the files recursively (including all sub folders, true) or not (false, default)
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. js:function:: OctoPrint.files.listForLocation(location, recursively, opts)
Retrieves a list of all files stored at the specified ``location`` from the server.
The response from the server will be preprocessed such that all contained entries (recursively)
will be guaranteed to have a ``parent``, ``size`` and ``date`` property set at least with a value
of ``undefined``.
For folders, all children will have their ``parent`` property set to the folder entry.
See :ref:`Retrieve files from specific location <sec-api-fileops-retrievelocation>` for more details.
:param string location: The location for which to retrieve the list
:param boolean recursively: Whether to list the files recursively (including all sub folders, true) or not (false, default)
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. js:function:: OctoPrint.files.select(location, filename, print, opts)
Selects a file at ``location`` named ``filename`` for printing. If ``print`` is supplied and
truthy, also starts printing the file immediately.
See the ``select`` command in :ref:`Issue a file command <sec-api-fileops-filecommand>` for more details.
:param string location: The location of the file to select
:param string filename: The name of the file to select
:param boolean print: Whether to print the file after selection (true) or not (false, default)
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. js:function:: OctoPrint.files.slice(location, filename, parameters, opts)
Slices a file at ``location`` called ``filename``, using the supplied slice command ``parameters``.
See the ``slice`` command in :ref:`Issue a file command <sec-api-fileops-filecommand>` for more details.
:param string location: The location of the file to slice
:param string filename: The name of the file to slice
:param object parameters: Additional parameters for the ``slice`` command
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. js:function:: OctoPrint.files.delete(location, filename, opts)
Deletes the file at ``location`` named ``filename``.
See :ref:`Delete file <sec-api-fileops-delete>` for more details.
:param string location: The location of the file to delete
:param string filename: The name of the file to delete
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. js:function:: OctoPrint.files.copy(location, filename, destination, opts)
.. todo::
Also needs API documentation.
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. js:function:: OctoPrint.files.move(location, filename, destination, opts)
.. todo::
Also needs API documentation.
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. js:function:: OctoPrint.files.createFolder(location, name, path, opts)
.. todo::
Also needs API documentation.
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. js:function:: OctoPrint.files.upload(location, file, data)
.. js:function:: OctoPrint.files.download(location, filename, opts)
Uploads a ``file`` to the specified ``location``.
.. js:function:: OctoPrint.files.pathForElement(element)
Additional command ``data`` may be provided. Supported properties are:
.. js:function:: OctoPrint.files.elementByPath(location, startElement)
filename
A string value, the filename to assign to the uploaded file. Optional, if not provided the filename
will be taken from the provided ``file`` object's ``name`` property.
select
A boolean value, specifies whether to immediately select the uploaded file for printing once
the upload completes (true) or not (false, default)
print
A boolean value, specifies whether to immediately start printing the file after the upload
completes (true) or not (false, default)
userdata
An optional object or a serialized JSON string of additional user supplised data to associate with
the uploaded file.
See :ref:`Upload file <sec-api-fileops-uploadfile>` for more details on the file upload API and
:js:func:`OctoPrint.upload` for more details on the underlying library upload mechanism, including
what values are accepted for the ``file`` parameter.
:param string location: The location to upload the file to
:param object or string file: The file to upload, either a
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
.. js:function:: OctoPrint.files.download(location, path, opts)
Downloads the file at ``path`` in ``location``.
The downloaded file will be returned as response body in the completed `Promise <http://api.jquery.com/Types/#Promise>`_.
Note that not all locations support downloading of files (``sdcard`` for example doesn't).
**Example:**
.. code-block:: javascript
OctoPrint.files.download("local", "somefile.gco")
.done(function(response) {
var contents = response;
// do something with the file contents
});
:param string location: The location of the file to download
:param string path: The path of the file to download
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response

4
docs/jsclientlib/printer.rst
View file

@ -297,6 +297,8 @@
Instructs the printer to refresh the list of files on the SD card (if present).
See the ``refresh`` command in :ref:`Issue an SD command <sec-api-printer-sdcommand>` for more details.
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response
@ -304,6 +306,8 @@
Instructs the printer to release its SD card (if present).
See the ``release`` command in :ref:`Issue an SD command <sec-api-printer-sdcommand>` for more details.
:param object opts: Additional options for the request
:returns Promise: A `jQuery Promise <http://api.jquery.com/Types/#Promise>`_ for the request's response