2026년 8월 11일 (화) 00:44 기준 최신판

5x5 매크로 키보드 만들기 (3D 프린터 ,NRF52840칩, ZMK)

준비물

SuperMini NRF52840
5×5 보드판(3d 프린팅)
키캡 , 기계식 키보드 체리식 키 클론(알리익프레스)
저항 다이오드

gpio 핀 할당 (5 Row + 5 Col = 10핀)

SuperMini 핀이 넉넉하게 남아서 여유 있게 배치 가능합니다.

납땜 핀 번호 (보드 실크스크린 기준)

| 용도 | 보드 라벨 | nRF52840 핀 |
|------|---------|------------|
| Row 0 | **011** | P0.11 |
| Row 1 | **013** | P0.13 |
| Row 2 | **015** | P0.15 |
| Row 3 | **017** | P0.17 |
| Row 4 | **020** | P0.20 |
| Col 0 | **022** | P0.22 |
| Col 1 | **024** | P0.24 |
| Col 2 | **100** | P1.00 |
| Col 3 | **011** | P1.11 |
| Col 4 | **113** | P1.13 |

⚠️ Row/Col 핀이 보드 라벨과 혼동되지 않도록 아래 다이어그램 참고

보드 핀 다이어그램

        
 
         USB-C
    ┌─────────────┐
B-  │ o         o │ B+
006 │ o         o │ RAW
008 │ o         o │ GND
GND │ o         o │ RST
020 │ o [Row 4] o │ VCC
022 │ o [Col 0] o │ 031
024 │ o [Col 1] o │ 029
100 │ o [Col 2] o │ 002
011 │ o [Row 0] o │ 115
104 │ o         o │ 113 [Col 4]
106 │ o         o │ 111 [Col 3]
009 │ o         o │ 010
008 │ o         o │ 106
    └─────────────┘

※ Row 1~3 핀: 별도 연결 필요
Row 1 → 013 (P0.13)
Row 2 → 015 (P0.15)  
Row 3 → 017 (P0.17)

보드 핀 다이어그램

SuperMini NRF52840

        
         		USB-C
    		┌─────────────┐
		B-  │ o         o │ B+
[Row 0] 006 │ o         o │ RAW
[Row 1]	008 │ o         o │ GND
		GND │ o         o │ RST
		GND	│ o 	    o │ VCC(3.5V)
[Row 1]	017 │ o 	    o │ 031
[Col 0]	020 │ o 	    o │ 029
[Col 1]	022 │ o 	    o │ 002
[Col 2]	024 │ o 	    o │ 115
[Col 3]	100 │ o 	    o │ 113
[Col 4]	011 │ o         o │ 111 
		104 │ o         o │ 010 [Row 3]
		106 │ o         o │ 009 [Row 2]
			└─────────────┘
<뒷면>
   o o o
107 102 101

✅ 확정 핀 할당 (SuperMini 실제 사용 가능 핀 기준)

| 용도 | 보드 라벨 | GPIO |
|------|---------|------|
| **Row 0** | 006 | P0.06 |
| **Row 1** | 008 | P0.08 |
| **Row 2** | 009 | P0.09 |
| **Row 3** | 010 | P0.10 |
| **Row 4** | 017 | P0.17 |
| **Col 0** | 020 | P0.20 |
| **Col 1** | 022 | P0.22 |
| **Col 2** | 024 | P0.24 |
| **Col 3** | 100 | P1.00 |
| **Col 4** | 011 | P0.11 |

배선도

스위치 매트릭스 (다이오드 col2row 방향)

        Col0  Col1  Col2  Col3  Col4
        (020) (022) (024) (100) (011)
          │     │     │     │     │
Row0(006)─┼─[K00]┼─[K01]┼─[K02]┼─[K03]┼─[K04]
          │     │     │     │     │
Row1(008)─┼─[K10]┼─[K11]┼─[K12]┼─[K13]┼─[K14]
          │     │     │     │     │
