KeyChron V1 MaxでQMK Firｍwareをカスタマイズして、OSがJIS設定でもUS配列通りのキー配列の動作を実現させる

## はじめに
　プライベートでUS配列を使用していますが、OS側の設定でUS配列モードにしないとUS配列の動作が無いので、JIS配列設定のままでも、US配列キーボードが使用できるように[Ule4Jis](https://www.vector.co.jp/soft/winnt/util/se476294.html)というソフトを使用していました。またUS配列をそのまま使用すると、英数かな変換がやりにくいので[alt-ime-ahk](https://github.com/karakaram/alt-ime-ahk)などのソフトを入れて、スペースキーの右側のAltキーを押すとかなモード、左側のAltキーを押すと英数モードになるようなソフトを入れて使いやすくしていました。

　しかし、職場ではセキュリティ上、私用で扱うPCのように申請を通さないとソフトをダウンロードすることはできません。そこで、OSの設定をしたり、ソフトをダウンロードするのではなく、ハードウェア側で設定して何とかしようとしているのがこの記事を発見して、それを基に私のキーボードをカスタマイズしました。

　この記事は、参考にした記事の中で私が詰まったところや分からなかったところを追記したものになります。
 
※私もキーボードカスタマイズは初めて、設定方法で分からないところはChat GPTに相談しながら設定しました。読んでいて至らない点もあるかと思いますが、ご了承ください。

## 実現できること
- JIS モードでも US 配列通りのキー入力ができるようになる
- JIS モード、US モードの切り替えができるようになる
- OS 側のキー配列設定に悩まされず、自由にキーをカスタマイズできるようになる
- カスタマイズ後もVIAやKeychron - Launcherによる GUI を使ったカスタマイズが可能(筆者はalt-ime-ahkを使用した際に近い動作になるようにカスタマイズしました。)

## ファームウェア書き込み手順
### 1. [QMK CLI](https://docs.qmk.fm/cli)をインストールおよびセットアップ
　まず[QMK MSYS](https://msys.qmk.fm/)という統合開発環境をインストールして、QMK CLIをインストール、セットアップを行います。
 セットアップコマンドは以下のものです。
 ```bash:bash
 qmk setup
 ```
### 2. [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases)をインストール
### 3. [https://github.com/hnishi/qmk_firmware.git](https://github.com/hnishi/qmk_firmware.git )をクローンしてください。
　以下のコマンドでクローンします。
 ```bash:bash
 git clone https://github.com/hnishi/qmk_firmware.git
 ```
 これで、hnishi/qmk_firmwareというGitHub上のフォルダ（リポジトリ）の内容が、PC上に「qmk_firmware」という名前のフォルダとしてコピーされます。
 ### 4. QMK Firmware をビルドします (qmk home directory を~/work/qmk_firmwareとします)
 　まず、以下のコマンドで「qmk_firmware」のディレクトリに移動します。
 ```bash:bash
 cd qmk_firmware
 ```
 　そして以下のビルドコマンドを実行します。
 ```bash:bash
 qmk compile -kb keychron/v1_max/ansi_encoder -km hnishi
 ```
 ※私は上記のコマンドを実行した際、「QMKファームウェアのビルドに必要なファイル（startup_stm32f4xx.mk など）が不足しているため、ビルドが途中で止まってしまった。つまり、サブモジュール（submodules）が正しく取得できていない」というエラーが出てきました。
 　ですので、QMKファームウェアの一部を手動で取得するために以下のようなコマンドを実行しました。
  ```bash:bash
  git submodule update --init --recursive
  ```
  　その後に、ビルドコマンドを実行して解決しました。
  　コンパイルが成功すると、~/work/qmk_firmware/keychron_v1_max_ansi_encoder_hnishi.binが生成されます。
### 5. キーボードを接続し、作成されたファームウェアを書き込みます
①QMK Toolboxを起動し、「Auto-Flash」にチェックを入れておきます。
②ファームウェア（.binファイル）を読み込む
 QMK Toolbox の上部にある「Open」ボタンから、先ほど作成したqmk_firmware/keychron_v1_max_ansi_encoder_hnishi.bin ファイルを開きます。
③キーボードを DFU（書き込みモード） に入れる
キーボード裏面のスイッチを「有線（Wired）」モードにします。
「Esc + Q キー」を同時押ししたまま、USBケーブルをPCに接続します。
そして、QMK Toolbox上に以下のようなメッセージが出れば成功です。
```
*** DFU device connected
```
④書き込みが開始（Auto-Flash有効なら自動）
Auto-Flash が有効になっていれば、キーボードがDFUモードに入った瞬間に書き込みが始まります
```
Flashing .bin to DFU device...
Flash complete!
```

## カスタマイズ作業手順
※このステップでは、Keychron用にカスタマイズされたQMKファームウェア（特に wireless_playground ブランチ）を、自分のPCにクローンしてセットアップする方法を解説しています。
私自身もGitHubをあまり扱わなかったことがなかったので、備忘録として詳しく書いてあります。
### 1. QMKファームウェアのセットアップ
　まず、[keychronのQMKファームウェアリポジトリ](https://hakasenote.hnishi.com/2025/20250404-customize-keychron-v1max-qmk-firmware/)をフォークします。
 ※V1 Maxは**wireless_playground**ブランチにソースコードがあるため、フォーク時に以下の写真にあるようにチェックボックスのチェックを外して、**wireless_playground**のブランチも含めてフォークする必要があります。
 
 ![Screenshot 2025-06-08 at 11-22-16 Fork Keychron_qmk_firmware.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3615896/898f87ad-ea9f-409c-9a57-da77ca273c72.png)

そして、以下のコマンドでカレントディレクトリに./qmk_firmwareのリポジトリをクローンし、必要なセットアップを行います。
```bash:bash
qmk setup あなたのGitHubユーザー名/qmk_firmware -H qmk_firmware -b wireless_playground
```
### 2. キーボードとキーマップの設定
　QMK の設定ファイルに、使用するキーボードとキーマップを指定します。まずは、qmk_firmwareのディレクトリ内に移動して以下の順にコマンドを実行し、リポジトリをクローンし、必要なセットアップを行います。
 ```bash:bash
qmk config user.keyboard=keychron/v1_max/ansi_encoder
qmk config user.keymap=hnishi
```
これらの設定はC:\Users\ユーザー名\AppData\Roaming\qmk\qmk.iniに保存されます。（筆者Windows11環境の場合）
### 3. 新しいキーマップの作成
　まず、QMKファームウェア内のディレクトリ(qmk_firmware)に移動します。
※パスは自身の環境に合わせます。
　そして、以下のコマンドを実行します。
 ```bash:bash
 qmk new-keymap
 ```
 このコマンドは、~/qmk_firmware/keyboards/keychron/v1_max/ansi_encoder/keymaps/hnishiに新しいキーマップを作成します。
### 4. キーマップのカスタマイズ
キーマップのカスタマイズは、keymaps/hnishi/keymap.cファイルを編集することで行えます。詳細な設定方法については、[QMK 公式ドキュメント](https://docs.qmk.fm/newbs_building_firmware#open-keymap-c-in-your-favorite-text-editor)を参照してください。
今回、この記事の[参考元の記事にあったコード](https://github.com/hnishi/qmk_firmware/blob/v1_max_us2jis/keyboards/keychron/v1_max/ansi_encoder/keymaps/hnishi/keymap.c)をそのまま使用しました。

以下のようなカスタマイズを行われます。
- Fn + Esc キーで JIS/US 配列切り替え可能
- EEPROM に設定を保存し、再起動後も維持
- LED パターンによるモード表示
    ・JIS モード: レインドロップパターン (RGB_MATRIX_RAINDROPS)
    ・US モード: サイクルパターン (RGB_MATRIX_CYCLE_ALL)
### 5. ファームウェアをコンパイル
　ディレクトリはQMKファームウェア内(qmk_firmware)のままで、作成したキーマップでファームウェアをコンパイルします。
 ```bash:bash
 qmk compile -kb keychron/v1_max/ansi_encoder -km hnishi
 ```
 コンパイルが成功すると、~/qmk_firmware/keychron_v1_max_ansi_encoder_hnishi.binが生成されます。
 ### 6. 作成したファームウェアウェア書き込み手順
 　作成したファームウェア(~/qmk_firmware/keychron_v1_max_ansi_encoder_hnishi.bin)をファームウェア書き込み手順の5であった通りに書き込みを行います。
### 7. キーマップカスタマイズ（Keychron - Launcherを使用）
 4の時点でキーマップを設定しておけば、良いのでは？と思った方もいらっしゃると思いますが、ファームウェアコンパイルを終了した後、キーマップを変更したくなり、手軽にキーマップを変更したかったのでこの方法を用いました。
 ![スクリーンショット_8-6-2025_18159_launcher.keychron.com.jpeg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3615896/c51806de-6b50-4ba8-8135-5b2eadc0b1f2.jpeg)
私はキーマップを以下のように変更しました。
- 右Altキーをかなモードキーに変更。
- 左Altキーを英数モードキーに変更。
- Caps lockをAltキーに変更。

 以上の設定で、[Ule4Jis](https://www.vector.co.jp/soft/winnt/util/se476294.html)や[alt-ime-ahk](https://github.com/karakaram/alt-ime-ahk)のソフトを使用したときに近い動作を実現できました。

 参考文献：
 - [Keychron V1MaxのQMK FirmwareをカスタマイズしてOSがJIS設定でもUS配列通りのキー入力を実現する](https://hakasenote.hnishi.com/2025/20250404-customize-keychron-v1max-qmk-firmware/)