Beyond-KLE/journal/2026-09-24-qmk-feature-inventory.md

QMK 0.34.4 の機能棚卸し(MAP P-2 の下調べ)

結論

• 対象: QMK 0.34.4(tag, commit 08c662f286ddfd12a985f57b584b02eca5af0ae6, 2026-09-05)。masterの最新リリース。 ユーザーが最初の対応環境として0.34.4を採用(2026-09-24)。
  • キーコード体系 QMK_KEYCODES_VERSION = 0.0.9(quantum/keycodes.h)
  • VIA_PROTOCOL_VERSION = 0x000D(quantum/via.h。9/23時点の調査と同じ)
• MAPから見たQMKの機能は次の6種類に分かれる(下の表)。スキーマ・編集機能への落とし込みは未着手。
• 既存ドキュメントに影響しうる事実が2つある:
  1. VIAのモジュール化(20260830 ChangeLog「VIA Feature Migration」#26315)。VIA統合の保守をVIAチームへ移し、 旧来のfeature実装は将来のリリースで削除予定と告知済み。PR本体はdevelop向けのDraftで、0.34.4時点のVIAは従来の quantum/via.c。MAPレイヤー.md は「Dynamic = QMK本家のVIA」「Community Modules は当面非対応」としているため、 VIAがモジュール側へ移った時点でこの2つが衝突する。
  2. VIAのマトリクス状態取得の無効化(20250831 ChangeLog #25414)。id_switch_matrix_state は既定で全0を返す。 VIA_INSECURE 定義時、または SECURE_ENABLE でアンロック中のみ実値。Remap等のキーテスターは既定では動かない。
• QMKのキーごとの設定(tapping term等)はデータテーブルではなく、keycode/keyrecordを受けるCのコールバック関数で表現される。 keymap.json(data-driven)で書けるのはレイヤー・エンコーダ・DIPスイッチ・マクロ・カスタムキーコード・config・modules まで。 タップダンス・コンボ・キーオーバーライド・キーごとの設定はCでしか書けない。

分類の概要

区分	主なもの	実機への保存	VIAで読み書き
A. キーコード(単体で完結)	基本キー、修飾付き、MT/LT/OSM等、レイヤー操作、Magic、メディア、マウス等	キーマップ	○(16bit値として)
B. 定義を参照するキーコード	TD(n)、QK_MACRO_n、UM/UP、QK_KB_n/QK_USER_n	参照はキーマップ、定義はファームウェア	参照のみ○。定義はマクロのみ○
C. キー以外の起動条件を持つ動作	コンボ、キーオーバーライド、リーダー、オートコレクト、Tri Layer	ファームウェア	×
D. タップ・ホールド等の挙動設定	TAPPING_TERM等 + キーごとのコールバック	ファームウェア(DTTの変更は揮発)	×
E. キー以外の入力への割り当て	エンコーダ、DIPスイッチ、ポインティング、ジョイスティック等	エンコーダはキーマップ	エンコーダのみ○
F. 実機の永続状態	Magic設定、保存されたデフォルトレイヤー、Unicodeモード等	EEPROM	×

MAPの所有外(照明・オーディオ・ディスプレイ・ハードウェア構成)は末尾にまとめた。

---

A. キーコード体系 0.0.9

data/constants/keycodes/*.hjson を 0.0.1〜0.0.9 の順にマージして得た範囲。

範囲	名前	内容
0x0000–0x00FF	QK_BASIC	KC_NO/KC_TRNS、HID基本キー(basic 161件)、system 3、media 27、mouse 19(QK_MOUSE_*)、修飾8
0x0100–0x1FFF	QK_MODS	LCTL(kc) 等。kcは基本キーのみ、修飾は5bit(左右混在不可)
0x2000–0x3FFF	QK_MOD_TAP	MT(mod, kc)。kcは基本キーのみ
0x4000–0x4FFF	QK_LAYER_TAP	LT(layer, kc)。layer 0–15、kcは基本キーのみ
0x5000–0x51FF	QK_LAYER_MOD	LM(layer, mod)。layer 0–15
0x5200–	QK_TO / MOMENTARY / DEF_LAYER / TOGGLE_LAYER / ONE_SHOT_LAYER / ONE_SHOT_MOD / LAYER_TAP_TOGGLE / PERSISTENT_DEF_LAYER	TO/MO/DF/TG/OSL/OSM/TT/PDF。各32(layer 0–31)
0x5600–0x56FF	QK_SWAP_HANDS	SH_T(kc)、SH_TOGG等7件
0x5700–0x57FF	QK_TAP_DANCE	TD(0–255)
0x7000–0x70FF	QK_MAGIC	Ctrl/Caps、Alt/GUI、Ctl/GUI、Grave/Esc、BSpc/BSlash、Esc/Caps入替、GUI無効、NKRO、EE_HANDS 等35件
0x7100–0x71FF	QK_MIDI	ノート・オクターブ・移調・ベロシティ・チャンネル等
0x7200–0x73FF	QK_SEQUENCER	9件
0x7400–0x743F	QK_JOYSTICK	ボタン0–31
0x7440–0x747F	QK_PROGRAMMABLE_BUTTON	1–32
0x7480–0x74BF	QK_AUDIO	Audio/Clicky/Music 15件
0x74C0–0x751F	QK_STENO	0.0.9で拡張・改名(STN_* → QK_STENO_* / ST_*、旧名はエイリアス)
0x7700–0x777F	QK_MACRO	QK_MACRO_0–31(名前付き)。VIA/keymap.jsonのマクロ
0x7780–0x77BF	QK_CONNECTION	出力先切替(USB/2.4GHz/BT)、BTプロファイル1–5等15件
0x77C0–0x77FF	QK_COMMUNITY_MODULE	Community Modules用
0x7800–0x78FF	QK_LIGHTING	Backlight 7、LED Matrix 11、RGBLight(underglow)11 + RGB_MODE_* 10、RGB Matrix 15
0x7C00–0x7DFF	QK_QUANTUM	下記
0x7E00–0x7E3F	QK_KB	QK_KB_0–31(キーボード固有)
0x7E40–0x7FFF	QK_USER	QK_USER_0–31(キーマップ固有。SAFE_RANGE以降)
0x8000–0xFFFF	QK_UNICODE / UNICODEMAP / UNICODEMAP_PAIR	UC(cp≤0x7FFF)、UM(i)、UP(i,j)

QK_QUANTUM の内訳(73件): Bootloader/Reboot/Debug/EEPROMクリア/Make、Auto Shift操作6、Grave Escape、 Velocikey、Space Cadet 7、Unicodeモード切替8、Haptic 13、Combo on/off/toggle、Dynamic Macro 5、Leader、 Key Lock、One Shot on/off/toggle、Key Override on/off/toggle、Secure 4、Dynamic Tapping Term 3、Caps Word、 Autocorrect 3、Tri Layer Lower/Upper、Repeat/Alt Repeat、Layer Lock。

補足:

• 20250831で旧RGB・マウスの非推奨キーコードを削除(#25444)。
• VIAはキーマップを16bit値で読み書きするため、上のどの値もキーへ書ける。ファームウェアで無効な機能の値は何もしない。

B. 定義を参照するキーコード

機能	キーコード	定義の中身	定義の置き場所
Tap Dance	TD(n)	ACTION_TAP_DANCE_DOUBLE(kc1,kc2) / _LAYER_MOVE(kc,layer) / _LAYER_TOGGLE(kc,layer) / _FN / _FN_ADVANCED / _FN_ADVANCED_WITH_RELEASE。組み込みは前3つで、残りはC関数	C(tap_dance_actions[])
マクロ	QK_MACRO_n	tap/down/up/delay(+keymap.jsonではbeep)と文字列。VIAの保存形式は SS_TAP/DOWN/UP/DELAY_CODE を含むバイト列	keymap.json macros またはVIA(EEPROM)。VIA既定16個
Unicode Map	UM(i), UP(i,j)	コードポイント表	C(unicode_map[])
固有キーコード	QK_KB_n, QK_USER_n	任意のC処理	C(process_record_*)。keymap.json keycodes で名前宣言のみ可
Send String	(キーコードなし)	文字列送信。マクロやC処理から呼ぶ	C

C. キー以外の起動条件を持つ動作

機能	定義	主な設定
Combos	キーコード列(最大8、EXTRA_LONGで16)→出力キーコード	COMBO_TERM、per-combo: term/must_hold/must_tap/must_press_in_order、COMBO_STRICT_TIMER、COMBO_ONLY_FROM_LAYER / COMBO_REF_DEFAULT(参照レイヤー)、Modifier Combos、キー解放・再押下の扱い
Key Overrides	trigger, trigger_mods, layers(ビットマスク), negative_mod_mask, suppressed_mods, replacement, options(ko_option_t), custom_action, enabled	MODS_TO_NEUTRALIZE
Leader Key	QK_LEADER の後のキー列(1〜5キー)→C処理	LEADER_TIMEOUT、LEADER_PER_KEY_TIMING、LEADER_NO_TIMEOUT、STRICT_KEY_PROCESSING
Autocorrect	誤字→訂正の辞書(ビルド時にtrieへ変換)	辞書ファイル、MIN/MAX_LENGTH
Tri Layer	lower+upper → adjust レイヤー	3レイヤーの番号
Caps Word / Repeat Key / Layer Lock / Key Lock / Swap Hands	定義データはほぼなし。Swap Handsは hand_swap_config(マトリクス対応表)が必要	Caps Wordの継続キー判定等はC

D. タップ・ホールド等の挙動設定(docs/tap_hold.md 他)

全体設定(config.h / keyboard.jsonのconfig)とキーごとのコールバックの組で提供される。

設定	全体	キーごと
Tapping Term	TAPPING_TERM	TAPPING_TERM_PER_KEY → get_tapping_term(keycode, record)
Dynamic Tapping Term	DYNAMIC_TAPPING_TERM_ENABLE(キーで増減、揮発)	—
Permissive Hold	PERMISSIVE_HOLD	get_permissive_hold
Hold On Other Key Press	HOLD_ON_OTHER_KEY_PRESS	get_hold_on_other_key_press
Quick Tap Term	QUICK_TAP_TERM	get_quick_tap_term
Flow Tap(2025-05追加)	FLOW_TAP_TERM	is_flow_tap_key、get_flow_tap_term(keycode, record, prev_keycode)
Chordal Hold(2025-02追加)	CHORDAL_HOLD + 左右手の割り当て(chordal_hold_layout)	get_chordal_hold(tap_hold_keycode, …, other_keycode, …)
Retro Tapping	RETRO_TAPPING	get_retro_tapping
Speculative Hold(2025-11追加)	SPECULATIVE_HOLD	get_speculative_hold
Tapping Force Hold	—	get_tapping_force_hold
Tapping Toggle	TAPPING_TOGGLE(TTのタップ回数)	—
Auto Shift	AUTO_SHIFT_TIMEOUT 等	get_autoshift_timeout、get_auto_shifted_key、REPEAT/NO_AUTO_REPEAT_PER_KEY
One Shot	ONESHOT_TAP_TOGGLE、ONESHOT_TIMEOUT	—
Combo	COMBO_TERM	get_combo_term 等(コンボごと)
その他	TAP_CODE_DELAY、TAP_HOLD_CAPS_DELAY、DEBOUNCE	—

• キーごとのコールバックは keycode と keyrecord(押された位置・レイヤーを含む)を受ける。 つまり「キーコード単位」「物理位置単位」のどちらでも書ける(docs/tap_hold.md「Why do we include the key record」)。
• Chordal Holdの手の割り当ては物理位置(マトリクス)単位のデータ。

E. キー以外の入力への割り当て

機能	MAP相当のデータ	備考
Encoders	ENCODER_MAP: レイヤーごと・エンコーダごとの ccw/cw キーコード	keymap.json encoders。VIAで読み書き可(0x14/0x15)
DIP Switch	DIP_SWITCH_MAP: スイッチごとの on/off キーコード	keymap.json dip_switches(2025-11追加)。VIA不可
Pointing Device	Auto Mouse Layer(レイヤー番号・タイムアウト)、ドラッグスクロール等はC	センサー設定はハードウェア寄り
Joystick / Digitizer / MIDI / Steno / Programmable Button / Sequencer	キーコードでボタン・音等を割り当て。軸・プロトコル設定は全体	Stenoは0.0.9でキーコード改名

F. 実機の永続状態(quantum/eeconfig.h)

VIA管理外でEEPROMに保存されるもの: debug、keymap config(Magic: Ctrl/Caps入替、Caps→Ctrl、Alt/GUI入替、GUI無効、Grave/Esc、BSpc/BSlash、NKRO 他)、 default layer(PDF)、Unicode入力モード、audio、backlight、rgblight/rgb_matrix/led_matrix、haptic、steno mode、 handedness(EE_HANDS)、connection、kb/user固有データ、Community Modules の永続データ(1.1.3で追加)。 QMK本家VIAにはこれらを読み出すコマンドがない(9/23調査の再確認)。

MAP所有外の機能(参考の一覧)

• 照明: Backlight、RGBLight、RGB Matrix、LED Matrix、LED Indicators
• 表示: OLED、Quantum Painter(LVGL含む)、ST7565、HD44780
• 音・触覚: Audio、Haptic Feedback
• ハードウェア構成: Split Keyboard、Custom Matrix、Debounce、Converters、PS/2 Mouse、Wireless、Battery、USBPD
• ホスト連携: Raw HID、OS Detection、Secure、Command、Bootmagic、WPM、Deferred Exec、Virtser、Plover HID
• 拡張: Community Modules(1.1.3。modules/qmk/ に hello_world, super_alt_tab, split_data_sync, nvm_test, flow_*_matrix_effect)

VIA 0x000D の読み書き範囲(0.34.4で再確認)

9/23の journal(qmk-dynamic-scope)と同じコマンド構成。差分・補足:

• id_switch_matrix_state は既定で0を返す(上記)。
• id_eeprom_reset は VIA_EEPROM_ALLOW_RESET 定義時のみ有効。
• エンコーダは ENCODER_MAP_ENABLE 時のみ。
• 既定: DYNAMIC_KEYMAP_LAYER_COUNT 4、DYNAMIC_KEYMAP_MACRO_COUNT 16。上限はEEPROM容量に従う。

調査方法

• git clone --depth 1 --branch 0.34.4 --filter=blob:none --sparse で docs / quantum / data / builddefs を取得。
• 機能一覧: docs/_sidebar.json、builddefs/generic_features.mk の GENERIC_FEATURES。
• キーコード: data/constants/keycodes/keycodes_*.hjson をバージョン順にマージ。
• 変更点: docs/ChangeLog/20250223〜20260830。
• VIA移行PR: https://github.com/qmk/qmk_firmware/pull/26315(develop向けDraft。VIA_EEPROM_MAGIC_ADDR 以外は後方互換を維持する方針と記載)
• 実機での検証はしていない。