結論

自作キーボードとは、基板・キースイッチ・キーキャップなどの部品を選んで自分で組み立て、キーの配置や働き(キーマップ)までファームウェアで決められるキーボードです。はじめは、はんだ付けの要らないキット(ホットスワップ対応)と、画面で書き換えられる VIA・Vial 対応の基板を選ぶと始めやすくなります。

この記事でわかること

  • 必要なもの(基板・スイッチ・キーキャップ・マイコンなど)と組み立ての流れ
  • QMK・VIA・Vial の違いと、レイヤー・Mod-Tap の考え方(公式の記載の範囲)
  • QMK 公式の keymap.json を Python で読み、レイヤー表と設定ミスの検出を動かした結果

2026年11月16日更新|QMK Firmware 公式ドキュメントと公式リポジトリの keymap.json・Python 3.13 で実行確認

自作キーボードは「部品を選ぶ」「組み立てる」「ファームウェアでキーマップを決める」「書き込んで確かめる」の4段で進みます。全体の流れは次の図のとおりです。

flowchart TD
    A[配列とキットを選ぶ] --> B[部品をそろえる]
    B --> C{はんだ付けが要る?}
    C -->|ホットスワップ| D[スイッチを差し込む]
    C -->|はんだ付け式| E[はんだ付けする]
    D --> F[キーマップを決める]
    E --> F
    F --> G[書き込んで全キーを確かめる]

よく調べられることの答えを先にまとめます。

知りたいこと 答え 詳しい節
自作キーボードとは 部品を選んで組み立て、キーマップも自分で決めるキーボード 自作キーボードとは
自作キーボードに必要なもの キット(基板)・キースイッチ・キーキャップ・マイコン・ケーブル 必要なもの
自作キーボードの始め方 ホットスワップ対応・VIA 対応のキットから始めると手順が少ない 始め方
はんだ付けは要るか キットによる。ホットスワップ対応ならスイッチは差し込むだけ 始め方
QMK とは キーボードの中で動き、押されたキーを PC に伝えるファームウェア QMK・VIA・Vial の違い
VIA と Vial の違い どちらも画面でキーマップを変える道具。Vial は QMK のフォーク QMK・VIA・Vial の違い
レイヤー・Mod-Tap とは 1つのキーに複数の役割を持たせるしくみ キーマップの考え方
日本語配列で使えるか キーボードは番号を送り、文字にするのは OS。OS 側の配列設定と合わせる 日本語配列で使うとき

確認環境:Ubuntu 24.04.5 LTS・Python 3.13.18・git 2.43.0。QMK Firmware の公式リポジトリ(github.com/qmk/qmk_firmware、2026年11月16日時点の最新コミット 8252b63)から、公式の keymap.json 2本(splitkb/aurora/lily58 と zsa/planck_ez の default)と配列の定義(keyboard.json)だけを読み取り専用で取得し、Python の標準ライブラリで読みました。キーマトリクスのゴースト、タップとホールドの判定、ピン数の計算は、自作の小さな模型を Python で動かした結果です(QMK の内部の実装そのものではありません)。このマシンではキーボードの組み立て・ファームウェアのビルド・書き込みは行っていません。QMK・VIA・Vial の機能と手順は、それぞれの公式ドキュメント(docs.qmk.fm・caniusevia.com・get.vial.today)で確かめた範囲だけを書いています。図は mermaid 11.16.0 で描画を確かめています(確認日 2026年11月16日)。

この記事で実際に動かしたもの:QMK 公式の keymap.json を読むスクリプト、キーマップの設定ミスを見つけるスクリプト、マトリクスとダイオードの模型。

本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。

(記載例)出典:株式会社RJC「自作キーボードとは|始め方・必要なもの・QMKとVIAでキーマップを書く」

自作キーボードとは(既製品との違い)

この節では、自作キーボードが何を指し、既製品のキーボードと何が違うのかが分かります。

自作キーボードとは、キーボードの部品を自分で選び、組み立て、キーの働きまでファームウェアで決めるキーボードのことです。略して「自キ」と呼ばれることもあります。「自作」といっても、基板から設計する人は一部で、多くはキット(基板と部品のセット)を買って組み立てる形から始めます。

既製品との大きな違いは、キーボードの中で動くプログラム(ファームウェア)を自分で書き換えられることです。QMK の公式ドキュメントは、QMK を「キーボードの中で動き、キーが押されたことを検出して PC に伝えるソフトウェア」と説明し、キーマップを作ることは「キーボード用の実行できるプログラムを作ること」だと書いています。どのキーを押すと何を送るかを、OS の設定ではなくキーボード自身が覚えるので、別の PC につないでも同じ配置で使えます。

既製品のキーボード

配列・スイッチ・キーキャップは製品で決まっている

キーの入れ替えは OS 側の設定や専用ソフトで行うことが多い

届いたらすぐ使える

自作キーボード

配列(分割・格子状など)や部品を選べる

キーマップをファームウェアに書き込むので、PC を替えても同じ

組み立てと書き込みの手間がかかる

