MrDraw/docs/events/index.rst

.. _sec-events:

######
Events
######

.. contents::


.. note::

   With release of OctoPrint 1.1.0, the payload data has been harmonized, it is now a key-value-map for all events.
   Additionally, the format of the placeholders in both system command and gcode command triggers has been changed to
   accommodate for this new format. Last but not least, the way of specifying event hooks has changed, OctoPrint no longer
   separates hooks into two sections (gcodeCommandTrigger and systemCommandTrigger) but instead event hooks are now typed
   to indicate what to do with the command contained.

.. _sec-events-configuration:

Configuration
=============

Event hooks are configured via OctoPrint's configuration file ``config.yaml``. There they are contained in a
``subscriptions`` list located directly under the ``events`` node. The ``command`` node accepts either a single string
or a list of strings so that multiple commands can be executed in one go. Each hook carries an additional node type that
must be either ``gcode`` (for GCODE commands to be sent to the printer based on the event) or ``system`` (for commands to be
executed on the system OctoPrint is running on).

All event hooks can be disabled completely by setting ``event > enabled`` to ``false``. You can also disable individual
hooks by setting the (optional) node ``enabled`` to false, see the example below.

Example
-------

.. sourcecode:: yaml

   events:
     enabled: True
     subscriptions:
     - event: Disconnected
       command: python ~/growl.py -t mygrowlserver -d "Lost connection to printer" -a OctoPrint -i http://raspi/Octoprint_logo.png
       type: system
       enabled: false
     - event: PrintStarted
       command: python ~/growl.py -t mygrowlserver -d "Starting {file}" -a OctoPrint -i http://raspi/Octoprint_logo.png
       type: system
     - event: PrintDone
       command: python ~/growl.py -t mygrowlserver -d "Completed {file}" -a OctoPrint -i http://raspi/Octoprint_logo.png
       type: system
     - event: Connected
       command:
       - M115
       - M117 printer connected!
       - G28
       type: gcode

.. _sec-events-placeholders:

Placeholders
============

You can use the following generic placeholders in your event hooks:

  * ``{__currentZ}``: the current Z position of the head if known, -1 if not available
  * ``{__filename}`` : name of currently selected file, or ``NO FILE`` if no file is selected
  * ``{__filepath}`` : path in origin location of currently selected file, or ``NO FILE`` if no file is selected
  * ``{__fileorigin}`` : origin of currently selected file, or ``NO FILE`` if no file is selected
  * ``{__progress}``: the progress of the print in percent, 0 if not available
  * ``{__data}``: a string representation of the payload
  * ``{__now}``: the date and time of the event in ISO 8601

Additionally, all data from the payload can be accessed by its key. Example: If the payload happens to be defined
something like this:

  * ``name``: the file's name
  * ``path``: the file's path in its origin storage location
  * ``origin``: the origin storage location of the file, either ``local`` or ``sdcard``

then you'll be able to access the file's name via the placeholder ``{name}``, its path via the placeholder ``{path}``
and its origin via the placeholder ``{origin}``.


.. _sec-events-available_events:

Available Events
================

Server
------

Startup
   The server has started.

Shutdown
   The server is shutting down.

ClientOpened
   A client has connected to the web server.

   Payload:

     * ``remoteAddress``: the remote address (IP) of the client that connected

   **Note:** Name changed in version 1.1.0

ClientClosed
   A client has disconnected from the webserver

   Payload:

     * ``remoteAddress``: the remote address (IP) of the client that disconnected

ConnectivityChanged
   The server's internet connectivity changed

   Payload:

     * ``old``: Old connectivity value (true for online, false for offline)
     * ``new``: New connectivity value (true for online, false for offline)

Printer communication
---------------------

Connecting
   The server is attempting to connect to the printer.

Connected
   The server has connected to the printer.

   Payload:

     * ``port``: the connected serial port
     * ``baudrate``: the baud rate

Disconnecting
   The server is going to disconnect from the printer. Note that this
   event might not always be sent when the server and printer get disconnected
   from each other. Do not depend on this for critical life cycle management.

Disconnected
   The server has disconnected from the printer

Error
   An error has occurred in the printer communication.

   Payload:

     * ``error``: the error string

PrinterStateChanged
   The state of the printer changed.

   Payload:

     * ``state_id``: Id of the new state. See
       :func:`~octoprint.printer.PrinterInterface.get_state_id` for possible values.
     * ``state_string``: Text representation of the new state.

File handling
-------------

