KMK 펌웨어 입문, 파이썬으로 키보드 커스텀하기
컴파일 없이 파일만 수정하면 끝나는 키보드 펌웨어
- KMK는 CircuitPython 기반 키보드 펌웨어로, main.py 하나만 수정하면 즉시 반영됩니다.
- QMK처럼 매번 빌드·플래시할 필요가 없어 코딩 초보자에게 진입장벽이 낮습니다.
- RP2040(라즈베리파이 피코) 계열 보드가 가장 무난한 선택지입니다.
- 인터프리터 방식이라 QMK 대비 반응 속도와 메모리 여유는 다소 부족합니다.
- 현재 KMK는 유지보수가 활발하지 않은 상태(limited life support)라 이 점을 감안해야 합니다.
커스텀 키보드를 만들다 보면 “펌웨어”라는 벽 앞에서 멈추는 경우가 많습니다. QMK는 기능은 많지만 빌드 환경을 세팅하고, 키맵 하나 바꿀 때마다 컴파일하고 플래시하는 과정이 은근히 번거롭습니다.
파이썬을 조금이라도 다뤄봤다면 KMK가 훨씬 편하게 느껴질 수 있습니다. 이 글에서는 KMK가 무엇인지, QMK와 뭐가 다른지, 어떤 보드로 시작해야 하는지, main.py를 어떻게 작성하는지 순서대로 정리했습니다.
결론부터 말하면 KMK는 “빠르게 이것저것 테스트해보고 싶은 사람”에게 잘 맞습니다. 반대로 최고 성능과 안정성이 필요하다면 QMK가 여전히 정답에 가깝습니다.
1. KMK 펌웨어란 무엇인가
KMK는 CircuitPython으로 작성되고 설정되는 키보드 펌웨어입니다. Adafruit이 만든 CircuitPython 위에서 동작하기 때문에, 별도의 컴파일 도구 없이 마이크로컨트롤러를 USB 드라이브처럼 인식시켜 파일을 직접 수정할 수 있습니다.
구조가 간단합니다. 보드를 컴퓨터에 연결하면 CIRCUITPY라는 이름의 드라이브가 나타나고, 그 안의 main.py 파일 하나로 키맵·레이어·매크로를 전부 정의합니다. 파일을 저장하는 즉시 변경 사항이 반영되며, DFU 같은 별도 개발 도구가 필요 없습니다.
단일 보드형 키보드는 물론 한 몸체 또는 두 조각으로 나뉜 스플릿 키보드도 지원하고, 블루투스 HID를 통한 무선 연결도 가능합니다. 유니코드 매크로, RGB 언더글로우, 여러 번 탭할 때마다 다른 동작을 하는 키 설정 같은 기능도 기본으로 들어 있습니다.
KMK를 쓰려면 최소 CircuitPython 8.0 이상이 설치돼 있어야 합니다. 보드에 이미 오래된 CircuitPython이 올라가 있다면 먼저 최신 버전으로 업데이트하세요.
2. QMK와 KMK, 뭐가 다른가
가장 큰 차이는 작업 방식입니다. QMK는 C 언어로 작성된 코드를 빌드해서 하나의 바이너리 파일로 만들고, 그걸 보드에 플래시하는 과정을 거칩니다. 키맵을 한 줄만 바꿔도 이 과정을 반복해야 합니다.
KMK는 이 과정이 없습니다. USB 드라이브로 인식되는 파일을 열어서 수정하고 저장하기만 하면 바로 반영됩니다. 그만큼 시행착오를 빠르게 반복할 수 있어서, 레이어 구조를 여러 번 뜯어고치는 초기 세팅 단계에서 특히 편합니다.
다만 공짜는 아닙니다. CircuitPython은 인터프리터 언어라서 미리 컴파일된 C 기반 펌웨어보다 느리고 메모리를 더 많이 씁니다. 이로 인해 키 입력 반응 속도에 체감할 수 있는 지연이 생길 수 있고, 넣을 수 있는 기능의 개수도 제한될 수 있습니다.
KMK는 현재 활발히 유지보수되지 않는 limited life support 상태입니다. 새 이슈나 PR이 바로 처리되지 않을 수 있으니, 장기적으로 안정적인 지원이 중요한 프로젝트라면 이 점을 감안하고 시작하세요.
3. 어떤 보드로 시작해야 하나
KMK는 CircuitPython이 도는 마이크로컨트롤러라면 대부분 사용할 수 있습니다. 입문자에게는 라즈베리파이 피코(RP2040) 계열을 추천합니다. 가격이 저렴하고 자료도 많습니다.
RP2040은 264KB의 온보드 RAM을 갖고 있고, 별도의 QSPI 플래시 칩을 통해 저장공간을 제공받습니다. 피코 기준으로는 2MB 용량 중 파이썬으로 코드를 돌릴 경우 약 1MB 정도가 코드·파일용으로 남습니다. 키맵 파일 하나 정도는 여유롭게 들어가는 크기입니다.
설치는 어렵지 않습니다. 피코를 USB에서 뽑은 상태에서 BOOTSEL 버튼을 누른 채로 연결하면 RPI-RP2라는 드라이브가 나타나고, 여기에 CircuitPython UF2 파일을 끌어다 놓으면 설치가 끝납니다.
4. main.py 기본 구조 이해하기
CircuitPython 설치가 끝나면 CIRCUITPY 드라이브에 KMK 라이브러리 폴더와 main.py 파일을 넣습니다. main.py는 아래와 같은 흐름으로 구성됩니다.
1. board와 kmk 모듈을 불러옵니다. 2. KMKKeyboard 객체를 만듭니다. 3. col_pins·row_pins로 매트릭스 배선을 지정합니다. 4. diode_orientation으로 다이오드 방향을 맞춥니다. 5. keymap 리스트에 실제 키 배열을 씁니다. 6. keyboard.go()로 실행을 시작합니다.
레이어를 쓰고 싶다면 Layers 모듈을 modules 리스트에 추가하고, KC.MO() 같은 함수로 레이어 전환 키를 만듭니다. 미디어 키가 필요하면 MediaKeys 확장 기능을 extensions 리스트에 넣으면 됩니다.
레이어 전환 키를 만들 때 코드 순서를 착각하는 경우가 많습니다. modules 리스트에 Layers()를 추가하기 전에 KC.MO() 같은 레이어 함수를 먼저 호출하면 보드가 세이프 모드로 빠지면서 부팅이 안 될 수 있습니다. 반드시 modules 설정을 먼저 끝낸 뒤 레이어 키를 정의하세요.
5. 자주 하는 실수와 해결 방법
가장 흔한 실수는 CircuitPython 버전 불일치입니다. KMK 최신 버전은 CircuitPython 8.0 이상을 요구하는데, 예전 튜토리얼을 보고 낮은 버전을 그대로 쓰는 경우가 있습니다. 부팅이 이상하다면 버전부터 확인하세요.
두 번째는 col_pins·row_pins 순서 착오입니다. 실제 배선과 코드의 핀 순서가 어긋나면 엉뚱한 키가 눌리거나 아예 반응이 없습니다. 매트릭스를 새로 짤 때마다 배선도와 코드를 나란히 놓고 확인하는 습관이 필요합니다.
세 번째는 code.py와 main.py를 동시에 두는 경우입니다. CircuitPython은 code.py를 우선 실행하기 때문에, main.py에 아무리 코드를 잘 짜도 code.py가 남아 있으면 그쪽이 먼저 돌아갑니다. KMK를 쓸 때는 code.py를 지우거나 main.py를 불러오도록 비워두는 게 안전합니다.
6. KMK가 잘 맞는 사람, 안 맞는 사람
레이어 구조를 자주 실험하고, 무선 스플릿 키보드를 파이썬으로 가볍게 만들어보고 싶은 사람에게 KMK는 좋은 선택입니다. 코딩 경험이 적어도 문법이 직관적이라 진입이 쉽습니다.
반대로 최고 수준의 응답 속도가 필요한 게이밍용 키보드를 만들거나, 장기적으로 안정적인 커뮤니티 지원을 받고 싶다면 QMK 쪽이 더 안전한 선택입니다. 두 펌웨어를 같은 보드에서 번갈아 테스트해보는 것도 방법입니다.
자주 묻는 질문
CircuitPython을 지원하는 보드여야 합니다. RP2040, SAMD21 계열 보드가 대표적이고, 보드가 CircuitPython을 지원하지 않으면 KMK도 쓸 수 없습니다.
VIA는 QMK·VIA 호환 펌웨어를 전제로 만들어진 도구라서 KMK와는 기본적으로 호환되지 않습니다. KMK는 main.py 파일을 직접 편집하는 방식으로 설정을 바꿉니다.
기본 예제를 복사해서 핀 번호와 키맵만 바꾸는 수준이라면 파이썬 문법을 몰라도 시작할 수 있습니다. 다만 레이어나 매크로처럼 복잡한 기능을 다루려면 기본 문법을 조금은 익히는 게 좋습니다.
이미 설치된 펌웨어 자체는 계속 동작합니다. 다만 새 기능 추가나 버그 수정이 느려질 수 있으니, 신규 프로젝트라면 이 점을 참고해서 QMK나 ZMK 같은 대안도 함께 검토해보는 걸 추천합니다.
📚 함께 보면 좋은 글
키보드를 직접 만지기 시작했다면 함께 보면 도움이 되는 글들입니다.
🔗 공식 자료
KMK 공식 GitHub 저장소(https://github.com/KMKfw/kmk_firmware), CircuitPython 공식 다운로드 사이트(https://circuitpython.org)를 확인하면 최신 정보를 얻을 수 있습니다.
📖 출처
1. KMK Firmware GitHub 저장소, https://github.com/KMKfw/kmk_firmware
2. Adafruit Learning System, “Installing CircuitPython”, https://learn.adafruit.com/intro-to-rp2040-pio-with-circuitpython/installing-circuitpython
3. CircuitPython 공식 다운로드 페이지(Raspberry Pi Pico), https://circuitpython.org/board/raspberry_pi_pico/
4. Nicholas Coughlin, “Keyboard Firmware Comparison”, https://ncoughlin.com/posts/keyboard-firmware-comparison
5. 0부터 시작하는 스플릿 키보드 자작, wikidocs, https://wikidocs.net/198789
KMK는 파이썬으로 키맵을 즉시 수정할 수 있는 진입장벽 낮은 키보드 펌웨어입니다. 다만 유지보수 상태가 예전 같지 않으니, 빠른 실험용으로는 좋지만 장기 프로젝트라면 QMK나 ZMK도 함께 검토해보세요.
