VIAキーボードJSON定義の詳細解説：ゼロからキーボード設定ファイルを作成する

VIAキーボードJSON定義の詳細解説：ゼロからキーボード設定ファイルを作成する

VIAキーボードJSON定義ファイルは、カスタムメカニカルキーボードにVIAサポートを追加するための重要なツールです。このチュートリアルでは、プロフェッショナルなVIAキーボード設定ファイルを作成し、リアルタイム設定機能を実現する方法について詳しく説明します。

VIAキーボードJSON定義とは?

VIAキーボードJSON定義ファイルは、キーボードのハードウェア構成を記述した標準化されたファイルで、VIAソフトウェアがキーボードを認識し、設定する方法を教えます。各VIA対応キーボードにはこのような定義ファイルが必要であり、キーボードの基本情報、キー配列レイアウト、物理サイズ、およびサポートする機能が含まれています。

コア構造の解説

すべてのVIAキーボードJSONファイルには、以下の基本的な構造が含まれています：

{
  "keyboardName": "キーボード名",
  "manufacturerId": "0xメーカーID",
  "deviceId": "0x製品ID",
  "keyMatrix": {
    "rowCount": 行数,
    "columnCount": 列数
  },
  "lightingType": "照明タイプ",
  "layoutInfo": {
    "layoutLabels": ["レイアウトラベル"],
    "keyPositions": [レイアウト配列]
  }
}

最初のVIAキーボード定義を作成する

ステップ1：キーマトリックスを理解する

まず、キーマトリックスのサイズを特定する必要があります。例えば、標準的な60%キーボードは通常5行14列のマトリックスです：

"keyMatrix": {
  "rowCount": 5,
  "columnCount": 14
}

ステップ2：物理レイアウトを定義する

物理レイアウトはキーボード上の各キーの位置とサイズを定義します。これはVIA設定ファイルで最も複雑な部分ですが、基本的なルールを理解すれば簡単です：

"keyPositions": [
  ["0,0", "0,1", "0,2", ...],  // 1行目
  ["1,0", "1,1", "1,2", ...],  // 2行目
  // ... さらに多くの行
]

各要素は次のいずれかになります：

  • 文字列形式のマトリックス座標："行,列"
  • オブジェクト形式の特殊キー：{"幅": 1.5} これは1.5uの幅のキーを表します

ステップ3：特殊機能を設定する

照明設定

VIAは複数の照明タイプをサポートしています：

  • "none" - 照明なし
  • "qmk_rgblight" - QMK RGB照明
  • "qmk_backlight" - QMKバックライト

メーカーIDと製品ID

これらのIDはVIAソフトウェアがキーボードを識別するために必要で、一意の16進値である必要があります。

高度なレイアウトテクニック

1. 複数のレイアウトをサポートする

多くのキーボードはANSI、ISO、WKLなどの異なる物理レイアウトをサポートします。labels配列を使用して異なるレイアウトバリエーションを定義できます：

"layoutLabels": [
  "標準レイアウト",
  ["下部行", "ANSI", "ISO", "WKL"]
]

2. 特殊キーの処理

スペースキー、シフトキーなどの特殊な大きさのキーについては、オブジェクト形式で定義します：

{
  "幅": 6.25,      // 6.25uの幅
  "色": "#cccccc",  // カラー
  "高さ": 2,          // 2uの高さ
  "x軸オフセット": 0.5         // X軸オフセット
}

3. マトリックスマッピング

複雑なキーボードでは、同じマトリックス位置を共有する複数の物理レイアウトがあります。\n\n\nセパレータを使用してマッピングします：

"4,5\n\n\n0,0",  // レイアウト0での位置4,5
"4,5\n\n\n0,1"   // レイアウト1での位置4,5

プロジェクトファイル構造

VIAキーボードプロジェクトでは、JSON定義ファイルはメーカーとモデル別に組織されます：

src/
├── 0_sixty/
│   └── 0_sixty.json          # 0-Sixtyキーボード定義
├── 0xC7/
│   └── 61key/
│       └── 61key.json        # 0xC7 61キーキーボード
├── 4pplet/
│   ├── aekiso60_rev_a.json   # AEKISO60 Rev A
│   ├── aekiso60_rev_b.json   # AEKISO60 Rev B
│   └── bootleg_rev_a.json    # Bootleg Rev A
└── ... 他のメーカーとモデル

実践的な演習：60%キーボード定義を作成する

標準的な60%キーボード定義を作成する手順を例にとってみましょう。

1. 基本情報を設定する

{
  "keyboardName": "My Custom 60%",
  "manufacturerId": "0xFEED",
  "deviceId": "0x6060",
  "keyMatrix": {"rowCount": 5, "columnCount": 14},
  "lightingType": "qmk_rgblight"
}

