JPN

【2021年12月最新版】QMK Firmwareにキーボードを追加する方法

by

この記事はキーボード #1 Advent Calendar 2021 18日目の記事です。
昨日の記事は cyamyさんのFDM 3D プリンタとキーボード設計でした。

こんにちは。hsgwです。毎年、キーボードのアドベントカレンダーでは開発初心者に役立つ記事を書くことを心がけています。
今年はQMK Firmwareにキーボードを追加して最低限の設定をしてキーボードを動かすまでを解説します。

環境の準備

QMK Firmwareをコンパイルする環境を整えます。
QMK公式ドキュメントのQMK環境の構築に従ってインストールしてください。
この記事ではwindows11上のQMK MSYSを使いますが、他の環境でも同じように行えると思います。

どれかひとつのキーボードがコンパイルできてバイナリファイル(hexやbin)が出来ていることまで確認してください。

QMK Firmwareを最新版にアップデートする

1から環境を整えた場合は最新のものをダウンロードしているはずですが、そうでない場合、特に理由がなければ最新版のQMK Firmwareで作業をします。
以下のコマンドでgitを使って最新のものをダウンロードします。

$ git pull origin master

ダウンロード後にもどれかのキーボードをコンパイルしてエラーのないことを確認してください。

もし、エラーが出たら一度以下のコマンドでファイルの状況を調べてみます。

$ git status

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   lib/chibios (new commits)
        modified:   lib/chibios-contrib (new commits)
        modified:   lib/googletest (new commits)
        modified:   lib/lufa (new commits)

git上のサブモジュール(lib/以下のファイル)で変更があった場合、このようなログが出力されます。
以下のコマンドで更新しておきます。

$ make git-submodule

新しいブランチを作る

gitのお作法の話になるので詳しくは検索してください。
masterから派生したブランチを作ります。ブランチの名前は追加するキーボードとあわせておきます。

$ git branch <ブランチ名>

この記事では、git branch new_kbdとしてnew_kbdというブランチを作成します。
そのあと、以下のコマンドで新しいブランチに移動し、現在のブランチ名を確認します。

$ git checkout <ブランチ名>
$ git branch

QMK CLIを使ってキーボードのテンプレートを追加する

便利なQMK CLIを使ってkeyboards/以下にキーボードの定義を追加します。
テンプレートがコピーされるだけなので各種設定は書き換えないといけません。
Keyboard Typeはとりあえず1でAVRを選んでおいて、あとから書き換えるのが無難です。
Your real nameも本名にこだわる必要はないです。

$ qmk new-keyboard
Ψ Generating a new QMK keyboard directory

Keyboard Name: new_kbd(キーボードの名前)
Keyboard Type:
        1. avr
        2. ps2avrgb
Please enter your choice:  [1]
Your GitHub User Name: [hsgw] hsgw
Your real name: [hsgw] hsgw

Ψ Created a new keyboard called new_kbd.
Ψ To start working on things, `cd` into keyboards/new_kbd,
Ψ or open the directory in your preferred text editor.

もし、エラーが出てしまう場合、QMK CLIをアップデートする必要があるかもしれません。

$ python3 -m pip install -U qmk

これで、keyboards/内に追加したいキーボードのディレクトリが作られ、ファイルがコピーされました。

keyboards/を編集してファームウェアを作る

追加されたファイルをvscodeやお気に入りのエディタで開いて編集します。
簡易的に最低限キーボードとして動くところまでを解説します。
詳しくは公式ドキュメントのキーボードガイドラインや他の方が書いている記事、 同じような機能の他のキーボードを参考にしてください。

config.h

キーボードの設定をするファイルです。

// キーマトリクスの大きさ
/* key matrix size */
#define MATRIX_ROWS 2
#define MATRIX_COLS 3

// キーのピン設定
// UNUSED_PINSには何も書かなくてOK
#define MATRIX_ROW_PINS { D0, D5 }
#define MATRIX_COL_PINS { F1, F0, B0 }
#define UNUSED_PINS

// ダイオードの向き
/* COL2ROW, ROW2COL */
#define DIODE_DIRECTION COL2ROW

<keyboard-name>.h

レイアウトの定義をします。

#define LAYOUT( \
    k00, k01, k02, \
      k10,  k12    \
) { \
    { k00, k01,   k02 }, \
    { k10, KC_NO, k12 }  \
}

rules.mk

MCUの種類やブートローダ、機能を設定します。

# Bootloader selection
BOOTLOADER = atmel-dfu

// もし、pro microを使っているなら、catherinaを指定する必要があるかもしれません
// BOOTLOADER = caterina

keymaps/default/keymap.c

キーマップを定義します。
<keyboard-name>.hで定義したLAYOUTの通りにキーマップを作ってあげてください。

コンパイル

コンパイルして書き込んで完成！

gitにコミットしておく

gitを使って変更を保存しておきます。検索してみてください。

終わりに

これで誰でもQMK Firmwareに自分のキーボードを追加できるようになったはずです。
来年もたくさんキーボードを開発して一緒に遊びましょう！

この記事はCasasagi Oリングマウントケースで書きました。