ZMKの使いかた:ローカルで作成編

情報

ZMKのドキュメントはよく作られていてここにあります。

ローカルでファームを作る環境の準備

作業環境としては、元Linux使いのWindowsユーザーなので、WSL2を使います。Ubuntu 20.04.4 が入っています。

環境構築の手順は、ドキュメントのここにあるものを使います。

OSのツーリング

基本書いてある通りにやります。まずは、必要なパッケージのインストール/更新です。

sudo apt install -y \
    git \
    wget \
    autoconf \
    automake \
    build-essential \
    bzip2 \
    ccache \
    device-tree-compiler \
    dfu-util \
    g++ \
    gcc \
    libtool \
    make \
    ninja-build \
    cmake \
    python3-dev \
    python3-pip \
    python3-setuptools \
    xz-utils

westをインストールします。

westというのは west is the Zephyr™ meta-tool used to configure and build Zephyr™ applications. ということで、ZMKのOSであるZephyrのツールの開発をするのに必要なツールのようです。

pip3 install --user -U west

インストールしたツールにパスを通すのに以下のコマンドを実行しろとありますが、自分でrcファイルを編集して適切な場所でPATH変数を更新しましょう。これは今「-U」オプションでインストールしたツールのパスですね。

echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc

Zephyrツールチェーンのインストールです

export ZSDK_VERSION=0.13.2
wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run" && \
    sh "zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \
    rm "zephyr-toolchain-arm-${ZSDK_VERSION}-linux-x86_64-setup.run"

「The installation will prompt with several questions about installation location, 」って書いてあるけど、何も聞かれずに終了しました。

ZMK環境の設定

このあたりから

まだZMKをクローンしていないのであればここでクローンしておきます。ZMKのソースのディレクトリは「zmk」です。

ZMKのwestの初期化をします。

ディレクトリツリーにビルドに必要な情報が追加されます。

cd zmk
west init -l app/
west update

west updateは書いてあるとおり、10分ほどで終りました。

次は、Zephyrのエクスポートとありますが、なにをしているのでしょう？

cmakeの設定にZephyrを入れているのかな

zmk$ west zephyr-export
Zephyr (/home/yosi/workspace/keyboard/zmk/zephyr/share/zephyr-package/cmake)
has been added to the user package registry in:
~/.cmake/packages/Zephyr

ZephyrUnittest (/home/yosi/workspace/keyboard/zmk/zephyr/share/zephyrunittest-package/cmake)
has been added to the user package registry in:
~/.cmake/packages/ZephyrUnittest

Zephyrに必要なpythonのパッケージのインストール

ここで、pythonの仮想環境を作っておけばと思ってやってみたのですが、--userオプションと被ってできなかったのでvenvはやめました。

pip3 install --user -r zephyr/scripts/requirements-base.txt

ここでインストールされたのは以下のパッケージ

 anytree-2.8.0 
 canopen-2.0.0 
 intelhex-2.3.0 
 msgpack-1.0.3 
 progress-1.6 
 psutil-5.9.0 
 pyelftools-0.28 
 python-can-4.0.0 
 typing-extensions-4.1.1 
 wrapt-1.14.0

環境変数の設定

最後に環境変数の設定をするようですがこれが記述の通りにできない。

"By default, the Zephyr™ SDK will create a file named ~/.zephyrrc with the correct environment variables to build ZMK. " と書いてありますが、前に書いととおり、Zephyrの設定をしても。.sephyrrcファイルが作られません。

Zephyrのドキュメントのこのあたりに、.zephyrrcは必要なら作ってねって感じ。

そもそも手順の続きを見ると、

シェル毎に設定するなら、以下のようにzmkのファイルをsourceするように書いてある。

source zephyr/zephyr-env.sh

すべてのshellで使えるようにするなら、bashrcとかにzephyrrcを追加しておいてねってなっている。

これはまあ、ドキュメントが古いんだなということにして進めてみる。

これで環境構築は終り

作った環境でファームをビルド

ファームをビルドします。

手順はここにあります。

まずはzmkディレクトリにあるコンフィグでビルド

zmkのappディレクトリに移動してコマンドを打ちます。

corneはboardとshieldに別れているので、以下のようなコマンドになります。

west build -b <board> -- -DSHIELD=<shield>

corneは分離型なのでshieldは右と左で別になり、別のコマンドで作らなければならないのですが、できあがるファームはzmk.uf2という固定名なので、左右を作り分けるためにビルドディレクトリを-dオプションで指定しまんす。

ということで、結局こんなコマンドになります。

west build -d build/left -b nice_nano_v2 -- -DSHIELD=corne_left 

west build -d build/right -b nice_nano_v2 -- -DSHIELD=corne_right