Windows の中だけでキーを入れ替える方法は、関連記事「PowerToysとは・使い方|全31ツール一覧と既定ショートカット46件」で扱っています。OS 側で入れ替える方法とキーボード側で入れ替える方法は、どちらが上というものではなく、効く範囲が違います。

自作キーボードで変えられること(配列・打ち心地・キーマップ)

この節では、自作キーボードで何を自分で選べるのかが分かります。

自作キーボードで選べるものは、大きく3つです。

1配列(キーの並び)

左右に分かれた分割型、キーが縦にそろった格子状、キーを減らした小型など。この記事で読む Lily58 は左右29キーずつ、計58キーの分割型です(公式の keyboard.json を数えた値)。

2打ち心地と見た目

キースイッチの種類(押したときの手応え・音・重さ)と、キーキャップの形・素材・印字を選べます。ホットスワップ対応なら、あとからスイッチだけ替えられます。

3キーマップ(キーの働き)

どのキーで何を送るか、レイヤーで1つのキーに複数の役割を持たせるかを、ファームウェアで決めます。エンジニアの仕事の道具と結びつけやすいのがこの部分です。

エンジニアの仕事では、エディターのショートカットをキー1つにまとめる、矢印キーをホームポジションの近くのレイヤーに置く、といった使い方がよく話題になります。よく使うショートカットの一覧は、関連記事「VSCodeショートカット一覧|Win/Mac対応130項目とAI操作・変更方法」で扱っています。

自作キーボードに必要なもの(部品一覧)

この節では、自作キーボードを1台作るのにそろえる部品と道具が分かります。

まず要るのは、キット(基板)・キースイッチ・キーキャップの3つです。マイコンボードやケースがキットに含まれるかどうかは、キットごとに違います。キットの説明書(ビルドガイド)にある「別に用意するもの」の欄を最初に読むのが確実です。

部品 役割 選ぶときに見ること
基板(PCB) スイッチをつなぐ配線の板。配列はここで決まる ホットスワップ対応か、対応ファームウェア(QMK・VIA・Vial)
マイコンボード ファームウェアが動く部品。キー入力を読み、USB で PC に送る キットの指定どおりのもの。最初から基板に載っている場合もある
キースイッチ 押されたことを電気的に伝える部品。キーの数だけ要る 基板が対応する形、押し心地、予備を何個か
キーキャップ 指が触れる部分 スイッチとの互換、長いキー(スペースなど)の大きさ
スタビライザー 長いキーの傾きを抑える 長いキーがある配列だけ要る
ケース・プレート 基板とスイッチを支える キットに含まれるか
ケーブル PC との接続。分割型は左右をつなぐケーブルも要る コネクターの形、左右をつなぐケーブルの種類(キットの指定)
ダイオード・ソケット キーマトリクスの誤検出を防ぐ部品と、スイッチを差し込む受け口 基板に実装済みか、自分ではんだ付けするか

はんだ付けをするキットでは、はんだごて・こて台・はんだ・はんだ吸い取り線・ピンセットなどの道具も要ります。はんだ付けの安全(温度・換気・やけど)は、各製品の説明書に従います。

価格は製品と販売店で幅が大きく、確かめられる公式の一覧がないため、この記事では書きません。代わりに、部品の数と作業の量を、配列の定義から計算します。キースイッチはキーの数だけ要り、スイッチ1個には足(ピン)が2本あります。基板に差し込む型のダイオードを自分で付ける場合は、それも1キーに2か所です。

== solder points ==
macropad 3x3: switch pins 18 / +through-hole diodes 18 -> 36
Planck(47): switch pins 94 / +through-hole diodes 94 -> 188
Lily58(58): switch pins 116 / +through-hole diodes 116 -> 232
58個Lily58 のキースイッチ公式の keyboard.json のキー数
116か所スイッチのはんだ付け58個 × 足2本(はんだ付け式の場合)
232か所ダイオードも付ける場合差し込む型のダイオード 58個 × 2

ホットスワップ対応の基板なら、スイッチのはんだ付けは0か所です。最初の1台でこの差は大きく、作業時間の見積もりにもそのまま効きます。

自作キーボードの始め方(組み立ての流れ・はんだ付けの有無)

この節では、自作キーボードを始めるときの順番と、はんだ付けが要るかどうかの見分け方が分かります。

始め方の要点は「キットを1つ決めて、その説明書の順に進める」ことです。部品をばらばらに集めると、形の合わない部品を選びやすくなります。

1

配列とキットを決める

分割型か一体型か、キーの数、ホットスワップ対応か、VIA・Vial 対応かを見ます。QMK の公式ドキュメントは、対応するキーボードを browse.qmk.fm で探せると案内しています。

キットの説明書の「別に用意するもの」を読む

2

部品をそろえる

キースイッチはキーの数+予備、キーキャップは長いキーの大きさまで合わせます。分割型は左右をつなぐケーブルも要ります。

基板が対応するスイッチの形を確かめる

3

組み立てる

はんだ付け式なら説明書の順にはんだ付けし、ホットスワップ式ならスイッチを差し込みます。スイッチの足が曲がっていないか、差す前に見ます。

スイッチを全部付ける前に、つないで反応を見ると切り分けやすい

4

ファームウェアを入れる

