QMKファームウェアの使い方

QMKファームウェアを使ってキーボード（Tercy_rev004）を制作しました。QMKファームウェアには他の方が作られたキーボードが色々と登録されています。そこに自作キーボード用のファイルを追加しました。特殊な独自機能を組み込むこともなかったので、追加したファイルは6個だけでした。

QMKファームウェアをマイコンへ書き込むにはQMK MSYSというソフトを使用します。Windows版のQMK MSYS 1.7.2を使用しました。あとは、Gitを使用します。なくても何とかできなくもないですが、使った方が必要なデータを簡単に集められます。

以下では、QMKファームウェアを自作キーボード用にコンパイルして書き込む方法を紹介します。

QMKファームウェアの利用

公式サイトにもGetting Startedに使い方の紹介があります。紹介で省略されている箇所を補足するとイメージとしては次のようになります。

  1. QMKファームウェアをダウンロードする。
  2. QMK MSYSを起動する。
  3. qmk_firmwareフォルダーでQMK MSYSをセットアップする。
  4. QMK MSYSでキーボードとキーマップを指定してコンパイルする。
  5. QMK MSYSでマイコンに書き込む。

ツールのインストール

QMKファームウェアを使用するためのツールとして、gitとQMK MSYSをダウンロードしてインストールします。

  1. Gitへアクセスしてください。
  2. インストーラーをダウンロードして、インストールしてください。
  1. GitHub qmk/qmk_distro_msysへアクセスしてください。
    （公式サイトからLatest Versionをクリックすると上記へ移動します）
  2. QMK_MSYS.exeをダウンロードして、インストールしてください。

QMKファームウェアのダウンロード

gitのcloneコマンドを使用して、QMKファームウェアをダウンロードします。手動でダウンロードも試してみましたが、関連ファイルを集めるのが大変でした（QMKファームウェアが他のgitリポジトリのコードを使用する）。

  1. GitHub qmk/qmk_firmwareへアクセスしてください。
  2. <>Codeボタン（上図の緑色）からHTTPSのURLをコピーしてください。
  3. Git CMDを起動してください。
  4. qmk_firmwareをダウンロードしたいフォルダーをカレントディレクトリーにしてください。
    例：cd c:\git
  5. クローンコマンドでqmk_firmwareをダウンロードしてください。
    例：git clone https://github.com/qmk/qmk_firmware.git

QMK MSYSの起動

WindowsのスタートメニューからQMK MSYSを起動してください。緑の横線部分はPCにより異なります。

QMKセットアップの実行

  1. QMKファームウェアのフォルダー（qmk_firmware）をカレントディレクトリーにしてください。
    例： [****@**** ~]$ cd C:/git/qmk_firmware
    　　実行すると [****@**** ~]$ が、 [****@**** qmk_firmware]$ となります。
  2. セットアップコマンド（qmk setup）を実行してください。
    例： [****@**** qmk_firmware]$ qmk setup

QMKファームウェアのコンパイル

キーボードとキーマップを指定して、コンパイルコマンド（qmk compile -kb <keyboard> -km <keymap>）を実行してください。keyboards/tercy/rev004/keymaps/defaultの場合、<keyboard>はtercy/rev004とkeyboardsからの相対パス、<keymap>はdefaultとkeymapsからの相対パスです。

例： [****@**** qmk_firmware]$ qmk compile -kb tercy/rev004 -km default

別のコマンド（make <keyboard>:<keymap>）もあります。QMKファームウェアの各キーボードのreadme.mdには、こちが書かれていることが多いと思います。これはreadme.mdのテンプレートがmakeで書かれているためで、機能に違いはありません。

例： [****@**** qmk_firmware]$ make tercy/rev004:default

QMKファームウェアの書き込み

キーボードのマイコンをPCに接続して、書き込みコマンド（qmk flash -kb <keyboard> -km <keymap>）を実行してください。このコマンドも<keyboard>、<keymap>はコンパイル同様です。

例： [****@**** qmk_firmware]$ qmk flash -kb tercy/rev004 -km default

Waiting for USB serial port – reset your controller now (Ctrl+C to cancel)….と表示されて待機状態になれば、マイコンをリセットしてください。マイコンのリセット方法はハードウェアに依存しますが、だいたいの場合はRSTとGNDを一瞬だけショートさせればOKです。

コンパイル同様に別コマンド（make <keyboard>:<keymap>:flash）もあります。

例： [****@**** qmk_firmware]$ make tercy/rev004:default:flash

QMKファームウェアへのキーボード追加

ダウンロードしたQMKファームウェアへキーボードを追加するために必須のファイルは次の3つです。

  • <keyboard>/info.json
  • <keyboard>/rules.mk
  • <keyboard>/keymaps/default/keymap.c

info.jsonでマイコンで使用するピンやキー配置の定義、機能の有効／無効などを指定します。keymap.cでキー配置に応じたキー配列を指定します。rules.mkでも機能の有効／無効を設定できるようですが、空ファイルでも問題ありません。

tercy/rev004では、Remapというキー配列を変更できるアプリを使えるようにしたかったので、keymaps/viaフォルダーを追加しました。このフォルダーには次の2つのファイルが必要です。

  • <keyboard>/keymaps/via/keymap.c
  • <keyboard>/keymaps/via/rules.mk

keymap.cは、defaultフォルダーのコピーでOKです。rules.mkは、VIA_ENABLE = yesの一行です。

readme.mdは、本家qmk_firmwareに自作キーボード用ファイルを取り込んでもらう際に必要となるキーボードの説明です。個人で使用するだけであれば必要ありません。

追加したinfo.jsonの内容

正確な説明の詳細は公式サイト（info.json Format）を参照してください。概要は以下の通りです。※featuresは書かなければデフォルトのfalseとなります。

キー値
manufacturer製造元（任意テキスト）
keyboard_nameキーボード名（任意テキスト）
maintainer保守担当（任意テキスト）
development_boardキーボードの使用マイコン（任意テキスト）
diode_directionダイオードの向き（COL2ROW or ROW2COL）
dynamic_keymap / layer_countキーマップのレイヤー数
features / bootmagicブートマジックの有効／無効（true or false）
features / extrakey※参考にしたキーボードで使用していたもので理解できていない
features / mousekeyマウスキーの有効／無効（true or false）
features / nkroNキーロールオーバーの有効／無効（true or false）
features / tri_layerLowerレイヤーとUpperレイヤーを同時にアクティブにするとAdjustレイヤーがアクティブになる機能の有効／無効（true or false）
デフォルトでは、Lower=1、Upper=2、Adjust=3
matrix_pins / cols回路の列に使用したマイコンのピンの配列
matrix_pins / rows回路の行に使用したマイコンのピンの配列
urlキーボードについての情報が得られるサイトURL
usb / device_versionバージョン番号（X.Y.Z形式、XYZは非負の整数）
usb / pidUSBプロダクトID（0xFFFF形式、FFFFは4桁の16進数）
usb / vidUSBベンダーID（0xFFFF形式、FFFFは4桁の16進数）
layouts / LAYOUT / layoutmatrix：回路の行列位置[row, col]
x：物理的な行列位置（横にいくつ目か）
y：物理的な行列位置（縦にいくつ目か）
info.json概要

追加したkeymap.cの内容

include QMK_KEYBOARD_H // とりあえずインクルードする

include “keymap_japanese.h" // 日本語キーの使用にインクルードする

[0] = LAYOUT( // レイヤー0のデフォルトキーマップ、info.jsonのlayout配列順に指定する

// [4]～[7]は未指定のためすべてKC_TRNSとなる

自作キーボード

Posted by Tercy