（設計者向け）VIA対応のファームウェアを作ろう

こんにちは。自キ温泉ガイドのサリチル酸です。

先日書いたVIAはいいぞ！という記事に対応する設計者向けの記事です。

※2020/10/06　レイヤー数変更手順の追加

はじめに

意外とVIA対応は簡単なので、自作キーボード設計者の皆さんは是非初心者への選択肢として用意しておきましょう、というわけで対応ファームウェアの作り方を書きたいと思います。

この記事は設計者、特に自作キーボードキットをすでに販売している方向けの記事なので、ファームウェア作成に必要な基本的な知識については補足しません。

ファームウェアの作り方等はQMK公式ドキュメントを参照してください。

また、VIA側のバージョンアップに伴って一部手順が変更になることもありますので、VIAのドキュメントも合わせて参照しておくことを強くオススメします。

VIA用ファームウェアの作成方法

まずはキーボードに書き込むVIA用のファームウェアを作成します。

公式ドキュメントの対応ページはこちらです。

DefaultキーマップをコピーしてVIA用のキーマップを作成する

viaというフォルダの名前にします。

viaフォルダのrules.mkにVIA_ENABLEを設定する

VIA_ENABLE = yes

rules.mkがなければ作成し、上記の「VIA_ENABLE = yes」とだけ入力します。

また、2020/7/25現在は以下のオプションには対応していないようです。（ドキュメントより）

• LEADER_ENABLE
• FAUXCLICKY_ENABLE
• MIDI_ENABLE
• BLUETOOTH_ENABLE
• KEY_LOCK_ENABLE
• TERMINAL_ENABLE

これらを有効にしているキーボードは無効にしておきましょう。

（多分Defaultキーマップで有効にしているキーボードは無いと思いますが）

keymap.cで定義するレイヤーの数を整理しておく

VIAではレイヤーの数はデフォルトで4となっており、ユーザ側でレイヤー数の増減はできない仕様となっているので、EEPROMの容量に不安や支障がなければ4つのレイヤーを準備しておくようにします。

使わなくても4つのレイヤーを用意しておきましょう

とりあえず準備だけしておけばいいのでKC_NOかKC_TRNSにしておきます。

（ドキュメントによるとオススメはKC_TRNSっぽい）

VID、PIDを～～する

ここは公式ドキュメントを参照してください。

付加的な機能を整理する

ロータリーエンコーダとかレイヤーインジケータなどのキーボード固有の設定はこの段階で書いておきます。

ここで書いておけばVIA側での操作はできないものの、ちゃんと動作します。

コンパイルしてファイルエラーをチェックする

エラーがあれば対応しておきます。

Hexファイルが生成されればOKです。

キーボードに書き込む

テストのためにキーボードに書き込んでみましょう。

KLEでキーレイアウトを作成する

KLEことKeyboard Layout Editorでキーボードのレイアウトデータを作成します。

この時、VIA用のキーマップjsonに変換しやすくするためにいくつかの注意が必要です。

Top Legendにキーマトリクスに対応する番号を入力する

キーマトリクスの通りにTop Legendに番号を入力していきます。

※この時、「,（カンマ）」で区切って入力すること。「.（ドット）」と間違えやすいので注意。

また、分割キーボードの場合、左側から右側にカウントしていきますので注意が必要です。

Key Colorを入力する

アクセントとなるキーについてはKey Colorに「#777777」を、モデファイアキーには「#aaaaaa」を入力します。

そうするとVIAで見たときに実際にキーキャップをはめたときのような感じに見えて綺麗で製品感が増します。

これはGMK Oliviaのカラースキームで表示されています。

異なるレイアウトの部分をBottom Legendに入力する

スプリットバックスペースやスプリットシフトに対応する場合等、一つのキーボードで複数のレイアウトに対応する場合、Bottom Legendに条件を記載します。

※傾いているキーは本項目の異なるキーレイアウトの定義はできません。

こんな感じでキーの選択肢があるレイアウトを作ります

0（VIAのレイアウト選択肢の番号）,（カンマ）0（VIAの選択したレイアウトの番号）

番号は以下のように後述のキーマップの定義と合わせる必要があります。

VIAに読み込ませるjsonファイルを作成する

ローカルにjsonファイルを作成する

キーボード名.jsonとか、適当なものを用意します。

フォーマットをjsonファイルにコピペする

以下に簡単なフォーマットを作ってみたので作ったjsonファイルにコピペします。

{
  "name": "7sKB",※キーボード名
  "vendorId": "0x",※QMKのものと同じものを書く
  "productId": "0x",※QMKのものと同じものを書く
  "lighting": "qmk_rgblight",※光らせたい場合書く
  "matrix": { "rows": 10, "cols": 8 },※QMK値をそのまま書く
  "layouts": {
    "labels": [
          ["Switch", "MX", "Choc"]※サンプル。左から順に、ラベル名、選択肢1、選択肢2
    ],
    "keymap": [
    ※ここにKLEのレイアウトデータをコピペする
    ]
  }
}

KLEからレイアウトデータをコピーする

