# WSL2にPico C SDK環境をインストールする

Windows 11自体やSDKのアップデートにより、Windows上でPico C SDKによるデバッグが頻繁に利用できなくなったり、壊れる現象が発生しています。もっとも良い解決方法は、開発環境にLinuxかmacOSを利用することですが、手元に自由に利用できるLinuxやMacがないという方も多いでしょう。

次善の策として、Windows上の仮想Linux環境であるWSL2にPico C SDKをインストールして利用する方法があります。若干の手間は発生しますが、VSCodeのWSL拡張機能を利用することでWindowsから透過的に開発環境を利用でき、なおかつ仮想とはいえLinux環境下であるためWindowsネイティブよりは安定してPico C SDKを利用することが可能です。Windows上でPico C SDKが動作しなくなった、あるいはインストールできなかった方は以下の手順を参考に、WSL2にインストールしてください。

## WSL2をWindowsにインストールする

WSL2のインストール方法はMicrosoft公式を始め、さまざまなサイトに解説があるので、それを参考にすればいいでしょう。インストールプロセス自体は簡単です。コマンドプロンプトかPower Shellを管理権限で開き、次のコマンドを実行してWindowsを再起動します。

```console
> wsl --install [Enter]
```

ディストリビューションはWindows Storeからインストールするのが簡単です。Windows Storeを起動して、インストールしたいディストリビューション名を検索してインストールしてください。ディストリビューションは自分が利用したいものがあればそれで構いませんが、ここではUbuntu 22.04 LTS以降を前提にしていきます。

![Windows StoreでUbuntuを検索した例。22.04 LTS以降をインストールします](image/INSTALL/1764217917063.png)

![入手をクリックしてインストール](image/INSTALL/1764217966770.png)

ディストリビューションのインストールが終わったら、端末を開いて初期ユーザー名とパスワードを登録し、Linuxのシェルが利用できる状態にしてください。

![端末を使えるようにする](image/INSTALL/1764218113004.png)

端末が使えるようになったら、aptを使って次のパッケージをインストールしておいてください。Pico C SDKを利用するために必要になります。

```console
sudo apt update [Enter]
sudo apt upgrade [Enter]
sudo apt install libhidapi-dev gdb-multiarch  libftdi1-dev libusb-1.0-0-dev usbutils autogen build-essential [Enter]
```

>初出時にインストールすべきパッケージとしてautogenが抜けていました。autogenがないせいでプロジェクトのエラーが出ている場合は追加でインストールしてください。

## usbipd-winのインストール

