diff --git a/CLAUDE.md b/CLAUDE.md index 7cb9a1b..4058988 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,6 +14,7 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ) | `PHYレイヤー.md` | PHY層の仕様 | | `ELCレイヤー.md` | ELC層の仕様 | | `IDXレイヤー.md` | IDX層の仕様 | +| `MAPレイヤー.md` | MAP層とエディタの責務・実機との読み書き方針 | | `phase1-json-schema.md` | 各層のJSON Schema | | `keyboard-making-workflow.md` | 既存の自作キーボード制作フローとの対応 | | `implementation-plan.md` | 実装方針の決定事項・検証用サンプル | diff --git a/MAPレイヤー.md b/MAPレイヤー.md new file mode 100644 index 0000000..0cf689a --- /dev/null +++ b/MAPレイヤー.md @@ -0,0 +1,86 @@ +# MAPレイヤー + +## 概要 + +MAPレイヤーは、キーマップレイヤーごとのキーへの割り当てを持つ。 +MAPエディタは、その設計・編集と、実機との読み書きを提供する。 +ここでいうキーマップレイヤーは、PHY・ELC等の設計レイヤーとは区別する。 + +主眼は、新しく作成するキーボードのワークフローにある。 +キーマップを設計し、実機へ反映し、使って調整した結果をプロジェクトへ戻せるようにする。 +既存キーボード全般への接続・取り込みを、初期対応の前提にはしない。 + +## MAPデータと他レイヤーの関係 + +キー参照と出力時の並べ替えは、[IDXレイヤー「他レイヤーとの関係」](IDXレイヤー.md#他レイヤーとの関係)に従う。 +MAPのキー参照にはPHYのキーIDを使い、実機との通信に使うアドレスを正本のキー参照にはしない。 + +現行の保存形式は、[JSON SchemaのMAP節](phase1-json-schema.md#4-mapレイヤー-json-schema)にある +レイヤー別のキーコード割り当てを出発点とする。 +動作定義と保存形式の拡張範囲は、[P-1](#p-1-割り当てる動作と保存形式の範囲)で扱う。 + +## MAPエディタの責務 + +- PHYの配置を参照し、キーマップレイヤーごとの割り当てを編集・保存する。 +- 対応する実機へ割り当てを書き込み、実機の現在の割り当てを読み出す。 +- 実機で使いながら調整し、その結果をMAPへ取り込むワークフローを提供する。 + +読み書きは一組として対応する。読み出しには、現在値の確認に加え、Remap等で調整した結果を +プロジェクトへ戻す用途も含む。保存と実機への反映の操作、差分表示、自動同期の有無は、 +[P-3](#p-3-プロジェクトと実機の対応状態管理)で扱う。 + +## DynamicとStatic + +Dynamicは、対応ファームウェアが公開している通信プロトコルを使って、再ビルドせずに設定を読み書きする経路。 +Staticは、設定をファームウェアへ組み込むために出力する経路とする。 +Staticの出力は[全体方針のFirmware Generator](keyboard-design-layers.md#firmware-generator)が担い、MAPエディタは持たない。 + +MAPエディタはDynamicの読み書きを提供する。Dynamicで変更できる範囲は、 +対象ファームウェアと既存プロトコルが公開する範囲に従う。 +Staticで扱う動作定義の範囲と、Dynamicで変更できない設定の扱いは、 +[P-1](#p-1-割り当てる動作と保存形式の範囲)で扱う。 + +## 対応プロトコル + +最初に対応する通信プロトコルはVIAとし、対応プロトコルを絞って段階的に増やす。 +ユーザーが好むRemapと同じ通信経路を使い、新規キーボードの設計から実機での調整へつなぐため。 + +- QMKやVial側にBeyond KLE独自のプロトコルを追加しない。そのためのファームウェアのフォークも行わない。 +- VIA対応では、対象ファームウェアの既存のVIA機能を使って読み書きする。 +- VIAへの対応は、Remapというアプリ全体の機能を再現することを意味しない。 +- 初期の実装対象はVIAに限る。 + +対応するVIAプロトコルのバージョン、キーコード体系、編集項目の範囲は、 +[P-2](#p-2-viaの初期対応範囲)で扱う。 + +## 持たないもの + +物理配置、配線、キーの出力番号は、それぞれPHY・ELC・IDXで扱う。 +OS配列やIMEの入力変換はIME側の責務とし、外部ツールで編集できる照明等の設定も、 +VIAで通信できるという理由だけでMAPの所有データには含めない。 + +アナログ入力の解釈の所属は、[全体方針のP-1](keyboard-design-layers.md#p-1-アナログ値の解釈をどの層が持つか)で扱う。 + +## 検討済み・非採用 + +- 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・通信上のアドレスの対応をどこに保持し、接続した実機とどう照合するか。バリアントや配線の変更後の扱い、プロジェクトと実機の差分・保存・反映の操作も未定。 +- 完了条件: 対応情報の生成・保存・照合方法と状態管理を定め、設計から実機へ反映し、Remap等での変更を元のPHYキーIDへの割り当てとして取り込む手順を確認する。 diff --git a/journal/2026-09-22-map-via-workflow.md b/journal/2026-09-22-map-via-workflow.md new file mode 100644 index 0000000..b663ff5 --- /dev/null +++ b/journal/2026-09-22-map-via-workflow.md @@ -0,0 +1,46 @@ +# MAPエディタの実機との往復とVIA対応 + +## 結論 + +新規作成するキーボードのワークフローを主眼とし、MAPエディタは実機の読み書きを一組で提供する。 +最初の通信プロトコルはVIA。対応プロトコルを絞り、段階的に増やす。 +独自プロトコルの追加や、そのためのQMK・Vial等のフォークは行わない。 +高度な動作定義、Staticの対応範囲、同期方式はまだ決めていない。 + +## 案の比較 + +| 案 | 扱い | +| --- | --- | +| 既存プロトコルで実機の読み書きを提供し、VIAから始める | 採用 | +| MAPエディタをStaticに閉じる | 採用しない | +| Dynamicの対応範囲を読み出しだけに限定する | ユーザーが読み書きの両対応を指定 | +| 独自プロトコルのためにファームウェアをフォークする | ユーザーが意図しないと明示 | + +## 判断の根拠 + +ユーザーは、既存キーボード全般への対応よりも、新しく作るキーボードのワークフローを重視している。 +VIAを話すなら読み書きの両方を提供し、利用者が好むRemapと同じ通信経路から始める方針となった。 +当初のアシスタントによる「互換性」の説明はファイル変換に寄りすぎており、実機との通信を中心に修正した。 +VIA向けのキーボード定義生成と、MAPの割り当ての読み書きは別の責務として整理した。 + +## 調査で確認した範囲 + +公式文書・実装を参照した。実機による読み書きの検証は行っていない。 + +- RemapはWebHIDを使い、QMKのVIAクライアント向け機能へアクセスする。Workbenchにはソース編集・ビルド・書き込みもある。 + 参照: https://github.com/remap-keys/remap#references + 参照: https://remap-keys.app/docs/workbench +- VIAのキーボード定義には配置とmatrix座標の対応がある。QMKのVIA実装はキー単位の読み書きにlayer・row・colを使う。 + 参照: https://caniusevia.com/docs/specification/ + 参照: https://github.com/qmk/qmk_firmware/blob/master/quantum/via.c +- Vialではタップダンスやコンボを実機へ保存できるが、枠数等にはビルド時の制約がある。 + 参照: https://get.vial.today/manual/tap-dance.html + 参照: https://get.vial.today/manual/combos.html +- ZMK Studioは既存behaviorの割り当てを変更できるが、新しいbehavior定義等は対象外。実機に保存した変更とソース側の設定の扱いにも注意が必要。 + 参照: https://zmk.dev/docs/features/studio + +## 未採用の提案との区別 + +共通の動作モデル、ファームウェア固有表現の保持、Staticを先に実装する順序、差分を選んで反映するUIは、 +アシスタントの提案段階にとどまる。今回の合意として固定しない。 +Vial・ZMK Studioを次にどの順序で実装するかも決めていない。 diff --git a/keyboard-design-layers.md b/keyboard-design-layers.md index d7667a1..20d3d97 100644 --- a/keyboard-design-layers.md +++ b/keyboard-design-layers.md @@ -50,11 +50,12 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し ### 4. MAPレイヤー (キーマップ) -- **役割**: キーとキーコードの対応 +- **役割**: キーマップレイヤーごとのキーへの割り当て - **入力**: PHYのキーID -- **対応ツール**: ファームウェア、VIA、Remap -- **出力**: レイヤー別キーコード +- **対応ツール**: MAPエディタ (Keymap Designer) +- **出力**: MAP JSON (現行形式はレイヤー別キーコード割り当て) - **備考**: キーの参照にPHYのキーIDを使う。配列としての並べ替えは、出力時にバリアント選択後のIDXの並び順で行う +- **詳細**: [MAPレイヤー](MAPレイヤー.md)。動作定義と保存形式の拡張範囲は、[MAPのP-1](MAPレイヤー.md#p-1-割り当てる動作と保存形式の範囲)で扱う ### 5. IMEレイヤー (入力変換) @@ -85,19 +86,22 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し - 視覚的に配線を確認 - 出力: ELC JSON -#### Keymap Designer +#### Keymap Designer (MAPエディタ) -- PHY JSONを入力 -- レイヤー別キーコード割り当て -- VIA/Remapとの互換性 +- PHYの配置を参照し、キーマップレイヤーごとの割り当てを編集・保存する +- 新規キーボードの設計から実機での調整までを扱い、割り当ての読み書きを一組で提供する +- 実機との通信は既存のVIAプロトコルから対応し、対象を段階的に増やす - 出力: MAP JSON +具体的な責務と通信上の制約は、[MAPレイヤー](MAPレイヤー.md#mapエディタの責務)に従う。 + #### Firmware Generator - 全レイヤーの情報を統合 - バリアントを選択し、IDXから対象外のキーを除いた並びで、キー番号の対応表とMAPの配列を生成 - row / col など、ターゲットが要求する派生情報をここで割り当てる - QMK/VIA/KMK等へ変換 +- VIA向けキーボード定義は、配置と接続先の対応などを統合して生成する - 出力: ターゲット固有の設定ファイル ### 統合環境 (IDE) @@ -107,6 +111,9 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し - **バージョン管理統合**: テキストベース定義でgit管理 - **ワークフローサポート**: ガイド付きウィザード、テンプレート +ビルド・ファームウェアの書き込みは、MAP編集とは別の実行機能として扱う。 +同じ画面から各ツールを利用できることと、各レイヤーがそのデータや処理を所有することは区別する。 + ## プロトコル設計 ### レイヤー間インターフェース @@ -122,7 +129,7 @@ PHY → IDX PHY → MAP Input: キーID - Output: レイヤー別キーコード + Output: MAP JSON (現行形式はレイヤー別キーコード割り当て) All → Firmware Input: 各レイヤーのデータ + バリアント選択 @@ -158,7 +165,7 @@ All → Firmware ## 既存ツールとの関係 - **KLE**: PHYデータを表示できる既存のビュワー。KLE JSONの読み書きで連携する -- **VIA/Remap**: MAP Layerクライアントとして連携 +- **VIA/Remap**: 同じVIA対応実機の割り当てを編集する外部クライアント。外部で調整した結果もMAPエディタで読み出してプロジェクトへ戻す。対応範囲は[MAPのP-2](MAPレイヤー.md#p-2-viaの初期対応範囲)、実機との対応・状態管理は[MAPのP-3](MAPレイヤー.md#p-3-プロジェクトと実機の対応状態管理)で扱う - **QMK Configurator**: Firmware Generatorのターゲット ## 配慮事項