Raw dataタグに出力されたレイアウトデータを、先程のjsonファイルの「※ここにKLEのレイアウトデータをコピペする」の部分にコピペします。

※KLEの右上の「Download」からJSONをダウンロードすると後の「keymapを編集する」の"（ダブルクオーテーション）で挟む工程をスキップできます。お好みでどうぞ。

コピペするとこんな感じになるはずです。

{
  "name": "7sKB",※キーボード名
  "vendorId": "0x",※QMKのものと同じものを書く
  "productId": "0x",※QMKのものと同じものを書く
  "lighting": "qmk_rgblight",※光らせたい場合書く
  "matrix": { "rows": 10, "cols": 8 },※QMK値をそのまま書く
  "layouts": {
    "labels": [
          ["Switch", "MX", "Choc"]※サンプル。左から順に、ラベル名、選択肢1、選択肢2
    ],
    "keymap": [
    [{c:"#777777"},"0,0",{c:"#cccccc"},"0,1","0,2","0,3","0,4","0,5",{x:1},"5,0","5,1","5,2","5,3","5,4","5,5","5,6","5,7",{c:"#aaaaaa"},"6,7"],
    [{w:1.5},"1,0",{c:"#cccccc"},"1,1","1,2","1,3","1,4","1,5",{x:1},"6,0","6,1","6,2","6,3","6,4","6,5","6,6",{c:"#aaaaaa",w:1.5},"7,7"],
    [{w:1.75},"2,0",{c:"#cccccc"},"2,1","2,2","2,3","2,4","2,5",{x:1},"7,0","7,1","7,2","7,3","7,4","7,5",{c:"#777777",w:2.25},"7,6"],
    [{c:"#aaaaaa",w:2.25},"3,0",{c:"#cccccc"},"3,1","3,2","3,3","3,4","3,5",{x:1},"8,0","8,1","8,2","8,3","8,4",{c:"#aaaaaa",w:1.75},"8,5","8,6"],
    [{x:1.5},"4,1",{w:1.5},"4,2",{w:1.5},"4,3",{w:1.25},"4,4\n\n\n0,0",{x:1,w:1.25},"9,0\n\n\n0,0",{w:2},"9,1",{w:1.5},"9,3","9,4"],
    [{y:0.5,x:5.5,w:1.5},"4,4\n\n\n0,1",{x:1},"9,0\n\n\n0,1"]
    ]
  }
}

キーボード名等の情報を埋めていく

name、vendorId、productId、lighting、matrix等を入力します。（割愛の構え）

※言わなくても分かると思いますが、「※」の注意書きは消してくださいね

公式ドキュメントの対応ページはこちらです。

{
  "name": "7sKB",
  "vendorId": "0x～～～",
  "productId": "0x～～～",
  "lighting": "qmk_rgblight",
  "matrix": { "rows": 10, "cols": 8 },
  "layouts": {
    "labels": [
          ["Switch", "MX", "Choc"]※サンプル。左から順に、ラベル名、選択肢1、選択肢2
    ],
    "keymap": [
    [{c:"#777777"},"0,0",{c:"#cccccc"},"0,1","0,2","0,3","0,4","0,5",{x:1},"5,0","5,1","5,2","5,3","5,4","5,5","5,6","5,7",{c:"#aaaaaa"},"6,7"],
    [{w:1.5},"1,0",{c:"#cccccc"},"1,1","1,2","1,3","1,4","1,5",{x:1},"6,0","6,1","6,2","6,3","6,4","6,5","6,6",{c:"#aaaaaa",w:1.5},"7,7"],
    [{w:1.75},"2,0",{c:"#cccccc"},"2,1","2,2","2,3","2,4","2,5",{x:1},"7,0","7,1","7,2","7,3","7,4","7,5",{c:"#777777",w:2.25},"7,6"],
    [{c:"#aaaaaa",w:2.25},"3,0",{c:"#cccccc"},"3,1","3,2","3,3","3,4","3,5",{x:1},"8,0","8,1","8,2","8,3","8,4",{c:"#aaaaaa",w:1.75},"8,5","8,6"],
    [{x:1.5},"4,1",{w:1.5},"4,2",{w:1.5},"4,3",{w:1.25},"4,4\n\n\n0,0",{x:1,w:1.25},"9,0\n\n\n0,0",{w:2},"9,1",{w:1.5},"9,3","9,4"],
    [{y:0.5,x:5.5,w:1.5},"4,4\n\n\n0,1",{x:1},"9,0\n\n\n0,1"]
    ]
  }
}

labelsを書く

異なるキーレイアウトをサポートするキーボードの場合、labelsを書きます。

必要ない場合はlabelsを消しておきます。

書き方は2種類です。

公式ドキュメントの対応ページはこちらです。

ラジオボタン

On/Offの選択肢のみの場合に使用します。

    "labels": [
          ”Split Left Shift”
    ],

プルダウンリスト

2種類以上から選ぶときに使用します。

    "labels": [
          ["Enter", "ANSI", "ISO","1.25u"]
    ],

