데브카페 - 사용자 기여 [ko]

West로 로컬 직접 컴파일

2026-08-19T06:53:47Z

Devcafe: /* west로 로컬 직접 컴파일 */

== west로 로컬 직접 컴파일 ==
=== 툴체인 준비 (최초 1회) ===
<source lang=bash>

pip install west --break-system-packages
# Zephyr SDK 설치 필요 (없으면):
# https://docs.zephyrproject.org/latest/develop/getting_started/index.html 참고
</source>

=== west workspace 초기화 ===

config/west.yml이 매니페스트이므로, 그걸 기준으로 west workspace를 초기화합니다.

<source lang=bash>
cd shortkey_firmware ## 펌웨어 대상 루트디렉토리로 이동
west init -l config
west update
west zephyr-export
pip install -r zephyr/requirements-base.txt --break-system-packages
</source>

=== 빌드 ===

* boards/shields/shortkey가 루트의 zephyr/module.yml을 통해 모듈로 인식되게 하려면,
* 빌드 시 ZEPHYR_EXTRA_MODULES로 이 저장소 루트를 명시적으로 넘겨줘야 합니다.
* 그리고 config/ 안의 keymap/conf/overlay(예: config/boards/arm/nice_nano_v2.overlay)를 적용하려면 ZMK_CONFIG로 config 경로를 지정합니다.

<source lang=bash>
west build -p -b nice_nano_v2 -- \
-DSHIELD=shortkey \
-DZMK_CONFIG=$(pwd)/config \
-DZEPHYR_EXTRA_MODULES=$(pwd)
-p : pristine build (처음 또는 구조 바꿀 때마다 권장)
-DSHIELD=shortkey : boards/shields/shortkey 사용
-DZMK_CONFIG=.../config : config/shortkey.conf, config/boards/arm/nice_nano_v2.overlay 등 반영
-DZEPHYR_EXTRA_MODULES=.../shortkey_firmware : 루트의 zephyr/module.yml을 모듈로 인식시켜 boards/shields/shortkey 탐색 가능하게 함
</source>

=== 펌웨어 결과물 ===
<source lang=bash>
ls build/zephyr/zmk.uf2
</source>

이 파일을 부트로더 모드 진입한 보드 드라이브에 드래그 앤 드롭하면 됩니다.

=== 재빌드 시 ===

설정만 바꿨다면 -p 없이:

<source lang=bash>
west build
</source>

shield/board 자체를 바꾸면 다시 -p(pristine)로 빌드하세요.

5x5 매크로 키보드 만들기

2026-08-19T06:53:24Z

Devcafe: /* {:west로 로컬 직접 컴파일} */

= 5x5 매크로 키보드 만들기 (3D 프린터 ,NRF52840칩, ZMK) =
* 준비물
# SuperMini NRF52840
# 5×5 보드판(3d 프린팅)
# 키캡 , 기계식 키보드 체리식 키 클론(알리익프레스)
# 저항 다이오드

== gpio 핀 할당 (5 Row + 5 Col = 10핀) ==
SuperMini 핀이 넉넉하게 남아서 여유 있게 배치 가능합니다.
* 납땜 핀 번호 (보드 실크스크린 기준)
<source lang=bash>
| 용도 | 보드 라벨 | 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 |
</source>

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

----
== 보드 핀 다이어그램 ==
<source lang=bash>

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)
</source>
----
=== 보드 핀 다이어그램 ===
* SuperMini NRF52840
<source lang=bash>
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

</source>

----

----

== ✅ 확정 핀 할당 (SuperMini 실제 사용 가능 핀 기준) ==
<source lang=bash>
| 용도 | 보드 라벨 | 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 |
</source>

----

== 배선도 ==

* 스위치 매트릭스 (다이오드 col2row 방향)
<source lang=bash>
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]
</source>

