Skip to content

octoprint.printer#

This module defines the interface for communicating with a connected printer.

The communication is in fact divided in two components, the :class:PrinterInterface and a deeper lying communication layer. However, plugins should only ever need to use the :class:PrinterInterface as the abstracted version of the actual printer communication.

.. autofunction:: get_connection_options

.. autoclass:: PrinterInterface :members:

.. autoclass:: PrinterCallback :members:

PrinterCallback #

on_printer_add_log(data) #

Called when the :class:PrinterInterface receives a new communication log entry from the communication layer.

Parameters:

Name Type Description Default
data str

The received log line.

required

on_printer_add_message(data) #

Called when the :class:PrinterInterface receives a new message from the communication layer.

Parameters:

Name Type Description Default
data str

The received message.

required

on_printer_add_temperature(data) #

Called when the :class:PrinterInterface receives a new temperature data set from the communication layer.

data is a dict of the following structure::

tool0:
    actual: <temperature of the first hotend, in degC>
    target: <target temperature of the first hotend, in degC>
...
bed:
    actual: <temperature of the bed, in degC>
    target: <target temperature of the bed, in degC>
chamber:
    actual: <temperature of the chamber, in degC>
    target: <target temperature of the chamber, in degC>

Parameters:

Name Type Description Default
data dict

A dict of all current temperatures in the format as specified above

required

on_printer_received_registered_message(name, output) #

Called when the :class:PrinterInterface received a registered message, e.g. from a feedback command.

Parameters:

Name Type Description Default
name str

Name of the registered message (e.g. the feedback command)

required
output str

Output for the registered message

required

on_printer_send_current_data(data) #

Called when the internal state of the :class:PrinterInterface changes, due to changes in the printer state, temperatures, log lines, job progress etc. Updates via this method are guaranteed to be throttled to a maximum of 2 calls per second.

data is a dict of the following structure::

state:
    text: <current state string>
    flags:
        operational: <whether the printer is currently connected and responding>
        printing: <whether the printer is currently printing>
        closedOrError: <whether the printer is currently disconnected and/or in an error state>
        error: <whether the printer is currently in an error state>
        paused: <whether the printer is currently paused>
        ready: <whether the printer is operational and ready for jobs>
        sdReady: <whether an SD card is present>
job:
    file:
        name: <name of the file>,
        size: <size of the file in bytes>,
        origin: <origin of the file, "local" or "sdcard">,
        date: <last modification date of the file>
    estimatedPrintTime: <estimated print time of the file in seconds>
    lastPrintTime: <last print time of the file in seconds>
    filament:
        length: <estimated length of filament needed for this file, in mm>
        volume: <estimated volume of filament needed for this file, in ccm>
progress:
    completion: <progress of the print job in percent (0-100)>
    filepos: <current position in the file in bytes>
    printTime: <current time elapsed for printing, in seconds>
    printTimeLeft: <estimated time left to finish printing, in seconds>
currentZ: <current position of the z axis, in mm>
offsets: <current configured temperature offsets, keys are "bed" or "tool[0-9]+", values the offset in degC>

Parameters:

Name Type Description Default
data dict

The current data in the format as specified above.

required

on_printer_send_initial_data(data) #

Called when registering as a callback with the :class:PrinterInterface to receive the initial data (state, log and temperature history etc) from the printer.

data is a dict of the following structure::

temps:
  - time: <timestamp of the temperature data point>
    tool0:
        actual: <temperature of the first hotend, in degC>
        target: <target temperature of the first hotend, in degC>
    ...
    bed:
        actual: <temperature of the bed, in degC>
        target: <target temperature of the bed, in degC>
  - ...
logs: <list of current communication log lines>
messages: <list of current messages from the firmware>

Parameters:

Name Type Description Default
data dict

The initial data in the format as specified above.

required

PrinterInterface #

The :class:PrinterInterface represents the developer interface to the :class:~octoprint.printer.standard.Printer instance.

valid_axes = ('x', 'y', 'z', 'e') class-attribute #

Valid axes identifiers.

valid_heater_regex = re.compile('^(tool\\d+|bed|chamber)$') class-attribute #

Regex for valid heater identifiers.

valid_tool_regex = re.compile('^(tool\\d+)$') class-attribute #

Regex for valid tool identifiers.

can_modify_file(path, sd, *args, **kwargs) #

