Arduino CLI Wrapper (VS Code 拡張機能)

English README

Arduino CLI を VS Code から「コマンドパレット」「ステータスバー」「エクスプローラー」から操作できます。カラー付きの疑似ターミナルにログを集約し、sketch.yaml のプロファイルに対応、ビルド中に IntelliSense の includePath を自動更新します。

エクスプローラービューからスケッチやプロファイル、各種操作をワンクリックで実行できます。

コンセプト

この拡張機能は、Arduino IDE の内部で呼び出されている Arduino CLI を VS Code から直接扱えるようにし、IDE と同等以上の操作性を目指しています。Arduino CLI が備えるプロファイル機能を活用すると、sketch.yaml にプラットフォームやライブラリのバージョンを明示してプロジェクトごとに切り替え管理できます。IDE では複数バージョンの使い分けが難しかった部分ですが、拡張機能では編集ヘルパーや最新バージョンとの差分チェックを通じて初心者でも簡単に扱えます。

エディタとして VS Code を活用しているため、マイクロソフト製 C/C++ 拡張機能と連携し、ビルド結果を IntelliSense や診断情報（エラー・警告）へ即座に反映します。生成される compile_commands.json も常に最新の状態に保たれ、強力な C/C++ コーディング支援を受けられます。また、Arduino IDE の既定が none となっているワーニング設定に対し、ワークスペース内のファイルだけを対象にする独自の「workspace (all*)」モードを追加し、ノイズの多い外部ライブラリの警告を抑制します。

さらに ESP32 向けの data/ フォルダー書き込み機能や、map ファイルなどを解析する Inspector など IDE にはないユーティリティも搭載。Arduino CLI をこれから学ぶ人にも、プロフェッショナルな開発フローを求める人にも便利な環境を提供します。

クイックスタート

Arduino CLI の準備

PATH に通すか、設定 arduino-cli-wrapper.path に実行ファイルのフルパスを指定。
「Arduino CLI: Check CLI Version」で認識確認（未設定ならガイドを表示）。
- Windows: インストーラー https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_64bit.msi または winget install ArduinoSA.CLI
- Linux: curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/.local/bin sh
- macOS: brew update && brew install arduino-cli
  - その他のインストール方法は公式ドキュメント https://arduino.github.io/arduino-cli/latest/installation/ を参照してください。
推奨 VS Code 拡張機能

この拡張機能は extensionPack で以下の VS Code 拡張機能を推奨しています。開発体験を高めるため、用途に応じてインストールしてください。
- C/C++ (ms-vscode.cpptools) – IntelliSense、コード補完、既定の cppdbg デバッガーなど、C/C++ 言語を扱うのに必須となる基本機能を提供します。Arduino CLI Wrapper を使う場合は常に導入しておくことをおすすめします。
- Cortex-Debug (marus25.cortex-debug) – レジスタやペリフェラルビュー、メモリマップ表示など高度なハードウェアデバッグ機能を備えています。本格的なデバッグを行う場合に導入してください。簡易的なデバッグしか行わない、あるいはデバッグ機能を使わない場合は必須ではありません。

スケッチフォルダーを開く

.ino を含むフォルダーを開くと、Compile/Upload/Monitor と FQBN/Port/Baud/Warn がステータスバーに表示されます。

コンパイル / 書き込み / モニタ

コンパイル: 「Arduino CLI: Compile Sketch」または Compile をクリック。
書き込み: 「Arduino CLI: Upload Sketch」または Upload をクリック。先にポートを選択してください（プロファイル使用時でも -p で明示指定）。
モニタ: 「Arduino CLI: Monitor Serial」または Monitor をクリック。ボーレートは既定 115200、ステータスバーから変更できます。
- シリアルプロッターが必要な場合は、VS Code の Teleplot などお好みの拡張機能をご利用ください。

ヒント:

.ino が複数あるときは選択ダイアログが出ます。アクティブな .ino エディターがあれば優先されます。
FQBN を自動取得できない場合は手入力できます。

`arduino_secrets.h` の管理

.ino ファイルに #include "arduino_secrets.h" が含まれている場合、インクルード行の上にインラインアクションを表示します。既存ファイルがあればワンクリックで開き、未作成ならフォールバックの #define 行を抽出して初期値付きのヘッダーを生成するため、Wi-Fi 認証情報などをソース本体から容易に切り離せます。

WSL を使ったビルド高速化ガイド

Windows 上で Arduino CLI のコンパイルが遅いときは、WSL (Windows Subsystem for Linux) に Linux 環境を作り、ビルドだけを高速な Linux 上で行う構成が便利です。この拡張機能はコンパイル時に WSL 側の arduino-cli を利用しつつ、Upload / Monitor だけを Windows ネイティブの arduino-cli.exe に自動で切り替えるため、シリアルポート設定を二重管理する必要がありません。手順は次のとおりです。

WSL と Linux ディストリビューションをインストール
```
# PowerShell (管理者) で実行
wsl --update
wsl --install -d Ubuntu-24.04
wsl --set-default-version 2
```
インストール後、初回起動でユーザー名とパスワードを設定します。既に WSL を利用している場合はこのステップをスキップできます。

