키보드에서 A 키를 누르면 컴퓨터 화면에 곧바로 알파벳 A가 나타나는 것처럼 보입니다. 하지만 키보드 내부에서는 스위치가 눌린 순간부터 운영체제가 문자를 표시하기까지 여러 단계의 변환이 일어납니다. 그 중심에 있는 값이 바로 Keycode입니다.

Keycode는 단순히 특정 문자를 의미하는 이름이 아닙니다. 펌웨어가 감지한 물리적인 키 위치에 어떤 기능을 부여할지 결정하는 숫자 값에 가깝습니다. 같은 스위치라도 기본 레이어에서는 A가 될 수 있고, Fn 레이어에서는 볼륨 조절이나 방향키가 될 수 있습니다. 따라서 키보드가 인식하는 것은 처음부터 문자가 아니라 매트릭스 좌표와 그 좌표에 배정된 기능 값입니다.

특히 QMK Firmware에서는 기본 문자 키뿐 아니라 레이어 전환, Ctrl 조합, Tap-Hold, 매크로, 마우스 이동, 미디어 제어까지 다양한 동작을 Keycode 형태로 관리합니다. 이번 글에서는 스위치가 눌린 뒤 Keycode가 선택되고, QMK 내부 처리 과정을 거쳐 USB HID 리포트로 전달되는 흐름을 순서대로 살펴보겠습니다.

1. Keycode는 키캡에 적힌 문자가 아니다

Keycode를 이해할 때 가장 먼저 구분해야 하는 것은 물리 키, Keycode, 실제 입력 문자가 서로 다른 개념이라는 점입니다. 키캡에 A가 인쇄되어 있어도 키보드 회로와 펌웨어가 그 글자를 직접 읽는 것은 아닙니다.

스위치를 누르면 전기적으로 특정 행과 열이 연결됩니다. MCU는 키보드 매트릭스를 반복해서 스캔하면서 이전 상태와 현재 상태가 달라진 지점을 찾습니다. 예를 들어 2번 행과 4번 열의 스위치가 새롭게 연결되었다면 펌웨어는 먼저 “2행 4열 키가 눌렸다”라는 사실을 알아냅니다.

그다음 QMK는 현재 활성화된 레이어의 키맵에서 해당 좌표를 조회합니다. 2행 4열에 KC_A가 저장되어 있다면 그제야 이 물리 입력은 KC_A라는 Keycode로 변환됩니다. 같은 좌표에 KC_LEFT가 배치되어 있다면 방향키 왼쪽으로 처리되고, MO(1)가 배치되어 있다면 레이어를 일시적으로 활성화하는 키가 됩니다.

2. 키를 누르면 먼저 매트릭스 좌표가 발견된다

대부분의 기계식 키보드는 각 스위치를 MCU 핀에 하나씩 직접 연결하지 않고 행과 열로 구성된 매트릭스를 사용합니다. 예를 들어 5개의 행과 15개의 열을 조합하면 비교적 적은 수의 MCU 핀으로 많은 스위치를 검사할 수 있습니다.

MCU는 한쪽 라인을 순서대로 활성화하고 반대쪽 라인의 전기 상태를 읽는 방식으로 전체 키를 스캔합니다. 특정 행을 활성화했을 때 특정 열에서 신호 변화가 감지되면 그 교차점에 있는 스위치가 눌린 것으로 판단합니다. 이때 얻는 정보는 아직 KC_A나 KC_ENTER가 아니라 행 번호와 열 번호입니다.

스위치는 접점이 맞닿는 순간 짧은 시간 동안 신호가 여러 번 흔들릴 수 있습니다. 펌웨어는 디바운스 처리를 통해 이 흔들림을 하나의 정상적인 입력으로 정리합니다. 안정된 상태 변화가 확인되면 QMK는 해당 좌표의 키 이벤트를 생성하며, 눌림과 떼어짐을 각각 구분합니다.

