VSCodeのRaspberry Pi Pico拡張機能をWSL2で利用する

本記事の記述は2025年12月時点のVSCodeやその拡張機能に基づいています。今後のバージョンアップによっては記事の内容が適用できなくなる可能性があります。
また、本記事は拡張機能によってインストールされるファイルに直接手を加えるものなので、場合によっては将来のバージョンアップに支障が出る可能性があります。自分の環境に適用する際は、何が行われているのかを理解してリスクを承知した上で実施してください。

概要

現在のRaspberry Pi Picoは、Visual Studio Code(以下VSCode)に公式の「Raspberry Pi Pico拡張機能」が提供されたことで開発環境の設定が非常に簡単になっています。
この拡張機能はクロスコンパイラやデバッガ、Pico SDKなど必要なツール類を一発でインストールしてくれるので大変便利なのですが、Windows版だとすべてのツールがWindows上に用意されるため、コマンドラインでの作業などVSCode内で収まらないことをやろうとすると、コマンドプロンプトやPowerShellを使うことになってしまって不便です。
拡張機能にはLinux版もあるのですが、こちらはネイティブのLinux環境を想定したもので、Windows内のLinux環境であるWSL2では基本的には使えません。そこで、WSL2にインストールした拡張機能に手を入れて、WSL2上でのPicoのコンパイル、書き込み、デバッグをWindows版VSCodeの拡張機能から使えるようにしてみました。

前提条件

• WSL2とVSCodeは既にセットアップ済みで、Windows側のVSCodeからリモートホストとしてWSL2に接続、WSL2側のファイルを扱えるようになっているものとします
• WSL2側に基本的な開発環境は入っているものとします (sudo apt install build-essentialなど)
• PicoにPico Debug Probeを接続して両方ともUSBでWindows側に接続されているものとします
• Raspberry Pi PicoのC/C++アプリの開発を前提としています。MicroPython等も問題なく扱えると思いますが、未確認です

動作原理

Raspberry Pi Pico開発環境とVSCode拡張機能

普通にWindowsのVSCodeにRaspberry Pi Pico拡張機能を導入すると、以下のような開発環境が構築されます。

• 拡張機能によって、Picoのバイナリをコンパイルするのに必要なツールチェイン一式やPico SDKなどがインストールされます。拡張機能の「Compile Project」などによりコンパイルが実行されます
• コンパイルされたバイナリは、「Run Project (USB)」によってPicoに書き込まれます。Pico基板上のBOOTSELボタンを押しながらリセットすることでPicoを書き込みモードにすると、picotool.exeというコマンドによって書き込みのためのアクセスができるようになります
• 「Flash Project (SWD)」では、Pico Debug ProbeからSWDを用いた書き込みが行えます。Debug ProbeはUSBでWindows上のopenocd.exeと接続します。openocd.exeはgdbから見たデバッグサーバとして働き、プログラムのデバッグを行うことができます
• Picoからのシリアルコンソール出力は、Debug ProbeのUART端子によってUSB UARTに変換されます。VSCodeからはSerial Monitor拡張機能によってPicoとの間でシリアル入出力を行うことができます

Pico拡張機能をWSL2側に適用すると

Raspberry Pi Pico拡張機能はLinux版もあるので、WSL2のLinuxにもインストールすることはできます。
この場合、ツール類ももちろんLinux版のものがインストールされるのですが、その結果以下のような状況が発生します。

• 「Compile Project」は普通に実行できて、Linuxファイルシステム上に置いたソースからELFバイナリも生成されます
• しかし、VSCode上からそのバイナリをPicoに書き込んだりデバッグしたりを行うことはできません

これは、WSL2がホストのWindowsと独立した仮想マシンとして動作していて、そのI/OであるUSBやシリアルポートがWindows環境と繋がっていないためです。
WSL2でない通常のLinux環境であれば、実際に外部デバイスと接続されているのでこれらの機能も使えるのですが。

WSL2からのデバイス利用

これを解決するのが以下の手段です。
やったことはシンプルで、「外部デバイスとやり取りするコマンドをLinux版からWindows版に差し替える」これだけです。

WSL2には、ホストのWindows環境と連携して動作するための以下の機能があります。

• WSL2のLinux上でWindowsのEXEファイルを実行すると、Windows側に投げられてWindowsアプリとして実行される
• WSL2のネットワークを「ミラーモード」にすると、WindowsとWSL2とで同一のIPアドレスを共有して動作する。あるポートに接続する際、そのポートをWindows側のアプリがlistenしていればWindows側に接続されるし、Linux側がlistenしていればLinux側に接続されてシームレスに扱うことができる

これらの機能によって、PicoやDebug Probeと接続する必要のあるコマンドだけをWindows版にしても、拡張機能からはあたかもLinux版がそのまま動いているかのように扱えるわけです。