WSL 内に Arduino CLI をセットアップ

# WSL (Ubuntu) ターミナル内
sudo apt update
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/.local/bin sh
arduino-cli config init
arduino-cli update

arduino-cli version コマンドでインストールが完了しているか確認してください。

VS Code から WSL リモートへ接続
- VS Code のコマンドパレットから “Remote-WSL: 新しいウィンドウで開く” を選び、Ubuntu 環境を開きます。
- この拡張機能を WSL 側にもインストールします (初回起動時に VS Code から確認ダイアログが出ます)。
- 設定 arduino-cli-wrapper.path が空の場合は、WSL の arduino-cli を自動検出して利用します。明示的に指定したい場合は arduino-cli のフルパス (/usr/local/bin/arduino-cli など) を入力してください。
WSL 上でビルドする
- WSL 上のワークスペースで .ino を含むフォルダーを開きます。
- 「Arduino CLI: Compile Sketch」を実行すると、WSL の arduino-cli が使用されます。ビルド成果物は Linux のファイルシステム上 (例: /home/<user>/.arduino15/...) に作成されます。
アップロード / モニタは Windows 側を自動利用
- この拡張機能は WSL 環境でも、Upload / Monitor コマンドを実行すると自動的に Windows 側の arduino-cli.exe を起動し、COM ポートへ直接接続します。WSL でシリアルポートを設定する必要はありません。
Upload Data / Debug の注意点
- Upload Data は WSL からでも Windows の COM ポートへ書き込めるようになりました。WSL 内でファイルシステムイメージを生成しつつ、Windows 側では自動的に arduino-cli.exe --show-properties と esptool.exe を呼び出して転送するため、usbipd でのデバイス転送は不要です（arduino-cli.exe が Windows の PATH に含まれていることだけ確認してください）。
- Arduino CLI: Debug は依然として WSL から Windows ホストのシリアルポートへ接続できません。usbipd-win でデバイスを /dev/tty* として認識させるか、Windows 側の VS Code / Arduino CLI で Debug を実行してください。
トラブルシューティング
- Latest arduino-cli: (unknown) と表示された場合、GitHub API のレート制限に引っかかっています。GITHUB_TOKEN を VS Code の環境変数に設定するか、しばらく時間を空けて再試行してください。
- COM ポートが表示されないときは、Windows 側でボードが正しく認識されているか (デバイスマネージャー) を確認し、必要であればドライバーを再インストールしてください。

これらの手順を踏むことで、コンパイルは WSL の高速な Linux 環境で実行しつつ、アップロードとシリアルモニターは Windows から直接行うハイブリッド運用が可能になります。

上級者向けカスタマイズ

オプション: `.arduino-cli-flags`（本拡張機能専用）

コンパイル毎に追加の build.extra_flags を自動注入する必要がある場合のみ、スケッチと同じフォルダーに .arduino-cli-flags を置けます。この仕組みは Arduino CLI Wrapper 専用で、他の IDE や拡張機能からは一切認識されません。まずは arduino_secrets.h など汎用的な方法で管理し、それでも不足するケースに限って利用する上級者向けのエスケープ手段として扱ってください。

1 行につき 1 個のフラグを書きます（例: -DWIFI_SSID="MySSID"）。
# または // で始まる行と空行は無視されます。
有効な行はスペース区切りで連結され、--build-property build.extra_flags=... として渡されます。
既に設定、タスク、コマンドパレットなどで build.extra_flags を指定している場合はそちらが優先され、ファイルは読み込まれません。

ドットから始まるファイル名のため既定では隠しファイルとして扱われます。認証情報がコミットに含まれないよう、必要に応じて .gitignore へ追加してください（本拡張の .gitignore には既にエントリを用意済みです）。

また、ビルド環境のタイムゾーンをコードから参照できるよう、拡張機能は既定でビルド時に次のプリプロセッサーマクロを build.extra_flags へ追加します。必要に応じて設定 Arduino CLI Wrapper › Inject Timezone Macros を無効化すると自動付与を停止できます。

CLI_BUILD_TZ_IANA – Asia/Tokyo のような IANA タイムゾーン ID。
CLI_BUILD_TZ_POSIX – newlib の TZ 変数へ設定できる POSIX 形式（例: JST-9 や PST8PDT,M3.2.0/2,M11.1.0/2）。
CLI_BUILD_TZ_OFFSET_SEC – 現在の UTC オフセット（秒）。
CLI_BUILD_TZ_OFFSET_ISO – +09:00 形式の ISO ライクなオフセット文字列。
CLI_BUILD_TZ_ABBR – JST や PST/PDT など画面表示向けの略称。

日常操作と UI

コマンドパレットから始める（初心者ガイド）

Ctrl+Shift+P（macOS は Cmd+Shift+P）でコマンドパレットを開き、「Arduino CLI」と入力するとよく使うコマンドが並びます。主なものは次のとおりです。

