Open6

ZMK Firmware調査メモ

自作キーボード
zmk
snizesnize

ファームウェアのディレクトリ構造

公式ドキュメントにあるように、xiao nrf52840などのMCUを後付けする基板の場合はシールドの設定ファイルをZMKは以下から探します。直感的にわかりづらいのですが、僕らがよく目にするのは２と４だと思いますが、各キーボードのファームウェアのフォルダ構造と違うのはZMK本体から視点だからです。このうち４は「後方互換性のために残してあるだけなので、使うな」とのこと。

  1. zmk/app/boards/shields/<shield>
  2. zmk-config/boards/shields/<shield>
  3. <module>/boards/shields/<shield>
  4. zmk-config/config/boards/shields/<shield> (For backwards compatibility only, do not use.)

つまり、リポジトリルートのconfigディレクトリにシールドの設定ファイルが配置されるのは適切ではありません。configフォルダに配置しても良いのは、次の２つの様です。

  • <name>.conf (Kconfig)
  • <name>.keymap (Devicetree)

またこれらはユーザ向けのものであり製作者がzmk-config/boards/shields/<shield>以下で提供されるデフォルトの設定を上書きするためのものです。

Configuration Overview| ZMK Firmware

わかりづらくしてる箇所

ドキュメントの以下の箇所でboardsディレクトリを含めることができるとも書いてある。ドキュメント全体の雰囲気と整合性から可能だけど推奨しない的なニュアンスなんだと思う。

However, your config folder can also be modified to include a boards/ directory for keymaps and configurations for multiple boards/shields outside of the default keyboard setting definitions.
Customizing ZMK/zmk-config folders | ZMK Firmware

ディレクトリ構造の参考になるリポジトリ

ZMKの作者であるPete Johanson氏がフォークし管理下にあるリポジトリで、公式の推奨する構造になっていると思われます。Module Creationのページ末尾のExamplesの項で紹介されてました。もっと目立つ位置にあってもいいと思います。

https://github.com/petejohanson/zmk-keyboards-katori

snizesnize

KconfigとDevicetree

ZMKのベースのZephyrにおけるKconfigとDevicetree

https://docs.zephyrproject.org/latest/build/dts/dt-vs-kconfig.html

Kconfig はソフトウェアに関する設定、devicetree は主にハードウェアに関する設定

ZMKにおけるファイル分類

Kconfig系（ソフトウェアに関する設定）

  • Kconfig.shield （シールド固有のKconfigシンボル定義）
  • Kconfig.defconfig （シールド/ボードのデフォルト設定）
  • .conf （ユーザーオーバーライド用のKconfig設定）

Devicetree系（ハードウェアに関する設定）

  • .dtsi （デバイスツリーインクルードファイル）
  • .overlay （デバイスツリーオーバーレイファイル）
  • .keymap （ZMK独自：デバイスツリー形式のキーマップ定義）

記述形式

KconfigはKconfigというDSL（ドメイン固有言語）で記述され、DevicetreeはDTSというDSLで記述される。

Kconfig

  • 設定用のDSLであり、
  • ファイル名としても「Kconfig」が使われる（拡張子ではなくファイル名そのもの）
  • ソフトウェア機能やビルドオプションの定義に使われる

DTS（Devicetree Source）

  • ハードウェア記述用のDSLであり、
  • 拡張子「.dts」「.dtsi」「.overlay」「.keymap」として使われる
  • ハードウェアの構造やブート時設定をツリー構造で表現する
snizesnize

GitHub Actionsでのビルドとdevcontainerでのビルド

devcontainerでのZMKビルドについてnoteにまとめたけど、正直おすすめしていいか悩んでる。
というのも、GitHub Actionsのビルド用ジョブとdevcontainer内のビルドコマンドでは、結構違いがある。

たとえば、GitHub Actionsだと config/west/.yml の依存関係を自動で解決してくれるけど、devcontainerでは自分で必要なリポジトリを取ってきて、ビルドオプションでモジュール指定しないといけない。
つまり、一部手動対応が必要で、運用がすっきりしない感じ。

むしろ、act を使ってGitHub Actionsそのものをローカルで動かした方がいい気もしてる。

snizesnize

GitHub Actionsでのビルドとdevcontainerの視点の違い

視点がちょっと違うのでやっぱり悩ましい。

  • Devcontainer: ZMK 本体が「主」であり、そこにユーザー設定/モジュールを「追加」するイメージ。
  • GitHub Actions: ユーザー設定/モジュールが「主」であり、その west.yml に従って ZMK 本体などを「取得」し、自身もビルド対象に含めるイメージ。