검색 여닫기
메뉴 여닫기
86
0
4
2천
데브카페
개인 메뉴 토글
로그인하지 않음
만약 지금 편집한다면 당신의 IP 주소가 공개될 수 있습니다.

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

데브카페
다른 명령
← 이전 편집
시각위키텍스트
편집 요약 없음
 
(같은 사용자의 중간 판 12개는 보이지 않습니다)
224번째 줄: 224번째 줄:


=== 2️⃣ `fn25key.keymap` ===
=== 2️⃣ `fn25key.keymap` ===
boards\shields\fn25key.keymap
<source lang=bash>
<source lang=bash>
/*
/*
277번째 줄: 278번째 줄:
----
----


=== 3️⃣ `macro25.conf` ===
=== 3️⃣ `fn25key.conf` ===
boards\shields\fn25key.conf
<source lang=bash>
<source lang=bash>
# FN5x5 기본 설정
# FN5x5 기본 설정
302번째 줄: 304번째 줄:


=== 4️⃣ `Kconfig.shield` ===
=== 4️⃣ `Kconfig.shield` ===
boards\shields\Kconfig.shield
<source lang=bash>
<source lang=bash>
config SHIELD_FN5X5
    def_bool $(shields_list_contains,fn5x5)
</source>


kconfig
----
config SHIELD_MACRO25
    def_bool $(shields_list_contains,macro25)


if SHIELD_MACRO25
=== 5️⃣ `Kconfig.defconfig` ===
boards\shields\Kconfig.defconfig
 
<source lang=bash>
if SHIELD_FN5X5


config ZMK_KEYBOARD_NAME
config ZMK_KEYBOARD_NAME
     default "Macro25"
     default "FN5x5"
 
endif # SHIELD_FN5X5


endif
</source>
</source>


----
 
=== 5️⃣ `build.yaml` ===
---
 
=== 6️⃣ `build.yml` ===
/build.yml
<source lang=bash>
<source lang=bash>
yaml
# 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:
include:
   - board: supermini_nrf52840
   - board: nice_nano_v2
     shield: macro25
     shield: fn25key
</source>
</source>
----
=== config/west.yml ,  zephyr/module.yml 은 수정하지 않고 템플릿 그대로 사용한다. ===
----


== 펌웨어 컴파일 ==


---
=== github 에 등록하기 ===
 
=== 6️⃣ `.github/workflows/build.yml` ===
<source lang=bash>
<source lang=bash>
yaml
git add .
name: Build ZMK Firmware
git commit -m "Add fn25key macropad shield"
git push origin main
</source>


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


jobs:
=== .uf2 파일 다운로드 ===
  build:
# 성공한 워크플로우 실행 클릭
    uses: zmkfirmware/zmk/.github/workflows/build-user-config.yml@main
# 하단 Artifacts 섹션에서 firmware 다운로드 (zip 안에 fn25key.uf2 등이 들어있음)
</source>


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


----


== 납땜 순서 요약 ==
== 납땜 순서 요약 ==
393번째 줄: 431번째 줄:


</source>
</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년 8월 11일 (화) 00:44 기준 최신판

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

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

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 공식 템플릿으로 저장소 생성
  • 이 템플릿에는 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 에서 컴파일 작업

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

.uf2 파일 다운로드

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

보드에 플래싱

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


납땜 순서 요약


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

Comments

원본 주소 "https://devcafe.co.kr/w/index.php?title=5x5_매크로_키보드_만들기&oldid=2525"
마지막 수정
이 문서는 2026년 8월 11일 (화) 00:44에 마지막으로 편집되었습니다.
저작권
별도로 명시하지 않은 경우, 내용은 크리에이티브 커먼즈 저작자표시에 따라 사용할 수 있습니다.