Row2(009)─┼─[K20]┼─[K21]┼─[K22]┼─[K23]┼─[K24]
          │     │     │     │     │
Row3(010)─┼─[K30]┼─[K31]┼─[K32]┼─[K33]┼─[K34]
          │     │     │     │     │
Row4(017)─┼─[K40]┼─[K41]┼─[K42]┼─[K43]┼─[K44]

각 스위치에 다이오드(1N4148) 직렬 연결
캐소드(띠) → Col 방향

ZMK 펌웨어 파일 구성

. ZMK 공식 템플릿으로 저장소 생성
- https://github.com/zmkfirmware/unified-zmk-config-template 접속 (또는 zmk-config-split 템플릿)
- Use this template → Create a new repository 클릭
- 저장소 이름 지정 (예: zmk-config-fn5x5), Public/Private 선택 후 생성
이 템플릿에는 config/west.yml(ZMK 소스를 가져오는 설정)과 .github/workflows/build.yml(빌드 워크플로우)이 이미 포함되어 있어서, 여기에 우리가 만든 shield 파일만 얹으면 됩니다.

📁 폴더 구조


zmk-config/
├── config/
│    └── west.yml
├── boards/shields/fn25key/
│   ├── fn25key.conf
│   ├── fn25key.keymap
│   ├── fn25key.overlay
│   ├── Kconfig.defconfig
│   └── Kconfig.shield
├── zephyr/
│    └── module.yml
└── build.yaml

1️⃣ `fn25key.overlay`

boards\shields\fn25key.overlay

/*
 * FN5x5 - 5x5 macropad (F-keys / Numbers / Arrows)
 * Super Mini nRF52840 대상
 *
 * ★★★ row-gpios / col-gpios 는 실제 배선한 핀으로 반드시 수정하세요 ★★★
 * Super Mini nRF52840 보드는 판매처마다 실크스크린 핀 번호가 다를 수 있어
 * 여기서는 nRF52840 SoC의 실제 GPIO 포트/핀(P0.xx, P1.xx) 기준으로 작성했습니다.
 * 보드 실크스크린에 적힌 핀이 SoC의 몇 번 GPIO인지 판매처 핀맵 문서를 참고해서
 * 아래 표를 갈아끼우면 됩니다.
 *
 * 예시 배선 (직접 수정):
 *  ROW0~4 : P0.31, P0.29, P0.02, P0.03, P0.28   (5핀)
 *  COL0~4 : P0.04, P0.05, P1.11, P1.15, P0.20   (5핀)
 *  diode  : row -> col 방향 (diode-direction = "col2row")
 */

#include <dt-bindings/zmk/matrix_transform.h>
#include <dt-bindings/gpio/gpio.h>

/ {
    chosen {
        zmk,kscan = &kscan0;
        zmk,matrix_transform = &default_transform;
    };

    default_transform: keymap_transform_0 {
        compatible = "zmk,matrix-transform";
        columns = <5>;
        rows = <5>;

        map = <
RC(0,0) RC(0,1) RC(0,2) RC(0,3) RC(0,4)
RC(1,0) RC(1,1) RC(1,2) RC(1,3) RC(1,4)
RC(2,0) RC(2,1) RC(2,2) RC(2,3) RC(2,4)
RC(3,0) RC(3,1) RC(3,2) RC(3,3) RC(3,4)
RC(4,0) RC(4,1) RC(4,2) RC(4,3) RC(4,4)
        >;
    };

    kscan0: kscan {
        compatible = "zmk,kscan-gpio-matrix";
        diode-direction = "col2row";

        // ROW 0~4 : 실제 배선한 핀 번호로 수정
        row-gpios
            = <&gpio0 6 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
            , <&gpio0 8 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
            , <&gpio0 9 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
            , <&gpio0 10 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
            , <&gpio0 17 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
            ;

        // COL 0~4 : 실제 배선한 핀 번호로 수정
        col-gpios
            = <&gpio0 20  GPIO_ACTIVE_HIGH>
            , <&gpio0 22  GPIO_ACTIVE_HIGH>
            , <&gpio0 24 GPIO_ACTIVE_HIGH>
            , <&gpio1 00 GPIO_ACTIVE_HIGH>
            , <&gpio0 11 GPIO_ACTIVE_HIGH>
            ;
    };
};