Command Center を開く – コマンドの一覧タブ、arduino-cli config を扱う設定タブ、コア／ライブラリ管理タブ（インストール・更新・削除と絞り込み付き）を備えた Webview を開きます。拡張機能でできることを一度に俯瞰するのに最適です。
CLI バージョン確認 – arduino-cli がインストールされているかチェックします。未設定なら手順付きのガイドが表示されます。
インデックスを更新 (Update Index) – arduino-cli update でボード／ライブラリのインデックスを更新します。このコマンドは VS Code を起動して最初に CLI バージョンを確認したタイミングでも自動実行されます。
コア/ライブラリをアップグレード (Upgrade Cores/Libraries) – arduino-cli upgrade を実行し、インストール済みのプラットフォームやライブラリを最新化します。
Board Details – 現在選択中のプロファイル/FQBN の詳細情報を表示し、使用しているボード設定を再確認できます。
Compile Sketch / Clean Compile / Upload Sketch – 日常的なビルド／書き込みコマンドです。Clean Compile は --clean 付きで再ビルドし、IntelliSense の includePath を更新します。
Build Check – sketch.yaml 内の全プロファイルをまとめてビルドし、警告とエラーを一覧に集約します。
Debug Sketch – プロファイルごとのデバッグ設定を自動生成します（詳しくは「デバッグを始める（上級者向け）」を参照）。

ステータスバー

$(tools) Compile: 現在のフォルダー内の .ino をコンパイル
$(cloud-upload) Upload: 現在のフォルダー内の .ino を書き込み
$(pulse) Monitor: シリアルモニタを開く
$(circuit-board) <FQBN/Profile>:
- ステータスバー／コマンド／Arduino CLI ツリーで最後に選んだプロファイルを表示します。プロファイル未選択でも sketch.yaml が存在する場合は Profile: 未選択 を表示し、「Arduino CLI: Set Profile」で選択できます。sketch.yaml が無い場合は FQBN を表示し、「Arduino CLI: Set FQBN」で変更可能。
$(plug) <Port>: 現在のシリアルポート（クリックで変更）。JTAG/SWD/ISP などの書き込み装置で書き込む場合は 外部書き込み装置を使用 (JTAG/SWD/ISP など) を選ぶと、-p を付けずにアップロードできます。
$(watch) <Baud>: 現在のボーレート（クリックで変更）
$(megaphone) <Warnings>: 警告レベル/verbose のバッジ（クリックで組み合わせを選択）

.ino がないワークスペースではステータスバー項目は非表示です。FQBN/Port/Baud はワークスペースごとに保存され、再起動後も保持されます。

エクスプローラービュー

エクスプローラーに「Arduino CLI」ビューを追加。
スケッチフォルダーを一覧表示し、sketch.yaml があればプロファイルも表示。
プロジェクト/プロファイルごとのアクション: Compile / Upload / Debug / Upload Data / Monitor / Sketch.yaml Helper / Open Examples。
- Debug はプロファイルノードにのみ表示され、選択したプロファイル向けに自動生成された設定で即座にデバッグを開始できます。
先頭にグローバルアクション: Command Center / CLI Version / Sketch.yaml Helper / Open Inspector / Sketch.yaml Versions / Build Check / Refresh View / New Sketch。
スケッチ項目はワークスペースからの相対パスで表示され、ノードは既定で展開状態です。

ビルドとアップロードの基本

Compile Sketch – 選択したスケッチをビルドします。複数の .ino がある場合はダイアログで選べます。sketch.yaml があればプロファイルを自動で適用、ない場合は保存済みの FQBN を使います。
Clean Compile – --clean オプション付きでクリーンビルドを実行し、IntelliSense の includePath も初期化した上で再計算します。ライブラリを入れ替えた後に便利です。
ローカルビルドパス（設定） – 設定「Arduino CLI Wrapper › Local Build Path」を有効にすると --build-path を自動付与し、.build/<プロファイル> 配下にビルド成果物を保存します。Compile / Upload / Inspector などの出力をスケッチ内にまとめて管理できます。
Upload Sketch – コンパイルしてそのまま書き込みます。ポートが未設定ならその場で選択でき、必要に応じてシリアルモニタを自動で閉じたり再オープンしたりします。
OTA 書き込み（ネットワーク経由） – 選択したポートに IP アドレスが含まれる場合は OTA 転送とみなし、--upload-field password=$ARDUINO_CLI_OTA_PASSWORD を自動付与します。CLI 実行時に環境変数を展開します（パスワード不要なら未設定のままで問題ありません）。Arduino Logs には展開前の $ARDUINO_CLI_OTA_PASSWORD をそのまま表示し、平文のパスワードは残りません。
Build Check – sketch.yaml に定義したすべてのプロファイルを --warnings all でビルドし、警告とエラーの集計結果を表示します。リグレッションチェックに最適です。
wokwi で実行 – プロファイルに wokwi: true を設定すると、ビルド時に .wokwi/<profile>/wokwi.elf を出力し、ボードに合わせた初期値で diagram.json / wokwi.toml を補完したうえで、エクスプローラーに「wokwiで実行」アクションが現れ、公式 Wokwi 拡張機能で図面を開けます。

