ESP-IDF 6.0 移行ガイド｜レガシードライバ全廃と破壊的変更の要点

🧭 はじめに：6.0 は「動いていたコードが通らなくなる」タイプの更新

2026年3月20日、Espressif の公式開発環境 ESP-IDF のメジャーバージョン 6.0 が正式リリースされました。

ESP-IDF のメジャー更新の中でも、6.0 は特に「移行作業が発生する」側の更新です。新機能が増えただけではなく、長く残っていた古い書き方が今回まとめて削除されたためです。v5.x でビルドが通っていたプロジェクトを 6.0 のツールチェーンに載せ替えると、そのままでは通らないことがあります。

とはいえ、身構えるほど難しい話ばかりではありません。変更の多くは「新しい書き方はすでに v5.0 の頃から用意されていて、今回ようやく古い方が消えた」という性質のものです。つまり、直し方は最初から決まっています。

この記事では、6.0 に上げると具体的に何が壊れ、どこをどう直せばいいのかを、公式のリリースノートと移行ガイドをもとに整理します。変更点の記載は公式ドキュメントに拠り、後半には Windows＋EIM 環境で ESP32-S3 向けのビルドを実際に通した実録を添えました。「移行すべきか」という判断の話ではなく、「移行するとき・新しい作例を試すときに、ここでつまずく」という地図として使ってください。

なお ESP-IDF そのものが初めてなら、先に VS Codeで始めるESP-IDF環境構築ガイド で開発環境の全体像をつかんでおくと、この記事の変更点が読みやすくなります。

🗺️ 全体像：変わったのは4つの領域

細かい変更点は多数ありますが、移行という視点では大きく4つの領域に分けて捉えると迷いません。

• ① 周辺ドライバ — いちばん多くのプロジェクトに影響します。ADC・I2S・RMT などの古いドライバが消えました
• ② ランタイムの土台 — 標準 C ライブラリと暗号ライブラリという、普段は意識しない足回りが入れ替わりました
• ③ ツールチェーン要件 — ビルドに必要な CMake・Python などの最低バージョンが上がりました
• ④ 構成の変化 — 一部のコンポーネントが本体から分離し、新しいインストーラが導入され、対応チップが増えました

上から順に見ていきます。

🧰 レガシー周辺ドライバの全廃（影響がいちばん大きい）

6.0 で最も多くのコードに影響する変更が、これです。公式の移行ガイドは、次のレガシードライバが「削除された（removed）」と明記しています。

• ADC（レガシー ADC ドライバ／レガシー ADC キャリブレーションドライバ）
• DAC
• I2S
• Timer Group（レガシータイマー）
• PCNT
• MCPWM
• RMT
• Sigma-Delta モジュレータ
• Temperature Sensor（温度センサ）

なぜ消すのか・新ドライバで何が良くなるのか

意外かもしれませんが、公式のリリースノートや移行ガイドは削除の理由を大きく語っていません。セキュリティ強化や高速化といった分かりやすい効能も、削除の理由としては挙げられていません。移行ガイドの記述から拾える公式の説明は、次の2点です。

• ドライバの移植性を高めるため、公開ヘッダが OS（FreeRTOS）のヘッダを暗黙に include するのをやめた
• 新ドライバでは複数のドライバオブジェクトが同じ GPIO 番号を共有できるようになり、より複雑な機能が実現できる

そのうえで、変更内容から読み取れる実利を整理すると（ここからは公式の言葉ではなく分析です）、中心は「二重体制の解消」でしょう。レガシー API は v4 時代の設計を引きずり、周辺機能ごとに書き方がばらばらでした。新 API は ADC でもタイマーでも RMT でも「設定構造体を渡してハンドルを受け取り、ハンドル越しに操作する」という同じ型に統一されています。覚え直しは最初の1回で済み、別の周辺機能に移っても読み方が通用します。そして Espressif の保守が新 API に一本化されることで、バグ修正や新チップ対応が入る場所も一本化されます。v5.0（2022年末）から3年あまりの並存期間、レガシー側は「動くが進化しない」状態でした——6.0 はそれを清算した、と読むのが実態に近いはずです。

置き換え先の対応表

削除されたレガシードライバは、それぞれ次の新しいヘッダに対応します。include を差し替え、呼び出しをハンドルベースの新 API に書き換えるのが基本の直し方です。

I2S・DAC・RMT のように1つのレガシーヘッダが用途別の複数ヘッダに分かれているものは、自分が使っている機能に対応するヘッダだけを include します。

あわせて入った、細かいが引っかかりやすい変更

