From d85836158630800cdb60327dd1a06d4e8bc088f3 Mon Sep 17 00:00:00 2001 From: EwdErna Date: Sun, 20 Sep 2026 21:56:32 +0900 Subject: [PATCH] =?UTF-8?q?schema:=20IDX/ELC=E3=82=B9=E3=82=AD=E3=83=BC?= =?UTF-8?q?=E3=83=9E=E3=82=92=E7=A2=BA=E5=AE=9A=E3=81=97=E3=81=9F=E4=BB=95?= =?UTF-8?q?=E6=A7=98=E3=81=AB=E8=BF=BD=E5=BE=93=E3=81=95=E3=81=9B=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ELCをELCレイヤー.mdの保存形式で書き直した。microcontrollerとmatrixの列挙は 捨てたモデルなので削除し、提供者・端子・LEDチェーンに置き換え。参照先もIDXからPHYへ。 IDXからはrow/colとラベルを外し、キーIDとキー番号の対応だけにした。 PHYはcompatibilityブロックを、キー側と同じ形のファイル単位kleCompatibilityに置換。 clusterのnameは保存形式に無いため必須から外した。 Co-Authored-By: Claude Opus 5 --- phase1-json-schema.md | 234 ++++++++++++++++++++++++++++-------------- 1 file changed, 156 insertions(+), 78 deletions(-) diff --git a/phase1-json-schema.md b/phase1-json-schema.md index f9ab281..41c6462 100644 --- a/phase1-json-schema.md +++ b/phase1-json-schema.md @@ -2,11 +2,16 @@ ## レイヤー間データフロー +```txt +PHY (物理配置) + ├─→ ELC (電気配線) + └─→ IDX (キー識別) + └─→ MAP (キーマップ) ``` -PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キーマップ) - ↓ ↓ - ファームウェア生成 VIA/Remap出力 -``` + +ELCとIDXはどちらもPHYを参照する。ELCはIDXを参照しない。 +ファームウェアやVIA/Remap向けの出力は、各レイヤーの情報を統合して生成する。 +他レイヤーからキーや部品を指す参照には、PHYのノードIDを使う。 ## 1. PHYレイヤー JSON Schema @@ -38,23 +43,10 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー "modified": { "type": "string", "format": "date-time" } } }, - "compatibility": { + "kleCompatibility": { "type": "object", - "description": "Information for external tool compatibility", - "properties": { - "kleJson": { - "type": "object", - "properties": { - "source": { "type": "string" }, - "checksum": { "type": "string" }, - "preservedFields": { "type": "array", "items": { "type": "string" } } - } - }, - "originalFormat": { - "type": "string", - "enum": ["kle", "via", "qmk", "native"] - } - } + "description": "File-level opaque KLE fields kept for round-trip output (switchMount, switchBrand, switchType, backcolor, radii, background, css). The owning layer is undecided; see P-6 in PHYレイヤー.md", + "additionalProperties": true }, "profiles": { "type": "array", @@ -196,7 +188,7 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー }, "cluster": { "type": "object", - "required": ["type", "id", "name", "transform", "children"], + "required": ["type", "id", "transform", "children"], "properties": { "type": { "type": "string", @@ -324,6 +316,10 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー ## 2. IDXレイヤー JSON Schema +IDXが持つのは、PHYのキーとキー番号の対応だけとする [推測:P-1]。 +マトリックス座標(row/col)とLEDの識別番号はここに置かない。どちらも配線で決まる情報で、 +row/col はELCの配線から導く派生情報、LEDの番号はELCが正本を持つ。 + ### 基本構造 ```json @@ -331,7 +327,7 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + 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": "Mapping between physical keys and logical identifiers", + "description": "Mapping between PHY keys and key numbers", "type": "object", "required": ["version", "phyReference", "keyMap"], "properties": { @@ -354,26 +350,16 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー "$defs": { "keyMapping": { "type": "object", - "required": ["physicalId", "logicalId"], + "required": ["keyId", "index"], "properties": { - "physicalId": { + "keyId": { "type": "string", "description": "Reference to PHY layer key ID" }, - "logicalId": { - "type": "object", - "required": ["index"], - "properties": { - "index": { "type": "integer", "minimum": 0 }, - "matrix": { - "type": "object", - "properties": { - "row": { "type": "integer", "minimum": 0 }, - "col": { "type": "integer", "minimum": 0 } - } - }, - "label": { "type": "string" } - } + "index": { + "type": "integer", + "minimum": 0, + "description": "Key number" } } } @@ -383,19 +369,21 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー ## 3. ELCレイヤー JSON Schema +各フィールドの意味は `ELCレイヤー.md` を正とする。 + ### 基本構造 ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://beyond-kle.org/schemas/elc-layer.json", - "title": "ELC Layer - Electrical Configuration", - "description": "Electrical wiring and pin mapping", + "title": "ELC Layer - Electrical Wiring", + "description": "Wiring between provider pins and key terminals", "type": "object", - "required": ["version", "idxReference", "microcontroller", "matrix"], + "required": ["version", "phyReference", "providers", "keys"], "properties": { "version": { "type": "string" }, - "idxReference": { + "phyReference": { "type": "object", "required": ["source", "checksum"], "properties": { @@ -403,41 +391,124 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー "checksum": { "type": "string" } } }, - "microcontroller": { + "providers": { + "type": "array", + "items": { "$ref": "#/$defs/provider" } + }, + "keys": { + "type": "array", + "items": { "$ref": "#/$defs/keyWiring" } + }, + "ledChains": { + "type": "array", + "items": { "$ref": "#/$defs/ledChain" } + } + }, + "$defs": { + "pinRef": { + "type": "string", + "pattern": "^(VCC|GND|[^.]+\\.[^.]+)$", + "description": "\".\", or the reserved power rails VCC / GND" + }, + "provider": { + "oneOf": [ + { "$ref": "#/$defs/mcuProvider" }, + { "$ref": "#/$defs/analogMuxProvider" } + ] + }, + "mcuProvider": { "type": "object", - "required": ["type", "pinMapping"], + "required": ["id", "kind", "part"], "properties": { - "type": { "type": "string" }, - "pinMapping": { + "id": { "type": "string" }, + "kind": { "const": "mcu" }, + "part": { + "type": "string", + "description": "Part number. Used to interpret pin names" + } + } + }, + "analogMuxProvider": { + "type": "object", + "required": ["id", "kind", "channels", "select", "common"], + "properties": { + "id": { "type": "string" }, + "kind": { "const": "analog-mux" }, + "channels": { + "type": "integer", + "minimum": 1, + "description": "Number of logical pins provided. Pin names are \"0\"..\"channels-1\"" + }, + "select": { + "type": "array", + "items": { "$ref": "#/$defs/pinRef" }, + "description": "Select pins, least significant bit first" + }, + "common": { "$ref": "#/$defs/pinRef" }, + "enable": { "$ref": "#/$defs/pinRef" } + } + }, + "keyWiring": { + "oneOf": [ + { "$ref": "#/$defs/contactKey" }, + { "$ref": "#/$defs/analogKey" } + ] + }, + "contactKey": { + "type": "object", + "required": ["key", "detect", "terminals"], + "properties": { + "key": { + "type": "string", + "description": "Reference to PHY layer key ID" + }, + "detect": { "const": "contact" }, + "terminals": { "type": "object", + "description": "Non-polar. a and b carry no ordering meaning", + "required": ["a", "b"], "properties": { - "rows": { - "type": "array", - "items": { "type": "string" } - }, - "cols": { - "type": "array", - "items": { "type": "string" } - } + "a": { "$ref": "#/$defs/pinRef" }, + "b": { "$ref": "#/$defs/pinRef" } + } + }, + "diode": { + "type": "string", + "enum": ["a-to-b", "b-to-a"], + "description": "Anode side comes first. Omitted means no diode" + } + } + }, + "analogKey": { + "type": "object", + "required": ["key", "detect", "terminals"], + "properties": { + "key": { + "type": "string", + "description": "Reference to PHY layer key ID" + }, + "detect": { "const": "analog" }, + "terminals": { + "type": "object", + "required": ["out", "vcc", "gnd"], + "properties": { + "out": { "$ref": "#/$defs/pinRef" }, + "vcc": { "$ref": "#/$defs/pinRef" }, + "gnd": { "$ref": "#/$defs/pinRef" } } } } }, - "matrix": { + "ledChain": { "type": "object", - "required": ["type", "dimensions"], + "required": ["id", "data", "order"], "properties": { - "type": { - "type": "string", - "enum": ["standard", "charlieplexing", "direct"] - }, - "dimensions": { - "type": "object", - "required": ["rows", "cols"], - "properties": { - "rows": { "type": "integer", "minimum": 1 }, - "cols": { "type": "integer", "minimum": 1 } - } + "id": { "type": "string" }, + "data": { "$ref": "#/$defs/pinRef" }, + "order": { + "type": "array", + "items": { "type": "string" }, + "description": "PHY node IDs. The position in the array is the LED number" } } } @@ -505,25 +576,32 @@ PHY (物理配置) → IDX (キー識別) → ELC (電気配線) + MAP (キー ### PHY → IDX変換 -1. PHYレイヤーから物理キーリストを取得 -2. 各キーに論理IDを割り当て -3. マトリックス座標の自動生成（行列最適化） +1. PHYレイヤーからキーのリストを取得 +2. 各キーにキー番号を割り当て -### IDX → ELC変換 +### PHY → ELC変換 -1. マトリックス次元を算出 -2. ピン配置の最適化提案 -3. 配線効率の検証 +1. ピン提供者を置き、各提供者が消費する上位ピンを指定 +2. 各キーの端子の接続先を指定 +3. LEDチェーンの並びを指定 -### IDX + ELC → MAP変換 +### IDX + ELC + MAP → ファームウェア出力 -1. キーインデックス配列の生成 -2. デフォルトキーマップの提案 +1. ELCの配線から、ターゲットが要求する row / col を割り当て +2. キー番号の配列とキーマップ配列の生成 3. VIA/QMK形式への出力 ## 次のステップ -1. **TypeScriptでの型定義作成** +1. **型定義の作成**(言語は `implementation-plan.md` で選定) 2. **変換ロジックのプロトタイプ実装** 3. **テストケース（60%、Split等）での検証** 4. **既存KLE JSONからの変換機能** + +## 未確認事項 + +### P-1 IDXがキー番号以外に持つものがあるか + +- 位置づけ: 本文「2. IDXレイヤー JSON Schema」が前提にしている。IDXには仕様ドキュメントがなく、 + 決定済みの情報(row/col と LEDの番号はELC)から引き算した最小形として書いている +- 格上げ条件: IDXレイヤーの仕様をユーザーと決め、`IDXレイヤー.md` に書く