Corne Cherry向けにQMK Firmwareをビルドするために学んだこととキーマップの紹介

Corne Cherry Light を組み立てました。

https://zenn.dev/konokenj/articles/02cb6457a43ef4

実現したい機能があったので、RemapやVIAを使うのではなく、QMK Firmwareを自分でビルドすることにしました。

やりたいこと

1. Lower, Raise キーに「英数」「かな」キーを同居させる
2. Lower, Raise, Adjust レイヤーの切り替えを update_tri_layer() を使って行う
3. ESCキーを押したときに「英数」キーを一緒に送信する

42キーのCorne Cherryでは「英数」「かな」キーを単独で置くことは難しいので、レイヤー切り替えキーと同居させることにしました。

また、Vim使いなのでESCキーを押したら「英数」を一緒に送りたいです。これはMacの場合Karabiner Elementsで実現していましたが、Windowsでは（あまりよく調べておらず）対応していませんでした。Karabiner Elementsはこの機能のためだけにインストールしていたので、これがファームウェアレベルで対応できると不要になります。

QMK Firmware のセットアップ

https://docs.qmk.fm/#/newbs_getting_started

こちらのQMKのドキュメントに従ってビルド環境を構築します。 brew install コマンドは環境によって数十分かかることがあります。キーボードの組み立て中や発送待ちなどの間に実行しておくとよいでしょう。

brew install qmk/qmk/qmk

GitHubで QMKのリポジトリ を folk してから、以下のコマンドを叩きます。こちらのコマンドでも依存関係のインストールが行われるため、数十分かかることがあります。

qmk setup <github_username>/qmk_firmware

デフォルトでは ~/qmk_firmware に上記で指定した folk したリポジトリがクローンされます。

Corne Cherryのビルドガイドに記載されているコマンドは2023/3/28時点のQMK Firmwareのドキュメントとは相違があったため、QMK Firmwareのドキュメント従ってファームウェアを試しにコンパイルしてみます。 make ではなく qmk compile コマンドを使用します。

qmk compile -kb crkbd/rev1 -km default

QMK Firmware で最初のファームウェアをビルドする

https://docs.qmk.fm/#/newbs_building_firmware

デフォルトのキーボードとキーマップ名を設定します。

qmk config user.keyboard=crkbd/rev1
qmk config user.keymap=<github_username>

新しいキーマップを作成するには、qmk new-keymap コマンドを使用するように記載されていますが、 crkbd/rev1 のディレクトリ構造のせいかキーマップが見つからないエラーになります。

$ qmk new-keymap
Ψ Generating a new keymap

☒ Default keymap /Users/xxxxx/qmk_firmware/keyboards/crkbd/rev1/keymaps/default does not exist!

このため、手動で default キーマップをコピーします。

cp -r keyboards/crkbd/keymaps/default keyboards/crkbd/rev1/keymaps/

再度 qmk new-keymapを実行します。

$ qmk new-keymap
Ψ Generating a new keymap

Ψ Created a new keymap called xxxxx in: /Users/xxxxx/qmk_firmware/keyboards/crkbd/rev1/keymaps/xxxxx.
Ψ Compile a firmware with your new keymap by typing: qmk compile -kb crkbd/rev1 -km xxxxx.

diffで確認してもdefaultと新たに作成されたディレクトリに差がないため、qmk new-keymap はどうやら単純にフォルダをコピーしているだけのようです。このため、qmk new-keymap 実行後にコピーした keyboards/crkbd/rev1/keymaps/default ディレクトリを削除してしまっても問題ありません。

次にコンパイルしてみます。

qmk compile

ファームウェアの書き込み (Flash) はコマンドでやるのが楽です。この方法で書き込みを行う場合、QMK Toolboxはもう必要ありません。

$ qmk flash
Ψ Compiling keymap with gmake --jobs=1 crkbd/rev1:xxxxx:flash


Making crkbd/rev1 with keymap xxxxx and target flash

avr-gcc (Homebrew AVR GCC 8.5.0) 8.5.0
Copyright (C) 2018 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Size before:
   text	   data	    bss	    dec	    hex	filename
      0	  26190	      0	  26190	   664e	crkbd_rev1_xxxxx.hex

Copying crkbd_rev1_xxxxx.hex to qmk_firmware folder                                              [OK]
Checking file size of crkbd_rev1_xxxxx.hex                                                       [OK]
 * The firmware size is fine - 26190/28672 (91%, 2482 bytes free)
