Xây dựng tác nhân iPhone tích hợp AI với ESP32-S3

ESP32 iPhone Agent thực hiện được những gì

ESP32 iPhone Agent cho phép một mô hình AI quan sát và điều khiển một chiếc iPhone thực. Công cụ này sử dụng tính năng phản chiếu màn hình AirPlay để nhận dữ liệu hình ảnh và một bo mạch ESP32-S3 giá rẻ làm chuột và bàn phím USB. Vì tương tác thông qua màn hình và con trỏ, công cụ không yêu cầu Xcode, tài khoản nhà phát triển Apple, jailbreak, Developer Mode hoặc ứng dụng hỗ trợ được cài trên điện thoại.

Máy tính có thể chạy macOS hoặc Linux. Máy tính này lưu trữ UxPlay, máy chủ Python, giao diện web và kết nối đến một mô hình thị giác tương thích với OpenAI. ESP32-S3 kết nối với máy tính qua Wi-Fi, đồng thời được iPhone nhận diện như một thiết bị giao diện người dùng USB tiêu chuẩn.

Cách hệ thống hoạt động

AirPlay cung cấp khả năng quan sát

iPhone phản chiếu màn hình đến UxPlay trên máy tính. Một pipeline GStreamer chuyển luồng này thành các khung hình JPEG, được cả tác nhân AI và chế độ xem trực tiếp trên trình duyệt sử dụng.

ESP32-S3 cung cấp khả năng điều khiển

Khi kết nối với iPhone, bo mạch hoạt động như một chuột và bàn phím USB. Khi bật AssistiveTouch trên iOS, thao tác nhấp chuột trở thành thao tác chạm, kéo con trỏ trở thành thao tác vuốt, con lăn dùng để cuộn giao diện, còn lệnh bàn phím có thể nhập văn bản hoặc nhấn phím tắt.

Firmware cố ý chứa rất ít logic. Máy chủ gửi các lệnh theo từng dòng như move, click, scroll, type và key qua TCP. Bo mạch phản hồi bằng ok hoặc thông báo lỗi.

Bộ lập kế hoạch và bộ thực thi cung cấp khả năng suy luận

Mô hình lập kế hoạch tạo một kế hoạch ngắn dựa trên mục tiêu được yêu cầu và màn hình hiện tại. Mô hình thực thi kiểm tra từng ảnh chụp màn hình mới và chọn hành động tiếp theo, chẳng hạn như chạm, vuốt, vẽ đường đi, nhập văn bản, nhấn phím, quay về màn hình chính hoặc hoàn tất. Cùng một mô hình thị giác có thể đảm nhiệm cả hai vai trò.

Kiểm tra vòng kín giúp tăng độ tin cậy

Chuyển động của con trỏ mang tính tương đối, vì vậy máy chủ theo dõi vị trí ước tính của con trỏ. Trước khi chạm, máy chủ có thể lắc nhẹ con trỏ, xác định vị trí của nó trong hình ảnh được phản chiếu, sửa lỗi lệch và tinh chỉnh hiệu chuẩn. Sau một hành động, tác nhân kiểm tra xem màn hình có thay đổi hay không. Nhờ đó, các hành động bị bỏ lỡ có thể được phát hiện và thử lại thay vì trở thành cơ sở cho các bước tiếp theo.

Hệ thống cũng có thể lập kế hoạch lại sau các hành động lặp lại và khôi phục từ các liên kết bị ngắt hoặc phản hồi không hợp lệ từ mô hình. Nếu kết nối Wi-Fi bị ngắt, bo mạch sẽ nhả các nút chuột và tự động kết nối lại.

Tính năng chính

