RGB Matrixで好きなエフェクトを作ろう（キーボード #2 Advent Calendar 2023 12.3）

アドカレ LALA50

★キーボード #2 Advent Calendar 2023の12/3のブログエントリです
☆前日はぴろりどんさんの今年設計したキーボードのこだわりポイントでした！今年制作された4つのキーボードのそれぞれを振り返り纏められた記事です。苦労した点や気づきはすごくためになります。私の次回作では、willow配列から着想された人差し指側と小指側で異なる曲線を描く物理配列について、ぜひ真似参考にさせていただきたいと思います。
★明日は◤◢◤◢◤◢◤◢さんのキーボードのロゴを設計したです！

adventar.org

2年ぶり2回目のAdvent Calendarになります。前回の記事は2021年に書いたこちらです。よかったら覗いてみてください。

cerbekos00.hatenablog.com

気がつけばもう12月。キーボードAdvent Calendarの時期がやってきましたね。11月30日(木)の朝、Xでたまたまアドカレを見かけ、空きを見つけて滑り込み登録した今回は、最近作ったキーボードで使用したQMKファームウェアのRGBマトリックスの仕組みやカスタムエフェクトの設定方法を書いていきたいと思います。RGBマトリックスについてまとまった記事は多くない印象ですので、この記事が誰かの設計の参考になれば幸いです。

目次

1.RGB Matrixとは

RGB MatrixはLEDを使った様々なエフェクトでキーボードをびかびかさせるQMKファームウェアの機能です。キープレス・リリースをトリガーとするエフェクトを設定することができる点で、同じLEDでびかびかさせるRBG LithingやLED Lithingのアニメーションとは異なっています。というよりも、RGB マトリックスから機能を落として扱いやすくしたものがRBG Lithingのようです。単色のものはLED Matrixです。

docs.qmk.fm

2.RGB Matrixの仕組み

RGBマトリックスは、LEDの物理的な位置とキーマトリックスを紐づけて管理することで、LEDの物理的な位置によりグラデーションやウェーブをつくったり、キープレス・リリースされたキーに位置するLEDを判定して点灯させたりすることができます。紐づけ管理にはled_config_tという構造体を用います。各LEDに役割（モディファイアキー用とかインジケータ用など）を持たせるフラグを付けることもでき、フラグにより色を変えるなどの操作が提供され、簡単に取り扱えるようになっています。LEDの物理的な位置は{x,y}の座標で示され、{0,0}がキーボードの左上、{224,64}が右下となります。 

LALA50は13行×4列の格子配列で52キーあり、52キーと同じ位置にLEDがあります。

これを、{0,0}がキーボードの左上、{224,64}が右下となるようにすると、次のようにLEDの物理的な位置が定義できます。

led_config_tで、電気的なマトリックス(LALA50では総当たりマトリックス)の定義とともに、物理的なLEDの位置と、それらのLEDがどのような種類か（1:モディファイア、8:インジケータ、4:キーバックライトなどの分類）を定義します。

RGB マトリックスではエフェクトも豊富にあり、使用するエフェクトをconfig.hで定義することで使用することができます。簡単なエフェクトの中身も見てみましょう。以下はモディファイアキーのみ別の色とするRGB_MATRIX_ALPHAS_MODSです。

alpha_mods_anim.h

RGB_MATRIX_ALPHAS_MODSは、alpha_mods_anim.hに記述されており、ループ処理でLEDを走査してLED_FLAG_MODIFIERが8の場合に、rgb_matrix_config.speed分のhsvをずらした色を設定しています。RGB マトリックスのエフェクトの種類ごとに.hファイルが存在し、config.hで定義されればエフェクトのコードが読み込まれると仕組みとなっています。

3.RGB Matrixの設定方法

それではRGB マトリックスを搭載するために必要なファイルや定義について、LALA50の設定を見ながら説明します。なお、使用するMCUやLEDによってファイルへ記述する内容が異なりますのであらかじめご了承ください。
今回使用したQMKファームウェアのバージョンは0.21.6、MCUはXIAO RP2040、LEDはSK6812MINI-Eです。

info.json
info.jsonのスキーマの定義方法はこちらのドキュメントを参照してください。

github.com

