커스텀 키보드 설명에서 자주 등장하는 QMK Firmware는 단순히 키 위치를 바꾸는 프로그램이 아닙니다. 키보드 전원이 켜진 순간부터 스위치 상태를 확인하고, 눌린 키를 해석하며, 레이어와 매크로를 처리하고, 최종 입력을 컴퓨터에 전달하는 전체 동작을 담당합니다.

VIA에서 키 하나를 바꾸면 화면에서는 단순한 키맵 변경처럼 보이지만, 그 아래에서는 QMK가 정의한 키코드 구조와 레이어 처리 방식, 메모리 저장 방식, USB HID 보고서 생성 과정이 함께 작동합니다. 직접 QMK 소스를 수정할 때는 여기에 키보드 매트릭스 핀, 다이오드 방향, MCU 종류, 부트로더, RGB 기능과 같은 하드웨어 설정까지 다뤄야 합니다.

QMK Firmware 구조가 어렵게 느껴지는 가장 큰 이유는 파일이 많기 때문입니다. 하지만 모든 파일을 한꺼번에 이해할 필요는 없습니다. QMK를 크게 보면 공통 펌웨어 엔진, 키보드 하드웨어 정의, 사용자 키맵이라는 세 계층으로 나눌 수 있습니다. 이 계층이 컴파일 단계에서 하나로 합쳐져 MCU가 실행할 펌웨어가 됩니다.

1. QMK Firmware는 키보드 안에서 무엇을 할까?

키보드 스위치는 문자 정보를 직접 만들어내지 않습니다. 사용자가 A 키를 누르더라도 스위치가 MCU에 전달하는 것은 특정 행과 열이 전기적으로 연결되었다는 상태 변화에 가깝습니다. 어느 위치가 어떤 문자에 해당하는지는 펌웨어가 판단합니다.

QMK는 먼저 키보드 매트릭스를 반복적으로 스캔합니다. 이전 스캔 결과와 현재 결과를 비교해 새로 눌린 키와 해제된 키를 찾고, 접점의 순간적인 흔들림을 걸러내기 위해 디바운스 처리를 적용합니다. 그다음 현재 레이어와 키맵을 기준으로 해당 위치의 키코드를 결정합니다.

키코드가 단순한 영문자라면 비교적 바로 처리할 수 있지만, QMK에서는 하나의 키에 훨씬 복잡한 동작을 지정할 수 있습니다. 짧게 누르면 Escape, 길게 누르면 Control로 작동하게 만들거나, 키를 누르는 동안만 다른 레이어를 활성화하거나, 여러 키를 순서대로 실행하는 매크로를 연결할 수도 있습니다.

모든 처리가 끝나면 QMK는 현재 눌린 키 정보를 USB HID 형식의 보고서로 구성합니다. 컴퓨터는 이 보고서를 받아 운영체제의 키보드 입력으로 처리합니다. 따라서 QMK는 물리적인 스위치 변화와 운영체제가 이해하는 키 입력 사이를 연결하는 핵심 소프트웨어라고 볼 수 있습니다.

이 과정은 키를 한 번 누를 때만 실행되는 것이 아닙니다. MCU의 메인 루프가 계속 반복되면서 매트릭스를 스캔하고 각종 작업을 처리합니다. 조명 애니메이션, 인코더 회전, OLED 표시, 분할 키보드 통신 같은 기능도 이 반복 구조 안에서 함께 관리됩니다.

2. QMK 소스는 어떤 계층으로 나뉠까?

QMK Firmware 저장소를 열어보면 수많은 폴더와 C 파일이 표시됩니다. 처음에는 키보드 하나를 작동시키는 데 왜 이렇게 많은 코드가 필요한지 의문이 들 수 있습니다. 이는 QMK가 특정 키보드 한 대만을 위한 펌웨어가 아니라 다양한 MCU와 수많은 키보드 설계를 공통 구조로 지원하기 때문입니다.

QMK 공식 저장소의 공통 영역에는 키 입력 처리, 레이어, 키코드, USB 통신, 조명, 오디오, 포인팅 장치 등 여러 키보드에서 재사용하는 기능이 들어 있습니다. 사용자는 이 공통 코드를 매번 새로 작성하지 않고, 자신의 키보드에 필요한 하드웨어 정보와 키맵만 추가해 펌웨어를 만들 수 있습니다.

예를 들어 하나의 키보드 제품에 여러 PCB 리비전이 존재한다면 상위 키보드 폴더에는 공통 설정을 두고, 하위 리비전 폴더에는 MCU나 핀 배치처럼 달라진 부분만 저장할 수 있습니다. QMK는 상위 폴더와 하위 폴더의 설정을 계층적으로 읽어 최종 구성을 만듭니다.

