QMK (1)

Date: 2022/01/14 (initial publish), 2022/08/23 (last update)

Source: jp/note-00039.md

Previous Post Top Next Post

TOC

どうもカスタムキーボードのフリーのファームウエアとしてはQMKが一番充実しているのですが、久しぶりにのぞくと2017年2月のころとかなり様子が変わっているようにも見えます。特に気になるのはconfig.jsonの存在です。

とにかくカバーするキーボードハードウエアー数が大きくなってきたので、リファクターして共通部分の重複回避を試みている様です。

QMKのドキュメントもかなり更新されています。

復習を兼ねてコード・ドキュメントを追います。

qmkコマンド導入とファームウエアーのビルド

最近、QMK Toolboxをpip経由で導入する、非プログラマーにも使いやすいマルチプラットフォーム対応のUIを目指したpythonで書かれたthin wrapperのqmkというCLIコマンドが提供されています。

qmkコマンドは、作業環境設定や、firmwareのビルド、はたまた種々の関連処理プログラムの提供や起動に用いるようです。でもビルドされるCコードのコアの部分はあまり変わっていないようです。

まず、Install Using pipに従い環境をDebian 11 (Bullseye/testing)に導入しました。

qmk setupの自動設定でチェックアウトされるレポは、git submoduleを使っていて、レボがうまくまとめられています。レポ内にグラフィクスなどを保存しなくなり、キーマッピングもキーボード間で共用可能なものをまとめたり、マッピングだけのユーザーカスタム化情報がメインのkeyboads/以下のソースツリー外に置けるようです。ただソースを理解するのが少々手間となりました。

qmkは、初期導入時に~/.bashrcを変更し、shellの環境変数QMK_HOMEにチェックアウトしたレポの場所を保存したようです。（手動でしたのかどうか忘れました）

qmkのコマンドの説明はQMK CLI Commandsにあります。

どうもビルドは公式にはqmkコマンドを使うようになっているそうですが、その背後で何がどうなっているのかが気になります。

レポを見ると、791b9cc652 (“remove all makefiles from keyboard directories”, 2017-09-27)で昔ビルドに使っていた各キーボード毎の独立のMakefileが無くなっています。だから、ビルドの実体はrootにあるMakefileがしているはずです。いかんせんrootのMakefileは複雑なので閉口でした。

今残っているrootにあるMakefileにからむのかがwebにあるエンドユーザー向けの説明ではよく分からないので、試しにrootにあるMakefileを無効なターゲットで動かすと以下のメッセージが出ます。

$ make help
QMK Firmware 0.15.12
make: *** No rule to make target 'help'. Stop.
|
| QMK's make format is:
|     make keyboard_folder:keymap_folder[:target]
|
| Where `keyboard_folder` is the path to the keyboard relative to
| `qmk_firmware/keyboards/`, and `keymap_folder` is the name of the
| keymap folder under that board's `keymaps/` directory.
|
| Examples:
|     keyboards/dz60, keyboards/dz60/keymaps/default
|       -> make dz60:default
|       -> qmk compile -kb dz60 -km default
|     keyboards/planck/rev6, keyboards/planck/keymaps/default
|       -> make planck/rev6:default:flash
|       -> qmk flash -kb planck/rev6 -km default
|
WARNING: Some git submodules are out of date or modified.
 Please consider running make git-submodule.

これで、マニュアルどおりにqmkコマンドによりビルドする際に、バックエンドのMakefileがどう起動されているかが分かりました。

