macroKey v0.15.0 - 8버튼 매크로 키패드

maduinos 9월 05, 2026
01_macrokey_v0.15.0

macroKey

Written by maduinos
Rev. 앱 0.15.0 / 펌웨어 0.9.4

macroKey v0.15.0 — 8버튼 매크로 키패드

망가진 키보드에서 뽑은 체리 MX 스위치 8개로 만든 매크로 키패드입니다.
핵심은 하나입니다 — 패드는 PC 프로그램 없이 혼자 동작합니다. USB로 꽂으면 그냥
키보드/마우스이고, 매크로는 패드 안에 저장돼 있습니다. 설정 앱은 녹음하고 설정할 때만
켭니다.

  • 8개 버튼 각각에 단축키 또는 녹음한 매크로
  • 버튼을 3초 홀드하면 녹음 시작
  • 마우스 이동·클릭·드래그·휠까지 녹음
  • WS2812B LED가 상태를 알려줌 — 녹음 중 빨강, 재생 중 시안, 끝나면 초록 한 번
  • 한국어·영어

만드는 순서는 ① 하드웨어 → ② 앱 다운로드 → ③ 녹음 셋입니다.
펌웨어는 앱이 알아서 굽기 때문에 arduino-cli도, 코어 설치도, 라이브러리도 필요 없습니다.

1. 하드웨어 만들기

케이스가 설계를 정했습니다

케이스는 Thingiverse의
Stream Cheap (Mini Macro Keyboard)
(DaveM, CC BY-SA)를 그대로 3D 프린트해서 씁니다. 체리 MX 스위치 4×2 = 8키 배열이고,
macroKey가 8버튼인 이유가 바로 이겁니다.

파일 용도
StreamCheap_Base.stl 아래 몸통 — 보드가 들어갑니다
StreamCheap_Faceplate.stl 스위치 8개를 잡아 주는 윗판
StreamCheap_Icons.pdf 투명 키캡에 끼울 아이콘 — 인쇄해서 잘라 넣습니다

체리 MX용 투명(relegendable) 키캡을 쓰면 인쇄한 아이콘을 키캡 안에 넣을 수 있습니다.
어떤 키가 무슨 매크로인지 한눈에 보이는 게 이 케이스의 핵심입니다.

케이스에 StreamCheap.ino가 같이 들어 있는데 쓰지 마세요. 원작자의 별개 펌웨어이고,
macroKey 펌웨어는 설정 앱이 알아서 굽습니다.

보드 고르기

**기본은 Pro Micro(ATmega32u4)**입니다 — SparkFun 설계이고, 같은 배열의 클론도 그대로
씁니다. 큰 매크로를 많이 넣고 싶을 때 쓰는 확장 선택지로 ProMicro RP2040을 지원하고,
둘은 같은 펌웨어 소스로 돕니다.

보드 저장소 매크로 용량 첫 플래싱
Pro Micro (ATmega32u4) — 기본 1 KB EEPROM 308 레코드 앱이 알아서 (손댈 것 없음)
ProMicro RP2040 (16 MB) — 확장 65,520 B LittleFS 21,801 레코드 첫 1회만 BOOTSEL

Pro Micro를 쓴다면 5 V / 16 MHz 버전이어야 합니다. 펌웨어가 16 MHz로 빌드되어 있어서
8 MHz 판에 구우면 클럭이 어긋나 USB가 아예 열거되지 않습니다. LED 전압 문제가 아니라
펌웨어 문제라서, 이건 우회할 방법이 없습니다.

용량 차이는 70배지만 단축키 몇 개와 짧은 매크로면 Pro Micro로 충분합니다.
긴 마우스 매크로를 여러 개 넣을 생각일 때만 RP2040을 고르세요.

준비물

  • 보드 1개 (위에서 고른 것)
  • 체리 MX 스위치 8개 — 저는 망가진 키보드에서 뽑은 것을 썼습니다. 스위치 하나 사려고
    돈 쓸 일이 아니고, 버리는 키보드 하나면 8개는 충분히 나옵니다
  • 투명 키캡 8개 + 인쇄한 아이콘
  • 3D 프린트한 케이스 (Base + Faceplate)
  • WS2812B(NeoPixel) 1픽셀 모듈 1개
  • 330~470 Ω 저항 1개 (LED 데이터 라인용)
  • 100 µF 전해 커패시터 1개
  • 1 m 이하 데이터용 USB 케이블

