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

Virtual printer configuration options¶

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

Defaults¶

plugins:
  virtual_printer:
    ambientTemperature: 21.3
    brokenM29: true
    brokenResend: false
    busyInterval: 2.0
    capabilities:
      AUTOREPORT_POS: false
      AUTOREPORT_SD_STATUS: true
      AUTOREPORT_TEMP: true
      BUSY_PROTOCOL: false
      CHAMBER_TEMPERATURE: false
      EMERGENCY_PARSER: true
      EXTENDED_M20: false
      LFN_WRITE: false
    commandBuffer: 4
    echoOnM117: true
    enable_eeprom: true
    enabled: false
    errors:
      checksum_mismatch: Checksum mismatch
      checksum_missing: Missing checksum
      command_unknown: Unknown command {}
      lineno_mismatch: expected line {} got {}
      lineno_missing: 'No Line Number with checksum, Last Line: {}'
      maxtemp: MAXTEMP triggered!
      mintemp: MINTEMP triggered!
    fanMaxSpeed: 4560
    firmwareName: Virtual Marlin 1.0
    forceChecksum: false
    hasBed: true
    hasChamber: false
    includeCurrentToolInTemps: true
    includeFilenameInOpened: true
    klipperTemperatureReporting: false
    locked: false
    m105NoTargetFormatString: '{heater}:{actual:.2f}'
    m105TargetFormatString: '{heater}:{actual:.2f}/ {target:.2f}'
    m114FormatString: 'X:{x} Y:{y} Z:{z} E:{e[current]} Count: A:{a} B:{b} C:{c}'
    m115FormatString: FIRMWARE_NAME:{firmware_name} PROTOCOL_VERSION:1.0
    m115ReportArea: false
    m115ReportCapabilities: true
    m123PowerFormatString: '{fan}@:{power}'
    m123RPMFormatString: '{fan}:{rpm} RPM'
    numExtruders: 1
    okAfterResend: false
    okBeforeCommandOutput: false
    okFormatString: ok
    passcode: '1234'
    pinnedExtruders: null
    preparedOks: []
    repetierStyleTargetTemperature: false
    resend_ratio: 0.0
    resetLines:
    - start
    - 'Marlin: Virtual Marlin!'
    - "\x80"
    - SD card ok
    rxBuffer: 64
    sdFiles:
      longname: false
      longname_quoted: true
      size: true
      timestamp: false
      upper_case: false
    sendBusy: false
    sendWait: true
    sharedNozzle: false
    simulateReset: true
    simulated_errors:
    - 100:resend
    - 105:resend_with_timeout
    - 110:missing_lineno
    - 115:checksum_mismatch
    smoothieTemperatureReporting: false
    supportF: false
    supportM112: true
    support_M503: true
    throttle: 0.01
    waitInterval: 1.0

Data model¶

