Beyond-KLE/keyboard-design-layers.md

Beyond KLE: キーボード設計レイヤー構造とツール設計方針

背景

KLEの問題点

• 物理配置と論理構造の混同: y座標や回転角度で行を判定するため、カラムスタッガードや曲線配列で大量の行が生成される
• データモデルの限界: 物理配置(PHY)のみを扱い、マトリックス座標やキーマップ情報を保持できない
• VIAのhackyな対応: ラベルフィールドに"1,5"と入れてmatrix:[1,5]を表現

設計思想

• 「Better KLE」ではなく「Beyond KLE」: UIではなくデータモデルとワークフロー全体の再設計
• UNIX哲学の適用: 小さな役割のツールがそれぞれしっかり機能する
• 統合環境(IDE)の提供: 独立したツール群をオーケストレート

レイヤー構造

レイヤーは一列に積み上がらない。ELC・IDX・MAPはそれぞれ独立にPHYを参照する。 ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照しない。 他レイヤーからキーや部品を指す参照には、PHYのノードIDを使う。

1. PHYレイヤー (物理配置)

• 役割: キーと部品の物理的な位置、サイズ、回転
• 対応ツール: PCBエディタ、KLE
• 出力: 相対座標の木(キー・クラスター・部品ノード・バリアントノード)。各ノードはIDを持つ
• 備考: 交換可能なレイアウト(ISO Enter等)は全パターンを同時に持ち、外部出力時に1つ選んで畳む

2. ELCレイヤー (電気配線)

• 役割: ピン提供者が提供する論理ピンと、各キーの端子・LEDの対応
• 入力: PHYのノードID
• 対応ツール: 回路図エディタ、ファームウェア
• 出力: 提供者定義、キーごとの端子の接続先、LEDチェーン
• 備考: 配線方式(マトリクス / direct / charlieplexing)を区分として選ばせず、端子の接続先の組み合わせとして表すため、非標準的な実装も同じ形で書ける
• 備考: row / col は正本に持たない。QMKなどが要求する形は出力時に割り当てる

3. IDXレイヤー (キー識別)

• 役割: 全バリアントにわたるPHYのキーの並び順を保存し、選択した構成の出力用キー番号を決める
• 入力: PHYのキーID
• 対応ツール: QMKの LAYOUT マクロ、ZMKの matrix transform、KMKの coord_mapping
• 出力: 全バリアントの対象キーIDを重複なく並べた order。出力時に対象外のキーを除き、0から連続する番号を与える
• 備考: キー番号はPHYの幾何からもELCの配線からも導出しない(導出すると、幾何の編集や再配線でキーマップがずれる)
• 備考: 並び順を正本として保存する。出力番号は公開インターフェースであり、互換性は出力レイアウトごとに扱う
• 備考: マトリックス座標とLEDの識別番号はIDXが持たない(どちらも配線で決まるためELCが持つ)
• 備考: 全バリアントで1つのIDXを持つ。同じ接続先に配線された排他キーも別々の要素とし、選択後の出力で番号を詰める。保存した order は変えない
• 備考: 既存のエコシステムでは、この並びが LAYOUT マクロの引数順などとして手書きされている。欠けている層ではなく、形式化されていない層

4. MAPレイヤー (キーマップ)

• 役割: キーマップレイヤーごとのキーへの割り当て
• 入力: PHYのキーID
• 対応ツール: MAPエディタ (Keymap Designer)
• 出力: MAP JSON (現行形式はレイヤー別キーコード割り当て)
• 備考: キーの参照にPHYのキーIDを使う。配列としての並べ替えは、出力時にバリアント選択後のIDXの並び順で行う
• 詳細: MAPレイヤー。動作定義とキーごとの設定の保存形式は、MAPのP-1で扱う

5. HSTレイヤー (ホスト)

• 役割: 接続先のホスト(OSとキーボード配列の設定)が、キーコードをどう解釈するかの記述
• 入力: なし。どの層も参照せず、MAPエディタとFirmware Generatorから参照される
• 対応ツール: OSのキーボード配列、QMKの言語別キーコード(keymap_japanese.h など)
• 出力: ホスト環境ごとのプロファイル。キーボードに依存しない共有カタログとする
• 備考: IMEのかな漢字変換はOSの責務で、HSTの対象外
• 詳細: HSTレイヤー

ツール設計方針

個別ツール (独立動作可能)

PHY Editor

• 物理配置の視覚的編集
• KLE JSONの読み込み・書き出し
• 出力: PHY JSON