배선

버튼은 한쪽을 신호 핀에, 반대쪽을 GND에 연결합니다. 마이크로컨트롤러의 내부 풀업을
쓰기 때문에 외부 저항은 필요 없습니다. 체리 MX 스위치는 접점이 두 개뿐이라 방향도
상관없습니다.

연결 Pro Micro (5 V 로직) ProMicro RP2040 (3.3 V 로직)
버튼 1~8 D3 ~ D9 + D10 GP2 ~ GP9
버튼 반대쪽 GND GND
WS2812B DIN A0 (330 Ω 직렬 저항 경유) GP21 (330 Ω 직렬 저항 경유)
WS2812B VDD VCC = 5 V 3V3 = 3.3 V
WS2812B GND GND (버튼과 공통) GND (버튼과 공통)

100 µF 커패시터는 LED 모듈 가까이에서 급전 핀–GND 사이에 답니다.

LED 급전 전압은 보드 로직 전압에 맞춥니다

두 보드에서 LED 전원이 다른 게 오타가 아닙니다.

먼저 규격 이야기부터 하면, WS2812B는 5 V 부품입니다 — 데이터시트의 VDD는
3.5~5.3 V이고 3.3 V는 그 아래입니다. 그런데 RP2040 판에 3.3 V로 물려 보니 그냥
동작했습니다. 규격 밖이라 보증할 수는 없고 5 V 때보다 어둡습니다만, 실제로 됩니다.

그리고 이 보드에서는 3.3 V가 오히려 안전한 선택입니다. WS2812B의 입력 하이 임계가
0.7 × VDD — 즉 급전 전압이 데이터 임계를 정하기 때문입니다.

LED 급전 데이터 임계 3.3 V 로직(RP2040)으로
3.3 V 2.31 V 여유 충분
5 V 3.50 V 미달

모듈만 5 V(RAW)에 물리면 임계가 3.50 V로 올라가 RP2040의 3.3 V 신호로는 모자랍니다.
아예 안 되면 차라리 낫습니다 — 되다 안 되다 하는 가장 나쁜 형태로 나타납니다.
파랑이 유독 약하거나 아예 안 뜨는 모듈이면 배선 가이드 07절의 대안을 보세요.

Pro Micro는 로직이 5 V라 규격대로 VCC(5 V)에 물리면 됩니다.

배선하기 전에 알아야 할 것 넷

① Pro Micro의 8번 버튼만 반대쪽 줄에 있습니다.
버튼 1~7은 아래쪽 줄 D3~D9인데, 8번(D10)만 위쪽 줄 맨 끝입니다. 배선이 한쪽으로
정리되지 않는 유일한 선이니 미리 알고 시작하세요.

② Pro Micro에는 D11이 없습니다.
ATmega32u4 칩에는 D11·D12·D13이 있지만 Pro Micro 보드는 그 핀을 밖으로 빼지 않습니다.
Leonardo용 자료를 그대로 따라 하면 존재하지 않는 핀에 배선하게 됩니다.
LED 데이터 핀으로 A0를 고른 이유도 이겁니다 — D2/D3은 I2C, D14/D15/D16은 SPI라서,
어느 버스와도 겹치지 않고 VCC·GND와 같은 쪽 헤더에 있는 핀이 A0입니다.

③ Pro Micro에서 VCC와 RAW를 구분하세요.
RAW는 USB VBUS가 그대로 나오는 핀이고, VCC는 레귤레이터를 거친 5 V 출력입니다.
이 보드의 WS2812B는 **VCC**에 물립니다. (RP2040은 3V3입니다 — 바로 위 절 참고.)

④ RP2040은 보드에 달린 LED가 아닙니다.
macroKey가 쓰는 것은 GP21에 외부로 연결하는 모듈입니다. 온보드 LED는 보드마다 핀도
종류도 달라서 — 제네릭 클론은 GP17에 WS2812가 아닌 RGB LED, SparkFun 판은 GP25에 WS2812 —
펌웨어가 어느 쪽도 건드리지 않습니다. 온보드 쪽에 배선하면 아무 반응도 없습니다.

