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:
devel:
  virtualPrinter:
    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:

OctoPrint Virtual Printer debug commands

help
?
| This help.

# 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
trigger_missing_checksum
| Triggers a resend error with a missing checksum
trigger_missing_lineno
| Triggers a "no line number with checksum" error w/o resend request
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>

# SD printing

start_sd <str:file>
| Select and start printing file <file> from SD
select_sd <str:file>
| Select file <file> from SD, don't start printing it yet. Use
| start_sd to start the print
cancel_sd
| Cancels an ongoing SD print

# Misc

send <str:message>
| Sends back <message>
reset
| Simulates a reset. Internal state will be lost.