スケッチ管理とユーティリティ

スケッチ管理をラクにするツール

Sketch.yaml Helper – Web ビューでボード/プラットフォーム/ライブラリを確認しながら sketch.yaml を編集できます。手打ちが不安なときにおすすめです。
sketch.yaml バージョン確認 – 各プロファイルを最新の公開インデックスと照らし合わせ、アップデートがあればその場で提案します。
New Sketch – 新しいスケッチフォルダーを作成し、生成した .ino を開いてヘルパーも同時に起動します。ゼロから環境を整えるのにぴったりです。

Sketch.yaml Helper でボードやライブラリを GUI で編集できます。

現在のバージョンと公開版との差分を確認し、その場で更新できます。

サンプルを素早く探す

Browse Examples – インストール済みのコアやライブラリが提供するサンプルスケッチをツリー表示します。Arduino IDE と違い、開く前に内容をプレビューでき、ビュー上部のタブで .ino や README など同じフォルダー内のファイルを切り替えながら確認し、そのままフォルダー配下を丸ごとプロジェクトへコピーできます。
名前やフォルダーで絞り込み – クイックフィルターでファイル名・フォルダー名を入力すると、目的のサンプルだけを表示できます。
本文テキストでの検索 – 内蔵の grep モードに切り替えると、ソース内の文字列で絞り込めます（例: rgb と入力して RGB LED を扱うサンプルを一気に探す）。
ワンクリックで編集開始 – プレビューで内容を確認したら、そのままエディターで開いて自分のプロジェクト向けに書き換えられます。

サンプルのプレビューや文字列検索を VS Code 内で完結できます。

ツール連携と細かな操作

Monitor Serial – シリアルモニタを開き、ポートとボーレートを指定できます（既定は 115200）。ポートが使用中の場合は注意点も表示します。
Configure IntelliSense – ビルドを走らせずに .vscode/c_cpp_properties.json を再生成し、最新のコンパイルフラグをエディタに反映します。
Run Command – UI にないオプションを試したいときに、任意の引数を arduino-cli へ直接渡せます。
Inspector – ビルド後に生成される map ファイルやセクションサイズを解析し、メモリ使用量を一目で把握できます。クリーンビルドが必要なときは Clean build (--clean) チェックを有効にしてください。既定では OFF なので手早い確認では既存ビルドを再利用します。
ステータスバーのトグル – 警告レベル（none / workspace / default / more / all）と --verbose の ON/OFF をワンクリックで切替できます。バッジ表記（例: all+V）ですぐに状態が分かります。
Include Order Lint – .ino の中で M5GFX 系ヘッダーより前に FS 系ヘッダーを書いた場合に警告を表示し、実行時のトラブルを未然に防ぎます。

ローカルポート設定（ワークスペースごとにポートを固定したいとき）

コマンドパレットまたは Command Center／エクスプローラービュー上部の「Local Port Rules」からウィザードを開き、.vscode/arduino-cli-wrapper.json を GUI で編集できます。
ルールは上から順に評価され、sketch（ワークスペース相対パスの glob）と profile（プロファイル名の glob）のどちらかを指定、port は必須、baud は任意です。空欄のフィールドは保存時に省略されます。

例:

{
  "ports": [
    { "sketch": "temp/assetsTest/**", "profile": "*", "port": "COM7", "baud": 921600 },
    { "profile": "esp32-*", "port": "/dev/ttyACM0", "baud": 921600 },
    { "sketch": "temp/test/**", "port": "/dev/ttyUSB0" }
  ],
  "defaultBaud": 115200
}

既存の sketch.yaml に書かれた port/baud よりもローカル設定が優先され、チームで共有したくない個人用ポート設定を安全に管理できます。

Inspector を使えばメモリマップやセクションごとのサイズを可視化できます。

すべてのコマンド結果は ANSI カラー付きの疑似ターミナルにまとめて表示され、Arduino CLI の実行内容をそのまま確認できます。

プロファイルとデータ書き込み

Upload Data (ESP32)

スケッチ直下に data/ フォルダーが必要です。スケッチに #include <LittleFS.h> または #include <SPIFFS.h> を含めてください。
mklittlefs または mkspiffs でイメージを生成し、esptool で SPIFFS パーティションに書き込みます。
arduino-cli compile --show-properties の結果からツールや速度を取得し、ビルド出力中の partitions.csv を解析してオフセット/サイズを特定します。
フラッシュ前にシリアルモニタを閉じ、完了後に自動で再オープンします。
WSL で動作している場合でも、Windows の COM ポートを選択すると Windows 側で arduino-cli.exe --show-properties と esptool.exe を自動実行して転送するため、Linux でビルドしつつ Windows ドライバーで書き込むハイブリッド構成を保てます。

アセットを埋め込むか、data イメージを使うか

