QMK Firmware를 사용해 IRIS 키보드 펌웨어를 만들어보자

키 매핑을 변경하는 정도라면 QMK Configurator나 VIA를 사용하는 것 정도로 충분하다. UI를 통해서 키 배치를 변경하면 되는데다, Ctrl, Alt, Cmd, Shift같은 조합키도 이미 정해져있다보니, 클릭 몇 번이면 간단하게 펌웨어를 수정할 수 있기 때문에, 굳이 QMK Firmware를 사용할 필요가 없기도 하다.

 

다만 문제라면 IRIS/rev.7 키보드의 마우스 조작 기본값은 OFF이며, 이 값은 QMK Configurator/VIA로 켜고 끌 수가 없다. QMK Configurator/VIA에 접속해서 할당할 수 있는 키를 살펴보면, 마우스 관련된 키가 있기 때문에 할당해놓고 펌웨어를 만들어보면 정상적으로 동작하지 않는 것을 확인할 수 있다. 문제는 QMK Configurator/VIA만 사용하던 사람은 이런 내용을 알 턱이 없다는 것. 나 역시 한참을 검색하다가 IRIS/rev.7 키보드의 마우스 조작 설정 기본값이 꺼짐으로 설정되어있다는 내용을 발견하고, QMK Firmware를 설치해서 펌웨어 만드는 법을 살펴보기 시작했다.

 

QMK Firmware는 오픈소스로 관리되고 있으며, 공식 페이지에서 설치 방법을 안내하고 있다. 먼저 펌웨어를 수정하기 위한 편집기와, 펌웨어를 키보드에 설치하고 디버깅하기 위한 툴 박스를 별도로 설치해야한다. 아마 QMK Configurator/VIA를 사용해본 적이 있다면 툴 박스는 이미 설치되어 있을테니, 설치 방법에 대해서는 이 글에서 다루지 않는다.

 

MacOS에서는 다음과 같이 brew를 사용해서 사전 빌드된 QMK Firmware를 받을 수 있다. 

brew install qmk/qmk/qmk

M1/M2 칩셋을 사용하는 경우에는 다음과 같이 입력하라고 되어있지만, 문서를 작성할 때와는 달리 업데이트 됐는지 큰 문제는 발생하지 않는 것 같다. 단순히 brew install qmk/qmk/qmk를 입력했을 때 제대로 설치가 안되는 경우에만 아래와 같이 입력하도록 하자.

arch -x86_64 brew install qmk/qmk/qmk

설치가 완료되면 qmk setup을 입력해서 설정을 완료하면 된다.

qmk setup을 입력하면 다음과 같이 설정 결과가 출력된다. 중간에 서브모듈 설치에 대한 내용이 뜨는데, 나는 Y를 눌러줬다. 와! 예스맨!

이제 펌웨어를 만들어보자. 나는 keeb io에서 구매한 IRIS/rev.7 키보드를 사용하고 있기 때문에, 다음과 같이 입력해줬다. 

qmk config user.keyboard=keebio/iris/rev7

keebio/iris/rev7 자리에는 펌웨어를 만들 키보드 명을 입력하면 되는데, 위의 qmk setup 실행 결과 중 QMK home으로 표시되는 경로를 기준으로, keyboards 하위 경로에 프리셋 파일들이 있으므로 참고하도록 하자. 만약 무엇을 입력해야될지 모르겠다면 다음과 같이 qmk list-keyboards를 입력해서, 지원하는 키보드 리스트를 확인해보면 된다. 

qmk list-keyboards 실행시 출력 결과는 꽤 길기 때문에, rg를 사용해서 iris가 들어간 항목만 추렸다.

qmk config를 사용해서 사용자의 키보드 설정이 끝났다면, 다음과 같이 새로운 펌웨어를 만들어주면 된다.

qmk new-keymap

위 명령어를 실행하면 qmk config를 사용해서 선언한 프리셋으로부터 파일을 복사하여, 새로운 펌웨어를 만들게 된다. 

qmk config를 호출하지 않은 상태로 qmk new-keymap을 실행하니 위처럼 키보드 이름을 물어본다. 나는 이미 이 과정을 거쳤기 때문에, 이미 zerodice0이라는 키맵은 존재하니 다른 이름을 사용하라는 문구가 출력됐다.

만약 qmk config를 실행하지 않았거나, 혹은 설정해놓은 키보드가 아닌 다른 프리셋을 설정하고 싶다면 다음과 같이 입력하자.

qmk new-keymap -kb <keyboard_name>

이제 QMK home 기준으로 keyboards 경로 밑에 <keyboard_name>/keymaps/<GitHub Username>경로가 생성된 것을 볼 수 있다. 이 다음에는 keymap.c 파일을 수정하면 된다. 파일을 열면 생각보다 단순한 구조이므로, C언어를 잘 모르더라도 어렵지 않게 키 맵핑이 가능하다. 키 코드는 QMK Firmware Keycodes 페이지를 참고하자.

keymap.c를 열어보면 IRIS 키보드 모양으로 2차원 배열이 구성되어있다. 생각보다 간단하다!

마우스 키를 활성화하기 위해서는 rules.mk를 열어서 MOUSEKEY_ENABLE를 yes로 변경해줘야 한다. 이후에는 펌웨어에 할당된 마우스 키가 동작한다. 키보드로 마우스 키를 움직이는 건 듣기엔 굳이 필요한가싶지만, 키보드에서 손을 때지 않고도 간단한 마우스 조각을 할 수 있다는 점에서 상당히 유용하니 참고하도록하자.

마우스 키를 활성화하기 위해서는 MOUSEKEY_ENABLE값을 yes로 바꿔줘야한다.

마지막으로 펌웨어를 만들어볼 차례다. 다음과 같이 qmk compile을 입력하면, 위에서 설정해놓은 키보드 펌웨어가 빌드되기 시작한다.

qmk compile

만약 설정을 하지 않았거나, 설정해놓은 키보드와 다른 키보드의 펌웨어를 빌드하는 경우에는 다음과 같이 입력하자.

qmk compile -kb <keyboard> -km <keymap>

 여기서 <keyboard>는 qmk list_keyboards 입력시 출력되는 리스트 중에서 고르면 되고, <keymap>은 keymap.c가 위치한 경로를 입력해주면 된다.

 

별다른 오류가 발생하지 않았다면, QMK home에 펌웨어가 생성된다.

이걸 QMK Toolbox를 사용해서 키보드에 올려주면 끝! 간단하지 않은가.

키를 할당하고 펌웨어를 올리는 과정을 반복할수록, 키보드가 점점 사용하기 편해지니 이 과정에 익숙해지면 익숙해질수록 좋다.

 

여담으로 IRIS 키보드를 집/회사/예비용으로 세 개를 맞추다보니, 펌웨어도 세 번 올려야하는데 매번 저장해놓은 펌웨어를 찾기 귀찮아서 깃허브 레포지터리에 펌웨어를 올려뒀다. 이것으로 만약 키보드가 망가지는 바람에 새로 구매할 일이 생기거나, 혹은 여러개의 IRIS/rev.7 키보드에 펌웨어를 올려야 할 때도 고민 끝! ' ㅇ')/

 

https://github.com/zerodice0/iris56_keymap