keymapを編集する

c,w,x,yのそれぞれは"（ダブルクオーテーション）で挟まなければならないので、テキストエディタの置換機能を駆使して挟みます。

{
  "name": "7sKB",
  "vendorId": "0x～～～",
  "productId": "0x～～～",
  "lighting": "qmk_rgblight",
  "matrix": { "rows": 10, "cols": 8 },
  "layouts": {
    "labels": [
          ["Switch", "MX", "Choc"]※サンプル。左から順に、ラベル名、選択肢1、選択肢2
    ],
    "keymap": [

    [{"c": "#777777"},"0,0",{"c": "#cccccc"},"0,1","0,2","0,3","0,4","0,5",{"x": 1},"5,0","5,1","5,2","5,3","5,4","5,5","5,6","5,7",{"c": "#aaaaaa"},"6,7"],
    [{"c": "#aaaaaa","w": 1.5},"1,0",{"c": "#cccccc"},"1,1","1,2","1,3","1,4","1,5",{"x": 1},"6,0","6,1","6,2","6,3","6,4","6,5","6,6",{"c": "#aaaaaa","w": 1.5},"7,7"],
    [{"c": "#aaaaaa","w": 1.75},"2,0",{"c": "#cccccc"},"2,1","2,2","2,3","2,4","2,5",{"x": 1},"7,0","7,1","7,2","7,3","7,4","7,5",{"c": "#777777","w": 2.25},"7,6"],
    [{"c": "#aaaaaa","w": 2.25},"3,0",{"c": "#cccccc"},"3,1","3,2","3,3","3,4","3,5",{"x": 1},"8,0","8,1","8,2","8,3","8,4",{"c": "#aaaaaa","w": 1.75},"8,5","8,6"],
    [{"x": 1.5,"c": "#aaaaaa"},"4,1",{"w": 1.5},"4,2",{"w": 1.5},"4,3",{"w": 1.25},"4,4\n\n\n0,0",{"x": 1,"w": 1.25},"9,0\n\n\n0,0",{"w": 2},"9,1",{"w": 1.5},"9,3","9,4"],
    [{"y": 0.5,"x": 5.75,"w": 1.5},"4,4\n\n\n0,1",{"x": 1},"9,0\n\n\n0,1"]
    ]
  }
}

作ったjsonファイルのテストをする

VIAを起動し、「SETTINGS」タブの「Show Design tab」を有効にします。

するとDesignタブが表示されるので、Loadボタンを押して作ったjsonをロードします。

成功するとキーレイアウトが表示されます。

ありがちなエラー

ダブルクオーテーションくくり忘れ

カンマではなくドット

テストする

実際にキーボードを接続してテストしましょう。

テストはVIAのKEY TESTERを使用すると便利です。

おまけ：VIAへのマージ方法

VIAへマージされることでVIAの対応キーボードページでファームウェアがダウンロード出来るようになりますし、VIAを接続するだけでキーボードが自動認識されるようになって非常に便利になります。

マージ方法は以下の4工程です。

1. VIAのリポジトリをフォーク
2. 「src」配下にキーボード名のディレクトリ、もしくは作者名のディレクトリを作成
3. 作成したディレクトリに作ったjsonファイルを配置
4. プルリクする

プルリクのルールはプルリク時にフォーマットが表示されるので、別途参照してください。

マージは1ヶ月くらいはかかるので、そういうタイムスケールで構えていくと安心です。

※私はプルリクのサポートはできないので他のプルリクの様子を見てご自分での対処をお願いします。

おまけ2：VIAで認識するレイヤー数を変更する

VIAキーマップフォルダにconfig.hを作成し、以下のコードを書いておきます。

#pragma once

#define DYNAMIC_KEYMAP_LAYER_COUNT 3

※80キー前後ではレイヤー数を4にするとProMicroのEEPROMの容量オーバーとなって書き込めないので3に減らす必要があります。

後はkeymap.cのレイヤー数を合わせて定義しておきます。

Remapの最新のQMKへの対応状況

VIAとRemapへの対応は、以前は一緒だったのですが、現時点では異なっています。

本記事更新時点（2023/2/16）ではVIAは最新のQMKバージョン19に対応していますが、Remapは最新のQMKバージョン19には追従していません。

よって、最新の環境でファームウェアを書くとRemapでは対応できないということになります。

利用するだけならなんの問題もありませんが、ファームウェアを作成しようとしている方はRemapのファームウェア対応状況を確認してください。

www.eisbahn.jp

Remap対応ファームウェアを作成する場合は、以前のQMKバージョン18を用いて環境を構築し、ファームウェアを作成してください。

github.com

おわりに

あまり難しくなかったと思いますが、VIA対応はできそうでしょうか。

この記事によりVIA対応キーボードが増え、これから入沼入ってくる初心者へのキーマップ変更の選択肢が増えるといいなと思っております。

本記事に対して問い合わせ等あれば遠慮なく私のDiscordまでどうぞ。

salicylic-acid3.hatenablog.com

本記事はNaked64SF v2で書きました。