手早く扱いたいだけなら Arduino CLI: アセットを埋め込む が便利です。Arduino CLI エクスプローラーの各プロファイル欄（Upload Data の直前）からコマンドを呼び出し、スケッチ直下の assets/ もしくは assets_ で始まる任意のフォルダー（例: assets_wifi/ や assets_ui/）にファイルを置けば、各ファイルを PROGMEM のバイト配列と長さ定数に展開した <フォルダー名>_embed.h を再生成します。出力される配列やシンボル（assets_wifi_file_names など）もフォルダー名ごとに分かれるため、複数のアセット束を並行して使えます。ベースの assets/ も assets_ で始まるフォルダーも一つも無い場合だけ、手動コマンド実行時に assets/ を初期作成しますが、コンパイル前の自動再生成では元フォルダーが無いときにヘッダーを作らず終了するため、意図せず復活することはありません。フォルダー内に .assetsignore を配置すると .gitignore 同様の書式で除外を制御でき（# コメント、foo/、*.psd、**/tmp/**、!important.bin など）、必要なファイルだけを埋め込めます。日本語や絵文字などシンボル名に使えないファイルでも、パスをハッシュ化した一意の識別子に自動変換するため安全に取り込めます。

さらに制御したい場合は .assetsconfig を同じフォルダーに置き、INI 形式で生成場所や圧縮手順を指定します。例:

[general]
dir = ../                ; ヘッダー出力先ディレクトリ (assets からの相対 PATH, 空欄でも ../ )
header_name = wifi.h     ; 出力ファイル名（ディレクトリ部分は dir 側で指定）
prefix = wifi_assets     ; シンボルのプレフィックス（既定はフォルダー名）

[minify]
enable = true
html = true
css = true
js = true
keep_comments = false
write_output_file = false
output_dir = .assets_minified

[gzip]
enable = true
patterns = **/*.html, **/*.css, **/*.js
min_size = 256
suffix = .gz

[stamp]
format = iso, unix    ; iso / unix / カンマで複数指定可、空欄=無効

[hash]
algorithms = sha256, md5

dir は assets からの相対パスで、空欄や未設定なら ../（= スケッチルート）に出力します。header_name はファイル名のみ指定し、dir と組み合わせて保存先を決めます。minify は軽量な正規表現ベースの実装なので複雑な構文には非対応ですが、空白やコメントを素早く削る用途には十分です。write_output_file を有効にする場合は output_dir を .assetsignore に追加しておくと、生成された中間ファイルが次回の埋め込み対象に混ざらず安心です。minify → gzip の順で処理し、patterns（glob、カンマ区切り）と min_size に一致したファイルに suffix を付けて圧縮結果を埋め込みます。.assetsconfig / .assetsignore 自身は自動的に出力対象から除外されます。

[stamp] セクションを追加すると各ファイルのタイムスタンプ配列を出力できます。format = iso で ISO 8601 文字列、format = unix で符号なしの Unix 秒を assets_wifi_stamp_iso[...] や assets_wifi_stamp_unix[...] のように assets_wifi_file_count と同じ長さで用意するため、既存の assets_wifi_file_names[...] と添え字で突き合わせられます。format = iso, unix のようにカンマ区切りで複数指定すれば両方の配列を同時に生成できます。また各ファイルごとに assets_wifi_index_html_stamp_iso のような個別シンボルも宣言され、配列はそれらを参照するだけなので用途に応じて好きな方を利用できます。[hash] では sha256 / sha1 / md5 をカンマ区切りで列挙すると、指定したアルゴリズムごとに assets_<bundle>_hash_<algo>[...] 配列を生成し、各ファイルにも assets_wifi_index_html_hash_sha256 のようなシンボルが出力されます。スタンプ同様に配列はファイル順へ揃います。

ただし埋め込んだバイト列はそのままファームウェアサイズに加算されるため、ファイルが大きいと upload/OTA のたびに転送時間が延び、パーティション上限にも届きやすくなります。

一方 Arduino CLI: Upload Data は初回に data/ からファイルシステムイメージを転送する手間があるものの、以降はスケッチを書き換えても data 側を再送する必要がなく、OTA でもファームウェアを肥大化させません。サイズが大きい、頻繁に更新する、あるいは OTA での運用を想定している場合は data フォルダー方式を選び、軽量なセットだけを手軽に配布したいときに埋め込みを使い分けるのがおすすめです。

Source Backup を埋め込む

スケッチの .ino と同じ場所に .sourcebackupconfig を置いたときだけ有効化します。
Arduino CLI ツリーの Source Backup を押すと、未作成時は .sourcebackupconfig を自動生成して開きます。
現在の assets 自動再生成と同じく、コンパイル前に sourcebackup_embed.h と sourcebackup_embed.cpp を自動生成します。
保存本体は base64 ではなく圧縮済みの zip バイナリをファームに保持します。
抽出ツールがバイナリから確実に見つけられるよう、複数のグローバルへ分散せず sourcebackup::blob / sourcebackup::blob_len という単一 blob を保持します。
retain = true のときは、スケッチ側で直接参照しなくてもリンク時のガベージコレクションで落ちにくくするため、生成される .cpp に sourcebackup::isValid() を静的初期化時に呼び出し、その結果を volatile フラグへ保持する内部用の自動参照オブジェクトも出力します。
解析や base64 出力のヘルパー関数は blob 本体と分離し、未使用ならリンカ最適化で削除されてもよい設計にします。
manifest には、生成時点で拡張機能がすでに把握している情報だけを入れます。Source Backup のためだけに追加の arduino-cli コマンドは実行しません。
既定では広めにファイルを含め、サイズが気になる場合は除外設定を足して削る運用を想定します。
Markdown ドキュメント（*.md）は、通常はファームウェア再現性に直接関与しないため既定では含めません。README や作業メモも一緒に残したい場合だけ include.patterns へ明示的に追加してください。

生成される API は次の通りです。

namespace sourcebackup {

extern const uint8_t blob[];
extern const size_t blob_len;

struct View {
  const uint8_t* manifest;
  uint32_t manifest_len;
  const uint8_t* archive;
  uint32_t archive_len;
  uint16_t version;
  uint16_t flags;
  bool valid;
};

bool parse(View& out);
bool isValid();

const uint8_t* manifestPtr();
uint32_t manifestLength();

const uint8_t* archivePtr();
uint32_t archiveLength();

bool writeRawTo(Print& out);
bool writeBlobBase64To(Print& out);
bool writeArchiveBase64To(Print& out);
bool printRestoreUrl(Print& out);
bool writeArchiveBase64WithInfoTo(Print& out);

}  // namespace sourcebackup

実運用では、常時出力するよりも、起動時に特定の GPIO 状態を見て Source Backup を吐き出す形が便利です。例えば、ブート時に特定ピンが Low のときだけ出力するなら次のように書けます。

pinMode(kBackupTriggerPin, INPUT_PULLUP);
delay(10);
if (digitalRead(kBackupTriggerPin) == LOW) {
  sourcebackup::writeArchiveBase64WithInfoTo(Serial);
}

利用方法のまとまった例は、以下の companion examples リポジトリにもあります。 https://github.com/tanakamasayuki/vscode-arduino-cli-wrapper-examples/tree/main/03_source-backup

生成される blob は、固定ヘッダーに続いて manifest JSON と zip 本体を並べる形式です。

[magic "SRCBAK1\\0" 8B]
[schema_version u16]
[flags u16]
[manifest_len u32]
[archive_len u32]
[header_crc32 u32]
[manifest bytes]
[zip bytes]
[payload_crc32 u32]

.sourcebackupconfig では次のように生成内容を調整できます。

dir = ./
header_name = sourcebackup_embed.h
source_name = sourcebackup_embed.cpp
prefix = sourcebackup

[include]
patterns = *.ino, *.pde, *.c, *.cc, *.cpp, *.cxx, *.h, *.hh, *.hpp, *.hxx, *.ipp, *.tpp, *.S, *.asm, sketch.yaml, arduino-cli.yaml, .sourcebackupconfig, .vscode/extensions.json, .vscode/settings.json, data/**, assets/**, assets_*/**

