목차
- 마블링 같은 출력물... 그냥 두고 볼 수 없었습니다
- Klipper 펌웨어란 무엇인가요? — 쉽게 말해서
- 준비물 및 환경 구성
- 하드웨어 요구사항
- 소프트웨어 스택
- Klipper 설치 단계별 가이드
- 1단계: 라즈베리 파이 OS 설치
- 2단계: SSH 접속 및 초기 업데이트
- 3단계: KIAUH로 Klipper, Moonraker, Mainsail 설치
- 4단계: 프린터 보드용 Klipper MCU 펌웨어 컴파일 및 플래시
- 5단계: printer.cfg 기본 설정
- Klipper 고급 설정 — 출력 품질 극대화
- Pressure Advance (압력 선행 보정)
- Input Shaping (입력 성형) — 링잉 제거의 핵심
- Bed Mesh Leveling (베드 메쉬 레벨링)
- Macro(매크로) 활용 — 반복 작업 자동화
- ⚠️ 트러블슈팅 — 제가 겪은 삽질들
- 문제 1: MCU 연결이 안 됨 (Unable to connect)
- 문제 2: Klipper 서비스 시작 후 에러 로그
- 문제 3: 베드 레벨링 프로브 동작 안 함
- 문제 4: 압출량(Extruder) 캘리브레이션
- ✅ 결과 확인 — 이렇게 달라졌습니다
- 자주 묻는 질문 (FAQ)
- Q. Klipper가 모든 프린터 보드와 호환되나요?
- Q. 라즈베리 파이 없이 Klipper를 쓸 수 있나요?
- Q. Klipper 설치 후 기존 Marlin으로 되돌릴 수 있나요?
- Q. Input Shaping에 가속도계가 반드시 필요한가요?
- 마무리 — 그래서 Klipper, 써야 할까요?
마블링 같은 출력물... 그냥 두고 볼 수 없었습니다
3D 프린터를 처음 샀을 때 기억 나시나요? 저는 당시 Marlin 펌웨어로 세팅하고 그냥 쓰고 있었는데, 출력물 표면에 물결 무늬(ringing 또는 ghosting이라고 부르는 현상)가 계속 생기는 거예요. 파라미터 이것저것 건드려봤는데 영 개선이 안 되더라고요. 그러다 동료 엔지니어한테서 처음 Klipper 펌웨어 얘기를 들었습니다. "그거 쓰면 진짜 달라져" 하는 말에 반신반의하면서 설치해봤는데... 솔직히 그 이후로 Marlin으로 돌아갈 생각이 전혀 없어요.
이 글에서는 Klipper 설치부터 고급 설정까지, 제가 직접 삽질하면서 쌓은 경험을 최대한 실용적으로 풀어드리려 합니다. 3D프린터 펌웨어를 처음 바꿔보시는 분도, 이미 Klipper를 쓰고 있지만 최적화가 잘 안 되는 분도 도움이 되셨으면 좋겠네요.
▲ Klipper의 핵심 구조 — 라즈베리 파이(호스트)와 마이크로컨트롤러(MCU)가 역할을 나눠서 처리하는 방식입니다.
Klipper 펌웨어란 무엇인가요? — 쉽게 말해서
Klipper는 3D 프린터의 제어 로직을 마이크로컨트롤러(MCU) 단독으로 처리하지 않고, 라즈베리 파이(Raspberry Pi) 같은 싱글보드 컴퓨터와 역할을 분리해서 처리하는 오픈소스 3D프린터 펌웨어입니다.
쉽게 말해서, 기존 Marlin 같은 펌웨어는 프린터 보드(예: SKR, RAMPS) 안에서 모든 계산을 혼자 다 처리했어요. 근데 그 보드들 성능이 그렇게 좋진 않잖아요. Klipper는 복잡한 수학 계산(G-code 파싱, 가감속 계산 등)을 라즈베리 파이에서 처리하고, 보드는 그냥 "이 모터를 이 타이밍에 이만큼 돌려"라는 저수준 명령만 받아서 실행하는 구조거든요.
| 항목 | Marlin 펌웨어 | Klipper 펌웨어 |
|---|---|---|
| 연산 위치 | 프린터 보드(MCU) 단독 | 라즈베리 파이 + MCU 분산 |
| 설정 변경 | 펌웨어 재컴파일 필요 | 텍스트 파일 수정 후 재시작 |
| 입력 성형(Input Shaping) | 제한적 | 가속도계 연동 자동 보정 가능 |
| 압력 선행(Pressure Advance) | Linear Advance (설정 복잡) | Pressure Advance (직관적) |
| 인터페이스 | LCD 또는 별도 호스트 | Mainsail/Fluidd 웹 UI |
| 다중 MCU 지원 | 어려움 | 기본 지원 |
이 구조 덕분에 설정을 바꿀 때마다 펌웨어를 새로 컴파일해서 플래시할 필요가 없어요. printer.cfg 파일만 수정하고 Klipper를 재시작하면 끝입니다. 처음에 이게 얼마나 편한지 실감 못 했는데, 써보고 나서 "아 이래서 다들 Klipper 쓰는구나" 했습니다.
준비물 및 환경 구성
Klipper 설치 전에 필요한 것들을 정리해볼게요. 제가 쓰는 환경 기준으로 설명하겠지만, 대부분의 환경에 적용 가능합니다.
하드웨어 요구사항
- 싱글보드 컴퓨터: 라즈베리 파이 3B+ 이상 권장 (저는 Pi 4 2GB 사용)
- 프린터 보드: SKR Mini E3, BTT Octopus, Creality 보드 등 대부분 지원
- MicroSD 카드: 라즈베리 파이용 8GB 이상
- USB 케이블: 라즈베리 파이 ↔ 프린터 보드 연결용 (데이터 전송 지원)
소프트웨어 스택
- Klipper: 실제 펌웨어 코어
- Moonraker: Klipper와 웹 UI를 연결하는 API 서버
- Mainsail 또는 Fluidd: 웹 기반 인터페이스 (저는 Mainsail 사용)
- KIAUH(Klipper Installation And Update Helper): 설치 자동화 스크립트
Klipper 설치 단계별 가이드
자, 이제 본격적으로 Klipper 설치 과정입니다. 처음에는 좀 복잡해 보이는데, 한 번만 하고 나면 별거 아니에요. 차근차근 따라오세요.
1단계: 라즈베리 파이 OS 설치
라즈베리 파이 이미저(Raspberry Pi Imager)로 Raspberry Pi OS Lite (64-bit)를 설치합니다. GUI 없는 Lite 버전으로 충분하고, 오히려 더 가볍게 돌아가요.
이미저에서 고급 설정으로 SSH 활성화와 Wi-Fi 설정까지 미리 해두면 나중에 편합니다. 저는 여기서 SSH 설정 안 해두고 나중에 모니터 연결해서 했던 기억이... 🤦
2단계: SSH 접속 및 초기 업데이트
# 라즈베리 파이에 SSH로 접속
ssh pi@[라즈베리파이_IP주소]
# 패키지 업데이트
sudo apt update && sudo apt upgrade -y3단계: KIAUH로 Klipper, Moonraker, Mainsail 설치
# KIAUH 다운로드
cd ~
git clone https://github.com/dw-0/kiauh.git
# KIAUH 실행
./kiauh/kiauh.shKIAUH 메뉴가 뜨면 순서대로 설치합니다:
- 1번 메뉴 (Install) 선택
- Klipper 설치
- Moonraker 설치
- Mainsail 또는 Fluidd 설치 (둘 중 하나)
설치 중에 Python 가상환경 세팅이나 의존성 설치가 자동으로 이루어져요. 예전에는 이걸 수동으로 다 해야 했는데, KIAUH 덕분에 진짜 편해졌더라고요.
4단계: 프린터 보드용 Klipper MCU 펌웨어 컴파일 및 플래시
이 단계가 핵심입니다. 프린터 보드에 올릴 Klipper MCU 펌웨어를 라즈베리 파이에서 컴파일해야 해요.
# Klipper 디렉토리로 이동
cd ~/klipper
# 메뉴 기반 설정 도구 실행
make menuconfig여기서 본인 보드에 맞는 설정을 해줘야 합니다. 예를 들어 BTT SKR Mini E3 V3 기준으로는:
- Micro-controller Architecture: STMicroelectronics STM32
- Processor model: STM32G0B1
- Bootloader offset: 8KiB bootloader
- Communication interface: USB (on PA11/PA12)
⚠️ 주의: 보드마다 설정이 달라요. Klipper 공식 문서나 보드 제조사 GitHub에서 본인 보드에 맞는 설정을 반드시 확인하세요. 잘못된 설정으로 플래시하면 보드가 벽돌이 될 수 있거든요. 저도 한 번 당했는데, 다행히 DFU 모드로 복구했어요.
# 설정 완료 후 컴파일
make clean
make -j4
# 컴파일 결과물 위치: ~/klipper/out/klipper.bin컴파일된 klipper.bin을 SD카드에 복사해서 보드에 플래시하거나, USB DFU 방식으로 직접 플래시합니다. 방법은 보드마다 다르니 반드시 확인이 필요해요.
▲ Mainsail 웹 인터페이스에서 printer.cfg를 직접 편집하고 저장하면 바로 적용됩니다 — 펌웨어 재플래시 없이요.
5단계: printer.cfg 기본 설정
Klipper의 핵심 설정 파일인 printer.cfg를 작성합니다. 이게 Marlin에서 Configuration.h 역할을 한다고 보시면 돼요. 근데 훨씬 읽기 쉽고 수정하기 편합니다.
# printer.cfg 기본 예시 (Cartesian 방식 프린터)
[mcu]
# 보드가 연결된 시리얼 포트 확인: ls /dev/serial/by-id/
serial: /dev/serial/by-id/usb-Klipper_stm32g0b1xx_XXXXXXXXXXXXXXXX-if00
[printer]
kinematics: cartesian
max_velocity: 300
max_accel: 3000
max_z_velocity: 5
max_z_accel: 100
[stepper_x]
step_pin: PB13
dir_pin: !PB12
enable_pin: !PB14
microsteps: 16
rotation_distance: 40
endstop_pin: ^PC0
position_endstop: 0
position_max: 235
homing_speed: 50
[stepper_y]
step_pin: PB10
dir_pin: !PB2
enable_pin: !PB11
microsteps: 16
rotation_distance: 40
endstop_pin: ^PC1
position_endstop: 0
position_max: 235
homing_speed: 50
[stepper_z]
step_pin: PB0
dir_pin: PC5
enable_pin: !PB1
microsteps: 16
rotation_distance: 8
endstop_pin: probe:z_virtual_endstop
position_min: -5
position_max: 250
[extruder]
step_pin: PB3
dir_pin: !PB4
enable_pin: !PD1
microsteps: 16
rotation_distance: 33.500
nozzle_diameter: 0.400
filament_diameter: 1.750
heater_pin: PC8
sensor_type: EPCOS 100K B57560G104F
sensor_pin: PA0
min_temp: 0
max_temp: 250
[heater_bed]
heater_pin: PC9
sensor_type: ATC Semitec 104GT-2
sensor_pin: PC4
min_temp: 0
max_temp: 130처음에는 이게 양이 많아 보이는데, 사실 각 섹션이 뭘 의미하는지 한 번만 파악하면 Marlin보다 오히려 직관적이에요.
Klipper 고급 설정 — 출력 품질 극대화
자, 이제 진짜 Klipper의 진가를 발휘하는 고급 기능들입니다. 이게 제가 Klipper로 넘어온 가장 큰 이유예요.
Pressure Advance (압력 선행 보정)
Pressure Advance는 익스트루더가 필라멘트를 밀 때 노즐 내부에 생기는 압력 지연을 보정하는 기능입니다. 쉽게 말해, 코너 부분에서 필라멘트가 뭉치거나 늘어지는 현상을 잡아주는 거예요.
[extruder]
# 위 extruder 섹션에 추가
pressure_advance: 0.05
pressure_advance_smooth_time: 0.040정확한 값은 캘리브레이션 타워를 출력해서 찾아야 해요. Klipper 공식 문서에 캘리브레이션 방법이 잘 나와 있습니다. 저는 이거 세팅하고 나서 코너 품질이 확실히 달라졌더라고요. 특히 벤치마크 모델 출력할 때 차이가 눈에 띄었습니다.
Input Shaping (입력 성형) — 링잉 제거의 핵심
이게 Klipper의 킬러 기능이라고 생각합니다. Input Shaping(입력 성형)은 프린터 프레임이 진동할 때 생기는 링잉(ringing, 고스팅) 현상을 소프트웨어적으로 보정하는 기술이에요.
가속도계(accelerometer)를 연결하면 자동으로 프린터의 공진 주파수를 측정해서 최적의 보정 필터를 적용해줍니다. 저는 ADXL345 모듈을 라즈베리 파이 SPI 핀에 연결해서 사용했어요.
# ADXL345 가속도계 설정
[adxl345]
cs_pin: rpi:None
spi_bus: spidev0.0
[resonance_tester]
accel_chip: adxl345
probe_points:
117.5, 117.5, 20# SSH에서 공진 주파수 측정 실행
# Mainsail 콘솔 또는 SSH에서:
SHAPER_CALIBRATE AXIS=X
SHAPER_CALIBRATE AXIS=Y측정 결과를 바탕으로 Klipper가 자동으로 추천 필터를 알려줘요. 그걸 printer.cfg에 적용하면 됩니다:
[input_shaper]
shaper_freq_x: 45.8
shaper_freq_y: 38.2
shaper_type: mzv💡 팁: 가속도계가 없어도 수동으로 캘리브레이션 타워를 출력해서 주파수를 추정할 수 있어요. 다만 ADXL345 같은 저렴한 모듈을 하나 구해두면 훨씬 정확하고 빠르게 캘리브레이션할 수 있습니다.
Bed Mesh Leveling (베드 메쉬 레벨링)
베드가 완벽하게 평평한 경우는 거의 없죠. Bed Mesh는 베드 여러 포인트를 측정해서 높이 편차를 보정 맵으로 만들어 출력 중에 실시간으로 Z축을 조정하는 기능입니다.
[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 10, 10
mesh_max: 225, 225
probe_count: 5, 5
algorithm: bicubicMacro(매크로) 활용 — 반복 작업 자동화
Klipper의 매크로 기능도 정말 편리해요. 자주 쓰는 작업을 버튼 하나로 실행할 수 있게 만들 수 있거든요.
# 출력 시작 매크로 예시
[gcode_macro START_PRINT]
gcode:
{% set BED_TEMP = params.BED_TEMP|default(60)|float %}
{% set EXTRUDER_TEMP = params.EXTRUDER_TEMP|default(190)|float %}
M140 S{BED_TEMP}
G28
BED_MESH_CALIBRATE
M109 S{EXTRUDER_TEMP}
M190 S{BED_TEMP}
G92 E0
G1 X5 Y20 Z0.3 F5000
G1 X5 Y200 E15 F1500
G92 E0
[gcode_macro END_PRINT]
gcode:
G91
G1 E-5 F3000
G1 Z10 F3000
G90
G1 X0 Y220 F5000
M104 S0
M140 S0
M84슬라이서(Slicer)에서 시작/종료 G-code를 START_PRINT BED_TEMP={material_bed_temperature} EXTRUDER_TEMP={material_print_temperature}처럼 설정하면, 슬라이서에서 설정한 온도가 자동으로 매크로에 전달돼요. 이거 처음 알았을 때 진짜 편하다 싶었습니다.
▲ Input Shaping 적용 전후 비교 — 공진 주파수 측정 그래프와 실제 출력물의 링잉(ghosting) 현상 개선 결과
⚠️ 트러블슈팅 — 제가 겪은 삽질들
설치하면서 자주 만나는 문제들을 정리해봤어요. 저도 다 겪어봤던 것들이라 공감하실 분들 많을 거예요.
문제 1: MCU 연결이 안 됨 (Unable to connect)
가장 흔한 문제입니다. printer.cfg의 시리얼 포트가 맞는지 확인하세요.
# 연결된 USB 장치 시리얼 ID 확인
ls /dev/serial/by-id/
# 출력 예시:
# usb-Klipper_stm32g0b1xx_XXXXXXXXXXXXXXXX-if00이 경로를 그대로 printer.cfg의 [mcu] 섹션 serial:에 넣으면 됩니다. USB 케이블 불량인 경우도 꽤 있어요. 데이터 전송이 되는 케이블인지 확인해보세요.
문제 2: Klipper 서비스 시작 후 에러 로그
# Klipper 로그 실시간 확인
tail -f ~/printer_data/logs/klippy.log
# 서비스 상태 확인
sudo systemctl status klipper대부분의 에러는 printer.cfg 설정 오류거든요. 로그를 보면 어느 섹션, 어느 파라미터에서 문제가 났는지 꽤 친절하게 알려줍니다.
문제 3: 베드 레벨링 프로브 동작 안 함
BLTouch나 CR Touch 같은 프로브를 쓰는 경우, 핀 설정이 까다로울 수 있어요. 특히 probe_with_touch_mode 옵션을 켜야 하는 경우도 있거든요. 저는 처음에 이거 몰라서 한참 헤맸습니다.
[bltouch]
sensor_pin: ^PC14
control_pin: PA1
pin_up_touch_mode_reports_triggered: False
probe_with_touch_mode: True
x_offset: -44
y_offset: -10
z_offset: 2.350문제 4: 압출량(Extruder) 캘리브레이션
rotation_distance 값이 맞지 않으면 압출량이 부정확해집니다. 마크 테스트(Mark Test)로 캘리브레이션해야 해요.
# 100mm 압출 명령 (Mainsail 콘솔에서)
G91
G1 E100 F100
# 실제 압출된 길이를 측정하고 아래 공식으로 계산
# 새 rotation_distance = 기존값 × (요청량 / 실제압출량)
# 예: 33.5 × (100 / 98.5) = 34.01✅ 결과 확인 — 이렇게 달라졌습니다
Klipper 설정을 완료하고 나서 체감한 변화를 솔직하게 공유할게요.
- 🎉 링잉(Ringing) 현상: Input Shaping 적용 후 거의 사라졌습니다. 코너 부분이 훨씬 깔끔해졌어요.
- 🎉 코너 품질: Pressure Advance 세팅 후 코너 뭉침/늘어짐이 확실히 개선됐어요.
- 🎉 출력 속도: Input Shaping 덕분에 고속 출력에서도 품질 저하가 줄어들었습니다. 가속도를 더 높게 설정할 수 있게 됐어요.
- 🎉 운용 편의성: 설정 변경이 너무 편해요. 파라미터 하나 바꾸는 데 펌웨어 재컴파일이 필요 없으니까요.
- 🎉 웹 인터페이스: Mainsail에서 실시간 모니터링, 파일 관리, 매크로 실행이 다 돼서 편합니다.
물론 초기 세팅 난이도가 Marlin보다 높은 건 사실이에요. 라즈베리 파이 세팅, 리눅스 기본 조작, 각 보드별 펌웨어 컴파일 설정 등 진입 장벽이 있습니다. 근데 한 번만 넘어서면, 그 이후는 오히려 훨씬 편하거든요.
▲ Mainsail 대시보드 — 온도 그래프, 출력 진행률, 매크로 버튼 등을 웹 브라우저에서 실시간으로 모니터링할 수 있습니다.
자주 묻는 질문 (FAQ)
Q. Klipper가 모든 프린터 보드와 호환되나요?
대부분의 주요 보드를 지원합니다. Klipper 공식 문서의 Config Reference 페이지에서 지원 MCU 목록을 확인할 수 있어요. STM32, AVR, RP2040 계열은 대부분 지원됩니다.
Q. 라즈베리 파이 없이 Klipper를 쓸 수 있나요?
네, 가능합니다. 라즈베리 파이 대신 오렌지 파이(Orange Pi), 일반 리눅스 PC도 호스트로 사용할 수 있어요.
Q. Klipper 설치 후 기존 Marlin으로 되돌릴 수 있나요?
네, 가능합니다. 프린터 보드에 Marlin 펌웨어를 다시 플래시하면 됩니다. 라즈베리 파이 쪽 Klipper 설정은 그냥 두거나 삭제하면 돼요.
Q. Input Shaping에 가속도계가 반드시 필요한가요?
필수는 아닙니다. 가속도계 없이 캘리브레이션 프린트로 수동으로 주파수를 추정할 수 있어요. 다만 ADXL345 같은 저렴한 모듈을 하나 구해두면 훨씬 정확하고 빠르게 캘리브레이션할 수 있습니다.
마무리 — 그래서 Klipper, 써야 할까요?
13년간 서버와 인프라를 다뤄온 입장에서, Klipper는 3D 프린터를 "설정 파일로 관리하는 시스템"으로 바꿔준 펌웨어라고 생각합니다. 코드로 인프라를 관리하는 IaC(Infrastructure as Code) 철학이랑 비슷한 느낌이랄까요.
처음 설치가 좀 복잡한 건 사실입니다. 근데 그 이후로는 정말 편해요. 설정 하나 바꿀 때마다 Arduino IDE 켜고 컴파일하고 플래시하는 과정이 없어지는 것만으로도 충분히 투자할 가치가 있다고 생각합니다.
처음엔 그냥 출력 품질 개선 목적으로 시작했는데, 이제는 홈랩 서버에서 Moonraker API로 자동화 스크립트도 돌리고, 출력 완료 시 알림도 보내고... 점점 재미있어지고 있어요. 혹시 이런 자동화 연동에 관심 있으신 분은 다음 글에서 Moonraker API 활용 자동화 방법도 다룰 예정이니 기대해주세요.
질문이나 본인만의 Klipper 세팅 팁이 있으시면 댓글로 공유해주세요. 저도 아직 배우는 중이라, 다른 분들 경험도 궁금하거든요. 😊
'Tech & Hobby > 3D Printer' 카테고리의 다른 글
| [3D Printer] Klipper 펌웨어 설치 및 최적화: 고속 3D 프린팅 완벽 가이드 (1) | 2026.05.01 |
|---|---|
| [3D Printer] 3D 프린터 베드 레벨링 완벽 가이드: 수동·자동 센서 활용법 (1) | 2026.05.01 |
| [3D 프린팅] Cura 5.7 슬라이서 설정: 초보자를 위한 완벽 출력 가이드 (0) | 2026.04.24 |
| [3D Printer] 3D 프린터 출력 실패 트러블슈팅: 층 분리·워핑·압출 불량 완벽 해결 가이드 (0) | 2026.04.21 |
| [3D 프린팅] OctoPrint 완벽 가이드: 라즈베리 파이로 원격 제어하기 (2) | 2026.04.19 |
| [3D Printer] 3D 프린터 출력 실패 원인 분석 및 해결: 흔한 문제와 트러블슈팅 (2) | 2026.04.18 |
