# QMKでのDynamic/Staticの対応範囲

## 結論

当面の対象ファームウェアはQMK。
- Dynamic: QMK本家のVIAプロトコルが公開する項目のみ
- Static: QMK本家の公式機能のうちVIAで変更できないものは、Firmware Generatorで生成する対象
- 非公式機能(Vial等のフォーク、XAP等のmaster以外のブランチ)は当面非対応
- developブランチ・Community Modulesは当面非対応(将来広げたい→backlog MAP-P-6)。キーボード・キーマップ固有コードは原則非対応
- 対応QMKは特定コミットに固定し、更新タイミングはユーザーが個別に判断する
- UIにはVIAプロトコルとキーコード体系のバージョンを表示し、実機とはこの2つで照合。不一致の実機は非対応
  (当初はUIにコミットを出す案だったが、実機から取れるのがこの2つだけなのでユーザーがバージョン表記に変更)
- Staticで定義する動作(タップダンス等)はキーから名前で参照し、出力時に番号へ変換する
- VIA管理外のEEPROM設定は読み出せない旨を制約として明記

どこまでを初期対応するか(P-1)、最初に対応するコミット(P-2)は未決。

## 案の比較

| 案 | 扱い |
| --- | --- |
| DynamicはQMK本家VIAのみ、他の公式機能はStatic | 採用(ユーザー指定) |
| VialでDynamicの範囲を広げる(タップダンス・コンボ・QMK Settings等) | 当面非対応(フォークのため) |
| XAP | 当面非対応(master外) |
| QMKの最新へ自動追従 | 採用しない。ユーザーが恣意的に更新時期を決める |

## 調査結果(2026-09-23時点のソース)

実機での検証はしていない。

### A. QMK本家 VIA
参照: https://raw.githubusercontent.com/qmk/qmk_firmware/master/quantum/via.h
VIA_PROTOCOL_VERSION = 0x000D

command:
- 0x01 get_protocol_version
- 0x02/0x03 get/set_keyboard_value
  - 0x01 uptime(get), 0x02 layout_options(get/set), 0x03 switch_matrix_state(get),
    0x04 firmware_version(get), 0x05 device_indication(set), 0x06 keycodes_version(get)
- 0x04/0x05 dynamic_keymap_get/set_keycode (layer,row,col)
- 0x06 dynamic_keymap_reset
- 0x07/0x08/0x09 custom_set/get_value, custom_save
  - channel 0 custom(キーボード独自メニュー)
  - 1 backlight: brightness, effect
  - 2 rgblight: brightness, effect, effect_speed, color
  - 3 rgb_matrix: brightness, effect, effect_speed, color
  - 4 audio: enable, clicky_enable
  - 5 led_matrix: brightness, effect, effect_speed
- 0x0A eeprom_reset
- 0x0B bootloader_jump
- 0x0C..0x10 dynamic_keymap_macro_get_count / get_buffer_size / get_buffer / set_buffer / reset
- 0x11 dynamic_keymap_get_layer_count
- 0x12/0x13 dynamic_keymap_get/set_buffer
- 0x14/0x15 dynamic_keymap_get/set_encoder

MAPに関係するもの: キーコード、レイヤー数、エンコーダ、マクロ、layout_options。
照明・オーディオはMAPの所有データ外(MAPレイヤー.md「持たないもの」)。

### B. Vial(フォーク、今回非対応)
参照: https://raw.githubusercontent.com/vial-kb/vial-qmk/vial/quantum/vial.h
参照: https://raw.githubusercontent.com/vial-kb/vial-qmk/vial/quantum/qmk_settings.c
VIAL_PROTOCOL_VERSION = 6

- keyboard_id、圧縮キーボード定義JSONの取得(get_size/get_def)
- unlock/lock(物理キー押下による解除)
- dynamic entry: tap dance, combo, key override, alt repeat key
- 拡張マクロ(EXT_TAP/DOWN/UP)
- QMK Settings (QSID):
  1 grave_esc_override, 2 combo_term, 3 auto_shift, 4 auto_shift_timeout,
  5 osk_tap_toggle, 6 osk_timeout, 7 tapping_term, 9-17 mousekey各種(MK_3_SPEED以外),
  18 tap_code_delay, 19 tap_hold_caps_delay, 20 tapping_toggle,
  21 magic_settings(Ctrl/Caps, Alt/GUI, Ctrl/GUI, Grave/Esc, BSpc/BSlash入替, GUI無効, NKRO),
  22 permissive_hold, 23 hold_on_other_key_press, 24 retro_tapping,
  25 quick_tap_term, 26 chordal_hold, 27 flow_tap_term
- VialRGB(RGB Matrixエフェクト列挙・設定)。ソース未確認

### C. プロトコル外で実機上だけ変わるもの(Dynamicの定義外)
当初「すべてEEPROMに保存される」と書いたが誤り。確認結果:
- 保存されない(再起動で消える): ダイナミックマクロ(docs/features/dynamic_macros.md
  "lost when the keyboard is unplugged or otherwise rebooted")、DT_UP/DT_DOWN(docs/tap_hold.md "*not* persistent")
- EEPROMに保存される(quantum/eeconfig.h): keymap config(Magic)、default layer、unicode mode、audio、backlight、
  rgblight/rgb_matrix/led_matrix、haptic、steno mode、handedness、connection、kb/user固有データ
- QMK本家via.cにはこれらを読み出すコマンドがない。照明・オーディオはcustom channel 1〜5で読めるがMAPの所有外。
  custom channel 0はweakの via_custom_value_command_kb() へ流れる(キーボード固有コード、原則非対応)。
- 参考: via_eeprom_is_valid() はビルド日時由来のmagicで検証し、不一致ならVIAのデータ(キーマップ・マクロ・layout options)を
  初期化する。再ビルドして書き込むとDynamicの変更は消える前提になる。

### XAP
QMK公式の次世代プロトコルとして開発されていたが、masterには入っていない認識。未確認。