diff --git a/ELCレイヤー.md b/ELCレイヤー.md index 73b00c6..2ffffc0 100644 --- a/ELCレイヤー.md +++ b/ELCレイヤー.md @@ -70,9 +70,13 @@ PHYがレイアウトバリアントを持つ場合も、ELCは選択に関係 設計エラーとする。接点マトリクスなら、どちらが押されたかを区別できないため。 排他かどうかはPHYの木から判る。 +ファームウェア向けのキー番号と接続先の対応表は、バリアント選択後のIDXの並びから生成する。 +同じ接続先を共有する排他キーも、選択後に同時には残らない。ELCの保存データは選択によって書き換えない。 + LEDチェーンもバリアントごとに分けない。排他なキー位置の両方にLEDが載る基板も、 バリアント固有のキーにLEDが載らない基板もあるが、どちらもチェーンは1本で、選択によって並びが変わらない。 載らないキーは、PHYがキーごとに持つper-key LEDの有無でそのまま表せる。 +キー配列の出力で行うバリアントの取捨・番号の詰め直しは、LEDチェーンには適用しない。 ### 他レイヤーへの参照 diff --git a/IDXレイヤー.md b/IDXレイヤー.md index 9b33321..5fb63aa 100644 --- a/IDXレイヤー.md +++ b/IDXレイヤー.md @@ -2,20 +2,24 @@ ## 概要 -IDXレイヤーは、PHYのキーに「キー番号」を与える。キー番号は、キーマップがキーを指すための識別子である。 +IDXレイヤーは、全バリアントにわたるPHYのキーの並び順を持つ。 +番号を使う形式への出力時に、選択したバリアントで使うキーだけを残し、0から連続するキー番号を与える。 +保存した並びの位置と、選択後の出力でのキー番号は区別する。 -キー番号は他のどの情報からも導出できない。設計者が決める並び順そのものであり、 -そのためIDXが正本として持つ。ELCのrow/colが「配線から決まるので出力時に導出する」のと、 -理由が裏返しの関係にある。 +並び順は他のどの情報からも導出できない。設計者が決める情報なので、IDXが正本として持つ。 +ELCのrow/colが「配線から決まるので出力時に導出する」のと、理由が裏返しの関係にある。 -IDXが持つのは、番号を振る対象のキーと、その並び順だけとする。 +IDXが持つのは、番号を振る対象のキーと、その並び順だけとする。バリアントの選択は保存しない。 ## キー番号は公開インターフェース -基板を公開すると、他人が書いたキーマップがそのキー番号に依存する。 -番号を振り直すと、既存のキーマップが別のキーを指す。 +基板を公開すると、他人が書いたキーマップが、出力したレイアウトのキー番号に依存する。 +同じレイアウトで番号を振り直すと、既存のキーマップが別のキーを指す。 -そのためキー番号は、出力のたびに生成し直す派生情報として扱わず、固定した正本として保存する。 +そのため並び順は正本として保存し、出力のたびに幾何や配線から生成し直さない。 +同じ並びと同じバリアント選択からは、同じ出力番号を得る。 +番号の互換性は出力レイアウトごとに扱い、異なるバリアントの同じ番号が同じキーを指すとは限らない。 +並びへの挿入・削除・並べ替えでは、影響する出力レイアウトの番号が変わることを考慮する。 ## 幾何から導出しない @@ -51,35 +55,47 @@ row / col 自体がELCの正本ではなく出力時の派生情報である。 ## レイアウトバリアント -PHYがレイアウトバリアントを持つ場合も、キー番号の空間は1つとする。バリアントごとにIDXを分けない。 -キー番号は公開インターフェースであり、どの空間のものかを断らずに解釈できなければならない。 -特定のレイアウト向けの並びは、選んだバリアントに属さないキーを落として得る。 -ただしこれだけでは足りない場合がある。QMKのコミュニティレイアウトでは、同じマトリクス位置が -レイアウトによって別の物理キーになり(ANSIのバックスラッシュとISOの `#~`)、残ったキーの読み順が変わる。 -ISO系で引数順が一致しない。 +IDXは、番号を振る対象のキーを全バリアントにわたって1つの `order` に持つ。 +各PHYキーIDを別々の要素として並べ、同じIDは重複させない。同じ接続先に配線された排他キーも +別々の要素にする。物理キーごとに、出力先が要求する並びの中の位置を与えられるようにするため。 -排他なキー同士は、同じキー番号を共有できる。`order` の要素にキーIDの配列を書くと、 -その位置の番号を配列内のキーで共有する。 +出力時は、PHYのVariantGroupごとにバリアントを選び、次の手順で出力用の並びを得る。 -番号を共有できるのは、ELCで同じ接続先の組に配線されたキーに限る。 -3つの処理系が要求するのはいずれも「番号の位置 → マトリクス位置」の1対1の対応表であり、 -1つの番号に対応するマトリクス位置は1つしかないため。 -逆に、同じ接続先の組に配線された排他キーは番号を共有しなければならない。 -別々の番号を与えると、その対応表に同じマトリクス位置が2回現れ、1回のキー押下で両方の番号が反応する。 +1. 選択したバリアントの配下と、バリアントに属さない共通のキーを対象にする。 + 入れ子の場合は、祖先のバリアントも選択されているキーだけを対象にする +2. `order` から対象外のキーを除く。残ったキー同士の順序は変えない +3. 残った並びの位置を、0から連続する出力用のキー番号とする -選択によって番号が詰まることはない。あるバリアントでしか実装されないキーの番号は、 -別のバリアントを選んだときには使われない番号として残る。 +保存した `order` は書き換えない。レイアウトごとに独立したIDXや並び順も保存しない。 +同じ接続先の排他キーは選択後に同時には残らないため、別々の要素でも出力の対応表に重複しない。 +番号を使う形式への出力は、バリアントを選択した構成を単位とする。 + +例えば、ANSIのバックスラッシュとISOの `#` が同じ接続先を使う場合も、次のように並べられる。 +QとAは共通キー、バックスラッシュと `#` は排他キーとする。 + +| キー | 保存したorderでの位置 | ANSI出力の番号 | ISO出力の番号 | +| --- | --- | --- | --- | +| Q | 0 | 0 | 0 | +| バックスラッシュ | 1 | 1 | — | +| A | 2 | 2 | 1 | +| # | 3 | — | 2 | + +全体の並びは `Q → バックスラッシュ → A → #`、ANSI出力は `Q → バックスラッシュ → A`、 +ISO出力は `Q → A → #` になる。 ## 他レイヤーとの関係 IDXはPHYのキーIDだけを参照する。ELCを参照しない。 MAPはIDXを参照しない。MAPもキーの参照にPHYのキーIDを使う。 -キーマップを配列として出力するとき、IDXの並び順で並べ替える。 -これにより、IDXにキーを挿入して番号がずれても、MAPは書き換えずに済む。 +キーマップを配列として出力するとき、バリアント選択後のIDXの並び順で並べ替える。 +ELCから作るキー番号と接続先の対応表にも、同じ選択後の並びを使う。 +これにより、IDXの編集やバリアント選択で出力番号が変わっても、MAP内のキーIDへの割り当ては書き換えずに済む。 +PHYのIDで参照するELC・MAPの保存データ自体には、番号を詰める処理はない。 MAPが番号を持たないキーにキーコードを割り当てていた場合、そのキーは出力に現れない。 -IDXの `order` と突き合わせて検出できる。 +IDXの `order` と突き合わせて検出できる。`order` に含まれていても、選ばれなかったバリアントの +キーへの割り当ては、その出力には含めない。 ## 持たないもの @@ -92,30 +108,31 @@ IDXの `order` と突き合わせて検出できる。 ```ts type IDX = { - order: (string | string[])[] // PHYのキーID。並びの位置がキー番号。 - // 配列は、その位置の番号を共有する排他バリアントのキー + order: string[] // 全バリアントの対象キーのPHY ID。各IDは1回だけ現れる。 + // 出力時に対象外のキーを除き、残った並びの位置をキー番号とする } ``` -並びの位置を番号とする形は、ELCの `LEDChain.order` と同じ形である。 -欠番・重複・番号の飛びが構造として起こらない。 +番号は個別のフィールドとして持たず、出力時の並びの位置で表すため、出力番号に欠番や飛びは生じない。 +キーIDの重複は許さない。 -`order` に挙げたキーだけが番号を持つ。PHYの部品ノードと `decal` のキーは対象にならない。 +出力番号の対象は `order` に挙げたキーに限る。PHYの部品ノードと `decal` のキーは対象にならない。 ## 検討済み・非採用 - PHYのツリー順をキー番号とする (journal/2026-09-21-idx-necessity.md) - ELCのマトリクス順からキー番号を導出する (journal/2026-09-21-idx-necessity.md) -- `keyId` と `index` の対を並べる形 (journal/2026-09-21-idx-necessity.md) +- 排他キーで番号を共有し、選択後も番号を詰めない (journal/2026-09-22-idx-variant-output.md) - MAPがキー番号を参照する (journal/2026-09-21-idx-necessity.md) - レイアウトごとに別のIDXを持つ (journal/2026-09-21-multi-layout.md) ## 未確認事項 -### P-1 一致しないコミュニティレイアウトの並びをどう与えるか +### P-1 単一のorderから既存コミュニティレイアウトの並びを得られる範囲 -- 位置づけ: 本文「レイアウトバリアント」の残余。一致しない場合があることは確認済み -- 現状の認識: QMKの実データで、コミュニティレイアウトとの173組のうち30組(すべてISO系)が - `order` からの取捨では得られない。並べ替えの規則を与えるか、レイアウトごとの並びを持つかが未定。 - 後者は「レイアウトごとに別のIDXを持つ」として一度落としている -- 格上げ条件: 埋め方をユーザーが決める +- 位置づけ: 本文「レイアウトバリアント」の方式を、既存レイアウトとの互換出力に使う際の未検証部分 +- 現状の認識: 同じ配線を使う別のPHYキーを別々の位置に置けるため、本文のANSI/ISO例は取捨で表せる。 + 既存のコミュニティレイアウト全般で同じように表せるかは未検証。同じPHYキーIDを使う共通キー同士の + 要求順がレイアウト間で逆転する場合は、単一のorderからの取捨では表せないが、その実例の有無は未確認 +- 格上げ条件: 実データのキーを共通キーとバリアント別のPHYキーに対応づけ、全体のorderから各レイアウトの + 要求順を取捨で再現できるか確認する。再現できないものが残る場合は、対応範囲と扱いを決める diff --git a/PHYレイヤー.md b/PHYレイヤー.md index 51a77c8..84a937a 100644 --- a/PHYレイヤー.md +++ b/PHYレイヤー.md @@ -170,7 +170,8 @@ VariantGroupごとにバリアントを1つ選んでから階層を畳んで生 Variantをまたぐノードの移動は、クラスター間の移動と同じreparentとして扱う。絶対配置は変わらない。 組み替えの対象を同一の親に限る規則がそのまま効くため、複数のVariantにまたがる選択は組み替えできない。 -選択はPHYを畳むときにだけ使う。他レイヤーはPHYのノードIDを参照するだけで、選択を見ない。 +ELC・IDX・MAPの保存データは全バリアントのPHYノードIDを参照し、選択によって書き換えない。 +選択は、PHYを単一の配置に畳むときや、IDX・MAPから選択した構成のキー配列を生成するときに使う。 ### クラスターの組み替え diff --git a/journal/2026-09-22-idx-variant-output.md b/journal/2026-09-22-idx-variant-output.md new file mode 100644 index 0000000..750665d --- /dev/null +++ b/journal/2026-09-22-idx-variant-output.md @@ -0,0 +1,38 @@ +# IDXの全体の並びとバリアント選択後の出力番号 + +## 結論 + +IDXは全バリアントの対象キーを `order: string[]` に持つ。同じ配線を使う排他キーも別々に並べる。 +出力時に選択した構成のキーだけを残し、残った並びの位置を0から連続する出力番号とする。 +保存したorderは変更しない。公開番号の互換性は出力レイアウトごとに扱う。 +ユーザーがこの方針を採用した。 + +## 案の比較 + +| 案 | 扱い | +| --- | --- | +| 1つのorderに全キーを置き、出力時に取捨して詰める | 採用 | +| 同じ配線の排他キーは番号を共有し、選択後も番号を詰めない | 今回置き換えた旧仕様 | +| レイアウトごとに独立したIDXを保存する | 採用しない | + +## 決定理由と例 + +ユーザーは、ANSIのバックスラッシュとISOの # が同じ配線を使っても、IDXでは別々の位置を持つことを希望した。 +QとAが共通キーなら、全体のorderを `Q, backslash, A, hash` と置くことで、 +ANSIでは `Q, backslash, A`、ISOでは `Q, A, hash` を取捨だけで得られる。 +ISO出力の番号は0, 1, 2であり、保存したorderでの位置0, 2, 3とは区別する。 + +旧仕様は、全バリアントを含む番号と配線の対応表に同じ接続先が重複することを理由に、番号共有を必須としていた。 +今回の出力単位はバリアント選択済みの構成であり、排他キーは同時に残らないため、その理由は当てはまらない。 +全バリアントを一度に含むキー番号の対応表は、今回の出力方式には含めない。 + +MAPはPHYキーIDへの割り当てを保持する。出力時に配線の対応表とMAPの配列へ同じ選択後の並びを適用する。 +ELCの保存データは全バリアントの配線を保持し、LEDチェーンも選択によって取捨・詰め直しをしない。 + +## 未検証の範囲 + +例での解消は、既存コミュニティレイアウト全般に対応できることの検証ではない。 +従来の実データ調査は、既存のLAYOUT_all等の並びから他の並びを取捨できるかを調べたものだった。 +今回の、別々のPHYキーIDを使って全体のorderを構成する方式については改めて確認が必要。 +共通キー同士の要求順がレイアウト間で逆転する場合には単一のorderで表せない。 +その実例の有無と互換出力の対応範囲を、IDX P-1の残余として残す。 diff --git a/keyboard-design-layers.md b/keyboard-design-layers.md index fa8c40d..d7667a1 100644 --- a/keyboard-design-layers.md +++ b/keyboard-design-layers.md @@ -38,14 +38,14 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し ### 3. IDXレイヤー (キー識別) -- **役割**: PHYのキーに"キー番号"を与える +- **役割**: 全バリアントにわたるPHYのキーの並び順を保存し、選択した構成の出力用キー番号を決める - **入力**: PHYのキーID - **対応ツール**: QMKの `LAYOUT` マクロ、ZMKの matrix transform、KMKの `coord_mapping` -- **出力**: 番号を振るキーの並び。並びの位置がキー番号 +- **出力**: 全バリアントの対象キーIDを重複なく並べた `order`。出力時に対象外のキーを除き、0から連続する番号を与える - **備考**: キー番号はPHYの幾何からもELCの配線からも導出しない(導出すると、幾何の編集や再配線でキーマップがずれる) -- **備考**: キー番号は公開インターフェースであり、出力のたびに生成し直さず固定する +- **備考**: 並び順を正本として保存する。出力番号は公開インターフェースであり、互換性は出力レイアウトごとに扱う - **備考**: マトリックス座標とLEDの識別番号はIDXが持たない(どちらも配線で決まるためELCが持つ) -- **備考**: レイアウトバリアントがあってもキー番号の空間は1つ。同じマトリクス位置に配線された排他キーは同じ番号を共有する +- **備考**: 全バリアントで1つのIDXを持つ。同じ接続先に配線された排他キーも別々の要素とし、選択後の出力で番号を詰める。保存した `order` は変えない - **備考**: 既存のエコシステムでは、この並びが `LAYOUT` マクロの引数順などとして手書きされている。欠けている層ではなく、形式化されていない層 ### 4. MAPレイヤー (キーマップ) @@ -54,7 +54,7 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し - **入力**: PHYのキーID - **対応ツール**: ファームウェア、VIA、Remap - **出力**: レイヤー別キーコード -- **備考**: キーの参照にキー番号を使わない。配列としての並べ替えは、出力時にIDXの並び順で行う +- **備考**: キーの参照にPHYのキーIDを使う。配列としての並べ替えは、出力時にバリアント選択後のIDXの並び順で行う ### 5. IMEレイヤー (入力変換) @@ -75,7 +75,7 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し #### Key Indexer - PHY JSONを入力 -- キーにキー番号を割り当て +- 全バリアントの対象キーを1つの並びに配置 - 出力: IDX JSON #### Wiring Editor @@ -95,6 +95,7 @@ ELCはIDXを参照せず、IDXもELCを参照しない。MAPもIDXを参照し #### Firmware Generator - 全レイヤーの情報を統合 +- バリアントを選択し、IDXから対象外のキーを除いた並びで、キー番号の対応表とMAPの配列を生成 - row / col など、ターゲットが要求する派生情報をここで割り当てる - QMK/VIA/KMK等へ変換 - 出力: ターゲット固有の設定ファイル @@ -117,13 +118,14 @@ PHY → ELC PHY → IDX Input: キーID + 配置 - Output: 番号を振るキーIDの並び + Output: 全バリアントの対象キーIDの並び PHY → MAP Input: キーID Output: レイヤー別キーコード All → Firmware + Input: 各レイヤーのデータ + バリアント選択 Output: QMK keyboard.json / VIA JSON / KMK .py ``` diff --git a/keyboard-making-workflow.md b/keyboard-making-workflow.md index abe0ea4..f991c74 100644 --- a/keyboard-making-workflow.md +++ b/keyboard-making-workflow.md @@ -62,7 +62,8 @@ - **現在の課題**: KLEとファームウェア設定の手動変換。並び順は手書きで、引数の数え間違いがそのまま キーのずれになる - **Beyond KLE対応**: **PHY** + **IDX** + **ELC** → ファームウェア自動生成。 - ROW/COLはELCの配線から出力時に割り当てる。並び順は**IDXレイヤー**が正本として持つ + ROW/COLはELCの配線から出力時に割り当てる。並び順は**IDXレイヤー**が全バリアントにわたって正本として持ち、 + 出力時に選択したバリアントで使うキーだけを残して、キー番号を0から連続する番号に詰める #### b) キーマップ設定 @@ -71,7 +72,7 @@ - 各キーへのキーコード割り当て - レイヤー設計 - マクロ・特殊機能の設定 -- **Beyond KLE対応**: **MAPレイヤー**。キーの参照にはPHYのキーIDを使い、配列への並べ替えは出力時にIDXの順で行う +- **Beyond KLE対応**: **MAPレイヤー**。キーの参照にはPHYのキーIDを使い、配列への並べ替えは出力時にバリアント選択後のIDXの順で行う ### 4. 製造・組み立て段階 diff --git a/phase1-json-schema.md b/phase1-json-schema.md index f35a3af..8816e1b 100644 --- a/phase1-json-schema.md +++ b/phase1-json-schema.md @@ -424,8 +424,9 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP 各フィールドの意味は `IDXレイヤー.md` を正とする。 -番号を振るキーの並びだけを持つ。並びの位置がキー番号になるため、欠番・重複・番号の飛びは -構造として起こらない。 +全バリアントの対象キーIDを、重複なく1つの並びに持つ。同じ配線を使う排他キーも別々の要素とする。 +出力時は選択したバリアントで使わないキーを除き、残った並びの位置を0から連続するキー番号とする。 +保存した `order` は変更しない。 ### 基本構造 @@ -434,7 +435,7 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://beyond-kle.org/schemas/idx-layer.json", "title": "IDX Layer - Key Identification", - "description": "Ordered list of PHY keys; the position in the list is the key number", + "description": "Ordered PHY key IDs across all variants. Output key numbers are contiguous positions after filtering by variant selection", "type": "object", "required": ["version", "phyReference", "order"], "properties": { @@ -450,20 +451,10 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP "order": { "type": "array", "uniqueItems": true, + "description": "Each PHY key has its own entry, including mutually exclusive keys wired to the same terminals. Variant selection does not modify this list", "items": { - "oneOf": [ - { - "type": "string", - "description": "Reference to PHY layer key ID" - }, - { - "type": "array", - "minItems": 2, - "uniqueItems": true, - "items": { "type": "string" }, - "description": "Mutually exclusive variant keys sharing this key number. They must be wired to the same terminals in ELC" - } - ] + "type": "string", + "description": "Reference to PHY layer key ID" } } } @@ -622,7 +613,8 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP ## 4. MAPレイヤー JSON Schema キーの参照にはPHYのキーIDを使う。キー番号は参照しない。 -配列としての並べ替えは、ファームウェア出力時にIDXの並び順で行う。 +配列としての並べ替えは、ファームウェア出力時にバリアント選択後のIDXの並び順で行う。 +キー番号と接続先の対応表も同じ並びで生成し、MAPの保存データは変更しない。 ### 基本構造 @@ -685,8 +677,8 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP ### PHY → IDX変換 -1. PHYレイヤーからキーのリストを取得 -2. 番号を振るキーを選び、並び順を決める +1. PHYレイヤーから全バリアントのキーのリストを取得 +2. 番号を振る対象キーを1つの `order` に重複なく並べる。同じ配線の排他キーも別々の要素にする ### PHY → ELC変換 @@ -696,9 +688,12 @@ ELC・IDX・MAPはどれもPHYを参照する。ELCはIDXを参照せず、MAP ### IDX + ELC + MAP → ファームウェア出力 -1. ELCの配線から、ターゲットが要求する row / col を割り当て -2. IDXの並び順に従って、MAPのキーコードを配列へ並べ替え -3. VIA/QMK形式への出力 +1. PHYのVariantGroupごとにバリアントを選び、共通キーと、祖先を含めて選択されたバリアントのキーを特定 +2. IDXの `order` から対象外のキーを除き、残った順序のまま出力用のキー番号を0から連続して割り当て +3. ELCの配線から、ターゲットが要求する row / col を割り当て、手順2の並びでキー番号との対応表を生成 +4. 同じ並びでMAPのキーコードを配列へ並べ替え、VIA/QMK形式へ出力 + +保存したPHY・IDX・ELC・MAPは書き換えない。ELCのLEDチェーンの並び・番号は、このキーの取捨では変わらない。 ## 次のステップ