はじめてのiPhoneエージェントを作る

ESP32 iPhone Agentは、ESP32-S3を介して視覚モデルに実機のiPhoneを操作させるプロジェクトです。現在のバージョンではiPhoneアプリ上でエージェントが動作するため、実行中にパソコンは必要ありません。ただし、初回の導入にはMacとXcodeを使います。

用意するもの

PSRAMとネイティブUSBを備えたESP32-S3。動作確認に使われているのは、8 MB PSRAM搭載の通常版Seeed Studio XIAO ESP32S3です。
iOS 18以降のiPhoneとモバイルデータ通信。LightningモデルにはLightning - USBカメラアダプタも必要です。
XcodeをインストールしたMacと、アプリの署名に使うApple ID。
画像入力に対応したモデルAPI。OpenAI互換のChat APIを使用します。

iPhoneのWi-Fiはボードへのミラーリングに使用し、モデルへのリクエストはモバイル通信で送ります。購入前に必要な機材を確認してください。

リポジトリをクローンして、プロジェクトのディレクトリに移動します。特に記載がない限り、以降のコマンドもここで実行します。

git clone https://github.com/onehumanbeing/esp32-iphone-agent.git
cd esp32-iphone-agent

このガイドは現在の「iPhoneアプリ + ESP32-S3」構成が対象です。legacyブランチとv0.1.0タグはパソコン側のサーバーを使う旧構成なので、手順を混ぜないでください。

arduino-cli、ESP32 3.3.xのボードパッケージ、NimBLE-Arduino 2.5.1を準備します。データ通信対応のUSBケーブルでボードをMacに接続し、プロジェクトのスクリプトを実行します。

arduino-cli lib install "[email protected]"
hardware/flash.sh

ボードパッケージの導入やポートの指定はファームウェアの書き込みを参照してください。hardware/flash.shは映像転送に必要なBLEバッファ設定を適用するため、標準設定でのビルドに置き換えないでください。

ローカル設定をコピーし、作成されたファイルに自分の署名チームと固有のBundle IDを設定します。

cp ios/Config/Local.xcconfig.example ios/Config/Local.xcconfig
open ios/IPhoneAgent.xcodeproj

XcodeでIPhoneAgentスキームと接続中のiPhoneを選び、ビルドして実行します。無料のApple IDでも署名できますが、7日ごとの再署名が必要です。オプションの権限設定も含め、iOSアプリの導入で確認してください。

ボードをMacから外してiPhoneに接続し、ESP32 Agentを開きます。初回設定は次の順番です。

Plug Me In：ボードを検出してBluetoothでペアリングする。
Let Me See the Screen：ボードのWi-Fiに接続し、コントロールセンターの「画面ミラーリング」でESP32 Agentを選ぶ。
Let Me Use the Pointer：AssistiveTouchを有効にして、ポインタの自動調整を待つ。
Give Me a Brain：APIのアドレス、キー、画像対応モデルを設定する。

各接続の確認はボードと画面の接続、モデルの確認は視覚モデルの設定を参照してください。アプリの表示言語はウェブサイトと同じとは限らないため、照合できるよう英語のステップ名も記載しています。

まずは**「設定を開いてWi-Fiの画面に移動して」**など、結果が簡単に確認できる指示を試します。モデルや端末の表示によっては、英語の “Open Settings and go to Wi-Fi” も使えます。

Startを押し、ロックを解除したまま動作を見守ってください。停止するときは対応端末のDynamic Islandから、またはアプリに戻って操作します。

現在、キーボードはASCII文字のみ対応しています。日本語で指示できることと、他のアプリに日本語を入力できることは別です。最初は日本語入力を必要としないタスクを選びましょう。

Runsでステップを再生し、最後の画面を確認します。モデルの「完了」は成功の独立した検証ではありません。原因を調べる場合は実行記録をエクスポートできます。

途中で止まった場合は、トラブルシューティングで失敗した接続を確認してください。毎回すべてをインストールし直す必要はありません。