Upload
   A file has been uploaded through the web interface.

   Payload:
     * ``name``: the file's name
     * ``path``: the file's path within its storage location
     * ``target``: the target storage location to which the file was uploaded, either ``local`` or ``sdcard``

   .. deprecated:: 1.3.0

        * ``file``: the file's path within its storage location

      Still available for reasons of backwards compatibility. Will be removed with 1.4.0.

FileAdded
   A file has been added to a storage.

   Payload:
     * ``storage``: the storage's identifier
     * ``path``: the file's path within its storage location
     * ``name``: the file's name
     * ``type``: the file's type, a list of the path within the type hierarchy, e.g. ``["machinecode", "gcode"]`` or
       ``["model", "stl"]``

   .. note::

      A copied file triggers this for its new path. A moved file first triggers ``FileRemoved`` for its original
      path and then ``FileAdded`` for the new one.

FileRemoved
   A file has been removed from a storage.

   Payload:
     * ``storage``: the storage's identifier
     * ``path``: the file's path within its storage location
     * ``name``: the file's name
     * ``type``: the file's type, a list of the path within the type hierarchy, e.g. ``["machinecode", "gcode"]`` or
       ``["model", "stl"]``

   .. note::

      A moved file first triggers ``FileRemoved`` for its original path and then ``FileAdded`` for the new one.

FolderAdded
   A folder has been added to a storage.

   Payload:
     * ``storage``: the storage's identifier
     * ``path``: the folders's path within its storage location
     * ``name``: the folders's name

   .. note::

      A copied folder triggers this for its new path. A moved folder first triggers ``FolderRemoved`` for its original
      path and then ``FolderAdded`` for the new one.

FolderRemoved
   A folder has been removed from a storage.

   Payload:
     * ``storage``: the storage's identifier
     * ``path``: the folders's path within its storage location
     * ``name``: the folders's name

   .. note::

      A moved folder first triggers ``FolderRemoved`` for its original path and then ``FolderAdded`` for the new one.

UpdatedFiles
   A file list was modified.

   Payload:

     * ``type``: the type of file list that was modified. Only ``printables`` is supported here. See the deprecation
       note below.

       .. deprecated:: 1.2.0

          The ``gcode`` modification type has been superceeded by ``printables``. It is currently still available for
          reasons of backwards compatibility and will also be sent on modification of ``printables``. It will however
          be removed with 1.4.0.


MetadataAnalysisStarted
   The metadata analysis of a file has started.

   Payload:

     * ``name``: the file's name
     * ``path``: the file's path within its storage location
     * ``origin``: the file's origin storage location

   .. deprecated:: 1.3.0

        * ``file``: the file's path within its storage location

      Still available for reasons of backwards compatibility. Will be removed with 1.4.0.

MetadataAnalysisFinished
   The metadata analysis of a file has finished.

   Payload:

     * ``name``: the file's name
     * ``path``: the file's path within its storage location
     * ``origin``: the file's origin storage location
     * ``result``: the analysis result -- this is a python object currently only available for internal use

   .. deprecated:: 1.3.0

        * ``file``: the file's path within its storage location

      Still available for reasons of backwards compatibility. Will be removed with 1.4.0.

FileSelected
   A file has been selected for printing.

   Payload:

     * ``name``: the file's name
     * ``path``: the file's path within its storage location
     * ``origin``: the origin storage location of the file, either ``local`` or ``sdcard``

   .. deprecated:: 1.3.0

        * ``file``: the file's full path on disk (``local``) or within its storage (``sdcard``)
        * ``filename``: the file's name

      Still available for reasons of backwards compatibility. Will be removed with 1.4.0.

FileDeselected
   No file is selected any more for printing.

TransferStarted
   A file transfer to the printer's SD has started.

   Payload:

     * ``local``: the file's name as stored locally
     * ``remote``: the file's name as stored on SD

   **Note:** Name changed in version 1.1.0

TransferDone
   A file transfer to the printer's SD has finished.

   Payload:

     * ``time``: the time it took for the transfer to complete in seconds
     * ``local``: the file's name as stored locally
     * ``remote``: the file's name as stored on SD

Printing
--------

PrintStarted
   A print has started.

   Payload:

     * ``name``: the file's name
     * ``path``: the file's path within its storage location
     * ``origin``: the origin storage location of the file, either ``local`` or ``sdcard``

   .. deprecated:: 1.3.0

        * ``file``: the file's full path on disk (``local``) or within its storage (``sdcard``)
        * ``filename``: the file's name

      Still available for reasons of backwards compatibility. Will be removed with 1.4.0.

PrintFailed
   A print failed.

   Payload:

     * ``name``: the file's name
     * ``path``: the file's path within its storage location
     * ``origin``: the origin storage location of the file, either ``local`` or ``sdcard``

   .. deprecated:: 1.3.0

        * ``file``: the file's full path on disk (``local``) or within its storage (``sdcard``)
        * ``filename``: the file's name

      Still available for reasons of backwards compatibility. Will be removed with 1.4.0.

