自作キーボード温泉街の歩き方

自作キーボードの世界は温泉に例えられます。自作キーボードの温泉街の楽しい歩き方を紹介します。

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

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

深海探査服・潜水服のイラスト

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

はじめに

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

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

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

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

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

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

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

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

f:id:Salicylic_acid3:20200725004518p:plain

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

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

VIA_ENABLE = yes

rule.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つのレイヤーを準備しておくようにします。

f:id:Salicylic_acid3:20200725005630p:plain

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

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

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

VID、PIDを~~する

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

付加的な機能を整理する

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

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

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

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

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

キーボードに書き込む

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

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

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

f:id:Salicylic_acid3:20200726003847p:plain

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

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

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

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

f:id:Salicylic_acid3:20200725014234p:plain

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

f:id:Salicylic_acid3:20200726003838p:plain

f:id:Salicylic_acid3:20200725013618p:plain

Key Colorを入力する

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

f:id:Salicylic_acid3:20200725014201p:plain

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

f:id:Salicylic_acid3:20200724013623p:plain

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

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

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

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

f:id:Salicylic_acid3:20200725015638p:plain

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

f:id:Salicylic_acid3:20200726003956p:plain

f:id:Salicylic_acid3:20200726004107p:plain

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

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

f:id:Salicylic_acid3:20200725015550p:plain

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からレイアウトデータをコピーする

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

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

f:id:Salicylic_acid3:20200726004254p:plain

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

{
  "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の選択肢のみの場合に使用します。

f:id:Salicylic_acid3:20200725022017p:plain

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

プルダウンリスト

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

f:id:Salicylic_acid3:20200725022231p:plain

    "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」を有効にします。

f:id:Salicylic_acid3:20200725022939p:plain

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

f:id:Salicylic_acid3:20200725023206p:plain

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

f:id:Salicylic_acid3:20200725023613p:plain

ありがちなエラー

f:id:Salicylic_acid3:20200725023324p:plain

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

f:id:Salicylic_acid3:20200725023417p:plain

カンマではなくドット

テストする

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

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

f:id:Salicylic_acid3:20200724012432p:plain

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

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

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

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

 

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

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

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

おわりに

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

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

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