MinGW64 を使って Vortex Core で QMK を使えるようにした

注意！）このページに書かれていることと同じことを行う場合には、Vortex Core の基板番号が "CYKB175_V03 20160511" であることを確認してください。。

私が40%キーボードにはまるきっかけとなった Vortex Core。最近では使う機会も減ってきていましたが、改めて見ると良いキーボードだなと思います。自分で設計した Rect44 も多くの点をパクらせてもらいました。アーキサイトさんが扱っていた国内販売は終了していますが、mechanicalkeyboards.com ではまだ販売しているようです。

このキーボードは、キーカスタマイズが可能（マクロ機能もあり）ですが QMK 程の自由度はなく、特に1キーで Tap と Hold の使い分けができないところが難点でした。この欠点をなくすために、Vortex Core の QMK 化を行いました。

参考にしたのはこれらのページ。

上記ページは Linux でのインストールを想定していますが、私は QMK firmware ビルド用に構築してあった Windows10 上の MinGW64 で作業しました。

お約束

以下の作業は Vortex Core を使用不能にし、高価な文鎮とする可能性がありますが、当方はその責任を負いかねます。下記作業は、たまたまうまくいった可能性があります。記述には間違いや抜けがあるかもしれません。各自の責任において作業してください。

また、この作業を行うと少なくとも下記の不具合が発生します。

CapsLock を含む全ての LED が使えなくなります。
QMK に入れ替えても Mouse Key は使えません。
ファームウェアが十分に安定していない可能性があり、PCの再起動時にキーボードがロックされることもあります。また、pok3rtool は新しいファームウェアのフラッシュに失敗することが度々あります。

必要なツール

Vortex core を QMK化しようとしている方なら Windows に MSYS2(MinGW64) と git のセットアップは済んでいて、QMK ファームウェアのビルドができる環境は揃っているものとします。

現在の QMK ビルド推奨環境は QMK_MSYS なので PATH 等がこの手順とは違ったもになりますが、その場合は適宜読み替えてください。手順は似たものになると思います。（丸投げ

それ以外に必要と思われるものは、

HT32F165x に対応した openocd : https://github.com/ChaoticConundrum/openocd-ht32
Vortex用のUSBフラッシングツール: https://github.com/pok3r-custom/pok3rtool
Vortex用のファームウェア: https://github.com/pok3r-custom/pok3r_re_firmware
Vortex用のQMK: https://github.com/pok3r-custom/qmk_pok3r
SWD プロトコルをサポートするハードウェアデバッガ（私の場合は、ST-Link/v2 を使いました）
キーボードとハードウェアデバッガを接続するための適切なケーブル
ハンダごて、ハンダ、ハンダ吸い取り線、フラックスクリーナー、ドライバー、キーキャップを外す工具

などです。

ハードウェアデバッガの Windows用ドライバーのインストール

私は ST-Link/v2 を使用したので、https://www.st.com/content/st_com/ja/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-utilities/stsw-link009.html から入手したドライバーをインストールしました。
ここは各自が実際に使用するハードウェアデバッガのドライバーをインストールしてください。

Zadig が必要という情報もありましたが、そのまま行けました。環境によっては Zadig によるデバイスドライバの書き換えが必要かもしれません。

MinGW64 での openocd-ht32 インストール

Vortex Core に使用されているHOLTEK製 HT32シリーズMCU をデバッグするために openocd-ht32 をインストールする。

まずはシステムのアップデートと必要ツールのインストール。

下記コマンドをアップデートが無くなるまで実行。

$ pacman -Syuu

この後必要になるパッケージのインストール。

$ pacman -S --needed base-devel mingw-w64-x86_64-gcc mingw-w64-x86_64-toolchain

openocd-ht32 のインストール開始。

$ cd ~
$ mkdir src
$ cd src
$ git clone https://github.com/ChaoticEnigma/openocd-ht32.git
$ cd openocd-ht32
$ ./bootstrap
$ ./configure --host=x86_64-w64-mingw32 --disable-werror
$ make
$ make install

＊--disable-werror は忘れないように。これが無いと make が途中で止まる。

MinGW64 での pok3rtool のビルド

CMake のインストール

https://github.com/pok3r-custom/pok3rtool の README.md を見るとビルドのやり方が

git clone --recursive https://gitlab.com/pok3r-custom/pok3rtool.git
mkdir pok3rtool-build
cd pok3rtool-build
cmake ../pok3rtool
make

