電子工作とプログラミング

Visual Studio Code と Arduino-cli

okiraku-camera

概要

前回の投稿では、pio-usb-hoboNicola アダプター用のファームウェア ( hoboNicola) をビルドするために Arduino IDE 1.8.19を構成した。今回は発展形として Microsoft の Visual Studio Code (以下、VSCode) と arduino-cli の構成方法を中心に、ファームウェアのビルドとXIAO RP2040への書込み方法について記す。

VSCodeやarduino-cli を導入した後も Arduino IDE 1.8 はふつうに使える。

開発用ソフトウェアの導入

aruduino-cli

Arduino-cli は Arduino IDEのもつ機能を備えたコマンドラインツールで、Arduino公式により Arduino IDE 2.xx のエンジン部分として用意された。詳しくは https://arduino.github.io/arduino-cli/1.3/ を参照のこと ( 現バージョンは 1.4だが、ドキュメントページは 1.3だった）。

Visual Studio Codeは、Arduino スケッチのビルドやボードへの書込みに際して従来の Arduino IDE (1.8) の機能、または、arduino-cli を使う。どちらを使うかは設定時に選択できる。新しく導入するのであれば、より新しい arduino-cli 一択だろう。

ダウンロードとインストール

https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_64bit.zip  から Windows 64ビット版のarduino-cli.exe を含む zipファイルをダウンロードし、適当なディレクトリに展開する。今回は、C:\tools\arduino-cli というディレクトリを作って配置した。これを書いている時点では、2025年12月にリリースされたバージョン 1.4.0 が入手できた。

環境変数 PATH の設定

arduino-cli.exe を配置するディレクトリは Windowsのシステム環境変数の PATH に追加しておく。今回は  C:\tools\arduino-cli を追加。これによりコマンドプロンプトや VSCodeターミナルからパス名無しで arduino-cli.exe が実行できるようになる。

環境変数
環境変数

環境変数の設定ダイアログは、Windows11の設定ホーム画面 (Win + I) において、環境変数 と入力して見つける。

arduino-cli の実行

WindowsのコマンドプロンプトやPower Shell を開き、以下を入力して実行し、実行できることを確認する。

arduino-cli version

実行できないとすれば、環境変数 PATH の設定違いが考えられる。 正しく実行できると以下のようにバージョン番号とリリースした日時が表示されるだろう。

C:\tools>arduino-cli version
arduino-cli Version: 1.4.0 Commit: b7000970f Date: 2025-12-09T15:56:10Z

この時点で、Arduino IDEのローカルディレクトリ ( C:\Users\<ユーザー名>\AppData\Local\Arduino15 ) の中に  inventory.yaml というファイルが作成される。Arduino IDE と同じディレクトリ %LOCALAPPDATA%\Arduino15 が暗黙で使われるわけである。このファイルは、arduino-cli がそれ自体の都合で作成するファイルであり内容について気にかける必要はない。削除しておいても、次回実行時に作成される。

arduino-cli.yaml の作成

次に以下のコマンドを実行する。

arduino-cli config init --dest-dir %LOCALAPPDATA%\Arduino15

これにより、Arduinoが使うディレクトリ内に arduino-cli.yaml という arduino-cli用の設定ファイル が作成される。当初の内容は以下の2行だけだった。

board_manager:
    additional_urls: []

Arduino IDEから移行し共用しようとする場合、このファイルに対して項目を一つ追加してやる必要がある。

なお、yaml ( ヤメル ) 形式のファイルはただのテキストファイルなので、編集はWindowsのメモ帳 (notepad.exe) を使うのでいいだろう。ただ、インデントにはTabコードではなく半角空白を用いること、 キー文字列:  (コロン記号) のあとに空白が必須なことなどに注意。

追加する項目

Arduiono IDEで使っていたスケッチ用のベースディレクトリ (ここでは C:\Arduino ) を追加する。

