Events¶
Contents
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, orNO FILE
if no file is selected{__filepath}
: path in origin location of currently selected file, orNO FILE
if no file is selected{__fileorigin}
: origin of currently selected file, orNO 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 namepath
: the file’s path in its origin storage locationorigin
: the origin storage location of the file, eitherlocal
orsdcard
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¶
Note
Plugins may add additional events via the octoprint.events.register_custom_events hook.
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 portbaudrate
: 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. Seeget_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 namepath
: the file’s path within its storage locationtarget
: the target storage location to which the file was uploaded, eitherlocal
orsdcard
-
Deprecated since version 1.3.0:
file
: the file’s path within its storage location. To be removed in 1.4.0.
- FileAdded
A file has been added to a storage.
- Payload:
storage
: the storage’s identifierpath
: the file’s path within its storage locationname
: the file’s nametype
: 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 thenFileAdded
for the new one.- FileRemoved
A file has been removed from a storage.
- Payload:
storage
: the storage’s identifierpath
: the file’s path within its storage locationname
: the file’s nametype
: 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 thenFileAdded
for the new one.- FolderAdded
A folder has been added to a storage.
- Payload:
storage
: the storage’s identifierpath
: the folder’s path within its storage locationname
: 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 thenFolderAdded
for the new one.- FolderRemoved
A folder has been removed from a storage.
- Payload:
storage
: the storage’s identifierpath
: the folder’s path within its storage locationname
: the folder’s name
Note
A moved folder first triggers
FolderRemoved
for its original path and thenFolderAdded
for the new one.- UpdatedFiles
A file list was modified.
Payload:
type
: the type of file list that was modified. Onlyprintables
is supported here. See the deprecation note below.Deprecated since version 1.2.0: The
gcode
modification type has been superseded byprintables
. It is currently still available for reasons of backwards compatibility and will also be sent on modification ofprintables
. It will however be removed with 1.4.0.
- MetadataAnalysisStarted
The metadata analysis of a file has started.
Payload:
name
: the file’s namepath
: the file’s path within its storage locationorigin
: the file’s origin storage location
-
Deprecated since version 1.3.0:
file
: the file’s path within its storage location. To be removed in 1.4.0.
- MetadataAnalysisFinished
The metadata analysis of a file has finished.
Payload:
name
: the file’s namepath
: the file’s path within its storage locationorigin
: the file’s origin storage locationresult
: 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. To be removed in 1.4.0.
- FileSelected
A file has been selected for printing.
Payload:
name
: the file’s namepath
: the file’s path within its storage locationorigin
: the origin storage location of the file, eitherlocal
orsdcard
-
Deprecated since version 1.3.0:
file
: the file’s full path on disk (local
) or within its storage (sdcard
). To be removed in 1.4.0.filename
: the file’s name. To be removed in 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 locallyremote
: 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 secondslocal
: the file’s name as stored locallyremote
: the file’s name as stored on SD
Printing¶
- PrintStarted
A print has started.
Payload:
name
: the file’s namepath
: the file’s path within its storage locationorigin
: the origin storage location of the file, eitherlocal
orsdcard
size
: the file’s size in bytes (if available)owner
: the user who started the print job (if available)user
: the user who started the print job (if available)
-
Deprecated since version 1.3.0:
file
: the file’s full path on disk (local
) or within its storage (sdcard
). To be removed in 1.4.0.filename
: the file’s name. To be removed in 1.4.0.
- PrintFailed
A print failed.
Payload:
name
: the file’s namepath
: the file’s path within its storage locationorigin
: the origin storage location of the file, eitherlocal
orsdcard
size
: the file’s size in bytes (if available)owner
: the user who started the print job (if available)time
: the elapsed time of the print when it failed, in seconds (float)reason
: the reason the print failed, eithercancelled
orerror
-
Deprecated since version 1.3.0:
file
: the file’s full path on disk (local
) or within its storage (sdcard
). To be removed in 1.4.0.filename
: the file’s name. To be removed in 1.4.0.
- PrintDone
A print completed successfully.
Payload:
name
: the file’s namepath
: the file’s path within its storage locationorigin
: the origin storage location of the file, eitherlocal
orsdcard
size
: the file’s size in bytes (if available)owner
: the user who started the print job (if available)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
). To be removed in 1.4.0.filename
: the file’s name. To be removed in 1.4.0.
- PrintCancelling
The print is about to be cancelled.
Payload:
name
: the file’s namepath
: the file’s path within its storage locationorigin
: the origin storage location of the file, eitherlocal
orsdcard
size
: the file’s size in bytes (if available)owner
: the user who started the print job (if available)user
: the user who cancelled the print job (if available)firmwareError
: the firmware error that caused cancelling the print job, if any
- PrintCancelled
The print has been cancelled.
Payload:
name
: the file’s namepath
: the file’s path within its storage locationorigin
: the origin storage location of the file, eitherlocal
orsdcard
size
: the file’s size in bytes (if available)owner
: the user who started the print job (if available)time
: the elapsed time of the print when it was cancelled, in seconds (float)user
: the user who cancelled the print job (if available)position
: the print head position at the time of cancelling (if available, not available if recording of the position on cancel is disabled)position.x
: x coordinate, as reported back from the firmware through M114position.y
: y coordinate, as reported back from the firmware through M114position.z
: z coordinate, as reported back from the firmware through M114position.e
: e coordinate (of currently selected extruder), as reported back from the firmware through M114position.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
). To be removed in 1.4.0.filename
: the file’s name. To be removed in 1.4.0.
- PrintPaused
The print has been paused.
Payload:
name
: the file’s namepath
: the file’s path within its storage locationorigin
: the origin storage location of the file, eitherlocal
orsdcard
size
: the file’s size in bytes (if available)owner
: the user who started the print job (if available)user
: the user who paused the print job (if available)position
: the print head position at the time of pausing (if available, not available if the recording of the position on pause is disabled or the pause is completely handled by the printer’s firmware)position.x
: x coordinate, as reported back from the firmware through M114position.y
: y coordinate, as reported back from the firmware through M114position.z
: z coordinate, as reported back from the firmware through M114position.e
: e coordinate (of currently selected extruder), as reported back from the firmware through M114position.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
). To be removed in 1.4.0.filename
: the file’s name. To be removed in 1.4.0.
- PrintResumed
The print has been resumed.
Payload:
name
: the file’s namepath
: the file’s path within its storage locationorigin
: the origin storage location of the file, eitherlocal
orsdcard
size
: the file’s size in bytes (if available)owner
: the user who started the print job (if available)user
: the user who resumed the print job (if available)
-
Deprecated since version 1.3.0:
file
: the file’s full path on disk (local
) or within its storage (sdcard
). To be removed in 1.4.0.filename
: the file’s name. To be removed in 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
orG1
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 toolt
and the current feedratef
) tracked by OctoPrint.Payload:
x
: x coordinate, parsed from responsey
: y coordinate, parsed from responsez
: z coordinate, parsed from responsee
: e coordinate, parsed from responset
: last tool selected through OctoPrintf
: last feedrate for move commandsG0
,G1
orG28
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 indexnew
: 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 savederror
: 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 offfmpeg
that indicates the error that occurredreason
: additional machine processable reason string - can bereturncode
if ffmpeg returned a non-0 return code,no_frames
if no frames were captured that could be rendered to a timelapse, orunknown
for any other reason of failure to render.
Slicing¶
- SlicingStarted
The slicing of a file has started.
Payload:
stl
: the STL’s filenamestl_location
: the STL’s locationgcode
: the sliced GCODE’s filenamegcode_location
: the sliced GCODE’s locationprogressAvailable
: true if progress information via theslicingProgress
push update will be available, false if not
- SlicingDone
The slicing of a file has completed.
Payload:
stl
: the STL’s filenamestl_location
: the STL’s locationgcode
: the sliced GCODE’s filenamegcode_location
: the sliced GCODE’s locationtime
: 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 filenamestl_location
: the STL’s locationgcode
: the sliced GCODE’s filenamegcode_location
: the sliced GCODE’s location
- SlicingFailed
The slicing of a file has failed.
Payload:
stl
: the STL’s filenamestl_location
: the STL’s locationgcode
: the sliced GCODE’s filenamegcode_location
: the sliced GCODE’s locationreason
: the reason for the slicing having failed
- SlicingProfileAdded
A new slicing profile was added.
Payload:
slicer
: the slicer for which the profile was addedprofile
: the profile that was added
- SlicingProfileModified
A new slicing profile was modified.
Payload:
slicer
: the slicer for which the profile was modifiedprofile
: the profile that was modified
- SlicingProfileDeleted
A slicing profile was deleted.
Payload:
slicer
: the slicer for which the profile was deletedprofile
: the profile that was deleted