macroKey 배선 가이드

Pro Micro(ATmega32u4, 5 V / 16 MHz) + 택트 스위치 8개 + WS2812B 1개. 전원은 PC USB 하나뿐입니다. 핀 번호의 유일한 진실 공급원은 firmware/src/Config.h이고, 핀을 바꾸려면 이 문서가 아니라 그 파일을 고칩니다. 사용법은 manual.html을 보세요.

01연결 요약

Pro Micro연결 대상중간에 들어가는 것비고
D3 – D10 택트 스위치 8개의 한쪽 다리없음 내부 풀업 사용, 외부 저항 불필요
A0 WS2812B DIN330 Ω 직렬 저항 Pro Micro에는 D11이 없어 A0를 씁니다
VCC WS2812B 5V100 µF 커패시터(VCC–GND) 5 V 버전 보드여야 함. RAW 아님
GND 스위치 8개 + WS2812B GND없음 모든 GND는 반드시 한 점으로

Pro Micro에는 D11이 없습니다. 칩에는 있지만 보드가 밖으로 빼지 않았습니다. Leonardo용 자료를 따라 하면 존재하지 않는 핀에 배선하게 됩니다. 노출된 핀 중 D2·D3은 SDA/SCL, D14·D15·D16은 SPI라 어느 버스와도 겹치지 않는 A0를 LED 데이터 핀으로 잡았습니다.

버튼만 먼저 만들어도 됩니다. LED가 없어도 펌웨어는 그대로 동작합니다. D3–D10만 배선해 업로드하면 키패드는 바로 쓸 수 있고, WS2812B는 나중에 A0에 붙이면 됩니다.

02핀 맵

USB 커넥터가 왼쪽으로 오게 놓고 부품면을 위에서 본 그림. 버튼용 D3–D9는 아래쪽 줄에 연속으로 있고, 여덟 번째 버튼 D10만 위쪽 줄 맨 끝입니다. LED에 쓸 A0·VCC·GND는 전부 위쪽 줄에 모여 있습니다.

WS2812B 5V ← VCC 공통 GND WS2812B DIN ← A0 버튼 8 ← D10 USB ATmega32u4 Pro Micro 5V / 16MHz RAW GND RST VCC A3 A2 A1 A0 15 14 16 10 TX0 RX1 GND GND 2 3 4 5 6 7 8 9 버튼 1–7 · D3–D9 스위치 공통 GND 버튼 LED 데이터 전원 접지
그림 1 — Pro Micro 상면도와 사용 핀

VCC와 RAW를 헷갈리지 마세요. RAW는 USB VBUS가 그대로 나오는 핀, VCC는 레귤레이터를 거친 5 V 출력입니다. WS2812B는 VCC에 물립니다. 그리고 반드시 5 V / 16 MHz 버전이어야 합니다. 이유는 LED가 아니라 펌웨어입니다 — cpu=16MHzatmega32U4로 빌드되므로 8 MHz 보드에 구우면 클럭이 어긋나 USB가 열거되지 않습니다. LED 쪽은 원칙이 하나입니다: 급전 전압을 보드 로직 전압에 맞춥니다. 이 보드는 둘 다 5 V라 VCC이고, 3.3 V 로직인 RP2040 판은 3V3에 물립니다.

03조립 순서

  1. 공통 GND 레일부터. 브레드보드 GND 열이나 배선재 한 줄을 잡고 Pro Micro의 GND 핀 하나를 물립니다. 스위치 8개와 WS2812B의 GND가 전부 여기로 모입니다. GND가 갈라져 있으면 LED 색이 튀고 원인 찾기가 어렵습니다.
  2. 택트 스위치 8개를 D3–D10에. 한쪽 다리는 핀, 반대쪽은 GND 레일. 내부 풀업을 쓰므로 외부 저항은 필요 없습니다. 4핀 택트 스위치는 대각선으로 마주 보는 두 핀을 쓰세요 — 같은 변의 두 핀은 스위치 안에서 이미 붙어 있어 항상 눌린 상태가 됩니다. 키 번호는 MK_KEY_PINS 배열 순서 = D3이 1번, D10이 8번입니다.
  3. WS2812B를 VCC · GND · A0에. DIN 라인에 330 Ω을 모듈 가까이 직렬로, VCC–GND 사이에 100 µF 전해 커패시터를 극성 맞춰 답니다. 1000 µF는 쓰지 마세요 — 그 값은 전용 어댑터를 쓰는 긴 스트립 기준이고, USB 2.0은 장치 벌크 커패시턴스를 10 µF로 제한해서 돌입 전류로 포트 보호가 걸릴 수 있습니다. 픽셀 1개에는 100 µF면 충분합니다.
  4. 전원 넣기 전 마지막 확인. VCC–GND 단락 여부, 커패시터 극성, DIN이 A0인지, RST–GND에 닿을 점퍼선을 미리 하나 꽂아 뒀는지. 마지막 항목이 잘못된 펌웨어에서 빠져나오는 유일한 길입니다.

