macroKey 배선 가이드 — RP2040

01연결 요약

납땜할 선은 버튼 8가닥 + GND 1가닥(왼쪽 열)과 LED 3가닥(오른쪽 열)입니다. 32u4 판과 부품 구성은 같지만, 전원을 3V3에서 뽑기 때문에 레벨 시프터가 필요 없다는 점이 다릅니다 — 그 이유는 07절에 있습니다.

02핀 맵

USB-C가 위로 오게 세워 놓고 부품면을 위에서 본 그림. 왼쪽 열 GND·GND 다음의 GP2부터 GP9까지 여덟 칸이 그대로 버튼 1–8입니다. 오른쪽 열은 버튼에 쓰지 않고, 외부 WS2812B가 3V3·GND·GP21 세 자리를 씁니다.

03조립 순서

외부 WS2812B를 3.3 V로 구동하는 구성입니다. LED 없이 키패드만 먼저 만들어도 펌웨어는 그대로 동작하므로, 2·5단계를 나중으로 미뤄도 됩니다.

1. 헤더를 답니다. 버튼용으로 왼쪽 열 12핀, LED용으로 오른쪽 열이 필요합니다. 오른쪽은 3V3·GND·GP21 세 자리뿐이라 잘라 쓰는 헤더로 세 칸만 꽂아도 되지만, 빵판에 세울 거면 12핀을 통째로 다는 편이 보드가 안 흔들립니다.
2. 납땜하기 전에 LED부터 판정합니다. 모듈을 빵판에 임시로 물려 3V3·GND·GP21에 연결하고 07절의 판정 스케치를 올립니다. 빨강·초록·파랑·흰색이 차례로 도는데, 파랑이 아예 안 뜨면 그 모듈은 3.3 V로 못 씁니다 — 다이오드 방식으로 바꿔야 하고 배선이 달라지므로, 확정하고 납땜을 시작하세요. 이 단계가 5분이고 나중에 뜯어내는 것이 30분입니다.
3. 공통 GND 레일부터. 왼쪽 열의 GND 두 칸(GP1과 GP2 사이) 중 하나를 잡고 브레드보드 GND 열이나 배선재 한 줄에 물립니다. 스위치 8개의 반대쪽 다리가 전부 여기로 모입니다. GND가 갈라져 있으면 원인 찾기가 어려워집니다.
4. 택트 스위치 8개를 GP2–GP9에. 한쪽 다리는 핀, 반대쪽은 GND 레일. 내부 풀업을 쓰므로 외부 저항은 필요 없습니다. 4핀 택트 스위치는 대각선으로 마주 보는 두 핀을 쓰세요 — 같은 변의 두 핀은 스위치 안에서 이미 붙어 있어 항상 눌린 상태가 됩니다. 키 번호는 MK_KEY_PINS 배열 순서 = GP2가 1번, GP9가 8번입니다.
5. WS2812B를 오른쪽 열 세 자리에. 배선 세 가닥이 전부입니다(그림 3).
   • 모듈 5V/VCC → 보드 3V3. 5V 핀이 아닙니다 — 여기가 이 조립에서 유일하게 치명적인 지점입니다.
   • 모듈 GND → 보드 오른쪽 열 GND. 버튼 GND와 다른 핀이지만 보드 안에서 같은 네트라 상관없습니다.
   • 모듈 DIN → 330 Ω 직렬 → 보드 GP21. 저항은 모듈 쪽에 붙입니다.
   • 100 µF 전해 커패시터를 모듈 가까이 3V3–GND 사이에. 극성이 있습니다 — 긴 다리가 3V3, 몸통의 흰 띠 쪽이 GND입니다.
6. 펌웨어 핀을 맞춥니다. Config.h에서 MK_LED_PIN을 21로 (05절의 전체 목록에 포함돼 있습니다). GP17은 펌웨어가 아예 건드리지 않으므로 온보드 LED는 그대로 둡니다.
7. 전원 넣기 전 마지막 확인. 모듈 전원이 5V가 아니라 3V3에 물렸는지, 커패시터 극성, 3V3–GND 단락 여부, DIN이 GP21인지, 스위치가 대각선 두 핀인지. RP2040은 BOOT 버튼이 있으므로 32u4처럼 RST–GND 점퍼를 미리 꽂아 둘 필요는 없습니다.

04결선도

선을 읽기 쉽게 배치한 논리 결선도입니다. 핀의 실제 물리 위치는 그림 1을 보세요. 아래는 버튼 쪽만 그린 것으로, 왼쪽 열에서 나가는 버튼 8가닥 + GND 1가닥입니다. LED 3가닥은 오른쪽 열에서 따로 나가며 07절 그림 3에 있습니다.

05펌웨어에서 바꿀 것

0.9.0 펌웨어는 ATmega32U4와 RP2040을 같은 소스에서 빌드합니다. AVR의 기존 1 KB 프로필은 그대로 두고, RP2040 빌드에서만 LittleFS 기반 대용량 프로필을 선택합니다.

