Klipper 오류: MCU ‘Unable to Connect’ 문제 진단 및 해결 가이드

Klipper 오류 중에서 제일 오래 붙잡히는 유형이 대개 MCU 연결 실패입니다. 화면에는 Unable to Connect 한 줄만 뜨는데, 실제 원인은 한 가지가 아니거든요. 저는 이 문제를 볼 때 장치가 안 보이는 문제, 장치는 보이는데 설정이 틀린 문제, 설정까지 맞는데 프로토콜 단계에서 붙지 않는 문제를 먼저 분리해서 봅니다.

이번 글은 그 세 층을 나눠서 정리합니다. 그냥 재부팅만 반복하는 방식보다, 장치 열거(enumeration) – 경로 고정 – 로그 확인 – 포트 점유/권한 – 펌웨어 정합성 순서로 좁혀가면 훨씬 덜 헤매더라고요. 실제로 제가 먼저 보는 명령어와 로그 포인트, 그리고 이럴 땐 A, 저럴 땐 B라고 판단하는 기준까지 같이 정리해보겠습니다.

Klipper 호스트와 프린터 보드가 어떤 경로로 연결되는지 한눈에 보여주는 개요 이미지입니다.

1. Klipper 오류, MCU 연결이 어디서 끊기는지부터 나눠 봐야 합니다

Klipper 연결 실패는 보통 세 단계로 나눠 보면 정리가 빨라집니다.

• 1단계: 호스트가 보드를 발견했는가 – /dev/serial/by-id/ 또는 /dev/serial/by-path/에 장치가 생기는지
• 2단계: Klipper가 올바른 장치를 열고 있는가 – printer.cfg의 [mcu] 아래 serial: 값이 실제 장치와 일치하는지
• 3단계: 장치를 열었는데도 통신이 실패하는가 – 잘못된 펌웨어 대상, 플래시 실패, 포트 점유, 호스트/MCU 소프트웨어 불일치 같은 문제

이 분류가 중요한 이유가 있습니다. 장치 자체가 안 보이는데 printer.cfg만 계속 수정하면 시간이 버려지고, 반대로 장치는 보이는데 케이블만 계속 바꾸고 있으면 해결이 안 되죠. 증상은 비슷해도 원인 계층이 다르기 때문입니다.

실제로 Unable to Connect가 뜨는 흔한 원인은 대체로 아래 범주에 들어갑니다.

• 장치 경로가 틀렸습니다. /dev/ttyUSB0, /dev/ttyACM0 같은 가변 이름을 고정값처럼 쓴 경우가 대표적입니다.
• printer.cfg의 serial: 값이 현재 보드와 다릅니다. 플래시 후 USB 식별명이 바뀌었는데 예전 경로를 그대로 쓴 경우가 많습니다.
• 펌웨어가 보드와 맞지 않거나 플래시가 제대로 완료되지 않았습니다.
• Klipper 호스트와 MCU 펌웨어가 서로 맞지 않습니다. 호스트만 업데이트하고 MCU는 예전 빌드인 상황이 여기 걸립니다.
• 포트 권한 또는 포트 점유 문제가 있습니다. Klipper 외 프로세스가 장치를 잡고 있거나, 서비스 계정이 장치에 접근하지 못하는 경우죠.

핵심만 먼저 말씀드리면, 장치가 보이는지 확인하기 전에는 설정을 고치지 말고, 설정이 맞는지 확인하기 전에는 재플래시부터 가지 않는 것이 가장 덜 돌아가는 루트입니다.

2. Klipper 트러블슈팅은 증상별로 첫 확인 지점이 다릅니다

제가 현장에서 자주 쓰는 판단표는 아래 형태입니다. 중요한 건 원인을 외우는 게 아니라, 다음 한 번의 확인으로 어떤 가설을 버릴 수 있느냐입니다.

