Events

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.

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

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

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}.

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 unrecoverable error has been encountered, either as reported by the firmware (e.g. a thermal runaway) or on the connection.

Payload:

  • error: the error string
PrinterStateChanged

The state of the printer changed.

Payload:

  • state_id: Id of the new state. See 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 since version 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 folder’s path within its storage location
  • name: the folder’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 folder’s path within its storage location
  • name: the folder’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 since version 1.2.0: The gcode modification type has been superseded 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 since version 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 since version 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 since version 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 since version 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
  • time: the elapsed time of the print when it failed, in seconds (float)
  • reason: the reason the print failed, either cancelled or error
Deprecated since version 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 since version 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.

PrintCancelling

The print is about to be cancelled.

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
  • firmwareError: the firmware error that caused cancelling the print job, if any
PrintCancelled

The print has been cancelled.

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 since version 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 since version 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 since version 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.