diff --git a/MAPレイヤー.md b/MAPレイヤー.md index 900a05d..0e66b48 100644 --- a/MAPレイヤー.md +++ b/MAPレイヤー.md @@ -65,6 +65,7 @@ MAPエディタはDynamicの読み書きを提供する。Dynamicで変更でき QMKはVIAをCommunity Modulesの形式へ移し、従来の実装を将来のリリースで削除すると告知している(QMK 0.34.4のChangeLog「VIA Feature Migration」)。 VIAがモジュールへ移っても、QMKとVIAの両方に追従する。そのため、移行がmasterに入る前に、VIAモジュールを有効にした出力と読み書きに対応する。 + - キーボード・キーマップ固有のコード(VIAのキーボード独自メニューを含む)には、原則として対応しない。 Staticで定義する動作(タップダンス等)をキーへ割り当てるときは、定義を名前で参照し、出力時に番号へ変換する。 @@ -95,8 +96,9 @@ MAPエディタのUIには、対応しているVIAプロトコルとキーコー 接続した実機とはこの2つのバージョンで照合し、一致しない実機には対応しない。 実機から取得できるバージョン情報がこの2つに限られるため。 -最初に対応するQMKのコミット、キーコード体系、編集項目の範囲は、 -[P-2](#p-2-viaの初期対応範囲)で扱う。 +最初に対応する環境は、QMK 0.34.4(commit `08c662f`)とする。このときキーコード体系は0.0.9、VIAプロトコルは0x000D。 +VIAは同梱の従来実装(`quantum/via.c`)で、追加のモジュールは使わない。 +レイヤー別の割り当て以外に読み書きする項目は、[P-2](#p-2-viaの初期対応範囲)で扱う。 ## 持たないもの @@ -129,8 +131,8 @@ MAPエディタは、キーコードを当面US配列の文字で表示する。 ### P-2 VIAの初期対応範囲 - 位置づけ: VIA通信と編集UIの実装に必要な対応範囲の判断。 -- 未決事項: 最初に対応するQMKのコミット、キーコード体系、レイヤー別割り当て以外に読み書きする項目、対象ファームウェアの機能・容量制約の確認方法。 -- 完了条件: 対象バージョンと読み書きする項目を定め、対応する新規キーボードの構成で必要なコマンドと制約を確認する。 +- 未決事項: レイヤー別割り当て以外に読み書きする項目、対象ファームウェアの機能・容量制約の確認方法。 +- 完了条件: 読み書きする項目を定め、対応する新規キーボードの構成で必要なコマンドと制約を確認する。 ### P-3 プロジェクトと実機の対応・状態管理 diff --git a/journal/2026-09-24-qmk-feature-inventory.md b/journal/2026-09-24-qmk-feature-inventory.md new file mode 100644 index 0000000..a45e56c --- /dev/null +++ b/journal/2026-09-24-qmk-feature-inventory.md @@ -0,0 +1,162 @@ +# 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 以外は後方互換を維持する方針と記載) +- 実機での検証はしていない。