2️⃣ `fn25key.keymap`

boards\shields\fn25key.keymap

/*
 * FN5x5 keymap
 *
 * Layer 0 (기본)
 *  F1    F2    F3    F4    F5
 *  F6    F7    F8    F9    F10
 *  1     2     3     4     5
 *  6     7     8     9     0
 *  MO1   LEFT  UP    DOWN  RIGHT
 *
 * Layer 1 (좌하단 MO1 누르고 있을 때)
 *  F11   F12   ___   ___   ___
 *  ___   ___   ___   ___   ___
 *  ___   ___   ___   ___   ___
 *  ___   ___   ___   ___   ___
 *  ___   HOME  PG_UP PG_DN END
 */

#include <behaviors.dtsi>
#include <dt-bindings/zmk/keys.h>
#include <dt-bindings/zmk/bt.h>

/ {
    keymap {
        compatible = "zmk,keymap";

        default_layer {
            bindings = <
&kp F1    &kp F2    &kp F3    &kp F4    &kp F5
&kp F6    &kp F7    &kp F8    &kp F9    &kp F10
&kp N1    &kp N2    &kp N3    &kp N4    &kp N5
&kp N6    &kp N7    &kp N8    &kp N9    &kp N0
&mo 1     &kp LEFT  &kp UP    &kp DOWN  &kp RIGHT
            >;
        };

        extra_layer {
            bindings = <
&kp F11   &kp F12   &trans    &trans    &trans
&trans    &trans    &trans    &trans    &trans
&trans    &trans    &trans    &trans    &trans
&trans    &trans    &trans    &trans    &trans
&trans    &kp HOME  &kp PG_UP &kp PG_DN &kp END
            >;
        };
    };
};

3️⃣ `fn25key.conf`

boards\shields\fn25key.conf

# FN5x5 기본 설정

# 매크로패드 단독 동작 (좌/우 분리 아님)
CONFIG_ZMK_SPLIT=n

# 배터리 게이지가 없는 Super Mini 보드라면 아래 옵션을 n 으로
CONFIG_ZMK_BATTERY_REPORTING=n

# USB 유선 사용 위주라면 BLE 끄고 유선만 써도 됨 (필요시 주석 해제)
# CONFIG_ZMK_BLE=n

# 사용하지 않을 때 자동 절전 (BLE 무선 사용 시)
CONFIG_ZMK_IDLE_SLEEP_TIMEOUT=1800000
CONFIG_ZMK_IDLE_TIMEOUT=30000

# 마지막 눌린 키가 남아있는 것 방지 (매트릭스 안정화)
CONFIG_ZMK_KSCAN_DEBOUNCE_PRESS_MS=5
CONFIG_ZMK_KSCAN_DEBOUNCE_RELEASE_MS=5

4️⃣ `Kconfig.shield`

boards\shields\Kconfig.shield

config SHIELD_FN5X5
    def_bool $(shields_list_contains,fn5x5)

5️⃣ `Kconfig.defconfig`

boards\shields\Kconfig.defconfig

if SHIELD_FN5X5

config ZMK_KEYBOARD_NAME
    default "FN5x5"

endif # SHIELD_FN5X5

---

6️⃣ `build.yml`

/build.yml