* 각 스위치에 다이오드(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 파일만 얹으면 됩니다.

=== 📁 폴더 구조 ===
<source lang=bash>

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

----

=== 1️⃣ `fn25key.overlay` ===
boards\shields\fn25key.overlay
<source lang=bash>
/*
* 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>
;
};
};

</source>

----

=== 2️⃣ `fn25key.keymap` ===
boards\shields\fn25key.keymap
<source lang=bash>
/*
* 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
>;
};
};
};

</source>

----

=== 3️⃣ `fn25key.conf` ===
boards\shields\fn25key.conf
<source lang=bash>
# 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

</source>
----

=== 4️⃣ `Kconfig.shield` ===
boards\shields\Kconfig.shield

<source lang=bash>
config SHIELD_FN5X5
def_bool $(shields_list_contains,fn5x5)

</source>

----

=== 5️⃣ `Kconfig.defconfig` ===
boards\shields\Kconfig.defconfig

<source lang=bash>
if SHIELD_FN5X5

config ZMK_KEYBOARD_NAME
default "FN5x5"

endif # SHIELD_FN5X5

</source>

---

=== 6️⃣ `build.yml` ===
/build.yml
<source lang=bash>
# 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
</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 파일을 그 드라이브에 드래그 앤 드롭
# 자동으로 리부트되며 새 펌웨어로 동작 시작

== 납땜 순서 요약 ==

<source lang=bash>

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 연결 후 펌웨어 플래시
</source>

---

== 키 배치 커스터마이징 팁 ==

<source lang=bash>

| 위치 | 추천 매크로 |
|------|-----------|
| 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/시스템) |

</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 방식 추천.

{{:west로 로컬 직접 컴파일}}

5x5 매크로 키보드 만들기

2026-08-19T06:52:58Z

Devcafe: /* {{:west로 로컬 직접 컴파일}} */

West로 로컬 직접 컴파일

2026-08-19T05:50:04Z

Devcafe: 새 문서: == west로 로컬 직접 컴파일 == === 툴체인 준비 (최초 1회) ==== <source lang=bash> pip install west --break-system-packages # Zephyr SDK 설치 필요 (없으면): # https://docs.zephyrproject.org/latest/develop/getting_started/index.html 참고 </source> === west workspace 초기화 === config/west.yml이 매니페스트이므로, 그걸 기준으로 west workspace를 초기화합니다. <source lang=bash> cd shortkey_firmware ## 펌웨어 대상 루트디렉...

== west로 로컬 직접 컴파일 ==
=== 툴체인 준비 (최초 1회) ====
<source lang=bash>

pip install west --break-system-packages
# Zephyr SDK 설치 필요 (없으면):
# https://docs.zephyrproject.org/latest/develop/getting_started/index.html 참고
</source>

=== west workspace 초기화 ===

config/west.yml이 매니페스트이므로, 그걸 기준으로 west workspace를 초기화합니다.

<source lang=bash>
cd shortkey_firmware ## 펌웨어 대상 루트디렉토리로 이동
west init -l config
west update
west zephyr-export
pip install -r zephyr/requirements-base.txt --break-system-packages
</source>

=== 빌드 ===

* boards/shields/shortkey가 루트의 zephyr/module.yml을 통해 모듈로 인식되게 하려면,
* 빌드 시 ZEPHYR_EXTRA_MODULES로 이 저장소 루트를 명시적으로 넘겨줘야 합니다.
* 그리고 config/ 안의 keymap/conf/overlay(예: config/boards/arm/nice_nano_v2.overlay)를 적용하려면 ZMK_CONFIG로 config 경로를 지정합니다.

<source lang=bash>
west build -p -b nice_nano_v2 -- \
-DSHIELD=shortkey \
-DZMK_CONFIG=$(pwd)/config \
-DZEPHYR_EXTRA_MODULES=$(pwd)
-p : pristine build (처음 또는 구조 바꿀 때마다 권장)
-DSHIELD=shortkey : boards/shields/shortkey 사용
-DZMK_CONFIG=.../config : config/shortkey.conf, config/boards/arm/nice_nano_v2.overlay 등 반영
-DZEPHYR_EXTRA_MODULES=.../shortkey_firmware : 루트의 zephyr/module.yml을 모듈로 인식시켜 boards/shields/shortkey 탐색 가능하게 함
</source>

=== 펌웨어 결과물 ===
<source lang=bash>
ls build/zephyr/zmk.uf2
</source>

이 파일을 부트로더 모드 진입한 보드 드라이브에 드래그 앤 드롭하면 됩니다.

=== 재빌드 시 ===

설정만 바꿨다면 -p 없이:

<source lang=bash>
west build
</source>

shield/board 자체를 바꾸면 다시 -p(pristine)로 빌드하세요.

5x5 매크로 키보드 만들기

2026-08-19T05:49:50Z

Devcafe: /* west로 로컬 직접 컴파일 */

5x5 매크로 키보드 만들기

2026-08-19T05:48:15Z

Devcafe: /* 로컬 빌드(west)로 하고 싶다면 */

2x2 매크로 키보드 만들기

2026-08-18T23:47:04Z

2026-08-10T16:27:40Z

Devcafe: 새 문서: = Lily58 매크로 키보드 = 좋습니다. Lily58은 이미 ZMK 공식 저장소에 shield로 포함되어 있어서, **핸드와이어링이라도 devicetree를 새로 짤 필요 없이 공식 핀맵 그대로 배선**하면 기존 `lily58` shield 설정을 그대로 쓸 수 있습니다. 이게 제일 편한 길입니다. ## 1. 매트릭스 구조 확인 - diode-direction: **col2row** (다이오드 캐소드가 row 쪽으로) - Row: 5개, 양쪽 half 공통 핀 사용 (ni...

= Lily58 매크로 키보드 =

좋습니다. Lily58은 이미 ZMK 공식 저장소에 shield로 포함되어 있어서, **핸드와이어링이라도 devicetree를 새로 짤 필요 없이 공식 핀맵 그대로 배선**하면 기존 `lily58` shield 설정을 그대로 쓸 수 있습니다. 이게 제일 편한 길입니다.

## 1. 매트릭스 구조 확인

- diode-direction: **col2row** (다이오드 캐소드가 row 쪽으로)
- Row: 5개, 양쪽 half 공통 핀 사용 (nice!nano pro_micro 넘버링 기준 5, 6, 7, 8, 9번)
- Column: 왼쪽 6개 + 오른쪽 6개 (엄지 클러스터 포함해서 총 columns=16으로 offset 처리됨)

정확한 컬럼 핀 번호(왼쪽/오른쪽 각각)는 제가 외워서 알려드리면 오타 위험이 있어서, 공식 핀맵 다이어그램을 보시는 걸 추천합니다:

👉 https://docs.typeractive.xyz/build-guides/lily58-wireless/troubleshooting

이 페이지에 nice!nano의 실제 물리 핀(P0.xx / P1.xx)과 row/column이 정확히 매칭된 다이어그램이 있고, devicetree 소스 링크도 같이 걸려 있습니다.

## 2. 핸드와이어링 순서

1. **키 배치/발판 확정**: 4메인로우(6열) × 2 + 엄지 5개 × 2 구조로 배치
2. **다이오드 먼저 납땜**: 각 스위치 핀 하나에 다이오드 캐소드(줄무늬) 쪽을 row 방향으로 통일해서 납땜 (col2row이므로 col 라인이 다이오드 애노드에 물림)
3. **Row 배선**: 같은 로우에 있는 스위치들의 다이오드 캐소드를 한 줄로 묶어서 nice!nano row 핀에 연결 (5줄)
4. **Column 배선**: 같은 컬럼에 있는 스위치 반대쪽 핀을 한 줄로 묶어서 nice!nano column 핀에 연결 (한쪽당 6~7줄, 위 다이어그램 기준)
5. **half 간 연결**: TRRS 또는 직결 배선 (기존 fn5x5 만드실 때 쓰신 방식과 동일)
6. **테스트**: 전체 조립 전에 ZMK 공식 "tester" shield로 GPIO 핀 하나씩 눌러서 단선/합선 확인 → https://zmk.dev/docs/troubleshooting/hardware-issues 참고

## 3. ZMK 설정 (zmk-config)

핀을 다이어그램 그대로 배선했다면 커스텀 오버레이 필요 없이 **공식 shield 이름만 지정**하면 끝입니다.

`config/west.yml`은 기본 zmk-config 템플릿 그대로 두시고, `build.yaml`만 이렇게:

```yaml
include:
- board: nice_nano_v2
shield: lily58_left
- board: nice_nano_v2
shield: lily58_right
```

`config/lily58.keymap` 파일 하나 만들어서 원하는 레이어(넘패드, 함수키 등 fn5x5/mynum25에서 쓰시던 구성) 넣으시면 GitHub Actions가 알아서 좌/우 uf2를 빌드해줍니다.

## 4. 만약 배선을 다이어그램과 다르게 하고 싶다면

핀 배치를 본인 편한 대로 바꾸고 싶으시면, 그때는 `lily58_left.overlay` / `lily58_right.overlay`만 복사해서 row-gpios/col-gpios 값을 본인 배선에 맞게 수정하면 됩니다 (matrix-transform, keymap은 그대로 재사용 가능).

핸드와이어링하면서 다이오드 방향이나 로우/컬럼 배선에서 막히는 부분 생기면 사진이나 구체적 배선 상황 알려주세요, 같이 디버깅해드리겠습니다.

5x5 매크로 키보드 만들기

2026-08-10T15:44:18Z

Devcafe:

= 5x5 매크로 키보드 만들기 (3D 프린터 ,NRF52840칩, ZMK) =
* 준비물
# SuperMini NRF52840
# 5×5 보드판(3d 프린팅)
# 키캡 , 기계식 키보드 체리식 키 클론(알리익프레스)
# 저항 다이오드

== gpio 핀 할당 (5 Row + 5 Col = 10핀) ==
SuperMini 핀이 넉넉하게 남아서 여유 있게 배치 가능합니다.
* 납땜 핀 번호 (보드 실크스크린 기준)
<source lang=bash>
| 용도 | 보드 라벨 | 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 |
</source>

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

----
== 보드 핀 다이어그램 ==
<source lang=bash>

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)
</source>
----
=== 보드 핀 다이어그램 ===
* SuperMini NRF52840
<source lang=bash>
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