Flashing for bootloader: caterina
Waiting for USB serial port - reset your controller now (Ctrl+C to cancel)...

上記のログが出たら、キーボードのリセットスイッチを押します。私の手元のPro Microではリセットスイッチは1回で大丈夫でした。

ビルドが通ったら、ブランチを切って一度コミットしておきましょう。

git checkout -b dev
git add keyboards/crkbd/rev1/keymaps/xxxxx
git commit -m "copy default keymap by 'qmk new-keymap'"
git push -u

キーマップを定義するために学んだこと

自分でキーマップを作る上で、そもそもどのようなキーマップが一般的で、どんなトレードオフがあるのか調べました。完全なオリジナルを作るよりも、キーボード作者が提供するデフォルトのものか、すでに実績のあるものを使ったほうがメンテナンスコストが低いからです。

こちらのブログで、さまざまなキーボードのデフォルトキーマップを比較して汎用的なキーマップを定義する試みをされています。

https://kbigwheel.hateblo.jp/entry/my-keymap

キー数を減らすアイデアはこちらのブログが参考になりました。

https://zenn.dev/tatsutanicov/articles/286f3d0f262f59

実際に Corne Cherry ユーザーが定義しているキーマップも確認してみます。

https://the-tanaka.com/archives/2552

https://note.com/scop00/n/n6d126de41b12

Layer切り替えキーと「かな」「英数」を同居させた場合の不都合を解消するために、サンプルコードを公開してくださっている方がいます。これは非常に重要です。例えば「A」を入力しようとしてシフトキーを押した直後に気が変わって「a」を入力するようなケースや、キーマップに慣れないうちに違うレイヤーを開いてしまうなどのケースで「かな」「英数」が発動してしまうと、元に戻す操作が必要になるからです。

https://okapies.hateblo.jp/entry/2019/02/02/133953

レイヤーの切り替え方法は、crkbdのデフォルトでは LOWER, RAISE, ADJUST を各レイヤーに配置していますが、こちらのブログで解説されている通り update_tri_layer() を使用したほうが良いでしょう。

https://kbigwheel.hateblo.jp/entry/update-tri-layer

QMK Firmware を VSCode で書くための設定

QMKのドキュメントにVSCodeの設定方法が記載されているのですが、うまく依存関係が解決できませんでした。

https://docs.qmk.fm/#/other_vscode?id=set-up-vs-code

上記では .vscode/c_cpp_properties.json にコードをコピペするのですが、サンプルコードと実際の環境のパスが異なる場合があるので適宜修正が必要です。

しかしそれでもビルドが通らなかったので、代わりにこちらのGistで紹介されている .vscode/c_cpp_properties.json を生成する Python スクリプトを利用しました。

https://gist.github.com/td2sk/99cc1f0f5340d16314e9e421aa7278e7

python3 update_qmk_c_cpp_properties.py -kb crkbd_rev1 -km xxxxx

QMK Firmware の開発 Tips

qmk flash はコンパイルを行わない

keymap.c を変更した後にファームウェアを書き込みたいときに qmk flash を実行すると以下のようなログが出ます。

$ qmk flash
Ψ Compiling keymap with gmake --jobs=1 crkbd/rev1:konokenj:flash

Making crkbd/rev1 with keymap konokenj and target flash

これを見るとコンパイルを行っているように見えるのですが、実際には keymap.c はコンパイルされていないため、qmk compile の実行が必要です。

タイピングの練習

みんな大好き寿司打でローマ字の練習をします。最初は散々でした。

https://sushida.net/

ローマ字だけだと、c, v, x, q あたりをほぼ使わないので英文も練習します。私はこのmonkeytypeを一番多くやってます。記号をオンにすることもできます。

https://monkeytype.com/

上部の歯車マークから様々な設定が可能です。間違えたところをきちんとbackspaceで消すように設定したり、間違えたキーを表示したりすると良いです。サウンドもつけると一気に楽しくなります。

次にとにかく記号を練習しておきました。

https://typing.twi1.me/game/55539

ある程度打てるようになったら、プログラミングの練習に切り替えます。慣れた言語に加えて、シェルスクリプトをやると扱う記号が多くて良いと思います。

https://typing.io/

作成したキーマップ

コードはこちらです。