# This file generates the GitHub Actions matrix.
# For simple board + shield combinations, add them to the top level board and
# shield arrays, for more control, add individual board + shield combinations
# to the `include` property. You can also use the `cmake-args` property to
# pass flags to the build command, `snippet` to add a Zephyr snippet, and
# `artifact-name` to assign a name to distinguish build outputs from each other:
#
# board: [ "nice_nano" ]
# shield: [ "corne_left", "corne_right" ]
# include:
#   - board: bdn9_rev2
#   - board: nice_nano
#     shield: reviung41
#   - board: nice_nano
#     shield: corne_left
#     snippet: studio-rpc-usb-uart
#     cmake-args: -DCONFIG_ZMK_STUDIO=y
#     artifact-name: corne_left_with_studio
#
---
include:
  - board: nice_nano_v2
    shield: fn25key

config/west.yml , zephyr/module.yml 은 수정하지 않고 템플릿 그대로 사용한다.

펌웨어 컴파일

github 에 등록하기

git add .
git commit -m "Add fn25key macropad shield"
git push origin main

github 에서 컴파일 작업

GitHub 저장소 페이지 → Actions 탭
push 직후 워크플로우가 자동 실행됨 (초록 체크 = 성공, 빨간 X = 실패)
실패 시 로그 클릭해서 에러 확인 (대부분 devicetree 문법 오류나 핀 중복 사용)

.uf2 파일 다운로드

성공한 워크플로우 실행 클릭
하단 Artifacts 섹션에서 firmware 다운로드 (zip 안에 fn25key.uf2 등이 들어있음)

보드에 플래싱

Super Mini nRF52840 리셋 버튼 2번 빠르게 눌러 부트로더 모드 진입 → PC에 USB 드라이브(XIAO-SENSE 등)로 인식됨
다운로드한 .uf2 파일을 그 드라이브에 드래그 앤 드롭
자동으로 리부트되며 새 펌웨어로 동작 시작

납땜 순서 요약


1. 다이오드(1N4148) 25개 → 각 스위치 위치에 납땜
   캐소드(띠쪽) → Col 방향

2. 스위치 25개 → PCB 또는 수납땜

3. Row 배선 (수평)
   Row0: 006핀 → 1행 스위치 5개 연결
   Row1: 008핀 → 2행 스위치 5개 연결
   Row2: 009핀 → 3행 스위치 5개 연결
   Row3: 010핀 → 4행 스위치 5개 연결
   Row4: 017핀 → 5행 스위치 5개 연결

4. Col 배선 (수직)
   Col0: 020핀 → 1열 스위치 5개 연결
   Col1: 022핀 → 2열 스위치 5개 연결
   Col2: 024핀 → 3열 스위치 5개 연결
   Col3: 100핀 → 4열 스위치 5개 연결
   Col4: 011핀 → 5열 스위치 5개 연결

5. SuperMini USB-C → PC 연결 후 펌웨어 플래시

---

키 배치 커스터마이징 팁


| 위치 | 추천 매크로 |
|------|-----------|
| R0C0 | `SELECT * FROM` |
| R0C1 | `COMMIT` |
| R0C2 | `ROLLBACK` |
| R0C3 | `EXPLAIN PLAN FOR` |
| R0C4 | `ALTER SESSION SET` |
| R1C0 | `print()` |
| R1C1 | `def func():` |
| R1C2 | `import cx_Oracle` |
| R4C3 | Layer 1 (Oracle 심화) |
| R4C4 | Layer 2 (BT/시스템) |

로컬 빌드(west)로 하고 싶다면

클라우드 빌드가 막힐 경우를 위해 로컬 빌드도 가능합니다.

pip install west --break-system-packages
west init -l config
west update
west zephyr-export
west build -p -b seeeduino_xiao_ble -- -DSHIELD=fn5x5

결과물은 build/zephyr/zmk.uf2에 생성됩니다.
- Zephyr SDK(nRF 툴체인) 설치가 선행되어야 해서, 처음이라면 GitHub Actions 방식 추천.

@@ 279번째 줄: / 279번째 줄: @@
 === 3️⃣ `fn25key.conf` ===
+boards\shields\fn25key.conf
 <source lang=bash>
 # FN5x5 기본 설정
