Tech Teardown 026｜esp32-iphone-agent：7ドルのESP32でAIがリアルiPhoneを操作

10月11日、個人開発者onehumanbeingがGitHubでesp32-iphone-agentをオープンソース化しました。4日間で2418★、322 forksに達しました（GitHub API、10-16スナップショット）。その人気はほとんどすべてGitHubのトレンドや技術コミュニティからの転送によるものです。Hacker Newsでのストーリーには2件のいいねと0件のコメントしかありません（Algoliaで確認）。拡散力が弱い点をまず明確にしておきます。プロジェクト自体の魅力は一言で言えます：約7ドルのESP32-S3開発ボードを「目」と「手」として使用し、AIの脳を同じiPhoneアプリ内で動作させ、視覚モデルを使って実際のiPhoneを操作します。コンピューターや越狱、開発者アカウントは必要ありません。MITライセンスです。この記事では従来の方法で6つのセクションに分けて解説します。

一、それは何か

iPhoneのスクリーンモニタリングリストには「ESP32 Agent」という受信機が追加されます。これはボード自体が起動するWi-Fiホットスポットと内蔵のAirPlay受信機です。iPhoneがスクリーンモニタリングをボードに送信すると、ボードはデコードせず、H.264をBLEを通じて同じiPhone上のアプリに転送します。アプリはスクリーンショットをOpenAI対応の視覚モデルに送信し、モデルが動作を決定し、指示はBLEを通じてボードに戻されます。ボードは標準のUSB HIDマウスとキーボードとしてiPhoneに接続し、システムに搭載されているAssistiveTouchを使ってクリックやスライド操作を行います。目、手、脳の3つで構成され、ハードウェアコストは約7ドルのボード、ソフトウェアコストは自作のアプリです。

同種のプロジェクトと比較すると、その差別化された位置が明確になります。boboabw/phone-agentは最も近い例です：ESP32-S3のBluetooth HID、AssistiveTouch、iPhoneアプリを脳として使用していますが、「目」がありません。モデルは画面を見ることができません。VersaiOSはコンピューター上でUxPlayを使ってモニタリングを行い、1台のコンピューターが必要であり、1つの指示は一度しか実行されません。ja1chen/actellはApple CoreDeviceのデバッグチャネルを利用し、開発者モードとDeveloper Disk Imageが必要です。mobile-mcpやMidsceneのWebDriverAgent系プロジェクトはMacとコード署名が必要です。このプロジェクトのユニークな点は、AirPlay受信機もボードに搭載し、コンピューターを不要にした点です。

二、リポジトリ構造

まず簡単な調査をしてみましょう：GitHub上の言語タグと実際の実装内容は一致していません。ローカルでの統計では（.gitファイルを除く190ファイル）、Swiftには11621行があり、これが最も多く使われている部分で、ios/ディレクトリ内のappに関連しており、13個のテストファイルも含まれています。C言語は2793行のみで、hardware/ディレクトリに集中しており、主にUxPlayから移植されたAirPlay受信機とplayfairのFairPlay認証実装に関連しています。C++の800行はESP32ファームウェアのHIDブリッジに関するものです。Pythonの1793行はserver/ディレクトリ内にありますが、CHANGELOGには「server/はもう必要ない」と明記されており、これはv0.1.0のコンピュータ版に残っているもので、活発なコードとは見なすべきではありません。これは025回のpg_vectorsearchの分解時に遭遇した言語タグの不一致と同じ現象です。

アーキテクチャの進化は、このプロジェクトで最も見る価値のあるナラティブです。v0.1.0はコンピュータ版のソリューションで、UxPlayとPythonサーバー、Web UIを組み合わせています。ESP32はWi-Fi上のUSB HIDブリッジに過ぎず、MacまたはLinuxコンピュータが中継役である必要があります。現在のmainブランチは「コンピュータの消失」というリファクタリングを完了しています：ボード自体がAirPlay受信機として機能し、自作のホットスポットを作り、BLEを通じて新しいiPhoneアプリと通信します。プロンプトはprompts/ディレクトリに収集され、製品名はESP32 Agentとなります。4日間で2400星を獲得しましたが、これはこの極簡素な形態のためです。

もう一つの正直な数字：コミットの総数は29件で、contributors APIからは単一の主要な貢献者が返されます。これは個人プロジェクトであり、コミュニティプロジェクトではありません。