PrintDone
   A print completed successfully.

   Payload:

     * ``name``: the file's name
     * ``path``: the file's path within its storage location
     * ``origin``: the origin storage location of the file, either ``local`` or ``sdcard``
     * ``time``: the time needed for the print, in seconds (float)

   .. deprecated:: 1.3.0

        * ``file``: the file's full path on disk (``local``) or within its storage (``sdcard``)
        * ``filename``: the file's name

      Still available for reasons of backwards compatibility. Will be removed with 1.4.0.

PrintCancelled
   The print has been cancelled via the cancel button.

   Payload:

     * ``name``: the file's name
     * ``path``: the file's path within its storage location
     * ``origin``: the origin storage location of the file, either ``local`` or ``sdcard``
     * ``position``: the print head position at the time of cancelling, if available
     * ``position.x``: x coordinate, as reported back from the firmware through `M114`
     * ``position.y``: y coordinate, as reported back from the firmware through `M114`
     * ``position.z``: z coordinate, as reported back from the firmware through `M114`
     * ``position.e``: e coordinate (of currently selected extruder), as reported back from the firmware through `M114`
     * ``position.t``: last tool selected *through OctoPrint* (note that if you did change the printer's selected
       tool outside of OctoPrint, e.g. through the printer controller, or if you are printing from SD, this will NOT
       be accurate)
     * ``position.f``: last feedrate for move commands **sent through OctoPrint** (note that if you modified the
       feedrate outside of OctoPrint, e.g. through the printer controller, or if you are printing from SD, this will
       NOT be accurate)

   .. deprecated:: 1.3.0

        * ``file``: the file's full path on disk (``local``) or within its storage (``sdcard``)
        * ``filename``: the file's name

      Still available for reasons of backwards compatibility. Will be removed with 1.4.0.

PrintPaused
   The print has been paused.

   Payload:

     * ``name``: the file's name
     * ``path``: the file's path within its storage location
     * ``origin``: the origin storage location of the file, either ``local`` or ``sdcard``
     * ``position``: the print head position at the time of pausing, if available
     * ``position.x``: x coordinate, as reported back from the firmware through `M114`
     * ``position.y``: y coordinate, as reported back from the firmware through `M114`
     * ``position.z``: z coordinate, as reported back from the firmware through `M114`
     * ``position.e``: e coordinate (of currently selected extruder), as reported back from the firmware through `M114`
     * ``position.t``: last tool selected *through OctoPrint* (note that if you did change the printer's selected
       tool outside of OctoPrint, e.g. through the printer controller, or if you are printing from SD, this will NOT
       be accurate)
     * ``position.f``: last feedrate for move commands **sent through OctoPrint** (note that if you modified the
       feedrate outside of OctoPrint, e.g. through the printer controller, or if you are printing from SD, this will
       NOT be accurate)

   .. deprecated:: 1.3.0

        * ``file``: the file's full path on disk (``local``) or within its storage (``sdcard``)
        * ``filename``: the file's name

      Still available for reasons of backwards compatibility. Will be removed with 1.4.0.

PrintResumed
   The print has been resumed.

   Payload:

     * ``name``: the file's name
     * ``path``: the file's path within its storage location
     * ``origin``: the origin storage location of the file, either ``local`` or ``sdcard``

   .. deprecated:: 1.3.0

        * ``file``: the file's full path on disk (``local``) or within its storage (``sdcard``)
        * ``filename``: the file's name

      Still available for reasons of backwards compatibility. Will be removed with 1.4.0.

GCODE processing
----------------

PowerOn
   An ``M80`` was sent to the printer through OctoPrint (not triggered when printing from SD!)

PowerOff
   An ``M81`` was sent to the printer through OctoPrint (not triggered when printing from SD!)

Home
   A ``G28`` was sent to the printer through OctoPrint (not triggered when printing from SD!)

ZChange
   The printer's Z-Height has changed (new layer) through a ``G0`` or ``G1`` that was sent to the printer through OctoPrint
   (not triggered when printing from SD!)

Dwell
   A ``G4`` was sent to the printer through OctoPrint (not triggered when printing from SD!)

Waiting
   One of the following commands was sent to the printer through OctoPrint (not triggered when printing from SD!):
   ``M0``, ``M1``, ``M226``

Cooling
   An ``M245`` was sent to the printer through OctoPrint (not triggered when printing from SD!)

Alert
   An ``M300`` was sent to the printer through OctoPrint (not triggered when printing from SD!)