ドライバ周りでは、削除以外にも移行時に手が止まりやすい変更がいくつかあります。公式移行ガイドが挙げているもののうち、影響しやすい2点を紹介します。

• ドライバの公開ヘッダが FreeRTOS ヘッダを暗黙で include しなくなった — 移植性を上げるための変更です。これまでドライバ経由で間接的に入っていた freertos/FreeRTOS.h などに頼っていたコードは、自分で明示的に include する必要があります
• RMT の設定構造体から io_od_mode が削除された — オープンドレイン出力にしたい場合は、gpio_od_enable() を自分で呼びます。また、同じ GPIO を複数のドライバオブジェクトで共有できるようになり、RMT の TX/RX を同一ピンに割り当てて 1-Wire のような読み書きを再現するのに、以前の io_loop_back 設定は不要になりました

🔤 標準 C ライブラリが Newlib から Picolibc に

6.0 では、既定の標準 C ライブラリ（libc）が Newlib から Picolibc に変わりました。オプションが増えたのではなく既定の交代です（後述のとおり、Newlib に戻す選択肢は残っています）。

以前はどうだった？ なぜ変える？

v5.x までの Newlib は実績のある定番ですが、stdio まわりの内部バッファや管理領域が RAM を相応に使います。公式移行ガイドは Picolibc を「stdio 実装を書き直した Newlib フォークで、目標はメモリ消費の削減」と説明しており、交代の狙いはまさにそこです。

効果は公式が比較値を出しています。移行ガイド記載のサンプル比較では：

RAM が数百 KB の世界で、libc の足回りだけでこれだけ軽くなるのは大きい。しかもコードを1行も書き換えずに、6.0 でビルドし直した全プロジェクトが自動的に受け取るメリットです（数値は公式サンプルでの比較で、削減幅は使う機能によって変わります）。

互換性の注意

移行の観点では、多くのアプリケーションはこの変更をほぼ意識せずに済みます。公式リリースノートも「まれなケースで破壊的変更を生むことがある（may introduce breaking changes in rare cases）」という書き方です。注意点は3つあります。

• タスクごとの stdin/stdout/stderr の付け替えができなくなった — Newlib では可能だったタスク単位のストリーム再定義が、Picolibc では全タスク共有のグローバルになりました。タスクごとにログの出口を分けるような凝った実装は要修正です
• Newlib の内部構造（struct _reent）に触るライブラリは危険 — 互換オプション CONFIG_LIBC_PICOLIBC_NEWLIB_COMPATIBILITY はあるものの限定的で、内部をいじるコードはタスクスタックの破壊につながると公式が警告しています
• どうしても合わなければ Newlib に戻せる — Newlib はツールチェーンに残っていて、menuconfig の LIBC_NEWLIB で切り替えられます。「まず Picolibc で試し、問題が出たら原因を切り分け、ダメなら戻す」が現実的な動線です

🔐 暗号が Mbed TLS 4.x・PSA Crypto へ

もう1つのランタイム側の大きな変更が、暗号ライブラリです。6.0 は Mbed TLS を 4.x に上げ、暗号処理の入り口を PSA Crypto API に切り替えました。公式リリースノートはこれを「PSA ファーストの暗号方針への大きな転換」と表現しています。

以前と以後で何が変わるか

移行時の実務チェックポイントは、psa_crypto_init() の呼び忘れです。初期化を忘れると暗号処理が失敗するので、6.0 で TLS まわりが急に動かなくなったら、まずここを疑ってください。

もう1つ、正直に書いておくと、この移行はタダではありません。公式リリースノートは、PSA 化に伴い Flash 使用量が約 37〜41KB 増え、HTTPS 接続時のスタック使用量も約 800 バイト増えることを明記しています。将来の移植性と鍵管理の安全性への投資と引き換えのコストで、Flash の小さい構成では効いてくる数字です。Picolibc の削減分もあるので、移行後に一度 idf.py size で全体を眺めておくと安心です。

HTTPS 通信の作例のように esp-tls や高レベルのクライアント越しに TLS を使っているだけであれば、内部が PSA に移っても呼び出し側の変更は小さく収まります。逆に、mbedtls_ の低レベル関数を直接叩いて暗号や署名を実装していたコードは、まとまった書き換えが必要です。

🧱 ツールチェーンの最低要件が上がった

6.0 をビルドするには、周辺のツール側の最低バージョンも満たす必要があります。まず環境を入れ直すところから始めるのが安全です。