Name	Type	Description	Default
`enabled`	`bool`	Whether to enable the virtual printer and include it in the list of available serial connections.	`False`
`okAfterResend`	`bool`	Whether to send an additional “ok” after a resend request (like Repetier)	`False`
`forceChecksum`	`bool`	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	`False`
`numExtruders`	`int`	Number of extruders to simulate on the virtual printer. Map from tool id (0, 1, …) to temperature in °C	`1`
`pinnedExtruders`	`dict[int, float]`	Allows pinning certain hotends to a fixed temperature	unset
`includeCurrentToolInTemps`	`bool`	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`	`True`
`includeFilenameInOpened`	`bool`	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`	`True`
`hasBed`	`bool`	Whether the simulated printer should also simulate a heated bed or not	`True`
`hasChamber`	`bool`	Whether the simulated printer should also simulate a heated chamber or not	`False`
`repetierStyleTargetTemperature`	`bool`	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`	`False`
`okBeforeCommandOutput`	`bool`	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`	`False`
`smoothieTemperatureReporting`	`bool`	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`	`False`
`klipperTemperatureReporting`	`bool`	Whether to report the hotend temperatures as `T0` even with a single extruder (Klipper behaviour)	`False`
`sdFiles.*`		Settings related to the SD file list output General format: `<filename>[ <filesize in bytes> [ <timestamp>][ (<longname> \| "<longname>")]]`
`sdFiles.size`	`bool`	Whether M20 responses will include filesize or not True: `<filename> <filesize in bytes>` False: `<filename>`	`True`
`sdFiles.timestamp`	`bool`	Whether M20 responses will include timestamp or not (only if `size` is enabled) True: `<filename> <filesize in bytes> <timestamp as hex>` False: `<filename> <filesize in bytes>`	`False`
`sdFiles.longname`	`bool`	Whether M20 responses will include longname or not (only if `size` is enabled) Mutually exclusive with `longname_quoted` True: `<filename> <filesize in bytes> <longname>` False: `<filename> <filesize in bytes>`	`False`
`sdFiles.longname_quoted`	`bool`	Whether M20 responses will include quoted longname or not (only if `size` is enabled) Mutually exclusive with `longname`. True: `<filename> <filesize in bytes> "<longname>"` False: `<filename> <filesize in bytes>`	`True`
`sdFiles.upper_case`	`bool`	Whether to uppercase the filenames in M20 responses	`False`
`throttle`	`float`	Forced pause for retrieving from the outgoing buffer	`0.01`
`sendWait`	`bool`	Whether to send “wait” responses every “waitInterval” seconds when serial rx buffer is empty	`True`
`waitInterval`	`float`	Interval in which to send “wait” lines when rx buffer is empty	`1.0`
`rxBuffer`	`int`	Size of the simulated RX buffer in bytes, when it’s full a send from OctoPrint’s side will block	`64`
`commandBuffer`	`int`	Size of simulated command buffer, number of commands. If full, buffered commands will block until a slot frees up	`4`
`supportM112`	`bool`	Whether to support the M112 command with simulated kill	`True`
`echoOnM117`	`bool`	Whether to send messages received via M117 back as “echo:” lines	`True`
`brokenM29`	`bool`	Whether to simulate broken M29 behaviour (missing ok after response)	`True`
`brokenResend`	`bool`	Whether to simulate broken resend behaviour (missing ok after response)	`False`
`supportF`	`bool`	Whether F is supported as individual command	`False`
`firmwareName`	`str`	Firmware name to report (useful for testing firmware detection) Default: `'Virtual Marlin 1.0'`	see left
`sharedNozzle`	`bool`	Simulate a shared nozzle	`False`
`sendBusy`	`bool`	Send “busy” messages if busy processing something	`False`
`busyInterval`	`float`	Interval in which to send “busy” lines while processing	`2.0`
`simulateReset`	`bool`	Simulate a reset on connect	`True`
`resetLines`	`list[str]`	Lines to send on simulated reset Default: `['start', 'Marlin: Virtual Marlin!', '\x80', 'SD card ok']`	see left
`preparedOks`	`list[str]`	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	`[]`
`okFormatString`	`str`	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}`	`'ok'`
`m115FormatString`	`str`	Format string for M115 output. Placeholders: `firmware_name`: The firmware name as defined in firmwareName Default: `'FIRMWARE_NAME:{firmware_name} PROTOCOL_VERSION:1.0'`	see left
`m115ReportCapabilities`	`bool`	Whether to include capability report in M115 output	`True`
`capabilities`	`dict[str, bool]`	Capabilities to report if capability report is enabled Default: `{'AUTOREPORT_TEMP': True, 'AUTOREPORT_SD_STATUS': True, 'AUTOREPORT_POS': False, 'BUSY_PROTOCOL': False, 'CHAMBER_TEMPERATURE': False, 'EMERGENCY_PARSER': True, 'EXTENDED_M20': False, 'LFN_WRITE': False}`	see left
`m115ReportArea`	`bool`	Whether to include area report in the M115 output (M115_GEOMETRY_REPORT in Marlin)	`False`
`m114FormatString`	`str`	Default: `'X:{x} Y:{y} Z:{z} E:{e[current]} Count: A:{a} B:{b} C:{c}'`	see left
`m105TargetFormatString`	`str`	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 Default: `'{heater}:{actual:.2f}/ {target:.2f}'`	see left
`m105NoTargetFormatString`	`str`	Response to M105 when there is no target Placeholders: `heater`: The heater id (eg. `T0`, `T1`, `B`) `actual`: The actual temperature of the heater Default: `'{heater}:{actual:.2f}'`	see left
`m123RPMFormatString`	`str`	Response to M123 for fan RPM Placeholders: `fan`: The fan id (e.g. E0) `rpm`: The rotation speed of the fan Default: `'{fan}:{rpm} RPM'`	see left
`m123PowerFormatString`	`str`	Response to M123 for fan power level Placeholders: `fan`: The fan id (e.g. E0) `power`: The power level being delivered to the fan Default: `'{fan}@:{power}'`	see left
`ambientTemperature`	`float`	Simulated ambient temperature in °C	`21.3`
`fanMaxSpeed`	`int`	The maximum speed (in RPM) the virtual printer’s virtual fans can spin at	`4560`
`errors.*`		Format strings for various error types
`errors.checksum_mismatch`	`str`	Default: `'Checksum mismatch'`	see left
`errors.checksum_missing`	`str`	Default: `'Missing checksum'`	see left
`errors.lineno_mismatch`	`str`	Default: `'expected line {} got {}'`	see left
`errors.lineno_missing`	`str`	Default: `'No Line Number with checksum, Last Line: {}'`	see left
`errors.maxtemp`	`str`	Default: `'MAXTEMP triggered!'`	see left
`errors.mintemp`	`str`	Default: `'MINTEMP triggered!'`	see left
`errors.command_unknown`	`str`	Default: `'Unknown command {}'`	see left
`enable_eeprom`	`bool`	Enable virtual EEPROM If enabled, a file `eeprom.json` will be created in the plugin data folder to enable settings persistence across connections. Enables `M50{0124}` commands and a selection of other settings commands. Responses modeled on Marlin 2.0	`True`
`support_M503`	`bool`	Support M503	`True`
`resend_ratio`	`float`	Resend ratio to simulate noise on the line	`0`
`locked`	`bool`	Whether the printer starts out as locked (active `M510`)	`False`
`passcode`	`str`	Passcode for unlocking the printer via `M511`	`'1234'`
`simulated_errors`	`list[str]`	Communication errors to simulate at specific line numbers, format `<lineno>:<resend type>` Default: `['100:resend', '105:resend_with_timeout', '110:missing_lineno', '115:checksum_mismatch']`	see left

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.