map: MAPレイヤーを新設し、実機との読み書きとVIA対応を決める
MAPエディタは割り当ての編集に加え、実機への書き込みと読み出しを一組で 提供する。新規キーボードの設計から実機での調整までを主眼に置くため。 最初の通信プロトコルはVIAとし、独自プロトコルの追加やそのための ファームウェアのフォークは行わない。 VIA向けキーボード定義の生成はFirmware Generator、ビルドと書き込みは IDEの責務として、MAP編集の外に置いた。VIAで通信できることと、MAPが そのデータを所有することは区別する。 Journal: journal/2026-09-22-map-via-workflow.md Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MtVk8W4yK6j3eCqQpEQBLS
This commit is contained in:
Claude Opus 5
@@ -14,6 +14,7 @@ PHY(物理配置) / ELC(電気配線) / IDX(キー識別) / MAP(キーマップ)
|
|||||||
| `PHYレイヤー.md` | PHY層の仕様 |
|
| `PHYレイヤー.md` | PHY層の仕様 |
|
||||||
| `ELCレイヤー.md` | ELC層の仕様 |
|
| `ELCレイヤー.md` | ELC層の仕様 |
|
||||||
| `IDXレイヤー.md` | IDX層の仕様 |
|
| `IDXレイヤー.md` | IDX層の仕様 |
|
||||||
|
| `MAPレイヤー.md` | MAP層とエディタの責務・実機との読み書き方針 |
|
||||||
| `phase1-json-schema.md` | 各層のJSON Schema |
|
| `phase1-json-schema.md` | 各層のJSON Schema |
|
||||||
| `keyboard-making-workflow.md` | 既存の自作キーボード制作フローとの対応 |
|
| `keyboard-making-workflow.md` | 既存の自作キーボード制作フローとの対応 |
|
||||||
| `implementation-plan.md` | 実装方針の決定事項・検証用サンプル |
|
| `implementation-plan.md` | 実装方針の決定事項・検証用サンプル |
|
||||||
|
|||||||
+86
@@ -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への割り当てとして取り込む手順を確認する。
|
||||||
@@ -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を次にどの順序で実装するかも決めていない。
|
||||||
@@ -50,11 +50,12 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し
|
|||||||
|
|
||||||
### 4. MAPレイヤー (キーマップ)
|
### 4. MAPレイヤー (キーマップ)
|
||||||
|
|
||||||
- **役割**: キーとキーコードの対応
|
- **役割**: キーマップレイヤーごとのキーへの割り当て
|
||||||
- **入力**: PHYのキーID
|
- **入力**: PHYのキーID
|
||||||
- **対応ツール**: ファームウェア、VIA、Remap
|
- **対応ツール**: MAPエディタ (Keymap Designer)
|
||||||
- **出力**: レイヤー別キーコード
|
- **出力**: MAP JSON (現行形式はレイヤー別キーコード割り当て)
|
||||||
- **備考**: キーの参照にPHYのキーIDを使う。配列としての並べ替えは、出力時にバリアント選択後のIDXの並び順で行う
|
- **備考**: キーの参照にPHYのキーIDを使う。配列としての並べ替えは、出力時にバリアント選択後のIDXの並び順で行う
|
||||||
|
- **詳細**: [MAPレイヤー](MAPレイヤー.md)。動作定義と保存形式の拡張範囲は、[MAPのP-1](MAPレイヤー.md#p-1-割り当てる動作と保存形式の範囲)で扱う
|
||||||
|
|
||||||
### 5. IMEレイヤー (入力変換)
|
### 5. IMEレイヤー (入力変換)
|
||||||
|
|
||||||
@@ -85,19 +86,22 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し
|
|||||||
- 視覚的に配線を確認
|
- 視覚的に配線を確認
|
||||||
- 出力: ELC JSON
|
- 出力: ELC JSON
|
||||||
|
|
||||||
#### Keymap Designer
|
#### Keymap Designer (MAPエディタ)
|
||||||
|
|
||||||
- PHY JSONを入力
|
- PHYの配置を参照し、キーマップレイヤーごとの割り当てを編集・保存する
|
||||||
- レイヤー別キーコード割り当て
|
- 新規キーボードの設計から実機での調整までを扱い、割り当ての読み書きを一組で提供する
|
||||||
- VIA/Remapとの互換性
|
- 実機との通信は既存のVIAプロトコルから対応し、対象を段階的に増やす
|
||||||
- 出力: MAP JSON
|
- 出力: MAP JSON
|
||||||
|
|
||||||
|
具体的な責務と通信上の制約は、[MAPレイヤー](MAPレイヤー.md#mapエディタの責務)に従う。
|
||||||
|
|
||||||
#### Firmware Generator
|
#### Firmware Generator
|
||||||
|
|
||||||
- 全レイヤーの情報を統合
|
- 全レイヤーの情報を統合
|
||||||
- バリアントを選択し、IDXから対象外のキーを除いた並びで、キー番号の対応表とMAPの配列を生成
|
- バリアントを選択し、IDXから対象外のキーを除いた並びで、キー番号の対応表とMAPの配列を生成
|
||||||
- row / col など、ターゲットが要求する派生情報をここで割り当てる
|
- row / col など、ターゲットが要求する派生情報をここで割り当てる
|
||||||
- QMK/VIA/KMK等へ変換
|
- QMK/VIA/KMK等へ変換
|
||||||
|
- VIA向けキーボード定義は、配置と接続先の対応などを統合して生成する
|
||||||
- 出力: ターゲット固有の設定ファイル
|
- 出力: ターゲット固有の設定ファイル
|
||||||
|
|
||||||
### 統合環境 (IDE)
|
### 統合環境 (IDE)
|
||||||
@@ -107,6 +111,9 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し
|
|||||||
- **バージョン管理統合**: テキストベース定義でgit管理
|
- **バージョン管理統合**: テキストベース定義でgit管理
|
||||||
- **ワークフローサポート**: ガイド付きウィザード、テンプレート
|
- **ワークフローサポート**: ガイド付きウィザード、テンプレート
|
||||||
|
|
||||||
|
ビルド・ファームウェアの書き込みは、MAP編集とは別の実行機能として扱う。
|
||||||
|
同じ画面から各ツールを利用できることと、各レイヤーがそのデータや処理を所有することは区別する。
|
||||||
|
|
||||||
## プロトコル設計
|
## プロトコル設計
|
||||||
|
|
||||||
### レイヤー間インターフェース
|
### レイヤー間インターフェース
|
||||||
@@ -122,7 +129,7 @@ PHY → IDX
|
|||||||
|
|
||||||
PHY → MAP
|
PHY → MAP
|
||||||
Input: キーID
|
Input: キーID
|
||||||
Output: レイヤー別キーコード
|
Output: MAP JSON (現行形式はレイヤー別キーコード割り当て)
|
||||||
|
|
||||||
All → Firmware
|
All → Firmware
|
||||||
Input: 各レイヤーのデータ + バリアント選択
|
Input: 各レイヤーのデータ + バリアント選択
|
||||||
@@ -158,7 +165,7 @@ All → Firmware
|
|||||||
## 既存ツールとの関係
|
## 既存ツールとの関係
|
||||||
|
|
||||||
- **KLE**: PHYデータを表示できる既存のビュワー。KLE JSONの読み書きで連携する
|
- **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のターゲット
|
- **QMK Configurator**: Firmware Generatorのターゲット
|
||||||
|
|
||||||
## 配慮事項
|
## 配慮事項
|
||||||
|
|||||||
Reference in New Issue
Block a user