• Không cần thiết lập phát triển Apple: không yêu cầu Xcode, tài khoản nhà phát triển, ký mã, Developer Mode hoặc ứng dụng chạy thử.
• Tương thích với nhiều ứng dụng: tác nhân hoạt động trên các điểm ảnh thay vì phụ thuộc vào cây trợ năng, nên có thể làm việc với các ứng dụng và trò chơi thông thường.
• Máy chủ macOS hoặc Linux: máy chủ không bị giới hạn ở macOS.
• Hỗ trợ mô hình linh hoạt: có thể sử dụng bất kỳ API trò chuyện tương thích với OpenAI nào chấp nhận hình ảnh.
• Điều khiển thủ công và tự động: giao diện web hỗ trợ chạm, vuốt, cuộn, nhập văn bản, Home, Back trực tiếp và các tác vụ do AI điều khiển.
• Giám sát quá trình thực thi: giao diện hiển thị màn hình điện thoại trực tiếp, kế hoạch, nhật ký, ảnh chụp màn hình, hành động, quá trình suy luận và thông tin thời gian.
• Kiểm soát an toàn: nút dừng khẩn cấp sẽ dừng tác nhân và nhả con trỏ.

Những gì bạn cần

• Bo mạch ESP32-S3: dự án đã được thử nghiệm với Seeed Studio XIAO ESP32S3 nguyên bản. Một bo mạch ESP32-S3 khác cũng có thể hoạt động nếu cổng USB-C được kết nối với giao diện USB gốc của chip.
• iPhone: các mẫu USB-C có thể kết nối trực tiếp. Các mẫu Lightning cần bộ chuyển đổi Lightning sang USB Camera.
• Máy tính: máy Mac hoặc Linux trong cùng mạng với iPhone.
• Wi-Fi: cấu hình bo mạch yêu cầu tên và mật khẩu mạng 2.4 GHz.
• Mô hình thị giác: một endpoint tương thích với OpenAI trên đám mây hoặc cục bộ, có thể nhận dữ liệu hình ảnh.

iPhone cấp nguồn cho bo mạch. Nếu điện thoại cần sạc đồng thời, hãy sử dụng hub USB-C có chức năng truyền nguồn.

Cài đặt và cấu hình tác nhân

1. Sao chép repository

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

2. Chuẩn bị và nạp firmware cho ESP32-S3

Cài đặt arduino-cli và ESP32 core 3.x. Kết nối ESP32-S3 với máy tính qua USB, sao chép tệp secrets mẫu và chỉnh sửa tệp mới.

cp hardware/hid_bridge/secrets.example.h hardware/hid_bridge/secrets.h

Trong hardware/hid_bridge/secrets.h, nhập tên mạng Wi-Fi 2.4 GHz, mật khẩu Wi-Fi và địa chỉ IP của máy tính sẽ chạy máy chủ. Sau đó nạp firmware cho bo mạch:

hardware/flash.sh

Tùy chọn, tập lệnh nạp firmware chấp nhận cổng nối tiếp và cờ --debug. Firmware gỡ lỗi sẽ lặp lại các lệnh và thời lượng của chúng qua cổng nối tiếp USB.

3. Cài đặt UxPlay

Trên macOS, cài đặt UxPlay bằng Homebrew:

brew install uxplay

Trên Debian hoặc Ubuntu, cài đặt UxPlay và các gói GStreamer cần thiết:

sudo apt install uxplay gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-libav

4. Tạo môi trường Python

Truy cập thư mục máy chủ, tạo môi trường ảo và cài đặt dự án:

cd server
python3 -m venv .venv
.venv/bin/pip install -e .

Yêu cầu Python 3.10 trở lên.

5. Cấu hình mô hình

Sao chép mẫu môi trường:

cp .env.example .env

Chỉnh sửa server/.env và đặt ít nhất endpoint tương thích với OpenAI, tên mô hình và khóa API:

LLM_BASE_URL=https://your-endpoint.example/v1
LLM_MODEL=your-vision-model
LLM_API_KEY=your-api-key

Mô hình được chọn phải hỗ trợ hình ảnh. Chỉ cần dùng API đám mây; chạy mô hình cục bộ là tùy chọn.

6. Khởi động máy chủ

set -a && . ./.env && set +a && .venv/bin/python -m hidagent

Mở http://<computer-ip>:8890 trong trình duyệt. IP của máy tính phải có thể truy cập từ mạng mà bo mạch sử dụng.

Thiết lập iPhone

Thông thường, cấu hình điện thoại sau đây chỉ cần thực hiện một lần:

