주요 콘텐츠로 건너뛰기
AI 튜토리얼

ESP32-S3로 AI 기반 iPhone 에이전트 구축하기

ESP32-S3 플래시 방법, UxPlay로 iPhone 미러링하기, OpenAI 호환 비전 모델 연결하기, 포인터 제어 보정하기, Xcode나 개발자 계정, 탈옥 또는 iPhone에 설치된 앱 없이 자동화 작업 실행하는 방법을 알아보세요.

약 14분 소요
ESP32-S3로 AI 기반 iPhone 에이전트 구축하기

ESP32 iPhone Agent의 기능

ESP32 iPhone Agent를 사용하면 AI 모델이 실제 iPhone의 화면을 보고 조작할 수 있습니다. 시각적 입력에는 AirPlay 화면 미러링을 사용하고, 저렴한 ESP32-S3 보드를 USB 마우스와 키보드로 활용합니다. 화면과 포인터를 통해 상호작용하므로 Xcode, Apple 개발자 계정, 탈옥, 개발자 모드 또는 iPhone에 설치하는 보조 앱이 필요하지 않습니다.

ESP32 iPhone Agent 인터페이스와 연결된 iPhone

컴퓨터는 macOS 또는 Linux에서 실행할 수 있습니다. 컴퓨터에서 UxPlay, Python 서버, 웹 인터페이스 및 OpenAI 호환 비전 모델 연결을 실행합니다. ESP32-S3는 Wi-Fi를 통해 컴퓨터에 연결되며, iPhone에서는 표준 USB 휴먼 인터페이스 장치로 인식됩니다.

시스템 작동 방식

AirPlay가 시각 정보를 제공합니다

iPhone은 컴퓨터의 UxPlay로 화면을 미러링합니다. GStreamer 파이프라인은 이 스트림을 JPEG 프레임으로 변환하며, 이 프레임은 AI 에이전트와 브라우저 기반 실시간 화면 보기에 모두 사용됩니다.

ESP32-S3가 조작을 담당합니다

iPhone에 연결하면 보드는 USB 마우스와 키보드처럼 작동합니다. iOS AssistiveTouch를 활성화하면 마우스 클릭은 탭으로, 포인터 드래그는 스와이프로, 스크롤 휠은 화면 스크롤로 동작합니다. 키보드 명령으로 텍스트를 입력하거나 단축키를 누를 수도 있습니다.

펌웨어에는 의도적으로 로직을 거의 넣지 않았습니다. 서버는 TCP를 통해 move, click, scroll, type, key와 같은 줄 단위 명령을 전송합니다. 보드는 ok 또는 오류 메시지로 응답합니다.

플래너와 액터가 두뇌 역할을 합니다

플래너 모델은 요청된 목표와 현재 화면을 바탕으로 짧은 계획을 만듭니다. 액터 모델은 새 스크린샷을 확인하고 탭, 스와이프, 경로 그리기, 입력, 키 누르기, 홈 화면으로 돌아가기 또는 작업 완료와 같은 다음 동작을 선택합니다. 동일한 비전 모델을 두 역할에 모두 사용할 수 있습니다.

폐쇄 루프 확인으로 안정성을 높입니다

포인터 이동은 상대적이므로 서버는 추정 위치를 추적합니다. 탭하기 전에 포인터를 조금 움직이고, 미러링된 이미지에서 포인터 위치를 찾은 다음, 빗나간 위치를 보정하고 캘리브레이션을 개선할 수 있습니다. 동작 후에는 에이전트가 화면이 변경되었는지 확인합니다. 따라서 동작이 빗나가도 이를 감지하고 재시도할 수 있어 이후 단계의 오류로 이어지는 것을 방지합니다.

반복 동작 후에는 시스템이 계획을 다시 수립할 수 있으며, 연결 끊김이나 잘못된 모델 응답에서도 복구할 수 있습니다. Wi-Fi 연결이 끊기면 보드는 마우스 버튼을 해제하고 자동으로 다시 연결합니다.