これでビルドされ、左右のファームができあがります。

自分のキーマップでビルド

ZMKのソースツリーでキーマップを変更したり新しいキーマップを作ったりすると、ソースツリーを最新版に維持するのが面倒になります。はGitHubを使って作る時のようにキーマップを別に用意すればその懸念はなくなります。

コマンドでコンフィグの場所を指定することで、自分で定義したキーマップでビルドすることができます。

コンフィグの場所を指定するオプションは -DZMK_CONFIGです。

west build -d build/left -b nice_nano_v2 -- -DSHIELD=corne_left -DZMK_CONFIG="/home/yosi/workspace/keyboard/zmk-config/config"

west build -d build/right -b nice_nano_v2 -- -DSHIELD=corne_right -DZMK_CONFIG="/home/yosi/workspace/keyboard/zmk-config/config"

ファームは以下の場所にできあがります。 build/[left|right]/zephyr/zmk.uf2

※ 実際の作業時には、ここで環境構築ではまったのですがそれについては末尾に記載。

ファーム構築手順まとめ

手順の通りに実施すればOK。

ただし、WSL2/Ubuntu20.04.4 LTSだとcmakeのバージョンが古いので、3.20.0以上を入れる必要がある。今回は、最新の 3.23.1 を入れた。

環境構築後のビルドは以下の手順

zmk ディレクトリに移動する。
環境設定を読み込む
source zephyr/zephyr-env.sh
zmk/app ディレクトリに移動する。
ビルドのコマンドを実行する。
1. 右側作成んのコマンド
  west build -d build/right -b nice_nano_v2 -- -DZMK_CONFIG="自分の/zmk-config/config" -DSHIELD=corne_right
2. 左側作成のコマンド
  west build -d build/left -b nice_nano_v2 -- -DZMK_CONFIG="自分の/zmk-config/config" -DSHIELD=corne_left
ファームは以下の場所にできる。
build/[left|right]/zephyr/zmk.uf2

ZMKの更新で必要な手順

ZMKはまだ活発に開発が進んでいるので、QMKに比べると、基本的なところの変更が多く入っているようです。

なので、ZMKのソースを更新するとビルド環境も更新しなくてはならないようです。

west updateあたりからやり直せばよさそうです。

また、ビルドのキャッシュも手動で消さなければならないようです。app/build配下を全部消します。

環境構築ではまった話

自分のコンフィグzmkの外の場所にあるコンフィグで構築しようとしても、キーマップが無視されるという問題が発生した。ログを見ても、キーマップが読み込まれていないように見える。

だめなとき

-- ZMK Config directory: /home/yosi/workspace/zmk-config/config
-- Board: nice_nano_v2, /home/yosi/workspace/keyboard/zmk_org/app/boards/arm/nice_nano, corne_left, corne
-- ZMK Config Kconfig: /home/yosi/workspace/zmk-config/config/corne.conf
Including boilerplate (Zephyr base (cached)): /home/yosi/workspace/keyboard/zmk_org/zephyr/cmake/app/boilerplate.cmake

できるとき

-- west build: generating a build system
-- ZMK Config directory: /home/yosi/workspace/keyboard/zmk-config/config
-- Board: nice_nano_v2, /home/yosi/workspace/keyboard/zmk_org/app/boards/arm/nice_nano, corne_left, corne
-- ZMK Config Kconfig: /home/yosi/workspace/keyboard/zmk-config/config/corne.conf
-- Using keymap file: /home/yosi/workspace/keyboard/zmk-config/config/corne.keymap
-- Using keymap file: /home/yosi/workspace/keyboard/zmk-config/config/corne.keymap
Including boilerplate (Zephyr base): /home/yosi/workspace/keyboard/zmk_org/zephyr/cmake/app/boilerplate.cmake

ソースコードそのものを眺めていたりしたのですが、考えてみたら、ビルドに使っているZMKは3ヶ月ぐらい前にフォークした自分のリポジトリのクローンだった。最新と違うはずなので、まずは最新で構築し直してみることにした。

新しくクローンして、ビルドしてみるとこんどはcmakeのエラー

CMake Error at /home/yosi/workspace/keyboard/zmk_org/zephyr/cmake/app/boilerplate.cmake:29 (cmake_minimum_required):
  CMake 3.20.0 or higher is required.  You are running version 3.16.3

cmakeのバージョンが古いとな。 WSLのubuntuだと 3.16.3が最新のようです。

cmakeのサイトから取ってきて自分で入れるしかないみたい。

サイトからバイナリを取得して、/optに展開してパスを通す。

それでビルドしてみると、ちゃんとファームが生成されました。めでたしめでたし。

ypsilon-takai/how_to_play_w_ZMK_local.md