커패시터는 100 µF, 1000 µF 아닙니다

WS2812B 자료에서 흔히 보이는 1000 µF는 긴 스트립에 전용 어댑터를 다는 경우의
권장값입니다. 이 프로젝트는 픽셀 하나를 PC USB로만 급전합니다.
USB 2.0 규격은 장치의 벌크 커패시턴스를 10 µF로 제한하고, 실제 포트는 수백 µF까지
견디지만 큰 용량은 돌입 전류로 포트 보호를 걸어 "USB 장치를 인식할 수 없음"이 되는
원인이 됩니다. 픽셀 1개에는 100 µF면 충분합니다.

전력은 사실상 걱정거리가 아닙니다. 픽셀 1개 흰색 100% + MCU가 약 90 mA로,
USB 2.0 예산 500 mA의 18%입니다. 밝기를 최대로 올려도 안전합니다.

케이블이 조용한 원인입니다

길고 얇은 충전 전용 케이블(28 AWG, 2 m 이상)은 보드 쪽 전압을 4.6 V 근처까지 끌어내려
LED 색이 틀어지거나 MCU가 브라운아웃으로 리셋되게 만듭니다.
1 m 이하 데이터용 케이블을 쓰세요. 그리고 USB 허브에 물리지 말고 메인보드 직결
포트에 꽂으세요 — 허브에서는 첫 열거부터 실패하는 경우가 있습니다.

Pro Micro라면: RST 점퍼선을 미리 꽂아 두세요

Pro Micro에는 리셋 버튼이 없습니다. 첫 설치 때문이 아닙니다 — 그건 앱이 알아서 합니다.
매크로가 잘못돼 키를 무한히 뿜는 펌웨어에서 빠져나오는 유일한 길이 RST–GND를 빠르게
두 번 단락시켜 부트로더를 띄우는 것이라서입니다. 배선할 때 RST와 GND에 닿을 수 있는
점퍼선을 하나 미리 꽂아 두세요.

그림 배선도

핀 위치, 버튼 1개 상세, 전체 결선도, 전력 예산이 들어간 그림 배선도를 따로 만들어 뒀습니다.
브라우저에서 바로 열리고, 인쇄해서 작업대에 두고 쓰시라고 만든 것입니다.

2. 앱 받기

GitHub Releases v0.15.0에서
내려받습니다. 설치 과정도, Python도 필요 없습니다.

파일 용도
macrokey-windows-x86_64.exe Windows 설정 앱 — 받아서 실행
macrokey-linux-x86_64 Linux 설정 앱 — chmod +x 후 실행
firmware-promicro.hex Pro Micro 펌웨어 (앱 안에 이미 들어 있음)
firmware-promicro-rp2040.uf2 RP2040 펌웨어 (앱 안에 이미 들어 있음)
SHA256SUMS.txt 무결성 확인용 해시

펌웨어 파일은 따로 받을 필요가 없습니다. 앱 실행 파일 안에 이미 들어 있어서 앱이
알아서 굽습니다. 참고용으로 올려둔 것입니다.

Ubuntu에서 앱이 패드를 못 찾으면 계정을 dialout 그룹에 넣고 로그아웃했다가 다시
로그인하세요. 키보드·마우스로 쓰기만 할 때는 필요 없고, 설정 앱이 패드와 통신할 때만
필요합니다.

sudo usermod -aG dialout "$USER"

Wayland에서 녹음이 안 되면 첫 실행 안내에 따라 input 권한을 한 번 허용하세요.
이 권한은 계정의 프로그램이 비밀번호를 포함한 모든 키보드·마우스 입력을 읽을 수 있는
강한 권한입니다. macroKey는 빨간 녹화 표시가 켜진 동안에만 입력 장치를 엽니다.

3. 펌웨어 — 앱이 알아서 굽습니다

패드를 USB로 꽂고 앱을 켜면 됩니다. 앱이 어떤 보드인지 알아보고, macroKey 펌웨어가
없거나 낡았으면 확인을 한 번 받은 뒤 직접 설치합니다. arduino-cli도, 코어도, 라이브러리도
필요 없습니다.

