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 can be enabled through its Settings pane.

Virtual printer configuration options

There many configuration options via config.yaml for the virtual printer that allow you to fine-tune its behavior:

plugins:

  # Settings for the virtual printer
  virtual_printer:

    # Whether to enable the virtual printer and include it in the list of available serial connections.
    # Defaults to false.
    enabled: true

    # Whether to send an additional "ok" after a resend request (like Repetier)
    okAfterResend: false

    # Whether to force checksums and line number in the communication (like Repetier), if set to true
    # printer will only accept commands that come with linenumber and checksum and throw an error for
    # lines that don't. Defaults to false
    forceChecksum: false

    # Whether to send "ok" responses with the line number that gets acknowledged by the "ok". Defaults
    # to false.
    okWithLinenumber: false

    # Number of extruders to simulate on the virtual printer. Map from tool id (0, 1, ...) to temperature
    # in °C
    numExtruders: 1

    # Allows pinning certain hotends to a fixed temperature
    pinnedExtruders: null

    # Whether to include the current tool temperature in the M105 output as separate T segment or not.
    #
    # True:  > M105
    #        < ok T:23.5/0.0 T0:34.3/0.0 T1:23.5/0.0 B:43.2/0.0
    # False: > M105
    #        < ok T0:34.3/0.0 T1:23.5/0.0 B:43.2/0.0
    includeCurrentToolInTemps: true

    # Whether to include the selected filename in the M23 File opened response.
    #
    # True:  > M23 filename.gcode
    #        < File opened: filename.gcode  Size: 27
    # False: > M23 filename.gcode
    #        > File opened
    includeFilenameInOpened: true

    # Whether the simulated printer should also simulate a heated bed or not
    hasBed: true

    # Whether the simulated printer should also simulate a heated chamber or not
    hasChamber: false

    # If enabled, reports the set target temperatures as separate messages from the firmware
    #
    # True:  > M109 S220.0
    #        < TargetExtr0:220.0
    #        < ok
    #        > M105
    #        < ok T0:34.3 T1:23.5 B:43.2
    # False: > M109 S220.0
    #        < ok
    #        > M105
    #        < ok T0:34.3/220.0 T1:23.5/0.0 B:43.2/0.0
    repetierStyleTargetTemperature: false

    # If enabled, uses repetier style resends, sending multiple resends for the same line
    # to make sure nothing gets lost on the line
    repetierStyleResends: false

    # If enabled, ok will be sent before a commands output, otherwise after or inline (M105)
    #
    # True:  > M20
    #        < ok
    #        < Begin file list
    #        < End file list
    # False: > M20
    #        < Begin file list
    #        < End file list
    #        < ok
    okBeforeCommandOutput: false

    # If enabled, reports the first extruder in M105 responses as T instead of T0
    #
    # True:  > M105
    #        < ok T:34.3/0.0 T1:23.5/0.0 B:43.2/0.0
    # False: > M105
    #        < ok T0:34.3/0.0 T1:23.5/0.0 B:43.2/0.0
    smoothieTemperatureReporting: false

    # Settings related to the SD file list output
    sdFiles:
      # Whether M20 responses will include filesize or not
      #
      # True:  <filename> <filesize in bytes>
      # False: <filename>
      size: true

      # Whether M20 responses will include timestamp or not (only if size = true as well)
      #
      # True: <filename> <filesize in bytes> <timestamp as hex>
      # False: <filename> <filesize in bytes>
      timestamp: false

      # Whether M20 responses will include longname or not (only if size = true as well)
      #
      # True:  <filename> <filesize in bytes> <longname>
      # False: <filename> <filesize in bytes>
      longname: false

    # Forced pause for retrieving from the outgoing buffer
    throttle: 0.01

    # Whether to send "wait" responses every "waitInterval" seconds when serial rx buffer is empty
    sendWait: false

    # Interval in which to send "wait" lines when rx buffer is empty
    waitInterval: 1

    # Size of the simulated RX buffer in bytes, when it's full a send from OctoPrint's
    # side will block
    rxBuffer: 64

    # Size of simulated command buffer, number of commands. If full, buffered commands will block
    # until a slot frees up
    commandBuffer: 4

    # Whether to support the M112 command with simulated kill
    supportM112: true

    # Whether to send messages received via M117 back as "echo:" lines
    echoOnM117: true

    # Whether to simulate broken M29 behaviour (missing ok after response)
    brokenM29: true

    # Whether F is supported as individual command
    supportF: false

    # Firmware name to report (useful for testing firmware detection)
    firmwareName: Virtual Marlin 1.0

    # Simulate a shared nozzle
    sharedNozzle: false

    # Send "busy" messages if busy processing something
    sendBusy: false

    # Simulate a reset on connect
    simulateReset: true

    # Lines to send on simulated reset
    resetLines:
    - start
    - "Marlin: Virtual Marlin!"
    - "SD card ok"

    # Initial set of prepared oks to use instead of regular ok (e.g. to simulate
    # mis-sent oks). Can also be filled at runtime via the debug command prepare_ok
    preparedOks: []

    # Format string for ok response.
    #
    # Placeholders:
    # - lastN: last acknowledged line number
    # - buffer: empty slots in internal command buffer
    #
    # Example format string for "extended" ok format:
    #   ok N{lastN} P{buffer}
    okFormatString: ok

    # Format string for M115 output.
    #
    # Placeholders:
    # - firmare_name: The firmware name as defined in firmwareName
    m115FormatString: "FIRMWARE_NAME: {firmware_name} PROTOCOL_VERSION:1.0"

    # Whether to include capability report in M115 output
    m115ReportCapabilities: true

    # Capabilities to report if capability report is enabled
    capabilities:
      AUTOREPORT_TEMP: true
      AUTOREPORT_TEMP: true
      AUTOREPORT_SD_STATUS: true
      AUTOREPORT_POS: false
      EMERGENCY_PARSER: true
      EXTENDED_M20: false
      LFN_WRITE: false

    # Whether to include area report in the M115 output (M115_GEOMETRY_REPORT in Marlin)
    m115ReportArea: false

    # Simulated ambient temperature in °C
    ambientTemperature: 21.3

    # Response to M105 when there is a target
    # Placeholders:
    # - heater: The heater id (eg. T0, T1, B)
    # - actual: The actual temperature of the heater
    # - target: The target temperature of heater
    m105TargetFormatString: {heater}:{actual:.2f}/ {target:.2f}

    # Response to M105 when there is no target
    # Placeholders:
    # - heater: The heater id (eg. T0, T1, B)
    # - actual: The actual temperature of the heater
    m105NoTargetFormatString: {heater}:{actual:.2f}

    # Enable virtual EEPROM
    # If enabled, a file `eeprom.json` will be created in the plugin data folder
    # to enable settings persistence across connections. Enables M500/1/2/4 commands
    # And a selection of other settings commands. Responses modeled on Marlin 2.0
    enable_eeprom: true

    # Support M503
    support_m503: true

    # Resend ratio to simulate noise on the line
    resend_ratio: 0

    # communication errors to simulate at specific line numbers
    simulated_errors:
    - 100:resend  # requests a simple resend at line 100
    - 105:resend_with_timeout  # requests a resend at line 105 and simulates not responding to it
    - 110:missing_lineno  # simulates a missing line number at line 110
    - 115:checksum_mismatch  # simulates a checksum mismatch at line 115

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 logs 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.