ZMK 무선 키보드 만들기, QMK와는 다른 시작점

무선 커스텀 키보드를 알아보다 보면 QMK 다음으로 꼭 마주치는 이름이 ZMK입니다. 그런데 막상 시작하려면 QMK 자료는 넘치는데 ZMK 쪽은 설명이 뚝뚝 끊기는 느낌을 받기 쉽습니다.

이 글은 QMK를 이미 써본 사람 기준으로, ZMK가 근본적으로 무엇이 다른지부터 짚고 들어갑니다. 키맵 문법, 빌드 방식, 배터리 관리까지 처음 설정할 때 막히는 지점 위주로 정리했습니다.

결론부터 말하면 ZMK는 무선 스플릿 키보드를 만들 계획이라면 QMK보다 자연스러운 선택입니다. 다만 배우는 방식 자체가 다르기 때문에 QMK 습관을 그대로 가져오면 오히려 헷갈립니다.

1. ZMK와 QMK, 근본적으로 다른 설계 철학

QMK는 2010년대 초반 유선 키보드 시대에 만들어진 코드베이스라 무선 기능이 나중에 추가된 구조입니다. 반면 ZMK는 처음부터 무선을 기본값으로 놓고 설계됐습니다.

ZMK는 Zephyr 프로젝트의 RTOS(Real Time Operating System) 위에서 동작합니다. Zephyr는 리눅스 재단이 관리하는 임베디드 운영체제로, 블루투스 스택과 전력 관리 기능이 처음부터 내장돼 있습니다. ZMK는 Zephyr RTOS 위에서 동작하는 오픈소스 커스텀 키보드 펌웨어로, USB·블루투스 연결부터 전원 관리, 키 입력 처리까지 Zephyr의 기능을 활용합니다.

그 결과 ZMK는 전력 효율성·유연성·폭넓은 하드웨어 지원을 목표로 설계됐고, 유선과 무선 입력 장치 모두에 사용할 수 있습니다. 라이선스도 MIT라 QMK의 GPL과 달리 상업적으로 훨씬 자유롭게 활용할 수 있습니다.

2. QMK와 ZMK 실전 비교

둘 다 커스텀 키보드 펌웨어지만 실제로 작업할 때 체감하는 차이는 꽤 큽니다. 표로 정리하면 다음과 같습니다.

가장 크게 체감되는 차이는 실시간 편집입니다. 유선에서 VIA나 Vial을 쓰면 매핑이 바로 반영되지만, ZMK는 원래 키맵을 수정하고 저장한 뒤 다시 컴파일해서 펌웨어를 키보드에 올려야 하는 번거로움이 있었습니다. 이 불편을 줄이려고 나온 도구가 뒤에서 다룰 ZMK Studio입니다.

2. 시작 전에 확인할 하드웨어

ZMK로 무선 키보드를 만들려면 컨트롤러 선택이 가장 중요합니다. Zephyr RTOS를 기반으로 하기 때문에 노르딕 nRF52 계열, 라즈베리파이 RP2040/RP2350, 대부분의 ST STM32 MCU, 마이크로칩 SAMD21까지 폭넓게 지원합니다.

이 중에서도 무선 키보드를 목표로 한다면 사실상 선택지는 정해져 있습니다. 블루투스 라디오가 내장된 Nordic nRF52840이 사실상 표준입니다. RP2040은 BLE가 없어 유선 전용이거나 별도 라디오 모듈이 필요합니다.

스플릿 키보드라면 양쪽 하프에 각각 컨트롤러가 필요하고, 배터리를 물려야 하니 케이스 안에 배터리 공간이 있는지도 미리 확인하는 게 좋습니다. 시중에는 nice!nano, Seeed XIAO nRF52840 같은 완제품 컨트롤러 모듈을 많이 씁니다.

3. 클라우드 빌드 환경 만들기

ZMK는 로컬에 컴파일 환경을 직접 깔지 않아도 됩니다. GitHub 저장소에 설정 파일만 올려두면 GitHub Actions가 서버에서 자동으로 펌웨어를 빌드해 줍니다.

1. zmk-config-template 저장소를 자신의 GitHub 계정으로 포크합니다.
2. config/ 폴더 안의 .keymap 파일과 .conf 파일을 자신의 키보드 설정에 맞게 수정합니다.
3. 변경 사항을 커밋(commit)하고 푸시(push)하면 Actions 탭에서 자동 빌드가 시작됩니다.
4. 빌드가 끝나면 .uf2 펌웨어 파일을 다운로드합니다.
5. 컨트롤러를 부트로더 모드로 진입시켜 가상 드라이브로 인식되면 .uf2 파일을 복사해 넣습니다.