보드 첫 플래싱에 필요한 동작
Pro Micro (ATmega32u4) 없습니다. 꽂고 앱을 켜면 끝입니다
ProMicro RP2040 BOOTSEL 버튼을 누른 채로 USB를 꽂습니다 — 첫 한 번만

Pro Micro는 그냥 됩니다. 공장 상태로 스케치가 없으면 Caterina 부트로더가 그대로 떠
있어서 앱이 알아보고 바로 굽고, 스케치가 들어 있어도 앱이 1200 bps 터치로 Caterina에
넣습니다. RST–GND 더블탭은 첫 설치용이 아닙니다 — USB가 죽은 펌웨어에서 빠져나오는
복구용입니다.

ProMicro RP2040만 첫 한 번 BOOTSEL이 필요합니다. 공장에서 들어 있는 데모 펌웨어가
시리얼 포트를 열지 않아서, "부트로더로 가라"고 부탁할 상대가 없기 때문입니다. BOOTSEL을
누른 채 꽂아 RPI-RP2 드라이브를 띄우면 앱이 그 드라이브를 알아보고 즉시 .uf2를
복사합니다. macroKey 펌웨어가 한 번 올라간 뒤로는 이쪽도 완전 자동입니다 — 앱이 BOOT
명령이나 1200 bps 터치로 직접 부트로더에 넣습니다.

4. 쓰는 법

  1. 앱 실행 → 패드 연결
  2. 키 칸에 단축키를 넣거나, 패드 키를 3초 홀드해서 녹음
  3. 같은 키를 다시 3초 홀드하면 저장
    (더블 슬롯 녹화는 탭한 뒤 250 ms 안에 다시 눌러 홀드)
  4. 앱 종료 — 패드는 HID로 계속 동작

매크로 재생 중에는 픽셀이 시안으로 맥동하고, 끝나면 초록으로 한 번 깜빡입니다.

마우스 녹화는 기본적으로 현재 포인터 기준입니다. 클릭은 현재 위치에서, 이동·드래그는
현재 위치로부터 상대적으로 재생됩니다. 화면의 같은 자리를 꼭 눌러야 할 때만 실험 기능인
Fixed screen을 켜세요. 모니터 배치·배율·창 위치가 바뀌면 고정 위치 매크로는 어긋납니다.

포인터 가속을 끄면 마우스 매크로가 녹화된 위치에 더 정확히 떨어집니다. 앱이 한 번
물어보고, 승낙하면 데스크톱 설정을 영구적으로 바꿉니다 — Linux는 GNOME accel-profile,
Windows는 "포인터 정확도 향상"입니다. 되돌리는 방법은 그 대화상자가 알려줍니다.

앱 화면 하나하나에 대한 설명은
사용 설명서에 있습니다.

Windows 11에서 작업 표시줄 아이콘을 클릭하는 매크로를 만든다면, 먼저
**설정 > 개인 설정 > 작업 표시줄 > 작업 표시줄 동작 > 작업 표시줄 맞춤을 “왼쪽”**으로
바꾸고 겨냥할 앱을 고정하세요. 기본값인 가운데 정렬에서는 앱이 하나 열릴 때마다 아이콘이
전부 옆으로 밀립니다 — macroKey를 켜는 것 자체가 그 하나여서, 매크로가 이웃 아이콘을
누르게 됩니다.

5. 업데이트

앱과 펌웨어는 스스로 최신을 따라갑니다. 앱은 시작할 때 GitHub 릴리스를 한 번 확인해
새 버전이 있으면 내려받아 설치하고(적용은 다음 실행), 패드를 연결할 때마다 패드의 펌웨어가
앱이 가진 것보다 낮으면 그 자리에서 올려 씁니다.

이 조합이 중요한 이유는 하나입니다 — 프로필 레이아웃은 앱과 펌웨어가 같은 스키마로
합의해야 하고, 한쪽만 뒤처지면 조용히 어긋납니다.

받은 파일은 릴리스가 함께 올린 SHA256SUMS.txt와 대조한 뒤에만 씁니다. 해시가 없거나
맞지 않으면 아무것도 남기지 않습니다.

