QMK Firmwareを使ってコンパイル

さて、ハード面が終われば、後はソフト面としてファームウェアを作成してキーボードに書き込めば完成です。ここではプログラマでもなく、Githubもこれまで距離をとっているようなデザイン寄りのWebスクリプター的な私のような人が理解できるように書きます。私のような初心者でもできちゃうはずです。

取り掛かる前に

基本はWindows、Mac、LinuxなどのPC環境があればいいわけですが、私の環境、Windows 10で行う場合の説明になります。以下を進めるにあたり、すごく大事なことはこれです。

QMK Configurator対応のPCBで複雑なことをやらない場合

使用するPCB（基盤）によるわけですが、大抵のものはQMK ConfiguratorというWebインタフェースのみでファームウェアのコンパイルまで出来てしまいます。この場合はこの記事にあるコマンドプロンプトなどをいじる必要がなく幸せに最短で話が済みます。その場合はQMK Configuratorの説明記事へ飛んでそちらで進めるといいかも。複雑なことをやらないと言っても、Configuratorで大抵の機能は網羅されていますのでお急ぎの方はそちらへどうぞ。

QMK Configuratorの使い方／DZ60RGB V1の設定

以下の記事はDZ60RGB V1を例としていますが、QMK Configuratorが対応...

QMK Configurator対応かどうかわかんないよ！

PCBの入手経路によりますが、通常は製品の情報として書かれているかと思います。で、「QMK対応」ということは、どのPCBでも変わりないと思いますが、逆にそうじゃないキーボードだった場合はたぶん私はお手上げです。例えば大手メーカー品を買った場合などにはこれに当てはまります。

次に「QMK対応」には3つのコンパイル環境があります。

1 QMK Configurator
2 kbfirmware
3 コマンドライン

QMKの正式なレポジトリに登録されているPCBは、時間差はありますがQMK Configuratorの対応リストとイコールになるはずです。また「2」のkbfirmwareには年単位で古いQMKが使われていて、別のWebインタフェースが用意されています。この2つには互換性はありません。（ないのですが、無理やり対応にする方法はあります。私が使っているPCBもQMKの正式なレポジトリには登録がなく、仕方ないのでコンバートして対応させました。）

ただ、コンパイラが古いだけでkbfirmwareでもそこそこなことはできますので、そのまま使っちゃうのも全然ありではあります。

QMK Configurator対応ではないけど、kbfirmwareには対応しているしそれでいいんじゃないという場合にはこちらの記事を使ってください。

kbfirmwareの説明記事へ飛ぶ

残りの方はコマンドラインとの戦いです。そしてWebインタフェースではできないマクロ機能などを使いたい、Configuratorではできない他の機能を使いたい場合もコマンドラインとの戦いになります。

↓いざっ

準備

基本はQMK公式のページにある内容のとおりになりますが、簡単に抜粋していきます。
ダウンロードすべきものなどがあります。
https://docs.qmk.fm/#/newbs_getting_started

必要なもの

ファームウェアを書き込みたいPCB
PCBと接続するためのUSBケーブル
デスクトップかラップトップPC

Windwos 10ではこれらをダウンロードしてください。

Msys2 http://www.msys2.org/
QMX Toolbox https://github.com/qmk/qmk_toolbox/releases
好みのテキストエディタ（すでにあればそれでOK）