이 구조 덕분에 같은 키보드의 여러 버전이 공통 코드를 공유할 수 있습니다. 반대로 폴더 계층을 제대로 이해하지 못하고 하위 리비전의 설정만 수정하면 상위 폴더에서 내려온 값과 충돌하거나, 의도한 키보드가 아닌 다른 빌드 대상에 설정을 적용하는 실수가 생길 수 있습니다.

3. 키보드 폴더 안의 주요 파일

QMK 키보드 폴더를 이해하려면 모든 C 파일보다 먼저 info.json, config.h, rules.mk, keymap.c의 역할을 구분해야 합니다. 이 네 파일은 비슷해 보이지만 담당하는 정보가 다릅니다.

최근 QMK는 키보드의 정적인 정보를 가능한 한 info.json으로 관리하는 데이터 기반 구성을 사용합니다. QMK 공식 문서에 따르면 info.json의 정보는 config.h와 rules.mk의 설정과 결합되어 컴파일 시 필요한 최종 구성을 만듭니다. 또한 QMK API와 Configurator가 키보드 배열을 표시할 때도 이 정보가 사용됩니다. :contentReference[oaicite:0]{index=0}

info.json｜키보드의 구조화된 설명서

info.json에는 키보드 이름, 제조사, USB 식별 정보, MCU와 부트로더, 매트릭스 크기, 다이오드 방향, 지원 기능, 물리적 레이아웃 같은 내용을 JSON 형식으로 작성할 수 있습니다. 특히 키보드의 키 위치와 배열 정보는 QMK Configurator가 화면에 키보드를 그릴 때 중요한 기준이 됩니다.

여기서 주의할 점은 물리적인 키 위치와 전기적인 매트릭스 위치가 같지 않을 수 있다는 것입니다. 키보드 위에서 왼쪽부터 순서대로 배치된 키라도 PCB 배선에서는 서로 다른 행과 열에 연결될 수 있습니다. info.json의 레이아웃 정의는 화면상의 위치와 매트릭스 좌표를 연결하는 역할을 합니다.

config.h｜컴파일 전 적용되는 설정값

config.h는 C 전처리기 매크로를 이용해 펌웨어 동작을 설정하는 헤더 파일입니다. 기능별 시간값, 버퍼 크기, 입력 방식, 조명 관련 옵션처럼 컴파일 과정에서 코드가 참고해야 할 값을 정의할 수 있습니다.

QMK는 폴더 계층마다 config.h를 둘 수 있으며, 상위 키보드 설정과 하위 리비전 설정, 키맵별 설정이 최종 빌드에 반영됩니다. 특정 값을 하위 단계에서 다시 지정해야 할 때는 이미 정의된 매크로를 #undef로 해제한 뒤 새 값으로 정의해야 하는 경우도 있습니다. :contentReference[oaicite:1]{index=1}

rules.mk｜포함할 기능과 빌드 규칙

rules.mk는 어떤 QMK 기능을 펌웨어에 포함할지 결정하는 빌드 설정 파일입니다. 예를 들어 RGB Matrix, OLED, 인코더, 오디오, 마우스 키, 콤보 기능을 활성화하면 관련 소스가 빌드 대상에 들어갑니다.

모든 기능을 무조건 활성화하지 않는 이유는 MCU의 플래시 메모리와 RAM이 제한되어 있기 때문입니다. 사용하지 않는 기능을 제외하면 펌웨어 크기를 줄일 수 있고, 작은 용량의 AVR MCU에서도 필요한 기능을 선택적으로 사용할 수 있습니다.

다만 최근 QMK 구조에서는 여러 정적 설정이 info.json으로 이동했으며, 내용이 없는 rules.mk는 필수가 아닙니다. 따라서 오래된 QMK 강좌와 최신 키보드 폴더를 비교하면 파일 구성이 다르게 보일 수 있습니다. :contentReference[oaicite:2]{index=2}

keymap.c｜레이어와 사용자 입력 동작

keymap.c는 사용자가 가장 자주 수정하는 파일입니다. 기본 레이어와 Fn 레이어에 어떤 키코드를 배치할지 정의하며, 키를 눌렀을 때 실행할 사용자 지정 코드도 작성할 수 있습니다.

단순한 키맵은 키코드 배열만으로 완성되지만, 복잡한 키맵에서는 process_record_user(), matrix_scan_user(), layer_state_set_user() 같은 사용자 후크를 활용할 수 있습니다. 이를 통해 특정 키 입력을 가로채거나, 레이어 상태에 따라 LED를 바꾸거나, 주기적으로 실행할 동작을 추가할 수 있습니다.

4. LAYOUT 매크로는 왜 필요할까?

keymap.c를 보면 키코드가 단순한 2차원 매트릭스 배열이 아니라 LAYOUT, LAYOUT_ansi, LAYOUT_60_ansi 같은 이름 안에 작성된 경우가 많습니다. 이 LAYOUT 매크로는 사용자가 보는 물리적 키 배열을 PCB의 행과 열 좌표로 변환합니다.