보드별 펌웨어 이미지가 앱 실행 파일 안에 들어 있어서 펌웨어 업데이트는 보통 오프라인에서
끝납니다. 네트워크는 새 앱을 가져올 때만 씁니다.

자동 업데이트는 도움말 > 업데이트 확인에서 직접 확인하거나 끌 수 있습니다.
MACROKEY_NO_UPDATE=1 환경변수는 앱 전체의 네트워크 확인을 막습니다.

6. 이번 버전에서 한 일 (v0.15.0)

키 편집 창이 단축키 하나만 묻습니다. "키 입력받기"는 이제 우분투 설정처럼 실제
키보드를 직접 잡아서 읽습니다. 펌웨어는 그대로입니다(0.9.4) — 다시 flash할 필요
없습니다.

"키 입력받기"가 커널에서 키를 직접 읽습니다.
예전에는 Qt가 이 창에 넣어주는 키만 받았습니다. 데스크톱이 먼저 가져가는 키 — super,
alt+tab, print, 미디어키 — 는 창까지 오지 않으니 누를 수가 없었습니다. 이제 녹음기가
쓰던 입력 노드(/dev/input/event*)를 같은 방식으로 읽습니다.

받는 동안에는 키보드를 독점합니다(EVIOCGRAB). 그래서 (1) 데스크톱이 그 조합을
가져가지 않고, (2) 지금 그 조합에 걸려 있는 동작이 같이 실행되지도 않습니다. 커널이 주는
것은 레이아웃을 적용하기 전의 물리 키라 shift+1이 !가 아니라 shift+1로 저장됩니다.
F13~F24, PrtSc, 메뉴키까지 전부 같은 방식으로 들어옵니다.

키보드를 뺏는 기능이라 빠져나갈 길을 여러 개 뒀습니다: 수식키가 아닌 키를 처음 누르면
종료, 창을 닫으면 종료, 30초 동안 아무 키도 없으면 종료.

패드가 보낼 수 없는 키는 삼키지 않고 이유를 말합니다.
노트북 Fn, 한/영·한자, 미디어키처럼 코드가 없는 키는 칸에 그대로 채운 뒤 "이 키패드는
보낼 수 없습니다"라고 알려줍니다. 아무 일도 일어나지 않아 키 입력을 놓친 것처럼 보이던
것보다 낫습니다.

PrtSc·메뉴키가 녹음에서도 살아납니다.
커널이 KEY_SYSRQ·KEY_COMPOSE로 보고하던 것을 printscreen·menu로 매핑했습니다.

키 편집 창에서 중복 녹음 체크박스를 뺐습니다.
메인 창 Recording 줄에 있는 것과 같은 설정의 복사본이었습니다.

수식키 표기 순서를 저장 형식과 통일했습니다.
직접 입력하든, 키보드에서 읽든, 패드에서 되읽든 ctrl+alt+shift+1 하나로 읽힙니다.

이전 버전은 마우스 매크로가 짧게 떨어지는 문제(0.14.x)와 앱 아이콘·Windows Git Bash
빌드(0.13.0)를 다뤘습니다. 전체 기록은
CHANGELOG.md에 있습니다.

7. 라이선스와 소스

macroKey 자체 코드는 MIT 라이선스입니다
(LICENSE).

배포하는 실행 파일과 펌웨어에는 LGPL 코드(Qt/PySide6, pynput, Adafruit_NeoPixel, Arduino
코어)가 함께 들어갑니다. 어떤 라이브러리가 들어가는지, 조건이 무엇인지, 어떻게 교체하는지는
THIRD_PARTY_NOTICES.md에
적어 뒀습니다. 소스로만 쓰면 전부 MIT입니다.

케이스는 제 것이 아닙니다 — Thingiverse 사용자 DaveM의
Stream Cheap (Mini Macro Keyboard)이고
CC BY-SA입니다.

보드 지원 요청이나 문제는 댓글로 남겨 주세요.

maduinos

작성자: maduinos

Founder of Maduinos, specializing in FPGA education and embedded systems. Passionate about innovation and growth in advanced hardware technology.

댓글 쓰기

0 댓글