C／C++ の既定標準が新しくなったことで、より新しい言語機能が既定で使える一方、古いコンパイラや古い書き方に依存していると警告・エラーが出ることがあります。CMake と Python は、要件を下回っているとそもそもビルドが始まりません。移行の初手として、まずここを確認してください。

もうひとつ、地味に効くのがコンパイラ警告の扱いです。6.0 では既定の警告がエラーとして扱われるようになりました（CONFIG_COMPILER_DISABLE_DEFAULT_ERRORS が既定で無効）。v5.x で「警告は出るけど動いていた」コードは、6.0 ではその警告のせいでビルドが止まります。移行ビルドで見慣れないエラーが並んだら、新規のバグではなく警告の格上げでないかを先に確認すると、直す量の見積りを誤りません。

📦 一部のコンポーネントが本体から分離した

6.0 では、これまで ESP-IDF 本体に同梱されていた一部のコンポーネントが、ESP Component Registry（コンポーネントレジストリ）側へ移されました。

使い方としては、idf_component.yml（依存定義ファイル）に必要なコンポーネントを書いてコンポーネントマネージャに取ってこさせる形になります。

🆕 対応チップ：従来チップはそのまま、C5・C61 が正式に加わった

先に誤解を1つ潰しておきます。「6.0 対応チップ」の話題は新顔ばかりが取り上げられるため、新しいチップ専用のバージョンに見えがちですが、ESP32・S2・S3・C3・C6・H2・P4 など v5.x で使えていたチップのサポートは、6.0 でもそのまま続いています。従来チップの継続に新顔が加わった、というのが正しい構図です。手元の v6.0.2 で idf.py --list-targets を実行した結果がこちら。

太字の ESP32-C5（2.4/5GHz デュアルバンド Wi-Fi 6）と ESP32-C61（安価な 2.4GHz Wi-Fi 6）が、6.0 でプレビューから正式サポートへ昇格した新顔です。この2チップには、要望の多かったリカバリーブートローダ（OTA 更新に失敗した機器を現場で復帰させるための予備ブートローダ）のサポートも 6.0 で入っています。一方、ESP32-H21・ESP32-H4 はプレビュー段階です。プレビューは動作が保証される正式サポートとは扱いが異なるため、本番用途では位置づけを踏まえて使ってください。

どのチップで作り始めるか自体を迷っている場合は、ESP32 シリーズの選び方｜S3・C3・C6・H2・P4 の違いと使い分け で用途からモデルを決めてから環境を作ると、後戻りが減ります。

🚀 新しいインストーラ「EIM」

6.0 に合わせて、ESP-IDF Installation Manager（EIM） という新しいインストーラが導入されました。公式は EIM を「ESP-IDF と好みの IDE のセットアップ全体を単純化する、統一されたクロスプラットフォームのツール」と説明しています。

これまで環境構築は、VS Code 拡張・OS ごとのインストーラ・スクリプトと入り口が分かれていましたが、EIM はそれを1つにまとめる位置づけです。これから 6.0 を新規に入れるなら EIM が素直な入り口で、Windows なら winget から2コマンドで済みます。

winget install Espressif.EIM
eim install --idf-versions v6.0.2

EIM そのもの（導入手順の詳細・コマンド一覧・複数バージョン共存の実運用パターン・既知の罠）は EIM（ESP-IDF Installation Manager）の使い方｜複数バージョン共存で変わる ESP32 開発環境 に詳しくまとめました。また mcp 機能を有効化すると Claude Code などの AI クライアントから ESP-IDF を操作できる MCP サーバも使えます（→ MCP サーバ活用ガイド）。

5.5 と 6.0 は同居できる（複数バージョン管理）

EIM のいちばんの実力は、複数の ESP-IDF バージョンを同居させて、切り替えながら使えることです。この記事の環境では、6.0 を入れた後もこうなっています。

> eim list
Installed versions:
- v6.0.2 [C:\esp\v6.0.2\esp-idf]
- v5.5.2 [C:\esp\v5.5.2\esp-idf]
- v5.5.3 (selected) [C:\esp\v5.5.3\esp-idf]

(selected) が付いているのが既定のバージョンで、使い分けは2通りあります。

• コマンド単位でバージョン指定 — eim run "idf.py build" v6.0.2 のように末尾へバージョンを付けると、既定を変えずにそのコマンドだけ 6.0.2 で走ります
• 既定ごと切り替え — eim select v6.0.2。以後の eim run はすべて 6.0.2 になります（eim select v5.5.3 でいつでも戻せます）

