실습 1 — 소프트웨어로만 존재하는 프린터
📍 현재 위치: 4부 · 가상 실습: 하드웨어 없이 만들기 — 16장 중 10장. 1-9장에서는 오픈소스 스택을 설명했고, 이 장은 그것을 처음으로 직접 실행하는 장입니다. 다음 실습에서는 여기서 만든 프린터에 실제로 슬라이싱한 G-code를 흘려 보냅니다.
비행 시뮬레이터에서는 훈련생이 아무도 다치지 않게 비행기를 추락시킬 수 있습니다. 이 장은 3D 프린터를 위한 비행 시뮬레이터입니다. "20 mm 이동"을 모터 펄스로 바꾸는 진짜 펌웨어는 노트북에서 돌아가고, 가짜 프린터가 모터와 히터 역할을 흉내 냅니다. G-code를 보내고, 펌웨어가 무엇을 결정하는지 지켜보고, 일부러 고장을 내서 펌웨어가 스스로를 어떻게 보호하는지 볼 수 있습니다.
이 장에서 다루는 내용
다섯 가지를 실행합니다. Klipper의 배치 모드(batch mode), 명령어 집합 시뮬레이터(simulavr) 안에서 도는 Klipper의 실제 AVR 펌웨어, Marlin의 네이티브 시뮬레이터, OctoPrint에 포함된 Virtual Printer, 그리고 시뮬레이션된 Klipper 위에서 도는 Moonraker입니다. 그다음 고장을 주입하고 각각이 어떻게 반응하는지 읽습니다. 모든 것은 examples/lab-virtual-printer/에 있습니다. 아래 출력은 모두 2026-11-15에 Apple 실리콘 Mac(arm64 Docker, Debian 12 이미지)에서 실행한 결과입니다. 버전은 Klipper v0.13.0, 그날 빌드한 Marlin bugfix-2.1.x, OctoPrint 1.11.8, Moonraker v0.11.0, PlatformIO 6.2.0, avr-gcc 5.4.0입니다. 이미지가 준비되면 make run 전체가 2.5분 걸립니다.
무엇이 진짜이고 무엇이 흉내인가
가상 프린터는 어느 부분을 믿어도 되는지 알아야 쓸모가 있습니다. 그림은 스택을 층별로 보여 줍니다.
Klipper 배치 모드와 OctoPrint의 프린터는 가볍고 빠르지만 일부 계층을 건너뜁니다. simulavr와 Marlin 시뮬레이터는 실제 펌웨어 코드를 실행하지만 실제 전자 장치는 실행하지 않습니다.
저자가 AI의 도움을 받아 직접 제작한 그림입니다.
Marlin 공식 문서도 한계를 분명히 말합니다. 시뮬레이터에는 실제 전자 장치와 인터럽트 타이밍이 없고, 드라이버 설정, 서미스터 테이블, 보드 핀 선택은 검증할 수 없습니다 [1]. 가상 프린터는 로직과 프로토콜을 시험하는 데 쓰고, 하드웨어를 인증하는 데는 쓰지 마십시오.
0단계: 이미지 빌드
cd examples/lab-virtual-printer
make images # Klipper, Marlin, OctoPrint, Moonraker images
저희가 잰 시간은 다음과 같습니다. Klipper 이미지는 처음에 8분 12초 걸렸습니다(apt 패키지와, simulavr 빌드의 첫 시도 실패가 포함된 시간이며, 고친 뒤 그 계층만 다시 빌드하는 데 49초 걸렸습니다). Marlin은 처음부터 빌드하는 데 3분 44초였고 그중 PlatformIO 컴파일이 53초였습니다. OctoPrint는 42초, Moonraker는 Klipper 이미지 위에서 약 20초였습니다.
1단계: Klipper 배치 모드
Klipper의 Debugging 문서는 호스트 소프트웨어가 파일에서 G-code를 읽고, 마이크로컨트롤러로 보냈을 이진 명령을 다른 파일에 쓰는 모드를 설명합니다. 그 파일은 펌웨어의 데이터 사전(data dictionary)을 이용해 parsedump.py로 해독합니다 [2]. 프린터는 필요 없고, 시뮬레이션된 프린터조차 필요 없습니다. 먼저 사전을 얻기 위해 펌웨어를 컴파일합니다(Klipper의 simulavr 설정이 요구하는 AVR atmega644p를 사용합니다). 그다음 다음을 실행합니다.
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는 F6000(100 mm/s)로 20 mm 정사각형을 그립니다. make klipper-batch가 모두 실행하며, X축의 첫 명령은 다음과 같이 해독됩니다.
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)
이렇게 읽습니다. AVR 클럭은 16 MHz이고 X축은 mm당 80스텝입니다(설정: 1회전 40 mm, 풀스텝 200, 마이크로스텝 16). 2000틱마다 한 스텝이면 초당 8000스텝, 즉 100 mm/s로 순항 구간입니다. 앞의 줄들은 가속 구간입니다(interval이 스텝마다 add 틱씩 줄어듭니다). 첫 간격 4,048,660틱은 0.253초인데, Klipper가 toolhead.py에서 0.25초의 시작 버퍼를 두기 때문입니다. 20 mm 이동 네 번에 이 버퍼를 포함해 1.175초의 출력 시간(print time)이 걸렸으니, 실제 움직임은 약 0.925초입니다. 실습 2는 이 숫자를 출력 전체의 기준값으로 씁니다.
2단계: simulavr 안의 진짜 AVR 펌웨어
배치 모드는 마이크로컨트롤러를 전혀 실행하지 않습니다. simulavr는 실행합니다. 컴파일된 AVR 기계어 코드를 명령어 단위로 실행하고 가상 시리얼 포트를 열어 주므로, klippy는 실제 보드에 연결하듯 접속합니다 [3] [2]. 파이썬 모듈을 빌드하려면 git 전체 클론이 필요한데, CMake 단계가 git describe를 실행하기 때문입니다(고장 났을 때 참고). -t PORTA.PORT를 주면 핀 레벨이 바뀔 때마다 추적 파일에 기록합니다. 저희가 만든 vcd_steps.py는 X, Y 스텝 핀의 펄스를 셉니다.
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
독립적인 확인 두 가지가 통과합니다. 20 mm 정사각형은 변마다 mm당 80스텝이므로 한 변이 1600스텝이고, 펌웨어는 축마다 핀을 실제로 3200번 토글했으며 방향 핀은 중간에 뒤집혔습니다. 첫 스텝부터 마지막 스텝까지의 시간 0.912초는 Klipper 플래너가 예측한 0.925초와 1.4 % 이내입니다(13 ms 차이는 추적하지 않았습니다). klippy는 configured for 16Mhz but running at 2Mhz라고 경고했습니다. 저희 컴퓨터에서 simulavr는 실제 AVR보다 대략 6-7배 느립니다. Klipper는 실제로 얻는 클럭을 계속 추정하므로 문제없이 동작합니다(로그의 freq=2448135).
3단계: Klipper의 Linux 프로세스 MCU
Klipper는 마이크로컨트롤러 코드를 보통의 Linux 프로그램으로 컴파일할 수도 있습니다. 라즈베리 파이 자체의 핀을 보조 MCU로 쓰는 방식이며, /tmp/klipper_host_mcu로 나타납니다 [4]. make linux-mcu가 이를 실행하고 klippy를 연결합니다.
MCU 'mcu' config: ADC_MAX=4095 CLOCK_FREQ=50000000 MCU=linux PCA9685_MAX=4096 PWM_MAX=32768 ...
Configured MCU 'mcu' (1024 moves)
프로토콜 핸드셰이크는 동작합니다. 그러나 핀을 켜라고 요청하면 동작하지 않습니다. 컨테이너에는 /dev/gpiochip0이 없기 때문입니다. 펌웨어가 직접 실패를 보고하고 klippy는 종료됩니다(MCU 'mcu' shutdown: GPIO chip device not found). 따라서 이 경로는 스테핑이 아니라 호스트와 MCU 사이의 대화를 시험합니다.
4단계: Marlin 네이티브 시뮬레이터
Marlin 시뮬레이터는 3D 화면과 디스플레이를 그리는 데스크톱 프로그램이라 화면이 필요합니다. 컨테이너 안에서 Xvfb로 가상 화면을 줍니다 [1]. 최신 MarlinSimUI는 127.0.0.1에서 HTTP/JSON "에이전트" 인터페이스도 제공합니다. G-code를 받고, 시뮬레이션된 부품의 실제 상태를 보고하며, 시간을 빨리 감을 수 있습니다 [5]. 중요한 설정이 두 가지 있습니다. SERIAL_PORT_2 3이 켜져 있어야만 그 G-code 스트림을 읽고(저희 Dockerfile이 켭니다), 에이전트 포트는 Docker 포트 매핑으로 접근할 수 없으므로 저희 클라이언트는 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=는 시뮬레이션된 초입니다. Count X:4000은 스테퍼 위치(스텝 수)로, 50 mm 곱하기 80스텝/mm입니다. M203 다음 줄은 Marlin의 최대 이송 속도(X, Y는 300 mm/s, Z는 5 mm/s)이며 다음에 사용합니다.
5단계: 일부러 고장 내기
한 번도 작동하는 것을 본 적 없는 안전 장치는 이해하지 못한 안전 장치입니다. 아래 실험은 각각 실습 폴더의 스크립트이며 결과는 저희 실행에서 나온 것입니다.
너무 빠르게(Klipper, Marlin). 500 mm/s(Klipper)와 300 mm/s(Marlin)로 제한된 기계에 F600000, 즉 10,000 mm/s를 요구했습니다. 둘 다 불평하지 않고 조용히 속도를 제한합니다. Klipper에서는 해독된 출력의 가장 빠른 X 스텝 간격이 400틱으로, 초당 40,000스텝, 정확히 500 mm/s입니다. Marlin에서는 200 mm 이동이 F18000과 F600000 모두에서 1.01초 걸렸는데, 둘 다 300 mm/s로 제한되기 때문에 같습니다.
범위 초과(Klipper). 200 mm 축에 G1 X250: Move out of range: 250.000 0.000 0.000 [0.000]이 나오고 동작은 만들어지지 않습니다(queue_step 줄 0개).
히터 없음(Klipper). [extruder] 섹션을 지우면 M104 S200은 Unknown command:"M104"를 냅니다. 설정이 만들어 주기 전에는 그 명령이 존재하지 않습니다.
죽은 히터(Klipper + simulavr, Marlin). simulavr에서는 서미스터의 ADC 핀을 구동하는 열 모델이 없어서 압출기가 전혀 데워지지 않습니다(로그에 내내 temp=0.0이 찍힙니다. 다른 실행에서는 구동되지 않은 베드 핀이 103.3을 읽었는데, 이는 인위적인 결과입니다). 일부러 짧게 줄인 [verify_heater extruder] 섹션 [6]을 두면 M104 S200은 Heater extruder not heating at expected rate와 Transition to shutdown state로 끝납니다. Marlin에는 열 모델이 있으므로 그 일부를 고장 낼 수 있습니다. M104 S200 뒤에 히터 카트리지를 고장(element_ok false)으로 설정하면 다음과 같습니다.
Error:Heating failed, system stopped! Heater_ID: E0 [t=46.0s]
Error:Printer halted. kill() called! [t=46.0s]
센서를 개방 회로 모드(ForceMax, 매우 차갑게 읽힘)로 두면 시뮬레이션 1초 안에 Error:MINTEMP triggered, system stopped!가 나오고, 단락 모드(ForceMin)는 Error:MAXTEMP triggered를 냅니다. 정지한 Marlin은 G-code에 더 이상 응답하지 않으며, 저희 스크립트는 끝내 오지 않는 응답을 3초 기다려 이를 보여 줍니다.
6단계: OctoPrint와 Moonraker
OctoPrint에는 가짜 시리얼 프린터를 만드는 Virtual Printer 플러그인이 들어 있습니다. config.yaml에서 켜고 VIRTUAL 포트에 연결하면 모든 통신을 plugin_virtual_printer_serial.log에 기록합니다 [7]. 움직임은 모델링하지 않지만(20 mm 정사각형 작업이 실제 시간 5초 만에 "출력"되었습니다) 프로토콜 오류는 흉내 낼 수 있습니다. simulated_errors를 4:resend, 6:checksum_mismatch, 8:missing_lineno로 설정하고 OctoPrint의 REST API [8]로 작업을 올려 시작하면, 로그에서 호스트가 복구하는 모습이 보입니다.
<<< N4 G90*20
>>> Error: Missing checksum
>>> Resend:4
<<< N4 G90*20
...
>>> Error: Checksum mismatch
>>> Resend:6
Moonraker는 클라이언트 응용 프로그램이 Klipper와 함께 쓸 API를 제공하는 파이썬 웹 서버입니다 [9]. 실행 중인 Klipper가 필요하므로 make moonraker는 시뮬레이션된 AVR 위에서 klippy를 띄운 뒤 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]
고장 났을 때
- simulavr 구성 실패:
string sub-command REPLACE requires at least four arguments. 원인은git clone --depth 1을 썼기 때문입니다. 빌드가git describe를 실행합니다. 해결: 전체 클론. - OctoPrint의
pip install실패: arm64에서netifaces컴파일 중gcc: No such file. 해결: 빌드 동안 컴파일러를 설치하고 이후 제거합니다. - Marlin 2.1.2.10(최신 릴리스)은 빌드되고 TCP 8099에서 대기하지만 응답하지 않습니다. 저희가 읽은 MarlinSimUI 소스에서 소켓은 시리얼 스트림 3으로 입력만 전달하고, 그 스트림의 Marlin 응답은 소켓이 아니라 GUI의 시리얼 모니터로 갔습니다. 이를 고치는 에이전트 인터페이스는
bugfix-2.1.x브랜치에 있으므로 그 브랜치를 빌드하고M115로 빌드 날짜를 출력합니다. - 명령은 받아들여지는데 아무 일도 일어나지 않음.
SERIAL_PORT_2 3이 여전히 주석 처리되어 있었습니다. 저희의 첫sed는 그 줄이 주석으로 끝나서 놓쳤고, 빌드는 정상으로 보였으며/idle은 계속rx_pending: true였습니다. 해결: 이제 Dockerfile은 그 줄이 없으면 빌드를 실패시킵니다. MarlinSimulator --help가 멈춤. 창을 열려고 하기 때문입니다. 항상xvfb-run아래에서 실행하십시오.- 빨리 감기는 타이밍을 망칩니다.
realtime_scale20에서 같은 200 mm 이동이 1.0초가 아니라 2.4초로 측정되었습니다. 저희의 설명은(더 시험하지는 않았습니다) 호스트가 스텝 인터럽트를 20배 빠르게 처리하지 못해 시뮬레이션 시계가 밀린다는 것입니다. SET_KINEMATIC_POSITION을 모른다고 나옴. Klipper 설정에[force_move]와enable_force_move: True가 있어야 합니다 [6].
다음에 해볼 것
- 배치 모드에서
max_accel을 1000과 6000으로 바꿔 해독된 가속 구간과 출력 시간을 비교합니다. [verify_heater]기본값을 되돌리고 Klipper가 포기하기까지 시뮬레이션 몇 초를 기다리는지 잽니다.- 에이전트의 핀 인터페이스로 Marlin의 엔드스톱 입력을 구동하고
M119가 바뀌는 것을 봅니다. - Klipper 설정에 두 번째 압출기를 추가하고 사전과
queue_step스트림이 어떻게 바뀌는지 봅니다. - 실제 G-code로 출력한 한 층을 재생합니다. 이것이 실습 2입니다.
왜 중요한가
프린터 버그와 안전 동작의 대부분은 펌웨어와 호스트 소프트웨어에 있는데, 지금까지는 프린터를 갖고 위험을 감수해야만 연구할 수 있었습니다. 가상 프린터는 실험을 값싸고, 반복 가능하고, 안전하게 만들며, 컨테이너에서 실행되므로 짧은 스크립트로 공유할 수도 있습니다. 또한 모든 시뮬레이터의 규율, 즉 무엇을 모델링하지 않는지 정확히 아는 습관을 가르쳐 줍니다.
실제 현장에서는
Klipper 저장소에는 컴파일된 사전을 기준으로 많은 테스트 G-code 파일에 klippy를 돌리는 CI 스크립트가 들어 있고 [10], Marlin 문서는 시뮬레이터 빌드가 모든 풀 리퀘스트마다 CI가 돌리는 테스트 중 하나라고 말합니다 [11]. 프로젝트 자체의 변경을 검증하는 도구와 이 실습이 여러분에게 건네는 도구가 같습니다.
핵심 용어
- 배치 모드(batch mode) — Klipper 호스트 소프트웨어를 G-code 파일에 대해 실행하고 MCU 명령을 프린터 대신 파일에 쓰는 방식.
- 데이터 사전(data dictionary) — 마이크로컨트롤러가 이해하는 모든 명령을 나열한 파일로, 펌웨어 빌드가 만들며 그 통신을 해독하는 데 필요함.
- queue_step — 스텝의 연속을 예약하는 Klipper MCU 명령으로, 초기 간격, 개수, 스텝당 변화량으로 이루어짐.
- simulavr — 실제 펌웨어 이미지를 실행할 수 있는 AVR 마이크로컨트롤러용 명령어 집합 시뮬레이터.
- VCD 추적(VCD trace) — 시간에 따른 신호 변화를 기록한 텍스트 로그로, 파형 뷰어나 짧은 스크립트로 읽을 수 있음.
- Xvfb — 창을 고집하는 프로그램을 서버에서 실행할 수 있게 해 주는 가상 X 디스플레이.
- 에이전트 인터페이스(agent interface) — G-code 전송, 시뮬레이션 상태 읽기, 고장 주입을 위한 MarlinSimUI의 HTTP/JSON 엔드포인트.
- 고장 주입(fault injection) — 시뮬레이션된 부품을 일부러 고장 내어 펌웨어의 보호 반응을 관찰하는 것.
- 열 폭주 방지(thermal runaway protection) — 온도가 정상 히터답게 움직이지 않으면 히터를 끄는 펌웨어의 점검.
다음 이야기
다음 실습 2에서는 명령줄로 부품을 슬라이싱하고, 걸리는 시간을 예측하고, 이 장의 Klipper와 Marlin 시뮬레이터에 G-code를 재생해 예측이 얼마나 맞는지 확인합니다.