Determines whether the path (on the printer's SD if sd is True) may be modified (updated or deleted) or not.

A file that is currently being printed is not allowed to be modified. Any other file or the current file when it is not being printed is fine though.

:since: 1.3.2

.. warning::

This was introduced in 1.3.2 to work around an issue when updating a file that is already selected. I'm not 100% sure at this point if this is the best approach to solve this issue, so if you decide to depend on this particular method in this interface, be advised that it might vanish in future versions!

Parameters:

Name Type Description Default
path str

path in storage of the file to check

required
sd bool

True if to check against SD storage, False otherwise

required

Returns:

Type Description

(bool) True if the file may be modified, False otherwise

cancel_print(tags=None, *args, **kwargs) #

Cancels the current print job.

Parameters:

Name Type Description Default
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

change_tool(tool, tags=None, *args, **kwargs) #

Switch the currently active tool (for which extrude commands will apply).

Parameters:

Name Type Description Default
tool str

The tool to switch to, matching the regex "tool[0-9]+" (e.g. "tool0", "tool1", ...)

required
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

commands(commands, tags=None, force=False, *args, **kwargs) #

Sends the provided commands to the printer.

Parameters:

Name Type Description Default
commands str, list

The commands to send. Might be a single command provided just as a string or a list of multiple commands to send in order.

required
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None
force bool

Whether to force sending of the command right away or allow queuing while printing

False

connect(port=None, baudrate=None, profile=None, *args, **kwargs) #

Connects to the printer, using the specified serial port, baudrate and printer profile. If a connection is already established, that connection will be closed prior to connecting anew with the provided parameters.

Parameters:

Name Type Description Default
port str

Name of the serial port to connect to. If not provided, an auto detection will be attempted.

None
baudrate int

Baudrate to connect with. If not provided, an auto detection will be attempted.

None
profile str

Name of the printer profile to use for this connection. If not provided, the default will be retrieved from the :class:PrinterProfileManager.

None

disconnect(*args, **kwargs) #

Disconnects from the printer. Does nothing if no connection is currently established.

extrude(amount, speed=None, tags=None, *args, **kwargs) #

Extrude amount millimeters of material from the tool.

Parameters:

Name Type Description Default
amount int, float

The amount of material to extrude in mm

required
speed int, None

Speed at which to extrude (F parameter). If set to None (or left out)

None
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

fake_ack(*args, **kwargs) #

Fakes an acknowledgment for the communication layer. If the communication between OctoPrint and the printer gets stuck due to lost "ok" responses from the server due to communication issues, this can be used to get things going again.

feed_rate(factor, tags=None, *args, **kwargs) #

Sets the factor for the printer's feed rate.

Parameters:

Name Type Description Default
factor int, float

The factor for the feed rate to send to the firmware. Percentage expressed as either an int between 0 and 100 or a float between 0 and 1.

required
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

flow_rate(factor, tags=None, *args, **kwargs) #

Sets the factor for the printer's flow rate.

Parameters:

Name Type Description Default
factor int, float

The factor for the flow rate to send to the firmware. Percentage expressed as either an int between 0 and 100 or a float between 0 and 1.

required
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

get_connection_options(*args, **kwargs) classmethod #

Retrieves the available ports, baudrates, preferred port and baudrate for connecting to the printer.

Returned dict has the following structure::

ports: <list of available serial ports>
baudrates: <list of available baudrates>
portPreference: <configured default serial port>
baudratePreference: <configured default baudrate>
autoconnect: <whether autoconnect upon server startup is enabled or not>

Returns:

Type Description
dict

A dictionary holding the connection options in the structure specified above

get_current_connection(*args, **kwargs) #

Returns:

Type Description

(tuple) The current connection information as a 4-tuple (connection_string, port, baudrate, printer_profile). If the printer is currently not connected, the tuple will be ("Closed", None, None, None).

get_current_data(*args, **kwargs) #

Returns:

Type Description

(dict) The current state data.

get_current_job(*args, **kwargs) #

Returns:

Type Description

(dict) The data of the current job.

get_current_temperatures(*args, **kwargs) #

Returns:

Type Description

(dict) The current temperatures.

get_state_id(*args, **kwargs) #

Identifier of the current communication state.

Possible values are
  • OPEN_SERIAL
  • DETECT_SERIAL
  • DETECT_BAUDRATE
  • CONNECTING
  • OPERATIONAL
  • PRINTING
  • PAUSED
  • CLOSED
  • ERROR
  • CLOSED_WITH_ERROR
  • TRANSFERING_FILE
  • OFFLINE
  • UNKNOWN
  • NONE

Returns:

Type Description

(str) A unique identifier corresponding to the current communication state.

get_state_string(*args, **kwargs) #

Returns:

Type Description

(str) A human readable string corresponding to the current communication state.

get_temperature_history(*args, **kwargs) #

Returns:

Type Description

(list) The temperature history.

get_transport(*args, **kwargs) #

Returns the communication layer's transport object, if a connection is currently established.

Note that this doesn't have to necessarily be a :class:serial.Serial instance, it might also be something different, so take care to do instance checks before attempting to access any properties or methods.

Returns:

Name Type Description
object

The communication layer's transport object

home(axes, tags=None, *args, **kwargs) #

Homes the specified printer axes.

Parameters:

Name Type Description Default
axes str, list

The axis or axes to home, each of which must converted to lower case must match one of "x", "y", "z" and "e"

required
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

is_cancelling(*args, **kwargs) #

Returns:

Type Description

(boolean) Whether the printer is currently cancelling a print.

is_closed_or_error(*args, **kwargs) #

Returns:

Type Description

(boolean) Whether the printer is currently disconnected and/or in an error state.

is_current_file(path, sd, *args, **kwargs) #

Returns whether the provided path (on the printer's SD if sd is True) is the currently selected file for printing.

:since: 1.3.2

.. warning::

This was introduced in 1.3.2 to work around an issue when updating a file that is already selected. I'm not 100% sure at this point if this is the best approach to solve this issue, so if you decide to depend on this particular method in this interface, be advised that it might vanish in future versions!

Parameters:

Name Type Description Default
path str

path in storage of the file to check

required
sd bool

True if to check against SD storage, False otherwise

required

Returns:

Type Description

(bool) True if the file is currently selected, False otherwise

is_error(*args, **kwargs) #

Returns:

Type Description

(boolean) Whether the printer is currently in an error state.

is_operational(*args, **kwargs) #

Returns:

Type Description

(boolean) Whether the printer is currently connected and available.

is_paused(*args, **kwargs) #

Returns:

Type Description

(boolean) Whether the printer is currently paused.

is_pausing(*args, **kwargs) #

Returns:

Type Description

(boolean) Whether the printer is currently pausing a print.

is_printing(*args, **kwargs) #

Returns:

Type Description

(boolean) Whether the printer is currently printing.

is_ready(*args, **kwargs) #

Returns:

Type Description

(boolean) Whether the printer is currently operational and ready for new print jobs (not printing).

job_on_hold(blocking=True, *args, **kwargs) #

Contextmanager that allows executing code while printing while making sure that no commands from the file being printed are continued to be sent to the printer. Note that this will only work for local files, NOT SD files.

Example:

.. code-block:: python

with printer.job_on_hold(): park_printhead() take_snapshot() send_printhead_back()

It should be used sparingly and only for very specific situations (such as parking the print head somewhere, taking a snapshot from the webcam, then continuing). If you abuse this, you WILL cause print quality issues!

A lock is in place that ensures that the context can only actually be held by one thread at a time. If you don't want to block on acquire, be sure to set blocking to False and catch the RuntimeException thrown if the lock can't be acquired.

Parameters:

Name Type Description Default
blocking bool

Whether to block while attempting to acquire the lock (default) or not

True

jog(axes, relative=True, speed=None, tags=None, *args, **kwargs) #

Jogs the specified printer axis by the specified amount in mm.

Parameters:

Name Type Description Default
axes dict

Axes and distances to jog, keys are axes ("x", "y", "z"), values are distances in mm

required
relative bool

Whether to interpret the distance values as relative (true, default) or absolute (false) coordinates

True
speed int, bool or None

Speed at which to jog (F parameter). If set to False no speed will be set specifically. If set to None (or left out) the minimum of all involved axes speeds from the printer profile will be used.

None
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

log_lines(*lines) #

Logs the provided lines to the printer log and serial.log

Parameters:

Name Type Description Default
*lines

the lines to log

()

pause_print(tags=None, *args, **kwargs) #

Pauses the current print job if it is currently running, does nothing otherwise.

Parameters:

Name Type Description Default
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

register_callback(callback, *args, **kwargs) #

Registers a :class:PrinterCallback with the instance.

Parameters:

Name Type Description Default
callback PrinterCallback

The callback object to register.

required

resume_print(tags=None, *args, **kwargs) #

Resumes the current print job if it is currently paused, does nothing otherwise.

Parameters:

Name Type Description Default
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

script(name, context=None, tags=None, *args, **kwargs) #

Sends the GCODE script name to the printer.

The script will be run through the template engine, the rendering context can be extended by providing a context with additional template variables to use.

If the script is unknown, an :class:UnknownScriptException will be raised.

Parameters:

Name Type Description Default
name str

The name of the GCODE script to render.

required
context dict

An optional context of additional template variables to provide to the renderer.

None
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

Raises:

Type Description
UnknownScriptException

There is no GCODE script with name name

select_file(path, sd, printAfterSelect=False, pos=None, tags=None, *args, **kwargs) #

Selects the specified path for printing, specifying if the file is to be found on the sd or not. Optionally can also directly start the print after selecting the file.

Parameters:

Name Type Description Default
path str

The path to select for printing. Either an absolute path or relative path to a local file in the uploads folder or a filename on the printer's SD card.

required
sd boolean

Indicates whether the file is on the printer's SD card or not.

required
printAfterSelect boolean

Indicates whether a print should be started after the file is selected.

False
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

Raises:

Type Description
InvalidFileType

if the file is not a machinecode file and hence cannot be printed

InvalidFileLocation

if an absolute path was provided and not contained within local storage or doesn't exist

send_initial_callback(callback) #

Sends the initial printer update to :class:PrinterCallback.

Parameters:

Name Type Description Default
callback PrinterCallback

The callback object to send initial data to.

required

set_job_on_hold(value, blocking=True, *args, **kwargs) #

Setter for finer control over putting jobs on hold. Set to True to ensure that no commands from the file being printed are continued to be sent to the printer. Set to False to resume. Note that this will only work for local files, NOT SD files.

Make absolutely sure that if you set this flag, you will always also unset it again. If you don't, the job will be stuck forever.

Example:

.. code-block:: python

if printer.set_job_on_hold(True): try: park_printhead() take_snapshot() send_printhead_back() finally: printer.set_job_on_hold(False)

Just like :func:~octoprint.printer.PrinterInterface.job_on_hold this should be used sparingly and only for very specific situations. If you abuse this, you WILL cause print quality issues!

Parameters:

Name Type Description Default
value bool

The value to set

required
blocking bool

Whether to block while attempting to set the value (default) or not

True

Returns:

Type Description

(bool) Whether the value could be set successfully (True) or a timeout was encountered (False)

set_temperature(heater, value, tags=None, *args, **kwargs) #

Sets the target temperature on the specified heater to the given value in celsius.

Parameters:

Name Type Description Default
heater str

The heater for which to set the target temperature. Either "bed" for setting the bed temperature or something matching the regular expression "tool[0-9]+" (e.g. "tool0", "tool1", ...) for the hotends of the printer

required
value int, float

The temperature in celsius to set the target temperature to.

required
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

set_temperature_offset(offsets=None, tags=None, *args, **kwargs) #

Sets the temperature offsets to apply to target temperatures read from a GCODE file while printing.

Parameters:

Name Type Description Default
offsets dict

A dictionary specifying the offsets to apply. Keys must match the format for the heater parameter to :func:set_temperature, so "bed" for the offset for the bed target temperature and "tool[0-9]+" for the offsets to the hotend target temperatures.

None
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

start_print(tags=None, *args, **kwargs) #

Starts printing the currently selected file. If no file is currently selected, does nothing.

Parameters:

Name Type Description Default
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

toggle_pause_print(tags=None, *args, **kwargs) #

Pauses the current print job if it is currently running or resumes it if it is currently paused.

Parameters:

Name Type Description Default
tags set of str

An optional set of tags to attach to the command(s) throughout their lifecycle

None

unregister_callback(callback, *args, **kwargs) #

Unregisters a :class:PrinterCallback from the instance.

Parameters:

Name Type Description Default
callback PrinterCallback

The callback object to unregister.

required

unselect_file(*args, **kwargs) #

Unselects and currently selected file.

Back to top