Windows(WSL)向けセットアップ

このガイドでは、Windows環境のWSL (Windows Subsystem for Linux) を使用して、PicoRubyを動作させるためのR2P2-ESP32環境を構築する手順を説明します。

前提

WSLを利用します。過去利用したことがあって以下のものがインストール済みの場合は次のステップに進んでください。

ESP-IDF のインストール

ESP-IDFはESP32の開発環境です。

1. WSL環境の準備

1.1 WSLの起動

ターミナルを開きます（スタートメニューで「Powershell」と検索）

wsl

プロンプトが以下のように変わります

1.2 必要なパッケージのインストール

WSL内で以下のコマンドを実行：

sudo apt-get update
sudo apt-get install -y git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

1.3 ESP-IDFのインストール

ESP32用のツールをインストールします

作業ディレクトリの作成

mkdir -p ~/esp
cd ~/esp

ESP-IDF v5.4をクローン

git clone -b v5.4 --recursive https://github.com/espressif/esp-idf.git

ESP32用ツールのインストール

cd ~/esp/esp-idf
./install.sh esp32

ESP-IDFの環境変数を読み込みます

. ~/esp/esp-idf/export.sh

1.4 usbipd-winのインストール

WSLからUSBデバイスを使用するため、別のターミナル でPowerShellを開き、以下を実行

usbipd-winがインストールされているか確認

usbipd --version

インストールされていない場合

winget install --interactive --exact dorssel.usbipd-win

install

「Install」を押す

completed

「Close」を押す

1.5 USBデバイスの認識確認

ここで一旦マイコンを接続して動作確認をします

マイコンをPCに接続して、PowerShellで以下を実行

usbipd list

出力例

BUSID  VID:PID    DEVICE                           STATE
1-1    0403:6001  USB Serial Converter             Not shared

USB Serial Converter が表示されることを確認します。

🛠️ デバイスが表示されない場合

確認できたら、一旦USB接続を外し、PowerShellは開いたままにしておきます（後で使用します）。

2. R2P2-ESP32のセットアップ

2.1 プロジェクトのクローン

WSLのターミナルで

cd ~/esp
git clone --recursive https://github.com/picoruby/R2P2-ESP32.git
cd R2P2-ESP32

2.2 初期セットアップとビルド

# ESP32用の初期セットアップ
rake setup_esp32

このコマンドで以下が実行されます

2.3 プロジェクトのビルド

rake build

ビルドが成功すると、buildディレクトリにファームウェアが生成されます。

3. デバイス接続と書き込み

USBでマイコンをパソコンと繋いでください

3.1 USBデバイスのバインド（Windows側）

PowerShellを管理者権限で新しく開き、以下を実行

usbipd bind --busid 1-1

※ BUSIDは[1.5]で確認した、USB Serial ConverterのBUSID値を使用します(上記例では1-1) （わからない場合はもう一度 usbipd list で確認できます）

3.2 WSLへのアタッチ（Windows側）

通常権限のPowerShellで､以下を実行

usbipd attach --wsl --busid 1-1

※ BUSIDは1.5で確認した値を使用

成功すると以下のようなメッセージが表示されます

usbipd: info: Using WSL distribution 'Ubuntu' to attach

3.3 デバイスの確認（WSL側）

WSLのターミナルで､以下を実行

ls /dev/tty*

/dev/ttyUSB0などが表示されることを確認します。

4. ファームウェアの書き込みと実行

4.1 書き込み

プログラム環境とファイルをマイコンに転送します。

WSLのターミナルで､以下を実行

rake flash

以下のエラーが出た場合は

/dev/ttyUSB0 failed to connect: Could not open /dev/ttyUSB0, the port is busy or doesn't exist.
([Errno 13] could not open port /dev/ttyUSB0: [Errno 13] Permission denied: '/dev/ttyUSB0')

Hint: Try to add user into dialout or uucp group.

以下を実行して再度WSLのターミナルを開き、 rake flash してください

sudo adduser $USER dialout

以下のエラーが出た場合は

A fatal error occurred: Unable to verify flash chip connection

以下を実行してください

ESPBAUD=115200 rake flash

4.2 シリアルモニターの起動

マイコンからの出力メッセージを表示し、コマンドを送信できる通信画面(=シリアルモニタ)を起動します。以下を実装します。

rake monitor

4.3 一括実行

ビルド、書き込み、モニターを一括で実行

rake

5. PicoRuby Shellの確認

書き込みが成功すると、シリアルモニターに以下が表示されます：

WSL R2P2

これで、マイコンでPicoRubyコードを実行できる環境が整いました！

終了するときは Ctl + ] で終わってください

トラブルシューティング

rake flashに失敗する

rake flash --trace
** Invoke flash (first_time)
** Execute flash
idf.py flash
rake aborted!
Command failed with status (127): [idf.py flash]

ESP-IDF環境変数の再読み込みが必要。別ターミナルを起動した等 export.sh がなくなっている場合がある。ので ~/esp/R2P2-ESP32 配下で実行する。

. ~/esp/esp-idf/export.sh

attachに失敗する

usbipd attach --wsl --busid 1-1
usbipd: info: Using WSL distribution 'Ubuntu' to attach; the device will be available in all WSL 2 distributions.
usbipd: info: Loading vhci_hcd module.
usbipd: info: Detected networking mode 'nat'.
usbipd: info: Using IP address 172.20.80.1 to reach the host.

管理者権限で実行できていないので、PowerShellを管理者権限で実行し直してください。

ポートが見つからない場合

No serial ports found. Connect a device, or use '-p PORT' option

対処法：

  1. USBデバイスがWSLにアタッチされているか確認
  2. /dev/ttyUSB0が存在するか確認
  3. ポートを明示的に指定： 
    idf.py -p /dev/ttyUSB0 flash

WSLでのパーミッションエラー

# 実行権限の付与
chmod +x ~/esp/esp-idf/install.sh
chmod +x ~/esp/esp-idf/export.sh

rake build や rake monitor でエラーが出る場合

一時的に動かなくなっている可能性があります

2.1 プロジェクトのクローン の後 2025/11/14時点動作確認済みバージョンに固定、サブモジュールも同じ時点の状態に更新してください

git checkout d7c61ab
git submodule update --init --recursive

参考リンク