Helixファームウェアのカスタマイズ 1

●「QMK Configurator」でのファームウェア・カスタマイズに失敗

Helixには、自作キーボード界では一番メジャーなファームウェアである、「QMKファームウェア」が使われている。このファームウェアは、オーソリニア型キーボードメーカーOLKB社のJack Humbert氏が開発したもので、オープンソースとしてGitHubで公開されている。
これをベースにHelixキーボードの作者、倉内さんがHelix用に最適化したデフォルトファームウェアもGitHubで公開されていて、筆者もそちらをダウンロードし、QMK Toolboxで書き込みして、キーボード組み立て後の動作確認を行った。

一般的なローマ字入力をするのであれば、Helix用のデフォルトファームウェアそのままで使えるのだが、筆者の場合、カスタマイズしないと独自配列の親指シフトが使えなくなってしまう。
最初からカスタマイズ前提でHelixを購入したので、ここは必須である。しかし実際にはカスタマイズに成功するまで、悪戦苦闘してしまった。

QMKファームウェアのカスタマイズの方法は、大きくわけて二つある。
方法1は、開発者が用意してくれたカスタマイズ用のツール「QMK Configurator」を使うこと。
方法2は、QMKファームウェアのサイトから必要なファイル一式をダウンロードした上で、これを書き換えて、マイコン用に書き込むこと。
まずは簡単そうな、方法1を試してみることにしよう。
QMK Configuratorのサイトへ行くと、以下のような画面が表示された。

上の画面の「きーぼーど」の欄の下向きの<をクリックすると表示される一覧の中から、「helix_rev2」を選択。これはHelixの5段用のデフォルトファームウェアだ。
すると、Helixのキー配列が画面に表示される。
これをマウスで操作すると配列を変更できるのだ。
大変、わかりやすい。

Helixのキー配列の画面の下には、一般的なキーボードが表示されている。

下のキーボードの各キーの中には、アルファベットや記号が書かれている。それをマウスで左クリックし、そのまま指を離さずにマウスのカーソルを上のHelixのキーボードのキーの上に持ってきて指を離す(ドラッグ&ドロップ)と、Helixのキーの文字が書き換えられる。
同じようにドラッグ&ドロップして、Helixのキー同士で文字を入れ替えることもできる。
別のやり方もある。
Helixのキーの中の×マークをクリックすると、キーの文字が消える。その状態で今、使っているキーボードの文字キーをクリックすると、その文字が表示されるようになる。

下に表示されているキーボードにはANSIとかISO/JISといった選択タブがある。ISO/JISを選ぶと、「かな」や「変換」も選択可能だ。
Quantamタブでは、QMK特有の機能キー(レイヤー移動)を選択できる。

helix_rev2では0~5まで合計6段のレイヤー(階層)にキーが割り当てられている。
これをベースに、各レイヤーのキーマップを自分好みに変更。
一通り設定が終わったら、右上の緑の「COMPILE」ボタンをクリックすると、豆マークが表示されて回転し始める。
これは書き換えたキーマップを、マイコンに書き込める形式のファイルに変換(ビルド)中ということ。
少々時間がかかるが、豆マークが消えたら、ビルドが完了したということなので、今度は黒画面右下の「Firmware」ボタンを押し、カスタマイズしたファームウェアをダウンロードする。
その後は、デフォルトファームウェアを書き込むときにも使った「QMK Toolbox」を、「qmk_toolbox.exe」をダブルクリックして起動し、ダウンロードしたファームウェアを選択した上で、Pro MicroをPCとUSB接続し、書き込みする。
キーボードのリセットボタンを押し、qmk_toolboxの黒い画面に黄色い文字で「Connected 」とメッセージが出たら、画面右上の「flash」ボタンをクリックする、という手順だ。黒い画面に「avrdude.exe done. Thank you.」と表示されたら、書き込み完了。

今回、左右とも問題なく書き込みできた……ように、見えた。
ところが実際にHelixをPCにつないでキーを打ってみると、なぜか文字入力ができない。そればかりか、マウスやファイラーまで異常動作を起こしてしまった。
何が起きたのか、さっぱりわからない。
とにかく、これでは使い物にならないので、PCを再起動し、QMK ToolboxでHelixにもとのデフォルトファームウェア「helix_rev2_default_oled_underglow.hex」を書き込み直した。

●「msys2」によるカスタマイズも失敗

なぜか方法1がうまくいかないので、方法2をやってみることにした。
遊舎工房のHelixのページの「ファームウェア」を参考に、「msys2」を使ってカスタマイズするやり方である。
なおmsys2とは、Windows上にUNIXやLinuxの開発環境を作り出すツールのこと。
カスタマイズの手順は以下のようになる。