2. ANSIレイアウトを定義する

"layoutInfo": {
  "layoutLabels": ["ANSI"],
  "keyPositions": [
    ["0,0","0,1","0,2","0,3","0,4","0,5","0,6","0,7","0,8","0,9","0,10","0,11","0,12",{"幅":2},"0,13"],
    [{"幅":1.5},"1,0","1,1","1,2","1,3","1,4","1,5","1,6","1,7","1,8","1,9","1,10","1,11","1,12",{"幅":1.5},"1,13"],
    [{"幅":1.75},"2,0","2,1","2,2","2,3","2,4","2,5","2,6","2,7","2,8","2,9","2,10","2,11",{"幅":2.25},"2,13"],
    [{"幅":2.25},"3,0","3,1","3,2","3,3","3,4","3,5","3,6","3,7","3,8","3,9","3,10",{"幅":2.75},"3,13"],
    [{"幅":1.25},"4,0",{"幅":1.25},"4,1",{"幅":1.25},"4,2",{"幅":6.25},"4,5",{"幅":1.25},"4,8",{"幅":1.25},"4,9",{"幅":1.25},"4,11",{"幅":1.25},"4,13"]
  ]
}

3. ISOレイアウトをサポートする

labelsとkeyPositions配列を拡張してISOレイアウトをサポートします。

テストと検証

ビルドツール

VIAプロジェクトは完全なビルドツールチェーンを提供しています：

  • scripts/build_definitions.ts - 主なビルドスクリプト
  • scripts/build_all.ts - 完全なビルドフロー
  • scripts/build_names.ts - キーボード名リストを生成

検証手順

  1. 構文チェック：JSONフォーマットが正しいことを確認します
  2. マトリックス検証：すべての座標がマトリックス範囲内にあることを確認します
  3. レイアウトの一貫性：異なるレイアウトのマッピングが正しいことを確認します
  4. 一意性チェック：メーカーIDと製品IDが重複しないことを確認します

ベストプラクティスとよくある問題

ベストプラクティス

  • 簡潔に保つ：必要なレイアウトバリエーションのみを定義します
  • 意味のある名前を使用する：他の開発者が理解しやすいようにします
  • コメントを追加する：複雑な部分にコメントを追加します
  • バージョン管理：異なるバージョンに対して個別のJSONファイルを作成します

よくある問題の解決策

問題1：VIAがキーボードを認識しない

  • manufacturerIdとdeviceIdがファームウェアと一致していることを確認します
  • マトリックスサイズが正しいことを確認します
  • JSON構文が正しいことを検証します

問題2：キーのマッピングが誤っている

  • マトリックス座標が正しいことを確認します
  • 特殊キーの幅/高さ設定が正しいことを確認します
  • レイアウトラベルの対応関係が正しいことを検証します

問題3：照明機能が異常

  • lightingTypeフィールドの値が正しいことを確認します
  • ファームウェアが対応する照明タイプをサポートしていることを確認します

高度な機能の探求

マクロサポート

VIA定義ファイルを使用して、ユーザーが簡単に設定できる複雑なマクロ機能を事前に定義できます。

レイヤー管理

複数のレイヤーキーマッピングをサポートし、キーボード機能を強化します。

リアルタイム設定

VIAの最大の利点はリアルタイム設定であり、ユーザーがファームウェアを書き換えることなくキーボード設定を変更できることです。

まとめ

VIAキーボードJSON定義ファイルを作成することは、カスタムキーボードにVIAサポートを追加するための重要なステップです。このガイドを通じて、以下の内容を学びました：

  • VIA JSON定義の基本構造を理解する
  • 基本的なキーボード設定ファイルを作成する
  • 複雑なマルチレイアウトシーンを処理する
  • 設定ファイルを検証およびテストする
  • ベストプラクティスに従って一般的な問題を避ける

良いVIA定義ファイルがあれば、自分自身だけでなくコミュニティ全体のユーザーもリアルタイム設定の利便性を享受できます。今すぐ自分のキーボードにVIAサポートを追加しましょう！

関連リソース

  • 公式ドキュメント：VIA仕様説明ドキュメント
  • ビルドスクリプト：scripts/build_definitions.ts
  • サンプルファイル：src/0_sixty/0_sixty.json
  • ツールチェーン：プロジェクトが提供するビルドツールを使用して互換性を確保する

VIAキーボードJSON定義をマスターすることで、QMKファームウェアのキーボードに強力なリアルタイム設定機能を追加し、キーボードカスタマイズをより簡単かつ柔軟にすることができます！🎉

タグ: VIA QMK キーボード JSON キーマトリックス

9月28日 16:53 投稿

ホットタグ

©2026 異端開発室