Documented SockJS interface, deprecated /api/state
This commit is contained in:
Gina Häußge
parent
587053b26c
commit
522eb40808
14 changed files with 490 additions and 355 deletions
348
docs/api/datamodel.rst
Normal file
348
docs/api/datamodel.rst
Normal file
|
|
@ -0,0 +1,348 @@
|
|||
.. _sec-api-datamodel:
|
||||
|
||||
*****************
|
||||
Common data model
|
||||
*****************
|
||||
|
||||
.. contents::
|
||||
|
||||
.. _sec-api-datamodel-printer:
|
||||
|
||||
Printer related
|
||||
===============
|
||||
|
||||
.. _sec-api-datamodel-printer-state:
|
||||
|
||||
Printer State
|
||||
-------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``text``
|
||||
- 1
|
||||
- String
|
||||
- A textual representation of the current state of the printer, e.g. "Operational" or "Printing"
|
||||
* - ``flags``
|
||||
- 1
|
||||
- Printer state flags
|
||||
- A couple of boolean printer state flags
|
||||
* - ``flags.operational``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer is operational, ``false`` otherwise
|
||||
* - ``flags.paused``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer is currently paused, ``false`` otherwise
|
||||
* - ``flags.printing``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer is currently printing, ``false`` otherwise
|
||||
* - ``flags.sdReady``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer's SD card is available and initialized, ``false`` otherwise. This is redundant information
|
||||
to :ref:`the SD State <sec-api-printer-datamodel-sdstate>`.
|
||||
* - ``flags.error``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if an unrecoverable error occurred, ``false`` otherwise
|
||||
* - ``flags.ready``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer is operational and no data is currently being streamed to SD, so ready to receive instructions
|
||||
* - ``flags.closedOrError``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer is disconnected (possibly due to an error), ``false`` otherwise
|
||||
|
||||
.. _sec-api-datamodel-printer-tempdata:
|
||||
|
||||
Temperature Data
|
||||
----------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``actual``
|
||||
- 1
|
||||
- Number
|
||||
- Current temperature
|
||||
* - ``target``
|
||||
- 1
|
||||
- Number
|
||||
- Target temperature, may be ``null`` if no target temperature is set.
|
||||
* - ``offset``
|
||||
- 0..1
|
||||
- Number
|
||||
- Currently configured temperature offset to apply, will be left out for historic temperature information.
|
||||
|
||||
.. _sec-api-datamodel-printer-temphistory:
|
||||
|
||||
Historic Temperature Data Point
|
||||
-------------------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``time``
|
||||
- 1
|
||||
- Unix Timestamp
|
||||
- Timestamp of this data point
|
||||
* - ``tool{n}``
|
||||
- 0..*
|
||||
- :ref:`Temperature Data <sec-api-datamodel-printer-tempdata>`
|
||||
- Temperature stats for tool *n*. Enumeration starts at 0 for the first tool. Not included if querying only
|
||||
bed state.
|
||||
* - ``bed``
|
||||
- 0..*
|
||||
- :ref:`Temperature Data <sec-api-datamodel-printer-tempdata>`
|
||||
- Temperature stats for the printer's heated bed. Not included if querying only tool state.
|
||||
|
||||
.. _sec-api-datamodel-printer-tempoffset:
|
||||
|
||||
Temperature offset
|
||||
------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``tool{n}``
|
||||
- 0..1
|
||||
- Number
|
||||
- Temperature offset for tool *n*. Enumeration starts at 0 for the first tool.
|
||||
* - ``bed``
|
||||
- 0..1
|
||||
- Number
|
||||
- Temperature offset for the printer's heated bed.
|
||||
|
||||
|
||||
.. _sec-api-datamodel-jobs:
|
||||
|
||||
Job related
|
||||
===========
|
||||
|
||||
.. _sec-api-datamodel-jobs-job:
|
||||
|
||||
Job information
|
||||
---------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``file``
|
||||
- 1
|
||||
- :ref:`File information (abridged) <sec-api-datamodel-files-file>`
|
||||
- The file that is the target of the current print job
|
||||
* - ``estimatedPrintTime``
|
||||
- 0..1
|
||||
- Integer
|
||||
- The estimated print time for the file, in seconds.
|
||||
* - ``filament``
|
||||
- 0..1
|
||||
- Object
|
||||
- Information regarding the estimated filament usage of the print job
|
||||
* - ``filament.length``
|
||||
- 0..1
|
||||
- Integer
|
||||
- Length of filament used, in mm
|
||||
* - ``filament.volume``
|
||||
- 0..1
|
||||
- Float
|
||||
- Volume of filament used, in cm³
|
||||
|
||||
.. _sec-api-datamodel-jobs-progress:
|
||||
|
||||
Progress information
|
||||
--------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``completion``
|
||||
- 1
|
||||
- Float
|
||||
- Percentage of completion of the current print job
|
||||
* - ``filepos``
|
||||
- 1
|
||||
- Integer
|
||||
- Current position in the file being printed, in bytes from the beginning
|
||||
* - ``printTime``
|
||||
- 1
|
||||
- Integer
|
||||
- Time already spent printing, in seconds
|
||||
* - ``printTimeLeft``
|
||||
- 1
|
||||
- Integer
|
||||
- Estimate of time left to print, in seconds
|
||||
|
||||
.. _sec-api-datamodel-files:
|
||||
|
||||
File related
|
||||
============
|
||||
|
||||
.. _sec-api-datamodel-files-file:
|
||||
|
||||
File information
|
||||
----------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``name``
|
||||
- 1
|
||||
- String
|
||||
- The name of the file
|
||||
* - ``size``
|
||||
- 0..1
|
||||
- Number
|
||||
- The size of the file in bytes. Only available for ``local`` files.
|
||||
* - ``date``
|
||||
- 0..1
|
||||
- Unix timestamp
|
||||
- The timestamp when this file 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-datamodel-files-ref`
|
||||
- References relevant to this file, left out in abridged version
|
||||
* - ``gcodeAnalysis``
|
||||
- 0..1
|
||||
- :ref:`GCODE analysis information <sec-api-datamodel-files-gcodeanalysis>`
|
||||
- Information from the analysis of the GCODE file, if available. Left out in abridged version.
|
||||
* - ``prints``
|
||||
- 0..1
|
||||
- :ref:`Print history <sec-api-datamodel-files-prints>`
|
||||
- Information regarding prints of this file, if available. Left out in abridged version.
|
||||
|
||||
.. _sec-api-datamodel-files-gcodeanalysis:
|
||||
|
||||
GCODE analysis information
|
||||
--------------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``estimatedPrintTime``
|
||||
- 0..1
|
||||
- Integer
|
||||
- The estimated print time of the file, in seconds
|
||||
* - ``filament``
|
||||
- 0..1
|
||||
- Object
|
||||
- The estimated usage of filament
|
||||
* - ``filament.length``
|
||||
- 0..1
|
||||
- Integer
|
||||
- The length of filament used, in mm
|
||||
* - ``filament.volume``
|
||||
- 0..1
|
||||
- Float
|
||||
- The volume of filament used, in cm³
|
||||
|
||||
|
||||
.. _sec-api-datamodel-files-prints:
|
||||
|
||||
Print history
|
||||
-------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``failure``
|
||||
- 1
|
||||
- Number
|
||||
- The number of failed prints on record for the file
|
||||
* - ``success``
|
||||
- 1
|
||||
- Number
|
||||
- The number of successful prints on record for the file
|
||||
* - ``last``
|
||||
- 0..1
|
||||
- Object
|
||||
- Information regarding the last print on record for the file
|
||||
* - ``last.date``
|
||||
- 1
|
||||
- Unix timestamp
|
||||
- Timestamp when this file was printed last
|
||||
* - ``last.success``
|
||||
- 1
|
||||
- Boolean
|
||||
- Whether the last print on record was a success (``true``) or not (``false``)
|
||||
|
||||
.. _sec-api-datamodel-files-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)
|
||||
|
||||
|
|
@ -240,7 +240,7 @@ Retrieve a specific file's information
|
|||
|
||||
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>`
|
||||
On success, a :http:statuscode:`200` is returned, with a :ref:`file information item <sec-api-datamodel-files-file>`
|
||||
as the response body.
|
||||
|
||||
**Example**
|
||||
|
|
@ -383,7 +383,7 @@ Retrieve response
|
|||
- Description
|
||||
* - ``files``
|
||||
- 0..*
|
||||
- Array of :ref:`File information items <sec-api-fileops-datamodel-fileinfo>`
|
||||
- Array of :ref:`File information items <sec-api-datamodel-files-file>`
|
||||
- The list of requested files. Might be an empty list if no files are available
|
||||
* - ``free``
|
||||
- 0..1
|
||||
|
|
@ -411,12 +411,12 @@ Upload response
|
|||
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`
|
||||
- :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).
|
||||
* - ``files.sdcard``
|
||||
- 0..1
|
||||
- :ref:`sec-api-fileops-datamodel-fileinfo`
|
||||
- :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).
|
||||
* - ``done``
|
||||
|
|
@ -426,136 +426,3 @@ Upload response
|
|||
to perform a slicing step (``false``). Clients may use this information to direct progress displays related to
|
||||
the upload.
|
||||
|
||||
.. _sec-api-fileops-datamodel-fileinfo:
|
||||
|
||||
File information
|
||||
----------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``name``
|
||||
- 1
|
||||
- String
|
||||
- The name of the file
|
||||
* - ``size``
|
||||
- 0..1
|
||||
- Number
|
||||
- The size of the file in bytes. Only available for ``local`` files.
|
||||
* - ``date``
|
||||
- 0..1
|
||||
- Unix timestamp
|
||||
- The timestamp when this file 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>`
|
||||
- Information from the analysis of the GCODE file, if available.
|
||||
* - ``prints``
|
||||
- 0..1
|
||||
- :ref:`Print information <sec-api-fileops-datamodel-prints>`
|
||||
- Information regarding prints of this file, if available.
|
||||
|
||||
.. _sec-api-fileops-datamodel-gcodeanalysis:
|
||||
|
||||
GCODE analysis information
|
||||
--------------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``estimatedPrintTime``
|
||||
- 0..1
|
||||
- Integer
|
||||
- The estimated print time of the file, in seconds
|
||||
* - ``filament``
|
||||
- 0..1
|
||||
- Object
|
||||
- The estimated usage of filament
|
||||
* - ``filament.length``
|
||||
- 0..1
|
||||
- Integer
|
||||
- The length of filament used, in mm
|
||||
* - ``filament.volume``
|
||||
- 0..1
|
||||
- Float
|
||||
- The volume of filament used, in cm³
|
||||
|
||||
|
||||
.. _sec-api-fileops-datamodel-prints:
|
||||
|
||||
Print information
|
||||
-----------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``failure``
|
||||
- 1
|
||||
- Number
|
||||
- The number of failed prints on record for the file
|
||||
* - ``success``
|
||||
- 1
|
||||
- Number
|
||||
- The number of successful prints on record for the file
|
||||
* - ``last``
|
||||
- 0..1
|
||||
- Object
|
||||
- Information regarding the last print on record for the file
|
||||
* - ``last.date``
|
||||
- 1
|
||||
- Unix timestamp
|
||||
- Timestamp when this file was printed last
|
||||
* - ``last.success``
|
||||
- 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)
|
||||
|
|
|
|||
|
|
@ -13,3 +13,5 @@ API Documentation
|
|||
printer.rst
|
||||
job.rst
|
||||
logs.rst
|
||||
sockjs.rst
|
||||
datamodel.rst
|
||||
|
|
|
|||
|
|
@ -174,90 +174,10 @@ Job information response
|
|||
- Description
|
||||
* - ``job``
|
||||
- 1
|
||||
- :ref:`sec-api-job-datamodel-job`
|
||||
- :ref:`sec-api-datamodel-jobs-job`
|
||||
- Information regarding the target of the current print job
|
||||
* - ``progress``
|
||||
- 1
|
||||
- :ref:`sec-api-job-datamodel-progress`
|
||||
- :ref:`sec-api-datamodel-jobs-progress`
|
||||
- Information regarding the progress of the current print job
|
||||
|
||||
.. _sec-api-job-datamodel-job:
|
||||
|
||||
Job information
|
||||
---------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``file``
|
||||
- 1
|
||||
- Object
|
||||
- The file that is the target of the current print job
|
||||
* - ``file.name``
|
||||
- 1
|
||||
- String
|
||||
- The file's name
|
||||
* - ``file.origin``
|
||||
- 1
|
||||
- String, either ``local`` or ``sdcard``
|
||||
- The file's origin, either ``local`` or ``sdcard``
|
||||
* - ``file.size``
|
||||
- 0..1
|
||||
- Integer
|
||||
- The file's size, in bytes. Only available for files stored locally.
|
||||
* - ``file.date``
|
||||
- 0..1
|
||||
- Unix timestamp
|
||||
- The file's upload date. Only available for files stored locally.
|
||||
* - ``estimatedPrintTime``
|
||||
- 0..1
|
||||
- Integer
|
||||
- The estimated print time for the file, in seconds.
|
||||
* - ``filament``
|
||||
- 0..1
|
||||
- Object
|
||||
- Information regarding the estimated filament usage of the print job
|
||||
* - ``filament.length``
|
||||
- 0..1
|
||||
- Integer
|
||||
- Length of filament used, in mm
|
||||
* - ``filament.volume``
|
||||
- 0..1
|
||||
- Float
|
||||
- Volume of filament used, in cm³
|
||||
|
||||
.. _sec-api-job-datamodel-progress:
|
||||
|
||||
Progress information
|
||||
--------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``completion``
|
||||
- 1
|
||||
- Float
|
||||
- Percentage of completion of the current print job
|
||||
* - ``filepos``
|
||||
- 1
|
||||
- Integer
|
||||
- Current position in the file being printed, in bytes from the beginning
|
||||
* - ``printTime``
|
||||
- 1
|
||||
- Integer
|
||||
- Time already spent printing, in seconds
|
||||
* - ``printTimeLeft``
|
||||
- 1
|
||||
- Integer
|
||||
- Estimate of time left to print, in seconds
|
||||
|
||||
|
|
|
|||
|
|
@ -801,71 +801,18 @@ Temperature State
|
|||
- Description
|
||||
* - ``tool{n}``
|
||||
- 0..*
|
||||
- :ref:`Temperature Data <sec-api-printer-datamodel-tempdata>`
|
||||
- :ref:`Temperature Data <sec-api-datamodel-printer-tempdata>`
|
||||
- Current temperature stats for tool *n*. Enumeration starts at 0 for the first tool. Not included if querying
|
||||
only bed state.
|
||||
* - ``bed``
|
||||
- 0..1
|
||||
- :ref:`Temperature Data <sec-api-printer-datamodel-tempdata>`
|
||||
- :ref:`Temperature Data <sec-api-datamodel-printer-tempdata>`
|
||||
- Current temperature stats for the printer's heated bed. Not included if querying only tool state.
|
||||
* - ``history``
|
||||
- 0..1
|
||||
- List of :ref:`Historic Temperature Datapoint <sec-api-printer-datamodel-temphistory>`
|
||||
- List of :ref:`Historic Temperature Datapoint <sec-api-datamodel-printer-temphistory>`
|
||||
- Temperature history
|
||||
|
||||
.. _sec-api-printer-datamodel-temphistory:
|
||||
|
||||
Historic Temperature Data Point
|
||||
-------------------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``time``
|
||||
- 1
|
||||
- Unix Timestamp
|
||||
- Timestamp of this data point
|
||||
* - ``tool{n}``
|
||||
- 0..*
|
||||
- :ref:`Temperature Data <sec-api-printer-datamodel-tempdata>`
|
||||
- Temperature stats for tool *n*. Enumeration starts at 0 for the first tool. Not included if querying only
|
||||
bed state.
|
||||
* - ``bed``
|
||||
- 0..*
|
||||
- :ref:`Temperature Data <sec-api-printer-datamodel-tempdata>`
|
||||
- Temperature stats for the printer's heated bed. Not included if querying only tool state.
|
||||
|
||||
.. _sec-api-printer-datamodel-tempdata:
|
||||
|
||||
Temperature Data
|
||||
----------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``actual``
|
||||
- 1
|
||||
- Number
|
||||
- Current temperature
|
||||
* - ``target``
|
||||
- 1
|
||||
- Number
|
||||
- Target temperature, may be ``null`` if no target temperature is set.
|
||||
* - ``offset``
|
||||
- 0..1
|
||||
- Number
|
||||
- Currently configured temperature offset to apply, will be left out for historic temperature information.
|
||||
|
||||
.. _sec-api-printer-datamodel-sdstate:
|
||||
|
||||
SD State
|
||||
|
|
@ -884,53 +831,3 @@ SD State
|
|||
- Boolean
|
||||
- Whether the SD card has been initialized (``true``) or not (``false``).
|
||||
|
||||
.. _sec-api-printer-datamodel-printerstate:
|
||||
|
||||
Printer State
|
||||
-------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``text``
|
||||
- 1
|
||||
- String
|
||||
- A textual representation of the current state of the printer, e.g. "Operational" or "Printing"
|
||||
* - ``flags``
|
||||
- 1
|
||||
- Printer state flags
|
||||
- A couple of boolean printer state flags
|
||||
* - ``flags.operational``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer is operational, ``false`` otherwise
|
||||
* - ``flags.paused``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer is currently paused, ``false`` otherwise
|
||||
* - ``flags.printing``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer is currently printing, ``false`` otherwise
|
||||
* - ``flags.sdReady``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer's SD card is available and initialized, ``false`` otherwise. This is redundant information
|
||||
to :ref:`the SD State <sec-api-printer-datamodel-sdstate>`.
|
||||
* - ``flags.error``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if an unrecoverable error occurred, ``false`` otherwise
|
||||
* - ``flags.ready``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer is operational and no data is currently being streamed to SD, so ready to receive instructions
|
||||
* - ``flags.closedOrError``
|
||||
- 1
|
||||
- Boolean
|
||||
- ``true`` if the printer is disconnected (possibly due to an error), ``false`` otherwise
|
||||
|
|
|
|||
114
docs/api/sockjs.rst
Normal file
114
docs/api/sockjs.rst
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
.. _sec-api-push:
|
||||
|
||||
************
|
||||
Push updates
|
||||
************
|
||||
|
||||
.. warning::
|
||||
|
||||
The interface documented here is the status quo that might be changed while the interfaces are streamlined for
|
||||
a more general consumption. If you happen to want to develop against it, you should drop me an email to make sure I can give you a heads-up when
|
||||
something changes.
|
||||
|
||||
.. contents::
|
||||
|
||||
To enable real time information exchange between client and server, OctoPrint uses
|
||||
`SockJS <https://github.com/sockjs/sockjs-protocol>`_ to push
|
||||
status updates, temperature changes etc to connected web interface instances.
|
||||
|
||||
Each pushed message consists of a simple JSON object that follows this basic structure:
|
||||
|
||||
.. sourcecode:: javascript
|
||||
|
||||
{
|
||||
"<type>": <payload>
|
||||
}
|
||||
|
||||
``type`` indicates the type of message being pushed to the client, the attached ``payload`` is message specific. The
|
||||
following message types are currently available for usage by 3rd party clients:
|
||||
|
||||
* ``current``: Rate limited general state update, payload contains information about the printer's state, job progress,
|
||||
accumulated temperature points and log lines since last update. OctoPrint will send these updates when new information
|
||||
is available, but not more often than twice per second in order to not flood the client with messages (e.g.
|
||||
during printing). See :ref:`the payload data model <sec-api-push-datamodel-currentandhistory>`.
|
||||
* ``history``: Current state, temperature and log history, sent upon initial connect to get the client up to date. Same
|
||||
payload data model as ``current``, see :ref:`below <sec-api-push-datamodel-currentandhistory>`.
|
||||
* ``event``: Events triggered within OctoPrint, such as e.g. ``PrintFailed`` or ``MovieRenderDone``. Payload is the event
|
||||
type and payload, see :ref:`below <sec-api-push-datamodel-event>`. Sent when an event is triggered internally.
|
||||
|
||||
Clients must ignore any unknown messages.
|
||||
|
||||
The data model of the attached payloads is described further below.
|
||||
|
||||
.. _sec-api-push-datamodel:
|
||||
|
||||
Datamodel
|
||||
=========
|
||||
|
||||
.. _sec-api-push-datamodel-currentandhistory:
|
||||
|
||||
``current`` and ``history`` payload
|
||||
-----------------------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``state``
|
||||
- 1
|
||||
- :ref:`State information <sec-api-datamodel-printer-state>`
|
||||
- Information about the current machine state
|
||||
* - ``job``
|
||||
- 1
|
||||
- :ref:`Job information <sec-api-datamodel-jobs-job>`
|
||||
- Information about the currently active print job
|
||||
* - ``progress``
|
||||
- 1
|
||||
- :ref:`Progress information <sec-api-datamodel-jobs-progress>`
|
||||
- Information about the current print/streaming progress
|
||||
* - ``currentZ``
|
||||
- 1
|
||||
- Float
|
||||
- Current height of the Z-Axis (= current height of model) during printing from a local file
|
||||
* - ``offsets``
|
||||
- 0..1
|
||||
- :ref:`Temperature offsets <sec-api-datamodel-printer-tempoffset>`
|
||||
- Currently configured temperature offsets
|
||||
* - ``temps``
|
||||
- 0..*
|
||||
- List of :ref:`Temperature Data Points <sec-api-datamodel-printer-temphistory>`
|
||||
- Temperature data points for plotting
|
||||
* - ``logs``
|
||||
- 0..*
|
||||
- List of String
|
||||
- Lines for the serial communication log (send/receive)
|
||||
* - ``messages``
|
||||
- 0..*
|
||||
- List of String
|
||||
- Lines for the serial communication log (special messages)
|
||||
|
||||
.. _sec-api-push-datamodel-event:
|
||||
|
||||
``event`` payload
|
||||
-----------------
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 5 10 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Multiplicity
|
||||
- Type
|
||||
- Description
|
||||
* - ``type``
|
||||
- 1
|
||||
- String
|
||||
- Name of the event
|
||||
* - ``payload``
|
||||
- 1
|
||||
- Object
|
||||
- Payload associated with the event
|
||||
|
|
@ -1,8 +1,3 @@
|
|||
.. OctoPrint documentation master file, created by
|
||||
sphinx-quickstart on Mon Dec 02 17:08:50 2013.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
#####################################
|
||||
Welcome to OctoPrint's documentation!
|
||||
#####################################
|
||||
|
|
@ -11,7 +6,7 @@ Welcome to OctoPrint's documentation!
|
|||
: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
|
||||
This is a work in progress. The goal is to document OctoPrint's REST API, event system, configuration etc in a way that
|
||||
allows different documentation per development branch in Git, which so far did not scale well with the Github-Wiki-based
|
||||
approach.
|
||||
|
||||
|
|
@ -22,4 +17,3 @@ Contents
|
|||
:maxdepth: 2
|
||||
|
||||
api/index.rst
|
||||
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ class Printer():
|
|||
addMessageCallback=self._sendAddMessageCallbacks
|
||||
)
|
||||
self._stateMonitor.reset(
|
||||
state={"state": None, "stateString": self.getStateString(), "flags": self._getStateFlags()},
|
||||
state={"text": self.getStateString(), "flags": self._getStateFlags()},
|
||||
jobData={
|
||||
"file": {
|
||||
"name": None,
|
||||
|
|
@ -323,7 +323,7 @@ class Printer():
|
|||
|
||||
def _setState(self, state):
|
||||
self._state = state
|
||||
self._stateMonitor.setState({"state": self._state, "stateString": self.getStateString(), "flags": self._getStateFlags()})
|
||||
self._stateMonitor.setState({"text": self.getStateString(), "flags": self._getStateFlags()})
|
||||
|
||||
def _addLog(self, log):
|
||||
self._log.append(log)
|
||||
|
|
@ -410,9 +410,9 @@ class Printer():
|
|||
try:
|
||||
data = self._stateMonitor.getCurrentData()
|
||||
data.update({
|
||||
"tempHistory": list(self._temps),
|
||||
"logHistory": list(self._log),
|
||||
"messageHistory": list(self._messages)
|
||||
"temps": list(self._temps),
|
||||
"logs": list(self._log),
|
||||
"messages": list(self._messages)
|
||||
})
|
||||
callback.sendHistoryData(data)
|
||||
except Exception, err:
|
||||
|
|
@ -492,7 +492,7 @@ class Printer():
|
|||
self._setCurrentZ(newZ)
|
||||
|
||||
def mcSdStateChange(self, sdReady):
|
||||
self._stateMonitor.setState({"state": self._state, "stateString": self.getStateString(), "flags": self._getStateFlags()})
|
||||
self._stateMonitor.setState({"text": self.getStateString(), "flags": self._getStateFlags()})
|
||||
|
||||
def mcSdFiles(self, files):
|
||||
eventManager().fire(Events.UPDATED_FILES, {"type": "gcode"})
|
||||
|
|
@ -500,21 +500,21 @@ class Printer():
|
|||
|
||||
def mcFileSelected(self, filename, filesize, sd):
|
||||
self._setJobData(filename, filesize, sd)
|
||||
self._stateMonitor.setState({"state": self._state, "stateString": self.getStateString(), "flags": self._getStateFlags()})
|
||||
self._stateMonitor.setState({"text": self.getStateString(), "flags": self._getStateFlags()})
|
||||
|
||||
if self._printAfterSelect:
|
||||
self.startPrint()
|
||||
|
||||
def mcPrintjobDone(self):
|
||||
self._setProgressData(1.0, self._selectedFile["filesize"], self._comm.getPrintTime(), 0)
|
||||
self._stateMonitor.setState({"state": self._state, "stateString": self.getStateString(), "flags": self._getStateFlags()})
|
||||
self._stateMonitor.setState({"text": self.getStateString(), "flags": self._getStateFlags()})
|
||||
|
||||
def mcFileTransferStarted(self, filename, filesize):
|
||||
self._sdStreaming = True
|
||||
|
||||
self._setJobData(filename, filesize, True)
|
||||
self._setProgressData(0.0, 0, 0, None)
|
||||
self._stateMonitor.setState({"state": self._state, "stateString": self.getStateString(), "flags": self._getStateFlags()})
|
||||
self._stateMonitor.setState({"text": self.getStateString(), "flags": self._getStateFlags()})
|
||||
|
||||
def mcFileTransferDone(self, filename):
|
||||
self._sdStreaming = False
|
||||
|
|
@ -526,7 +526,7 @@ class Printer():
|
|||
self._setCurrentZ(None)
|
||||
self._setJobData(None, None, None)
|
||||
self._setProgressData(None, None, None, None)
|
||||
self._stateMonitor.setState({"state": self._state, "stateString": self.getStateString(), "flags": self._getStateFlags()})
|
||||
self._stateMonitor.setState({"text": self.getStateString(), "flags": self._getStateFlags()})
|
||||
|
||||
def mcReceivedRegisteredMessage(self, command, output):
|
||||
self._sendFeedbackCommandOutput(command, output)
|
||||
|
|
|
|||
|
|
@ -132,11 +132,7 @@ def firstRunSetup():
|
|||
@api.route("/state", methods=["GET"])
|
||||
@restricted_access
|
||||
def apiPrinterState():
|
||||
currentData = octoprint.server.printer.getCurrentData()
|
||||
currentData.update({
|
||||
"temperatures": octoprint.server.printer.getCurrentTemperatures()
|
||||
})
|
||||
return jsonify(currentData)
|
||||
return make_response(("/api/state has been deprecated, use /api/printer instead", 405, []))
|
||||
|
||||
|
||||
#~~ system control
|
||||
|
|
|
|||
|
|
@ -53,5 +53,5 @@ def jobState():
|
|||
return jsonify({
|
||||
"job": currentData["job"],
|
||||
"progress": currentData["progress"],
|
||||
"state": currentData["state"]["stateString"]
|
||||
"state": currentData["state"]["text"]
|
||||
})
|
||||
|
|
@ -38,10 +38,7 @@ def printerState():
|
|||
# add state information
|
||||
if not "state" in excludes:
|
||||
state = printer.getCurrentData()["state"]
|
||||
result.update({"state": {
|
||||
"text": state["stateString"],
|
||||
"flags": state["flags"]
|
||||
}})
|
||||
result.update({"state": state})
|
||||
|
||||
return jsonify(result)
|
||||
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@ function PrinterStateViewModel(loginStateViewModel) {
|
|||
}
|
||||
|
||||
self._processStateData = function(data) {
|
||||
self.stateString(data.stateString);
|
||||
self.stateString(data.text);
|
||||
self.isErrorOrClosed(data.flags.closedOrError);
|
||||
self.isOperational(data.flags.operational);
|
||||
self.isPaused(data.flags.paused);
|
||||
|
|
|
|||
|
|
@ -118,7 +118,7 @@ function TemperatureViewModel(loginStateViewModel, settingsViewModel) {
|
|||
|
||||
self.fromHistoryData = function(data) {
|
||||
self._processStateData(data.state);
|
||||
self._processTemperatureHistoryData(data.tempHistory);
|
||||
self._processTemperatureHistoryData(data.temps);
|
||||
self._processOffsetData(data.offsets);
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ function TerminalViewModel(loginStateViewModel, settingsViewModel) {
|
|||
|
||||
self.fromHistoryData = function(data) {
|
||||
self._processStateData(data.state);
|
||||
self._processHistoryLogData(data.logHistory);
|
||||
self._processHistoryLogData(data.logs);
|
||||
};
|
||||
|
||||
self._processCurrentLogData = function(data) {
|
||||
|
|
|
|||
Loading…
Reference in a new issue