1. Mở Cài đặt, sau đó vào Trợ năng, Cảm ứng và AssistiveTouch.
2. Bật AssistiveTouch.
3. Ngắt kết nối bo mạch đã được nạp chương trình khỏi máy tính rồi cắm vào iPhone.
4. Xác nhận rằng con trỏ tròn xuất hiện và trang web hiển thị bộ điều khiển đã kết nối.
5. Mở Trung tâm điều khiển trên iPhone và chọn Phản chiếu màn hình.
6. Chọn iPhone Agent. Màn hình điện thoại trực tiếp sẽ xuất hiện trong giao diện web.
7. Trong giao diện web, mở Điều khiển thủ công và chọn Hiệu chỉnh.
8. Nhấp chính xác vào con trỏ đang hiển thị trên màn hình trực tiếp.

Hãy hiệu chỉnh lại nếu sau đó bạn thay đổi tốc độ theo dõi của AssistiveTouch.

Chạy tác vụ đầu tiên

Nhập mục tiêu trong giao diện web và nhấn Bắt đầu. Ví dụ:

Open Settings and go to Wi-Fi

Bộ lập kế hoạch tạo một kế hoạch ngắn, còn tác nhân liên tục kiểm tra ảnh chụp màn hình hiện tại và chọn một hành động. Hãy theo dõi chế độ xem điện thoại trực tiếp và nhật ký trong khi tác vụ chạy.

Bảng bước lưu ảnh chụp màn hình được sử dụng cho mỗi quyết định. Bảng cũng vẽ thao tác chạm hoặc vuốt đã chọn lên hình ảnh và hiển thị phần suy luận cùng thời gian thực hiện của mô hình. Chọn một thẻ bước để mở chế độ xem lớn hơn.

Sử dụng điều khiển thủ công

• Nhấp vào hình ảnh điện thoại trực tiếp để chạm tại vị trí đó.
• Kéo trên hình ảnh để thực hiện thao tác vuốt.
• Sử dụng thao tác cuộn để cuộn trên điện thoại.
• Sử dụng các điều khiển được cung cấp cho Màn hình chính, Quay lại, nhập văn bản và các phím.

Nếu tác nhân hoạt động bất thường, hãy kích hoạt Dừng khẩn cấp hoặc nhấn Esc. Thao tác này sẽ dừng quá trình chạy và giải phóng con trỏ. Giao diện cũng cung cấp điều khiển để xóa lịch sử thực thi.

Tùy chọn cấu hình quan trọng

• LLM_BASE_URL: endpoint tương thích với OpenAI. Mặc định là http://localhost:8000/v1.
• LLM_MODEL và LLM_API_KEY: tên mô hình và thông tin xác thực API.
• LLM_EXTRA_BODY: JSON được gộp vào mọi yêu cầu mô hình, chẳng hạn các tùy chọn tắt chế độ suy nghĩ của mô hình.
• ACTOR_* và PLANNER_*: tùy chỉnh theo vai trò cho các thiết lập LLM_* tương ứng.
• AIRPLAY_NAME: tên bộ thu hiển thị trong danh sách Phản chiếu màn hình của iPhone. Mặc định là iPhone Agent.
• PORT: cổng giao diện web, mặc định là 8890.
• DEVICE_PORT: cổng được ESP32-S3 sử dụng, mặc định là 7300.
• HIDAGENT_DATA: thư mục lưu dữ liệu hiệu chỉnh và dấu vết, mặc định là ~/.hidagent.
• HIDAGENT_DEBUG: bật ghi nhật ký gỡ lỗi phía máy chủ khi được đặt thành 1.

Sử dụng nâng cao và khắc phục sự cố

Gán các mô hình riêng cho bộ lập kế hoạch và tác nhân

Bộ lập kế hoạch và tác nhân có thể dùng cùng một mô hình, nhưng các biến môi trường theo vai trò cho phép bạn ghi đè độc lập các thiết lập mô hình. Sử dụng dạng PLANNER_* và ACTOR_* của các biến LLM_* liên quan khi cần các endpoint hoặc mô hình riêng.

Kết nối máy chủ mô hình cục bộ

Có thể cấu hình mọi máy chủ tương thích với OpenAI có mô hình hỗ trợ hình ảnh theo cùng cách, bao gồm vLLM, SGLang, llama.cpp và Ollama. Dự án được phát triển và đo thời gian với NVIDIA Qwen3.8-Flash-Next-NVFP4, được cung cấp từ hai NVIDIA DGX Sparks bằng tính song song tensor.