04결선도

선을 읽기 쉽게 배치한 논리 결선도입니다. 핀의 실제 물리 위치는 그림 1을 보세요.

Pro Micro ATmega32u4 · 5 V / 16 MHz USB HID USB 공통 GND S1 S2 S3 S4 S5 S6 S7 S8 D3 D4 D5 D6 D7 D8 D9 D10 GND A0 VCC GND 330 Ω ＋ 100 µF WS2812B ×1 DIN 5V GND 버튼 신호 LED 데이터 VCC GND
그림 2 — 전체 결선도 (논리 배치)

05빌드와 업로드

Pro Micro는 arduino:avr 코어에 없습니다. SparkFun 보드 패키지를 먼저 추가합니다.

arduino-cli config add board_manager.additional_urls \
  https://raw.githubusercontent.com/sparkfun/Arduino_Boards/master/IDE_Board_Manager/package_sparkfun_index.json
arduino-cli core update-index
arduino-cli core install SparkFun:avr
arduino-cli lib install "Adafruit NeoPixel"

arduino-cli lib install "Keyboard"
arduino-cli lib install "Mouse"
arduino-cli compile --upload --fqbn SparkFun:avr:promicro:cpu=16MHzatmega32U4 \
  -p /dev/ttyACM0 firmware

보통은 그냥 올라갑니다. arduino-cli도 앱과 같은 1200 bps 터치로 Caterina를 부르므로 손댈 것이 없습니다. 부트로더 모드에서는 포트 번호가 바뀌니 arduino-cli board list나 python -m macrokey ports로 확인하세요.

터치가 통하지 않을 때만 타이밍 싸움이 됩니다. 시리얼 포트를 열지 않는 스케치가 올라가 있거나 매크로가 폭주 중이면 부를 상대가 없습니다. 그때는 RST–GND를 빠르게 두 번 단락시킨 직후에 upload를 실행하세요 — 부트로더는 8초만 떠 있습니다.

Keyboard와 Mouse는 AVR 코어에 없으므로 별도 설치가 필요합니다(위 명령). 배선 확인은 python -m macrokey monitor가 빠릅니다 — 키를 누르면 EV t=key k=0 g=tap 같은 줄이 찍힙니다.

06안 될 때

증상가장 흔한 원인확인/조치
LED가 전혀 안 켜짐DIN이 A0가 아니거나, 모듈을 RAW에 물림MK_LED_PIN이 18인지, 모듈 전원이 VCC인지 확인
색이 엉뚱하거나 깜빡임직렬 저항 없음 또는 GND 미공통330 Ω을 모듈 가까이로, GND를 한 점으로
빨강↔초록이 바뀜모듈 색 순서가 GRB가 아님LedController.h의 NEO_GRB를 NEO_RGB로
전원 인가 때 한 번 번쩍임커패시터 없음100 µF를 VCC–GND 사이에 추가
특정 키가 계속 눌린 상태택트 스위치의 같은 변 두 핀 사용대각선으로 마주 보는 두 핀으로 이동
여덟 번째 키만 반응 없음D10을 아래쪽 줄에서 찾음D10은 위쪽 줄 맨 끝입니다 (그림 1)
업로드가 안 되고 포트가 사라짐매크로가 키를 계속 뿜는 상태RST–GND 빠르게 두 번 단락 → 8초 안에 업로드
키가 씹히거나 보드가 리셋됨USB 케이블 전압 강하1 m 이하 데이터용 케이블로 교체

케이블이 조용한 원인입니다. 길고 얇은 충전 전용 케이블(28 AWG, 2 m 이상)은 보드 쪽 전압을 4.6 V 근처까지 끌어내려 LED 색을 틀어지게 하거나 ATmega32u4를 브라운아웃으로 리셋시킵니다. 원인을 못 찾는 불안정의 상당수가 이겁니다.

07부품 목록

부품수량비고
Pro Micro (ATmega32u4)15 V / 16 MHz 버전. 8 MHz 판은 펌웨어 클럭이 달라 USB가 안 잡힘
6 mm 택트 스위치84핀형이면 대각선 두 핀 사용
WS2812B 모듈15 V 품종. 단품 또는 스트립에서 1픽셀
330 Ω 저항 (1/4 W)1300–500 Ω이면 무방
100 µF 전해 커패시터1정격 6.3 V 이상, 극성 있음
점퍼선 / 배선재—RST–GND용으로 한 가닥 여유 있게
USB 데이터 케이블 (micro-B)11 m 이하 권장. 충전 전용 불가

전력은 실질적인 제약이 아닙니다. 픽셀 1개 흰색 최대 60 mA + MCU 30 mA = 90 mA로 USB 500 mA 예산의 18%입니다. 밝기를 255까지 올려도 안전합니다. 계산 근거와 픽셀 수를 늘릴 때의 상한은 docs/HARDWARE.md에 있습니다.