.. _sec-events:

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

.. contents::

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}``: filename of the currently selected file, "NO FILE" if not available
  * ``{__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:

  * ``file``: the file's name
  * ``origin``: the origin of the file, either ``local`` or ``sdcard``

then you'll be able to access the filename via the placeholder ``{file}`` and the origin via the placeholder ``{origin}``.


.. _sec-events-available_events:

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

Server
------

Startup
   The server has started

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

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

Connected
   The server has connected to the printer.

   Payload:

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

Disconnected
   The server has disconnected from the printer

Error
   An error has occurred in the printer communication.

   Payload:

     * ``error``: the error string

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

Upload
   A file has been uploaded.

   Payload:
     * ``file``: the file's name
     * ``target``: the target to which the file was uploaded, either ``local`` or ``sdcard``

UpdatedFiles
   A file list was modified.

   Payload:

     * ``type``: the type of file list that was modified. Currently only ``printables`` and ``gcode`` (DEPRECATED) are supported here.

       .. note::

          The type ``gcode`` has been renamed to ``printables`` with the introduction of a new file management layer that
          supports STL files as first class citizens as well. For reasons of backwards compatibility the ``UpdatedFiles``
          event for printable files will be fired twice, once with ``type`` set to ``gcode``, once set to ``printables``.
          Support for the ``gcode`` type will be removed in the next release after version 1.2.0.

MetadataAnalysisStarted
   The metadata analysis of a GCODE file has started.

   Payload:

     * ``file``: the file's name

MetadataAnalaysisFinished
   The metadata analysis of a GCODE file has finished.

   Payload:

     * ``file``: the file's name
     * ``result``: the analysis result -- this is a python object currently only available for internal use

FileSelected
   A GCODE file has been selected for printing.

   Payload:

     * ``file``: the file's name
     * ``origin``: the origin of the file, either ``local`` or ``sdcard``

FileDeselected
   No file is selected any more for printing.

TransferStarted
   A GCODE file transfer to 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 GCODE file transfer to 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:

     * ``file``: the file's name
     * ``origin``: the origin of the file, either ``local`` or ``sdcard``

PrintFailed
   A print failed.

   Payload:

     * ``file``: the file's name
     * ``origin``: the origin of the file, either ``local`` or ``sdcard``

PrintDone
   A print completed successfully.

   Payload:

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

PrintCancelled
   The print has been cancelled via the cancel button.

   Payload:

     * ``file``: the file's name
     * ``origin``: the origin of the file, either ``local`` or ``sdcard``

PrintPaused
   The print has been paused.

   Payload:

     * ``file``: the file's name
     * ``origin``: the origin of the file, either ``local`` or ``sdcard``

PrintResumed
   The print has been resumed.

   Payload:

     * ``file``: the file's name
     * ``origin``: the origin of the file, either ``local`` or ``sdcard``

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

PowerOn
   The GCode has turned on the printer power via M80

PowerOff
   The GCODE has turned on the printer power via M81

Home
   The head has gone home via G28

ZChange
   The printer's Z-Height has changed (new layer)

Paused
   The print has been paused

Waiting
   The print is paused due to a gcode wait command

Cooling
   The GCODE has enabled the platform cooler via M245

Alert
   The GCODE has issued a user alert (beep) via M300

Conveyor
   The GCODE has enabled the conveyor belt via M240

Eject
   The GCODE has enabled the part ejector via M40

EStop
   The GCODE has issued a panic stop via M112

Timelapses
----------

CaptureStart
   A timelapse image has started to be captured.

   Payload:

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

CaptureDone
   A timelapse image has completed being captured.

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

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

Slicing
-------

SlicingStarted
   The slicing of a file has started.

   Payload:

     * ``stl``: the STL's filename
     * ``gcode``: the sliced GCODE's filename
     * ``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
     * ``gcode``: the sliced GCODE's filename
     * ``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
     * ``gcode``: the sliced GCODE's filename

SlicingFailed
   The slicing of a file has failed.

   Payload:

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

Settings
--------

SettingsUpdated
   The internal settings were updated.