WSL2での開発のためのセットアップ

前置きが長くなりましたが、ここからPico拡張機能をWSL2で利用するための具体的な手順について説明します。

WSL2をミラーモードに設定

まずはWSL2環境とWindows環境のネットワークを透過に扱うために、WSL2をミラーモードに設定します。

Windowsのスタートメニューから すべて > WSL Settings > ネットワーク を選択して、「ネットワークモード」を Mirrored にします。

拡張機能のインストール

VSCodeのRaspberry Pi Pico拡張機能を「WSL2側に」インストールします。
既にWindows側でのインストールが行われていると途中の設定でWindows側のパスが出てきたりして上手く行かないことがあったので、まずWindows/WSL2両方からPico拡張機能を削除されているのを確認してから始めた方が良いです。
(拡張機能削除後は、一旦VSCodeを終了させて再起動してください)

VSCodeを起動して、左下の「リモートウィンドウを開く」で「WSLへの接続」を行います。

この状態で拡張機能から「Raspberry Pi Pico」を検索して、WSL側に対してインストールを行います

SDKやツール類のインストールは、初回のプロジェクト生成時に行われます。
サイドバーからRaspberry Pi Picoアイコンを選択して、メニューの「New Project From Example」を選択します。

適当なプロジェクト名 (ここでは blink (LEDチカチカ) にしました) とボード種別、ソースコードの置き場を指定して、「Create」でSDK、ツール等のインストールが始まります。

ここでおすすめ拡張機能として 'Serial Monitor' 拡張機能をインストールするかを聞いてくることがあるので、一旦インストールします。

拡張機能を見ると、ローカル(Windows側)とWSL側の両方にSerial Monitorがインストールされていますが、WSL側をアンインストールします。
WSL側にこの拡張機能があるとWSLから見たシリアルポート(/dev/ttySxなど)を見に行ってしまうのですが、削除することでローカル側の機能が有効となり、WindowsのCOMポートに接続できるようになります。

openocd, picotool の差し替え

拡張機能のインストールが完了すると、ユーザのホームディレクトリに .pico-sdk というディレクトリが作られて、その中にツール類がインストールされます。この中の openocd と picotoolをWindows版と差し替えます。

$ ls ~/.pico-sdk
cmake  examples  ninja  openocd  picotool  sdk  toolchain  tools

ここでインストールされるファイルは、拡張機能が持っているURLのリストから取得されたファイルを展開したものです。
拡張機能本体は、Linux版VSCodeの場合は ~/.vscode-server/extensions/raspberry-pi.raspberry-pi-pico-<バージョン番号> に置かれています。この中の data/<バージョン番号>/github-cache.json というファイルにURLがあるので、openocdとpicotoolについて該当するファイルを探します。
執筆時点(2025年12月)では以下のようになっています。

• openocd

      {
        "id": 184737292,
        "name": "openocd-0.12.0+dev-aarch64-lin.tar.gz",
        "browser_download_url": "https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/openocd-0.12.0%2Bdev-aarch64-lin.tar.gz"
      },
      {
        "id": 184736619,
        "name": "openocd-0.12.0+dev-arm64-mac.zip",
        "browser_download_url": "https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/openocd-0.12.0%2Bdev-arm64-mac.zip"
      },
      {
        "id": 184739207,
        "name": "openocd-0.12.0+dev-x64-win.zip",
        "browser_download_url": "https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/openocd-0.12.0%2Bdev-x64-win.zip"
      },
      {
        "id": 184736698,
        "name": "openocd-0.12.0+dev-x86_64-lin.tar.gz",
        "browser_download_url": "https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/openocd-0.12.0%2Bdev-x86_64-lin.tar.gz"
      },

• picotool

      {
        "id": 184737290,
        "name": "picotool-2.0.0-aarch64-lin.tar.gz",
        "browser_download_url": "https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/picotool-2.0.0-aarch64-lin.tar.gz"
      },
      {
        "id": 184736618,
        "name": "picotool-2.0.0-mac.zip",
        "browser_download_url": "https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/picotool-2.0.0-mac.zip"
      },
      {
        "id": 184739208,
        "name": "picotool-2.0.0-x64-win.zip",
        "browser_download_url": "https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/picotool-2.0.0-x64-win.zip"
      },
      {
        "id": 184736697,
        "name": "picotool-2.0.0-x86_64-lin.tar.gz",
        "browser_download_url": "https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/picotool-2.0.0-x86_64-lin.tar.gz"
      }

この中で、x64-winがWindows版のアーカイブなので、これらをダウンロードします。
2025年12月時点では以下のファイルとなります。

• https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/openocd-0.12.0%2Bdev-x64-win.zip
• https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/picotool-2.0.0-x64-win.zip

$ wget https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/openocd-0.12.0+dev-x64-win.zip

