GCODE Scripts

OctoPrint allows you to define custom GCODE scripts to be executed on specified occasions, e.g. when a print starts, when OctoPrint connects to a printer, or when a button defined as a custom control is clicked.

Unless configured otherwise, OctoPrint expects scripts to be located in the scripts/gcode folder in OctoPrint configuration directory (per default ~/.octoprint on Linux, %APPDATA%\OctoPrint on Windows and ~/Library/Application Support/OctoPrint on MacOS).

These GCODE scripts are backed by the templating engine Jinja2, allowing more than just simple “send-as-is” scripts but making use of a full blown templating language in order to create your scripts. To this end, OctoPrint injects a couple of variables into the template rendering context as described below.

Predefined Scripts

The following GCODE scripts are sent by OctoPrint automatically:

  • afterPrinterConnected: Sent after OctoPrint successfully connected to a printer. Defaults to an empty script.
  • beforePrintStarted: Sent just before a print job is started. Defaults to an empty script.
  • afterPrintCancelled: Sent just after a print job was cancelled. Defaults to the bundled script listed below.
  • afterPrintDone: Sent just after a print job finished. Defaults to an empty script.
  • afterPrintPaused: Sent just after a print job was paused. Defaults to an empty script.
  • beforePrintResumed: Sent just before a print job is resumed. Defaults to an empty script.

Note

Plugins may extend these scripts through a hook.

Snippets

For making small GCODE snippets reusable in a template (e.g. for disabling all hotends) there’s an additional Jinja template command {% snippet '<snippet name>' %} available which allows including snippets stored under scripts/gcode/snippets in OctoPrint’s configuration directory. They fully support the whole spectrum of the Jinja2 templating language (that includes including other snippets).

Context

All GCODE scripts have access to the following template variables through the template context:

  • printer_profile: The currently selected Printer Profile, including information such as the extruder count, the build volume size, the filament diameter etc.
  • script: An object wrapping the script’s type (gcode) and name (e.g. afterPrintCancelled) as script.type and script.name respectively.

The predefined GCODE scripts are also called with the following additional template variables:

  • event: The payload of the Connected, PrintStarted, PrintCancelled, PrintDone, PrintPaused or PrintResumed event. See the documentation of events for the contained values.

GCODE scripts attached to custom controls are called with the following additional template variables:

  • parameters: The parameters as defined for the custom control, if it has any inputs.
  • context: Additional context included in the definition of the custom control.

Bundled Scripts

Out of the box, OctoPrint defaults to the following script setup for afterPrintCancelled:

Listing 1 Default afterPrintCancelled script
; disable motors
M84

;disable all heaters
{% snippet 'disable_hotends' %}
[% snippet 'disable_bed' %}

;disable fan
M106 S0

The disable_hotends snippet is defined as follows:

Listing 2 Default disable_hotends snippet
{% for tool in range(printer_profile.extruder.count) %}
M104 T{{ tool }} S0
{% endfor %}

The disable_bed snippet is defined as follows:

Listing 3 Default disable_bed snippet
{% if printer_profile.heatedBed %}
M140 S0
{% endif %}

As you can see, the disable_hotends and disable_bed snippets utilize the printer_profile context variable in order to iterate through all available extruders and set their temperature to 0, and to also set the bed temperature to 0 if a heated bed is configured.

See also

Jinja Template Designer Documentation
Jinja’s Template Designer Documentation describes the syntax and semantics of the template language used also by OctoPrint’s GCODE scripts.