ewdernaandClaude Opus 5
2eb2867c13
キー番号はPHYの幾何からもELCの配線からも導出できない決めごとなので、IDXが正本を持つ。 公開した基板のキー番号は他人のキーマップが依存する公開インターフェースであり、 出力のたびに生成し直さず固定する。 「最も重要な抽象化層」「最も欠けている層」という位置づけは誤りだったので落とした。 QMKのLAYOUTマクロの引数順、ZMKのmatrix transformのmap、KMKのcoord_mappingとして 既に存在していて、形式化されていないだけである。 あわせて2点。MAPはキー番号ではなくPHYのキーIDを参照する(IDXへの挿入でMAPがずれないため)。 IDXの保存形式は order: string[] とし、ELCのLEDChain.orderと同じく並びの位置を番号とする。 phase1-json-schema.md の P-1 を解消。 Journal: journal/2026-09-21-idx-necessity.md Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
7.1 KiB
7.1 KiB
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を持つ
2. ELCレイヤー (電気配線)
- 役割: ピン提供者が提供する論理ピンと、各キーの端子・LEDの対応
- 入力: PHYのノードID
- 対応ツール: 回路図エディタ、ファームウェア
- 出力: 提供者定義、キーごとの端子の接続先、LEDチェーン
- 備考: 配線方式(マトリクス / direct / charlieplexing)を区分として選ばせず、端子の接続先の組み合わせとして表すため、非標準的な実装も同じ形で書ける
- 備考: row / col は正本に持たない。QMKなどが要求する形は出力時に割り当てる
3. IDXレイヤー (キー識別)
- 役割: PHYのキーに"キー番号"を与える
- 入力: PHYのキーID
- 対応ツール: QMKの
LAYOUTマクロ、ZMKの matrix transform、KMKのcoord_mapping - 出力: 番号を振るキーの並び。並びの位置がキー番号
- 備考: キー番号はPHYの幾何からもELCの配線からも導出しない(導出すると、幾何の編集や再配線でキーマップがずれる)
- 備考: キー番号は公開インターフェースであり、出力のたびに生成し直さず固定する
- 備考: マトリックス座標とLEDの識別番号はIDXが持たない(どちらも配線で決まるためELCが持つ)
- 備考: 既存のエコシステムでは、この並びが
LAYOUTマクロの引数順などとして手書きされている。欠けている層ではなく、形式化されていない層
4. MAPレイヤー (キーマップ)
- 役割: キーとキーコードの対応
- 入力: PHYのキーID
- 対応ツール: ファームウェア、VIA、Remap
- 出力: レイヤー別キーコード
- 備考: キーの参照にキー番号を使わない。配列としての並べ替えは、出力時にIDXの並び順で行う
5. IMEレイヤー (入力変換)
- 役割: キーコードと実際の入力文字の対応
- 対応ツール: OS
- 備考: MAPレイヤー設計時に考慮が必要
ツール設計方針
個別ツール (独立動作可能)
PHY Editor
- 物理配置の視覚的編集
- KLE JSONの読み込み・書き出し
- 出力: PHY JSON
Key Indexer
- PHY JSONを入力
- キーにキー番号を割り当て
- 出力: IDX JSON
Wiring Editor
- PHY JSONを入力
- ピン提供者(マイコン、マルチプレクサ等)を置き、各キーの端子の接続先を指定
- 視覚的に配線を確認
- 出力: ELC JSON
Keymap Designer
- PHY JSONを入力
- レイヤー別キーコード割り当て
- 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の並び
PHY → MAP
Input: キーID
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データがなくても読める)
- 段階的移行パスの提供
- レガシーツールとの共存
次のステップ
- プロトコル仕様ドラフト作成
- GitHubでRFCリポジトリ立ち上げ
- 小規模コミュニティでフィードバック収集
- リファレンス実装の開発
未確認事項
P-1 アナログ値の解釈をどの層が持つか
- 位置づけ: 未解決の問い。ELCは配線だけを持つと決めたため、生値から押下深さを出す変換の置き場が空いている
- 現状の認識: センサの品種と出力特性はPCB設計ツール側、キャリブレーションは実機ごとの実測値で設計データではない、とまでは決まっている。残りをMAPに寄せるか、別の層を立てるかは未定
- 格上げ条件: アナログ入力のキーボードを1つ通しで設計し、変換に必要な情報と、それを置く層をユーザーが決める