PCB 매트릭스는 배선 효율을 기준으로 구성되기 때문에 실제 키보드 모양과 다를 수 있습니다. 사용자가 keymap.c에 매트릭스 좌표를 직접 입력해야 한다면 키 하나를 변경할 때마다 회로도를 확인해야 합니다. LAYOUT 매크로를 사용하면 키보드 위에 보이는 순서대로 키코드를 작성하고, 내부에서 올바른 매트릭스 좌표로 재배열할 수 있습니다.

하나의 PCB가 ANSI Enter와 ISO Enter, 분할 Backspace, 분할 Spacebar 같은 여러 배열을 지원한다면 LAYOUT 매크로도 여러 개 존재할 수 있습니다. 이때 자신의 실제 조립 배열과 다른 매크로를 선택하면 키 개수가 맞지 않거나 일부 위치가 의도와 다르게 연결될 수 있습니다.

QMK Configurator에서 배열을 고를 때 여러 레이아웃 이름이 나타나는 것도 같은 이유입니다. Configurator가 단순히 키보드 제품명만 확인하는 것이 아니라, 해당 PCB가 제공하는 LAYOUT 정의를 읽어 선택 가능한 배열을 보여주는 것입니다.

5. keymap.c에서 레이어는 어떻게 표현될까?

QMK의 레이어는 서로 다른 키맵 배열을 여러 장 겹쳐 놓은 구조입니다. 일반적으로 Layer 0에는 기본 입력을 두고, Layer 1에는 숫자열이나 방향키, 미디어 키, RGB 제어 같은 보조 기능을 배치합니다.

keymap.c에서는 각 레이어가 별도의 LAYOUT 배열로 정의됩니다. 레이어 번호는 단순히 화면 전환 순서가 아니라, 현재 활성화된 여러 레이어 가운데 어떤 키코드를 우선해서 읽을지 결정하는 기준이 됩니다.

상위 레이어의 특정 위치가 KC_TRNS로 설정되어 있으면 QMK는 바로 아래 활성 레이어의 같은 위치를 확인합니다. 반대로 KC_NO는 해당 위치에서 아무 입력도 발생시키지 않습니다. 두 키코드는 화면에서 비슷하게 보일 수 있지만 레이어가 겹쳐질 때 결과가 완전히 다릅니다.

레이어 상태는 MCU가 실행 중인 동안 RAM에서 관리됩니다. 다만 기본 레이어처럼 전원을 껐다 켜도 유지해야 하는 설정은 EEPROM 또는 MCU의 비휘발성 저장 영역에 기록할 수 있습니다. 따라서 모든 레이어가 EEPROM에 통째로 저장되는 것은 아니며, 컴파일된 키맵과 실행 중인 레이어 상태, 비휘발성 기본 레이어 설정을 구분해야 합니다.

6. QMK는 설정 파일을 어떻게 하나의 펌웨어로 만들까?

QMK 소스 폴더에 있는 파일은 MCU가 그대로 실행할 수 있는 형태가 아닙니다. C 소스와 JSON 설정, 빌드 규칙을 컴파일해 MCU 종류에 맞는 기계어 바이너리로 변환해야 합니다.

사용자가 키보드와 키맵을 지정해 컴파일을 시작하면 QMK 빌드 시스템은 해당 키보드 경로를 확인합니다. 이후 상위 키보드 폴더, 하위 리비전 폴더, 선택한 키맵 폴더에서 설정을 수집하고, info.json과 config.h, rules.mk의 내용을 결합합니다.

그다음 선택한 MCU 플랫폼에 필요한 드라이버와 QMK 공통 코어, 활성화된 기능의 소스 코드, 키보드별 코드, keymap.c의 사용자 코드를 함께 컴파일합니다. 사용하지 않는 기능은 빌드 대상에서 제외되거나 최종 링크 과정에서 제거될 수 있습니다.

출력 파일 형식은 MCU와 부트로더에 따라 다릅니다. AVR 기반 키보드에서는 HEX 파일을 자주 사용하고, ARM 계열에서는 BIN 파일이 사용될 수 있습니다. RP2040처럼 UF2 부트로더 방식을 사용하는 MCU에서는 UF2 파일을 저장 장치에 복사하는 방식으로 플래시할 수 있습니다.

중요한 점은 QMK 소스 수정과 실제 키보드 변경이 서로 다른 단계라는 것입니다. keymap.c를 수정했더라도 다시 컴파일하지 않으면 새 펌웨어 파일이 만들어지지 않습니다. 컴파일된 파일을 만들었더라도 MCU에 플래시하지 않으면 현재 키보드는 기존 펌웨어를 계속 실행합니다.