firmware/src/Config.h

#define MK_BOARD_NAME "promicro-rp2040"

// 왼쪽 열에 연속으로 있는 여덟 핀. 배열 순서가 키 번호입니다.
static const uint8_t MK_KEY_PINS[MK_KEY_COUNT] = {2, 3, 4, 5, 6, 7, 8, 9};

// 외부 WS2812B 모듈의 DIN. 오른쪽 열 맨 아래 핀입니다.
// GP17의 온보드 LED는 WS2812가 아니라 여기 쓸 수 없습니다(07절).
#define MK_LED_PIN 21

// RP2040은 14 MB LittleFS 파티션에 프로필 파일을 원자적으로 교체합니다.
#define MK_STORAGE_FLASH_EMULATED 1

firmware/src/Storage.h — 빌드가 'class EEPROMClass' has no member named 'update'에서 멈추면(코어에 따라 다릅니다) 플래시 분기에만 래퍼를 넣습니다.

inline void mkStoreUpdate(uint16_t address, uint8_t value) {
#if MK_STORAGE_FLASH_EMULATED
  // 같은 값이면 건드리지 않는다는 update()의 의미는 그대로 유지합니다.
  if (EEPROM.read(address) != value) EEPROM.write(address, value);
#else
  EEPROM.update(address, value);
#endif
}

firmware/src/SerialProtocol.cpp — 시리얼 BOOT 명령이 지금은 ERR code=unsupported를 답합니다. RP2040은 부트롬에 진입 함수가 있어 세 줄이면 됩니다.

#elif defined(ARDUINO_ARCH_RP2040)

#include <pico/bootrom.h>
#define MK_HAS_BOOTLOADER_ENTRY 1
void enterBootloader() { reset_usb_boot(0, 0); }

#else

macrokey/device/discovery.py — 선택 사항입니다. 모르는 벤더의 포트도 어차피 마지막에 시도하므로 안 고쳐도 연결은 됩니다. 다만 자동 연결이 한 번에 붙게 하려면 RP2040의 CDC id를 목록에 넣어 줍니다.

# arduino-pico 코어의 기본 CDC id.
KNOWN_USB_IDS = {
    ...,
    (0x2E8A, 0x000A),
}

firmware.ino의 quietBoardLeds()는 손댈 필요가 없습니다. defined(RXLED0) && defined(TXLED0) 가드가 걸려 있어 RP2040에서는 빈 함수로 컴파일되고, 이 보드에는 애초에 RX/TX LED가 없습니다.

06빌드와 업로드

RP2040은 Earle Philhower의 arduino-pico 코어를 씁니다. SparkFun AVR 패키지와 무관하며, 둘을 같이 설치해 둬도 됩니다.

arduino-cli config add board_manager.additional_urls \
  https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
arduino-cli core update-index
arduino-cli core install rp2040:rp2040
arduino-cli lib install "Adafruit NeoPixel"

arduino-cli compile --upload \
  --fqbn rp2040:rp2040:generic:flash=16777216_14680064,freq=133 \
  -p /dev/ttyACM0 firmware

첫 업로드는 UF2로. 공장 출하 상태에는 시리얼 포트가 없어 -p가 가리킬 대상이 없습니다.

1. BOOT 버튼을 누른 채로 USB를 꽂습니다(또는 BOOT를 누른 채 RESET을 눌렀다 뗍니다).
2. RPI-RP2 이름의 USB 드라이브가 뜹니다.
3. arduino-cli compile --fqbn rp2040:rp2040:generic:flash=16777216_14680064,freq=133 --output-dir build/rp2040-large firmware로 만든 build/rp2040-large/firmware.ino.uf2를 그 드라이브에 복사합니다.
4. 복사가 끝나면 보드가 알아서 재부팅하고 드라이브가 사라집니다.

한 번 올라간 뒤부터는 compile --upload가 그냥 됩니다 — 코어가 1200 bps로 포트를 열었다 닫는 신호를 부트로더 진입으로 받습니다.

배선 확인은 python -m macrokey monitor가 빠릅니다 — 키를 누르면 EV t=key k=0 g=tap 같은 줄이 찍힙니다. python -m macrokey ports로 포트를 먼저 확인하세요.

07WS2812B를 3.3 V로 붙이기

그리고 RP2040은 3.3 V 로직이라 5 V 급전 WS2812B를 그냥 물리면 데이터 레벨이 미달입니다. 그래서 이 절이 있습니다 — 결론은 모듈을 3.3 V로 급전하는 것이고, 근거는 아래와 같습니다.

먼저: 3.3 V로 켜지는가

결론부터 — 켜집니다. 다만 규격 밖이고, 색이 붉게 기웁니다. 근거는 이렇습니다.

실물에서 확인한 구성입니다. ProMicro RP2040 판에 3V3로 급전한 WS2812B 모듈이 정상 동작합니다. 아래는 왜 그런지에 대한 설명이지 추정이 아닙니다.

