Zenn
⌨️

オリジナルDIYキーボードでQMK firmwareを使う方法 - DIY kit 01 - Keyboard XIAO RP2040

2023/10/16に公開
自作キーボード
QMK
rp2040
tech

これは何？

ボクの作ったDIYキーボードキット、DIY kit 01 - Keyboardはマイコンとプログラミングの勉強用に作ったDIYキットだけど、QMK firmwareと呼ばれるキーボード制御用のファームウェアをマイコン(XIAO RP2040)に書き込むことで安定して実用で使えるマクロパッドにすることができるよ。

このページでは、DIYキーボードキットのKey1からKey4までにキーを割り当てて、QMKでファームウェアをビルドして、XIAO RP2040に書き込むまでの手順について説明しているよ。今回作成するファームウェアはマトリクス回路の無い、キーとGPIOを1対1で接続したdirect pinの方法になるよ。ロータリーエンコーダへのキー割り当てとNeoPixelの使い方はこのページでは触れていないけど、また別の機会に説明するね。

QMK firmareを使用したロータリーエンコーダとNeoPixelの使い方はこちらの記事を見てね！
https://zenn.dev/nananauno/articles/bc258f7375604a

DIYキーボードキットはBOOTHで発売中なので、まだ持っていない場合はぜひ購入してね！

BOOTHの商品ページ
DIY kit 01 - Keyboard XIAO RP2040

ホントはDIYキーボードキットを購入してもらいたいけど、もしDIYキーボードキットを持っていなくても、RP2040にQMK firmwareを書き込みたい場合は、同じ手順でできるから参考にしてみてね。

対象読者

  • DIYキーボードキットを手っ取り早くマクロパッドにしたいみんな
  • RP2040用にQMKを使ったファームウェアの作り方を知りたいみんな

環境

  • QMK firmware
  • DIY kit 01 - Keyboard XIAO RP2040
  • Windows/Mac

MacはSonomaでも動作することを確認済みだよ。

QMK firmwareって何？

QMK (Quantum Mechanical Keyboard) はカスタムキーボード用のツールを開発する人たちが集まったグループで、AVRやARMアーキテクチャを採用したチップで動作するキーボード用の制御プログラムを作成するためのオープンソースなツール群がQMK firmwareだよ。

https://github.com/qmk/qmk_firmware

QMKを使用したファームウェア作成手順

QMKを使用したキーボード用ファームウェアの作成手順は以下の通りだよ。

  1. QMKのインストール
  2. QMKの動作確認
  3. キーボード作成
  4. キーマップ作成
  5. 環境設定
  6. ビルド
  7. ファームウェア書き込み

QMK firmwareのビルド環境構築、書き込み方法についてはAdafruitさんのページを参考にしたよ。
https://learn.adafruit.com/using-qmk-on-rp2040-microcontrollers

QMKのインストール

QMK firmwareを作成するための環境を構築するよ。QMK firmwareの公式ドキュメントを参考に自分のPC環境に合わせてQMKをインストールするよ。

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

ボクはMacにインストールしたけど、pipを使用してQMKをインストールしたよ。python3とpip3をインストールした状態で以下のコマンドを実行するよ。

python3 -m pip install --user qmk

--userオプションでローカルにインストールした場合は、qmkがインストールされた場所にパスを通しておく必要があるよ。以下のように.zshrcを編集したよ。編集するファイルは使用しているシェルに合わせてね。

export PATH=/Users/<your name>/Library/Python/<python version>/bin:$PATH

QMKがインストールできたら、QMKの初回セットアップを行うよ。ホームディレクトリで以下のコマンドを実行してね。

qmk setup

自動的に必要なファイルがコピーされるから、何か聞かれたらYを入力してね。初回セットアップが完了するとホームディレクトリにqmk_firmwareというディレクトリが作成されているよ。

QMKの動作確認

QMKがインストールできたら、ファームウェアを作成できるかどうかを確認するよ。Adafruitさんの例にあるhandwireキーボードを試しにコンパイルしてみるよ。ターミナルを開いて以下のようにコマンドを実行してみてね。

cd ~/qmk_firmware
qmk compile -kb handwired/onekey/rp2040 -km default

コンパイル中に色々メッセージが出た後、正常に終了するとqmk_firmware直下にhandwired_onekey_rp2040_default.uf2というファームウェアが作成されているよ。これをマイコンに書き込むことで、キーボードとして動作するよ。

qmk compileで指定したオプションについて簡単に説明するよ。

-kbオプション
コンパイルするキーボードを指定