WSL2はMicrosoftの仮想化技術Hyper-Vを用いて、WSL2専用の仮想マシン下でLinuxを動作させています。Hyper-V仮想マシンに、ホストOS側のUSBデバイスを割り当てる[usbipd-win](https://github.com/dorssel/usbipd-win)というツールがオープンソースで開発されています。

WSL2上のPico C SDKを利用してデバッグを行うには、WSL2環境下でCMSIS-DAPを利用しなければならないので、そのためにusbipd-winを利用します。[公式サイトのReleaseページ](https://github.com/dorssel/usbipd-win/releases)から最新バージョンのインストーラー（MSIパッケージ形式）ダウンロードしてください。MSIパッケージをダブルクリックしてWindowsにインストールします。

PCにCMSIS-DAP（PicoprobeかRaspberry Pi Debug Probe）を接続しておいてください。usbipd-winをインストール後、Power Shellまたはコマンドプロンプトを**管理権限で**開きます。まず、`usbipd list`を実行して現在のUSBデバイスのリストを得ます。

![Windowsが認識しているUSBデバイスのリストを得る](image/INSTALL/1764220124728.png)

このようにCMSIS-DAP v2がリストに含まれているはずです。usbipdは、BUSIDかVID:PIDのいずれかでデバイスをHyper-V仮想マシン下に割り当てることができます。どちらでもいいですが、おすすめはVID:PIDです。VID:PIDで割り当てておくと、接続するUSBポートを変えてもusbipdの共有対象デバイスが維持されるからです。この例であれば2e8a:000cをコピーしておきます。

そのうえで、次のコマンドを実行しusbipdの共有対象デバイスに2e8a:000cを登録します。

```console
> usbipd bind --hardware-id 2e8a:000c [Enter]
```

改めてリストを取ると、次のようにSTATEがSharedに変わっているはずです。

![usbipdの共有対象にCMSIS-DAPが追加された](image/INSTALL/1764220815816.png)

このようにSharedに設定したデバイスは、次のコマンドでWSL2仮想マシンに接続できます。

```console
> usbipd attach --wsl --hardware-id 2e8a:000c [Enter]
usbipd: info: Device with hardware-id '2e8a:000c' found at busid '9-2'.
usbipd: info: Using WSL distribution 'Ubuntu' to attach; the device will be available in all WSL 2 distributions.
usbipd: info: Detected networking mode 'nat'.
usbipd: info: Using IP address 172.30.112.1 to reach the host.
```

この例のようにエラーなくattachできたなら、Linuxの端末側で`lsusb`コマンドを実行してみてください。

```console
$ lsusb [Enter]
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 2e8a:000c Raspberry Pi Debugprobe on Pico (CMSIS-DAP)
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
```

このように仮想マシン下のLinux側に接続されているはずです。なお、仮想マシンに接続したUSBデバイスは、ホストOSであるWindows上では利用できなくなります。ホストOS側でCMSIS-DAPを利用したいときは、Power Shellまたはコマンドプロンプトで次のコマンドを実行しdetachします。

```console
> usbipd detach --hardware-id 2e8a:000c [Enter]
```

同じようにunbindを実行すれば共有デバイスからも外せますが、今後もWSL2環境側でCMSIS-DAPを使うのであればunbindは必要ありません。いったんbindしたデバイスは、USBポートから取り外したり、Windowsを再起動しても共有デバイスリストに残り続けます。

ただし、attachの操作はWSL2起動後に毎回必要になります。少々面倒ですが、Pico C SDKを利用する前にPower Shellもしくはコマンドプロンプトを開いてコマンドを実行するだけでので、大した手間でもないでしょう。

### ユーザー権限でCMSIS-DAPを利用できるようにする

以上のよううusbipd-winを利用すればWSL2仮想マシンにCMSIS-DAPを接続できますが、インストールしたディストリビューションによってはユーザー権限でCMSIS-DAPが利用できないかもしれません。Ubuntuのデスクトップ版などデスクトップ向けのディストリビューションをインストールした場合、通常はUSBデバイスのアクセス権がユーザーにあるのでユーザー権限でCMSIS-DAPを利用できます。しかし、Ubuntuの最小構成をインストールしたり、あるいは他のディストリビューションの初期設定では必ずしもユーザー権限でCMSIS-DAPが利用できるとは限りません。

CMSIS-DAPが`lsusb`コマンドで見えているのにデバッグできない場合、通常はUSBデバイスにアクセスするために必要な権限がユーザーにないことが原因なので対処が必要です。まず、グループplugdevに自分自身を追加してください。次のコマンドをLinuxの端末上で実行します。`yourname`はLinux上のアカウント名にします。

```console
sudo usermod -aG plugdev yourname [Enter]
```

次にudevの設定ファイルを作成します。nanoエディタをroot権限で起動して/etc/udev/rules.d/99-cmsis-dap.rulesを新規作成しましょう。

```console
sudo nano /etc/udev/rules.d/99-cmsis-dap.rules [Enter]
```

設定ファイルの内容は次のとおりです。なお、`ATTRS{idVendor}`の右辺は先に確認したCMSIS-DAPのVendorID、`ATTRS{idProduct}`の右辺は同ProductIDです。自分で確認したIDにそれぞれを変更してください。

```udev.rule
SUBSYSTEM=="usb", ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="000c", MODE="0660", GROUP="plugdev"
```

この1行をnanoエディタで入力したら、[Ctrl+X]を押して保存、エディタを終了させます。

設定を反映させるために、WSL2を再起動させます。Linux端末やWSL2に接続しているVSCodeがあるなら、それらを閉じてから、Power Shellまたはコマンドプロンプトを開き、次のコマンドを実行してWSL2をいったんシャットダウンしてください。

```console
> wsl --shutdown [Enter]
```

以上の作業で、CMSIS-DAPによるデバッグができるようになるはずです。

## VSCodeにWSL拡張とPico拡張をインストール

Windows上でVSCodeを起動し、拡張機能「WSL」を検索してインストールしてください。提供元がMicrosoftになっていることを必ず確認します。

![Microsoft純正のWSL拡張機能をインストールする](image/INSTALL/1764222939769.png)

インストール後、VSCodeウィンドウ左下にあるリモート接続アイコンをクリックします。接続先を聞いてくるので、「WSLへの接続」を選択します。

![WSLへの接続を選択](image/INSTALL/1764223120049.png)

初回接続時にはWSL2のLinux側でVSCodeサーバーの設定が行われるので少し時間がかかりますが、しばらくするとWS2に接続した状態に切り替わります。左下のアイコンが`WSL:ディストリビューション名`に切り替わるので、それを確認してください。

![WSL2に接続した状態](image/INSTALL/1764223279680.png)

正常にWSL2に接続できたら、拡張機能アイコンをクリックしてPico拡張を検索します。次のように`WSL:ディストリビューション名にインストール`というインストールボタンが表示されるはずなので、クリックしてWSL側にPico拡張をインストールしましょう。

![WSL2にPico拡張をインストールする](image/INSTALL/1764223420014.png)

あとは、Windows側にインストールした場合とほとんど同じようにPico C SDKによる開発が行えます。注意すべきなのは、次の点です。

* VSCode起動後に必ずWSLに接続し接続状態を確認する
* デバッグを行う前に、CMSIS-DAPがWSLにattachされていることを確認する。attachされていないときはPower Shellまたはコマンドプロンプト上でusbipdコマンドを使ってattachする
* プロジェクトディレクトリはWSL2の仮想ストレージ下に作成する（/mnt/ドライブレター/以下を使えばWindows側のストレージにもプロジェクトを作成できますが、WSL2はWindowsストレージへのアクセスが極端に遅いので、あまりおすすめできません）
* シリアル端末にはデバイスノード`/dev/ttyACM0`を利用する

![WSL2上でPico C SDK](image/INSTALL/1764290077246.png)