とあるので pok3rtool のビルドには cmake が必要らしい。

なのでまずは Kitware/CMake から cmake をインストール。

$ cd ~/src
$ git clone https://github.com/Kitware/CMake.git
$ cd CMake
$ ./bootstrap --prefix=/mingw64
$ make
$ make inatall

＊ --prefix=/mingw64 を付けると PATH が通っている /mingw64/bin に出来上がったバイナリーを置いてくれる。これを付けないと C:/Program Files/CMake 以下に配置される。

pok3rtool のビルド

準備ができたので pok3rtool のビルド

$ cd ~/src
$ git clone --recursive https://gitlab.com/pok3r-custom/pok3rtool.git
$ mkdir pok3rtool-build
$ cd pok3rtool-build
$ cmake -Wno-dev -G"Unix Makefiles" ../pok3rtool

＊ -Wno-dev は余計な警告を表示させないため。
＊ -G"Unix Makefiles" は出力されるファイルを Unix の Makefile 形式にしてくれる。これを付けないと Projectファイルが生成される。

make をする前に以下の3つのファイルを C:/msys64/mingw64/bin から C:/msys64/mingw64/x86_64-w64-mingw32/lib にコピーする。これをしておかないと最後でエラーになる。

libgcc_s_seh-1.dll
libstdc++-6.dll
libwinpthread-1.dll

ファイルをコピーした後

$ make

初期ファームウェアのクローン

ファームウェア書き換え時の初期ファームウェアをクローンしておく。

$ cd ~/src
$ git clone https://github.com/pok3r-custom/pok3r_re_firmware.git

カスタムファームウェアのビルド

ファームウェアビルド用の qmk_pok3r.git をクローン。

$ cd ~/src
$ git clone --recursive https://github.com/pok3r-custom/qmk_pok3r.git

~\src\qmk_pok3r\keyboards\vortex\keymaps\default にある keymap.c の #elif defined(KEYMAP_VORTEX_CORE) 以下を編集して好みのキーマップにする。

私は下記のようにしました。

#elif defined(KEYMAP_VORTEX_CORE)
    [0] = LAYOUT_core(
        KC_ESC,   KC_Q,    KC_W,    KC_E,  KC_R,  KC_T,  KC_Y,  KC_U,    KC_I,    KC_O, KC_P, KC_MINS, KC_BSPC,
        LCTL_T(KC_TAB),    KC_A,    KC_S,  KC_D,  KC_F,  KC_G,  KC_H,    KC_J,    KC_K, KC_L, KC_SCLN,  KC_ENT,
        KC_LSFT,  KC_Z,    KC_X,    KC_C,  KC_V,  KC_B,  KC_N,  KC_M, KC_COMM,  KC_DOT, RSFT_T(KC_UP), KC_SLSH,
        LCTL_T(KC_DEL), KC_LGUI, KC_LALT, MO(2), LT(1,KC_SPC), RSFT_T(KC_SPC), KC_RALT, KC_LEFT, KC_DOWN, KC_RGHT
    ),
    [1] = LAYOUT_core(
        KC_GRV,    KC_F1,   KC_F2,   KC_F3,   KC_F4,   KC_F5,   KC_F6,   KC_F7,   KC_F8,   KC_F9,  KC_F10,  KC_F11, KC_F12,
        KC_TRNS,    KC_1,    KC_2,    KC_3,    KC_4,    KC_5,    KC_6,    KC_7,    KC_8,    KC_9,    KC_0,  KC_EQL,
        KC_TRNS,  KC_APP, _______, _______, _______, KC_LBRC, KC_RBRC, KC_QUOT, KC_TRNS, KC_TRNS, KC_PGUP, KC_BSLS,
        KC_INS,  KC_TRNS, KC_TRNS, _______, KC_TRNS, KC_TRNS, KC_TRNS, KC_HOME, KC_PGDN,  KC_END
    ),
    [2] = LAYOUT_core(
        KC_MUTE, _______, _______, _______, _______, _______, _______, _______, _______, KC_PSCR, KC_SLCK, KC_PAUS, _______,
        KC_CAPS, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______,
        KC_TRNS, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______,
        KC_LCTL, _______, _______, KC_TRNS, _______, KC_TRNS, KC_TRNS, _______, _______, _______
    ),
#else