まず、featuresブロックではrgb_matrixをtrueにします。rgb_matrixブロックを記述します。上記では、led_config_tという構造体を定義するコードを書いていましたが、同じ定義をinfo.json内で行うことができます。

あとinfo.jsonでLEDに関係のある定義として、WS2812ドライバーとピンの指定があります。

config.h
config.hではLED数の指定と使用するエフェクトや効果、オプションなどの定義をします。

docs.qmk.fm

docs.qmk.fm

ここで、RGB_MATRIX_DEFAULT_MODEで定義しているRGB_MATRIX_CUSTOM_myef_mod_funcは自身で作成したカスタムエフェクトです。LALA50では、複数キーのレイアウトを切り替えて使えるようにしていますが、それぞれのレイアウトに合わせたモディファイアキーやレイヤーキーのLEDの色を変えて、レイアウトを分かりやすくするためにカスタムエフェクトを作成しています。

カスタムエフェクトを作成する場合、keymaps/キーマップ名のディレクトリの直下にrgb_matrix_user.incというファイルを作成し、その中にalpha_mods_anim.hのようなエフェクトを記述します。

rgb_matrix_user.incこのエフェクトでは次のように点灯します。

rules.mk
自分で好きなエフェクトを追加する場合は、RGB_MATRIX_CUSTOM_USERを定義する必要があります。

keymap.c
私が自作するキーボードにはたいていLEDをレイヤーインジケータとして点灯させているのですが、RGBマトリックスでレイヤーインジケータを働かせる場合はget_highest_layer(layer_state)でレイヤーを判定してLEDの色を指定することで実現できます。またLEDに設定した種類（flag）を条件することで特定のキーのみ点灯させるという指定が簡単にできます。

自身で作成したカスタムエフェクトは、RGB_MODやRGB_RMODでエフェクトを切り替えて見つけるほかにも、rgb_matrix_mode(RGB_MATRIX_CUSTOM_myef_mod_func)などによる指定も可能です。LALA50ではF21からF24キーを押すと、デフォルトレイヤーを切り替えたうえでレイアウトに合ったカスタムエフェクトを設定するようにしてみました。

ファームウェアも少々作り込んで、あらかじめ設定した4パターンのレイアウトをデフォルトレイヤーを変更しつつLEDをキーマップに合わせて点灯させるようにしてみました🌈
なぜかLeyer(7)以上はset_single_persistent_default_layerが失敗してしまうのが残念#LALA50 pic.twitter.com/GIh9NzCepR

4.RGB Matrixの操作

コンパイル後に、キーボードでRGBマトリックスのエフェクトを操作するには特定のキーコードを使用します。キーコードはRGB Lithingと共通となっており、以下のキーコードが割り当てられています。（表をQMKドキュメントより引用します）

Key Aliases Description
RGB_TOG   Toggle RGB lighting on or off
RGB_MODE_FORWARD RGB_MOD Cycle through modes, reverse direction when Shift is held
RGB_MODE_REVERSE RGB_RMOD Cycle through modes in reverse, forward direction when Shift is held
RGB_HUI   Increase hue, decrease hue when Shift is held
RGB_HUD   Decrease hue, increase hue when Shift is held
RGB_SAI   Increase saturation, decrease saturation when Shift is held
RGB_SAD   Decrease saturation, increase saturation when Shift is held
RGB_VAI   Increase value (brightness), decrease value when Shift is held
RGB_VAD   Decrease value (brightness), increase value when Shift is held
RGB_SPI   Increase effect speed (does not support eeprom yet), decrease speed when Shift is held
RGB_SPD   Decrease effect speed (does not support eeprom yet), increase speed when Shift is held

RGB_MODやRGB_RMODを押すたび、config.hで定義したエフェクトが順番に切り替わります。自身で作成したカスタムエフェクトもこれに含まれる形になります。

おわりに

いかがでしたでしょうか。市販のキーボードやカスタムキーボードではよく見かけるRGB マトリックス（正確にはキーボード独自のライティング）ですが、自作キーボードではLEDの数が多く設計が面倒なためか（勝手な想像ですが）あまり見かけない気がします。気が向いたらぜひRBGマトリックスとカスタムエフェクトで、自分好みにキーボードを彩りましょう。

それでは、良いキーボードライフを。

＊この記事はテンキーが中央にあるキーマップでカスタムエフェクトで彩られたLALA50で書きました。