[exclude]
patterns = .git/**, .github/**, .vscode/launch.json, .vscode/tasks.json, build/**, .build/**, dist/**, .sourcebackup/**, sourcebackup_embed.h, sourcebackup_embed.cpp, *_embed.h, *.bin, *.hex, *.elf, *.map, *.o, *.a, *.so, *.d, *.tmp, *.log, .DS_Store, Thumbs.db

[archive]
format = zip
compression = deflate

[embed]
retain = true
progmem = true
align = 4
section = .rodata.sourcebackup

[manifest]
enable = true
include_profile = true
include_fqbn = true
include_port = true
include_baud = true
include_generated_at = false
hash = sha256

[helpers]
emit_parse = true
emit_base64 = true
emit_raw = true

sketch.yaml とプロファイル

sketch.yaml があるときはプロファイルを優先。ない場合は FQBN を使用します。
- ひな形を作るには「Sketch.yaml Helper」を使ってボードやライブラリを選択し、生成されたテンプレートを sketch.yaml として保存してください。
ステータスバーの FQBN 表示は、プロファイルがあればプロファイル名に切り替わります。「Arduino CLI: Set Profile」で変更できます。
「Sketch.yaml Helper」では、選択したプロファイルの FQBN やライブラリ、プラットフォーム情報の確認と反映ができます。
wokwi: true を付けたプロファイルは、コンパイルのたびに .wokwi/<profile>/wokwi.elf と diagram.json / wokwi.toml を自動整備し、Wokwi 拡張機能で最新ファームウェアを即座にシミュレートできます。生成される diagram.json は UNO / MEGA / Nano / ESP32 S3 Box / M5Stack CoreS3 / Seeed XIAO ESP32 各モデル / その他 ESP32 (DevKitC) 向けのレイアウトを初期配置します。

デバッグを始める（上級者向け）

Debug Sketch – プロファイルに紐づくデバッガー設定を Arduino CLI から自動取得し、Cortex-Debug が入っていれば cortex-debug、なければ Microsoft C/C++ デバッガーを request: "launch" 付きで起動します。従来の「アタッチするプロセスを選択してください」ダイアログは表示されません。
- ボードによっては JTAG／USB シリアル／プローブ経由など複数のデバッグ接続方式があり、追加設定が必要なケースがあります。その際はエクスプローラーのデバッグヘルパーから該当プロファイルを選び、接続方法に応じた設定を反映してください。
- デバッグは VS Code の公式 C/C++ 拡張機能が提供する cppdbg と、追加拡張機能である cortex-debug の両方をサポートしています。Arduino IDE でも機能が豊富な cortex-debug を利用しているため、可能であれば cortex-debug のインストールをおすすめします。

手順

プロファイルと環境を整える。 sketch.yaml でデバッグ対象のプロファイルを既定にするか、コマンド実行時に選べるようにしておきます。シリアルポートやローカルビルドパス設定も合わせて確認しておくと生成されるタスクがハードウェアと一致します。
「Arduino CLI: Debug Sketch」を実行する。 対象スケッチとプロファイルを選ぶと .vscode/ に 2 つのファイルが生成されます。

tasks.json に Arduino: Debug Build & Upload … タスクが追加され、プローブ接続を維持したまま書き込みできます。ローカルビルドパス設定やプロファイル固有の CLI 引数も反映されます。
launch.json に Cortex-Debug 用（拡張機能がある場合）と Microsoft C/C++ 用の構成が追加されます。必要な OpenOCD / GDB 設定は Arduino CLI の出力から取り込まれるため、手作業で調整する必要はありません。このコマンドはプロファイルごとに初回実行が必須です。コアやボードパッケージ、ツールのバージョンを更新した際も再実行して最新情報を取り込みましょう。実行中は arduino-cli compile --show-properties などを解析し、自動生成した設定を使って即座にデバッグビルドを走らせます。ファイル更新後に同じコマンドが書き込みまで完了させ、Arduino が用意した thb setup（setup() の先頭）で停止した状態のセッションが開きます。初回はデバッグオプション付きで全ソースを再コンパイルするため時間がかかります。VS Code から「preLaunchTask 'Arduino: Debug Build & Upload MyProject (debugProfile)' を待機しています...」（スケッチ/プロジェクト名やプロファイル名は環境によって異なります）というダイアログが出ることがありますが、「そのままデバッグする」ボタンを押さずにそのまま待てばコンパイルと書き込みが完了し、自動的にデバッグが開始されます。

構成を最新に保つ。 ハードウェアやプロファイルを切り替えたとき、あるいは Arduino CLI やツールチェーンを更新したときは再度コマンドを実行してタスクと起動設定を再生成してください。
生成済みの設定を活用する。 前回から変更がない場合は Run and Debug ビューや F5 からデバッグを開始して構いません。どちらもコマンドが作成した構成とビルド成果物を再利用します。
必要に応じてカスタマイズする。 生成された launch.json は自由に編集できます（例: overrideAttachCommands の追加、semihosting コマンド、別の SVD への切り替えなど）。再生成時は可能な限りマージされます。ツールチェーンを入れ替えたら、Arduino CLI から新しいパスを取得するためにもう一度コマンドを実行してください。

ヒント:

デバッガー向け設定は拡張機能が自動生成します。「Arduino CLI: Debug Sketch」を実行するたびに arduino-cli compile --show-properties などを解析するため、引数を手動で管理する必要はありません。
デバッグビルド実行中は Arduino Logs 端末が前面に来るので、OpenOCD のログをリアルタイムに確認できます。
プローブを接続したまま Compile Sketch や Upload Sketch を実行しても問題ありません。同じビルドパスを共有するため、launch.json の ELF と直近の書き込み内容が一致します。

IntelliSense と開発支援

IntelliSense

ビルド中にコンパイラ出力（-I / -isystem / -iprefix）を解析し、.vscode/c_cpp_properties.json（Arduino 構成）を更新します。ビルドの最中は新規パスの追加のみ行い、ビルド完了時に未使用および存在しないパスを削除して最終的に整理します。
クリーンビルドでは先に includePath を空にし、その後に検出パスのみを追加します。
ESP32 系（esp32/xtensa-esp32/riscv32-esp-elf）では c17 / c++23 を優先します。
「Configure IntelliSense」でビルドせずに includePath を計算し、c_cpp_properties.json を作成できます。

clangd や CMake Tools で compile_commands.json を使う

clangd や CMake Tools、VS Code の C/C++ 拡張機能を compile_commands モードで使う場合は、この拡張機能が自動で出力するファイルを指定してください。

「Arduino CLI: Compile Sketch」で一度ビルドを実行します。ビルドが完了すると情報を収集できます。
ワークスペース直下の .vscode/compile_commands.json を参照します。ビルドするたびに自動で上書きされ、常に最新の内容になります。
ファイルにはスケッチフォルダー内のソースだけでなく、ビルドディレクトリ内で生成されたファイルのコマンドも含まれています。
一時的な .ino.cpp から生成されたエントリは元の .ino 名に戻し、file 列はファイル名だけを保持します。異なる PC やワークスペースでも差分が発生しにくくなります。

clangd などの設定で <ワークスペース>/.vscode/compile_commands.json を指定すれば、Arduino CLI が使ったコンパイルフラグをそのまま取り込めます。特別な手作業は不要です。

設定

arduino-cli-wrapper.path: arduino-cli 実行ファイルのパス
arduino-cli-wrapper.additionalArgs: すべての呼び出しに付与する追加引数（配列）
arduino-cli-wrapper.localBuildPath: --build-path を自動で .build/<プロファイル> に設定し、ビルド成果物をプロジェクト直下にまとめます
arduino-cli-wrapper.verbose: コンパイル/書き込み時に --verbose を付与（ステータスバーのトグルと同期）
arduino-cli-wrapper.compileWarnings: arduino-cli compile に渡す警告レベル (--warnings) を指定（ステータスバーのトグルと同期）
arduino-cli-wrapper.lint.m5gfxIncludes: Include 順チェックで M5GFX 系として扱うヘッダー一覧
arduino-cli-wrapper.lint.fsIncludes: Include 順チェックで FS 系として扱うヘッダー一覧

Include 順リント

対象はワークスペース内の .ino ファイルです。
arduino-cli-wrapper.lint.m5gfxIncludes で指定したヘッダーの後に、arduino-cli-wrapper.lint.fsIncludes に含めたヘッダーを記述するとエラー診断を表示します。
既定値で主要な M5GFX / FS ヘッダーをカバーしています。プロジェクトに応じて設定から追加・削除できます。
ドキュメントの変更や設定の更新を検知して診断を再評価します。

要件

VS Code 1.84.0 以降
Arduino CLI がローカルにインストール済み

Third-Party Notices

Highlight.js (core, cpp grammar, VS2015 theme) (c) 2006-2023 highlight.js authors, BSD-3-Clause. License: https://github.com/highlightjs/highlight.js/blob/main/LICENSE

トラブルシューティング

実行ファイルが見つからない: arduino-cli-wrapper.path にフルパスを設定してください。
ボードが検出されない: ケーブル/ドライバー/ポートを確認し、「Arduino CLI: List Connected Boards」で確認してください。
Upload Data: data/ が存在するか、スケッチに SPIFFS.h または LittleFS.h を含めているか確認してください。

ライセンス

CC0 1.0 Universal (Public Domain Dedication)。詳細は LICENSE を参照してください。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Arduino CLI Wrapper (VS Code 拡張機能)

コンセプト

クイックスタート

推奨 VS Code 拡張機能

`arduino_secrets.h` の管理

WSL を使ったビルド高速化ガイド

上級者向けカスタマイズ

オプション: `.arduino-cli-flags`（本拡張機能専用）

日常操作と UI

コマンドパレットから始める（初心者ガイド）

ステータスバー

エクスプローラービュー

ビルドとアップロードの基本

スケッチ管理とユーティリティ

スケッチ管理をラクにするツール

サンプルを素早く探す

ツール連携と細かな操作

ローカルポート設定（ワークスペースごとにポートを固定したいとき）

プロファイルとデータ書き込み

Upload Data (ESP32)

アセットを埋め込むか、data イメージを使うか

Source Backup を埋め込む

sketch.yaml とプロファイル

デバッグを始める（上級者向け）

手順

IntelliSense と開発支援

IntelliSense

clangd や CMake Tools で compile_commands.json を使う

設定

Include 順リント

要件

Third-Party Notices

トラブルシューティング

ライセンス

FilesExpand file tree

README.ja.md

Latest commit

History

README.ja.md

File metadata and controls

Arduino CLI Wrapper (VS Code 拡張機能)

コンセプト

クイックスタート

推奨 VS Code 拡張機能

arduino_secrets.h の管理

WSL を使ったビルド高速化ガイド

上級者向けカスタマイズ

オプション: .arduino-cli-flags（本拡張機能専用）

日常操作と UI

コマンドパレットから始める（初心者ガイド）

ステータスバー

エクスプローラー ビュー

ビルドとアップロードの基本

スケッチ管理とユーティリティ

スケッチ管理をラクにするツール

サンプルを素早く探す

ツール連携と細かな操作

ローカルポート設定（ワークスペースごとにポートを固定したいとき）

プロファイルとデータ書き込み

Upload Data (ESP32)

アセットを埋め込むか、data イメージを使うか

Source Backup を埋め込む

sketch.yaml とプロファイル

デバッグを始める（上級者向け）

手順

IntelliSense と開発支援

IntelliSense

clangd や CMake Tools で compile_commands.json を使う

設定

Include 順リント

要件

Third-Party Notices

トラブルシューティング

ライセンス

`arduino_secrets.h` の管理

オプション: `.arduino-cli-flags`（本拡張機能専用）

エクスプローラービュー