キットに書き込み済みのこともあります。自分で入れる場合は、QMK の手順(環境の準備→ビルド→書き込み)か、キットが案内する方法に従います。

QMK 公式の3段:Setup・Building・Flashing

5

キーマップを決めて、全部のキーを確かめる

VIA・Vial 対応なら画面で変更します。QMK の公式は、書き込んだあとにすべてのキーを押して期待どおりか確かめるよう案内しています。

QMK Configurator のテストモードでも確かめられる

はんだ付けの有無で選ぶと

はんだ付け式スイッチを基板に直接はんだ付けする。あとからスイッチを替えるには外す作業が要る
↔
ホットスワップ基板の受け口(ソケット)にスイッチを差し込む。抜いて差し替えられる

見分ける問い:「キットの説明に、スイッチのソケットが実装済みと書いてあるか」

ホットスワップ対応でも、ソケットやマイコンの取り付けにはんだ付けが要るキットもあります。「はんだ付け不要」と書かれているかを、説明書で確かめます。

キーマトリクスとダイオード:配線の仕組みを Python で確かめる

この節では、キーボードがたくさんのキーを少ない配線で読むしくみと、ダイオードが要る理由が分かります。

キーボードのスイッチは行と列の格子(キーマトリクス)につながっていて、マイコンは列に順番に信号を送り、どの行に届いたかでキーを判定します。QMK の公式ドキュメント「How a Keyboard Matrix Works」は、この手順をマトリクスのスキャンと呼び、ダイオードは電流を一方向にしか通さないため、同時押しのときに押していないキーが押されたと誤認される「ゴースト」を防ぐと説明しています。

まず、キーの数に対して何本の線が要るかを計算しました。キー1つずつに線を引くとキーの数だけ要りますが、格子にすると「行の数+列の数」で済みます。

== matrix pins ==
keys=  9 direct=  9 pins  matrix 3x3 = 6 pins (cells 9)
keys= 30 direct= 30 pins  matrix 5x6 = 11 pins (cells 30)
keys= 47 direct= 47 pins  matrix 6x8 = 14 pins (cells 48)
keys= 58 direct= 58 pins  matrix 6x10 = 16 pins (cells 60)
keys= 61 direct= 61 pins  matrix 7x9 = 16 pins (cells 63)
keys= 87 direct= 87 pins  matrix 8x11 = 19 pins (cells 88)
keys=104 direct=104 pins  matrix 8x13 = 21 pins (cells 104)
lily58 half: 5 rows x 6 cols = 11 pins for 29 keys

Lily58 の公式の keyboard.json では、片手側は行が5本("rows": ["F4", "F6", "D7", "E6", "B4"])、列が6本で、29キーを11本の線で読んでいます。ダイオードの向きは "diode_direction": "ROW2COL" と書かれていました。

次に、3×3 の格子で、ダイオードがない場合とある場合を模型で比べました。左上・その右・その下の3つを同時に押すと、ダイオードがないときは電気が押したスイッチを逆向きにたどり、押していない右下(1,1)まで届きます。

== ghosting 3x3 ==
no diodes [(0, 0), (0, 1), (1, 0), (1, 1)] ghost: [(1, 1)]
diodes [(0, 0), (0, 1), (1, 0)] ghost: []

公式の説明どおり、3つを押したときに4つ目が現れ、ダイオードを入れると消えました。組み立てでダイオードの向きを逆に付けると、その列や行のキーが反応しない原因になります。向きは基板の印と説明書で確かめます。

ファームウェアとは:QMK・VIA・Vial の違い

この節では、自作キーボードでよく出てくる QMK・VIA・Vial が、それぞれ何をするものかが分かります。

QMK はキーボードの中で動くファームウェア、VIA と Vial は、そのキーマップを PC の画面から書き換えるための道具です。3つは競合ではなく、組み合わせて使われます。

1

QMK Firmware

キーボードの中で動き、キーの入力を検出して PC に伝える。キーマップはファイルに書き、ビルドして書き込む。

docs.qmk.fm

2

VIA

キーボードをつなぐと画面で設定できる道具。公式サイトは1400以上のキーボードに対応と紹介。設定はキーボードの不揮発性メモリに保存される。

caniusevia.com

3

Vial

Windows・Linux・Mac で動くオープンソースの設定画面と、リアルタイムで設定するための QMK のフォーク。Web 版もある。

get.vial.today

QMK(ファイルで書く) VIA Vial
変え方 keymap.json・keymap.c を書いてビルドし、書き込む 画面で変更。キーボードの定義(JSON)が要る 画面で変更。Vial 対応のファームウェアが要る
変えたあと 書き込み直しで反映 不揮発性メモリに保存(公式の説明) 対応ファームウェアなら画面が自動で認識(公式の説明)
レイヤーの数 LT で指定できるのは 0〜15 既定は4つ(公式の説明。変えられる) 公式トップに具体の数の記載なし
できること(公式の記載) レイヤー・Mod-Tap・Tap Dance など キーマップ・マクロ・配列の選択など レイヤー・マクロ・タップダンス・コンボなど

