ESP32 Simulator

esp32sim-mcp

エージェントがESP32ファームウェアを作成し、起動してテストします。ボードもアカウントも不要です。

_{実際のClaude Codeセッションをライブで記録したものです（最後のアイドル時間のみ短縮しています）。ESP-IDFのhello_worldを編集し、ESP-IDFがインストールされていないためDockerでビルドして、エミュレーターのコンソールを確認しています。}

コーディングエージェントは組み込みCの作成は得意です。しかし、実行となると手も足も出ません。手元にボードがなければ、「コンパイルできた」でフィードバックループが終わってしまいます。

esp32sim-mcpは、そのループを完結させます。Claude Code、Codex、Cursor、または任意のMCPクライアントにツール一式を提供し、エージェントが作成したファームウェアを、ローカルで動作する命令レベルのESP32エミュレーターであるesp32sim上で起動します。そして、チップが出力した内容、クラッシュの有無、ディスプレイの表示を返します。エージェントは結果を読み、コードを修正して再試行します。実機を手元で使う場合と同じ流れです。

• 🔌 ハードウェアもクラウドも不要です。 すべてお使いのマシン上で動作します。アカウント、トークン、ボードは必要ありません。
• 🧬 実際のブートチェーンを使用します。 EspressifのマスクROM、ESP-IDFブートローダー、変更していないアプリを、ESP32-S3、C3、C6、従来のESP32で実行します。
• 📡 コンソールだけではありません。 DHCP、DNS、NATを備えた仮想WiFiアクセスポイント、ボタン、ロータリーエンコーダー、GPIO、UART入力、タッチ、ディスプレイのスクリーンショットに対応しています。
• 🧪 雰囲気ではなくアサーションで検証します。 sim_expectは合否と、見つからなかった正確な行を返すため、エージェントは何を修正すべきか把握できます。
• ⚡ 高速です。 エミュレーションは通常、実時間より速く進みます。Appleシリコンでは、WiFiステーションがネットワークに接続するまでのエミュレーション上の8秒が、約0.6秒で完了します。
• 🤖 スキルが付属します。 initを実行すると、作成 → ビルド → シミュレーション → 修正の流れをエージェントに教えるスキルがインストールされます。ESP-IDFがインストールされていない場合にDockerでビルドする方法も含まれます。

クイックスタート

npx -y esp32sim-mcp setup                      # emulator + mask ROMs, pinned and SHA-256 verified
cd your-esp-idf-project
npx -y esp32sim-mcp init                       # registers the MCP server and the skill for your agents

次に、シリアルコンソールで確認できるものをエージェントに依頼します。

1秒ごとに出力するカウンターを追加してビルドし、シミュレーターで5まで増えることを確認してください。

必要条件：Node.js 22以上、およびファームウェアのビルドにESP-IDF または Dockerが必要です。エミュレーターのビルド済みバイナリはmacOS（Appleシリコン）とLinux（x64、arm64）に対応しています。詳しくはその他のプラットフォームをご覧ください。

エージェントに見える内容

実際のセッションでは、エージェントは次のように呼び出します。

{
  "tool": "sim_expect",
  "projectDir": ".",
  "chip": "s3",
  "board": "none",
  "maxSeconds": 10,
  "patterns": ["Hello world!", "Counter: 1", "Counter: 2", "Counter: 3", "Counter: 4", "Counter: 5"]
}

すると、次の結果が返ります。

### Expect Test: ✅ PASSED

Matched 6 / 6 patterns.

- ✅ Matched (line 54): `Hello world!`
- ✅ Matched (line 55): `Counter: 1`
  ...
- ✅ Matched (line 65): `Counter: 5`

#### Full UART Logs:
ESP-ROM:esp32s3-20210327
Build:Mar 27 2021
rst:0x1 (POWERON),boot:0xf (SPI_FAST_FLASH_BOOT)
...

問題が発生した場合は、代わりにパニックの情報が返されます（Guru Meditation Error、スタックオーバーフロー、アサーション失敗、ヒープ破損）。そこには、発生までのログと、見つからなかったパターンが明示されます。

ツール

すべてのツールはprojectDir（ESP-IDFビルドはbuild/flasher_args.jsonから検出されます）、または明示的なappBin／bootloaderBin／ptableBinのパスに加え、chip、board、wifi（例：ssid=demo,psk=secret）を受け取ります。UART0とUSB-Serial/JTAGコンソールの両方がキャプチャされるため、プロジェクトがどちらにログを出力していても、その内容が表示されます。

仕組み

flowchart LR
    A["Coding agent<br/>(Claude Code, Codex, Cursor)"] -- "edits code,<br/>runs idf.py build<br/>(local or Docker)" --> B["ESP-IDF build/"]
    A -- "MCP: sim_expect, sim_run, ..." --> C["esp32sim-mcp"]
    C -- "flasher_args.json" --> B
    C -- "spawns" --> D["esp32sim emulator<br/>mask ROM → bootloader → app"]
    D -- "UART / USB-JTAG, panics,<br/>display, virtual WiFi" --> C
    C -- "pass/fail, logs, PNG" --> A