Makefileはかなり複雑ですが、%ターゲット中で呼ばれるPARSE_RULEがキーです。処理の実体はPARSE_RULEが呼ぶPARSE_KEYBOARDです。KEYMAPS := $$(sort $$(KEYMAPS) $$(LAYOUT_KEYMAPS))となっているので、キーマップは旧来のスタイルのkeyboards/以下の.../keymaps/*/に定義された専用の定義のみならず、layouts/以下に定義された汎用の定義も使えるようです。

qmkコマンドは、一見便利なんですが、背後で何をしているのかが最初分からずちょっと悩みました。まだ開発中なので変わるかもしれませんが、気になった関連作業を以下にメモしておきます

qmkレポの移動方法

qmkレポの移動は、レポのディレクトリーを移動、それに併せて環境変数$QMK_HOMEの設定を~/.bashrc中で対応して代え新規にシェルを立ち上げるとできます。

新規のクリーンなqmkレポを新規の場所に作成する方法

既存レポに手を加えず、新規にqmkレポを作成するには、何もない作成場所を確保し移動し以下を実行します。

 $ qmk clone

すると、現行ディレクトリ下にqmk/qmk_firmwareが作成されます。

それに併せて環境変数$QMK_HOMEの設定を~/.bashrc中で対応して代え新規にシェルを立ち上げます。

この状態では既存だったレポにはqmkからはアクセスできませんが、GITからのデーターアクセスはできます。環境変数$QMK_HOMEの設定を戻せばqmkからのアクセスが回復できます。

qmkレポのREMOTE名変更

上記のように普通にsetup やcloneをすると、デフォルトでoriginにもupstreamにも、アップストリームのhttps://github.com/qmk/qmk_firmwareが指定されてます。 また、masterbranchはoriginをトラックしています。

How to Use GitHub with QMKにあるように、自分のレポにフォークしてgithubにバックアップをとりながら作業したいので、GITを使うフォークの管理の時と同様にqmkレポのREMOTE名をorigin からupstreamに変更します。

 $ git remote set-url origin git@github.com:osamuaoki/qmk_firmware.git
 $ git branch -u upstream/master master
 $ git remote set-url --push upstream BOGUS

 $ git checkout master
 $ git pull upstream master
 $ git push origin master

QMKで使われているMakefileのターゲットの整理

QMK導入先システムのPython のアップグレード

Python 3.9下でQMK Toolboxを導入すると、~/.local/lib/python3.9に導入されます。このままシステムのPython 3.10にアップグレードしたらQMK Toolboxが動かなくなりました。Symlink ~/.local/lib/python3.10 -> ~/.local/lib/python3.9 を作ったら、とりあえず動いています。

QMK関連の参考文書

現状のビルド環境のカスタマイズのために自力でコードを見たあと、見通しのよいカスタマイズ方法の入門参考文書を見つけました。

これで、ほぼ大枠がわかった気がしたので自力の努力はストップしました。

公式のドキュメントはエンドユーザー各論（Windows環境対応等…）が多すぎて迷いますが、少なくとも以下には目を通しましょう。

ウェッブアプも含めた開発環境

ウェッブアプも含めた開発環境としてQMK Web Stackを導入するのが良いみたい。

Debianだとdocker.ioパッケージ以外に、docker-composeパッケージも必要みたい。

 $ cd path/to/LAYOUTマクロ定義
 $ git clone -r https://github.com/qmk/qmk_web_stack.git
 $ cd qmk_web_stack
 $ ./fix-submodules.sh
 $ sudo apt update
 $ sudo apt install docker.io docker-compose
 $ sudo docker-compose build
 $ sudo docker-compose up

この時に以下のような色々の警告が出ましたが、問題なく動いている様です。

...
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
WARNING: You are using pip version 21.2.4; however, version 21.3.1 is available.
You should consider upgrading via the '/usr/local/bin/python -m pip install --upgrade pip' command.
...

これらは気にせずさらに指示どおり進めます。

 $ cd path/to/qmk_web_stack
 $ sudo ./populate_api.sh

ローカルのQMK Configuratorが立ち上がってます: http://127.0.0.1:5000/

docker-compose.ymlを変更すると、qmk_firmwareのレポやブランチ指定が変更できるようなので、種々のレポへの変更をPUSHする前にローカルで試すのにはよさそうです。

キーボードレイアウト外部ツール

新規キーボードレイアウトのデザインには外部ツールの WEB ベースのキーボードレイアウトエディター (a.k.a KLE) を利用すると便利です。

このKLEが生成するJSONファイル（layouts/以下にはlayout.jsonに保存されている）からQMKが利用するJSONファイル（info.json）に変換するのには、Convert KLE raw to QMK info.jsonを用います。

以前は手動でコーディングしていたQMKのkeymap.cは、info.json からqmk c2json ...として生成できます。一度これを作るとQMK自身のコンフィギュレーターでデーターを編集できます。このinfo.jsonを用いるData Driven ConfigurationがQMKの今後の方向の様です。

QMKが利用するJSONファイルinfo.jsonを直接編集するWEB上のQMKのコンフィギュレーターは、公式のqmk_firmwareに収録されている場合にのみつかえます。非公開の変更ソースに関してQMKのコンフィギュレーターを使うには、上記の様にローカルのqmk_firmwareのGITレポを用いる開発環境をローカルで作り利用します。

ちなみに、既存キーボードレイアウトがkeymap.cで存在する場合、 これからQMKが利用するJSONファイルinfo.jsonを逆生成するにはqmk c2json ...を利用します。

QMKコードの全体感のメモ

QMKコードの注意点

QMK再導入の注意点

ホームディレクトリー中に開発環境を導入しているので、新規のシステムにホームディレクトリー関係を移動させる際にはいささか注意がいる。

フレッシュなインストールのお試しにはKVMが便利。GNOME boxesが少々不安定だったので、Virtual Machine Manager (virt-manageパッケージ)を利用した。

久しぶりにqmk_firmwareのレポを見ると、私の出した「Caps<->Esc交換マジックキー」関連のPRがマージされていました。これで楽になります。

Previous Post Top Next Post