directories:
    user: c:\Arduino

Arduino IDEと同様に、ベースディレクトリを指定すれば、ライブラリのディレクトリ (libraries) もその直下にあることになる。

項目を追加した場合、以下を実行することで正しく設定されているか確認できる。

arduino-cli config dump

何か誤りがあると、その旨を表すメッセージが表示される。

arduino-cli.yaml に設定できる項目は他にも数多くあるのだが、Arduino IDE用に構成した標準的なディレクトリ構成を引き継ぐ場合、スケッチ用のベースディレクトリさえ設定してあれば、各ディレクトリのデフォルト値が同じなのでビルドや書込みには支障がない。その他の設定可能な項目についてはドキュメントを参照のこと。

Visual Studio Code のインストール

VSCode 公式サイト ( https://code.visualstudio.com/ ) からインストール用プログラム ( VSCodeUserSetup-x64-x.xxx.x.exe ) をダウンロードし実行してインストールする。VSCodeの実行ファイルを置く場所は、デフォルトのインストール先でもよいし  C:\tools\vscode などでもよい。

インストール直後に実行すると、おおむね以下のようなウィンドウが開く。

VSCode にようこそ
VSCode にようこそ

AI エージェントとチャットするためのパネルも表示され AIの利用 を促されるが、余計なことをされても困るので、閉じることにしている。

なお、インストールの過程でWindowsのシステム環境変数 PATH にインストール先のパス名が追加される。

日本語化

VSCode アクティビティバー
VSCode アクティビティバー

VSCodeを起動後、左側のアクティビティバーの中から拡張機能アイコン（上図では、一番したの四角が4つのアイコン）をクリックすると拡張機能用のサイドバーが現れ、その上部に検索用のフィールドがある。ここに Japanese Language Pack と入力して検索する。

すると Microsoftが提供する Japanese Language Pack for Visual Studio Code   という項目が表示されるのでこれをインストールする。インストールが終わると 言語を切り替えてVSCodeを再起動するか？ という問い合わせがあるので Yes とする。再起動後、UIが日本語になっているはず。

Arduino for Visual Studio Code (vscode-arduino)

VSCodeでArduinoの開発やビルドを行うための拡張機能として、vscode-arduino を導入する。

vscode-arduinoは、Arduinoスケッチの開発・ビルド・書込みを行うための拡張機能で、Arduino IDEの機能を VSCode に統合する。Arduino IDE のもつすべての機能と、VSCodeのもつリッチな編集機能やGitを使ったリビジョン管理が可能になる。

vscode-arduino は当初 Microsoft が提供していたが、2024 年ごろに公開された 0.6.0 版をもって deprecated (非推奨) となった。
(参考: https://github.com/microsoft/vscode-arduino )
その後、この拡張機能のリポジトリはコミュニティ有志によってフォークされ https://github.com/vscode-arduino/vscode-arduino として開発が継続されている。現在の最新版は 0.7.1。

vscode-arduino のインストール

やはり左側のアクティビティバー内の拡張機能アイコンをクリックし Arduino Community Edition (vscode-arduino )を検索してインストールする。

vscode-arduinoを導入すると、この拡張機能が依存するMicrosoftの C/C++ と Serial Monitor (シリアルモニター)も追加される。拡張機能の内容は以下のようになる。

vscode-arduino
vscode-arduino

インストールできたら設定を行う。

vscode-arduino の設定

アクティビティバー内の拡張機能アイコンをクリックし vscode-arduino を選び、歯車アイコンをクリックして出てくるメニューから 設定 を選択する。

VSCodeの設定
VSCodeの設定

以下のよう設定項目が表示される。

vscode-arduino 設定
vscode-arduino 設定

設定すべき項目

16項目の設定があるのだが、以下の項目を確認／設定すればよいだろう。

  • Arduino: Clear Output On Build
    チェックを推奨。(ビルド時に出力パネルがクリアされるはず)。
  • Arduino: Command Path
    空欄のまま
  • Arduino: Log Level
    verbose を推奨
  • Arduino: Path
    C:\tools\arduino-cli\   (arduino-cliのパスを入力)
  • Arduino: Use Arduino Cli
    チェックする

settings.json

なお、上記の設定の内容は、%APPDATA%\Code\User\settings.json に記録されており、以下のような内容になる。

{
    "arduino.useArduinoCli": true,
    "arduino.clearOutputOnBuild": true,
    "arduino.logLevel": "verbose",
    "arduino.path": "C:\\tools\\arduino-cli\\",
}

このファイルには、vscode-arduino だけではなくVSCode本体や拡張機能に対して行った設定内容が記録される。

Arduino IDEやarduino-cliの設定ファイルは %LOCALAPPDATA%\Arduino15  ディレクトリを使うが、VSCodeは %APPDATA%\Code を使う。%APPDATA% は C:\Users\<ユーザー名>\AppData\Roaming をもつ環境変数。

スケッチのビルド

ここまでの設定で、Arduino スケッチをビルドする準備がおおむね整った。VSCode のファイルメニュー／フォルダを開く にて、Arduino IDEで使った rp_hobo_nicola を開く。ino ファイルではなく、inoファイルを含むディレクトリ (ここでは C:\Arduino\rp_hobo_nicola ) を選択する。

そして、アクティビティバーの エクスプローラー (一番上の、クリップボードのようなアイコン )を選択すると、エディター内に rp_hobo_nicola.ino が表示される。

VSCode エディター
VSCode エディター

この時点では、上図のようにエラーを表す赤い波線が表示されるが、気にする必要はない。

ビルドのやり方と準備

表示メニュー／コマンドパレットを選択し、検索フィールドに Arduino と入力する。すると、vscode-arduino のためのコマンドのリストが表示される。Arduino 関係で何かやらせようとするときはこのリストの中から選択する。

コマンドパレット Arduino
コマンドパレット Arduino

ビルド (コンパイル) するためには、 Arduino: Verify を選択するか、このコマンドのショートカットの Ctrl + Alt + R キーを押す。 これは、Arduino IDEでの 検証・コンパイル と同じ意味をもつ。

この時点では、ターゲットのマイコンやボードを指定していないので、以下のようなエラーメッセージが表示されるだろう。

VSCode Arduino
VSCode Arduino

ターゲットボードの選択

ビルドの対象のマイコンやボードを選択するためには、コマンドパレットから Arduino: Change Board Type を選択するか、ステータスバーに表示されている <Select Board Type> をクリックする　(上図参照) 。

前者の場合、以下のようにボード名がずらっと表示される。ここからターゲットとするボード名 (Seeed XIAO RP2040) を選択する。

VSCode Change Board Type
VSCode Change Board Type

選択したボード名 ( Seeed XIAO RP2040 ) は、ステータスバーの <Select Board Type>  の代わりに表示される。ステータスバーの <Select Board Type> をクリックした場合も、表示形式は異なるものの表示されたボードリストから選択することになる。

ビルドパラメータの設定

ボードを選択したらそのボード用のビルドパラメータを設定する。コマンドパレットから Arduino: Board Config を選択するか、ステータスバーのボード名をクリックする。いずれの場合も以下のようにエディターの領域が分割されビルドパラメータの設定が可能となる。

VSCode Board Config
VSCode Board Config

初期値から変更する内容は Arduino IDEのときと同じで以下のとおり。

  • CPU Speed: 120MHz
  • USB Stack: Adafruit TinyUSB

ここまでの設定により、rp_hobo_nicolaのビルドの準備は完了なので、Arduino: Verfy ( あるいは Ctrl + Alt + R ) によってビルドを実行。

VSCode 出力パネル
VSCode 出力パネル

ビルドを開始すると、上図のように出力パネルに各種の情報が非表示される。先頭には以下のような表示が出てくるだろう。

[Starting] Verifying sketch 'rp_hobo_nicola.ino'
[Warning] Output path is not specified. Unable to reuse previously compiled files. Build will be slower. See README.

Warning となっている出力パス (Output Path) の指定については後述する。

初回なので少々時間がかかるが、出力パネルに以下のように表示されてビルドは完了する。

VSCode 出力パネル
VSCode 出力パネル

文字化けが… これについても後述する。

メインスケッチの指定が必要なこともある

rp_hobo_nicolaではスケッチのディレクトリの中に メインスケッチの rp_hobo_nicola.ino しかないのでよいのだが、複数の ino ファイルがあるような場合、コマンドパレットから Arduino: Select Sketch  を選択し、メインスケッチを指定しておく必要がある。

.vscode ディレクトリと arduino.json

ビルドを実行すると、vscode-arduino によりスケッチのディレクトリ内に .vscode というディレクトリが作られ、その中に arduino.json というファイルが作られる。これらには以下のような役割がある。

  • .vscode
    プロジェクトごとの VSCode にかかわる設定をまとめて管理するディレクトリ。
  • arduino.json
    現在のスケッチについてのビルド用の情報を記憶するファイル。

arduino.json に出力パスを指定

一つのスケッチからビルドを行うときにも、コアパッケージやライブラリファイルなど数多くのソースファイルのコンパイルが行われ、必要なファイルがリンクされてビルドが完了する。

プログラムを更新するとき、自分が書いているスケッチ以外はほぼ変更がない。前回ビルド時の中間ファイル (コンパイルによって生成されるオブジェクトファイル) が残っていれば、それらを再利用することで再度のコンパイルを避けることができるのでビルド時間を大幅に短縮できる。

Arduino IDE 1.8 ではスケッチごとのビルドディレクトリが指定できなかったのに対し、arduino-cli ではスケッチごとに指定できるため、各スケッチごとの中間ファイルを安全に保管し再利用できる。

arduino.json に “output”: “./build” という1行を追加すればよい。この指定を行った次回のビルド時に、スケッチディレクトリに build というディレクトリが作成され、その中に中間ファイルやリンク済のファームウェア (.UF2) が作られる。

rp_hobo_nicola用の arduino.json は以下のようになるだろう。

{
    "configuration": "flash=2097152_0,freq=120,opt=Small,rtti=Disabled,stackprotect=Disabled,exceptions=Disabled,dbgport=Disabled,dbglvl=None,usbstack=tinyusb,ipbtstack=ipv4only,uploadmethod=default",
    "board": "rp2040:rp2040:seeed_xiao_rp2040",
    "sketch": "rp_hobo_nicola.ino",
    "output": "./build"
}

リリース時はビルドディレクトリを削除してから

常識的な事がらとして、リリース版を作るようなときは build ディレクトリ自体を削除した状態から再ビルドするのがよいだろう。ライブラリだったり開発ツールだったりを更新していることを忘れているのはよくあること。

出力パスを指定しなかったとき

arduino.json に出力パスを指定しなかった場合、vscode-arduinoは　%LOCALAPPDATA%\arduino\sketched\xxxxxxxx というディレクトリを使う。最後の xxxxxxxx と表現した要素は 32バイトの英数字で構成されるユニークな文字列が入る。どのような値になるかは分からないので、ディレクトリの作成タイムスタンプなどで見分けている。Arduino IDEのときと同様にディレクトリの所在が分かりにくいので、出力パスの指定は必須と思う。

出力パネルの文字化け対策

これは vscode-arduino が登場したときから生じている有名な障害で、UTF-8 ではなくShift_JISコードで漢字やかなを出力しているためである。

VSCode の一部を修正する

vscode-arduinoに含まれているjavascriptファイル (*.js) の内容を変更する。C:\Users\<ユーザー名>\.vscode\extensions\vscode-arduino.vscode-arduino-community-0.7.2-win32-x64\out\src\common\util.js  をエディタで開き、209行目にある function spawn(command, ….) に注目する。行番号は日本語拡張パッケージのバージョンによって異なることに注意。

文字化けを引き起こしているのは、この関数の中の、以下の部分になる。

if (os.platform() === "win32") {
  codepage = getArduinoL4jCodepage(command.replace(/.exe$/i, ".l4j.ini"));
  if (!codepage) {
      try {
          const chcp = child_process.execSync("chcp.com");
          codepage = chcp.toString().split(":").pop().trim();
      }
      catch (error) {
         outputChannel_1.arduinoChannel.warning(`Defaulting to code page 850 because chcp.com failed.\
          \rEnsure your path includes %SystemRoot%\\system32\r${error.message}`);
         codepage = "850";
      }
   }
}

getArduinoL4jCodepage(command.replace(/.exe$/i, “.l4j.ini”)); によって、実行中の Arduino.exe の拡張子を l4j.ini に変更し、そのファイル内に含まれているはずの エンコーディング設定を取得しようとしている。しかしながら現在の環境にはそのようなファイルはないので、戻り値の codepage はおそらく値を持たない。!codepage が真なので chcp.com を実行して実行環境のコードページを得ているが、codepage の内容は日本語の Windows環境では Shift_JIS を表す 932 となる。

上記のコードブロックでは、わざわざ無駄なことをして文字化けを起こしているわけである。引用したブロックの直上で正解の let codepage = “65001”;  としているのにもったいない。

対策として、上に引用したブロックをすっかりコメント化してしまう。コメント化した内容を引用すると、以下のようになる。

...
let codepage = "65001";
/**
if (os.platform() === "win32") {
  codepage = getArduinoL4jCodepage(command.replace(/.exe$/i, ".l4j.ini"));
  if (!codepage) {
      try {
          const chcp = child_process.execSync("chcp.com");
          codepage = chcp.toString().split(":").pop().trim();
      }
      catch (error) {
          outputChannel_1.arduinoChannel.warning(`Defaulting to code page 850 because chcp.com failed.\
          \rEnsure your path includes %SystemRoot%\\system32\r${error.message}`);
          codepage = "850";
      }
  }
}
*/
if (output) {
    ...

この修正を加え VSCodeを再起動してからビルドすると、出力パネルの文字化けは消えて以下のようになる。

文字化けのない出力パネル
文字化けのない出力パネル

ビルド結果の書込み

さて、コマンドパレットの Arduino: Verify を選択するか、ショートカットの Ctrl + Alt + R キー の押下によって開始したビルドが成功すると、arduino.json の 出力パス (output: ) で指定したディレクトリの中に、マイコンに書き込むファームウェアファイル (.uf2) が出来上がる。

書込みの方法

vscode-arduinoやArduino IDEでは、USBケーブルでPCとRP2040のマイコンボードと接続し、USBシリアルポート経由でUF2ファイルを送り込むことができる。今回は、この方法を選択する。

(USB)シリアルポートの選択

(更新中)

BOOTSEL / RESET による書込みについて

なお、(USB)シリアルポートを使った書込み方法は、マイコンボード側のプログラムがUSBシリアルのためのCDCプロトコルを有効にしているときにのみ利用できる。マイコン側でCDCを無効にしているときは、RP2040のBOOTSEL機能とリセット操作によってブートローダーモードとする。

このモードでは、RP2040自体が「USBマスストレージ（USBメモリ）」として振る舞うための USBスタック を起動するので、PCからは新しいドライブができたように見える。このドライブのルートフォルダにUF2ファイルをドロップすることで、ファームウェアが更新される。

たとえばRP2040を使ったキーボードでは、BOOTSEL(BSEL)スイッチをもつものが多い。リセットについては、USBケーブルの抜き差しで代用できるので、スイッチを省略できる。