esp32sim-mcpは、薄くテスト済みのレイヤーです。ビルドを検出し、ツール呼び出しをesp32simのコマンドラインに変換し、2つのコンソールを分離して重複を除去し、パニックを検出して、エージェント向けに結果を整えます。エミュレーション自体はesp32simが担います。

CIでの使用

エージェントなしでも同じチェックを実行でき、成功時は終了コード0、失敗時は1を返します。ファームウェアをビルドし、起動ログをアサートするGitHub Actionsジョブの例：

jobs:
  firmware:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - name: Build
        run: docker run --rm -v "$PWD:/project" -w /project espressif/idf:v5.5.4 idf.py set-target esp32s3 build
      - name: Install the emulator
        run: npx -y esp32sim-mcp setup
      - name: Boot and check the console
        run: npx -y esp32sim-mcp expect --max-seconds 10 --pattern "app_main" "Counter: 5"

このリポジトリ独自のCIでは、ボタンのスクリプト操作も含め、examples/hello-esp32に対して同様の処理を行います。

esp32sim-mcp setup                 # install emulator + ROMs (or: install-emulator, fetch-roms)
esp32sim-mcp init [--global] [--agent claude-code|codex|cursor|claude-desktop] [--dry-run]
esp32sim-mcp run [-p dir] [--chip s3] [--board none] [--max-seconds 5] [--wifi ssid=x,psk=y]
esp32sim-mcp expect --pattern "a" "b" [--unordered] [--script actions.txt] [...run options]
esp32sim-mcp list [--chip c6]
esp32sim-mcp doctor
esp32sim-mcp serve                 # the MCP server (what agents launch)

対応チップとボード

標準のESP-IDFプロジェクトではnoneを使用してください。仮想WiFiアクセスポイントは、4種類すべてのチップで動作します。

エージェントのセットアップ

initは使用しているエージェントを検出し、それぞれを設定します。デフォルトではファームウェアプロジェクト内で実行されます。--globalを指定すると、ユーザーレベルの設定を書き込みます。

既存のエントリーは保持され、再実行しても変更はなく、解析できない設定ファイルには手を加えません。

Claude Codeプラグイン。 initの代わりに、サーバーとスキルをプラグインとして、すべてのプロジェクトにインストールできます：

/plugin install esp32sim --marketplace stramanu/esp32sim-mcp

MCPレジストリ。 サーバーはio.github.stramanu/esp32sim-mcpとして公式MCPレジストリに公開されています。その他のMCPクライアントでは、次のようにします：

{
  "mcpServers": {
    "esp32sim": { "command": "npx", "args": ["-y", "esp32sim-mcp", "serve"] }
  }
}

その他のプラットフォーム

setupはmacOS arm64とLinux x64/arm64に、ビルド済みバイナリをインストールします。これらは、このリポジトリのエミュレータワークフローによって、署名済みビルド来歴（gh attestation verify <archive> -R stramanu/esp32sim-mcp）付きでソースからビルドされます。それ以外の環境では、Cargoを使ってesp32simをビルドしてください（rustup）。このリリースのテスト対象となったコミットに固定されています：

cargo install --locked --git https://github.com/mikroverk/esp32sim --rev f535f3b42293a76ab64c231a0425f35857ab6cf1 esp32sim
npx esp32sim-mcp fetch-roms

ESP32SIM_PATHは別の場所にあるエミュレータバイナリを、ESP32SIM_ROM_DIRは別のROMディレクトリを指定します。ESP-IDFのインストール内にあるROMは自動的に検出されます。

比較

esparagus は次の自然なステップです。まず esp32sim-mcp でシミュレーションし、その後、実際のボードで確認します。

制限事項

• エミュレーターはシリコンではありません。esp32sim がモデル化していない周辺機器、RF のタイミング、Bluetooth は対象外です。出荷前にハードウェアで確認してください。
• エージェント自身がファームウェアをビルドします（ローカルまたは Docker で idf.py を使用）。MCP サーバーはコンパイルを行いません。
• Windows でのテストは行われていません。

貢献

Issue やプルリクエストを歓迎します。開発環境のセットアップと、実際のエミュレーターを使ったエンドツーエンドテストの実行方法については CONTRIBUTING.md を、変更内容については CHANGELOG.md をご覧ください。

クレジット

• Joakim Eriksson、Alice、Mattia Fiumara による esp32sim：実際の処理を担うエミュレーター（MIT）。
• Espressif：ESP-IDF とマスク ROM の ELF（Apache-2.0）。
• Model Context Protocol。

ライセンス

MIT © Emanuele Strazzullo