@@ 303번째 줄: / 304번째 줄: @@
 === 4️⃣ `Kconfig.shield` ===
+boards\shields\Kconfig.shield
 <source lang=bash>
 config SHIELD_FN5X5
@@ 312번째 줄: / 315번째 줄: @@
 === 5️⃣ `Kconfig.defconfig` ===
+boards\shields\Kconfig.defconfig
 <source lang=bash>
 if SHIELD_FN5X5
@@ 326번째 줄: / 331번째 줄: @@
 === 6️⃣ `build.yml` ===
+/build.yml
 <source lang=bash>
 # This file generates the GitHub Actions matrix.
@@ 350번째 줄: / 356번째 줄: @@
    - board: nice_nano_v2
      shield: fn25key
+</source>
+----
+=== config/west.yml ,  zephyr/module.yml 은 수정하지 않고 템플릿 그대로 사용한다. ===
+----
+== 펌웨어 컴파일 ==
+=== github 에 등록하기 ===
+<source lang=bash>
+git add .
+git commit -m "Add fn25key macropad shield"
+git push origin main
 </source>
+=== github 에서 컴파일 작업 ===
+# GitHub 저장소 페이지 → Actions 탭
+# push 직후 워크플로우가 자동 실행됨 (초록 체크 = 성공, 빨간 X = 실패)
+# 실패 시 로그 클릭해서 에러 확인 (대부분 devicetree 문법 오류나 핀 중복 사용)
+=== .uf2 파일 다운로드 ===
+# 성공한 워크플로우 실행 클릭
+# 하단 Artifacts 섹션에서 firmware 다운로드 (zip 안에 fn25key.uf2 등이 들어있음)
+=== 보드에 플래싱 ===
+# Super Mini nRF52840 리셋 버튼 2번 빠르게 눌러 부트로더 모드 진입 → PC에 USB 드라이브(XIAO-SENSE 등)로 인식됨
+# 다운로드한 .uf2 파일을 그 드라이브에 드래그 앤 드롭
+# 자동으로 리부트되며 새 펌웨어로 동작 시작
-----
 == 납땜 순서 요약 ==
@@ 401번째 줄: / 431번째 줄: @@
 </source>
+==  로컬 빌드(west)로 하고 싶다면 ==
+* 클라우드 빌드가 막힐 경우를 위해 로컬 빌드도 가능합니다.
+<source lang=bash>
+pip install west --break-system-packages
+west init -l config
+west update
+west zephyr-export
+west build -p -b seeeduino_xiao_ble -- -DSHIELD=fn5x5
+</source>
+* 결과물은 build/zephyr/zmk.uf2에 생성됩니다.
+** Zephyr SDK(nRF 툴체인) 설치가 선행되어야 해서, 처음이라면 GitHub Actions 방식 추천.

5x5 매크로 키보드 만들기: 두 판 사이의 차이

2026년 8월 11일 (화) 00:44 기준 최신판

5x5 매크로 키보드 만들기 (3D 프린터 ,NRF52840칩, ZMK)

gpio 핀 할당 (5 Row + 5 Col = 10핀)

보드 핀 다이어그램

보드 핀 다이어그램

✅ 확정 핀 할당 (SuperMini 실제 사용 가능 핀 기준)

배선도

ZMK 펌웨어 파일 구성

📁 폴더 구조

1️⃣ `fn25key.overlay`

2️⃣ `fn25key.keymap`

3️⃣ `fn25key.conf`

4️⃣ `Kconfig.shield`

5️⃣ `Kconfig.defconfig`

6️⃣ `build.yml`

config/west.yml , zephyr/module.yml 은 수정하지 않고 템플릿 그대로 사용한다.

펌웨어 컴파일

github 에 등록하기

github 에서 컴파일 작업

.uf2 파일 다운로드

보드에 플래싱

납땜 순서 요약

키 배치 커스터마이징 팁

로컬 빌드(west)로 하고 싶다면

Comments