Lab 1 — A printer that exists only in software
📍 Where we are: Part IV · Virtual Labs: Build Without Hardware — Chapter 10 of 16. Chapters 1-9 described the open-source stack; this is the first chapter where you run it. The next lab feeds real sliced G-code into the printers you build here.
A flight simulator lets a trainee crash a plane without hurting anyone. This chapter is a flight simulator for 3D printers. The real firmware, the program that turns "move 20 mm" into motor pulses, runs on your laptop, and a fake printer pretends to be the motors and heaters. You can send it G-code, watch what it decides to do, and break things on purpose to see how it protects itself.
What this chapter covers
We run five things: Klipper in batch mode, Klipper's real AVR firmware inside an instruction-set simulator (simulavr), Marlin's native simulator, OctoPrint's bundled Virtual Printer, and Moonraker on top of the simulated Klipper. Then we inject faults and read how each reacts. Everything lives in examples/lab-virtual-printer/. All output below is from our run on 2026-11-15 on an Apple-silicon Mac (arm64 Docker, Debian 12 images): Klipper v0.13.0, Marlin bugfix-2.1.x built that day, OctoPrint 1.11.8, Moonraker v0.11.0, PlatformIO 6.2.0, avr-gcc 5.4.0. Once the images exist, the whole make run takes 2.5 minutes.
What is real and what is pretend
A virtual printer is only useful if you know which parts to trust. The figure shows the stack layer by layer.
Klipper batch mode and OctoPrint's printer are cheap and fast but skip layers; simulavr and the Marlin simulator run real firmware code but never real electronics.
Original diagram by the authors, created with AI assistance.
Marlin's own documentation is blunt about the limit: the simulator has no real electronics or interrupt timing and cannot check driver configuration, thermistor tables or board pin choices [1]. Use virtual printers to test logic and protocol, never to certify hardware.
Step 0: build the images
cd examples/lab-virtual-printer
make images # Klipper, Marlin, OctoPrint, Moonraker images
Our timings: the Klipper image took 8 min 12 s the first time (apt packages plus a failed first attempt at the simulavr build; rebuilding that layer after the fix took 49 s); Marlin took 3 min 44 s from scratch, of which the PlatformIO compile was 53 s; OctoPrint 42 s; Moonraker about 20 s on top of the Klipper image.
Step 1: Klipper batch mode
Klipper's Debugging page describes a mode where the host software reads G-code from a file and writes the binary commands it would have sent to the microcontroller into another file, which parsedump.py decodes using the firmware's data dictionary [2]. No printer, not even a simulated one. First compile a firmware to get the dictionary (we use the AVR atmega644p that Klipper's simulavr config expects), then:
python klippy/klippy.py printer-sim.cfg -i square.gcode -o test.serial -v -d out/klipper.dict
python klippy/parsedump.py out/klipper.dict test.serial > test.txt
square.gcode draws a 20 mm square at F6000 (100 mm/s). make klipper-batch runs it all; the first X-axis commands decode to:
set_next_step_dir oid=0 dir=1
queue_step oid=0 interval=4048660 count=1 add=0
queue_step oid=0 interval=23659 count=2 add=-6948
queue_step oid=0 interval=12983 count=4 add=-1220
...
queue_step oid=0 interval=2000 count=1330 add=0
Exiting (print time 1.175s)
Read it like this. The AVR clock is 16 MHz and the X axis has 80 steps/mm (config: 40 mm per rotation, 200 full steps, 16 microsteps). A step every 2000 ticks is 8000 steps/s, which is 100 mm/s: the cruise. The earlier lines are the acceleration ramp (interval shrinks by add ticks per step). The first interval, 4,048,660 ticks, is 0.253 s: Klipper keeps a 0.25 s start-up buffer in toolhead.py. Four 20 mm moves took 1.175 s of print time including that buffer, so about 0.925 s of motion. Lab 2 uses this number as ground truth for a whole print.
Step 2: the real AVR firmware inside simulavr
Batch mode never runs a microcontroller. simulavr does: it executes the compiled AVR machine code instruction by instruction and exposes a pseudo serial port, so klippy connects as if to a board [3] [2]. Its Python module needs a full git clone to build, because the CMake step runs git describe (see When it breaks). With -t PORTA.PORT it also writes every change of the pin levels to a trace file. Our vcd_steps.py counts the pulses on the X and Y step pins:
make klipper-sim
X: 3200 steps (dir pin low: 1600, high: 1600), net 0.000 mm, first-to-last step 0.683 s simulated
Y: 3200 steps (dir pin low: 1600, high: 1600), net 0.000 mm, first-to-last step 0.683 s simulated
all axes: first step to last step 0.912 s simulated
Two independent checks pass. A 20 mm square is 80 mm of path per axis pair, 1600 steps at 80 steps/mm per leg, and the firmware really toggled the pins 3200 times per axis with the direction pin flipping halfway. The time between the first and last step, 0.912 s, is within 1.4 % of the 0.925 s Klipper's planner predicted (we did not chase the 13 ms gap). klippy warned configured for 16Mhz but running at 2Mhz: simulavr runs roughly 6-7 times slower than a real AVR on our machine. Klipper copes because it keeps estimating the clock it actually gets (freq=2448135 in its log).
Step 3: Klipper's Linux-process MCU
Klipper can also compile its microcontroller code as an ordinary Linux program, which is how a Raspberry Pi's own pins are used as a secondary MCU; it appears as /tmp/klipper_host_mcu [4]. make linux-mcu runs it and connects klippy:
MCU 'mcu' config: ADC_MAX=4095 CLOCK_FREQ=50000000 MCU=linux PCA9685_MAX=4096 PWM_MAX=32768 ...
Configured MCU 'mcu' (1024 moves)
The protocol handshake works. Asking it to switch a pin does not, because a container has no /dev/gpiochip0; the firmware itself reports the failure and klippy shuts down (MCU 'mcu' shutdown: GPIO chip device not found). So this path tests the host/MCU conversation, not stepping.
Step 4: Marlin's native simulator
The Marlin simulator is a desktop program that draws a 3D view and a display, so it needs a screen; we give it a virtual one with Xvfb inside the container [1]. A current MarlinSimUI also exposes an HTTP/JSON "agent" interface on 127.0.0.1 that accepts G-code, reports ground truth about simulated parts and can fast-forward time [5]. Two settings matter: it only reads that G-code stream if SERIAL_PORT_2 3 is enabled (our Dockerfile does it), and the agent port is not reachable through Docker port mapping, so our clients run inside the container with docker exec.
marlin/run-marlin.sh basic
> M115
< FIRMWARE_NAME:Marlin bugfix-2.1.x (Nov 15 2026 17:55:59) SOURCE_CODE_URL:github.com/MarlinFirmware/M...
> M105
< ok T:25.00 /0.00 B:25.00 /0.00 @:0 B@:0 [t=7.15s]
> M203
< M203 X300.00 Y300.00 Z5.00 E25.00 [t=7.35s]
> G28
< X:220.00 Y:200.00 Z:5.00 E:0.00 Count X:17600 Y:16000 Z:2000 [t=42.88s]
> G1 X50 Y50 F6000
< ok P14 B3 [t=42.97s]
> M400
< ok P15 B3 [t=45.40s]
> M114
< X:50.00 Y:50.00 Z:5.00 E:0.00 Count X:4000 Y:4000 Z:2000 [t=45.41s]
t= is simulated seconds. Count X:4000 is the stepper position in steps: 50 mm times 80 steps/mm. The line after M203 is Marlin's maximum feedrate (300 mm/s on X and Y, 5 mm/s on Z), which we use next.
Step 5: break things on purpose
A safety system you have never seen fire is a safety system you do not understand. Each experiment below is a script in the lab folder and its result is from our run.
Too fast (Klipper, Marlin). We asked for F600000, 10,000 mm/s, on a machine limited to 500 mm/s (Klipper) and 300 mm/s (Marlin). Neither complains; both quietly clamp. In Klipper the fastest X step interval in the decoded output is 400 ticks, which is 40,000 steps/s or exactly 500 mm/s. In Marlin a 200 mm move took 1.01 s at both F18000 and F600000, identical because both are clamped to 300 mm/s.
Out of range (Klipper). G1 X250 on a 200 mm axis: Move out of range: 250.000 0.000 0.000 [0.000], and no motion is emitted (0 queue_step lines).
Missing heater (Klipper). With the [extruder] section deleted, M104 S200 gives Unknown command:"M104": the command does not exist until a config creates it.
Dead heater (Klipper + simulavr, Marlin). In simulavr nothing drives the thermistor's ADC pin with a thermal model, so the extruder never warms up (its log shows temp=0.0 throughout; in another run the undriven bed pin read 103.3, an artefact). With a deliberately shortened [verify_heater extruder] section [6], M104 S200 ends in Heater extruder not heating at expected rate and Transition to shutdown state. Marlin has a thermal model, so we can break parts of it. After M104 S200, setting the heater cartridge to failed (element_ok false):
Error:Heating failed, system stopped! Heater_ID: E0 [t=46.0s]
Error:Printer halted. kill() called! [t=46.0s]
Setting the sensor to its open-circuit mode (ForceMax, reads as very cold) triggers Error:MINTEMP triggered, system stopped! within a simulated second, and the shorted mode (ForceMin) triggers Error:MAXTEMP triggered. A halted Marlin stops answering G-code, which our scripts show by waiting 3 s for a reply that never comes.
Step 6: OctoPrint and Moonraker
OctoPrint ships a Virtual Printer plugin that fakes a serial printer: enable it in config.yaml, connect to the port VIRTUAL, and it logs all traffic to plugin_virtual_printer_serial.log [7]. It models no motion (our 20 mm-square job "printed" in 5 s of wall time), but it can simulate protocol faults. With simulated_errors set to 4:resend, 6:checksum_mismatch, 8:missing_lineno and a job uploaded and started through OctoPrint's REST API [8], the log shows the host recovering:
<<< N4 G90*20
>>> Error: Missing checksum
>>> Resend:4
<<< N4 G90*20
...
>>> Error: Checksum mismatch
>>> Resend:6
Moonraker is a Python web server that exposes an API for client applications to work with Klipper [9]; it needs a running Klipper, so make moonraker starts klippy on the simulated AVR and then Moonraker v0.11.0:
klippy state: ready | version: v0.13.0-0-g61c0c8d
POST gcode/script 'G1 X20 F6000' -> ok
toolhead position: [20.0, 0.0, 0.0, 0.0] | max_velocity: 500.0
POST gcode/script 'G1 X999 F6000' -> Move out of range: 999.000 0.000 0.000 [0.000]
When it breaks
- simulavr fails to configure with
string sub-command REPLACE requires at least four arguments. Cause: we usedgit clone --depth 1; the build runsgit describe. Fix: full clone. - OctoPrint's
pip installfails compilingnetifaceson arm64 (gcc: No such file). Fix: install a compiler for the build and remove it afterwards. - Marlin 2.1.2.10 (the latest release) builds and listens on TCP 8099 but never answers. In the MarlinSimUI source we read, the socket only feeds serial stream 3; Marlin's replies on that stream went to the GUI's serial monitor, not back to the socket. The agent interface that fixes this is in the
bugfix-2.1.xbranch, so we build that and print the build date fromM115. - Commands accepted, nothing happens.
SERIAL_PORT_2 3was still commented out. Our firstsedmissed the line (it ends in a comment), so the build looked fine and/idlestayedrx_pending: true. Fix: the Dockerfile now fails the build if the line is absent. MarlinSimulator --helphangs in an unattended shell: it opens a window. Always run it underxvfb-run.- Fast-forwarding breaks timing. At
realtime_scale20 the same 200 mm move measured 2.4 s instead of 1.0 s. Our explanation, which we did not test further, is that the host cannot service the step interrupts 20 times faster and the simulated clock slips. Fast-forward homing and heating, never measure motion time. SET_KINEMATIC_POSITIONis unknown in Klipper unless the config contains[force_move]withenable_force_move: True[6].
What to try next
- In batch mode set
max_accelto 1000 and 6000 and compare the decoded ramps and print time. - Add
[verify_heater]defaults back and measure how many simulated seconds Klipper waits before it gives up. - Use the agent's pin interface to drive an endstop input in Marlin and watch
M119change. - Add a second extruder to the Klipper config and see how the dictionary and
queue_stepstream change. - Replay a printed layer of real G-code: that is Lab 2.
Why it matters
Firmware and host software are where most printer bugs and safety behaviour live, and until now you could only study them by owning a printer and risking it. A virtual printer makes each experiment cheap, repeatable and safe, and, because it runs in a container, shareable as a short script. It also teaches the discipline of every simulator: know exactly what it does not model.
In the real world
Klipper's repository ships a CI script that runs klippy over many test G-code files against compiled dictionaries [10], and Marlin's documentation says the Simulator build is one of the tests its CI runs on every pull request [11]. The same tools that gate the projects' own changes are the ones this lab hands you.
Key terms
- Batch mode — running Klipper's host software on a G-code file and writing the MCU commands to a file instead of a printer.
- Data dictionary — the file the firmware build produces that lists every command the microcontroller understands, needed to decode its traffic.
- queue_step — the Klipper MCU command that schedules a run of steps: an initial interval, a count and a change per step.
- simulavr — an instruction-set simulator for AVR microcontrollers that can run real firmware images.
- VCD trace — a text log of signal changes over time, readable by waveform viewers or a short script.
- Xvfb — a virtual X display that lets programs which insist on a window run on a server.
- Agent interface — MarlinSimUI's HTTP/JSON endpoint for sending G-code, reading simulated state and injecting faults.
- Fault injection — deliberately breaking a simulated part to observe the firmware's protective response.
- Thermal runaway protection — firmware checks that shut a heater down if the temperature does not behave as a working heater would.
Where this leads
Next, Lab 2 slices a part from the command line, predicts how long it will take, and replays the G-code through the Klipper and Marlin simulators from this chapter to see how well the prediction holds.