# 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 以外は後方互換を維持する方針と記載)
- 実機での検証はしていない。