Klipper 푸시 알림: 출력 상태를 휴대폰으로 받아보기

열두 시간짜리 출력을 옆에서 지켜볼 필요는 없어요. 필요한 건 출력이 끝나는 순간, 그리고 더 중요하게는 출력이 멈추는 순간을 아는 것입니다.
Klipper는 이 두 가지를 이미 알려줄 수 있어요. Mainsail과 Fluidd의 뒤에서 동작하는 API 서버인 Moonraker에는 출력 이벤트에 반응해 Apprise로 알림을 보내는 기능이 내장되어 있습니다. 이 기능이 Pocket Alert 웹훅을 가리키게 하면, 완료되거나, 실패하거나, 취소되거나, 일시 정지된 모든 출력이 휴대폰 푸시 알림으로 도착해요. 플러그인도, 라즈베리 파이에 추가로 올릴 서비스도 필요 없고, 설정 블록 하나면 끝납니다.
준비물
- Moonraker가 설치된 Klipper 프린터. 브라우저에서 Mainsail이나 Fluidd를 열 수 있다면 Moonraker가 있는 거예요.
- 무료 Pocket Alert 계정과 iPhone 또는 Android 휴대폰의 앱.
- 약 5분.
1단계. Pocket Alert에서 웹훅 만들기
대시보드에서 웹훅을 열고 새 웹훅을 만드세요:
- 이름 – 프린터 이름, 예를 들어
Voron 2.4. 이 이름이 푸시 제목(Webhook Voron 2.4)이 되므로 프린터가 여러 대라면 어느 프린터가 도움을 필요로 하는지 한눈에 알 수 있어요. - 애플리케이션과 기기 – 알림이 전달될 위치.
- 메시지 – 다음 템플릿을 붙여넣으세요:
%title%
%message%
저장한 뒤 웹훅 URL을 복사하세요. 형태는 https://p4a.me/wh/<your-webhook-id>와 같아요.
이 템플릿을 쓰는 이유: Moonraker는 각 알림을 Apprise에 넘기고, Apprise의 JSON 알림 기능은 아래와 같은 작은 페이로드를 전송합니다:
{
"version": "1.0",
"title": "❌ Print error",
"message": "3DBenchy.gcode Move out of range: 235.000 0.000 0.200 [0.000]",
"attachments": [],
"type": "info",
"level": "high"
}
템플릿의 %key%는 JSON에서 해당 필드 값으로 바뀝니다. 푸시에서는 첫 줄에 제목이, 그 아래에 메시지가 표시돼요. 템플릿 경로에 대한 자세한 내용은 첫 웹훅 URL 만들기에서 확인하세요.
2단계. moonraker.conf에 알림 설정 추가하기
moonraker.conf를 여세요. Mainsail에서는 Machine, Fluidd에서는 Configuration 아래에 있어요. 그리고 파일 끝에 다음 세 섹션을 추가하세요. YOUR_WEBHOOK_ID는 웹훅 URL에 있는 ID로 바꿔 주세요.
[notifier pocketalert_done]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID
events: complete
title: ✅ Print complete
body: {event_args[1].filename}
[notifier pocketalert_fail]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: error, cancelled
title: ❌ Print {event_name}
body: {event_args[1].filename} {event_args[1].message}
[notifier pocketalert_pause]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: paused
title: ⏸ Print paused
body: {event_args[1].filename}: check the printer
각 항목의 역할:
- **
jsons://**는 HTTPS로 동작하는 Apprise의 JSON 알림 기능이에요. 위의 페이로드를 웹훅으로 보냅니다. - **
events**는 섹션을 트리거할 출력 상태를 고릅니다. Moonraker는started,complete,error,cancelled,paused,resumed를 지원해요. - **
?:level=high**는 Apprise가 JSON에"level": "high"를 추가하도록 합니다. Pocket Alert는 이 필드를 읽고 높은 우선순위로 푸시를 보내요. iPhone에서는 시간에 민감한 알림으로 도착해 집중 모드도 뚫고 들어옵니다. "complete" 섹션에는 level이 없으므로 일반 푸시로 도착해요. - **
{event_args[1]}**는 이벤트 이후의 출력 작업 상태예요. Klipper의print_stats객체와 같아서,filename은 G-code 파일이고message는 출력이 실패했을 때 Klipper가 남긴 오류 텍스트예요. - **
{event_name}**은 발생한 이벤트예요. 그래서 하나의 섹션이error와cancelled를 모두 처리하면서도 제목에서 어떤 일이 일어났는지 알려 줍니다.
3단계. Moonraker 재시작 후 테스트하기
Mainsail이나 Fluidd의 전원 메뉴에서 Moonraker를 재시작하거나, SSH로 다음 명령을 실행하세요:
sudo systemctl restart moonraker
테스트로 필라멘트를 쓰기 전에 curl로 웹훅을 먼저 확인하세요. Apprise가 보내는 것과 같은 형태의 JSON을 전송합니다:
curl -X POST https://p4a.me/wh/YOUR_WEBHOOK_ID \
-H 'Content-Type: application/json' \
-d '{"title":"❌ Print error","message":"test.gcode Move out of range","level":"high"}'
휴대폰이 진동하면 Pocket Alert 쪽은 정상이에요. 이제 작은 출력을 시작하고 첫 레이어 뒤에 취소해 보세요. 몇 초 안에 ❌ Print cancelled 알림이 와야 합니다.
휴대폰에 도착하는 알림
밤에 출력이 실패하면 잠금 화면에는 이렇게 보입니다:
Webhook Voron 2.4
❌ Print error
3DBenchy.gcode Move out of range: 235.000 0.000 0.200 [0.000]
휴대폰 잠금을 풀기 전에 어느 프린터인지, 어떤 파일인지, 왜 멈췄는지 알 수 있어요.
내 환경에 맞게 바꾸기
아래 내용은 모두 같은 파일을 조금 수정하는 것입니다.
- 출력 시작은 조용히 기록하기.
events: started와?:level=silent를 넣은 섹션을 추가하세요. 시작 기록은 소리 없이 메시지 기록에 남아요. - 실패하면 바로 깨우기. 실패 섹션의
?:level=high를?:level=critical로 바꾸세요. Android에서는 critical 알림이 방해 금지 모드를 뚫고 들어와요. Critical 전달은 유료 기능이라, 무료 플랜에서는 메시지가 여전히 high 우선순위로 도착합니다. 자세한 내용은 critical 알림을 참고하세요. - 프린터가 여러 대일 때. 프린터마다 웹훅을 하나씩 만들고, 각 웹훅 이름을 장비 이름으로 지어 주세요. 푸시 제목을 보면 어느 프린터가 멈췄는지 알 수 있어요.
- 직접 만든 매크로에서 알림 보내기. Moonraker에는
gcode이벤트도 있어서, Klipper 매크로로 원하는 텍스트를 보낼 수 있어요. 필라멘트 교체나 런아웃 센서에 유용합니다.
moonraker.conf에 추가:
[notifier pocketalert_macro]
url: jsons://p4a.me/wh/YOUR_WEBHOOK_ID?:level=high
events: gcode
title: 🧵 Printer needs you
body: {event_message}
printer.cfg에 추가:
[gcode_macro NOTIFY_FILAMENT_CHANGE]
gcode:
{action_call_remote_method("notify",
name="pocketalert_macro",
message="Filament change needed")}
NOTIFY_FILAMENT_CHANGE 매크로나 필라멘트 센서의 M600에서 runout_gcode를 호출하세요.
알림이 도착하지 않는다면
- 대시보드에서 웹훅 확인하기. 웹훅 기록에는 모든 호출과 원본 페이로드가 남아요. 기록이 없다면 Moonraker가 Pocket Alert에 도달하지 못한 거예요. 오류가 있는 기록이 있다면 그 이유가 적혀 있어요.
moonraker.log읽기. Moonraker는 알림 오류를 설치된 Apprise 버전과 함께 이 파일에 기록해요. 대부분의 설치에서는~/printer_data/logs/moonraker.log에 있습니다.- 푸시에 빈 줄이 보일 때. 템플릿 키는 Apprise 페이로드와 맞아야 해요.
%title%가 아니라%message%과%body%를 써야 합니다.
왜 플러그인이 아닌가요?
Klipper용 텔레그램 봇이나 원격 접속 서비스는 카메라 스냅샷, 타임랩스, 원격 제어처럼 더 많은 기능을 제공해요. 대신 라즈베리 파이에 설치하고 계속 업데이트해야 하는 서비스가 하나 더 생기죠. "끝나면 알려 주고, 실패하면 깨워 줘"가 목표라면 Moonraker가 이미 알림을 보내고 있으니, Pocket Alert는 받기만 하면 됩니다.
프린터가 홈랩 옆에 있다면, 프린터 알림도 서버, 백업, 크론 작업 알림과 같은 앱에 모이고 같은 기록과 같은 우선순위 단계를 따릅니다.
자주 묻는 질문
라즈베리 파이에 무언가 설치해야 하나요?
아니요. 알림 기능은 Moonraker에 포함되어 있고, Apprise는 의존성으로 함께 설치돼요. moonraker.conf를 수정하고 Moonraker를 재시작하기만 하면 됩니다.
Mainsail과 Fluidd에서도 동작하나요?
네. 둘 다 Moonraker의 웹 인터페이스이고, 알림 기능은 Moonraker에 있으므로 설정 방법이 같아요. 둘 중 어디서든 moonraker.conf를 수정할 수 있습니다.
프린터 여러 대의 알림을 받을 수 있나요?
네. 프린터마다 웹훅을 하나씩 만들고 장비 이름으로 지으세요. 웹훅 이름이 푸시 제목이 됩니다.
실패한 출력이 밤에 나를 깨울까요?
level=high를 쓰면 iPhone에서 시간에 민감한 알림으로 도착해 집중 모드도 뚫고 들어와요. Android에서 방해 금지 모드를 뚫으려면 유료 플랜에서 level=critical을 사용하세요.
무료인가요?
네. 웹훅은 무료 플랜에서도 쓸 수 있어요. 이벤트마다 일일 한도에서 메시지 하나를 사용하고, 일반적인 출력은 한두 개의 메시지를 보냅니다.
웹훅 만들기에서 설정을 붙여넣으세요. 다음 출력부터는 끝나는 순간을 바로 알려 줄 거예요.