-kmオプション
コンパイルするキーマップを指定

qmk_firmwareディレクトリの下にkeyboardsというディレクトリがあって、その中にホントに色々な種類のキーボードが入っているよ。-kbオプションはこのkeyboardsの中からどのキーボード用のファームウェアを作成するのかを指定しているよ。試しにkeyboards/handwired/onekey/に移動してみてね。onekeyディレクトリの下にkeymapsというディレクトリがあって、この中にdefaultというディレクトリがあるよね？-kmオプションは選択したキーボードの中でどのキーマップを使用するかを指定しているよ。

キーボード作成

QMKで正しくファームウェアを作成できることを確認できたら、DIYキーボードキット用のファームウェアを作成するよ。まずは、DIYキーボードキット用に新しくキーボードを作成するよ。以下のコマンドを実行してね。

qmk new-keyboard

色々質問されると思うから、以下のように指定してね。

Keyboard Name
キーボードの名前を適当につけてね。例：nanana_diy

Your GitHub Username
GitHubのユーザ名を指定してね。無ければ自分の名前でもいいよ。例：nananauno

Your Real Name
自分の名前を指定してね。例：NANANA

Default Layout
57. none of the aboveを選択してね。

MCU
36. RP2040を選択してね。

これで、新しいキーボード用のディレクトリとテンプレートのファイルが作成されるよ。keyboardsディレクトリの下にKeyboard Nameで指定した名前のディレクトリが作成されていることを確認してね。

作成したキーボードのディレクトリの直下にinfo.jsonというファイルがあるから、テキストエディタで開いて、以下のように編集するよ（kayboard_nameなどは自分で設定した名前に適宜読み換えてね）。このinfo.jsonでは、使用しているマイコンの種類、マイコンのどのGPIOにキーを接続しているかや、キーのレイアウトを定義しているよ。

{
    "manufacturer": "NANANA",
    "keyboard_name": "nanana_diy",
    "maintainer": "nananauno",
    "bootloader": "rp2040",
    "diode_direction": "COL2ROW",
    "features": {
        "bootmagic": true,
        "command": false,
        "console": false,
        "extrakey": true,
        "mousekey": true,
        "nkro": true
    },
    "matrix_pins": {
	"direct": [
		["GP26","GP27","GP28","GP29"]
	]
    },
    "processor": "RP2040",
    "url": "",
    "usb": {
        "device_version": "1.0.0",
        "pid": "0x2326",
        "vid": "0xFEED"
    },
    "layouts": {
        "LAYOUT": {
            "layout": [
                {"label": "GP26", "matrix": [0, 0], "x": 0, "y": 0},
		{"label": "GP27", "matrix": [0, 1], "x": 1, "y": 0},
		{"label": "GP28", "matrix": [0, 2], "x": 2, "y": 0},
		{"label": "GP29", "matrix": [0, 3], "x": 3, "y": 0},
            ]
        }
    }
}

JSONファイルの内容について少し説明するよ。DIYキーボードキットは４つのキースイッチがあるから、各キースイッチがどのGPIOに接続されているかを定義する必要があるよ。info.jsonの以下の部分で指定しているよ。Key1はP26, Key2はP27, Key3はP28, Key4はP29に繋がっているよ。GPxxという表記はQMKのルールでxxの部分がピン番号になるよ。また、ピンの設定を"direct"キーで指定することで、ピン１つに対して１つのキーが接続されていることを表しているよ。

     "matrix_pins": {
	"direct": [
		["GP26","GP27","GP28","GP29"]
	]
    },
補足

キーボードは一般的には１００キーとか大量のキーがあって、GPIO１つに１つのキーを繋ぐわけにはいかないので、通常はマトリクス回路というものを構成しているよ。マトリクス回路を使うことで少ないGPIOで大量のキーを読み取ることができるよ。ただ、今回のDIYキーボードキットは１つのキーに対して１つのGPIOだから、普通のマトリクス回路を使ったキーボードとは少し違うよ。キーとGPIOが1対1のものをqmkではdirect pinと呼んでいて、ちゃんとdirect pinのための設定もあって、それがmatrix_pinsのdirectキーになっているよ。

キーとGPIOを1対1で接続するdirect pinで構成されたキーボードとして、QMKにはez_makerというキーボードが既にあるから、ボクはそれを参考にしてJSONファイルを作成したよ。
ez_maker/directpins/rp2040

info.jsonの編集が終わったら保存してファイルを閉じてね。

キーマップ作成