三、メカニズムの分解

3つの重要なメカニズムを一つずつ分解します。

第一はBLEビデオの透過転送です。このボードの計算能力は低いため、H.264の硬式解像度は実現不可能です。作者の選択は、AirPlayから受け取ったH.264ストリームをそのままチャンクに分割し、BLE通知を通じてスマートフォンに転送し、解像度の処理はiPhoneが自ら行うことです。docs/ble-protocol.mdには非常に規則的な記述があります：このボードはBLEペリフェリアであり、1つのサービス下に5つの特性値が付属しています。cmdはコマンドラインを受信し、replyは結果を返し、statusは毎秒1回のJSONハートビットを送信します（アプリのバックエンドでの活性化も兼ねています）。videoはH.264チャンクを送信し、netは暗号化されたチャネルを通じてネットワークに接続します。セキュリティのためLE Secure Connectionsを使用し、bondingを行います。videoチャネルの各通知には16ビットのシーンナンバーとフラグが含まれており、アプリはシーンナンバーの欠けを検出してパケットの損失を判断します。パケットが失われた場合は、次のIDRキーフレームで再び整列します。streamモードでは800ミリ秒を超えるPフレームは直接スキップされ、帯域幅が不足している場合は自動的にキーフレームのみを送信し、蓄積による遅延を避けます。statusの毎秒のハートビットも見る価値があります。1行のJSONには、実行時間、リセット原因、ヒープとPSRAMの残量、USB状態、ホットスポットの接続数、現在のコーデックレート、実際のフレームレート、BLEのMTUと物理層速度、パケット損失のカウントが含まれており、これによりデータパス全体の健康状態をアプリにリアルタイムで提供しています。MTUが低すぎる場合は、ファームウェアが自動的に簡素化されたオブジェクトを送信し、statusを読み取ることで完全な情報を得ることができます。送信の優先順位も定められています：replyとstatusは常にvideoの前に配置され、videoはコントローラ内で最大8つのACLパケットしか圧縮できません。これにより、コマンドはビデオストリームによって飢え死にすることはありません。ファームウェアにはcoexコマンドもあり、Wi-FiとBLEのRF共存の好みを調整します。これら2つが同じアンテナを使用する場合、ESP32-S3ではこの設定を行う際に避けられないエンジニアリングの詳細があります。デフォルトでは、起動時には常にバランス状態に戻ります。

第二は指針の校正に関するフィードバックループです。USB HIDマウスはiOSでは相対位置で動作し、モデルが提供するのはスクリーンショット上の絶対座標です。その間には漂移があり、指針の現在の位置はアプリが過去の移動量を計算することでしか推定できず、誤差が蓄積されます。作者の解決策は、校正をアクティビティとして実行することです：アプリは指針を継続的に追跡し、スクリーンの角で「位置を復元」します。正確なタッチ前にwiggleを行い、指針を揺らし、最新のスクリーンショットで視覚モデルを使用して位置を特定し、計算の誤差を修正した後で位置を決定します。actor.mdではtapコマンドにpreciseパラメータが含まれており、小さな目標と密集した要素（リスト行、スイッチ、チェックボックス）は1秒遅れるがより正確な経路を使用します。各アクションの後でスクリーンが安定するまで待ち、スクリーンに変化がないかモデルにフィードバックします。変化がなければ、そのタッチは正確ではなかったことを意味し、モデルは成功を仮定してはならず、再び狙いを定めるか別の方法を選択する必要があります。ボード、ホットスポット、またはミラーが切断された場合はタスクを一時停止し、復帰後は同じステップから続けます。READMEではこれをself-healingと呼んでいます。