編集が終わったら下記コマンドでファームウェアを作成。

$ cd ~/src/qmk_pok3r
$ make vortex/core:default

エラー無く、下記のように終了したらOK。

QMK Firmware 0.1.3
Making vortex/core with keymap default

make[1]: Entering directory '/home/hoge/src/qmk_pok3r'
arm-none-eabi-gcc.exe (GNU Tools for Arm Embedded Processors 8-2019-q3-update) 8.3.1 20190703 
(release) [gcc-8-branch revision 273027]
Copyright (C) 2018 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Size before:
   text    data     bss     dec     hex filename
  27028    3120   13620   43768    aaf8 ./.build/vortex_core_default.elf

Compiling: keyboards/vortex/vortex.c                                      [OK]
Compiling: keyboards/vortex/keymaps/default/keymap.c                      [OK]
Compiling: ./tmk_core/common/command.c                                    [OK]
Linking: .build/vortex_core_default.elf                                   [OK]
Creating binary load file for flashing: .build/vortex_core_default.bin    [OK]
Creating load file for flashing: .build/vortex_core_default.hex           [OK]

Size after:
   text    data     bss     dec     hex filename
  27046    3120   13620   43786    ab0a ./.build/vortex_core_default.elf

Copying vortex_core_default.bin to qmk_firmware folder                    [OK]
31204 vortex_core_default.bin
make[1]: Leaving directory '/home/hoge/src/qmk_pok3r'

これでファームウェア書き換えの準備は完了です。

ファームウェアの書き換え

ハードウエアデバッガの接続

ハードウエアデバッガを接続する前に、基板番号が "CYKB175_V03 20160511" であることをもう一度確認。

この番号のすぐ下にハードウエアデバッガを接続する部分(CN2)がある。上から PIN 1、PIN 2、…、PIN 5 とすると

PIN1 - MCU VDD
PIN2 - SWDIO
PIN3 - SWCLK
PIN4 - nRST
PIN5 - GND

になるよう接続。

よって、次の写真のようにハンダ付けして接続。

OpenOCD の立ち上げ

キーボードとPCをUSBケーブルで繋いで電源を供給し、そのあとデバッガをPCに接続。

下記コマンドで OpenOCD を立ち上げ。

$ openocd -c 'set HT32_SRAM_SIZE 0x4000' -c 'set HT32_FLASH_SIZE 0x10000' -f /mingw64/share/openocd/scripts/interface/stlink-v2.cfg -f /mingw64/share/openocd/scripts/target/ht32f165x.cfg

実行結果

Open On-Chip Debugger 0.10.0-rc1-dev-00005-ge3fa2ecb (2022-04-24-20:56)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
0x4000
0x10000
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
adapter speed: 12 kHz
trst_only separate trst_push_pull
Info : Unable to match requested speed 12 kHz, using 5 kHz
Info : Unable to match requested speed 12 kHz, using 5 kHz
Info : clock speed 5 kHz
Info : STLINK v2 JTAG v29 API v2 SWIM v7 VID 0x0483 PID 0x3748
Info : using stlink api v2
Info : Target voltage: 3.247431
Info : ht32f165x.cpu: hardware has 6 breakpoints, 4 watchpoints

OpenOCD の立ち上げを確認。

"別の MinGW64 ターミナル" を立ち上げて 127.0.0.1:4444 に Telnet 接続。

$ telnet 127.0.0.1 4444

Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
Open On-Chip Debugger
>

OpenOCD を立ち上げているターミナルにも接続されたことが表示される。

Info : accepting 'telnet' connection on tcp/4444

オリジナルファームウェアの消去と新しい初期ファームウェアの導入

最初に mass_erase を実行。

これを実行するとオリジナルのファームウェアが消えるので、もう元には戻れなくなります。

Telnet 接続をしたターミナルで下記コマンドを実行。

> ht32f165x mass_erase 0

ht32f165x probe: 64 pages, 0x400 bytes, 0x10000 total
Target not halted
ht32f165x mass erase failed

"Target not halted" と言われて消去できなかったので、halt コマンド後に ht32f165x mass_erase 0 を実行する。そのあと新しい初期ファームの書き込み。

$ telnet 127.0.0.1 4444

Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
Open On-Chip Debugger

> halt

target halted due to debug-request, current mode: Handler HardFault
xPSR: 0x01000003 pc: 0x00000124 msp: 0x20000710

