본문으로 건너뛰기
시골프로그래머의 블로그
블로그 메뉴

문서 없는 매크로 키패드의 통신 방식을 알아내 만든 설정 프로그램 — hid-macro-keypad

6키와 노브 하나짜리 미니 매크로 키패드(VID 1189 / PID 8890)의 비공식 설정 프로그램입니다. 제조사 프로그램을 분석해 통신 방식을 알아냈고, 설정을 프로파일 파일로 저장합니다.

풀빛컴퓨팅3분 읽기#오픈소스#Delphi#HID#리버스 엔지니어링

키 6개와 돌리는 노브 하나가 달린 작은 매크로 키패드가 있습니다. 제조사 설정 프로그램으로 키마다 단축키를 넣을 수 있는데, 두 가지가 없습니다. 설정을 저장하고 불러오는 기능이 없어 용도를 바꿀 때마다 6개 키를 손으로 다시 넣어야 합니다. 장치에서 현재 설정을 읽어 오는 기능도 없어, 지금 무엇이 들어 있는지 확인할 방법이 없습니다.

hid-macro-keypad는 이 키패드를 위한 비공식 설정 프로그램입니다. 소스도 문서도 없는 장치라 제조사 프로그램의 실행 파일만 가지고 통신 방식을 복원했고, 실제 기기에 패킷을 보내 하나씩 확인했습니다.

대상 키패드 — 물리 키 6개와 로터리 노브 1개

무엇을 하나

  • 각 키와 노브(좌회전·누름·우회전)에 키보드 조합, 멀티미디어 키, 마우스 동작을 지정합니다.
  • 키보드 조합은 한 키에 최대 5단계까지 이어 붙일 수 있습니다.
  • 매핑을 프로파일 파일로 저장하고 불러옵니다.
  • 장치 LED 모드(꺼짐, 항상 켜짐, 순차 점등)를 바꿉니다.

장치를 읽을 수 없으므로 프로파일 파일이 기준입니다. 파일은 %APPDATA%\HIDKeyboard\profiles\<이름>.json에 저장되고, 키를 고치면 바로 파일에 써집니다. 탐색기에서 파일을 복사하면 그대로 새 프로파일이 됩니다. 제목 표시줄의 *는 아직 장치에 보내지 않은 변경이 있다는 뜻입니다.

대상 장치 값
VID / PID 0x1189 / 0x8890
구성 물리 키 6개(2행 × 3열) + 로터리 노브 1개
설정용 인터페이스 MI_01 (공급업체 정의 HID)

통신 방식을 알아낸 과정

제조사 프로그램은 .NET으로 만들어졌고, 디버그 심볼(.pdb)이 함께 들어 있었습니다. Windows SDK의 ildasm으로 풀어 보니 약 18,000줄의 IL 코드에 클래스와 메서드 이름이 그대로 남아 있었습니다. 여기서 장치를 찾는 방법, 실제로 보내는 데이터가 8바이트라는 점, 키 종류별 코드(키보드 1, 멀티미디어 2, 마우스 3, LED 8), 키 코드가 표준 HID 값이라는 점을 읽어 냈습니다.

그런데 이것만으로 만든 첫 구현은 동작하지 않았습니다. 실제 장치에 패킷을 보내 보며 바로잡은 내용이 많습니다.

코드 분석으로 알아낸 것 실측으로만 확정된 것
VID와 인터페이스 필터 ReportID 값 (3)
8바이트 페이로드 전송 방식 (WriteFile만 동작)
버퍼 위치별 의미 순번 0이 헤더라는 것
키 종류 코드 레이어 미지원
키 코드가 표준 HID 값 modifier 비트 배치, LED 모드의 실제 동작

몇 가지는 꽤 큰 문제였습니다. 순번 0이 헤더라는 것을 모르고 키를 보냈더니 기존 매핑이 모두 지워졌습니다. 반복 조건이 <가 아니라 <=였던 것입니다. 레이어 1~3이 있는 줄 알고 세 번 나눠 보냈더니, 실제로는 저장소가 한 벌뿐이라 뒤에 보낸 빈 키가 앞의 설정을 덮어썼습니다.

이 확인에는 GUI 없이 PowerShell로 패킷을 직접 보내는 tools\hidwrite.ps1을 썼습니다. 앱의 버그인지 프로토콜을 잘못 이해한 것인지 나눠 볼 수 있었던 것이 컸습니다. 전체 프로토콜과 실측 근거는 저장소의 docs/PROTOCOL.md에 정리해 두었습니다.

빌드

Delphi 13.0(Studio 37.0) Win64 전용입니다.

.\build.ps1          # 전체 리빌드
.\build.ps1 -Run     # 빌드 후 실행

setupapi.dll과 hid.dll을 직접 선언해 쓰므로 외부 라이브러리 없이 실행 파일 하나로 배포됩니다.

알아 둘 점

  • 레이어는 지원하지 않습니다. 이 장치가 레이어 전환 명령을 무시하기 때문에 항상 레이어 1만 씁니다.
  • 장치에서 설정을 읽어 올 수 없습니다. 프로파일 파일을 잃으면 그 설정도 잃으니 백업이 필요합니다.
  • [적용]으로 보낸 설정은 휘발성입니다. [장치에 저장]을 눌러야 장치 플래시에 남습니다.
  • 라이선스는 MIT입니다.

소스와 프로토콜 문서는 GitHub 저장소에 있습니다.

함께 읽으면 좋은 글