$ wget https://github.com/raspberrypi/pico-sdk-tools/releases/download/v1.5.1-0/picotool-2.0.0-x64-win.zip

取得したzipファイルをそれぞれ展開しますが、元からインストールされているLinux版のファイルと同じ位置に展開されるようにディレクトリを作って、その中に展開します。
(元のファイルは-linuxの付いたディレクトリ名に変更して残してあります)

• openocd

$ cd ~/.pico-sdk/openocd/
$ ls
0.12.0+dev
$ mv 0.12.0+dev 0.12.0+dev-linux
$ mkdir 0.12.0+dev
$ cd 0.12.0+dev
$ unzip ~/openocd-0.12.0+dev-x64-win.zip
Archive:  /home/nakamura/openocd-0.12.0+dev-x64-win.zip
  inflating: libhidapi-0.dll
     : (中略)
  inflating: scripts/board/xtensa-rt685-ext.cfg
  inflating: scripts/board/gti/espressobin.cfg
$

• picotool

$ cd ~/.pico-sdk/picotool/
$ ls
2.2.0-a4
$ mv 2.2.0-a4 2.2.0-a4-linux
$ mkdir 2.2.0-a4
$ cd 2.2.0-a4
$ unzip ~/picotool-2.0.0-x64-win.zip
Archive:  /home/nakamura/picotool-2.0.0-x64-win.zip
  inflating: .keep
   creating: picotool/
  inflating: picotool/libusb-1.0.dll
  inflating: picotool/picotool.exe
  inflating: picotool/picotoolConfig.cmake
  inflating: picotool/picotoolConfigVersion.cmake
  inflating: picotool/picotoolTargets-release.cmake
  inflating: picotool/picotoolTargets.cmake
  inflating: picotool/rp2350_otp_contents.json
  inflating: picotool/xip_ram_perms.elf
$

picotoolについては更に追加の作業として、picotool.exe に対して picotool からシンボリックリンクを張っておきます。Pico拡張機能がLinux上で動作しているときはpicotoolをpicotool、Windows上の場合はpicotool.exeというファイルを実行しようとするためです。
(openocdは環境に関係なくopenocd.exeを実行するようになっていて、逆にLinux版には最初からopenocd→openocd.exeのシンボリックリンクが張られています)

$ cd ~/.pico-sdk/picotool/2.2.0-a4/picotool/
$ ln -s picotool.exe picotool

.bashrcへのパスの追加 (オプション)

拡張機能によってArmとRISC-Vのクロスコンパイラがインストールされるので、.bashrcに以下の記述を追加しておくと、bashのコマンドラインからもこれらのクロスコンパイラが使えるようになって便利です。

for f in .pico-sdk/toolchain/*/bin;do export PATH=${PATH}:$f;done

動作確認

プログラムの書き込み (SWD, USB)

これでWSLからPico拡張機能を使うための準備が出来ました。
既にblinkのソースコードが展開されているので、それを開いてサイドバーから「Flash Project (SWD)」を選択すると、ファイルをコンパイルしてPico Debug Probeから書き込まれているのを確認できます。

「Run Project (USB)」ではpicotoolを用いた書き込みが行えます。実行前にBOOTSELボタンを押しながらPicoをリセット(再接続)して、ファームウェア書き込みモードにしておいてください。

デバッグ

「Debug Project」ではPico Debug Probeを用いたデバッグが出来るはずなのですが、拡張機能の中からopenocdを立ち上げるやり方だとなぜかエラーが出て上手く行かないので、別途立ち上げたopenocdに拡張機能から接続するようにしてみます。以下のスクリプトを openocd-pico という名前で用意しておくと、インストールされたopenocdをターミナルから立ち上げることができるようになります。

openocd-pico

#!/bin/sh
OPENOCDDIR=$(dirname `find ~/.pico-sdk/openocd -name \*.exe -type f`)
${OPENOCDDIR}/openocd.exe -s ${OPENOCDDIR}/scripts -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000"

このコマンドをターミナルから実行してある状態で、VSCodeのPicoサイドバーから「Debug Project」を選択します。Pico Debugについての選択肢が出てくるので、「external OpenOCD」の方を選択すると、先ほど立ち上げたopenocdを用いてデバッグセッションを開始します。

シリアルコンソール接続

hello_serial のようなシリアルコンソールを用いるアプリでは、VSCodeからその出力を確認できます。
Serial Monitor拡張機能がインストールされているとターミナルに「シリアルモニター」というタブが追加されるので、ここでポートにPico Debug ProbeのCOMポートを選択し、「監視の開始」を実行するとシリアルコンソールからの出力が得られます。

まとめ

多少強引な手段でしたが、これでWSL2環境でもPico拡張機能によるRaspberry Pi Pico開発ができるようになりました。
将来、拡張機能の方でWSL2環境も正式にサポートしてくれると嬉しいですね。