이 구조 덕분에 물리 키의 위치와 기능을 분리할 수 있습니다. PCB의 스위치 위치는 그대로 두고 펌웨어의 키맵만 변경해도 완전히 다른 배열을 만들 수 있는 이유입니다. QWERTY 배열을 Colemak이나 Dvorak으로 바꾸거나, Caps Lock 위치에 Ctrl을 배치하는 것도 같은 원리입니다.

3. QMK는 활성 레이어에서 Keycode를 찾는다

매트릭스 좌표가 확인되면 QMK는 keymaps 배열에서 해당 위치의 값을 조회합니다. QMK 키맵은 일반적으로 레이어, 행, 열로 구성된 다차원 구조를 사용하며 각 위치에는 16비트 형태의 액션 코드가 저장됩니다.

기본 레이어가 활성화된 상태에서 A 위치를 누르면 Layer 0의 해당 좌표를 확인합니다. 그러나 Fn 키로 Layer 1이 활성화되어 있다면 같은 물리 위치에서도 Layer 1의 값을 먼저 확인합니다. Layer 1에 KC_F1이 배치되어 있다면 A가 아니라 F1 기능으로 처리됩니다.

상위 레이어의 해당 위치가 KC_TRNS로 설정되어 있으면 QMK는 그 키를 투명한 위치로 판단합니다. 즉 현재 레이어에서 기능을 확정하지 않고 아래쪽 레이어로 내려가 실제 Keycode를 찾습니다. 반대로 KC_NO가 배치되어 있으면 해당 위치는 아무 동작도 하지 않습니다.

4. KC_A는 내부적으로 숫자 값으로 처리된다

QMK의 키맵 파일을 보면 KC_A, KC_ENTER, KC_LCTRL 같은 이름이 사용됩니다. 사람이 보기에는 문자와 기능 이름이지만 컴파일 과정이 끝난 펌웨어에서는 숫자 값으로 처리됩니다. 이 이름들은 개발자가 키맵을 읽고 수정하기 쉽게 만든 기호입니다.

QMK 공식 문서에 따르면 Quantum Keycode는 일정한 숫자 범위 안에서 관리됩니다. 기본 키에 해당하는 표준 Keycode는 낮은 범위를 사용하고, 레이어 전환이나 Mod-Tap처럼 추가 정보가 필요한 기능은 다른 비트 영역을 활용합니다. 겉으로는 함수처럼 보이는 Keycode도 전처리와 컴파일 과정을 거치면 펌웨어가 해석할 수 있는 값으로 변환됩니다.

예를 들어 KC_A는 일반적인 키보드 입력을 나타내는 기본 Keycode입니다. 반면 LCTL(KC_C)는 Ctrl과 C를 함께 보내는 조합을 표현하며, LT(1, KC_SPC)는 짧게 누르면 Space를 보내고 길게 누르면 Layer 1을 활성화하도록 구성됩니다. 이 값들은 모두 같은 방식으로 처리되지 않고 Keycode의 종류에 따라 서로 다른 QMK 처리 루틴으로 전달됩니다.

5. 기본 Keycode와 QMK 전용 Keycode의 차이

모든 Keycode가 컴퓨터로 곧바로 전송되는 것은 아닙니다. KC_A나 KC_ENTER 같은 기본 Keycode는 최종적으로 USB HID 키보드 리포트에 반영될 수 있지만, MO(1), TG(2), QK_BOOT 같은 QMK 전용 Keycode는 키보드 내부 상태를 변경하기 위해 사용됩니다.

MO(1)을 누르면 운영체제에 “MO(1) 키가 눌렸다”라는 값이 전달되는 것이 아닙니다. QMK가 해당 Keycode를 먼저 가로채 Layer 1을 활성화하고, 이후 다른 키가 눌렸을 때 Layer 1의 키맵을 조회하도록 내부 상태를 변경합니다. 키를 떼면 해당 레이어를 다시 비활성화합니다.