이 방식은 초반에는 낯설어도 로컬 컴파일 환경을 따로 세팅할 필요가 없다는 장점이 있습니다. 실제로 QMK에서 넘어온 사용자들 사이에서도 깃허브 액션에서 자동으로 빌드되니 로컬에서 직접 컴파일하는 방식보다 편리하다는 평가가 많습니다.

4. .keymap 파일, devicetree 문법 이해하기

ZMK 키맵은 C 함수 호출이 아니라 devicetree 문법으로 작성합니다. 처음 보면 중괄호와 앤퍼샌드(&)가 낯설지만, 구조를 알면 QMK보다 오히려 간결합니다.

가장 자주 쓰는 세 가지 바인딩은 다음과 같습니다. &kp는 키 입력(key press), &mo는 눌려 있는 동안만 레이어 전환(momentary layer), &lt는 짧게 누르면 키, 길게 누르면 레이어 전환(layer-tap)입니다.

레이어는 keymap { layer_0 { bindings = <...>; }; } 형태로 중첩된 노드 안에 정의합니다. 콤보(combo)나 매크로도 같은 devicetree 방식으로 별도 노드에 선언합니다.

5. ZMK Studio로 실시간 편집하기

ZMK Studio는 펌웨어를 다시 굽지 않고도 키보드의 키맵 레이어를 변경할 수 있게 해주는 런타임 편집 기능입니다. QMK의 VIA·Vial과 비슷한 목적으로 만들어졌습니다.

현재 ZMK Studio는 크롬·엣지 브라우저와 리눅스·macOS·윈도우 네이티브 앱으로 사용할 수 있으며, 레이어 편집과 키 리매핑을 지원합니다. 다만 아직 모든 기능을 지원하지는 않습니다. 인코더나 마우스 에뮬레이션 같은 커스텀 비헤이비어는 Studio에서 편집할 수 없고 펌웨어를 다시 플래싱해야 합니다.

주의할 점도 있습니다. ZMK Studio를 활성화하려면 램(RAM)을 훨씬 많이 사용하기 때문에 STM32F072 같은 일부 저사양 MCU는 설정값을 세밀하게 조정해야 Studio 빌드가 들어갈 수 있습니다.

6. 처음 만들 때 흔히 하는 실수

ZMK를 처음 설정할 때 막히는 지점은 대체로 비슷합니다. 미리 알아두면 시간을 아낄 수 있습니다.

컨트롤러부터 잘못 고르는 경우. 예전 QMK 보드에서 쓰던 Pro Micro(ATmega32U4)를 그대로 재사용하려다가 지원이 안 된다는 걸 뒤늦게 알게 되는 경우가 많습니다. 구매 전에 nRF52840 계열인지부터 확인해야 합니다.

양쪽 하프의 역할을 헷갈리는 경우. 스플릿 키보드는 central(중앙)과 peripheral(주변) 역할을 구분해야 합니다. 설정 파일에서 이 역할이 뒤바뀌면 페어링은 되는데 특정 쪽 입력이 아예 안 먹는 증상이 생깁니다.

배터리 소모를 신경 쓰지 않는 경우. BLE 자체는 전력 효율이 좋지만, 디스플레이나 백라이트를 켜두면 배터리가 빠르게 닳습니다. 디스플레이가 필요 없다면 아예 빼는 것이 배터리 수명에 유리합니다.

7. 자주 묻는 질문

📚 함께 보면 좋은 글

ZMK로 무선 키보드를 조립한 다음 참고하면 좋은 글들을 모았습니다.

🔗 공식 자료

📖 출처

1. ZMK Firmware GitHub README, https://github.com/zmkfirmware/zmk
2. Introduction to ZMK, ZMK 공식 문서, https://zmk.dev/docs
3. Supported Hardware, ZMK 공식 문서, https://zmk.dev/docs/hardware
4. ZMK Studio, ZMK 공식 문서, https://zmk.dev/docs/features/studio
5. Building Open Keyboards with ZMK & Zephyr, Zephyr Project 블로그, https://www.zephyrproject.org/building-open-keyboards-with-zmk-zephyr/