このページでは QMK における AVR マイコンのサポートについて説明します。AVR マイコンには、Atmel 社製の atmega32u4、atmega32u2、at90usb1286 やその他のマイコンを含みます。AVR マイコンは、簡単に動かせるよう設計された8ビットの MCU です。キーボードでよく使用される AVR マイコンには USB 機能や大きなキーボードマトリックスのためのたくさんの GPIO を搭載しています。これらは、現在、キーボードで使われる最も一般的な MCU です。
まだ読んでない場合は、キーボードガイドライン を読んで、キーボードを QMK にどのように適合させるかを把握する必要があります。
QMK には AVR を使ったキーボードでの作業を簡略化するための機能が多数あります。大体のキーボードでは1行もコードを書く必要がありません。まずはじめに、qmk new-keyboard を実行します。
$ qmk new-keyboard
Ψ Generating a new QMK keyboard directory
Keyboard Name: mycoolkeeb
Keyboard Type:
1. avr
2. ps2avrgb
Please enter your choice: [1]
Your Name: [John Smith]
Ψ Copying base template files...
Ψ Copying avr template files...
Ψ Renaming keyboard.[ch] to mycoolkeeb.[ch]...
Ψ Replacing %YEAR% with 2021...
Ψ Replacing %KEYBOARD% with mycoolkeeb...
Ψ Replacing %YOUR_NAME% with John Smith...
Ψ Created a new keyboard called mycoolkeeb.
Ψ To start working on things, `cd` into keyboards/mycoolkeeb,
Ψ or open the directory in your preferred text editor.
これにより、新しいキーボードをサポートするために必要なすべてのファイルが作成され、デフォルト値で設定が入力されます。あとはあなたのキーボード用にカスタマイズするだけです。
readme.mdこのファイルではキーボードに関する説明を記述します。キーボード Readme テンプレートに従って readme.md を記入して下さい。readme.md の上部に画像を配置することをお勧めします。画像は Imgur のような外部サービスを利用してください。
<keyboard>.cこのファイルではキーボード上で実行される全てのカスタマイズされたロジックを記述します。多くのキーボードの場合、何も書く必要はありません。 機能のカスタマイズで、カスタマイズされたロジックの記述方法を詳しく学ぶことが出来ます。
<keyboard>.hこのファイルでは、レイアウトを定義します。最低限、以下のような #define LAYOUT を記述する必要があります。
#define LAYOUT( \
k00, k01, k02, \
k10, k11 \
) { \
{ k00, k01, k02 }, \
{ k10, KC_NO, k11 }, \
}
LAYOUT マクロの前半部ではキーの物理的な配置を定義します。後半部ではスイッチが接続されるマトリックスを定義します。これによってマトリックス配線の順とは異なるキーを物理的に配置できます。
それぞれの k__ 変数はユニークでなければいけません。通常は k<row><col> というフォーマットに従って記述されます。
物理マトリックス（後半部）では、MATRIX_ROWS に等しい行数が必要であり、各行には正確に MATRIX_COLS と等しい数の要素が含まれていなければいけません。物理キーが存在しない場合は、KC_NO を使用して空白を埋める事ができます。
config.hconfig.h ファイルには、ハードウェアや機能の設定を記述します。このファイルで設定できるオプションは列挙しきれないほどたくさんあります。利用できるオプションの概要は設定オプションを参照して下さい。
config.h の先頭には USB に関する設定があります。これらはキーボードが OS からどのように見えるかを制御しています。変更する理由がない場合は、VENDOR_ID を 0xFEED のままにしておく必要があります。PRODUCT_ID にはまだ使用されていない番号を選ばなければいけません。
MANUFACTURER、 PRODUCT をキーボードにあった設定に変更します。
#define VENDOR_ID 0xFEED
#define PRODUCT_ID 0x6060
#define DEVICE_VER 0x0001
#define MANUFACTURER You
#define PRODUCT my_awesome_keyboard
?> Windows や macOS では、MANUFACTURER と PRODUCT が USBデバイスのリストに表示されます。Linux 上の lsusb では、代わりに USB ID Repository によって維持されているリストの値を優先します。デフォルトでは、リストに VENDOR_ID / PRODUCT_ID を含まない場合にのみ、MANUFACTURER と PRODUCT を使います。sudo lsusb -v を使用するとデバイスから示された値を表示します。また、接続したときのカーネルログにも表示されます。
config.h ファイルの次のセクションではキーボードのマトリックスを扱います。最初に設定するのはマトリックスのサイズです。これは通常、常にではありませんが、物理キー配置と同じ数の行・列になります。
#define MATRIX_ROWS 2
#define MATRIX_COLS 3
マトリックスのサイズを定義したら、MCU のどのピンを行と列に接続するかを定義します。そのためにはピンの名前を指定するだけです。
#define MATRIX_ROW_PINS { D0, D5 }
#define MATRIX_COL_PINS { F1, F0, B0 }
#define UNUSED_PINS
MATRIX_ROW_PINS の要素の数は MATRIX_ROWS に定義した数と同じでなければいけません。同様に MATRIX_COL_PINS の要素の数も MATRIX_COLS と等しい必要があります。UNUSED_PINS は定義しなくても問題ありませんがどのピンが空いているのか記録しておきたい場合は定義できます。
最後にダイオードの方向を定義します。これには COL2ROW か ROW2COL を設定します。
#define DIODE_DIRECTION COL2ROW
各スイッチが、列と行のピンを共有する代わりに、それぞれ個別のピンとグランドに接続されているキーボードを定義するには、DIRECT_PINS を使用します。マッピング定義では、列と行の各スイッチのピンを左から右の順に定義します。MATRIX_ROWS と MATRIX_COLS 内のサイズに準拠する必要があり、空白を埋めるには NO_PIN を使用します。これによって DIODE_DIRECTION、MATRIX_ROW_PINS、MATRIX_COL_PINS の動作を上書きします。
// #define MATRIX_ROW_PINS { D0, D5 }
// #define MATRIX_COL_PINS { F1, F0, B0 }
#define DIRECT_PINS { \
{ F1, E6, B0, B2, B3 }, \
{ F5, F0, B1, B7, D2 }, \
{ F6, F7, C7, D5, D3 }, \
{ B5, C6, B6, NO_PIN, NO_PIN } \
}
#define UNUSED_PINS
/* COL2ROW, ROW2COL */
//#define DIODE_DIRECTION
QMK では GPIO ピンでのバックライト制御をサポートしています。これらの設定を選択して MCU から制御できます。詳しくはバックライトを参照して下さい。
#define BACKLIGHT_PIN B7
#define BACKLIGHT_LEVELS 3
#define BACKLIGHT_BREATHING
#define BREATHING_PERIOD 6
config.h で設定・調整できる機能はたくさんあります。詳しくは設定オプションを参照して下さい。
rules.mkrules.mk ファイルを使用して、ビルドするファイルや有効にする機能をQMKへ指示します。atmega32u4 を使っている場合、これらのオプションはデフォルトのままにしておくことが出来ます。他の MCU を使用している場合はいくつかのパラメータを調整する必要があります。
このオプションではビルドする CPU をビルドシステムに指示します。これらの設定を変更する場合は非常に注意して下さい。キーボードを操作不能にしてしまう可能性があります。
MCU = atmega32u4
F_CPU = 16000000
ARCH = AVR8
F_USB = $(F_CPU)
OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
ブートローダーは MCU に保存されているプログラムをアップグレードするための特別なセクションです。キーボードのレスキューパーティションのようなものだと考えて下さい。
BOOTLOADER = halfkay
BOOTLOADER = atmel-dfu
BOOTLOADER = caterina
rules.mk にはオン・オフできるたくさんの機能があります。詳細なリストと説明は設定オプションを参照して下さい。