[doc] documented gcode scripts and snippets
This commit is contained in:
Gina Häußge
parent
a146cb193b
commit
c6a0ef2425
1 changed files with 94 additions and 2 deletions
|
|
@ -3,16 +3,108 @@
|
|||
GCODE Scripts
|
||||
=============
|
||||
|
||||
.. todo::
|
||||
.. contents::
|
||||
|
||||
Needs to be written
|
||||
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.
|
||||
* ``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 :ref:`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.
|
||||
Loading…
Reference in a new issue