<commit_before>.. _sec-api-printer:

******************
Printer operations
******************

.. contents::

Printer control is mostly achieved through the use of commands, issued to resources reflecting components of the
printer. OctoPrint currently knows the following components:

Print head
  Print head commands allow jogging and homing the print head in all three axes. See :ref:`sec-api-printer-printheadcommand`.
Heater
  Heater commands allow setting the temperature and temperature offsets for the printer's hotend and bed. Currently
  OctoPrint only supports one hotend heater (this will change in the future). See :ref:`sec-api-printer-heatercommand`.
Feeder
  Feeder commands allow extrusion/extraction of filament. Currently OctoPrint only supports one feeder (this will
  change in a future version). See :ref:`sec-api-printer-feedercommand`.
SD card
  SD commands allow initialization, refresh and release of the printer's SD card (if available). See :ref:`sec-api-printer-sdcommand`.

.. _sec-api-printer-printheadcommand:

Issue a print head command
==========================

.. http:post:: /api/printer/printhead

   Print head commands allow jogging and homing the print head in all three axes. Available commands are:

   jog
     Jogs the print head (relatively) by a defined amount in one or more axes. Additional parameters are:

     * ``x``: Optional. Amount to jog print head on x axis, must be a valid number corresponding to the distance to travel in mm.
     * ``y``: Optional. Amount to jog print head on y axis, must be a valid number corresponding to the distance to travel in mm.
     * ``z``: Optional. Amount to jog print head on z axis, must be a valid number corresponding to the distance to travel in mm.

   home
     Homes the print head in all of the given axes. Additional parameters are:

     * ``axes``: A list of axes which to home, valid values are one or more of ``x``, ``y``, ``z``.

   All of these commands may only be sent if the printer is currently operational and not printing. Otherwise a
   :http:statuscode:`409` is returned.

   Upon success, a status code of :http:statuscode:`204` and an empty body is returned.

   **Example Jog Request**

   Jog the print head by 10mm in X, -5mm in Y and 0.02mm in Z.

   .. sourcecode:: http

      POST /api/printer/printhead HTTP/1.1
      Host: example.com
      Content-Type: application/json
      X-Api-Key: abcdef...

      {
        "command": "jog",
        "x": 10,
        "y": -5,
        "z": 0.02
      }

   **Example Home Request**

   Home the X and Y axes.

   .. sourcecode:: http

      POST /api/printer/printhead HTTP/1.1
      Host: example.com
      Content-Type: application/json
      X-Api-Key: abcdef...

      {
        "command": "home",
        "axes": ["x", "y"]
      }

   :json string command: The command to issue, either ``jog`` or ``home``.
   :json number x:       ``jog`` command: The amount to travel on the X axis in mm.
   :json number y:       ``jog`` command: The amount to travel on the Y axis in mm.
   :json number z:       ``jog`` command: The amount to travel on the Z axis in mm.
   :json array axes:     ``home`` command: The axes which to home, valid values are one or more of ``x``, ``y`` and ``z``.
   :statuscode 204: No error
   :statuscode 400: Invalid axis specified, invalid value for travel amount for a jog command or otherwise invalid
                    request.
   :statuscode 409: If the printer is not operational or currently printing.

.. _sec-api-printer-heatercommand:

Issue a heater command
======================

.. http:post:: /api/printer/heater

   Heater commands allow setting the temperature and temperature offsets for the printer's hotend and bed. Available
   commands are:

   temp
     Sets the given target temperature on the printer's hotend and/or bed. Additional parameters:

     * ``temps``: Target temperature(s) to set, allowed properties are:

       * ``hotend``: New target temperature of the printer's hotend in centigrade.
       * ``bed``: New target temperature of the printer's bed in centigrade.

   offset
     Sets the given temperature offset on the printer's hotend and/or bed. Additional parameters:
<commit_msg>Teenytiny update to the API docs to indicate current state of temperature APIs (hint: still highly unstable and heavily being worked on conceptually)<commit_after>.. _sec-api-printer:

******************
Printer operations
******************

.. warning::

   This part of the API is still heavily in development, especially anything that has to do with temperature control.
   If you happen to want to develop against it, you should drop me an email to make sure I can give you a heads-up when
   something changes.