Conveyor
   An ``M240`` was sent to the printer through OctoPrint (not triggered when printing from SD!)

Eject
   An ``M40`` was sent to the printer through OctoPrint (not triggered when printing from SD!)

EStop
   An ``M112`` was sent to the printer through OctoPrint (not triggered when printing from SD!)

PositionUpdate
   The response to an ``M114`` was received by OctoPrint. The payload contains the current position information
   parsed from the response and (in the case of the selected tool ``t`` and the current feedrate ``f``) tracked
   by OctoPrint.

   Payload:

     * ``x``: x coordinate, parsed from response
     * ``y``: y coordinate, parsed from response
     * ``z``: z coordinate, parsed from response
     * ``e``: e coordinate, parsed from response
     * ``t``: last tool selected *through OctoPrint*
     * ``f``: last feedrate for move commands ``G0``, ``G1`` or ``G28`` sent *through OctoPrint*

ToolChange
   A tool change command was sent to the printer. The payload contains the former current tool index and the
   new current tool index.

   Payload:

     * ``old``: old tool index
     * ``new``: new tool index

Timelapses
----------

CaptureStart
   A timelapse frame has started to be captured.

   Payload:

     * ``file``: the name of the image file to be saved

CaptureDone
   A timelapse frame has completed being captured.

   Payload:
     * ``file``: the name of the image file that was saved

CaptureFailed
   A timelapse frame could not be captured.

   Payload:
     * ``file``: the name of the image file that should have been saved
     * ``error``: the error that was caught

MovieRendering
   The timelapse movie has started rendering.

   Payload:

     * ``gcode``: the GCODE file for which the timelapse would have been created (only the filename without the path)
     * ``movie``: the movie file that is being created (full path)
     * ``movie_basename``: the movie file that is being created (only the file name without the path)

MovieDone
   The timelapse movie is completed.

   Payload:

     * ``gcode``: the GCODE file for which the timelapse would have been created (only the filename without the path)
     * ``movie``: the movie file that has been created (full path)
     * ``movie_basename``: the movie file that has been created (only the file name without the path)

MovieFailed
   There was an error while rendering the timelapse movie.

   Payload:

     * ``gcode``: the GCODE file for which the timelapse would have been created (only the filename without the path)
     * ``movie``: the movie file that would have been created (full path)
     * ``movie_basename``: the movie file that would have been created (only the file name without the path)
     * ``returncode``: the return code of ``ffmpeg`` that indicates the error that occurred
     * ``reason``: additional machine processable reason string - can be ``returncode`` if ffmpeg
       returned a non-0 return code, ``no_frames`` if no frames were captured that could be rendered
       to a timelapse, or ``unknown`` for any other reason of failure to render.

Slicing
-------

SlicingStarted
   The slicing of a file has started.

   Payload:

     * ``stl``: the STL's filename
     * ``stl_location``: the STL's location
     * ``gcode``: the sliced GCODE's filename
     * ``gcode_location``: the sliced GCODE's location
     * ``progressAvailable``: true if progress information via the ``slicingProgress`` push update will be available, false if not

SlicingDone
   The slicing of a file has completed.

   Payload:

     * ``stl``: the STL's filename
     * ``stl_location``: the STL's location
     * ``gcode``: the sliced GCODE's filename
     * ``gcode_location``: the sliced GCODE's location
     * ``time``: the time needed for slicing, in seconds (float)

SlicingCancelled
   The slicing of a file has been cancelled. This will happen if a second slicing job
   targeting the same GCODE file has been started by the user.

   Payload:

     * ``stl``: the STL's filename
     * ``stl_location``: the STL's location
     * ``gcode``: the sliced GCODE's filename
     * ``gcode_location``: the sliced GCODE's location

SlicingFailed
   The slicing of a file has failed.

   Payload:

     * ``stl``: the STL's filename
     * ``stl_location``: the STL's location
     * ``gcode``: the sliced GCODE's filename
     * ``gcode_location``: the sliced GCODE's location
     * ``reason``: the reason for the slicing having failed

SlicingProfileAdded
   A new slicing profile was added.

   Payload:

     * ``slicer``: the slicer for which the profile was added
     * ``profile``: the profile that was added

SlicingProfileModified
   A new slicing profile was modified.

   Payload:

     * ``slicer``: the slicer for which the profile was modified
     * ``profile``: the profile that was modified

SlicingProfileDeleted
   A slicing profile was deleted.

   Payload:

     * ``slicer``: the slicer for which the profile was deleted
     * ``profile``: the profile that was deleted

Settings
--------

SettingsUpdated
   The internal settings were updated.