まずはQMKファームウェアのサイトから、ファイル一式をまとめてダウンロードする。
そのやり方は、ページ右側の緑色の「Clone or download」ボタンをクリックし、出てきた「Download ZIP」をクリックして、ZIPファイルをダウンロードし、解凍する。今回はC/Users/ユーザー名/OneDrive/Downloads/QMK/ というフォルダに解凍した。
続いてmsys2のサイトから、64bit OS用の「msys2-x86_64-20190524.exe」をダウンロードし、ダブルクリックしてインストール。
出てきたmsys2.exeをダブルクリックしてmsys2を起動する。すると黒画面が出てくるので、そこに、
cd /C/Users/ユーザー名/OneDrive/Downloads/QMK/qmk_firmware-master/
と入力。これでダウンロードしておいたQMKファームウェアのフォルダに移動したことになる。
util/msys2_install.sh と入力し、enterを押す。
インストールするパッケージを聞かれるので、記号を入力せずにenterを2回押す。
これでデフォルトの「ALL」が選択される。
「Do you want install?」とY/N で聞かれるので、yを入力してenter。
かなり待った後、「Which USB drivers do you want install?」と訊かれるので、(A)all を選び、Aと入力。
ここで動作が停止し、「この不明なアプリが……」とWindowsに許可を求められるので、「はい」をクリック。
しばらく待ち、AVRのインストールを求められたので、yを入力、enter。
「Do you want install?」と訊かれたので、yを入力、enter。
また「Do you want install?」と訊かれたので、yを入力、enter。
しばらく待ち、「Do you want to add ~」と訊かれたので、yを入力、enter。
「Installation completed!
Please close this Window and restart MSYS2 MinGW」
と表示された。
これで書き込み用のツールがインストールされた。

続いてカスタマイズ用のフォルダを作成する。
「qmk_firmware-master.zip」を展開した先の、/keyboards/helix/rev2/keymaps/ にある defaultフォルダをまるごとコピーし、名前を変えて/keyboards/helix/rev2/keymaps/ に貼り付ける。
名前を変えたフォルダの中のkeymap.cというファイルを、エディタで開いて、内容を書き換える。
エディタで見ると以下のようになっている。

実際にどう書き換えたかは、次の記事で説明する。QMKのリファレンスを参照に、各レイヤーを変更した。

変更が済んだら、keymap.cを上書き保存。
cd /C/Users/ユーザー名/OneDrive/Downloads/QMK/qmk_firmware-master/ と入力、enter。
引き続き、
make helix:修正用のフォルダの名前:avrdude
と入力、enter。
予定ではその後、「Detecting USB port, reset your controller now.」と表示され、そこでキーボードのリセットボタンを押して書き込みを行う……
はずだったのだが、以下のようなエラーが出て止まってしまった。

msys2.exeでなくmingw64.exeを起動して入力してみても、同じエラーが出た。
「qmk_firmware-masterとmsys2の階層が深すぎたのかな」と思い、アンイストールして両方ともCドライブの直下にインストールし直してみたが、状況は変わらない。
試しにデフォルトのファームウェアをビルドしてみた。
ところが、
make helix:default
としても、同じエラーが出て止まってしまう。

カスタマイズどころかデフォルト・ファームウェアのビルドもできないというのは、どういうことだろう。
表示を見るかぎり、「lib/lufa/LUFA フォルダにあるはずのmakefileというファイルがないよ」と言っているようなのだが……
確認してみると、「tmk_core/protocol/lufa.mk:14: lib/lufa/」まではあるのだが、LUFA以下のフォルダは見当たらない。
「Makefile」というファイルなら最上層の「qmk_firmware-master」フォルダ内にあるのだが……

あきらめて、遊舎工房の問い合わせフォームから質問したところ、
「『make git-submodule』と入力してから、改めてmakeをしてみてほしい」
との返事をいただいた。
で、やってみたのだが、
「make git-submodule」と入力して、enterを押すと、これもエラー表示が出てしまう。

その後、改めてmakeをしてみても、前と同じエラーが出る。

●WSLによるカスタマイズも失敗

QMK Configuratorでもmsys2でもだめだったので、方法3として、「qmk_firmwareをWindows上でmakeする方法」(marksardさん)というサイトを参考に、WSL(Windows Subsystem for Linux)を使ってビルドを試みた。
以下のようなやり方だ。

Windows10のコントロールパネルの「プログラム/プログラムと機能/Windowsの機能の有効化または無効化」を開き、「Windows Subsystem for Linux」にチェックを入れ、OKをクリック。再起動し、インストールを完了させる。
Microsoft Storeで画面右上の検索アイコンをクリックし、「Linux」で検索。
出てきたフリーウェアの中から「Debian」を選択し、「入手」「起動」「再起動」でインストール。
スタートメニューに出てきたDebianのアイコンをクリックして起動。
ユーザー名とパスワードを設定した。

順番的にはここでqmk_firmwareのダウンロードと展開をするのだが、これは既に済んでいるので、すぐにWSLツールのインストールを始める。

