VRC Pro：MINI-Z のプロポで運転する 2/2（ファームウェア書き込み）

MINI-Z のプロポ KT-531P を分解して XIAO RP2040 に配線したので、その続き。
ファームウェアを書き込んで、USB HID ゲームパッドとして Windows に認識させるところまでです。MINI-Z のプロポで VRC Pro を運転するのが目的です。

コードは GitHub に上げてあります。

※ 自分の環境（Windows 11）での話です。他の環境での結果を保証するものではありません。

用意するもの

品目	入手先など
Visual Studio Code	https://code.visualstudio.com/
PlatformIO IDE 拡張	VSCode の拡張機能マーケットプレイス（ID: `platformio.platformio-ide`）
Git for Windows	https://git-scm.com/
USB Type-C ケーブル	データ通信対応品。充電専用ケーブルだと PC が認識しません

ディスクは %USERPROFILE%\.platformio の下に 2〜3 GB ぐらい空きが要ります。初回ビルドでツールチェーンとコアを取得するので。

※ Arduino for Visual Studio Code（vsciot-vscode.vscode-arduino）は入れないこと。開発が終了していて、PlatformIO と競合します。

Windows の長いパスを有効にする（必須）

arduino-pico のコアはパスの深いファイルを含むので、Windows の 260 文字制限を解除していないとコアのインストール自体が Filename too long で失敗します。

管理者権限の PowerShell で実行して、再起動します。Windows 10 バージョン 1607 以降で有効です。

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

グループポリシーからやる場合は、「コンピューターの構成」→「管理用テンプレート」→「システム」→「ファイルシステム」→「Win32 の長いパスを有効にする」を「有効」に。

Git 側にも同じ制限があるので、こちらも解除しておきます。

git config --global core.longpaths true

クローン先は浅い場所に

上を設定していても、深い階層に置くとツールによっては失敗します。C:\dev\kt531p-usb-gamepad ぐらいの短いパスに置くのが無難です。

プロジェクトを開く

VSCode を起動する
PlatformIO IDE 拡張をインストールして、VSCode を再起動する（左サイドバーにアリのアイコンが出れば成功）
「ファイル」→「フォルダーを開く」で、クローンしたリポジトリのルート（platformio.ini があるフォルダ）を開く

.vscode/extensions.json の推奨拡張が提示されたら入れて大丈夫です。

ビルド

VSCode 下部のステータスバーのアイコン、またはショートカットを使います。

操作	アイコン	ショートカット
ビルド	チェックマーク	`Ctrl+Alt+B`
ビルド＋書き込み	右矢印	`Ctrl+Alt+U`
クリーン	ゴミ箱	—

CLI からやる場合は、コマンドパレット（Ctrl+Shift+P）→ PlatformIO: New Terminal で開いたターミナルを使います。pio にパスが通っていて、カレントディレクトリもプロジェクトルートになります。

pio run

通常の PowerShell でも pio は使えることが多いです。インストーラが %USERPROFILE%\.platformio\penv\Scripts を %PATH% の先頭に追加するので。見つからない場合はフルパスで。

& "$env:USERPROFILE\.platformio\penv\Scripts\platformio.exe" run

pio 系のコマンドは、いずれも platformio.ini があるフォルダで実行してください。別の場所だと設定が読まれません。

初回だけ、platformio.ini に書かれたプラットフォームとツールチェーンの取得が走ります。事前インストールは不要ですが、数分から十数分かかります。framework-arduinopico のサブモジュール取得が大半。

成功すると RAM / Flash の使用率と [SUCCESS] が出て、.pio\build\seeed_xiao_rp2040\firmware.uf2 ができます。

RAM:   [          ]   x.x% (used ... bytes from 270336 bytes)
Flash: [          ]   x.x% (used ... bytes from 2093056 bytes)
========================= [SUCCESS] Took ... seconds =========================

platformio.ini はいじらないこと

build_flags は意図的に空にしてあります。
-DUSE_TINYUSB を足すと Joystick.h が使えなくなり、-DCFG_TUSB_CONFIG_FILE= を足すとビルドそのものが通りません。

USB スタック	`Joystick.h`
Pico SDK（デフォルト）	使える
Adafruit TinyUSB	使えない

コアの指定も board_build.core = earlephilhower の 1 行が必要です。これが無いと Joystick.h が入っていない別のコアになります。

書き込み

ブートローダーモードに入る