第三はヒントワードエンジニアリングで、これがプロジェクト全体で最も参考になる部分です。planner.mdでは、モデルに目標と現在の画面に基づいて最大6ステップの計画を記述するよう求めており、見たもののみを基にして、見たことのないアカウント、メールアドレス、ログインページを捏造することはありません。actor.mdではさらに詳細で、出力はTHINKとDOの2つのセクションで構成され、THINKでは非技術的なユーザーでも理解できる英語で前のステップが有効かを確認する必要があります。座標は0から1000までの整数です。核心的な規律は「行動する前に見る」であり、画面に実際に存在するものだけを記述し、スクリーンショットで見える要素のみをタップします。swipeには慣性がなく、100から250の単位の短いスワイプと検査結果を確認することを好みます。時間のスライダーはまず中央行をクリックしてから直接数字を入力します（例：0700を入力）。リスト検索では、1ページ未満でスクロールし、各項目を見終わったら両端までスクロールしていない場合は失敗し、最も近いオプションを報告します。アクションセットにはtap、swipe、path（2から20の連続した点で、ペイントに使用される）、circle、type、key、home、back、wait、replan、done、failが含まれます。このヒントワードは、「視覚エージェントがGUIを信頼性を持って操作する方法」のほぼすべての問題を事前に定義しています。

iPhoneがなぜチェックボードを合法的なAirPlayターゲットとして認識するかについては、hardware/内のplayfairコード（omg_hax.c、hand_garble.c、sap_hash.cなど）はUxPlayから移植されたFairPlayペアリング認証の逆実装であり、そのルーツと表現方法は「移植/逆転換」として理解されています。UxPlay自体は有名なオープンソースのAirPlayレシーバープロジェクトです。

四、数字と検証

ハードウェアのリストは非常に短いです：著者はSeeed Studio XIAO ESP32S3の通常版を使用して検証を行い、8MBのPSRAMで、約7ドルです。READMEには、ネイティブUSB（USB-Cポート）とPSRAMを持つESP32-S3であれば使用可能であると記載されています。ミラーはデフォルトで480×1040、5fpsで、resとfpsコマンドで変更でき、NVSに保存されます。BLEの実際の帯域幅は約300から500kbpsで、これが解像度とフレームレートの上限です。エージェントの各ステップは数秒かかり、大部分はモデルの推論に費やされます。アプリが動作する際、スマートフォンのWi-Fiはボードのホットスポットに接続されており、インターネットはありません。モデル呼び出しは携帯電話の携帯データを使用します。

制限リストはREADMEの原文に記載されており、売り点リストよりも長いですが、そのまま記録します：BLEの帯域幅によりミラーが小さく、フレームレートが低くなります。iOSではパスワード入力、Apple Pay、DRMビデオのミラーが行われず、画面ロック時にはミラーが停止します。これらの状況ではエージェントは機能しません。アプリは私有のiOS API（suspend）を使用してバックグラウンドで常駐し、自作でも問題ありませんが、App Storeに登録する前に必ず置き換えなければなりません。キーボード入力はASCIIのみです。横画面のアプリはサポートされていません。Roadmap上で未完了の項目には、横画面、非ASCII入力（例えば中国語のピンイン）、単一のモデル呼び出しで複数のアクションを高速化することがあります。バージョン要件はiOS18以上で、システム更新に敏感です。

検証の次元にさらに3つの数値を追加：HN story 2▲ 0コメント、伝播力が弱いのは事実；29のコミット、単一の主要貢献者、持続性は観察中；ios/ディレクトリには13のテストファイルがあり、この程度のプロジェクトは抑制的かつ真剣だ。READMEには「Responsible use」というセクションもあり：自動化されるのは、あなたが所有しているまたは許可されたデバイスとアカウントのみ、エージェントはあなたの手で動作し、実行時には注意深く監視し、停止ボタンは手元に置いておく。

五、判断

3点について言及する価値がある。

第一に、これは工学的な技巧による解決であり、強引なハッキングではない。全体のソリューションはiOSのどのセキュリティ境界にも触れていない：AirPlayモニタリングはシステム機能、USB HIDは標準的な外部デバイスプロトコル、AssistiveTouchはバリアフリー機能であり、「モデルのクリック意図」を「iOSが受け入れるマウス入力」と翻訳し、各ステップはシステムが許可するインターフェースを踏んでいる。playfairのFairPlay逆転はUxPlayの既存の公開実装から来ており、新しいアイデアではない。この「閉鎖されたエコシステム内の合法的な隙間に橋を架ける」というアプローチは、どんな脱獄ソリューションよりも長期的に維持可能な形に近い。