주요 기능

  • Apple 개발 환경 불필요: Xcode, 개발자 계정, 코드 서명, 개발자 모드 또는 테스트 실행 앱이 필요하지 않습니다.
  • 폭넓은 앱 호환성: 접근성 트리에 의존하지 않고 픽셀을 기반으로 조작하므로 일반 앱과 게임 전반에서 사용할 수 있습니다.
  • Mac 또는 Linux 호스트: 서버가 macOS로 제한되지 않습니다.
  • 유연한 모델 지원: 이미지를 허용하는 모든 OpenAI 호환 채팅 API를 사용할 수 있습니다.
  • 수동 및 자율 제어: 웹 인터페이스에서 직접 탭, 스와이프, 스크롤, 입력, 홈, 뒤로 가기 및 AI 기반 작업을 지원합니다.
  • 실행 과정 확인: 인터페이스에 실시간 휴대폰 화면, 계획, 로그, 스크린샷, 동작, 추론 및 시간 정보가 표시됩니다.
  • 안전 제어: 비상 정지 기능으로 에이전트를 중지하고 포인터를 해제할 수 있습니다.

필요한 준비물

  • ESP32-S3 보드: 이 프로젝트는 별도 부품이 없는 Seeed Studio XIAO ESP32S3로 테스트되었습니다. USB-C 포트가 칩의 네이티브 USB 인터페이스에 연결되는 다른 ESP32-S3 보드도 사용할 수 있습니다.
  • iPhone: USB-C 모델은 직접 연결할 수 있습니다. Lightning 모델에는 Lightning-USB 카메라 어댑터가 필요합니다.
  • 컴퓨터: iPhone과 동일한 네트워크에 연결된 macOS 또는 Linux 컴퓨터가 필요합니다.
  • Wi-Fi: 보드 설정에는 2.4GHz 네트워크 이름과 비밀번호가 필요합니다.
  • 비전 모델: 이미지 입력을 허용하는 클라우드 또는 로컬 OpenAI 호환 엔드포인트가 필요합니다.

iPhone이 보드에 전원을 공급합니다. 휴대폰을 동시에 충전해야 한다면 전원 패스스루를 지원하는 USB-C 허브를 사용하세요.

에이전트 설치 및 구성

1. 저장소 복제

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

2. ESP32-S3 준비 및 플래시

arduino-cli와 3.x ESP32 코어를 설치합니다. ESP32-S3를 USB로 컴퓨터에 연결하고, 예제 비밀 설정 파일을 복사한 다음 새 파일을 편집합니다.

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

hardware/hid_bridge/secrets.h에 2.4GHz Wi-Fi 네트워크 이름, Wi-Fi 비밀번호 및 서버를 실행할 컴퓨터의 IP 주소를 입력합니다. 그런 다음 보드를 플래시합니다.

hardware/flash.sh

플래시 스크립트에는 선택적으로 시리얼 포트와 --debug 플래그를 지정할 수 있습니다. 디버그 펌웨어는 명령과 실행 시간을 USB 시리얼로 에코합니다.

3. UxPlay 설치

macOS에서는 Homebrew로 UxPlay를 설치합니다.

brew install uxplay

Debian 또는 Ubuntu에서는 UxPlay와 필요한 GStreamer 패키지를 설치합니다.

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

4. Python 환경 생성

서버 디렉터리로 이동하고 가상 환경을 생성한 다음 프로젝트를 설치합니다.

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

Python 3.10 이상이 필요합니다.

5. 모델 구성

환경 템플릿을 복사합니다:

cp .env.example .env

server/.env를 편집하고 OpenAI 호환 엔드포인트, 모델 이름, API 키를 최소한 다음과 같이 설정합니다:

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

선택한 모델은 이미지를 지원해야 합니다. 클라우드 API로 충분하며 로컬 모델 실행은 선택 사항입니다.

6. 서버 시작

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

브라우저에서 http://<computer-ip>:8890을 엽니다. 컴퓨터 IP는 보드가 연결된 네트워크에서 접근할 수 있어야 합니다.