次にキーボードのキーマップを作成するよ。キーマップというのは、どのキーに対して何のキーを割り当てるのかを定義しているよ。例えばKey1を押したときには'a'という文字を入力してね、といった感じで、各キーにキーコードを設定していくよ。

QMKにはQMK ConfiguratorというWeb上でキーマップを作成できる便利なものがあるんだけど、DIYキーボードキットは４キーしかないから、今回はテキストエディタで作成するよ。QMK Configuratorは以下からアクセスできるよ。
https://config.qmk.fm/#/ez_maker/directpins/rp2040/LAYOUT_all

作成したキーボードのディレクトリ直下のkeymaps/default/というディレクトリに移動して、そこにあるkeymap.jsonを開いてね。これがキーマップを定義するためのファイルだよ。

cd ~/qmk_firmware/keyboards/nanana_diy/keymaps/default/

keymap.jsonを以下のように編集して保存してね（kayboardは自分で設定した名前に適宜読み換えてね）。

{
    "keyboard": "nanana_diy",
    "keymap": "default",
    "layout": "LAYOUT",
    "layers": [
        [
            "KC_A","KC_B","KC_C","KC_D"
        ]
    ]
}

見たらすぐに分かるかもしれないけど、layersキーの値がキーの割り当てになっているよ。キーの順番は、キーボード作成で編集したinfo.jsonで定義されたlayoutキーの順番と一致しているよ。つまり、GP26が押されたとき、KC_Aというキーを入力、GP27が押されたときはKC_Bというキーを入力・・という並びになっているよ。

KC_Aは'a'という文字を表すキーコードだよ。キーコードの一覧は以下を参照してね。
https://docs.qmk.fm/#/keycodes_basic

環境設定

この設定はしなくても大丈夫だけど、ファームウェア作成や書き込みの度にキーボードの種類とキーマップを指定するのは面倒だから、以下のように作成対象のキーボードを設定しておくことをオススメするよ。この設定をしておくことで、-kbや-kmオプション無しでコンパイルや書き込みができるよ。

qmk config user.keyboard=nanana_diy user.keymap=default

ファームウェアのビルド

いよいよファームウェアを作成するよ。作成方法はとっても簡単で、以下のコマンドを実行するだけだよ。

qmk compile

コンパイルに成功したらqmk_firmwareのディレクトリにnanana_diy_default.uf2というイメージが作成されるよ。キーボード名は自分で付けた名前に適宜読み換えてね。

ファームウェア書き込み

ファームウェアが作成できたら、最後にファームウェアをマイコンに書き込むよ。ここでは、DIYキーボードキットで使用するXIAO RP2040にファームウェアを書き込む方法を説明するよ。

XIAO RP2040のボード上にあるB(=Boot)ボタンを押しながら、R(=Reset)ボタンを押してね。PC上でRP2040がUSBのストレージドライブとして認識されたことを確認してね。

以下のコマンドを実行してファームウェアを書き込むよ。

qmk flash

ファームウェアの書き込みが完了したら、XIAO RP2040は自動的にリセットされて、キーボードとして使えるようになっているよ。最初にファームウェアを書き込んだ後はPC上では新しいキーボードとして認識されるから、PCの指示に従ってね。テキストエディタを開いてKey1からKey4を適当に押してみてね、Key1=a, Key2=b, Key3=c, key4=dの文字が入力されるはずだよ。

ArduinoやCircuitPythonへの戻し方

QMKのファームウェアからArduinoやCircuitPythonへ戻す方法を説明するよ。QMKファームウェアを書き込んだ後はArduino IDEからマイコンをソフトリセットできないから、そのままだとスケッチの書き込みができないよ。次の方法でRP2040をBootloaderモードにしてから、ArduinoやCircuitPythonで書き込みをしてね。

XIAO RP2040のボード上にあるB(=Boot)ボタンを押しながら、R(=Reset)ボタンを押す。

まとめ

DIYキーボードキットのXIAO RP2040にQMK firmwareを書き込んでマクロパッドにする方法について説明したよ。色々なキーを割り当てて、便利に活用してみてね！DIYキーボードキットにはロータリーエンコーダとNeoPixelも搭載されていて、QMK firmwareはどちらも対応可能になっているよ。QMK firmwareでロータリーエンコーダとNeoPixelに対応したキーボードを作成する方法はまた別の機会に説明するよ。

QMK firmwareでロータリーエンコーダとNeoPixelに対応したキーボードを作成する方法はこちら！
https://zenn.dev/nananauno/articles/bc258f7375604a

じゃあ、またね！

Discussion