Beyond-KLE/MAPレイヤー.md

MAPレイヤー

概要

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

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

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

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

現行の保存形式は、JSON SchemaのMAP節にある レイヤー別のキーコード割り当てを出発点とする。 動作定義と保存形式の拡張範囲は、P-1で扱う。

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

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

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

MAPエディタの責務

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

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

DynamicとStatic

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

MAPエディタはDynamicの読み書きを提供する。Dynamicで変更できる範囲は、 対象ファームウェアと既存プロトコルが公開する範囲に従う。 Staticで扱う動作定義の範囲と、Dynamicで変更できない設定の扱いは、 P-1で扱う。

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

対応プロトコル

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

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

対応するVIAプロトコルのバージョン、キーコード体系、編集項目の範囲は、 P-2で扱う。

持たないもの

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

アナログ入力の解釈の所属は、全体方針のP-1で扱う。

保留課題

• PHYの保留課題

検討済み・非採用

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

未確認事項

P-1 割り当てる動作と保存形式の範囲

• 位置づけ: MAPのデータモデルを定めるための設計判断。
• 未決事項: キーコード割り当てに加え、タップ／ホールド、コンボ、マクロ等の定義・設定をどこまで扱うか。Staticで扱う範囲、ファームウェア共通表現と固有表現の境界も未定。
• 完了条件: 初期対応する動作と設定、その保存形式、Static出力とDynamic読み書きでの扱いをユーザーが決める。

P-2 VIAの初期対応範囲

• 位置づけ: VIA通信と編集UIの実装に必要な対応範囲の判断。
• 未決事項: 対応プロトコルのバージョン、キーコード体系、レイヤー別割り当て以外に読み書きする項目、対象ファームウェアの機能・容量制約の確認方法。
• 完了条件: 対象バージョンと読み書きする項目を定め、対応する新規キーボードの構成で必要なコマンドと制約を確認する。

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

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