iPhone 설정

다음 휴대폰 설정은 일반적으로 한 번만 필요합니다:

  1. 설정을 열고 손쉬운 사용, 터치, AssistiveTouch로 이동합니다.
  2. AssistiveTouch를 켭니다.
  3. 플래시한 보드를 컴퓨터에서 분리하고 iPhone에 연결합니다.
  4. 둥근 포인터가 나타나고 웹 페이지에 컨트롤러가 연결된 것으로 표시되는지 확인합니다.
  5. iPhone에서 제어 센터를 열고 화면 미러링을 선택합니다.
  6. iPhone Agent를 선택합니다. 웹 인터페이스에 휴대폰 화면이 실시간으로 표시됩니다.
  7. 웹 인터페이스에서 수동 제어를 열고 보정을 선택합니다.
  8. 실시간 화면에 표시된 포인터를 정확히 클릭합니다.

나중에 AssistiveTouch 추적 속도를 변경하면 다시 보정합니다.

첫 번째 작업 실행

웹 인터페이스에 목표를 입력하고 시작을 누릅니다. 예를 들면 다음과 같습니다:

설정을 열고 Wi-Fi로 이동

플래너가 짧은 계획을 만들고, 액터가 현재 스크린샷을 반복해서 확인하며 동작을 선택합니다. 작업이 실행되는 동안 실시간 휴대폰 화면과 로그를 확인합니다.

단계 목록에는 각 결정에 사용된 스크린샷이 기록됩니다. 이미지 위에 선택한 탭 또는 스와이프를 표시하고 모델의 추론과 소요 시간도 보여 줍니다. 단계 카드를 선택하면 더 큰 화면으로 볼 수 있습니다.

수동 제어 사용

  • 실시간 휴대폰 이미지를 클릭하면 해당 위치를 탭합니다.
  • 이미지를 가로질러 드래그하면 스와이프를 수행합니다.
  • 스크롤 입력을 사용해 휴대폰 화면을 스크롤합니다.
  • 제공된 컨트롤을 사용해 홈, 뒤로 가기, 텍스트 입력 및 키를 조작합니다.

에이전트가 예상치 않게 동작하면 긴급 중지를 활성화하거나 Esc를 누릅니다. 그러면 실행이 중지되고 포인터가 해제됩니다. 인터페이스에는 실행 기록을 지우는 컨트롤도 있습니다.

중요한 구성 옵션

  • LLM_BASE_URL: OpenAI 호환 엔드포인트입니다. 기본값은 http://localhost:8000/v1입니다.
  • LLM_MODEL 및 LLM_API_KEY: 모델 이름과 API 인증 정보입니다.
  • LLM_EXTRA_BODY: 모델의 사고 모드를 비활성화하는 설정 등 모든 모델 요청에 병합되는 JSON입니다.
  • ACTOR_* 및 PLANNER_*: 해당 LLM_* 설정을 역할별로 재정의합니다.
  • AIRPLAY_NAME: iPhone 화면 미러링 목록에 표시되는 수신기 이름입니다. 기본값은 iPhone Agent입니다.
  • PORT: 웹 인터페이스 포트이며 기본값은 8890입니다.
  • DEVICE_PORT: ESP32-S3에서 사용하는 포트이며 기본값은 7300입니다.
  • HIDAGENT_DATA: 보정 및 추적 디렉터리이며 기본값은 ~/.hidagent입니다.
  • HIDAGENT_DEBUG: 1로 설정하면 서버 측 디버그 로깅을 활성화합니다.

고급 사용 및 문제 해결

플래너와 액터에 별도 모델 할당

플래너와 액터는 같은 모델을 사용할 수 있지만, 역할별 환경 변수를 사용하면 모델 설정을 독립적으로 재정의할 수 있습니다. 별도의 엔드포인트나 모델이 필요한 경우 관련 LLM_* 변수에 PLANNER_* 및 ACTOR_* 형식을 사용합니다.

로컬 모델 서버 연결

