ewdernaandClaude Opus 5.5
49b023ceaa
- キーコードはQMKの表記を基本とし、レイヤーとStatic定義は名前で参照する - キーボード全体の設定値はFirmware Generator、キーごとの上書きはMAPが持つ。QMKの機能ごとに所属を判断しないため - P-1を動作定義とキーごとの設定の保存形式に絞り、初期対応範囲の問いを削除する - QMK以外のファームウェアでのキーコード表記をMAP-P-8としてbacklogへ Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P4UAjpgV7DLqJqF3sEf1bi
199 lines
9.3 KiB
Markdown
199 lines
9.3 KiB
Markdown
# 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レイヤー.md)。動作定義とキーごとの設定の保存形式は、[MAPのP-1](MAPレイヤー.md#p-1-動作定義とキーごとの設定の保存形式)で扱う
|
|
|
|
### 5. IMEレイヤー (入力変換)
|
|
|
|
- **役割**: キーコードと実際の入力文字の対応
|
|
- **対応ツール**: OS
|
|
- **備考**: MAPレイヤー設計時に考慮が必要
|
|
|
|
## ツール設計方針
|
|
|
|
### 個別ツール (独立動作可能)
|
|
|
|
#### 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レイヤー](MAPレイヤー.md#mapエディタの責務)に従う。
|
|
|
|
#### Firmware Generator
|
|
|
|
- 全レイヤーの情報を統合
|
|
- バリアントを選択し、IDXから対象外のキーを除いた並びで、キー番号の対応表とMAPの配列を生成
|
|
- row / col など、ターゲットが要求する派生情報をここで割り当てる
|
|
- QMK/VIA/KMK等へ変換
|
|
- VIA向けキーボード定義は、配置と接続先の対応などを統合して生成する
|
|
- 出力: ターゲット固有の設定ファイル
|
|
|
|
### 統合環境 (IDE)
|
|
|
|
- **プロジェクトファイル**: 全レイヤーの状態を一元管理
|
|
- **リアルタイムプレビュー**: レイヤー間の依存関係を可視化
|
|
- **バージョン管理統合**: テキストベース定義でgit管理
|
|
- **ワークフローサポート**: ガイド付きウィザード、テンプレート
|
|
|
|
ビルド・ファームウェアの書き込みは、MAP編集とは別の実行機能として扱う。
|
|
同じ画面から各ツールを利用できることと、各レイヤーがそのデータや処理を所有することは区別する。
|
|
|
|
## プロトコル設計
|
|
|
|
### レイヤー間インターフェース
|
|
|
|
```txt
|
|
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のP-2](MAPレイヤー.md#p-2-viaの初期対応範囲)、実機との対応・状態管理は[MAPのP-3](MAPレイヤー.md#p-3-プロジェクトと実機の対応状態管理)で扱う
|
|
- **QMK Configurator**: Firmware Generatorのターゲット
|
|
|
|
## 配慮事項
|
|
|
|
### 学習コスト
|
|
|
|
- テンプレートプロジェクト提供 (60%, Split等)
|
|
- 簡易モード/詳細モードの切り替え
|
|
- 段階的な機能開示
|
|
|
|
### 互換性
|
|
|
|
- 既存KLE JSONの読み込み(PHYデータがなくても読める)
|
|
- 段階的移行パスの提供
|
|
- レガシーツールとの共存
|
|
|
|
## 次のステップ
|
|
|
|
1. プロトコル仕様ドラフト作成
|
|
2. GitHubでRFCリポジトリ立ち上げ
|
|
3. 小規模コミュニティでフィードバック収集
|
|
4. リファレンス実装の開発
|
|
|
|
## 未確認事項
|
|
|
|
### P-1 アナログ値の解釈をどの層が持つか
|
|
|
|
- 位置づけ: 未解決の問い。ELCは配線だけを持つと決めたため、生値から押下深さを出す変換の置き場が空いている
|
|
- 現状の認識: センサの品種と出力特性はPCB設計ツール側、キャリブレーションは実機ごとの実測値で設計データではない、とまでは決まっている。残りをMAPに寄せるか、別の層を立てるかは未定
|
|
- 格上げ条件: アナログ入力のキーボードを1つ通しで設計し、変換に必要な情報と、それを置く層をユーザーが決める
|