즉 데이터 레벨 문제는 3V3 급전으로 완전히 해결되고, 대신 밝기와 색균형을 내줍니다. 흰색이 노르스름하거나 분홍으로 보이고 전체가 어두워집니다. 이 프로젝트는 픽셀 1개를 기본 밝기 64/255로 쓰므로 실사용에서는 거의 문제가 되지 않습니다.

어디에 연결하나

버튼이 왼쪽 열을 다 쓰므로 LED는 오른쪽 열에서 전부 해결됩니다. GND와 3V3가 위쪽에 나란히 있고, 데이터는 같은 열 맨 아래 GP21을 씁니다.

데이터 핀은 GP21이 무난합니다. 왼쪽 열은 버튼이 다 쓰고, GP17은 온보드 LED 전용이며, GP0·GP1은 UART입니다. 다른 자리가 필요하면 GP26·GP27·GP28도 됩니다. GP23·GP24·GP25·GP29는 피하세요 — RP2040 보드 설계에 따라 내부 용도(VBUS 감지, 전원 모드, VSYS 분압)가 붙어 있는 자리라서 개체마다 다릅니다. GND는 왼쪽 열 것을 써도 같은 네트라 상관없지만, 오른쪽 열 GND를 쓰면 LED 배선 세 가닥이 한쪽에 모입니다.

납땜 전에 판정하는 스케치

빵판에 임시로 물려 놓고 이것부터 올려 보세요. 펌웨어와 무관한 독립 스케치입니다.

#include <Adafruit_NeoPixel.h>

// 외부 WS2812B가 3.3 V 급전으로 제대로 켜지는지만 보는 스케치.
// 데이터 = GP21, 전원 = 보드의 3V3.
Adafruit_NeoPixel pixel(1, 21, NEO_GRB + NEO_KHZ800);

void flash(uint8_t r, uint8_t g, uint8_t b) {
  pixel.setPixelColor(0, pixel.Color(r, g, b));
  pixel.show();
  delay(900);
}

void setup() {
  pixel.begin();
  pixel.setBrightness(255);  // 판정은 최대 밝기에서. 펌웨어 기본값은 64입니다.
}

void loop() {
  flash(255, 0, 0);      // 빨강
  flash(0, 255, 0);      // 초록
  flash(0, 0, 255);      // 파랑
  flash(255, 255, 255);  // 흰색
  flash(0, 0, 0);        // 꺼짐
}

arduino-cli compile --upload \
  --fqbn rp2040:rp2040:generic:flash=16777216_0 \
  -p /dev/ttyACM0 ledtest

펌웨어에서 바꿀 것

// firmware/src/Config.h
#define MK_LED_PIN 21

05절의 변경 목록에 이미 들어 있습니다. 데이터 핀을 GP21이 아닌 곳으로 잡았다면 그 번호로 맞추세요.

pinMode(17, OUTPUT);
digitalWrite(17, LOW);   // 안 꺼지면 HIGH로

3.3 V로 안 되면

픽셀 수를 늘리면 Config.h의 MK_LED_COUNT와 호스트 macrokey/config/model.py의 LED_COUNT를 같은 값으로 올립니다. EEPROM 팔레트 크기와 MK_LED_MAX_MILLIAMPS 전류 제한은 그 값에서 자동으로 따라옵니다. 3V3 급전으로 몇 개까지 되는지는 08절에 있습니다.

08전력 예산

전원은 PC USB 하나뿐이고 USB 2.0 장치는 500 mA를 넘게 쓸 수 없습니다. 32u4 판보다 MCU가 더 먹지만 LED가 3.3 V로 켜져 덜 먹으므로 총합은 비슷합니다.

근사치입니다. 픽셀이 하나뿐이라 전력은 실질적인 제약이 아니고 밝기를 255로 올려도 안전합니다. MK_LED_MAX_MILLIAMPS(100)는 3.3 V 급전에서 더더욱 걸릴 일이 없지만, MK_LED_COUNT를 올리는 순간 다른 곳을 고치지 않아도 바로 안전장치로 동작하기 때문에 그대로 둡니다.

케이블은 여기서도 조용한 원인입니다. 길고 얇은 충전 전용 케이블은 보드 쪽 전압을 끌어내립니다. 다만 32u4 판만큼 치명적이지는 않습니다 — 3.3 V 레귤레이터는 입력이 4.5 V까지 떨어져도 출력을 유지하므로, 5 V 직결이던 32u4보다 여유가 있습니다. 그래도 1 m 이하 데이터용 USB-C 케이블을 쓰세요. 충전 전용 케이블은 아예 인식되지 않습니다.

0932u4 판과 달라지는 것

10안 될 때

11부품 목록

부품 구성은 32u4 판과 같습니다 — 이 보드의 온보드 RGB LED는 WS2812가 아니라 상태 표시에 쓸 수 없어서, WS2812B 모듈·330 Ω·100 µF가 그대로 필요합니다. 달라지는 것은 모듈을 VCC(5 V)가 아니라 3V3에서 급전한다는 점 하나입니다.