まずはcdコマンドでqmk_firmware-masterフォルダに移動……するのだが、ここでちょっと手間取った。
Debianのコマンドでは大文字は使えないらしい。またフォルダの後の/もいらないらしい。
なんとか移動できたので、
「sudo ./util/wsl_install.sh」と入力し、enter。
パスワードを求められたので入力し、enter。
「Do you want to install all toolchain ~」と訊かれたので、「y」を入力。
「Which USB drivers do you want to install?」に「n」を入力。
「Flip need to be ~」に「n」を入力。
「Creating a softlink ~」に「y」を入力。
「Do you want to add ‘source ~」に「y」を入力。
「Do you want to add a symlink ~」に「y」を入力。
すると、「Installation completed! You need to open a new bash command prompt ~」と表示された。
WSLツールのインストール、完了である。

さて、ビルド作業開始だ。
ここでもまず、移動に手間取った。
cd qmk_firmware と入力しても、cd qmk_firmware-master と入力しても、 No such file or directory とされてしまう。
cd ~ と入力して、ようやく無事に移動できた。
おかしい。インストール時に「symlinkを張るか?」と訊かれて、「y」と押したはずだが……(確認すると確かにyを押していた)
試しに「ls -l」と入力してリンクを調べると、「total 0」と表示された。リンクを張ったはずが、張られていないらしい。
なんだかなあ。
その後もいろいろ試して、
cd /mnt/c/qmk_firmware-master と入力したら、無事に移動できた。
ここで、
make helix:default
とコマンドを打ったが……やはりmsys2のときと同じエラーが出て止まってしまう。

どうやらmsys2やWSLの問題ではなく、GitHubのqmk_firmwareのファイルのセットに欠けがあるような雰囲気だが……
しかし、そんなことがあるだろうか。
もし欠けがあったら、筆者だけでなく全ての人がファームウェアをビルドできなくなるわけだから、とっくの昔に修正されているはずだ。

●ダウンロードではなくcloneしてみる

ここで遊舎工房に送った質問に返事があり、Helix作者の倉内さんより、
「make git-submodule ができないのは、gitでcloneしていないのが原因と思われるので、いったん展開したqmk_firmware-masterを削除し、同じ階層で git clone https://github.com/qmk/qmk_firmware.git とコマンドを打つように」
とのアドバイスをいただいた。
こうすることでgitを使用して qmk_firmware/ をcloneできるので、その後、qmk_firmware/ に移動し、「make git-submodule」を行ってから「make helix:default」を行う、とのこと。

ダウンロードとクローンでどう違うのかよくわからなかったが、とにかく指示に従って「make helix:default」を行ったら、今度は無事にビルドできた。
このときできたhexファイルは、その後、QMK ToolboxでPro Microに書き込みもでき、動作も正常だった。
やれやれ。
倉内さん、重ねてありがとうございます。

●フォルダ名を変えるとエラーに

ここまででデフォルトのファームウェアについては、msys2を使ってビルドと書き込みができたわけだが、やりたいのはそれではなくて、カスタマイズである。
ところが、ここでまた問題が起きた。
make helix:defaultではちゃんとビルドできるのに、defaultフォルダをコピーし、フォルダ名を変え、キーマップをカスタマイズしたフォルダを使って、
make helix:フォルダ名
と入力すると、こちらはエラーとなってしまうのだ。
なぜなのか。
キーマップの書き換えが問題なのか。それともフォルダ名が問題なのか。
検証してみた。

まず、msys2を起動し、
cd /C/Users/ユーザー名/OneDrive/Downloads/QMK/qmk_firmware/
make git-submodule
make helix:default
とコマンドを入力すると、これは成功する。
続いて、遊舎工房のファームウェアについてのガイドにあった通り、/keyboards/helix/rev2/keymaps/ にある defaultフォルダを複製、その名前を変更して「kubota」とし、/keyboards/helix/rev2/keymaps/ に貼り付け、再び
make git-submodule
make helix:kubota
とコマンドを入力してみた。
すると、以下のような表示が出てエラーになってしまう。

今度はフォルダを別な名前にしてみた。
「kubota」フォルダの名前を変更して「default2」とし、
make helix:default2
とコマンド入力。
するとおもしろいことに、上とはちょっと違うエラーになった。
下のような形だ。

ここで、今度は上の「default2」のフォルダ名を元の「default」に変更し、
make helix:default
と入力してみた。
すると、無事にビルドすることができた。

どうやら問題はキーマップの内容ではなくて、フォルダの名前にあるらしい。
理由は不明だが、ガイドに書かれていた通りdefaultフォルダをコピーして名前を変更してしまうと、うまくビルドできなくなってしまうのだ。

そこで、defaultフォルダのkeymap.cを、名前は同じままカスタマイズした別のkeymap.cと入れ替え、フォルダの名前は変えずに、
make helix:default
と入力してみた。
すると無事にビルドできたが、それをQMK ToolboxでPro Microに書き込み、実際にキーボードを使ってみると、動作がおかしい。
文字キーは指定通りに入力できるのだが、機能キーが指定した通りに動かないのだ。
やれやれ、いったいどうなっているのか……

「Helixファームウェアのカスタマイズ 2」に続く。

  ≪