VIA の公式ドキュメント「Configuring QMK」には、知っておくと迷わない点が3つありました。1つ目は、ファームウェア側では VIA_ENABLE = yes を加え、yes は小文字にすること。2つ目は、VIA 用のキーマップは QMK 本体のリポジトリでは受け付けなくなり、VIA の QMK Userspace で扱うこと。3つ目は、VIA が保存した設定はキーボードの不揮発性メモリにあるため、あとで keymap.c を変えても、そのメモリ(EEPROM)を消すまで反映されないことです。

VIA と Vial のどちらを使うかは、キットがどちらに対応しているかで決まることがほとんどです。キットの説明に書かれた対応ファームウェアを使います。

キーマップの考え方:レイヤーと Mod-Tap

この節では、キーの少ない自作キーボードで、数字や記号、矢印をどう打つのかが分かります。

キーの少ない配列では、「レイヤー」で同じキーに別の役割を重ね、「Mod-Tap」で1つのキーに押し方ごとの役割を持たせます。どちらも QMK の公式ドキュメントに定義があります。

レイヤーのキーコード

キーコード 働き(公式の説明) 使いどころ
MO(layer) 押している間だけそのレイヤーになる 数字・記号のレイヤー
LT(layer, kc) 長押しでレイヤー、タップで kc を送る。0〜15のレイヤーだけ スペースを長押しで矢印のレイヤーに
TG(layer) 押すたびにオン・オフを切り替える テンキーのレイヤーを出しっぱなしに
TO(layer) そのレイヤーにし、既定以外のレイヤーをすべて切る 今のレイヤーから確実に移る
TT(layer) 長押しは MO、連打は TG のように働く(既定は5回) ふだんは一時、ときどき固定
OSL(layer) 次のキーを押すまでだけそのレイヤーになる 記号を1文字だけ打つ
DF(layer) 既定のレイヤーを替える(電源を切ると戻る) 配列ごと切り替える

QMK はレイヤーを番号順に重ね、上から順に見て、透過(KC_TRNS、keymap.json では _______ とも書く)でない最初の有効なレイヤーのキーを使う、と公式は説明しています。上のレイヤーで何も割り当てない位置を透過にしておくと、下のレイヤーのキーがそのまま使えます。

Mod-Tap と TAPPING_TERM

MT(mod, kc) は、長押しすると修飾キー(Ctrl・Shift など)、タップすると通常のキーを送ります。LCTL_T(KC_A) のような短い書き方もあります。公式の説明では、kc に入れられるのは基本のキーコードだけで、KC_TILD のような Shift つきの記号は入れられません。また右側の修飾キーを1つでも指定すると、すべて右側として扱われます。

タップか長押しかの境目は TAPPING_TERM で、公式の既定は200ミリ秒です。押していた時間で分ける考え方を、単純化した模型で動かしました(QMK の実際の判定には PERMISSIVE_HOLD などの設定も関わります)。

== tap or hold (TAPPING_TERM=200ms, simplified) ==
held  90 ms -> tap: sends KC_A
held 150 ms -> tap: sends KC_A
held 260 ms -> hold: acts as Ctrl
held 450 ms -> hold: acts as Ctrl

文字のキーに Mod-Tap を置くと、速く打ったつもりでも長押しと判定されて、意図しない Ctrl が入ることがあります。最初は端のキー(Esc・Enter など)から試すと影響が小さくて済みます。

QMK の keymap.json を Python で読む(公式の例をレイヤー表にする)

この節では、QMK のキーマップのファイル(keymap.json)の形と、それをプログラムで読んで中身を確かめる方法が分かります。

keymap.json は、keyboard・keymap・layout・layers の4つを持つ JSON で、layers はレイヤーごとのキーコードの配列です。QMK の公式ドキュメント(QMK Configurator 用の既定のキーマップの説明)は、この4つを必須の項目として挙げ、レイヤーは名前ではなく番号で書く(MO(2) のように)と説明しています。公式リポジトリの Lily58 の default は、次のように始まります(先頭の行だけ抜き出し)。

