はじめに

自作キーボード #2 Advent Calendar 2018 5日目の記事です。

ここではプログラマーではない人向けの入門記事です。

構成としては、以下になります。

QMK Firmwareのビルド環境構築
QMK Firmwareのビルド
キーマップの変更

3のキーマップの変更だけをやりたいところですが、プログラマーでない人向けということで、1や2で躓くことが多いので、ここらに説明をそれなりに割いています。

QMK Firmwareのビルド環境構築

ビルド環境といいましても、いろいろとバリエーションがあります。
OS（Windows、Mac OSX、Linux）も複数ありますし、ファームウェア作成用のWebサービス¹があったり、実際にファームウェアへの書き込み方法もCUIだけでなく、GUI操作のQMK Toolboxなどがあります。

1. MSYS2をインストール

MSYS2とは、Windows上で動くUnixシェル環境で、Windows上でQMK Firmwareをビルドするために使います。
ほかのシェル環境でもビルドはできますが、紹介しだすときりがないので、MSYS2に限定します。

MSYS2は https://www.msys2.org/ からダウンロードできます。
注意する点は、いまどき使用しているOSは64bit版がほとんどのため、64bit版であるx86_64とついてる方をダウンロードしてください。³

2. MSYS2のパッケージを最新へ更新

インストール直後にMSYS2が起動しているのなら、そのままにしてください。
そうでないなら、MSYS2を起動させてください。
先ほどインストールした先(デフォルトだとC:\msys64)にmsys2.exeがあるので、マウスでダブルクリックすると起動します。
Windows10だとタスクバーにピン止めしておくと、次からいちいち探さなくて便利だと思いますが、その場合は起動時にどれで起動するかと聞かれますので、「MSYS2」を選んでください。

以下のコマンドを打ち込んで（コピペでも可）、エンターキーを押して実行させてください。

pacman -Syu

以後、「コマンドを実行してください」という場合はこのようなことをしてもらいます。

上記コマンドが終了したら以下のコマンドを実行してください。

pacman -Syu

途中、コマンド実行が止まることがありますが、いったんMSYS2を落として(ウィンドウの右上のx印をクリック)から、再度起動させてから、再度同じコマンドを打ち込んで実行してください。

3. QMK Firmwareをダウンロード

QMK FirmwareをGithubからダウンロードします。
git⁵を使うと便利な点があるのですが、今回はなるべく説明を平易にしたいために、扱わないことにします。

以下のURLをブラウザで開いてください。

そうすると、qmk_firmware-master.zip というファイル名でzipファイルがダウンロードが開始されるはずです。
そのzipファイルの展開先はお好みの場所でいいのですが、こだわりがなければ以後の説明の都合もあり、C:\直下がいいと思います。
あと、zipファイルの展開先で同名ディレクトリ⁶が2重で作成されている場合は、子ディレクトリ内をすべて親ディレクトリに移動という感じのことを行って、解消してください。

4. QMK Firmwareのビルドに必要なツール類のインストール

QMK Firmwareをビルドするために必要なツール類をインストールします。

MSYS2上で、先ほど展開したディレクトリに移動させてください。

cd /C/qmk_firmware-master

C:\直下の場合に展開した場合になりますが、ほかの場所に展開した場合やディレクトリを別名にした場合は適宜読み変えてください。

そのあと、以下のコマンドを実行してください。

./util/msys2_install.sh

何かしら聞かれますが、基本的にYもしくはAもしくはそのままエンターで問題ないです。
途中、別ウィンドウを開くための許可を求めるダイアログ(インストーラを実行したときのアレ)が表示されるので、はいを押してください。
それなりに時間がかかりますので、音楽を聴くなり動画を見るなりと、何か別の作業をしながらやるのがいいでしょう。

問題なく無事完了したら、いったんMSYS2を落として、再度起動してください。⁷

環境構築は以上になります。

QMK Firmwareのビルド