Key Indexer

• PHY JSONを入力
• 全バリアントの対象キーを1つの並びに配置
• 出力: IDX JSON

Wiring Editor

• PHY JSONを入力
• ピン提供者(マイコン、マルチプレクサ等)を置き、各キーの端子の接続先を指定
• 視覚的に配線を確認
• 出力: ELC JSON

Keymap Designer (MAPエディタ)

• PHYの配置を参照し、キーマップレイヤーごとの割り当てを編集・保存する
• 新規キーボードの設計から実機での調整までを扱い、割り当ての読み書きを一組で提供する
• 実機との通信は既存のVIAプロトコルから対応し、対象を段階的に増やす
• 出力: MAP JSON

具体的な責務と通信上の制約は、MAPレイヤーに従う。

Firmware Generator

• 全レイヤーの情報を統合
• バリアントを選択し、IDXから対象外のキーを除いた並びで、キー番号の対応表とMAPの配列を生成
• row / col など、ターゲットが要求する派生情報をここで割り当てる
• QMK/VIA/KMK等へ変換
• VIA向けキーボード定義は、配置と接続先の対応などを統合して生成する
• 出力: ターゲット固有の設定ファイル

統合環境 (IDE)

• プロジェクトファイル: 全レイヤーの状態を一元管理
• リアルタイムプレビュー: レイヤー間の依存関係を可視化
• バージョン管理統合: テキストベース定義でgit管理
• ワークフローサポート: ガイド付きウィザード、テンプレート

ビルド・ファームウェアの書き込みは、MAP編集とは別の実行機能として扱う。 同じ画面から各ツールを利用できることと、各レイヤーがそのデータや処理を所有することは区別する。

プロトコル設計

レイヤー間インターフェース

PHY → ELC
  Input:  ノードID + 配置
  Output: 提供者定義 + 端子の接続先 + LEDチェーン

PHY → IDX
  Input:  キーID + 配置
  Output: 全バリアントの対象キーIDの並び

PHY → MAP
  Input:  キーID
  Output: MAP JSON (現行形式はレイヤー別キーコード割り当て)

All → Firmware
  Input: 各レイヤーのデータ + バリアント選択
  Output: QMK keyboard.json / VIA JSON / KMK .py

データフォーマット

• JSON Schema で各レイヤーの入出力を定義
• 後方互換性の維持 (KLE JSONからのインポート)
• 拡張可能な設計 (3D配置、非標準マトリックス対応)

実装戦略

Phase 1: プロトコル策定

• JSON Schemaでフォーマット定義
• リファレンス実装(言語・構成は implementation-plan.md で選定)
• CLIツールとして動作確認

Phase 2: 個別ツール開発

• 各レイヤー用エディタを独立開発
• 既存ツールからのインポート機能
• 単独利用可能な設計

Phase 3: IDE統合

• Electron/Tauri or Webアプリ
• プロジェクト管理機能
• ワークフロー支援

既存ツールとの関係

• KLE: PHYデータを表示できる既存のビュワー。KLE JSONの読み書きで連携する
• VIA/Remap: 同じVIA対応実機の割り当てを編集する外部クライアント。外部で調整した結果もMAPエディタで読み出してプロジェクトへ戻す。読み書きする項目はMAP「VIAで読み書きする項目」、実機との対応・状態管理はMAPのP-3で扱う
• QMK Configurator: Firmware Generatorのターゲット

配慮事項

学習コスト

• テンプレートプロジェクト提供 (60%, Split等)
• 簡易モード/詳細モードの切り替え
• 段階的な機能開示

互換性

• 既存KLE JSONの読み込み(PHYデータがなくても読める)
• 段階的移行パスの提供
• レガシーツールとの共存

次のステップ

1. プロトコル仕様ドラフト作成
2. GitHubでRFCリポジトリ立ち上げ
3. 小規模コミュニティでフィードバック収集
4. リファレンス実装の開発

未確認事項

P-1 アナログ値の解釈をどの層が持つか

• 位置づけ: 未解決の問い。ELCは配線だけを持つと決めたため、生値から押下深さを出す変換の置き場が空いている
• 現状の認識: センサの品種と出力特性はPCB設計ツール側、キャリブレーションは実機ごとの実測値で設計データではない、とまでは決まっている。残りをMAPに寄せるか、別の層を立てるかは未定
• 格上げ条件: アナログ入力のキーボードを1つ通しで設計し、変換に必要な情報と、それを置く層をユーザーが決める