{
    "keyboard": "splitkb/aurora/lily58/rev1",
    "keymap": "default",
    "version": 1,
    "layout": "LAYOUT",
    "layers": [
        [
            "KC_ESC" , "KC_1"   , "KC_2"   , "KC_3"   , "KC_4"   , "KC_5"   ,

これを Python の標準ライブラリだけで読み、レイヤーごとにキーの種類を数えるスクリプトを作りました。JSON の読み書きの基本は、関連記事「Python JSON 読み書き|コピペレシピと実行結果・3.14対応」で扱っています。

import json, re, collections

TRNS = {"_______", "KC_TRNS", "KC_TRANSPARENT"}
NOKEY = {"XXXXXXX", "KC_NO"}
LAYER_RE = re.compile(r"^(MO|TG|TO|TT|OSL|DF|PDF|LT|TL_LOWR|TL_UPPR)\b")
MT_RE = re.compile(r"^(MT|[LR]?(CTL|SFT|ALT|GUI)_T|MEH_T|HYPR_T)\(")

def kind(k):
    if k in TRNS: return "trns"
    if k in NOKEY: return "no"
    if LAYER_RE.match(k): return "layer"
    if MT_RE.match(k): return "modtap"
    return "key"

km = json.load(open("keymap.json", encoding="utf-8"))
for i, layer in enumerate(km["layers"]):
    c = collections.Counter(kind(k) for k in layer)
    print(f"layer {i}: keys={len(layer)} key={c['key']} layer={c['layer']} trns={c['trns']} no={c['no']}")

公式の2本で動かした結果です(Mod-Tap の数の列も出しています)。

keyboard: splitkb/aurora/lily58/rev1 / layout: LAYOUT / layers: 4
layer 0: keys=58 key=56 modtap=0 layer=2 trns=0 no=0
layer 1: keys=58 key=29 modtap=0 layer=1 trns=27 no=1
layer 2: keys=58 key=33 modtap=0 layer=1 trns=22 no=2
layer 3: keys=58 key=8 modtap=0 layer=0 trns=8 no=42
layer keys: [(0, 'L28', 'MO(1)'), (0, 'R28', 'MO(2)'), (1, 'R28', 'MO(3)'), (2, 'L28', 'MO(3)')]

keyboard: zsa/planck_ez/base / layout: LAYOUT_planck_1x2uC / layers: 4
layer 0: keys=47 key=45 modtap=0 layer=2 trns=0 no=0
layer 1: keys=47 key=38 modtap=0 layer=0 trns=9 no=0
layer 2: keys=47 key=38 modtap=0 layer=0 trns=9 no=0
layer 3: keys=47 key=22 modtap=0 layer=0 trns=25 no=0

配列の定義(keyboard.json)にあるキーの位置(x・y)と合わせると、左手側をレイヤーごとに表にできます。▽は透過、×は何も送らないキー(XXXXXXX)です。

--- layer 0 (left half, by y row) ---
0     ESC       1       2       3       4       5
1     TAB       Q       W       E       R       T
2    LCTL       A       S       D       F       G    LBRC
3    LSFT       Z       X       C       V       B
4    LALT    LGUI   MO(1)     SPC
--- layer 1 (left half, by y row) ---
0       ▽       ▽       ▽       ▽       ▽       ▽
1      F1      F2      F3      F4      F5      F6
2     GRV    EXLM      AT    HASH     DLR    PERC       ▽
3       ▽       ▽       ▽       ▽       ▽       ▽
4       ▽       ▽       ▽       ▽
--- layer 2 (left half, by y row) ---
0       ▽       ▽       ▽       ▽       ▽       ▽
1     GRV       1       2       3       4       5
2      F1      F2      F3      F4      F5      F6       ▽
3      F7      F8      F9     F10     F11     F12
4       ▽       ▽   MO(3)       ▽

左の親指の MO(1) を押している間、上段の Tab の位置は F1、Ctrl の位置は `(GRV)になる、ということが表から読めます。上から見て透過でないキーを選ぶ規則で、実際に送られるキーも計算しました。

L01 layer0: KC_ESC | hold MO(1): KC_ESC | layer1+3: XXXXXXX
L07 layer0: KC_TAB | hold MO(1): KC_F1 | layer1+3: XXXXXXX
L13 layer0: KC_LCTL | hold MO(1): KC_GRV | layer1+3: XXXXXXX
L28 layer0: MO(1) | hold MO(1): MO(1) | layer1+3: MO(1)
R28 layer0: MO(2) | hold MO(1): MO(3) | layer1+3: MO(3)

この default では、左の MO(1) を押したまま右の親指を押すと、そこが MO(3) になり、3番のレイヤー(光の設定)に入れるようになっていました。2つのレイヤーキーの組み合わせで3つ目に入る作りが、ファイルを読むだけで分かります。

つまずいた点:keyboard.json は標準の json で読めなかった

Lily58 の keyboard.json には // L RGB1 のような行末のコメントが入っていて、Python の json.load はそのままでは読めませんでした。

json.decoder.JSONDecodeError: Expecting value: line 134 column 64 (char 5818)

行末の // 以降を除いてから読むと通りました(QMK の CLI 自体がどう読むかは、ここでは確かめていません)。JSON の読み込みエラーの見方は、関連記事「JSON.parseとJSON.stringifyの使い方|エラー原因と整形」で扱っています。

キーマップの重複・設定ミスを見つける(チェックを実際に動かす)

この節では、キーマップを自分で書いたときに起きやすい間違いを、プログラムで先に見つける方法が分かります。

書き込む前に、公式ドキュメントの決まりに反していないかをスクリプトで確かめると、書き込み直しの回数を減らせます。今回のチェックは次の4つです。

  • 1レイヤーごとのキーの数が配列と同じかlayout のキーの数と layers の各配列の長さを比べる
  • 2MO・LT で入る先のレイヤーで、その位置が透過か公式は MO・LT・TT を使うとき、上のレイヤーの同じ位置を透過にしておくよう説明している
  • 3存在しないレイヤー番号を指していないかLT は 0〜15 だけ
  • 4Mod-Tap の kc が基本のキーコードか、同じレイヤーに同じキーが2つないかKC_TILD などは Mod-Tap に入れられない

わざと間違いを入れた、3×3 の小さなキーボード(架空)のキーマップを用意しました。

{
    "keyboard": "example/macropad3x3",
    "keymap": "mine",
    "layout": "LAYOUT",
    "layers": [
        ["KC_A", "KC_B", "KC_C",
         "KC_D", "KC_C", "LCTL_T(KC_TILD)",
         "MO(1)", "LT(2, KC_SPC)", "MO(4)"],
        ["KC_1", "KC_2", "KC_3",
         "KC_4", "KC_5", "KC_6",
         "KC_ENT", "KC_TRNS", "KC_TRNS"],
        ["KC_F1", "KC_F2", "KC_F3",
         "KC_F4", "KC_F5", "KC_F6",
         "KC_TRNS", "KC_TRNS"]
    ]
}

チェックの中心の部分は次のとおりです。

def check(L, lab):
    probs = []
    for src, layer in enumerate(L):
        for pos, k in enumerate(layer):
            m = re.match(r"^(MO|TT|OSL|LT)\((\d+)", k)
            if not m:
                continue
            tgt = int(m.group(2))
            if tgt >= len(L):
                probs.append(f"{k} at {lab[pos]} points to layer {tgt}, but only {len(L)} layers")
            elif L[tgt][pos] not in TRNS:
                probs.append(f"{k} at {lab[pos]}: layer {tgt} has {L[tgt][pos]} there (not transparent)")
    for i, layer in enumerate(L):
        c = collections.Counter(k for k in layer if kind(k) in ("key", "modtap"))
        for k, n in c.items():
            if n > 1:
                ps = [lab[p] for p, x in enumerate(layer) if x == k]
                probs.append(f"layer {i} duplicate {k} at {', '.join(ps)}")
    return probs

実行した結果です。

keyboard: example/macropad3x3 / layout: LAYOUT / layers: 3
layer 0: keys=9 key=5 modtap=1 layer=3 trns=0 no=0
layer 1: keys=9 key=7 modtap=0 layer=0 trns=2 no=0
layer 2: keys=8 key=6 modtap=0 layer=0 trns=2 no=0
  NG: layer 2 has 8 keys but layout has 9
layer keys: [(0, 'K20', 'MO(1)'), (0, 'K21', 'LT(2, KC_SPC)'), (0, 'K22', 'MO(4)')]
CHECK: MO(1) at K20: layer 1 has KC_ENT there (not transparent)
CHECK: MO(4) at K22 points to layer 4, but only 3 layers
CHECK: layer 0 K12 LCTL_T(KC_TILD): kc of Mod-Tap must be a basic keycode
CHECK: layer 0 duplicate KC_C at K02, K11

入れた間違い5つがすべて見つかりました。一方、公式の Lily58・Planck の default では何も出ませんでした。なお、同じキーが別のレイヤーにあるのは間違いではありません。Lily58 の default を数えると、2つ以上のレイヤーに出てくるキーコードは27種(例:数字の1〜0は0番と2番、KC_GRV は0・1・2番の3つ)で、使う場面ごとに打ちやすい位置へ置いた結果です。重複のチェックは「同じレイヤーの中」に絞るのが実用的です。

ファームウェアの書き込みの流れ(QMK 公式の手順)

この節では、QMK のファームウェアをキーボードに書き込む流れと、書き込みモードへの入り方が分かります。

書き込みは「キーボードを書き込みモード(ブートローダー)にする」→「ファイルを書き込む」→「全部のキーを確かめる」の順です。以下は QMK の公式ドキュメント「Flashing Your Keyboard」の記載をまとめたもので、この記事の環境では書き込みをしていません。

  1. 1両方の Shift を押しながら Pause、または B を押すキーマップにその設定がある場合
  2. 2抜いた状態でスペースと B を押したまま挿す少し待ってから離す
  3. 3左上のキー(Esc か左 Ctrl が多い)を押しながら挿す公式が挙げる方法の1つ
  4. 4基板の RESET ボタンを押す裏側にあることが多い
  5. 5RESET と GND のピンをつなぎながら挿すボタンがない基板。説明書で位置を確かめる

書き込みの道具について、公式の記載は次のとおりです。

  • QMK Toolbox:Windows と macOS 用。<keyboard>_<keymap>.{bin,hex} という名前のファイルを選び、Flash を押す。RP2040 のマイコンでは QMK Toolbox は要らない、と書かれています。
  • コマンド:qmk flash -kb <my_keyboard> -km <my_keymap> でビルドと書き込みをまとめて行う。Linux はコマンドで書き込む。ブートローダーが見つからないときは qmk doctor を実行するよう案内されています。
  • 書き込み中:キーボードを抜いたり、処理を止めたりしない。

VIA・Vial 対応のキットで、すでに対応ファームウェアが入っているなら、キーマップを変えるたびに書き込む手順は要りません。画面で変えた内容がキーボードに保存されます。QMK のファームウェアを自分でビルドするときは、まず公式リポジトリを手元に取得します。git の取得の基本は、関連記事「git cloneの使い方|ブランチ指定とshallow clone」で扱っています。

自作キーボードを日本語配列で使うときの注意

この節では、自作キーボードで日本語の記号が思った文字にならない理由と、合わせ方が分かります。

キーボードが送るのは文字ではなくキーの番号で、それを文字にするのは OS です。QMK の公式ドキュメントは、既定の配列は US ANSI(HID の仕様どおり)で、言語ごとのキーコードを使っても OS 側の配列設定を合わせなければ効果がない、と説明しています。言語別のキーコードは「キーマップ上のキーキャップの表示名のようなもの」だという説明です。

  • 日本語向けには keymap_japanese.h(keymap.c で読み込む)があり、keymap.json では host_language の項目で指定できる、と公式の一覧にあります。
  • OS で「日本語キーボード」として使うか「英語キーボード」として使うかを決め、キーマップの記号をそれに合わせます。たとえば OS が日本語配列のまま US 配列向けのキーマップを使うと、記号のキーで別の文字が出ます。
  • VIA・Vial で変えるときも同じで、画面に出るキーの名前と、OS で実際に出る文字が違うことがあります。

日本語の配列のキーキャップは、英語の配列より選べる数が少ないと紹介されることが多く、購入前に対応を確かめます。キーの刻印にこだわらないなら、無刻印のキーキャップを選ぶ人もいます。

自作キーボードのよくあるつまずき

この節では、自作キーボードでよく起きる症状と、確かめる順番が分かります。

症状 よくある原因 確かめ方・直し方
1つのキーだけ反応しない スイッチの足が曲がった・差し込み不足・はんだ付け不足 スイッチを差し直す、別のスイッチと入れ替えて症状が移るかを見る
縦1列・横1行がまとめて反応しない その行か列の配線・ダイオードの向き・マイコンの接続 マトリクスの節のとおり、行・列のどちらに並んでいるかで場所をしぼる
押していないキーが入る ダイオードがない・付け忘れ(ゴースト) 3つ同時押しで4つ目が出るかを確かめる
分割型の片側が動かない 左右をつなぐケーブルの抜け・種類違い キットが指定するケーブルか、抜き差しは電源を切ってから行うか、説明書を確かめる
keymap.c を変えたのに反映されない VIA が保存した設定が残っている VIA の公式:EEPROM を消すまで keymap.c の変更は出ない
レイヤーから戻れない・キーが効かない MO の入る先で同じ位置を透過にしていない 前の節のチェックで「not transparent」が出るかを見る
Mod-Tap で Ctrl が勝手に入る 速く打っても長押しと判定された 端のキーに移す、TAPPING_TERM などの設定を公式の Tap-Hold の項で確かめる
記号が違う文字になる OS の配列設定とキーマップの前提が違う OS を US・日本語のどちらで使うかに合わせる
書き込みでブートローダーが見つからない 書き込みモードに入っていない 前の節の入り方を順に試し、qmk doctor を実行する

キーが反応しないときは、いきなり全部をばらさず、「1キーだけか」「1列・1行か」「片側全部か」に分けると、配線のどこを見ればよいかが決まります。

判断表:自作キーボードの始め方をどう選ぶか

この節では、自分の状況に合った始め方の組み合わせが分かります。

状況 選び方 理由
はんだ付けをしたことがない ホットスワップ対応・はんだ付け不要と書かれたキット はんだ付けが0か所になる(58キーなら116か所の差)
プログラムを書かずにキーを変えたい VIA か Vial 対応のキット 画面で変えて、キーボードに保存できる
Tap Dance・コンボなど細かい動きまで決めたい QMK で keymap.c を書く、または Vial QMK Configurator では Tap Dance などの独自のコードを使えない(公式の説明)
キーの数を大きく減らしたい レイヤー・Mod-Tap を前提に配列を選ぶ 数字・記号・矢印をレイヤーで打つ
左右の手の間隔を変えたい 分割型 左右の間隔と角度を自由に置ける
日本語配列の刻印がほしい キーキャップの対応を先に確かめる 英語配列より選べる数が少ないと紹介されることが多い
キーマップをファイルで管理したい QMK の keymap.json git で差分を見られ、この記事のチェックも使える

キーボードの方式そのもの(静電容量無接点方式など)から選びたいときは、方式の仕組みを扱った別の記事「REALFORCE(リアルフォース)とは|静電容量無接点方式の仕組み・種類と選び方」(公開準備中)が役に立ちます。

自作キーボードについてよくある質問

この節では、自作キーボードを始める前によく出る疑問への答えが分かります。

Q. 自作キーボードとは何ですか?
A. 基板・キースイッチ・キーキャップなどの部品を選んで自分で組み立て、キーの働き(キーマップ)までファームウェアで決めるキーボードです。多くの人はキットを組み立てるところから始めます。

Q. 自作キーボードの始め方は?
A. キットを1つ決め、その説明書の「別に用意するもの」をそろえ、説明書の順に組み立てます。はじめはホットスワップ対応で、VIA か Vial に対応したキットが手順の少ない組み合わせです。

Q. はんだ付けは必ず要りますか?
A. キットによります。ホットスワップ対応ならスイッチは差し込むだけですが、ソケットやマイコンの取り付けにはんだ付けが要るキットもあります。説明書で確かめます。

Q. 必要なものは何ですか?
A. キット(基板)・キースイッチ(キーの数+予備)・キーキャップが中心で、キットによってはマイコンボード・ケース・スタビライザー・ケーブルも別に要ります。

Q. QMK とは何ですか?
A. キーボードの中で動き、押されたキーを検出して PC に伝えるオープンソースのファームウェアです。キーマップを書いてビルドし、キーボードに書き込みます。

Q. VIA と Vial の違いは?
A. どちらも PC の画面からキーマップを変える道具です。VIA はキーボードの定義(JSON)を使って設定し、Vial は Vial 対応のファームウェア(QMK のフォーク)と組み合わせて使います。どちらを使うかは、キットの対応で決まることがほとんどです。

Q. VIA で変えた設定はどこに保存されますか?
A. VIA の公式の説明では、キーボードの不揮発性メモリです。PC を替えても同じキーマップで使えます。その代わり、あとで keymap.c を変えても、メモリを消すまで反映されません。

Q. レイヤーとは何ですか?
A. 同じキーに別の役割を重ねるしくみです。たとえば親指のキーを押している間だけ、上段の数字が F1〜F6 になる、という使い方をします。

Q. Mod-Tap とは何ですか?
A. 長押しで Ctrl や Shift、タップで通常のキーを送る QMK の機能です。境目の時間は TAPPING_TERM で、公式の既定は200ミリ秒です。

Q. Mac でも Windows でも使えますか?
A. キーボードは USB の HID として番号を送るので、OS を選ばずにつなげます。ただし Ctrl と Command の位置など、OS ごとに置きたいキーは違うので、レイヤーや DF でキーマップを切り替える人もいます。

Q. 日本語配列で使えますか?
A. 使えます。キーボードが送るのは番号で、文字にするのは OS なので、OS の配列設定(日本語か英語か)とキーマップの前提を合わせます。QMK には日本語向けのキーコードの定義もあります。

Q. 自作したキーマップの間違いを書き込む前に見つけられますか?
A. keymap.json なら、この記事のようにプログラムで読み、キーの数・透過・レイヤー番号・同じレイヤーの重複を確かめられます。書き込んだあとは、全部のキーを押して確かめます。

まとめ

  • 自作キーボードとは、部品を選んで組み立て、キーマップまでファームウェアで決めるキーボード。
  • 必要なものはキット(基板)・キースイッチ・キーキャップが中心。キットの「別に用意するもの」を最初に読む。
  • はじめはホットスワップ対応・VIA か Vial 対応のキットが手順が少ない。58キーのはんだ付け式なら、スイッチだけで116か所の作業になる。
  • QMK はキーボードの中で動くファームウェア、VIA・Vial は画面でキーマップを変える道具。レイヤーと Mod-Tap でキーの少なさを補う。
  • keymap.json は Python で読める。キーの数・透過・レイヤー番号・同じレイヤーの重複を書き込む前に確かめると、書き込み直しが減る。

参考・出典

確認日:2026年11月16日

  • QMK Firmware「The QMK Tutorial」:https://docs.qmk.fm/newbs
  • QMK Firmware「Flashing Your Keyboard」:https://docs.qmk.fm/newbs_flashing
  • QMK Firmware「Layers」:https://docs.qmk.fm/feature_layers
  • QMK Firmware「Mod-Tap」:https://docs.qmk.fm/mod_tap
  • QMK Firmware「Tap-Hold Configuration Options」:https://docs.qmk.fm/tap_hold
  • QMK Firmware「How a Keyboard Matrix Works」:https://docs.qmk.fm/how_a_matrix_works
  • QMK Firmware「Language-specific Keycodes」:https://docs.qmk.fm/reference_keymap_extras
  • QMK Firmware「Adding Default Keymaps to QMK Configurator」(keymap.json の項目):https://docs.qmk.fm/configurator_default_keymaps
  • QMK Firmware のリポジトリ(keyboards/splitkb/aurora/lily58、keyboards/zsa/planck_ez):https://github.com/qmk/qmk_firmware
  • VIA:https://www.caniusevia.com/
  • VIA「Configuring QMK」:https://www.caniusevia.com/docs/configuring_qmk
  • VIA「Specification」:https://www.caniusevia.com/docs/specification
  • Vial:https://get.vial.today/

本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。

(記載例)出典:株式会社RJC「自作キーボードとは|始め方・必要なもの・QMKとVIAでキーマップを書く」

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。

WE ARE HIRING

RJCで一緒に開発しながら、
成長を楽しみませんか?

RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!

  • 127日年間休日
  • 12時間平均残業時間
  • 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!

ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。

ABOUT RJC RJCがどんな会社か知る 考え方、研修、働き方、福利厚生、社員の前職まで。RJCのことが丸わかり! RJC丸わかりページへ JOB DESCRIPTION 仕事内容・待遇を見てみる 仕事内容、給与・待遇、選考の流れ。経験者も未経験も!応募前に知りたいこと、まとめました! 募集要項を見る ENTRY エントリーする エントリーは1〜2分・履歴書不要です。まずは話を聞いてみたい、という方でも歓迎です! エントリーフォームへ

成長のヒミツ、 ぜんぶ丸わかり