Setting up the virtual printer for debugging

OctoPrint includes, by default, a virtual printer plugin. This plugin allows you to debug OctoPrint’s serial communication without connecting to an actual printer. Furthermore, it is possible to create certain edge conditions that may be hard to reproduce with a real printer.

Enabling the virtual printer

The virtual printer is enabled by editing OctoPrint’s config.yaml file. Details on the configuration file can be found in the full config.yaml documentation.

The steps to take are as follows:

  • Find config.yaml in the OctoPrint settings folder. Usually in ~/.octoprint on Linux, in %APPDATA%/OctoPrint on Windows and in ~/Library/Application Support/OctoPrint on MacOS.
  • Add or extend the devel section with:
    enabled: true
  • Restart OctoPrint.
  • In the connection panel, a new option will appear in the Serial Port dropdown labeled VIRTUAL.
  • Select this option and click connect.
  • The virtual printer is now active.

Virtual printer configuration options

The config.yaml file has many configuration options for the virtual printer that allow you to fine-tune its behavior.

Please see the relevant config.yaml section for the full details.

Log file

Once activated, the virtual printer will log all serial communication in the plugin_virtual_printer_serial.log file that can be found in the OctoPrint settings folder.

Debug commands

You can simulate certain conditions and communications through the terminal tab in OctoPrint’s interface.

All commands start with !!DEBUG: and are followed by the command you want to execute. For instance, sending !!DEBUG:action_disconnect will disconnect the printer. Sending !!DEBUG without command will show a help message with all the available commands.

Action Triggers

action_pause Sends a “// action:pause” action trigger to the host.

action_resume Sends a “// action:resume” action trigger to the host.

action_disconnect Sends a “// action:disconnect” action trigger to the host.

action_custom <action>[ <parameters>] Sends a custom “// action:<action> <parameters>” action trigger to the host.

Communication Errors

dont_answer Will not acknowledge the next command.

go_awol Will completely stop replying.

trigger_resend_lineno Triggers a resend error with a line number mismatch

trigger_resend_checksum Triggers a resend error with a checksum mismatch

drop_connection Drops the serial connection

prepare_ok <broken ok> Will cause <broken ok> to be enqueued for use, will be used instead of actual “ok”

Reply Timing / Sleeping

sleep <int:seconds> Sleep <seconds> s

sleep_after <str:command> <int:seconds> Sleeps <seconds> s after each execution of <command>

sleep_after_next <str:command> <int:seconds> Sleeps <seconds> s after execution of next <command>


help Show the available commands.

send <str:message> Sends back <message>