115 lines
3.6 KiB
ReStructuredText
115 lines
3.6 KiB
ReStructuredText
|
.. _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
|