.. contents::

Printer control is mostly achieved through the use of commands, issued to resources reflecting components of the
printer. OctoPrint currently knows the following components:

Print head
  Print head commands allow jogging and homing the print head in all three axes. See :ref:`sec-api-printer-printheadcommand`.
Heater
  Heater commands allow setting the temperature and temperature offsets for the printer's hotend and bed. Currently
  OctoPrint only supports one hotend heater (this will change in the future). See :ref:`sec-api-printer-heatercommand`.
Feeder
  Feeder commands allow extrusion/extraction of filament. Currently OctoPrint only supports one feeder (this will
  change in a future version). See :ref:`sec-api-printer-feedercommand`.
SD card
  SD commands allow initialization, refresh and release of the printer's SD card (if available). See :ref:`sec-api-printer-sdcommand`.

.. _sec-api-printer-printheadcommand:

Issue a print head command
==========================

.. http:post:: /api/printer/printhead

   Print head commands allow jogging and homing the print head in all three axes. Available commands are:

   jog
     Jogs the print head (relatively) by a defined amount in one or more axes. Additional parameters are:

     * ``x``: Optional. Amount to jog print head on x axis, must be a valid number corresponding to the distance to travel in mm.
     * ``y``: Optional. Amount to jog print head on y axis, must be a valid number corresponding to the distance to travel in mm.
     * ``z``: Optional. Amount to jog print head on z axis, must be a valid number corresponding to the distance to travel in mm.

   home
     Homes the print head in all of the given axes. Additional parameters are:

     * ``axes``: A list of axes which to home, valid values are one or more of ``x``, ``y``, ``z``.

   All of these commands may only be sent if the printer is currently operational and not printing. Otherwise a
   :http:statuscode:`409` is returned.

   Upon success, a status code of :http:statuscode:`204` and an empty body is returned.

   **Example Jog Request**

   Jog the print head by 10mm in X, -5mm in Y and 0.02mm in Z.

   .. sourcecode:: http

      POST /api/printer/printhead HTTP/1.1
      Host: example.com
      Content-Type: application/json
      X-Api-Key: abcdef...

      {
        "command": "jog",
        "x": 10,
        "y": -5,
        "z": 0.02
      }

   **Example Home Request**

   Home the X and Y axes.

   .. sourcecode:: http

      POST /api/printer/printhead HTTP/1.1
      Host: example.com
      Content-Type: application/json
      X-Api-Key: abcdef...

      {
        "command": "home",
        "axes": ["x", "y"]
      }

   :json string command: The command to issue, either ``jog`` or ``home``.
   :json number x:       ``jog`` command: The amount to travel on the X axis in mm.
   :json number y:       ``jog`` command: The amount to travel on the Y axis in mm.
   :json number z:       ``jog`` command: The amount to travel on the Z axis in mm.
   :json array axes:     ``home`` command: The axes which to home, valid values are one or more of ``x``, ``y`` and ``z``.
   :statuscode 204: No error
   :statuscode 400: Invalid axis specified, invalid value for travel amount for a jog command or otherwise invalid
                    request.
   :statuscode 409: If the printer is not operational or currently printing.

.. _sec-api-printer-heatercommand:

Issue a heater command
======================

.. todo::

   Update to current implementation!

.. http:post:: /api/printer/heater

   Heater commands allow setting the temperature and temperature offsets for the printer's hotend and bed. Available
   commands are:

   temp
     Sets the given target temperature on the printer's hotend and/or bed. Additional parameters:

     * ``targets``: Target temperature(s) to set, allowed properties are:

       * ``hotend``: New target temperature of the printer's hotend in centigrade.
       * ``bed``: New target temperature of the printer's bed in centigrade.

   offset
     Sets the given temperature offset on the printer's hotend and/or bed. Additional parameters:

{'fraction_non_alphanumeric': 0.10116775207725129, 'fraction_numerical': 0.006961598922075006, 'mean_word_length': 3.1505125815470643, 'pattern_counts': {'":': 12, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6159616', 'n_tokens_mistral': 2528, 'n_tokens_neox': 2370, 'n_words': 1174}