つまり 6.0 への移行は、動いている 5.x 環境を壊して入れ替える作業ではありません。6.0.2 を隣に足して、プロジェクトごとに使うバージョンを選ぶ——5.5 系の資産はそのまま維持し、新しい開発だけ 6.0 で始められます。メジャーバージョン移行の心理的ハードルを、道具の側が下げてくれた格好です。この共存管理を軸にした実運用パターン集は EIM の徹底ガイド を参照してください。

VS Code の拡張機能を使った環境構築の全体像は、VS Codeで始めるESP-IDF環境構築ガイド｜最小構成でHello Worldまで にまとめてあります（こちらは v5.5.2 を前提にした手順ですが、拡張機能の使い方・ステータスバーの見方などは 6.0 でもそのまま役立ちます）。

🧭 移行の進め方

ここまでの内容を、実際に手を動かす順番に並べると次のようになります。上から順に潰していくと、影響箇所を取りこぼしにくくなります。

1. 環境を用意する — EIM などで 6.0 を導入します
2. ツールチェーン要件を確認 — CMake 3.22・Python 3.10 を満たしているか
3. まずビルド — 通らないのが前提です。エラーメッセージが、直すべき箇所の一覧になります
4. ドライバの include を差し替え — レガシーヘッダを新ヘッダへ。呼び出しもハンドルベースへ
5. 暗号を使っていれば PSA へ — psa_crypto_init() の追加を忘れずに
6. FreeRTOS ヘッダと依存コンポーネントを補う — 暗黙 include に頼っていた箇所、レジストリへ移った cJSON など
7. 再ビルドして実機で確認 — Picolibc など足回りの変更は、実機の挙動で最終確認します

🧪 実録：ESP32-S3 向けに 6.0 の初回ビルドを通す

机上の整理だけでは絵に描いた餅なので、この環境（Windows 11＋EIM 0.17.1＋ESP-IDF v6.0.2）で、ESP32-S3 向けに hello_world のクリーンビルドを通したときの記録です。手順は、v6.0.2 の examples から get-started/hello_world を作業ディレクトリへコピーして、次の2コマンドだけです。

eim run "idf.py -C <プロジェクトパス> set-target esp32s3" v6.0.2
eim run "idf.py -C <プロジェクトパス> build" v6.0.2

実際に流れたログの中で、記事前半の変更点がいくつも「本物だ」と確認できました。

• set-target は自動で fullclean を伴い、esp32s3 用の sdkconfig を新規生成します。ターゲットを切り替えるとビルド成果物は消える、と覚えておくと慌てません
• コンパイラは xtensa 向け GCC 15.2.0。プロジェクトの CMakeLists.txt には cmake_minimum_required(VERSION 3.22) が直書きされていて、ツールチェーン要件の引き上げがそのまま形になっています
• 6.0 の examples には idf_build_set_property(MINIMAL_BUILD ON)（main が依存するコンポーネントだけをビルドする設定）が最初から入っています。hello_world のフルビルドは 543 ステップ・約3分で完了しました
• 成果物の hello_world.bin は 145,424 バイト。既定の 1MB アプリパーティションに対して 86% の空きです。Successfully created ESP32-S3 image. が出ればビルド成功で、警告は1件も出ませんでした

続けて、ESP32-S3 実機（COM5 接続）へ書き込みます。

eim run "idf.py -C <プロジェクトパス> -p COM5 flash" v6.0.2

esptool（v5.3.1）が接続時にチップを識別し、bootloader・パーティションテーブル・アプリの3イメージを書き込んで検証まで通します。実際の出力の要点はこうでした。

Connected to ESP32-S3 on COM5:
Chip type:          ESP32-S3 (QFN56) (revision v0.1)
Features:           Wi-Fi, BT 5 (LE), Dual Core + LP Core, 240MHz,
                    Embedded PSRAM 8MB (AP_3v3)

Writing 'hello_world.bin' at 0x00010000...
Wrote 145424 bytes (81475 compressed) at 0x00010000 in 2.2 seconds (534.9 kbit/s).
Verifying written data...
Hash of data verified.

Hard resetting via RTS pin...
Done

すべてのイメージで Hash of data verified が出て、最後に Hard resetting via RTS pin で終われば書き込み成功です。

リセット後のシリアル出力（115200bps。idf.py monitor で見るのと同じ内容、終了は Ctrl+]）はこうなりました。

I (29) boot: ESP-IDF v6.0.2 2nd stage bootloader
I (29) boot: chip revision: v0.1
I (43) boot.esp32s3: SPI Flash Size : 2MB
I (182) app_init: ESP-IDF:          v6.0.2
I (256) main_task: Calling app_main()
Hello world!
This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision v0.1, 2MB external flash
Minimum free heap size: 401084 bytes
Restarting in 10 seconds...