第二に、「弱いハードウェアでモデルを強化する」という分担は真似に値する。デバイスは何の知的な作業もせず、限られた帯域幅を持つパイプラインとして、忠実な手として機能するだけである；デコーディング、視覚処理、計画はすべてスマートフォンとクラウドで行われる。BLE透過通信はデコーディングせず、wiggleによる校正は相対的なポインタを調整し、各ステップで画面の変化をフィードバックする。これら3つのメカニズムは同じ問題を解決している：信頼できないチャネル上で信頼性の高いフィードバックループを構築する方法。デバイス側のエージェントを作る人は直接参考にでき、prompts/actor.mdはそのまま利用することもできる。

第三に、境界を明確にする必要がある。単独プロジェクト、29のコミット、HN上でのほとんど無名、starの急増は「7ドルで本物のiPhoneを操作する」というストーリーの伝播力によるものであり、コミュニティやビジネスの支援があるわけではない。iOSの各大きなバージョンではAssistiveTouchやAirPlayの動作が変更される可能性があり、プライベートAPIの常時実行は潜在的なリスクである。これは精巧な個人プロジェクト実験であり、評価する際には「オープンソースインフラ」という基準ではなく、この基準を用いるべきである。

ちょっとした観察：READMEには6つの制限が目立つ場所に記載されており、作者はプロジェクトを汎用のソリューションとして宣伝していない。制限リストが長いREADMEは、通常、健全なオープンソースプロジェクトの兆候である。

六、誰がどのように使用できるか

適した人物：iPhone（iOS 18以上）とネイティブUSBおよびPSRAMを搭載したESP32-S3を持ち、自らiOSアプリをコンパイルする意志がある人（Xcodeと無料のApple IDのダウンロードが必要で、有料の開発者アカウントは不要）、そして「視覚モデルを実機で操作するGUI」という方向性を研究したい開発者や愛好家。自動化処理を行う前に、「Responsible use」を一度読んでください：自動化されるのは、あなたが所有しているまたは許可されたデバイスとアカウントのみ、タスクを実行する際には離れないようにしてください。

実行方法はREADMEに従います：ハードウェアやファームウェアを書き込み、ボードにホットスポットを設置した後、iPhoneのスクリーンモニターでESP32 Agentを選択し、USBケーブルを接続してAssistiveTouchを起動します。アプリでコードをスキャンするかペアリングしてBLEに接続します。OpenAI対応のビジュアルモデルのエンドポイントを入力すると、指示を出すことができます。毎回実行すると携帯電話に残り、順番に再生できます。タップやスワイプは対応するスナップショットに表示され、復習が非常に便利です。バックグラウンドで実行中もリングアイドルで進捗を表示し、Live Activity、Widgets、Siri、Shortcutsも利用できます。

実際に手を動かす予定がない人でも読む価値のある2つのファイルがあります：docs/ble-protocol.mdは、UUIDの割り当て、ハートビートによるアイドル状態の維持、パケットの復旧、RF周波数の共存まで詳細に記述したBLEプライベートプロトコルの教科書級の文書です；prompts/ディレクトリには、GUIエージェントの操作規則を詳細に記述した公開プロンプトが含まれています。これら2つのファイルの価値は、プロジェクト自体の持続可能性によって変動しません。

情報源

• リポジトリの情報（2418★/322フォーク/作成とプッシュ時間/MIT/topic）：GitHub API repos/onehumanbeing/esp32-iphone-agent, 10-16スナップショット
• コードの規模（190ファイル、Swift 11621行、C 2793行、C++ 800行、Python 1793行）：ローカル浅いクローン/tmp/eia-1016, find+wcによる拡張子別の統計、GitHub以外の言語タグなし
• アーキテクチャとデータフロー、制限リスト、責任ある使用、ハードウェアBOM、同種プロジェクトの比較：README（中国語版README.zh-CN.mdを含む）原文
• BLEプロトコルの詳細（5つのフィーチャー値、シーケンスパケットの失われ方、800msのPフレームスキップ、coex、NVSストレージ）：docs/ble-protocol.md
• プロンプトの規則：prompts/planner.md、prompts/actor.md原文
• アーキテクチャの進化（v0.1.0コンピューター版からmain「コンピューターが消える」）：CHANGELOG
• playfair/UxPlayのルート：hardware/hid_bridge/src/airplay/playfair/ディレクトリとCHANGELOG「ported from UxPlay」に記載
• HNの拡散力（story 50102527、2▲0コメント）：HN Algoliaで確認
• 貢献者の分布とコミット数の合計（29）：GitHub contributors APIとcommits Link header