vLLM, SGLang, llama.cpp, Ollama를 포함해 비전 모델을 제공하는 모든 OpenAI 호환 서버를 같은 방식으로 구성할 수 있습니다. 이 프로젝트는 텐서 병렬 처리를 사용해 NVIDIA DGX Spark 두 대에서 제공되는 NVIDIA Qwen3.8-Flash-Next-NVFP4로 개발 및 성능 측정되었습니다.

해당 설정의 구성 예시는 다음과 같습니다:

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

사고 모드를 비활성화한 개발 환경에서는 작업당 약 1.3초, 계획당 2초의 성능이 측정되었습니다. 이 수치는 특정 하드웨어와 모델 구성에 해당하며 다른 배포 환경에서 보장되는 속도는 아닙니다.

추적 수집 활성화

server/.env에 다음 값을 설정합니다:

HIDAGENT_DEBUG=1

디버그 모드에서는 모든 보드 명령과 해당 지연 시간을 기록합니다. 또한 ~/.hidagent/traces/ 아래에 에이전트 실행마다 하나의 디렉터리를 생성합니다. 이 디렉터리에는 모델 프롬프트, 원시 응답, 지연 시간 측정값, 동작이 포함된 steps.jsonl과 모델 호출에 사용된 스크린샷이 저장됩니다.

보드 프로토콜 이해

  • ping은 상태를 확인합니다.
  • home은 포인터를 왼쪽 상단 모서리로 이동해 기준 위치를 설정합니다.
  • move <dx> <dy>는 일정한 속도로 포인터를 상대적으로 이동합니다.
  • press, release, click은 마우스 왼쪽 버튼을 제어합니다.
  • scroll <v> <h>는 세로 및 가로 스크롤 휠 입력을 전송합니다.
  • type <text>는 ASCII 텍스트를 입력합니다.
  • key <combo>는 enter, cmd+h, cmd+space와 같은 키 또는 키 조합을 전송합니다.

Linux에서 AirPlay 검색 문제 해결

컴퓨터에 네트워크 인터페이스가 여러 개 있고 iPhone에 수신기가 표시되지 않는 경우, Avahi mDNS 광고를 iPhone이 연결된 네트워크의 인터페이스로 제한하세요.

알려진 제한 사항

  • iOS는 암호 입력, Apple Pay, DRM으로 보호되는 동영상 및 일부 기타 보호된 화면을 미러링하지 않으므로 에이전트가 해당 화면을 볼 수 없습니다.
  • iPhone이 잠기면 화면 미러링이 중지됩니다. 에이전트가 실행되는 동안 자동 잠금을 비활성화하세요.
  • 키보드 텍스트 입력은 ASCII로 제한됩니다.
  • AssistiveTouch 추적 속도를 변경한 후에는 포인터 보정을 다시 수행해야 합니다.
  • 에이전트는 보드와 서버 사이의 네트워크 경로가 정상적으로 작동하고, iPhone과 컴퓨터 사이에 AirPlay 스트림을 사용할 수 있어야 합니다.

책임 있는 운영

소유하고 있거나 사용 권한을 부여받은 기기와 계정만 자동화하고, 관련 애플리케이션의 이용 약관을 준수하세요.

에이전트는 사람이 입력하는 것과 같은 종류의 입력으로 동작할 수 있으므로, 실행 중인 작업을 감독하고 비상 정지 기능에 쉽게 접근할 수 있도록 하세요.

결론

ESP32 iPhone Agent는 AirPlay 미러링, 저비용 ESP32-S3 USB HID 브리지, OpenAI 호환 비전 모델을 결합해 Apple의 기존 개발 도구 체계 없이 실제 iPhone을 자동화합니다. 펌웨어, 서버, 모델 엔드포인트, AssistiveTouch, 미러링, 포인터 보정을 구성하면 자연어 목표를 전달하고, 모든 결정을 확인하며, 수동으로 개입하고, 디버깅을 위한 상세 추적 기록을 수집할 수 있습니다.