Hello world! とチップ情報が流れ、10秒カウントダウンして再起動を繰り返します。ここまで通れば、6.0 環境の土台は完成です。

ひとつ、実機ならではの気づきもありました。起動ログに次の警告が出ています。

W (231) spi_flash: Detected size(16384k) larger than the size in the
binary image header(2048k). Using the size in the binary image header.

この基板の Flash は実際には 16MB 載っているのに、hello_world の既定設定が 2MB のままなので、安全側に倒して 2MB として扱った——という意味です。実開発に入るときは idf.py menuconfig の Serial flasher config → Flash size を実装どおりに合わせます。こうした「既定値と実基板の食い違い」に最初のスモークテストで気づけるのが、hello_world を一度通しておく価値です。

既存の v5.x プロジェクトを移すときは、この土台の上に前半の対応表の置き換え作業が乗ります。確認の観点は3つです。

• クリーンビルドが 0 エラーで通るか（6.0 は警告もエラー扱いになる点に注意）
• 暗号処理が psa_crypto_init() の追加で正しく動くか
• Picolibc への切り替えで、printf のフォーマットや malloc 周辺の挙動に差が出ないか

✅ まとめ

• 6.0 は破壊的変更を含むメジャー更新です。特に ADC・I2S・RMT などレガシー周辺ドライバの全廃が、最も多くのコードに影響します
• 直し方は明確で、古い driver/xxx.h を新しいヘッダ（adc_oneshot.h・gptimer.h など）へ差し替えるのが基本です。新ドライバは v5.0 から使えたものなので、新しめのコードほど移行は軽くなります
• 標準 C ライブラリは Picolibc、暗号は Mbed TLS 4.x／PSA Crypto へ。高レベル API 越しに使っているだけなら影響は小さく、低レベル関数を直接叩いていた場合はまとまった書き換えが必要です
• CMake・Python・C/C++ 標準の最低要件も上昇。移行はまず環境を入れ直すところから
• 従来チップは継続サポートのまま、C5・C61 が正式昇格（H21・H4 はプレビュー）。新インストーラ EIM を使えば 5.5 系と 6.0 を同居させたまま、プロジェクト単位で移行できます

型番選びと同じで、6.0 も「何が自分のコードに効くか」を先に押さえれば、移行はそれほど怖くありません。影響が大きいのはドライバ周りなので、まずそこから見ていくのが近道です。

関連記事

• EIM（ESP-IDF Installation Manager）の使い方｜複数バージョン共存で変わる ESP32 開発環境：本記事の移行を支えた新インストーラの徹底ガイド。導入・コマンド一覧・実運用パターンまで
• ESP-IDF 6.0×ESP32-S3でWi-Fi接続とHTTP POST｜cJSONをidf_component.ymlで取得するレジストリ時代の依存管理：コンポーネント移管を実機で通した実践編
• ESP32 シリーズの選び方｜S3・C3・C6・H2・P4 の違いと使い分け：6.0 で正式対応した C5・C61 を含め、どのチップで作るかを用途から選ぶガイド
• VS Codeで始めるESP-IDF環境構築ガイド｜最小構成でHello Worldまで：ESP-IDF 環境構築の基本。拡張機能の使い方は 6.0 でも役立ちます
• ESP32-S3 × ESP-IDF｜cJSONとHTTP ClientでJSONをPOST送信：cJSON と esp_http_client を使う実装。6.0 では cJSON の依存の扱いに注意
• ESP32-S3からAzureへデータを飛ばす！HTTPS POSTとサーバーレス連携の極意：HTTPS 通信の実装。TLS の土台が PSA Crypto に移った点が関わります
• ESP32 Arduino IDE セットアップ手順【2026年版】｜インストールからLチカまで：ESP-IDF が重いと感じたら、まず Arduino IDE で感触をつかむのも手です

参考

• Announcing ESP-IDF v6.0（Espressif Developer Portal・2026年3月）
• ESP-IDF Release v6.0（GitHub リリースノート）
• Migration from 5.x to 6.0 — Peripherals（ESP-IDF 公式ドキュメント）
• Migration from 5.x to 6.0 — System（ESP-IDF 公式ドキュメント・Picolibc の比較値と互換性注意）
• PSA Certified Crypto API（Arm 公式仕様）
• Espressif Announces ESP-IDF v6.0（Espressif 公式ニュース）