Mod-Tap과 Layer-Tap처럼 하나의 키에 두 가지 기능이 들어 있는 Keycode는 눌린 시간, 다른 키의 입력 여부, 탭 횟수 같은 추가 조건도 확인합니다. 따라서 같은 키를 눌러도 짧게 누른 경우와 길게 누른 경우의 결과가 달라질 수 있습니다.

1. 키보드 매트릭스에서 눌린 위치를 확인합니다.
2. 현재 활성화된 레이어를 확인합니다.
3. 키맵에서 해당 위치의 Keycode를 조회합니다.
4. QMK 내부 기능이 먼저 Keycode를 검사합니다.
5. 사용자 정의 처리 함수가 입력을 확인합니다.
6. 전송 가능한 HID 입력으로 변환합니다.
7. USB 또는 무선 연결을 통해 PC로 전달합니다.

• 사용자 정의 Keycode 동작 실행
• 특정 키를 다른 키 조합으로 변환
• 문자열이나 단축키 전송
• 키가 눌릴 때와 놓일 때의 동작 분리
• 조건에 따라 기본 Keycode 처리 차단

• KC_LSFT — 왼쪽 Shift
• KC_LCTL — 왼쪽 Ctrl
• KC_LALT — 왼쪽 Alt
• KC_LGUI — Windows 키 또는 Command 키
• LCTL(KC_C) — Ctrl+C 조합

• 현재 활성화된 QMK 레이어가 맞는지 확인
• VIA 또는 키맵에서 지정한 Keycode 확인
• Windows 또는 macOS의 키보드 배열 확인
• 입력 언어와 한영 전환 상태 확인
• Shift, Ctrl, Alt 같은 수식 키가 남아 있지 않은지 확인
• 탭홀드 판정이 의도대로 작동하는지 확인

• 키 입력 자체가 감지되지 않으면 매트릭스 또는 하드웨어 확인
• 다른 Keycode가 조회되면 레이어와 키맵 확인
• Keycode는 맞지만 기능이 다르면 사용자 정의 함수 확인
• HID 입력은 맞지만 문자가 다르면 운영체제 배열 확인

• Keycode를 화면에 표시되는 문자와 동일하게 생각하는 것
• 모든 QMK Keycode가 PC로 직접 전송된다고 생각하는 것
• 물리 키 위치와 Keycode가 항상 고정되어 있다고 생각하는 것
• 레이어가 바뀌어도 같은 키가 같은 기능을 한다고 생각하는 것
• 펌웨어 문제와 운영체제 키보드 배열 문제를 구분하지 않는 것

아닙니다. 키보드는 A 키 위치에 해당하는 HID 입력 정보를 보내고, 운영체제가 현재 언어와 키보드 배열을 기준으로 최종 문자를 결정합니다.

가능합니다. 레이어마다 서로 다른 Keycode를 배치할 수 있으며, 탭홀드 기능을 사용하면 짧게 누를 때와 길게 누를 때의 동작도 나눌 수 있습니다.

MO(1)은 QMK 내부에서 레이어를 활성화하는 기능입니다. 일반 문자 키처럼 운영체제로 그대로 전송되는 값은 아닙니다.

일반적으로 사용자 정의 Keycode 값을 선언한 뒤 process_record_user 함수에서 해당 값이 눌렸을 때 실행할 동작을 작성합니다.

대부분의 경우 숫자를 외울 필요는 없습니다. KC_A, KC_ENT, MO(1)처럼 QMK가 제공하는 이름을 사용하면 컴파일 과정에서 실제 값으로 변환됩니다.

가능합니다. 운영체제에 설정된 키보드 언어와 배열이 다르면 동일한 HID 입력도 다른 문자로 해석될 수 있습니다.

Keycode는 키캡에 적힌 문자가 아니라, 매트릭스 위치와 활성 레이어를 바탕으로 QMK가 찾아낸 동작 값입니다. 이 값은 펌웨어 내부 기능으로 처리되거나 HID 리포트로 변환된 뒤 운영체제에서 최종 입력으로 해석됩니다.