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はそれぞれ独立にPHYを参照する。 ELCはIDXを参照せず、IDXもELCを参照しない。 他レイヤーからキーや部品を指す参照には、PHYのノードIDを使う。

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

• 役割: キーと部品の物理的な位置、サイズ、回転
• 対応ツール: PCBエディタ、KLE
• 出力: 相対座標の木(キー・クラスター・部品ノード)。各ノードはIDを持つ

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

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

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

• 役割: PHYのキーと"キー番号"の対応付け
• 入力: PHYのキーID
• 重要性: 物理世界と論理世界を繋ぐ最も重要な抽象化層
• 出力: キーIDとキー番号の対応
• 備考: 現状のエコシステムで最も欠けている層
• 備考: マトリックス座標とLEDの識別番号はIDXが持たない(どちらも配線で決まるためELCが持つ)

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

• 役割: キー番号とキーコードの対応
• 対応ツール: ファームウェア、VIA、Remap
• 出力: レイヤー別キーコード配列

5. IMEレイヤー (入力変換)

• 役割: キーコードと実際の入力文字の対応
• 対応ツール: OS
• 備考: MAPレイヤー設計時に考慮が必要

ツール設計方針

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

PHY Editor

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

Key Indexer

• PHY JSONを入力
• キーにキー番号を割り当て
• 出力: IDX JSON

Wiring Editor

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

Keymap Designer

• キー番号のリストを入力
• レイヤー別キーコード割り当て
• VIA/Remapとの互換性
• 出力: MAP JSON

Firmware Generator

• 全レイヤーの情報を統合
• row / col など、ターゲットが要求する派生情報をここで割り当てる
• QMK/VIA/KMK等へ変換
• 出力: ターゲット固有の設定ファイル

統合環境 (IDE)

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

プロトコル設計

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

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

PHY → IDX
  Input:  キーID + 配置
  Output: キーIDとキー番号の対応

IDX → MAP
  Input:  キー番号のリスト
  Output: レイヤー別キーコード配列

All → Firmware
  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: MAP Layerクライアントとして連携
• QMK Configurator: Firmware Generatorのターゲット

配慮事項

学習コスト

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

互換性

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

次のステップ

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

未確認事項

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

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