> ht32f165x mass_erase 0

ht32f165x probe: 64 pages, 0x400 bytes, 0x10000 total
ht32f165x mass erase complete

次の書き込みコマンドは実行してからしばらく待たされます。プログレスバーも出ないのでプロンプトが戻るまで待ちましょう。私の場合は8分弱かかりました。

> flash write_image ./src/pok3r_re_firmware/disassemble/core/builtin_core/firmware_builtin_core.bin 0

ht32f165x probe: 64 pages, 0x400 bytes, 0x10000 total
wrote 8856 bytes from file 
./src/pok3r_re_firmware/disassemble/core/builtin_core/firmware_builtin_core.bin in 456.586639s (0.019 KiB/s)

exit で Telnet を抜ける。

> exit

Connection closed by foreign host.

これで元のファームウェアの消去と新しい初期ファームの書き込みが終了して Unlock された Vortex Core を手に入れました。

OpenOCD が起動しているターミナルは下記のような表示になっているはずです。このまま ctrl+c で OpenOCD を終了します。

$ openocd -c 'set HT32_SRAM_SIZE 0x4000' -c 'set HT32_FLASH_SIZE 0x10000' -f /mingw64/share/openocd/scripts/interface/stlink-v2.cfg -f /mingw64/share/openocd/scripts/target/ht32f165x.cfg
Open On-Chip Debugger 0.10.0-rc1-dev-00005-ge3fa2ecb (2022-04-24-20:56)
Licensed under GNU GPL v2
For bug reports, read
    http://openocd.org/doc/doxygen/bugs.html
0x4000
0x10000
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
adapter speed: 12 kHz
trst_only separate trst_push_pull
Info : Unable to match requested speed 12 kHz, using 5 kHz
Info : Unable to match requested speed 12 kHz, using 5 kHz
Info : clock speed 5 kHz
Info : STLINK v2 JTAG v29 API v2 SWIM v7 VID 0x0483 PID 0x3748
Info : using stlink api v2
Info : Target voltage: 3.247431
Info : ht32f165x.cpu: hardware has 6 breakpoints, 4 watchpoints
Info : accepting 'telnet' connection on tcp/4444
target halted due to debug-request, current mode: Handler HardFault
xPSR: 0x01000003 pc: 0x00000124 msp: 0x20000710
Info : ht32f165x probe: 64 pages, 0x400 bytes, 0x10000 total
ht32f165x mass erase complete
Info : ht32f165x probe: 64 pages, 0x400 bytes, 0x10000 total
wrote 8856 bytes from file 
./src/pok3r_re_firmware/disassemble/core/builtin_core/firmware_builtin_core.bin in 456.586639s (0.019 KiB/s)
Info : dropped 'telnet' connection

ここで一度、電源を供給しているUSBケーブルとデバッガのUSBケーブルをPCから外し、デバッガとキーボードをつないでいる20PINコネクタも外します。

キーボード上にハンダ付けしている部分はまだ外さないでください。この後の作業でキーボードが反応しなくなり、再度ファームウェアの消去と初期化を行うかもしれないからです。

カスタムファームウェア書き込み

再びキーボードとPCをUSBケーブルで接続し、予め作成しておいたカスタムファームウェアを書き込みます。

$ cd ~/src/pok3rtool-build
$ ./pok3rtool -t vortex-core flash QMK_CORE ~/src/qmk_pok3r/vortex_core_default.bin

下記のように表示されますが、OK をタイプして続行、OK は大文字にしなければダメでした。

WARNING: THIS TOOL IS RELATIVELY UNTESTED, AND HAS A VERY REAL RISK OF CORRUPTING YOUR 
KEYBOARD, MAKING IT UNUSABLE WITHOUT EXPENSIVE DEVELOPMENT TOOLS. PROCEED AT YOUR OWN RISK.
Type "OK" to continue:

OK

Proceeding...
Opened Vortex Core (bootloader)
Update Firmware: C:\msys64\home\hoge\src\qmk_pok3r\vortex_core_default.bin
Current Version: CLEARED
Firmware CRC D: 7b359562
Firmware CRC E: 45c12403
crc 0
sum 0
Current CRC: 00000000
Erase...
Write...
crc 45c12403
sum 45e6cc48
New CRC: 45c12403
Writing Version: QMK_CORE
Reset to Firmware
true

