はじめに
前回は、家族で楽しめる機能を生成AIと考え、「手拍子に合わせて踊るｽﾀｯｸﾁｬﾝ」を連載の題材に決めました。手拍子で踊るには、音を聞く、タイミングを決める、顔や光で反応する、首を動かすといった複数の処理が必要です。本連載では、各機能を1つずつ実装し、最終的に1つの連携した動きへとまとめていきます。
コードを書き始める前に、まずはファームウェアを選ばなければなりません。筆者は普段、Moddable版のｽﾀｯｸﾁｬﾝを開発していますが、本連載では別のプロジェクトである「stackchan-idf」を採用します。選定の詳しい理由は後述します。
なお、本連載はAIに実装を主導させる「バイブコーディング縛り」で進めます。実装自体はまるごとCodexに任せ、筆者は要件の整理、コード差分の確認、安全な実機操作、および動作確認を担当します。
電子工作の入門では、LEDを点滅させる「Lチカ」がよく最初の題材に選ばれます。「光る」という視覚的にわかりやすい結果によって、開発環境の構築、ビルド、実機への書き込み、入出力の動作までを一度に検証できるためです。
ｽﾀｯｸﾁｬﾝの背面には、左右合わせて12個のフルカラーLEDが並んでいます。最初の実装では、開発環境の動作確認を兼ねてこのLEDを点滅させます。ただしその前に、吹き出しへ「Hello World」を表示させ、画面表示の変更からビルド、実機書き込みまでの一連の流れを確認しておきましょう。
構造を追いやすい「stackchan-idf」
筆者が開発するModdable版のｽﾀｯｸﾁｬﾝは、JavaScriptで制御コードを書ける点が大きな魅力です。 一方でESP32向けに利用する場合、マイコン側の開発環境に加えてModdable SDK や、XS JavaScriptエンジンも扱う必要があります。Web開発者の視点からはJavaScriptに親しみやすさがあるものの、初期の環境確認で追うべき構成要素が増えてしまいます。
また、M5Stackの公式ファームウェアは、AI Agentやモバイルアプリ連携、遠隔操作、OTA（Over The Air）更新など、製品レベルの機能を包含したコードベースです。公式リポジトリにはファームウェアだけでなく、モバイルアプリ、リモコン、サーバーのコードも収録されており、ビルド時にはXiaoZhiを含む複数のリポジトリを取得し、パッチを適用する構成となっています。公式のAI Agentやアプリを活用して開発を進めるのであれば、この公式構成を選ぶのが自然です。
今回、機能や開発環境に加えて「筆者にとって未知のコードベースであること」も選定条件に設定しました。自身が開発するModdable版であれば、Codexが探索する前に構造や修正箇所を予想できてしまいます。筆者自身も全体構造を把握していない状態からCodexと共にコードを読み解く過程を示すほうが、バイブコーディングの入門記事としてより価値があると判断しました。
Kenta Idaさんが開発する「stackchan-idf」では、画面描画とLED制御がESP-IDF上のC++として実装されており、アプリ層からハードウェア層までの呼び出し構造を追いやすい点が特徴です。ESP-IDFは、ｽﾀｯｸﾁｬﾝに搭載されているチップのメーカーであるEspressif社が直接提供しています。一次資料やツールチェーンが充実しているため、チップ固有の挙動まで遡って確認しやすい点も本連載に適しています。
C++言語に不慣れであっても、Codexを活用すれば既存ソースコードから必要な処理を探し出し、内容を解説させることができます。なお、stackchan-idf自体も最初からAIエージェントと共に開発されてきたプロジェクトであり、コミット履歴にはClaudeを共同作者とする変更が数多く残されています。
ESP-IDF上の構成を追いやすく、Codexによるコード調査からスムーズに始められること。これが自作のファームウェアではなくstackchan-idfを選んだ理由です。短いプロンプトを送り、実機検証を挟みながら要件を具体化していく手法は、他のファームウェア開発にも十分応用できます。Web技術に馴染みがある方はModdable版、公式アプリやAI Agentを生かしたい方はM5Stack公式版など、目的に合わせて選択すると良いでしょう。
執筆時の開発・検証環境
本連載の開発は、以下の環境で実施しました。
| 項目 | 使用したもの |
|---|---|
| ホストOS | Ubuntu 24.04.3 LTS（x86-64） |
| コーディングエージェント | Codex CLI 0.144.3 |
| 使用モデル | gpt-5.6（reasoning effortは作業内容に応じて変更） |
| ファームウェア | stackchan-idf v0.10.3 |
| SDK | ESP-IDF v5.5.4 |
| 確認日 | 2026年7月14日 |
「/plan」コマンドによる安全なセットアップ計画
OSSの開発環境構築では、READMEに記載された手順と手元のPC環境が合致しないケースがよくあります。CodexはOSや既存SDKの状態を調べ、差分に応じた適切な手順を提案してくれます。ただし、SDKのインストールはホームディレクトリやシステム環境へ影響を与えるため、内容を確認せずに実行させるわけにはいきません。
まず、セットアップを行うフォルダをターミナルで開き、Codex CLIを起動します。Codex CLIをあるフォルダーで初めて起動すると、設定によっては「Do you trust the contents of this directory?」という確認が表示されます。そのフォルダを信頼するとリポジトリ内のCodex設定やフックが読み込まれるため、安全性を把握しているリポジトリのみ許可してください（信頼を選んだ場合でも、PC全体への無制限なアクセスが許可されるわけではありません）。
Codex CLIでは、入力欄に/を入力すると、モデルの切り替えや権限の変更などに使えるスラッシュコマンドが表示されます。ここで「/plan」を実行してPlanモードへ切り替えると、Codexは即座にコード変更を行わず、必要な調査や確認を行った上で作業計画を作成します。
/plan stackchan-idf v0.10.3の開発環境をこのPCにセットアップし、M5Stack CoreS3向けの変更前ビルドが通るところまで進めたいです。まだインストールや変更はせず、計画だけ立ててください。
これに対し、Codexから以下の計画が提示されました。
全体の構成と、ホスト環境への影響に関する部分を抜粋します。
まだインストール、リポジトリの取得、設定変更、ビルドは行いません。 次の順序なら、ホストへの変更範囲を確認しながら、stackchan-idf v0.10.3の変更前ビルドまで進められます。 ## セットアップ計画 ### 1. 現在のPCを読み取りだけで確認する 最初に、UbuntuのバージョンとCPUアーキテクチャがUbuntu 24.04.3 x86-64であることを確認します。 Git、CMake、Ninja、Python 3など、ESP-IDFの導入に必要なコマンドがすでに入っているかも調べます。 既存のIDF_PATHやESP-IDF環境を確認し、別バージョンとの混在を避けます。 /dev/ttyACM0は存在と読み書き権限だけを確認します。 今回の完了条件はビルドまでなので、実機への書き込み、シリアルモニターの起動、ユーザーのグループ変更は行いません。 ### 2. ホストへ加える変更を限定する ESP-IDF v5.5.4は、他のバージョンと混ざらないように$HOME/esp/esp-idf-v5.5.4へ置く計画です。 ESP-IDFが導入するクロスコンパイラーやPython環境は、原則として$HOME/.espressif配下に置きます。 シェルの起動設定は変更せず、作業するシェルでだけexport.shを読み込みます。 この工程で想定されるホストへの影響は次のとおりです。 - Ubuntuに不足パッケージがある場合だけ、aptでシステム全体へ追加する - $HOME/esp/esp-idf-v5.5.4にESP-IDF本体とサブモジュールを配置する - $HOME/.espressifにESP32-S3向けツールチェーンとPython環境を配置する - ネットワークから数GB規模の取得が発生する可能性がある OS全体のアップグレード、既存ESP-IDFの削除、シェル設定ファイルの変更、udevルールの追加は行いません。 ### 5. 変更前ビルドを実行する 準備が整ったら、アプリケーションのソースコードを変更していない状態で、リポジトリが用意する手順を使ってBOARD=cores3のクリーンビルドを行います。 初回ビルドではESP-IDFのManaged Componentsが追加取得される可能性があるため、取得元とバージョンも記録します。 追加パッケージやパッチが必要になった場合は、ビルドを止めて、必要な理由とホストまたはリポジトリへの影響を報告します。 ## 完了条件 次のすべてを満たした時点で、セットアップを完了と判定します。 1. stackchan-idfがv0.10.3へ固定され、追跡対象ファイルに変更がない … 3. BOARD=cores3、ESP32-S3向けの変更前ビルドが終了コード0で終わる … 6. /dev/ttyACM0には書き込んでおらず、実機のFlashや設定は変化していない この計画では、ｽﾀｯｸﾁｬﾝへの書き込みと実機動作確認は次の段階に分けます。 まず変更前ビルドを再現できる状態を作り、その後で/dev/ttyACM0への書き込み権限と安全な書き込み手順を確認します。
提示された計画には、SDKのインストール先、システムへ影響する範囲、実機書き込みの有無が明確に記載されていました。筆者の環境には既存のESP-IDFが存在していたため、stackchan-idf用ESP-IDFの保存先を記事用の一時ディレクトリへ変更するよう指示を調整した上でセットアップを進めました。
Planモード実行中に「ESP-IDFはどのバージョンを使いますか？」といった確認が入る場合があります。意図が不明な場合は推測で選択せず、Escキーで一度質問を閉じ、後述する「/side」コマンドで「なぜそのバージョンを指定する必要がありますか？」とCodexへ聞き返すのが安全です。
計画がまとまると画面に選択肢が表示されます。1つ目は現在の会話文脈を維持したままDefaultモードで実装を開始し、2つ目は計画内容のみを新しいコンテキストへ渡して実行します。3つ目を選ぶとPlanモードに留まり、計画の再調整を行えます。
1つ目の「Yes, implement this plan」を選択すると、Codex CLI内部でImplement the plan.というメッセージが送信され、同一セッションのままセットアップが開始されます。
「/permissions」でAIの操作権限とサンドボックスを制御
Codexが計画に沿ってセットアップを進めると、ESP Component Registryから依存コンポーネントを取得する手前で処理が一時停止しました。
画面にはサンドボックス外でコマンドを実行してよいかを尋ねる確認が表示され、実行予定のコマンドと外部実行が必要な理由が明示されます。
コマンドと取得元を確認の上、「Yes, just this once」を選択して今回限りの実行を許可しました。これはコンパイルエラーではなく、Codexが許可なくネットワーク通信を行わず、人間に判断を委ねた場面です。
CodexはOSの機能を活かしたサンドボックスにより、アクセス可能なファイルやネットワーク範囲を制限しています。本稿では、Codexを起動したカレントディレクトリを起点に書き込みが許可された領域をワークスペースと呼びます。（実際のワークスペースには一時ディレクトリなどが含まれる場合があり、/statusで確認可能です。）
Planモードが「実装を開始するかどうか」を決定するのに対し、「/permissions」は「実装中にどこまでの操作を自律的に任せるか」を設定します。作業の途中でも呼び出し可能です。
選択肢は環境により異なりますが、本環境では「Ask for approval」「Approve for me」「Full access」が用意されていました。今回採用した「Ask for approval」は、ワークスペース内のファイル編集や標準コマンドをCodexに任せつつ、ネットワーク接続や領域外への書き込み時のみ人間の承認を求める安全な設定です。
一方、「Full access」はファイル・ネットワークの制限を完全に解除する設定であり、失敗時の影響を隔離できる専用環境向けです。「Approve for me」は別のレビュアー役Codexが権限要求を審査し、安全と判断されれば自動承認するモードです。人間の手をとめずに進めやすい反面、レビューごとにモデル呼び出しが発生しトークン消費が早くなる点に留意してください。