Ví dụ cấu hình cho thiết lập đó:

LLM_BASE_URL=http://<dgx-spark-ip>:8888/v1
LLM_MODEL=Qwen3.8-Flash-Next
LLM_EXTRA_BODY='{"chat_template_kwargs": {"enable_thinking": false}}'

Thiết lập phát triển được báo cáo đạt khoảng 1,3 giây cho mỗi hành động và 2 giây cho mỗi kế hoạch khi tắt chế độ suy nghĩ. Các con số này mô tả cấu hình phần cứng và mô hình cụ thể đó, không phải tốc độ được đảm bảo cho các môi trường triển khai khác.

Bật thu thập dấu vết

Đặt giá trị sau trong server/.env:

HIDAGENT_DEBUG=1

Chế độ gỡ lỗi ghi nhật ký mọi lệnh của bo mạch và độ trễ tương ứng. Chế độ này cũng tạo một thư mục cho mỗi lần chạy tác nhân trong ~/.hidagent/traces/. Thư mục chứa steps.jsonl, bao gồm lời nhắc mô hình, phản hồi thô, số đo độ trễ và các hành động, cùng với ảnh chụp màn hình được các lệnh gọi mô hình quan sát.

Tìm hiểu giao thức của bo mạch

• ping thực hiện kiểm tra tình trạng hoạt động.
• home đưa con trỏ vào góc trên bên trái để xác lập vị trí đã biết.
• move <dx> <dy> di chuyển con trỏ tương đối với tốc độ không đổi.
• press, release và click điều khiển nút chuột trái.
• scroll <v> <h> gửi thao tác cuộn dọc và ngang.
• type <text> nhập văn bản ASCII.
• key <combo> gửi phím hoặc tổ hợp phím như enter, cmd+h hoặc cmd+space.

Khắc phục sự cố phát hiện AirPlay trên Linux

Nếu máy tính có nhiều giao diện mạng và iPhone không hiển thị bộ thu, hãy giới hạn quảng bá mDNS của Avahi trên giao diện được kết nối với mạng của điện thoại.

Giới hạn đã biết

• iOS không phản chiếu màn hình nhập mật mã, Apple Pay, video được bảo vệ bằng DRM và một số màn hình được bảo vệ khác, vì vậy tác nhân không thể nhìn thấy chúng.
• Phản chiếu màn hình dừng khi điện thoại khóa. Hãy tắt khóa tự động trong khi tác nhân đang chạy.
• Nhập văn bản bằng bàn phím chỉ hỗ trợ ASCII.
• Phải hiệu chỉnh lại con trỏ sau khi thay đổi tốc độ theo dõi của AssistiveTouch.
• Tác nhân phụ thuộc vào đường truyền mạng hoạt động giữa bo mạch và máy chủ, cũng như luồng AirPlay khả dụng giữa điện thoại và máy tính.

Vận hành có trách nhiệm

Chỉ tự động hóa các thiết bị và tài khoản thuộc sở hữu của bạn hoặc bạn được phép sử dụng, đồng thời tuân thủ các điều khoản của những ứng dụng liên quan.

Vì tác nhân có thể thực hiện các kiểu thao tác đầu vào giống như con người, hãy giám sát các phiên chạy đang hoạt động và luôn để nút dừng khẩn cấp trong tầm truy cập.

Kết luận

ESP32 iPhone Agent kết hợp tính năng phản chiếu AirPlay, cầu nối USB HID ESP32-S3 giá rẻ và mô hình thị giác tương thích với OpenAI để tự động hóa iPhone vật lý mà không cần bộ công cụ phát triển thông thường của Apple. Sau khi cấu hình firmware, máy chủ, điểm cuối mô hình, AssistiveTouch, tính năng phản chiếu và hiệu chỉnh con trỏ, bạn có thể đưa ra mục tiêu bằng ngôn ngữ tự nhiên, kiểm tra từng quyết định, can thiệp thủ công và thu thập dấu vết chi tiết để gỡ lỗi.