キーボードが意図した通りにカスタマイズされていることを確認したら、デバッグ用にハンダ付けした部分を取り外し基板を元のケースに戻してください。

これで QMK化された Vortex Core を手に入れました。

Keyboard:Vortex Core, Keycap:DSA MILKSHAKE

書き込みに失敗する場合

書き込みに失敗した例

下記のように書き込みに失敗する場合が度々あります。

$ ./pok3rtool -t vortex-core flash QMK_CORE ~/src/qmk_pok3r/vortex_core_default.bin

WARNING: THIS TOOL IS RELATIVELY UNTESTED, AND HAS A VERY REAL RISK OF CORRUPTING YOUR 
KEYBOARD, MAKING IT UNUSABLE WITHOUT EXPENSIVE DEVELOPMENT TOOLS. PROCEED AT YOUR OWN RISK.
Type "OK" to continue:
OK
Proceeding...
Opened Vortex Core [QMK]
Update Firmware: C:\msys64\home\hoge\src\qmk_pok3r\vortex_core_default.bin
Reset to Bootloader
false

リセット＆再書き込み

bootloader コマンドの実行。

$ ./pok3rtool -t vortex-core bootloader
Opened Vortex Core [QMK]
Reset to Bootloader
true

再書き込み。

$ ./pok3rtool -t vortex-core flash QMK_CORE ~/src/qmk_pok3r/vortex_core_default.bin

WARNING: THIS TOOL IS RELATIVELY UNTESTED, AND HAS A VERY REAL RISK OF CORRUPTING YOUR 
KEYBOARD, MAKING IT UNUSABLE WITHOUT EXPENSIVE DEVELOPMENT TOOLS. PROCEED AT YOUR OWN RISK.
Type "OK" to continue:
OK
Proceeding...
Opened Vortex Core [QMK]
Update Firmware: C:\msys64\home\moto-\src\qmk_pok3r\vortex_core_default.bin
Reset to Bootloader
false

また失敗なので、bootloader コマンドの実行からやり直し。

$ ./pok3rtool -t vortex-core bootloader
Opened Vortex Core [QMK]
Reset to Bootloader
true

$ ./pok3rtool -t vortex-core flash QMK_CORE ~/src/qmk_pok3r/vortex_core_default.bin
WARNING: THIS TOOL IS RELATIVELY UNTESTED, AND HAS A VERY REAL RISK OF CORRUPTING YOUR 
KEYBOARD, MAKING IT UNUSABLE WITHOUT EXPENSIVE DEVELOPMENT TOOLS. PROCEED AT YOUR OWN RISK.
Type "OK" to continue:
OK
Proceeding...
Opened Vortex Core (bootloader)
Update Firmware: C:\msys64\home\moto-\src\qmk_pok3r\vortex_core_default.bin
Current Version: QMK_CORE
Firmware CRC D: 0199cb8f
Firmware CRC E: 3f6d7aee
crc fe209faa
sum e8559d3b
Current CRC: fe209faa
Erase...
Write...
crc a01092b8
sum 7bc2ac6f
New CRC: a01092b8
CRCs do not match, firmware write failed
false

また失敗。めげずにやり続ける。

$ ./pok3rtool -t vortex-core bootloader
Opened Vortex Core (bootloader)
true

$ ./pok3rtool -t vortex-core flash QMK_CORE ~/src/qmk_pok3r/vortex_core_default.bin
WARNING: THIS TOOL IS RELATIVELY UNTESTED, AND HAS A VERY REAL RISK OF CORRUPTING YOUR 
KEYBOARD, MAKING IT UNUSABLE WITHOUT EXPENSIVE DEVELOPMENT TOOLS. PROCEED AT YOUR OWN RISK.
Type "OK" to continue:
OK
Proceeding...
Opened Vortex Core (bootloader)
Update Firmware: C:\msys64\home\moto-\src\qmk_pok3r\vortex_core_default.bin
Current Version: CLEARED
Firmware CRC D: 0199cb8f
Firmware CRC E: 3f6d7aee
crc a01092b8
sum 7bc2ac6f
Current CRC: a01092b8
Erase...
Write...
crc 3f6d7aee
sum 5088c541
New CRC: 3f6d7aee
Writing Version: QMK_CORE
Reset to Firmware
true

成功！このように連続して書き込みに失敗することがありますが、何度か繰り返せば書き込めるようです。

Koshinoyaのブログ

キーボード関連を中心に