7f2476e513
Introduced three new events:
* CONNECTING - fired just before starting the connection process
* DISCONNECTING - fired just before starting the (active) disconnection
process
* PRINTER_STATE_CHANGED - fired every time the printer state changes
Also introduced new GCODE script beforePrinterDisconnected, which will
get sent just before the printer gets (actively) disconnected. Also enabled
communication object to wait for the send queue to be emptied before
closing it, in order to allow sending all lines from the disconnect script.
114 lines
5 KiB
ReStructuredText
114 lines
5 KiB
ReStructuredText
.. _sec-features-gcode_scripts:
|
|
|
|
GCODE Scripts
|
|
=============
|
|
|
|
.. contents::
|
|
|
|
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 :ref:`button defined as a custom control <sec-features-custom_controls>`
|
|
is clicked.
|
|
|
|
Unless :ref:`configured otherwise <sec-configuration-config_yaml-folder>`, 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 <http://jinja.pocoo.org/>`_, 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 :ref:`template rendering context <sec-features-gcode_scripts-context>`
|
|
as described below.
|
|
|
|
.. _sec-features-gcode_scripts-predefined:
|
|
|
|
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.
|
|
* ``beforePrinterDisconnected``: Sent just before OctoPrint (actively) closes the connection to the printer. Defaults
|
|
to an empty script. Note that this will *not* be sent for unexpected connection cut offs, e.g. in case of errors
|
|
on the serial line, only when the user clicks the "Disconnect" button or the printer requests a disconnect via an
|
|
:ref:`action command <sec-features-action_commands>` .
|
|
* ``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
|
|
:ref:`bundled script listed below <sec-features-gcode_scripts-bundled>`.
|
|
* ``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 :ref:`a hook <sec-plugins-hook-comm-protocol-scripts>`.
|
|
|
|
.. _sec-features-gcode_scripts-snippets:
|
|
|
|
Snippets
|
|
--------
|
|
|
|
For making small GCODE snippets reusable in a template (e.g. for :ref:`disabling all hotends <sec-features-gcode_scripts-bundled>`)
|
|
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).
|
|
|
|
.. _sec-features-gcode_scripts-context:
|
|
|
|
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 :ref:`predefined GCODE scripts <sec-features-gcode_scripts-predefined>` are also called with the following additional
|
|
template variables:
|
|
|
|
* ``event``: The payload of the ``Connected``, ``PrintStarted``, ``PrintCancelled``, ``PrintDone``, ``PrintPaused`` or
|
|
``PrintResumed`` event. See :ref:`the documentation of events <sec-events-available_events>` for the contained values.
|
|
|
|
GCODE scripts attached to :ref:`custom controls <sec-features-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.
|
|
|
|
.. _sec-features-gcode_scripts-bundled:
|
|
|
|
Bundled Scripts
|
|
---------------
|
|
|
|
Out of the box, OctoPrint defaults to the following script setup for ``afterPrintCancelled``:
|
|
|
|
.. code-block:: jinja
|
|
:caption: Default ``afterPrintCancelled`` script
|
|
|
|
; disable motors
|
|
M84
|
|
|
|
;disable all heaters
|
|
{% snippet 'disable_hotends' %}
|
|
M140 S0
|
|
|
|
;disable fan
|
|
M106 S0
|
|
|
|
The ``disable_hotends`` snippet is defined as follows:
|
|
|
|
.. code-block:: jinja
|
|
:caption: Default ``disable_hotends`` snippet
|
|
|
|
{% for tool in range(printer_profile.extruder.count) %}
|
|
M104 T{{ tool }} S0
|
|
{% endfor %}
|
|
|
|
As you can see, the ``disable_hotends`` snippet utilizes the ``printer_profile`` context variable in order to
|
|
iterate through all available extruders and set their temperature to 0.
|
|
|
|
.. seealso::
|
|
|
|
`Jinja Template Designer Documentation <http://jinja.pocoo.org/docs/dev/templates/>`_
|
|
Jinja's Template Designer Documentation describes the syntax and semantics of the template language used
|
|
also by OctoPrint's GCODE scripts.
|