Beyond-KLE/MAPレイヤー.md

# MAPレイヤー

## 概要

MAPレイヤーは、キーマップレイヤーごとのキーへの割り当てを持つ。
MAPエディタは、その設計・編集と、実機との読み書きを提供する。
ここでいうキーマップレイヤーは、PHY・ELC等の設計レイヤーとは区別する。

主眼は、新しく作成するキーボードのワークフローにある。
キーマップを設計し、実機へ反映し、使って調整した結果をプロジェクトへ戻せるようにする。
既存キーボード全般への接続・取り込みを、初期対応の前提にはしない。

## MAPデータと他レイヤーの関係

キー参照と出力時の並べ替えは、[IDXレイヤー「他レイヤーとの関係」](IDXレイヤー.md#他レイヤーとの関係)に従う。
MAPのキー参照にはPHYのキーIDを使い、実機との通信に使うアドレスを正本のキー参照にはしない。

現行の保存形式は、[JSON SchemaのMAP節](phase1-json-schema.md#4-mapレイヤー-json-schema)にある
レイヤー別のキーコード割り当てを出発点とする。
キーコードはQMKの表記を基本とする。当面の対象ファームウェアがQMKであるため。
レイヤーとStaticの動作定義への参照は、QMKの番号ではなく名前で書く([DynamicとStatic](#dynamicとstatic))。

ファームウェアの設定値は、キーボード全体に効くものをFirmware Generatorの設定とし、
キーごとに上書きする値(tapping termのper key設定等)をMAPが持つ。
QMKの機能ごとにどちらに属するかを個別に判断しないで済むようにするため。

動作定義とキーごとの設定の保存形式は、[P-1](#p-1-動作定義とキーごとの設定の保存形式)で扱う。

新規作成したMAPは、すべてのキーが未割り当ての状態から始める。
PHYのラベルからの自動適用は行わない([PHY「ラベル」](PHYレイヤー.md#ラベル))。

## キーマップレイヤーの識別

キーマップレイヤーは、並び順と独立した名前で識別する。名前はMAP内で一意とする。
レイヤーを切り替える動作も名前でレイヤーを参照し、番号へは出力時に並び順から変換する。
レイヤーの並べ替えや挿入で参照先がずれないようにするため。IDXがキー番号を正本にしないのと同じ理由による。

## MAPエディタの責務

- PHYの配置を参照し、キーマップレイヤーごとの割り当てを編集・保存する。
- 対応する実機へ割り当てを書き込み、実機の現在の割り当てを読み出す。
- 実機で使いながら調整し、その結果をMAPへ取り込むワークフローを提供する。

読み書きは一組として対応する。読み出しには、現在値の確認に加え、Remap等で調整した結果を
プロジェクトへ戻す用途も含む。保存と実機への反映の操作、差分表示、自動同期の有無は、
[P-3](#p-3-プロジェクトと実機の対応状態管理)で扱う。

## DynamicとStatic

Dynamicは、対応ファームウェアが公開している通信プロトコルを使って、再ビルドせずに設定を読み書きする経路。
Staticは、設定をファームウェアへ組み込むために出力する経路とする。
Staticの出力は[全体方針のFirmware Generator](keyboard-design-layers.md#firmware-generator)が担い、MAPエディタは持たない。

MAPエディタはDynamicの読み書きを提供する。Dynamicで変更できる範囲は、
対象ファームウェアと既存プロトコルが公開する範囲に従う。

当面の対象ファームウェアはQMKとし、対応範囲を次のように分ける。

- Dynamic: QMK本家のVIAプロトコルが公開する項目に限る。
- Static: QMK本家masterの公式機能のうちVIAで変更できないものは、Firmware Generatorで生成する対象とする。
- 次のものには当面対応しない。
    - Vial等のフォーク
    - XAP、developブランチ等、master以外にある機能
    - Community Modules(VIAモジュールを除く)

QMKはVIAをCommunity Modulesの形式へ移し、従来の実装を将来のリリースで削除すると告知している(QMK 0.34.4のChangeLog「VIA Feature Migration」)。
VIAがモジュールへ移っても、QMKとVIAの両方に追従する。そのため、移行がmasterに入る前に、VIAモジュールを有効にした出力と読み書きに対応する。

- キーボード・キーマップ固有のコード(VIAのキーボード独自メニューを含む)には、原則として対応しない。

Staticで定義する動作(タップダンス等)をキーへ割り当てるときは、定義を名前で参照し、出力時に番号へ変換する。
割り当て自体はVIAで読み書きできても、参照先の定義はStaticにしかないため、
[レイヤーの参照](#キーマップレイヤーの識別)と同じく並び順に依存させない。

QMK本家のVIAには、VIAの管理外にある実機の保存設定(Magic設定、保存されたデフォルトレイヤー、Unicodeの入力モード等)を読み出す手段がない。
これらを実機で変更しても、MAPエディタはプロジェクトへ取り込めない。

プロジェクトのMAP、Staticで組み込んだ初期キーマップ、実機に保存された現在の割り当ては区別する。
実機で調整してMAPへ取り込んだ割り当ては、Firmware Generatorへの入力としてStaticの初期キーマップへ反映できるようにする。
実機の保存内容を初期化しても、調整後の割り当てに戻せるようにするため。

## 対応プロトコル

最初に対応する通信プロトコルはVIAとし、対応プロトコルを絞って段階的に増やす。
ユーザーが好むRemapと同じ通信経路を使い、新規キーボードの設計から実機での調整へつなぐため。

- QMKやVial側にBeyond KLE独自のプロトコルを追加しない。そのためのファームウェアのフォークも行わない。
- VIA対応では、対象ファームウェアの既存のVIA機能を使って読み書きする。
- VIAへの対応は、Remapというアプリ全体の機能を再現することを意味しない。
- 初期の実装対象はVIAに限る。

対応環境は、QMKのコミットと、使うモジュールの一覧(各モジュールの出所とコミット)で固定し、
更新するタイミングはユーザーが個別に判断する。QMKに同梱されたモジュールは、QMKのコミットで決まる。
VIAもモジュールの1つとして扱い、QMKリポジトリの外へ移った場合にも同じ形で指定できるようにするため。
MAPエディタのUIには、対応しているVIAプロトコルとキーコード体系のバージョンを明示する。
接続した実機とはこの2つのバージョンで照合し、一致しない実機には対応しない。
実機から取得できるバージョン情報がこの2つに限られるため。

最初に対応する環境は、QMK 0.34.4(commit `08c662f`)とする。このときキーコード体系は0.0.9、VIAプロトコルは0x000D。
VIAは同梱の従来実装(`quantum/via.c`)で、追加のモジュールは使わない。

## VIAで読み書きする項目

VIAプロトコル0x000Dのコマンドのうち、MAPエディタが扱うものを次のように分ける[推測:P-2]。

- 対応する:
    - VIAプロトコルとキーコード体系のバージョンの読み出し(実機との照合に使う)
    - レイヤー数の読み出し
    - レイヤー別のキーコード割り当ての読み書き
    - マクロの読み書き(個数・容量の読み出しとリセットを含む)
- 別の課題で扱う:
    - エンコーダの割り当て([MAP-P-4](backlog/README.md#map-p-4-onoff以外の入力への割り当て))
    - layout option([P-3](#p-3-プロジェクトと実機の対応状態管理))
- 当面対応しない: キーマップ・EEPROMのリセット、ブートローダへの移行、デバイスの識別表示、
  マトリクス状態の読み出し(キーテスター)、custom channel(照明・オーディオ・キーボード独自メニュー)

実機のファームウェアでどの機能が有効かは、VIAでは読み出せない。
新規キーボードではFirmware Generatorのビルド設定を正とする。既存キーボードでは、利用者が同じ形式で申告した内容を信用する。
レイヤー数、マクロの個数と容量は実機から読み出し、書き込む前にMAPの内容が収まるかを確認する。

## 持たないもの

物理配置、配線、キーの出力番号は、それぞれPHY・ELC・IDXで扱う。
OS配列やIMEの入力変換はIME側の責務とし、外部ツールで編集できる照明等の設定も、
VIAで通信できるという理由だけでMAPの所有データには含めない。
MAPエディタは、キーコードを当面US配列の文字で表示する。

アナログ入力の解釈の所属は、[全体方針のP-1](keyboard-design-layers.md#p-1-アナログ値の解釈をどの層が持つか)で扱う。

## 保留課題

- [MAPの保留課題](backlog/README.md#map)
- [PHYの保留課題](backlog/README.md#phy)

## 検討済み・非採用

- MAPエディタをStaticに閉じる (journal/2026-09-22-map-via-workflow.md)

## 未確認事項

### P-1 動作定義とキーごとの設定の保存形式

- 位置づけ: MAPのデータモデルを定めるための設計判断。
- 未決事項:
    - マクロ(VIAで読み書きするため内容をMAPが持つ)と、タップダンス・コンボ等のStaticで定義する動作を、MAPにどう保存するか。
    - キーごとに上書きする設定を、PHYのキー、キーとレイヤーの組、キーコードのどれに付けるか。
- 完了条件: 動作定義とキーごとの設定の保存形式をユーザーが決める。

### P-2 VIAのコマンドはQMK 0.34.4のソースどおりに動作する

- 位置づけ: 本文「VIAで読み書きする項目」が前提にしている。コマンドの内容はソース(`quantum/via.c`)と公式文書から確認したもので、実機では検証していない。
- 格上げ条件: QMK 0.34.4でビルドした新規キーボードの構成で、対応するコマンドの読み書きと、レイヤー数・マクロの個数と容量の読み出しを実機で確認する。

### P-3 プロジェクトと実機の対応・状態管理

- 位置づけ: 実機への読み書きをMAPへ結び付けるための設計判断。
- 未決事項:
    - 出力した構成とPHYキーID・通信上のアドレスの対応をどこに保持し、接続した実機とどう照合するか。
    - VIAの割り当ては接続先(row/col)単位で保存されるため、同じ接続先に配線された排他キーは、実機では1つの割り当て先を共有する。書き込み時に選択外のバリアントのキーの割り当てをどう扱うか、読み出した値をどのPHYキーへ戻すか(実機側のlayout optionの選択に従うか)。
    - バリアントや配線の変更後の扱い。
    - プロジェクトと実機、プロジェクトとStaticで組み込んだ初期キーマップの差分表示・保存・反映の操作。
- 完了条件: 対応情報の生成・保存・照合方法と状態管理を定め、設計から実機へ反映し、Remap等での変更を元のPHYキーIDへの割り当てとして取り込む手順を確認する。排他キーを含む構成で、書き込みと読み出しがバリアントの選択に従って元のPHYキーへ対応することを確認する。