</source>

----

----

== ✅ 확정 핀 할당 (SuperMini 실제 사용 가능 핀 기준) ==
<source lang=bash>
| 용도 | 보드 라벨 | 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 |
</source>

----

== 배선도 ==

* 스위치 매트릭스 (다이오드 col2row 방향)
<source lang=bash>
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]
</source>

* 각 스위치에 다이오드(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 파일만 얹으면 됩니다.

=== 📁 폴더 구조 ===
<source lang=bash>

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

----

=== 1️⃣ `fn25key.overlay` ===
boards\shields\fn25key.overlay
<source lang=bash>
/*
* 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>
;
};
};

</source>

----

=== 2️⃣ `fn25key.keymap` ===
boards\shields\fn25key.keymap
<source lang=bash>
/*
* 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
>;
};
};
};

</source>

----

=== 3️⃣ `fn25key.conf` ===
boards\shields\fn25key.conf
<source lang=bash>
# 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

</source>
----

=== 4️⃣ `Kconfig.shield` ===
boards\shields\Kconfig.shield

<source lang=bash>
config SHIELD_FN5X5
def_bool $(shields_list_contains,fn5x5)

</source>

----

=== 5️⃣ `Kconfig.defconfig` ===
boards\shields\Kconfig.defconfig

<source lang=bash>
if SHIELD_FN5X5

config ZMK_KEYBOARD_NAME
default "FN5x5"

endif # SHIELD_FN5X5

</source>

---

=== 6️⃣ `build.yml` ===
/build.yml
<source lang=bash>
# 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
</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 파일을 그 드라이브에 드래그 앤 드롭
# 자동으로 리부트되며 새 펌웨어로 동작 시작

== 납땜 순서 요약 ==

<source lang=bash>

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 연결 후 펌웨어 플래시
</source>

---

== 키 배치 커스터마이징 팁 ==

<source lang=bash>

| 위치 | 추천 매크로 |
|------|-----------|
| 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/시스템) |

</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 방식 추천.

2026-08-10T15:32:18Z

Devcafe: /* 5️⃣ `build.yaml` */

2026-08-10T15:30:05Z

Devcafe: /* 📁 폴더 구조 */

= 5x5 매크로 키보드 만들기 (3D 프린터 ,NRF52840칩, ZMK) =
* 준비물
# SuperMini NRF52840
# 5×5 보드판(3d 프린팅)
# 키캡 , 기계식 키보드 체리식 키 클론(알리익프레스)
# 저항 다이오드

== gpio 핀 할당 (5 Row + 5 Col = 10핀) ==
SuperMini 핀이 넉넉하게 남아서 여유 있게 배치 가능합니다.
* 납땜 핀 번호 (보드 실크스크린 기준)
<source lang=bash>
| 용도 | 보드 라벨 | 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 |
</source>

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

----
== 보드 핀 다이어그램 ==
<source lang=bash>

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)
</source>
----
=== 보드 핀 다이어그램 ===
* SuperMini NRF52840
<source lang=bash>
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