QMK Firmwareのビルドをやっていきます。
ビルドというと何をしているかというと、ざっくりとした説明になりますが、QMK Firmwareのソースコードからコンパイルを行い、Pro Microで実行するためのバイナリファイル(.hex)を生成することを行っています。

では、実際ビルドを行いますが、対象キーボードが何かというmint60で行いますが、そこは自分が使うキーボードに読み替えてください。
MSYS2上で、qmk_firmwareがあるディレクトリに移動させてください。

cd /C/qmk_firmware-master

先ほどと同じように、上記コマンドで移動できるでしょう。（もちろん、ほかの場所に展開した場合やディレクトリを別名にした場合は適宜読み変えてください）

では、早速ビルドできるかどうかを試すために、defaultキーマップでビルドを行うために、以下のコマンドを実行してください。

make mint60:default

エラーが表示されずに、以下のような生成されたファイルのファイルサイズが表示されれば成功です。

The firmware size is fine - 20834/28672 (7838 bytes free)

問題がなければ、次にPro Microにファームウェアを書き込みましょう。
以下のコマンドを実行してください。

make mint60:default:avrdude

そうすると、make mint60:defaultで行ったのと同じビルドが実行され、以下のようなメッセージが出て、「.」が出力され続けます。

Detecting USB port, reset your controller now.

自作したキーボードを接続し、リセットボタンを押してください。
そうすると、Pro Microへの書き込みが開始されます。

avrdude.exe done. Thank you.

このメッセージが表示されれば、成功です。
分割キーボードなら、この作業をもう片方のキーボードについても行う必要があります。

余談になりますが、シェルにはヒストリーという機能がありまして、カーソルキーの上を押すと、過去実行したコマンドの履歴が表示され、再度実行することができます。
上を押せば1つ過去へ、下を押せば1つ現在への履歴が表示されますので、エンターキーを押せば、表示されているコマンドが実行できます。
ビルド自体、1回で終わりではなく、何回も行うようなものなので、GUIでの操作に比べると格段に楽だと思います。

ビルドについては以上になります。　

キーマップ変更

1. 事前準備

キーマップの変更をする前に、defaultの設定をいじるのは良くないため、あなたがカスタマイズするため専用のkeymapディレクトリを、defaultからコピーして作りましょう。
この時のディレクトリ名ですが、あなたがPCで使用しているユーザ名や、SNSで使用しているHNなんかがいいと思います⁸。

cp -R keyboards/mint60/keymaps/default/ keyboards/mint60/keymaps/nemo

ここでdefaultを触らないようにした理由ですが、以下になります。

自分のkeymapでビルドできなくなった時に、defaultでビルドしてみて、ビルドできるかどうかを確認して問題を切り分けるため
自分のkeymapの設定でどこがまずいかを、defaultとの差分を見ることで、どこがまずいかを判別しやすくするため。
defaultのキーマップに戻したくなった時に、すぐに戻せるようにするため

もちろん、nemo_rev1, nemo_rev2といったように、バージョンごとにこまめにkeymapディレクトリをコピーしておくと、よりいいと思います。

さて、コピー自体は一瞬で終わるはずなので、キーマップのカスタマイズに移ります。
本当はC言語をわかっていないと本格的なカスタマイズは難しいですが、キーマップのカスタマイズならC言語の知識はほぼ必要ないです。