テキストエディタはメモ帳でもダメってことはないですが、コード内容によって色分けしてくれたりするもの、行数がわかるものが最低限欲しいです。私はNotepad++を使っています。が、将来的に複数のキーボードをいじり始めたり、他のキーボードのファイルを参照したりとややこしくなってくることを考えると、Vscode (Visual Studio Code）を入れておくとコンパイルまでいけてしまうので便利かなぁと思います。やや設定が面倒になるのでそのうち別記事で。

Msys2はインストールするだけですぐにQMK Firmware作業に入れてしまうスグレモノです。何でもいいんでコマンドラインを少しだけでいじったことがあれば問題なく使えます。私でも全然OKでした。可能な限りCドライブにデフォルトのままインストールしてください。「C:msys64/……」

Windows 10であればほとんど皆さん64bitだと思うので、そちらをインストールしましょう。

初回インストール時にはドライバーのインストールを求められますが、そのままインストールしちゃってください。別画面でインストールされます。

msys2の設定など

インストーラーで注意すべきはディレクトリだけ。ここはなるべくCドライブにデフォルトのままインストールします。

インストールが完了したら、msys2が起動しているかも知れませんが一旦ウィンドウを閉じて終了させます。インストールしたディレクトリにある「mingw64.exe」の方を起動します。

このウィンドウが開きます。

ここにコマンドを打ち込んでQMKを使える環境にしていきます。

$の出ている行に以下のコマンドを入力&リターンします。Windowsのコピペショートカットは使えないので、コピーした場合はスクリーン上で右ボタン→Pasteしてください。

pacman -S git

これでGitを扱うのに必要なファイルやプログラムがダウンロード＆インストールされます。結構時間かかりますが、その途中で何度かドライバのインストールなどが尋ねられます。すべてY（Yes）かA（All）としてください。

完了したら、今度は2つのコマンドを使ってQMKのレポジトリをローカル環境に持ってきます。元々自分Githubアカントがある場合は、Forkしたものを持ってくるのもありです。

git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
cd qmk_firmware

一番最後の「qmk_firmware」はコピーする先のディレクトリ名になりますが、特に理由がなければこのままにしておきます。これが終わったらローカルで以下のコマンドを使って設定を終わらせます。

util/qmk_install.sh

最後にコンパルできるかテストをしておきます。qmk_firmwareのディレクトリにいることを確認して試しに以下のコマンドを打ちます。

make clueboard/66/rev3:default

少し時間が掛かりますがグリーンの[OK]の文字が何行か流れたあとに元の$表示に持っていれば完了です。qmk_firmwareをインストールしたディレクトリに移動するか、あるいはWindowsでqmk_firmwareのフォルダを開いてみて、そこに「clueboard_66_rev3_default.hex」が生成されていれば成功。これで目的のキーボードのファームウェアをコンパイルする環境が準備できました。

QMKのディレクトリ構造を覚えちゃうと楽です。

一般的な感じはこうなっています。「Keyboard」以下にすべてのPCBが羅列され、目的のPCBをそこで見つけることができますが、新たに作る場合もここに置きます。

PCBディレクトリにはワイヤー配線など、設計ファイルやコンパイルオプションの設定ファイルが並びます、ひとつ下の「Keymaps」ディレクトリにいじる対象のキーマップが含まれます。qmkでは、ここにdefaultディレクトリを置き、そこに基本となるキーマップを置くルールになっています。ローカルに置いたものなのでdefaultをいじっちゃってもいいっちゃぁ、いいんですけどね。ちなみにこれによって何が変わるかというと、コンパイルするときのキーマップの指定が変わります。なので、dedaultを残しておけば、コマンドを変えるだけでオリジナルのキーマップでコンパイルすることができるわけです。

keymac.cの中身はこんな感じになります。

この例だとレイヤーが3つ、キーコード名が長くなるのでdefineを使って名称を変換しているというものになります。それぞれのコードは「,」で区切られているだけですので、見やすくする工夫をしている例も多くあります。下のものは先日、作らせていただいたくまお工房さんのKudox rex2のキーマップです。これはワンキーでIMEをトグルするためのマクロをこのファイル内で書いています。

あまり難しく考えずとも、コピーしたdefaultのキーマップをベースに、一部いじりたいところを書き換えればいいだけ。詳しいことは本家の木キーコードを参照します。注意すべき点は全角文字などを使わないこと、カンマや＿は下手に消しちゃわないように気をつけること、そしてRESETがあれば必ず残すように（配置換えはOK）すること。

QMKキーコードリスト

https://docs.qmk.fm/#/ja/keycodes

コンパイルしてPCBへ書き込み

キーマップをいじる前に一度デフォルトのまま書き込めるかまでテストしておきたいかもですね。キーマップの変更を保存したら、Msys2を起動してqmk_firmwareのインストールされたディレクトリへ移動します。

cd qmk_firmware

このディレクトリでファームウェアをコンパイルします。

make <PCB名>:<キーマップ名>

例として

make bm60hsrgb:default
make kudox/rev2:ime_togg

などとなります。PCB名はkeyboadディレクトリに存在するPCBのディレクトリ名に合致している必要があります。「:」を挟んでキーマップ名はkeymapsフォルダ内のキーマップのディレクトリです。初期設定を使う場合は「default」、他のものにしたい場合には自分が作成したkeymap.cの置かれているディレクトリ名となります。

make  <PCB名>:<キーマップ名>:dfu

緑文字の[OK]が流れてエラーが出ない状態でコマンドプロンプトに戻っていればコンパイルが完了しています。

ここで選択肢。そのままmsys2を使ってPCBに書き込みを行う場合は、コンパイルのコマンドに「:dfu」や「:flash」などを追加します。そうすることで、コンパイル後にdfuモードのPCBをシリアルUSB上で検索しますで、物理RESETをするか、あるいはあらかじめ設定されているRESET用のキーを押します。PCBがうまいこと見つかれば自動的に書き込みが開始されます。

このスクリーンショットではコンパイルが終わったあと5秒毎にブートローダーを探しているメッセージが表示されます。もしキーボードが準備できてなくてキャンセルしたい場合にはCtrl+Cを押して中断してください。

これがうまく行けばいいんですが、なぜかデスクトップPCだとエラーが出てしまって、ラップトップだとうまくいったり、恐らくmsys2の環境構築時の問題なんだと思うのですが、理由はともあれエラーが出てしまうことがあります。できれば他のPCで試すのが原因の切り分けがしやすいですが、無理な場合はQMK Toolboxを使ってコンパイルしたファームウェアを書き込んでみてください。ダメ元ってことで。

これで一通りのQMK Firmwareお説明は終わりです。