</source>

----

----

== ✅ 확정 핀 할당 (SuperMini 실제 사용 가능 핀 기준) ==
<source lang=bash>
| 용도 | 보드 라벨 | 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 |
</source>

----

== 배선도 ==

* 스위치 매트릭스 (다이오드 col2row 방향)
<source lang=bash>
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]
</source>

* 각 스위치에 다이오드(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 파일만 얹으면 됩니다.

=== 📁 폴더 구조 ===
<source lang=bash>

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

----

=== 1️⃣ `macro25.overlay` ===
boards\shields\macro25.overlay
<source lang=bash>
/*
* 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>
;
};
};

</source>

----

=== 2️⃣ `macro25.keymap` ===
<source lang=bash>
/*
* 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
>;
};
};
};

</source>

----

=== 3️⃣ `macro25.conf` ===
<source lang=bash>
# 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

</source>
----

=== 4️⃣ `Kconfig.shield` ===
<source lang=bash>

kconfig
config SHIELD_MACRO25
def_bool $(shields_list_contains,macro25)

if SHIELD_MACRO25

config ZMK_KEYBOARD_NAME
default "Macro25"

endif
</source>

----
=== 5️⃣ `build.yaml` ===
<source lang=bash>
yaml
---
include:
- board: supermini_nrf52840
shield: macro25
</source>

---

=== 6️⃣ `.github/workflows/build.yml` ===
<source lang=bash>
yaml
name: Build ZMK Firmware

on:
push:
pull_request:
workflow_dispatch:

jobs:
build:
uses: zmkfirmware/zmk/.github/workflows/build-user-config.yml@main
</source>

----

== 납땜 순서 요약 ==

<source lang=bash>

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 연결 후 펌웨어 플래시
</source>

---

== 키 배치 커스터마이징 팁 ==

<source lang=bash>

| 위치 | 추천 매크로 |
|------|-----------|
| 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/시스템) |

</source>