では、先ほどコピーしたディレクトリ内のキーマップファイル(keymap.c)を好みのテキストエディタで開いてみましょう。
mint60のdefaultのkeymap.cの場合、38行目からの53行目までがキーマップ定義になります。
ほかのキーボードでも、keymapsとかかれた部分を目印にして探してみてください。
ここではmint60に限定して話を進めます。

 38 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 39   [0] = LAYOUT( \
 40     KC_GRV,  KC_1,    KC_2,    KC_3,    KC_4,    KC_5,      KC_6,    KC_7,    KC_8,    KC_9,    KC_0,    KC_MINS, KC_EQL,    KC_BSPC,  \
 41     KC_TAB,    KC_Q,    KC_W,    KC_E,    KC_R,    KC_T,      KC_Y,    KC_U,    KC_I,    KC_O,    KC_P,    KC_LBRC, KC_RBRC, KC_BSLS,  \
 42     KC_CAPS,     KC_A,    KC_S,    KC_D,    KC_F,    KC_G,      KC_H,    KC_J,    KC_K,    KC_L,    KC_SCLN, KC_QUOT,        KC_ENT,   \
 43     KC_LSFT,       KC_Z,    KC_X,    KC_C,    KC_V,    KC_B,      KC_N,    KC_M,    KC_COMM, KC_DOT,  KC_SLSH, KC_RSFT,   KC_UP,  MO(1),   \
 44     KC_ESC,    KC_LCTL,    KC_LGUI,    KC_LALT,    KC_SPC,        KC_BSPC, KC_ENT,  LALT(KC_GRV),               KC_LEFT,KC_DOWN,KC_RGHT \
 45   ),
 46   [1] = LAYOUT( \
 47     KC_ESC,  KC_F1,   KC_F2,   KC_F3,   KC_F4,   KC_F5,     KC_F6,   KC_F7,   KC_F8,   KC_F9,   KC_F10,  KC_F11,  KC_F12,    KC_DEL, \
 48     RGB_TOG,   RGBRST,  RGB_HUI, RGB_SAI, RGB_VAI, XXXXXXX,   XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, \
 49     XXXXXXX,     RGB_MOD, RGB_HUD, RGB_SAD, RGB_VAD, XXXXXXX,   XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX,        XXXXXXX, \
 50     _______,       XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX,   XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, XXXXXXX, _______, KC_PGUP, _______, \
 51     XXXXXXX,   _______,    _______,    _______,    XXXXXXX,       XXXXXXX, XXXXXXX, XXXXXXX,                   KC_HOME, KC_PGDN, KC_END \
 52   )
 53 };

39行目から45行目までがレイヤー0の定義、46行目から52行目までがレイヤー1の定義になります。
レイヤーについては、あとで説明をします。

2.キー割り当ての変更

ではここでいつもいつもいつも邪魔なCapsLockキーを無効化(押しても何も反応しない)してみましょう。
「KC_CAPS」とあるところ、レイヤー0の定義の上から3行目(ソースコードの42行目)のいちばん左のところに、 XXXXXXX と変えて保存してみましょう。
XXXXXXX は何もしない、というものです。
そうすると、先ほどの章で行ったビルドをして、Pro Microに書き込んでみてください。
成功して、キーボードのCapsLockキーを押しても、何も起きないはずです。

おめでとうございます。これであなたは晴れてCapsLockキーの呪縛から解放されました。

冗談はさておき、CapsLockキーを押しても何もしない、ということが実現しましたが、これだと1キー無駄になりますので何かもったいないですよね？
ということで、このキーに別のキーをアサインしてみましょう。
よくあるケースとしては、Ctrlキーにしたい、というものです。
では、先ほどと同じ場所の「KC_CAPS」があったところを、 XXXXXXX ではなく、 KC_LCTL と変えて保存してみましょう。
ちなみに KC_LCTL というのは、左側のCtrlキーという意味で、右側のものをアサインしたければ、 KC_RCTL になります。
このように、左右にあるキーについては、それぞれとして定義することが可能です。
話を戻して、またビルドを行い、Pro Microに書き込んでみてください。
これでCapsLockキーがCtrlキーに変わりました。
同様に、Altキーに変えたり、ESCキーに変えたりと、好みのキーにすることも可能です。

3. レイヤー

