QMK Firmware、REMAP(VIA)の対応手順
Sparrow60C を作るに当たって、RP2040にて、QMK Firmware、REMAPへの対応を行ったので、その手順を残しておきます。Ubuntu 22.04、MacOSで実施しました。
qmkコマンドが便利でした。
1. QMK Firmwareのインストール
pipxでインストールする。
pipx install qmk
qmk setup
~/qmk_firmware/というディレクトリにQMK Firmwareのリポジトリがチェックアウトされる。
2. QMKでキーボード設定を生成する
qmk new-keyboard
- Keyboard Name?: 小文字+数字で付ける
- Your GitHub Username?: GitHubアカウント
- Your Real Name?: 英語で
- Default Layout?: 60. none of the above（後で設定するので適当に）
- MCU?: 36. RP2040（適切なものを）
keyboards/{キーボード名} というフォルダができる。
3. info.json にレイアウト以外を設定する
keyboards/{キーボード名}/info.json を編集する。
3.1. matrix_pins、diode_direction
キーボードの実装通り、ピンを設定する。
"diode_direction": "COL2ROW",
"matrix_pins": {
"cols": ["GP21", "GP20", "GP19", "GP18", "GP17", "GP16", "GP15", "GP13", "GP12", "GP10", "GP9", "GP8", "GP7"],
"rows": ["GP28", "GP27", "GP26", "GP22", "GP11"]
},
3.2. USBのVenderID、ProductIDを設定する
USBのVenderIDは法人の有償の登録制だが、Maker界隈では適当に使われている印象がある。一応、下記に登録されているIDは避けておくのが無難。
"usb": {
"device_version": "1.0.0",
"pid": "0x7437",
"vid": "0xDA74"
},
3. Keyboard Layout Editorでレイアウトを再現する
Keyboard Layout EditorというWebツールを使って、マトリクスを指定する。
ここでレイアウトを作る。この際、以下のことをやる。
- 左上の印字（Top Legendの1番目）を、
2,3のようにROW,COLの番号にする。この内容は後でVIAで使われる。 - レイアウトを左に寄せる（寄せないとQMKでWarningが出る）
ここで制作したデータは、Raw dataタブから、「Download JSON」「Upload JSON」をすると保存したり、続きから作業したりできるので、作成したデータは取っておく。
4. Keyboard Layout Editorからinfo.json用データに変換して、さらにmatrix属性を追加して、info.jsonに追加する
このInput:に、Keyboard Layout EditorのRaw dataタブのテキストをコピペして、Convertを押す。
できたJSONの"layouts"属性をinfo.jsonの"layouts"属性にコピーする。
"layouts": {
"LAYOUT": {
"layout": [
{"label": "0,0", "x": 0.75, "y": 0},
{"label": "0,1", "x": 1.75, "y": 0},
{"label": "0,2", "x": 2.75, "y": 0},
各キーの"label"属性を見て、"matrix"属性を追加する。
"layouts": {
"LAYOUT": {
"layout": [
{"matrix": [0, 0], "label": "0,0", "x": 0.75, "y": 0},
{"matrix": [0, 1], "label": "0,1", "x": 1.75, "y": 0},
{"matrix": [0, 2], "label": "0,2", "x": 2.75, "y": 0},
5. キーマップを作る
keyboards/<キーボード名>/keymaps/default/keymap.c を開き、キーを記述する。ここにLAYOUTと書かれているマクロは、info.jsonの"layouts"内の属性"LAYOUT"と一致刺せる必要がある。
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
/*
* ┌───┬───┬───┬───┬───┬───┐ ┌───┬───┬───┬───┬───┬───┐
* │Esc│ 1 │ 2 │ 3 │ 4 │ 5 │ │ 7 │ 8 │ 9 │ 0 │ - │ = │
* ┌┴───┼───┼───┼───┼───┼───┼───┐ ├───┼───┼───┼───┼───┼───┤
* │ Tab│ Q │ W │ E │ R │ T │ 6 │ │ Y │ U │ I │ O │ P │ \ │
* ├────┼───┼───┼───┼───┼───┼───┤ O ├───┼───┼───┼───┼───┼───┤
* │Ctrl│ A │ S │ D │ F │ G │ [ │ │ H │ J │ K │ L │ ; │ ' │
* ├────┼───┼───┼───┼───┼───┼───┤ ├───┼───┼───┼───┼───┼───┤
* │Shft│ Z │ X │ C │ V │ B │ ] │ │ N │ M │ , │ . │ / │Sft│
* └────┴───┼───┼───┴┬──┴─┬─┴──┬┴───┼───┴┬──┴─┬─┴──┬┴──┬┴───┘
* │SCR│LGUI│LALT│SPC │CLIK│Ent │Basc│RAIS│RCl│
* └───┴────┴────┴────┴────┴────┴────┴────┴───┘
*/
[0] = LAYOUT(
KC_ESC, KC_1, KC_2, KC_3, KC_4, KC_5, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL,
KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_6, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_BSLS,
KC_LCTL, KC_A, KC_S, KC_D, KC_F, KC_G, KC_LBRC, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT,
KC_LSFT, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_RBRC, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT,
SCROLL, KC_LGUI, KC_LALT, KC_SPC, KC_BTN1, KC_ENT, KC_BSPC, MO(1), KC_BTN2
),
次に keymap.cのLAYOUT()マクロに並べた順に、以下のinfo.jsonの"layout"属性の各キーの順に並び替える。LAYOUT()マクロの引数の順序と、info.jsonの”layout"内の配列の順序が一致する必要がある。
"layouts": {
"LAYOUT": {
"layout": [
{"matrix": [0, 0], "label": "0,0", "x": 0.75, "y": 0},
{"matrix": [0, 1], "label": "0,1", "x": 1.75, "y": 0},
{"matrix": [0, 2], "label": "0,2", "x": 2.75, "y": 0},
6. ビルドしてみる
コマンドを実行して、defaultキーマップをビルドしてみます。
qmk compile -kb <キーボード名> -km default
更に書き込む場合は以下のコマンドが使えるようです。
qmk flash -kb <キーボード名> -km default
しかし、私の場合はビルドマシンと、キーボードが接続されているマシンが異なるため、~/qmk_firmware/.build/に作られたRP2040用のファームウェアのuf2ファイルをコピーして書き込みました。
7. VIAのキーマップを作る
コマンドを実行して、viaキーマップを作成します。
qmk new-keymap -kb <キーボード名> -km via
keyboards/<キーボード名>/keymaps/via/ディレクトリが作られ、defaultディレクトリのkeymap.cがkeyboards/<キーボード名>/keymaps/via/keymap.cにコピーされます。
7.1 rules.mkに追記する
keyboards/<キーボード名>/keymaps/via/rules.mkファイルを作成し、VIAを有効にする設定を追加します。
VIA_ENABLE = yes
7.2 config.c に追記する。
keyboards/<キーボード名>/keymaps/via/config.hファイルを作成し、Layerを追加する設定を追加します。
#pragma once
#define DYNAMIC_KEYMAP_LAYER_COUNT 7
8. VIAの設定ファイルを作る
現在、VIA自体はQMKのinfo.jsonに対応しているようでしたが、REMAPが現状VIAの独自ファイルにしか対応していないようだったので、VIA用の設定ファイルのJSONを作成します。
8.1 info.jsonからの転記
info.jsonにも記述した、vendorID、productIDを入れておきます。matrixに、col、rowの数を入れます。
{
"name": "Sparrow60C",
"vendorId": "0xDA74",
"productId": "0x7437",
"menus": [],
"keycodes": [],
"matrix": { "cols": 13, "rows": 5 },
"layouts": {
"keymap": [
]
}
}
8.2 Keyboard Layout Editorからの転記
Keyboard Layout EditorからRaw dataタブにて「Download JSON」を押したときに得られるJSONファイルの配列の内容を、"layouts"、"keymap" 内にコピーします。
"layouts": {
"keymap": [
[
{
"x": 0.75
},
"0,0",
"0,1",
"0,2",
"0,3",
"0,4",
"0,5",
{
"x": 2.5
},
"0,7",
"0,8",
...
9. Firmwareを焼いて、REMAPを利用する
viaキーマップをコンパイルします。
qmk compile -kb <キーボード名> -km via
私は生成された.build/<キーボード名>_via.uf2を書き込みましたが、直接書き込むには以下のコマンドを実行します。
qmk flash -kb <キーボード名> -km via
REMAPのサイトを開き、「CUSTOMIZE YOUR KEYBOARD」を押して、「+KEYBOARD」からキーボードを認識させます。さらに、「Please import your Sparrow60C definition file(.json)」とJSONの読み込みが求められるため、VIAの設定ファイルを投入します。
最初、JSONを読み込ませても真っ白い画面になっていたのですが、JavaScript Consoleを見ると存在しないキーを読み込ませている様なエラーになっていました。rowsの値が1つ小さいことに気づきました。
この時作ったもの
以下に置いています。実際に販売できる段階まで行きましたら、qmk_firmwareにPR、Remapに登録したいと思います。下記リポジトリにはkeyboard-layout.json、via.jsonが含まれいますが、qmk_firmwareにPRを出すときには削除する予定です。
- Keyboard Layout Editor のJSONファイル: https://github.com/74th/qmk_firmware_sparrow_keyboard/blob/sparrow/keyboards/sparrow60c/keyboard-layout.json
- info.json: https://github.com/74th/qmk_firmware_sparrow_keyboard/blob/sparrow/keyboards/sparrow60c/info.json
- VIAのJSONファイル: https://github.com/74th/qmk_firmware_sparrow_keyboard/blob/sparrow/keyboards/sparrow60c/keymaps/via/via.json
Discussion