실전에서는 여기서 한 단계 더 들어가면 좋습니다. 장치가 안 보이면 물리/USB 계층, 장치는 보이는데 경로가 안 맞으면 설정 계층, 경로까지 맞는데 안 붙으면 펌웨어/점유/권한 계층으로 끊어서 보시면 됩니다. 이렇게 나누면 범위를 절반씩 줄여갈 수 있어서 진짜 편합니다.

3. 실전 진단 1단계: MCU 장치가 실제로 열거되는지 확인

여기서는 느낌으로 보면 안 됩니다. 호스트 OS가 보드를 장치로 만들었는지를 먼저 확인해야 합니다. Klipper 공식 문서도 /dev/serial/by-id/* 사용을 권장하고, 저도 이 경로를 기본으로 봅니다. 이유는 단순합니다. ttyUSB0, ttyACM0는 순서가 바뀌면 이름이 달라지지만, by-id는 장치 식별자를 기준으로 잡히기 때문입니다.

1. SSH로 Klipper 호스트에 접속합니다.
2. 장치가 고유 ID로 보이는지 확인합니다.
3. 아무것도 안 보이면 커널이 장치를 감지했는지까지 확인합니다.

ls /dev/serial/by-id/*
ls /dev/serial/by-path/*
dmesg | tail -n 50
# dmesg 접근이 막히면
sudo dmesg | tail -n 50

여기서 판단 기준은 꽤 명확합니다.

• by-id가 보이면: USB 열거는 성공한 겁니다. 이제 설정과 포트 점유 쪽으로 넘어가면 됩니다.
• by-id는 없고 by-path만 보이면: CH340 계열처럼 고유 ID가 애매한 경우를 의심해볼 수 있습니다. 이런 환경에선 by-path를 차선책으로 씁니다.
• 둘 다 안 보이면: 이 시점에는 printer.cfg를 만질 이유가 거의 없습니다. 케이블, 전원, USB 포트, 보드 부트 상태를 먼저 봐야 합니다.

제가 특히 강조드리고 싶은 포인트가 하나 있습니다. 플래시 전의 장치명과 플래시 후의 장치명이 같을 거라고 가정하지 마세요. 공식 설치 문서도 플래시 후 장치명이 바뀔 수 있으니 다시 확인하라고 안내합니다. 이거 한 번 놓치면 펌웨어는 정상인데 경로만 예전 값을 보고 있어서, 재플래시 실패로 오해하기 쉽더라고요.

보드가 여러 개인 환경이라면 더 엄격하게 보셔야 합니다. 메인보드와 USB 가속도계, 별도 MCU가 같이 꽂혀 있으면 장치 목록이 여러 줄 나옵니다. 이럴 때는 케이블을 하나씩 빼고 다시 같은 명령을 실행해서 어떤 항목이 사라지는지 확인하는 방식이 제일 정확합니다.

SSH 터미널에서 MCU 장치 경로를 식별하는 실제 작업 흐름을 보여주는 이미지입니다.

4. 실전 진단 2단계: printer.cfg의 serial 설정을 고정 경로로 맞추기

장치가 보이기 시작했다면 이제는 Klipper가 그 장치를 정확히 열 수 있는지를 봐야 합니다. 대부분은 printer.cfg의 [mcu] 아래 serial: 한 줄에서 갈립니다. 이 값이 실제 장치와 한 글자라도 다르면 연결은 실패합니다.

[mcu]
serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0

여기서 제 권장 방식은 단순합니다. 직접 타이핑하지 말고, 방금 확인한 경로를 그대로 복사해서 붙여넣는 것입니다. 문자열이 은근히 비슷해서 사람 손으로 넣다가 오타 나는 경우가 꽤 많습니다.

그리고 보드 특성에 따라 선택 기준이 조금 갈립니다.

설정을 수정한 뒤에는 UI만 보지 말고 콘솔과 로그를 같이 보시는 게 좋습니다. 연결 문제와 설정 문법 문제는 겉보기엔 비슷하게 보일 때가 있는데, 실제론 전혀 다른 장애거든요.

tail -n 100 ~/printer_data/logs/klippy.log

로그를 볼 때 무엇을 읽어야 하는가도 중요합니다. 저는 아래처럼 해석합니다.

• 장치 파일을 못 찾는 메시지: 경로 문제일 가능성이 큽니다.
• 권한 거부 메시지: 포트 권한 또는 서비스 계정 문제입니다.
• 장치는 열었는데 MCU 식별/초기화 단계에서 실패: 펌웨어 불일치, 잘못된 빌드 타깃, 플래시 문제 쪽으로 넘어갑니다.
• 설정 문법 오류: 이건 연결 문제가 아니라 printer.cfg 파싱 단계에서 막힌 겁니다.

여기서 한 가지 더. RESTART가 만능은 아닙니다. 설정을 다시 읽는 데는 유효하지만, 호스트 소프트웨어를 업데이트했거나 MCU 펌웨어를 바꾼 뒤라면 서비스 재시작이나 재플래시가 따로 필요할 수 있습니다. 이 구분을 해두면 같은 작업을 몇 번씩 반복하는 일을 줄일 수 있습니다.

5. 실전 진단 3단계: 포트 점유, 권한, 펌웨어 정합성까지 확인

장치도 보이고 serial:도 맞는데 여전히 Unable to Connect가 뜬다면, 그때부터는 장치를 여는 데 실패하는지, 열고도 통신이 안 되는지를 더 깊게 봐야 합니다. 이 구간에서 흔한 함정이 세 가지 있습니다. 포트 점유, 권한, 호스트/MCU 빌드 불일치입니다.

먼저 포트 점유부터 보는 이유가 있습니다. 펌웨어나 케이블보다 더 흔한데, UI만 봐서는 티가 잘 안 납니다. 특히 예전에 OctoPrint, 시리얼 모니터, 다른 자동화 스크립트를 같이 쓴 환경이면 이 가능성을 먼저 의심하셔야 합니다.

sudo service klipper stop
lsof /dev/serial/by-id/*
fuser -v /dev/ttyUSB0 /dev/ttyACM0 2>/dev/null
sudo service klipper start

위 명령에서 포인트는 이겁니다.

• lsof나 fuser 결과가 나오면: 누군가 그 포트를 잡고 있는 겁니다. Klipper만의 문제로 보면 안 됩니다.
• Klipper를 멈춘 뒤 플래시가 성공한다면: 플래시 실패의 본질은 포트 점유였을 가능성이 큽니다.

그다음은 권한입니다. 여기서는 무조건 tty 그룹부터 추가하는 식으로 가지 않는 게 좋습니다. 실제 장치 파일의 그룹은 배포판과 설정에 따라 dialout, uucp, tty처럼 다를 수 있거든요. 그래서 먼저 어떤 사용자로 서비스가 돌고 있는지, 장치 파일의 소유 그룹이 무엇인지를 확인해야 합니다.

ps -ef | grep -E 'klippy|klipper'
ls -l /dev/serial/by-id/*
id
groups
# 예시: 실제 그룹명과 사용자명 확인 후
sudo usermod -a -G <device_group> <service_user>

마지막 줄의 <device_group>과 <service_user>는 예시입니다. 실제 환경에 맞게 바꿔야 하고, 그룹 추가 뒤에는 보통 새 로그인 세션이나 서비스 재시작이 필요합니다. 이 부분을 건너뛰면 적용이 안 됐는데 명령만 반복하는 상황이 생기기 쉽습니다.

마지막으로 남는 게 펌웨어 쪽입니다. 특히 아래 상황이라면 재빌드/재플래시 우선순위가 올라갑니다.

• 보드를 새로 교체했습니다.
• make menuconfig에서 MCU 아키텍처나 통신 인터페이스를 바꿨습니다.
• 호스트 소프트웨어는 업데이트했는데 MCU는 오래된 빌드입니다.
• 플래시 직후부터 장치는 보이지만 초기화가 안 됩니다.

menuconfig, build, flash, service restart 순서가 어떻게 이어지는지 정리한 다이어그램입니다.

6. 재빌드와 재플래시가 필요한 경우, 어디서 실수하는지

장치 경로와 설정이 모두 맞는데도 붙지 않으면, 그다음은 펌웨어 자체를 의심해야 합니다. 다만 여기서도 무턱대고 다시 굽는 것보다 왜 재플래시가 필요한 상황인지를 먼저 판단하는 편이 낫습니다.

제가 보통 재플래시로 넘어가는 조건은 이렇습니다.

• 장치는 열리는데 MCU 초기화가 안 된다
• 방금 보드 정의를 바꿨다
• 호스트 업데이트 후 MCU 쪽 재빌드 경고 또는 비정상 동작이 있다
• 플래시 과정 자체가 의심스럽다 – 예를 들어 잘못된 대상 보드로 빌드했거나, 부트 모드 진입이 안 된 경우

일반적인 빌드 흐름은 아래와 같습니다.

cd ~/klipper
make menuconfig
make clean
make

make clean을 중간에 넣는 이유는 이전 빌드 산출물이 섞여 판단을 흐리는 일을 줄이기 위해서입니다. 특히 보드 종류나 옵션을 바꾼 뒤에는 이 단계가 더 안전합니다.

시리얼 장치를 통한 일반적인 플래시 흐름은 다음 패턴을 많이 씁니다.

sudo service klipper stop
make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0
sudo service klipper start

여기서 실제로 많이 틀리는 지점은 네 군데입니다.

• FLASH_DEVICE에 현재 장치가 아닌 예전 경로를 넣는 경우
• Klipper 서비스를 안 멈춘 상태에서 플래시하는 경우
• 보드가 make flash 대신 SD 카드 또는 제조사 전용 방식이 필요한 경우
• 플래시 후 장치명이 바뀌었는데 printer.cfg를 갱신하지 않은 경우

특히 STM32 계열이나 일부 클론 보드는 첫 Klipper 플래시를 SD 카드로 요구하는 경우가 있습니다. 공식 설치 문서도 이 가능성을 따로 언급합니다. 이때 make flash만 반복하면 원인을 잘못 짚게 됩니다.

또 SD 카드 방식은 보드마다 파일명 재사용이 안 되는 경우, 또는 플래시 후 firmware.cur처럼 이름이 바뀌는 경우가 있어서, 파일만 넣었다고 바로 성공으로 판단하면 안 됩니다. 이런 부분은 제조사 문서를 같이 보는 게 안전합니다.

7. 제가 자주 봤던 실제 원인 4가지와 근본 원인

겉으로는 다 비슷한 연결 불가지만, 반복해서 나오는 패턴은 어느 정도 정해져 있습니다. 저는 아래 네 가지를 먼저 의심합니다.

7-1. 가변 포트명 사용

가장 흔합니다. /dev/ttyUSB0 또는 /dev/ttyACM0는 짧아서 편해 보이지만, 장기 안정성은 떨어집니다. 근본 원인은 Klipper가 틀린 포트를 보고 있는 게 아니라, 운영체제가 같은 종류의 장치를 다른 번호로 다시 배정하기 때문입니다. 해결은 간단합니다. /dev/serial/by-id/를 사용하세요.

7-2. 플래시 후 장치명이 달라짐

이건 생각보다 자주 놓칩니다. 사용자는 플래시가 끝났다고 생각하지만, 실제로는 플래시 후 USB 식별 문자열이 바뀌어서 예전 경로가 더 이상 유효하지 않은 경우가 많습니다. 이때 재플래시를 반복해도 증상은 그대로입니다. 플래시 직후 다시 ls /dev/serial/by-id/*를 실행해서 현재 경로를 기준으로 설정을 바꿔야 합니다.

7-3. 권한 문제

이때 근본 원인은 Klipper 설정이 아니라 호스트의 장치 접근 정책입니다. 로그에 Permission denied가 보이면, 먼저 어떤 사용자로 서비스가 돌고 있는지 확인하고, 그다음 실제 장치 파일의 그룹에 맞춰 권한을 부여해야 합니다. 배포판마다 그룹명이 다를 수 있다는 점도 꼭 같이 기억해두세요.

7-4. 다른 프로세스가 포트를 점유함

이 문제는 UI에서 잘 안 드러납니다. 사용자는 MCU 연결 실패라고 보지만, 운영체제 입장에서는 이미 다른 프로세스가 장치를 열고 있어서 Klipper가 들어갈 자리가 없는 겁니다. 근본 원인은 장치 충돌이지 펌웨어 불량이 아닙니다. 특히 플래시 단계에서 실패하면 이쪽 가능성이 더 큽니다.

추가로 하나 더 말씀드리면, 케이블 문제는 생각보다 단순하지 않습니다. 전원은 들어오는데 데이터 라인이 불안정한 USB 케이블도 꽤 있습니다. 그래서 보드 전원이 들어온다고 통신까지 정상이라고 보면 안 됩니다. 장치가 아예 안 보이거나, 꽂을 때마다 커널 로그가 들쭉날쭉하다면 케이블 교체 테스트는 충분히 해볼 만합니다.

8. 재현 가능한 시나리오로 보면 훨씬 빨리 잡힙니다

제가 실제로 여러 번 본 흐름을 하나 적어보겠습니다. 초보자뿐 아니라 어느 정도 익숙한 분도 여기서 많이 걸립니다.

1. 보드에 새 Klipper 펌웨어를 올립니다.
2. 웹 UI에서 바로 Unable to Connect가 뜹니다.
3. 사용자는 보통 빌드가 잘못됐나?부터 의심합니다.
4. 그런데 SSH에서 ls /dev/serial/by-id/*를 다시 보면, 기존과 다른 새 경로가 잡혀 있습니다.
5. printer.cfg의 serial:을 새 값으로 바꾸고 재시작하면 바로 붙습니다.

이 시나리오가 주는 교훈은 분명합니다. 연결 불가가 보이면 바로 재플래시로 가지 말고, 플래시 이후 장치명이 바뀌었는지 먼저 확인할 것. 이 한 단계만 지켜도 불필요한 재작업이 꽤 줄어듭니다.

반대로 이런 경우도 있습니다. 장치는 by-id에 보이고, serial:도 맞는데, 플래시만 계속 실패합니다. 이럴 땐 대부분 포트 점유 또는 보드가 요구하는 실제 플래시 방식이 make flash가 아닌 상황입니다. 같은 Klipper 오류처럼 보여도 보는 층위가 달라야 한다는 얘기죠.

9. 검증: 어디까지 확인돼야 정상 복구로 볼 수 있나

한 번 붙었다고 끝내면 안 됩니다. MCU 연결 문제는 간헐 복구가 제일 까다롭거든요. 화면이 살아났더라도 아래 기준까지는 확인해두는 편이 안전합니다.

• Klipper 상태가 ready로 전환되는지
• 재시작 후에도 같은 상태가 유지되는지
• USB 케이블 재연결 뒤에도 같은 경로를 계속 쓰는지
• klippy.log에 같은 연결 오류가 다시 반복되지 않는지

제가 복구 검증에 자주 쓰는 최소 명령은 아래 정도입니다.

sudo service klipper restart
tail -n 50 ~/printer_data/logs/klippy.log

여기서 판단은 이렇게 합니다.

• 한 번은 붙는데 재부팅 후 깨진다: 대개 경로 선택이 불안정합니다. ttyUSB0 같은 가변 이름을 의심하세요.
• 플래시 직후만 안 되다가 경로 수정 후 안정화된다: 포트 식별 문제가 맞을 가능성이 큽니다.
• 여러 번 재시작해도 로그에 포트 열기 실패가 반복된다: 권한, 점유, 장치 인식, 케이블 쪽을 다시 봐야 합니다.
• 장치는 잘 열리는데 MCU 초기화가 계속 실패한다: 보드 대상, 통신 방식, 펌웨어 재빌드 정합성으로 넘어가야 합니다.

저는 여기서 한 번 더 엄격하게 봅니다. 재부팅 1회, 서비스 재시작 1회, 케이블 재연결 1회까지는 통과해야 “고쳤다”고 판단합니다. 그 전에는 그냥 운 좋게 한 번 붙은 상태일 수도 있거든요.

연결 복구 후 상태 화면과 로그를 함께 점검하는 검증 단계를 표현한 이미지입니다.

10. 자주 헷갈리는 포인트 정리

10-1. 로그는 어디서 보나요?

보통 ~/printer_data/logs/klippy.log입니다. 일부 환경에서는 /tmp/klippy.log를 보는 경우도 있지만, 요즘 많이 쓰는 Mainsail/Fluidd 계열 구성에선 전자가 먼저입니다. UI 팝업보다 이 로그가 훨씬 정보가 많습니다.

10-2. 왜 by-id를 그렇게 강조하나요?

ttyUSB0, ttyACM0는 사람이 보기엔 간단하지만 운영체제 입장에서는 고정 이름이 아닙니다. 반면 /dev/serial/by-id/는 장치 식별값 기반이라 훨씬 안정적입니다. 한두 번은 차이를 못 느껴도, 재부팅과 장치 추가가 반복되면 차이가 바로 납니다.

10-3. by-id가 없으면 실패한 건가요?

꼭 그렇진 않습니다. 일부 CH340 계열처럼 by-id가 깔끔하지 않은 보드는 by-path를 써야 할 수 있습니다. 다만 이 경우엔 USB 허브나 포트 위치가 바뀌면 경로도 달라질 수 있으니, 물리 포트 변경에 더 민감하다는 점은 감안하셔야 합니다.

10-4. make flash가 안 되면 Klipper 자체 문제인가요?

아닐 때가 많습니다. 서비스가 포트를 잡고 있거나, 보드가 SD 카드 방식이나 별도 부트로더 절차를 요구할 수 있습니다. 이때는 플래시 도구 실패와 MCU 연결 실패를 같은 문제로 보지 않는 게 중요합니다.

10-5. 재시작 명령만 반복하면 되나요?

설정 반영에는 도움이 되지만, 장치가 아예 안 보이거나 새 펌웨어를 실제로 올려야 하는 상황까지 해결해주진 않습니다. RESTART는 설정 재적용, 서비스 재시작은 호스트 프로세스 재기동, 재플래시는 MCU 코드 교체라는 차이를 구분하셔야 합니다.

장치 경로, 설정, 권한, 재플래시 순서를 빠르게 훑을 수 있는 요약 인포그래픽입니다.

11. 이런 상황이면 이렇게 결정하시면 됩니다

장치가 아예 안 보인다면 설정 파일부터 열지 마세요. 케이블, 전원, USB 포트, 보드 부트 상태, 커널 로그를 먼저 확인하는 편이 맞습니다.

장치는 보이는데 Unable to Connect가 뜬다면 우선순위는 거의 항상 같습니다. printer.cfg의 serial: 값, 그리고 klippy.log입니다. 특히 플래시 직후라면 장치명이 바뀌었는지를 먼저 보세요.

장치도 보이고 경로도 맞는데 계속 안 붙는다면 그때는 포트 점유, 권한, 펌웨어 정합성으로 넘어가면 됩니다. 이 단계에서는 lsof, fuser, 서비스 중지 후 플래시, 보드별 플래시 방식 확인이 효율적입니다.

제가 추천하는 실제 순서는 딱 이겁니다. 1) 장치 열거 확인, 2) 고정 경로 반영, 3) 로그 해석, 4) 포트 점유/권한 정리, 5) 마지막으로 재빌드와 재플래시. 이 순서로 가면 괜히 반나절씩 재설치하는 일을 많이 줄일 수 있습니다.

다음 단계의 Klipper 오류가 MCU shutdown이나 Lost communication with MCU처럼 “붙긴 붙는데 출력 중 끊기는” 유형이라면 접근법이 조금 달라집니다. 이 블로그의 관련 Klipper 트러블슈팅 글도 이어서 보시면 흐름을 잡는 데 도움이 됩니다.