初回の書き込みでは、ボードを手動でブートローダーモードにします。XIAO RP2040 には B（BOOT）と R（RESET）の 2 つのボタンがあります。

B ボタンを押したまま USB ケーブルを PC に接続する
（接続済みなら、B を押しながら R を押して離し、その後 B を離す）
エクスプローラーに RPI-RP2 という名前のドライブが現れる

一度書き込んだ後は、PlatformIO が COM ポートを 1200bps で開閉してボードをブートローダーに落とすので、以降はボタン操作なしで書き込めます。

PlatformIO から書き込む

RPI-RP2 が見えている状態で Ctrl+Alt+U（または pio run -t upload）を実行します。書き込みには picotool が使われます。

COM ポートの自動検出に失敗する場合は明示的に指定します。ポート番号は pio device list かデバイスマネージャーで確認できます。

pio run -t upload --upload-port COM5

RP2040 のブート ROM は MS OS ディスクリプタを持っているので、通常は Zadig で WinUSB に差し替えなくても picotool が動きます。環境によってはドライバが当たらない事例もあるようですが、その場合は次の UF2 コピーに切り替えれば済むので、Zadig は試さなくて良いです。

駄目なら UF2 を直接コピーする

書き込みツールが失敗する場合、UF2 のドラッグ＆ドロップが確実です。

B ボタンを押しながら接続して RPI-RP2 ドライブを出す
.pio\build\seeed_xiao_rp2040\firmware.uf2 を RPI-RP2 にコピーする

コピーが終わると同時にドライブが消えて、ボードが自動でリブートします。

初回キャリブレーション

書き込み後に一度キャリブレーションをやります。
やらなくてもそれなりに動くと思いますが、ニュートラル位置やエンドポイントがずれているかもしれません。

キャリブレーション値は XIAO 側の EEPROM（フラッシュ最終セクタのエミュレーション）に保存されるので、電源を切っても、ファームウェアを再書き込みしても残ります。

通常起動したあと、B ボタンを 3 秒長押しで入ります。PC は不要です。

※ 「B を押しながら起動」では入れません。それはブートローダーに入る操作です。

手順は

段階	LED	操作
1. ニュートラル採取（3 秒）	青ゆっくり点滅	ホイールとトリガーから手を離して待つ
2. エンドポイント採取	青速く点滅	ステアリングを左右いっぱい、スロットルを前後いっぱいに数往復させる
3. 確定（2 秒）	緑 = 保存 / 赤 = 不採用	動きが 5 秒止まると自動で終了する

キャリブレーション中は両軸の出力が 0 に固定されます。終わると自動で通常動作に戻ります。
途中でやめたいときは B を押す。その場合は前回の値がそのまま維持されます。

LED が赤で終わった場合は、妥当性チェックで不採用になったか、EEPROM への書き込みに失敗しています。
不採用になるのは振り切りが足りていないことが多いので、両端まで確実に動かしてやり直してください。

認識の確認

書き込み後、デバイスマネージャーの「ヒューマンインターフェイスデバイス」に「HID 準拠ゲームコントローラー」として出て Windows 標準ドライバで動きます。

軸の確認は VRC Pro のコントローラー設定画面でやります。ステアリングを回すとステアリングの軸が、トリガーを引くとスロットルの軸が反応すれば正常です。

※ Windows のゲームコントローラー設定（Win+R → joy.cpl）の「設定」タブにある「調整」は実行しないこと。キャリブレーションはファームウェア側でやるので、Windows 側でも掛けると二重になってニュートラルのずれや可動域の欠けが起きます。誤って実行した場合は同じ画面の「既定値にリセット」で戻せます。

※ POV（ハットスイッチ）の表示が中央にならず特定方向を指すことがあります。このファームウェアは POV を使わないので実害はないんですが、ゲーム側で方向入力が勝手に入るように見えたら、そのゲームで POV の割り当てを外してください。

VRC Pro 側の設定

VRC Pro からは DirectInput のゲームコントローラーとして見えます。
「options」→「control options」の「select controller」で XIAO RP2040 を選びます。
スロットルの前後が逆になるので、同じ画面の「reverse throttle」は ON にしています。

VRC Pro の control options で XIAO RP2040 を選び reverse throttle を ON にする

使ってみた感想

初のホイールプロポかつまともに周回できてない腕前ですが、ホイールプロポに慣れるには良さそうです。
ただ、有線接続部の強度が不安なので、負荷が掛からないように工夫した方が無難そうです。