先ほど、CapsLockキーはCtrlキーに変更することができましたが、これだとデフォルトで割り当てられているキーと被るため、あまりうれしくないです。
ほかのキーも合わせて変更していけばいいですが、そこでちょっとお勧めなものして、レイヤー変更キーにしてみましょう。
レイヤー変更キーは右側(上から4行目の一番右)にもありますが、Fn6を押したいときにはレイヤー変更キーを小指で押しながら親指で6を押すというすごく指が吊りそうになります。
かといって、右手側にあるキーに対して両手を使うのは負けた気になるので、ここは左側にレイヤー変更キーがあれば、この問題は解消します。
ということで、「KC_CAPS」があったところを、 KC_LCTL ではなく MO(1) と変えて保存してみましょう。
ちなみに、MO(番号)で、押したままで番号のレイヤーに移動します。（離すと、元のレイヤーに戻る）
レイヤーとは、キーマップを多層にして切り替えられるようにしている機能です。
mint60のデフォルトでは、レイヤー0は基本的なキーで、レイヤー1にFnキーとLEDの操作にしています。
話を戻して、またビルドを行い、Pro Microに書き込んでみてください。
これでCapsLockキーがレイヤー変更キーに変わりました。
今回は0と1しかレイヤーがないため、MO(1)にしていますが、別レイヤーを追加して、CapsLockキー追加したレイヤー変更のキーにする、としてもいいと思います。

補足

キーマップをカスタマイズをするうえで気を付けるところは、キーマップ定義のところで、各行の行末に「￥」がありますが、これは削除してはいけません。
理由についてはC言語の話になるのでここではしませんが、ビルド時にエラーになります。
また同じように、一番最後のものは「,」は不要で、これもあるとビルド時にエラーになります。
例えば、44行目の　KC_RGHT や51行目の KC_END の右隣にはカンマがない、ということです。

また、キーマップについて、トグルやダブルタップ、マクロなどはどうすればいいんだ、というのがありますが、説明を簡便にするためにここでは割愛しました。
このあたりについては、識者の方々がブログに上げていると思いますので、探してみるといいでしょう。
また、より詳しく知りたいという場合は、いきなりハードルが上がりますが、公式ドキュメント(英語)を読むのが確実だと思います。
https://docs.qmk.fm/#/

では、みなさん、よい自作キーボードライフを

補足の補足

この記事ははじめて自作したMint60で書きました。

https://config.qmk.fm/
とはいえ、ここではすべてを網羅できるわけではないので、一番ユーザが多いだろうWindows 10でかつCUI(MSYS2)でのビルド環境構築に限定して説明します。
なぜCUIかと言うと、記事での説明がしやすいのと、ビルドしてPro MicroにFirmwareを焼くことが何回も繰り返す場合に楽だから、という点です。
CUIというとハッカーな人が謎の黒い画面でカチャカチャするというイメージ²とかで怖いと思うかもしれませんが、ビルド環境構築以外は限定的な使い方しか行わないので、やってみると楽だという実感を持ってもらえると思います。 ↩
実際は黒い画面見ながらうなってることが多いかと ↩
使ってるOSが32bit版であるなら、i686がついている方をダウンロードしてください。
インストーラファイルのダウンロード後、インストーラファイルをダブルクリックすればインストーラが起動して、「次へ」を適当に押していけばインストールが完了します。
この時にインストール先を指定できますが、こだわりがなければデフォルト( C:\msys64 ⁴)でいいと思います。 ↩
「＼」は「￥」のことです。 ↩
バージョン管理システムの一つです。ソースコードの変更を保存し、その履歴を追ったり過去のものを取り出したりできるツールです。 ↩
Windowsでは「フォルダ」のほうが馴染みがありますが、「ディレクトリ」と意味は同じです。 ↩
実際は soucre ~/.bashrc を実行すればいいんですが、説明しだすと長くなるので割愛です。 ↩
例えば、筆者の場合は、「cac」としています。
思いつかなければ、nemoとかjohndoe, janedoeみたいなのでいいでしょう。
ここではnemoとしますので、自分の好みのディレクトリ名に適宜読み変えてください。 ↩