https://github.com/konokenj/qmk_firmware/blob/8d38032cf9c20c029b2d70608666d6bd555902c1/keyboards/crkbd/rev1/keymaps/konokenj/keymap.c

Corne Cherry のデフォルトから変更したこと

Default レイヤー (0)

• 右シフトが必要ないので、ESCに変更

基本的に変更しませんでした。

Lower レイヤー (1)

デフォルトでは数字と方向キーが配置されていますが、左手でLowerキーを押しながら押したいショートカットがあったので、こちらに記号を集約しました。記号の配置自体はデフォルトのRaiseレイヤーとまったく同じで、あいていた左手側の10キーにマウスを操作しながら使うウィンドウ操作系のショートカットキーをまとめて配置しました。

• ワークスペース（デスクトップ）切り替え
• Mission Control & Launchpad
• ブラウザの拡大・縮小
• スクリーンショット

ワークスペース切り替えとMission ControlはMagic Trackpadを使っている人には不要ですが、今の所私はKensington Slim Bladeを使用していて、同時押しによるワークスペース切り替えがうまく機能しないことがある悩みを抱えていたのでキーマップに取り入れました。

Raise レイヤー (2)

デフォルトではこちらに記号キーが配置されていますが、右手でRaiseキーを押しながらHJKLで移動したかったので、こちらに数字と方向キーを集約しました。こちらも、デフォルトのLowerにあった配置とまったく同じで、あいていた右手側のキーに移動系のショートカットキーをまとめて配置しました。

• MacのFinderでディレクトリツリーを上に移動/下に移動
• DeleteとCmd+Delete (Finderでのファイル削除)
• Home, End, PageUp, PageDown

Finderの操作にはもともとキーボードで右Commandを多用していました。今回Commandキーが左手側にしかないので、片手で操作できるように意識しています。

Adjust レイヤー (4)

デフォルトではファームウェア関連のキーだけが配置されており、ファンクションキーがありませんでした。

• F2~F15 (F1はいらない)
• メディア系キー (再生、停止、音量調整、輝度調整など)
  • Mac Book Pro / Realforce for Mac で Fn キーとの同時押しで賄われていたキー
• CapsLock, Insert (たまに必要になるので念の為)

試したけどボツにしたアイデア

(ボツ) ハイフンをDefaultレイヤーに置く

右シフトの代わりにESCを置くかハイフンを置くか悩みました。日本語の文章を打っていてハイフン（長音）はよく登場するので最初はレイヤーにしまわれていると不便に感じたからです。

Vim使いだからESCを優先した、、と思われそうですが、実際にはESCはVimを使っているとき以外でもガンガンおしていることに気づきました。編集をキャンセルしたり、Excelでセルから抜けたりと「何もせずにキャンセルする」目的でよく押しますし、ESCがレイヤーにしまわれていてミスタイプする可能性が増えると、「何もしない」つもりが「なにかしちゃう」ケースが出ると判断しました。

(ボツ) 右親指でシフト

日本語の入力方式の話ではありません。一時期、右親指にシフトを、右小指にEnterを置く配置を試しました。シフトを押しながらアルファキーを押すのが楽だし、右小指Enterにも慣れていると思ったからです。

しかしこれはModキーとの組み合わせに問題が出ました。

• Ctrl + Shift + 何か
  • 左手側にCtrlとShiftがあることを想定している事が多いが、Shiftが右手側に来るとややこしい
• Option + Shift + 何か
  • 単純に右親指で2つのキーを押せないので厄介です
• Shift + 方向キー
• Shift + マウス操作

実際のところ致命的に辛かったのが最後の2つです。範囲選択で多用する組み合わせですが、方向キーはRaise (右親指) にしまわれています。すると、右親指で2つのキーをまたいで押して、さらにHJKLを押す形になって非常に無理があります。マウスも右手で操作しますが、Shiftが右親指にあると左手が出張してくるしかなくなってしまいます。

結局、デフォルト通り左小指でShiftを押すことになりました。Shiftを押しながらアルファキーを押すのはもともと厄介でしたが、これはもう手が慣れてしまっているので今更問題にはならなかった、ということです。

SandS (Space + Shift) も考えましたが、日本人の場合IMEの変換候補をSpace長押しですっ飛ばすこともあるので採用しませんでした。

まとめ

キーマップをいじるのは楽しいですね！！