Google Flow 한국어 나레이션과 자막을 사용한 설명 영상입니다. 2026-10-15 무렵의 main(e035e424) 구조를 깃밥이 그림으로 풀었으며, 실제 기기 실행 녹화는 아닙니다. 아래 안내와 화면 설명은 그 뒤의 main(68751e4) 기준이에요.
02 · 원본이 공개한 화면
현재 앱의 실제 화면 두 장, 그리고 이전 v0.1.0 화면
원본 README에 실린 현재 버전(main)의 공식 스크린숏을 깃밥이 두 장으로 나눴어요. README 설명으로는 각 장의 왼쪽이 실제 아이폰을 찍은 사진, 오른쪽이 보드의 AirPlay 미러링을 거쳐 에이전트가 보는 화면이에요. 정지 화면이라 작업 하나를 처음부터 끝까지 실행한 녹화는 아니에요. 셋째 장은 README 맨 위에 아직 실려 있는 이전 v0.1.0 사진이라, 이전 버전이라고 따로 표시했어요.
앱 첫 화면: 실제 아이폰(왼쪽)과 에이전트가 보는 화면(오른쪽)README 설명으로는 왼쪽이 실제 휴대폰, 오른쪽이 보드의 AirPlay 미러를 거쳐 에이전트가 보는 화면이에요. 깃밥이 화면을 보고 확인한 것: 위쪽 상태 표시 다섯 개(Board·Mirroring·Mouse·Pointer·Model) 중 초록 체크는 Pointer와 Model에만 있고, Board·Mirroring·Mouse는 체크 없이 주황색이에요. 'Plug me into the USB-C port to wake me up.' 문구와 Start 아래 'Connect the board'도 보여요. 작업 입력칸(What should I do on this iPhone?), 저장된 작업 'Daily 7 AM alarm'·'Draw a smiley', 왼쪽 아래의 회색 동그라미도 보여요. 다만 이 장면은 Board·Mirroring이 연결 전으로 표시돼 있어, 오른쪽이 실제로 보드 미러를 거친 화면인지는 이미지만으로 확인되지 않아요. 맨 아래 'Freeform' 표시는 원본 이미지에 있던 그대로예요.
이미지: onehumanbeing/esp32-iphone-agent의 docs/images/app-screens.png와 example-alarm.png(main 커밋 68751e4), MIT 라이선스, Copyright (c) 2026 Henry Yuan. 깃밥이 app-screens.png(1983×900)의 네 칸을 두 장으로 잘라(가로 0~962px, 983~1939px) WebP로 바꿨고, example-alarm.png는 자르지 않고 WebP로만 바꿨어요. 그 밖에는 고치지 않았어요. 깃밥이 찍은 화면이 아니고, 깃밥은 펌웨어를 올리거나 앱을 빌드·실행하지 않았어요.
03 · 바로 시작하기
부품 준비 → 보드에 펌웨어 → 앱 빌드 → 앱 안에서 설정
책상 위 아이폰에게 'Wi-Fi 설정 화면을 열어 줘'라고 맡겨 본다고 해 볼게요. 앱스토어에서 받는 앱이 아니라서, 맥에서 보드에 펌웨어를 한 번 올리고 앱을 직접 빌드해 아이폰에 설치해야 해요. 그다음 보드를 아이폰에 꽂고 앱이 안내하는 설정 네 단계를 마치면 첫 작업을 줄 수 있어요. 맥은 이 처음 준비에만 필요하고(무료 Apple ID라면 7일마다 맥에서 다시 서명해요), 실행할 때는 아이폰과 보드만 있으면 돼요. 아래 순서대로 진행하되, '시작하기 전에 꼭 알아둘 것'을 먼저 읽어 주세요.
main 커밋 68751e4(2026-10-18 UTC) 문서 기준 · 2026-10-19 확인 · 깃밥은 문서와 코드만 읽었고, 보드에 펌웨어를 올리거나 앱을 빌드·실행해 보지는 않았어요. 이 '컴퓨터 없는' 버전은 아직 정식 릴리스가 없어요: CHANGELOG에는 'Unreleased (main)'로만 적혀 있고, GitHub의 정식 릴리스 v0.1.0은 이전 컴퓨터 방식이에요. 빠르게 바뀌는 중이라 현재 버전이 처음 올라온 10월 15일(UTC) 뒤로 18일까지 main에 커밋이 25개 더 쌓였어요. 그래서 이 페이지는 커밋 하나에 고정해 읽었고, 지금 main은 이 안내와 다를 수 있어요. 설치는 README의 안내만 따르세요: README는 이슈나 댓글에 올라온 명령(예: '빠른 설치' 한 줄 명령)을 절대 실행하지 말라고, 관리자가 올린 것이 아니라고 경고해요.
순서대로 진행해요
① 부품과 코드 준비
처음 시작할 때 (README의 준비물 표 그대로)
git clone https://github.com/onehumanbeing/esp32-iphone-agent.git
cd esp32-iphone-agent
git checkout 68751e4d89abf64af338de39e5452da30d8f2173
① ESP32-S3 보드: 원본이 시험한 것은 Seeed Studio XIAO ESP32S3 기본형(PSRAM 8MB, Sense도 Plus도 아님)이고 값은 약 7달러예요. USB-C 단자에 네이티브 USB가 연결되고 PSRAM이 있는 ESP32-S3라면 동작할 거라고 적어요. ② iOS 18 이상이고 셀룰러 데이터를 쓸 수 있는 아이폰: Wi-Fi는 보드의 핫스폿이 차지해요. USB-C 아이폰은 바로 꽂고, Lightning 아이폰은 Lightning to USB Camera Adapter가 필요해요. 보드 전원은 아이폰이 공급해요. ③ 이미지를 받는 OpenAI 호환 채팅 API: 클라우드 API든 직접 운영하는 서버든 돼요. ④ Xcode가 있는 맥: 보드에 펌웨어를 올리고 앱을 한 번 빌드할 때만 필요하고(무료 Apple ID라면 7일마다 맥에서 다시 서명해요), 실행할 때는 필요 없어요.
깃밥 덧붙임: README의 설치 명령은 레포 폴더 안에서 실행하는 것(hardware/flash.sh, ios/…)인데, 현재 버전의 코드를 받는 줄은 없어요(git clone은 이전 버전 안내에만 있어요). 위 세 줄은 이 페이지와 같은 커밋으로 맞추려고 깃밥이 쓴 것이에요. flash.sh는 폴더 경로에 띄어쓰기가 있으면 멈추니, 띄어쓰기 없는 폴더에서 받으세요.
② 보드에 펌웨어 올리기 (맥에 꽂고)
보드를 처음 준비할 때, 또는 이전 버전 펌웨어가 올라간 보드를 현재 버전으로 바꿀 때
CI가 쓰는 명령 · ESP32 core 3.3.12 설치 (README는 '3.3.x'만 적어요)
README는 arduino-cli(설치 방법은 공식 문서), ESP32 core 3.3.x, NimBLE-Arduino 2.5.x를 설치한 뒤 NimBLE 설치 줄과 flash.sh 줄을 실행하라고 해요. core를 설치하는 정확한 명령은 README에 없어서, 원본 CI(.github/workflows/ci.yml)가 쓰는 두 줄을 그대로 옮겼어요. flash.sh는 펌웨어를 빌드해 보드에 올려요. 이미 펌웨어가 도는 보드는 1200baud 신호로 부트로더 모드로 바꾼 뒤 올리고, 빈 보드는 바로 올려요. 원문은 항상 flash.sh로 빌드하라고 해요: hardware/hid_bridge/nimble_cfg.h의 BLE 버퍼 크기를 적용하기 때문이고, 일반 IDE 빌드는 실패한다고 적혀 있어요.
포트를 꼭 직접 넣으세요. 깃밥이 flash.sh를 읽어 보니, 포트를 주지 않으면 /dev/cu.usbmodem*이나 /dev/ttyACM* 중 처음 찾은 장치에 리셋 신호를 보내고 올려요. 포트를 넣어도 리셋 뒤에는 다시 처음 찾은 포트로 올리게 되어 있으니, 다른 보드와 USB 시리얼 장치는 미리 빼 두세요. --sta·--build-only·--ap-tune은 시험용 옵션이라 처음에는 쓰지 않아요.
③ 앱 빌드하고 아이폰에 설치 (Xcode)
보드 준비가 끝나면, 아이폰을 맥에 연결해서
README 원문 · 설정 파일 복사 (DEVELOPMENT_TEAM과 IA_BUNDLE_ID 채우기)
README 원문 · Xcode에서 열기 (IPhoneAgent 스킴을 내 아이폰으로 실행)
open ios/IPhoneAgent.xcodeproj
복사한 Local.xcconfig에 내 Apple 개발 팀 ID(DEVELOPMENT_TEAM)와 내 번들 ID(IA_BUNDLE_ID)를 넣고, Xcode에서 IPhoneAgent 스킴을 내 아이폰으로 실행해요. 무료 Apple ID로도 서명할 수 있지만 7일마다 다시 서명해야 해요. 핫스폿 원터치 연결은 Hotspot Configuration 기능, 즉 유료 개발자 계정이 필요하고, 없으면 앱이 핫스폿 비밀번호를 보여 줘서 직접 입력해 연결해요. 프로젝트는 ios/project.yml에서 XcodeGen으로 만든 것이라, 다시 만들어야 할 때만 cd ios && xcodegen을 써요.
README에 공개 App Store·TestFlight 설치 경로가 없고, 맥과 Xcode로 직접 빌드해요. 예제 설정 파일은 핫스폿 원터치 연결·Live Activity 그룹·시간 민감 알림에 IA_ENTITLEMENTS·IA_WIDGET_ENTITLEMENTS가 필요하고(그중 Hotspot Configuration은 유료 계정), 비우면 이 기능 없이 빌드된다고 적어요.
보드를 아이폰에 꽂은 다음 (앱 안에서 한 번)
1. Plug Me In: 보드와 Bluetooth 연결
보드를 아이폰에 꽂고 ESP32 Agent 앱을 열면 설정이 네 단계를 안내하고, 단계마다 스스로 확인해요. 첫 단계에서 보드를 Bluetooth로 페어링해요. 앱은 백그라운드에서도 Bluetooth로 보드와 연결하도록 만들어져 있어요.
2. Let Me See the Screen: 핫스폿과 화면 미러링
보드의 Wi-Fi 핫스폿(이름 ESP32Agent-XXXX)에 연결한 뒤 제어 센터 → 화면 미러링 → ESP32 Agent를 골라요. 목록에 ESP32 Agent가 보이면 보드의 AirPlay 수신이 켜진 거예요. 이때부터 아이폰의 Wi-Fi는 인터넷이 없는 보드 핫스폿이 되고, 모델에는 셀룰러로 접속해요.
3. Let Me Use the Pointer: AssistiveTouch 켜기
AssistiveTouch를 켜면 앱이 스스로 포인터를 맞춰요(위 '실제 화면'의 Calibrating pointer... 7/8 장면). 보드가 USB 마우스로 화면 위 포인터를 움직여서, 클릭이 탭이 되고 끌기가 밀기(스와이프)가 돼요. 맞추는 동안은 화면에서 손을 떼요.
4. Give Me a Brain: 모델 고르기와 이미지 확인
모델 주소(endpoint)와 키를 넣어요. 키는 아이폰의 키체인에 저장돼요. 그다음 그 주소의 모델 목록에서 이미지를 볼 수 있는 모델을 직접 고르거나 모델 ID를 입력해요. 앱에는 OpenAI, Google Gemini, Qwen · China, Qwen · International, DeepSeek, OpenRouter, Others(직접 입력) 프리셋이 있어요. 깃밥이 코드를 읽어 보니, 연결 확인 때 이미지 하나를 보내 모델이 'red' 한 단어로 답해야 통과시켜요. 이 확인이 실패해도 키나 네트워크 문제라는 뜻은 아니라고 코드에 적혀 있으니, 다시 해 보거나 다른 비전 모델을 골라요.
첫 작업 주기
목표를 입력하고 Start를 눌러요. README의 예시는 'Open Settings and go to Wi-Fi'예요. Start를 누르면 앱이 스스로 홈 화면으로 비켜나 작업하고, Dynamic Island에 지금 하는 일을 보여 줘요. 멈추려면 Dynamic Island에서 멈추거나 앱으로 돌아와요. 깃밥 덧붙임: 완료 표시만 믿지 말고, Wi-Fi 설정 화면이 실제로 열렸는지 직접 확인하세요.
Open Settings and go to Wi-Fi
잘 되고 있는지 확인
원본 문서 기준으로 이렇게 보이면 돼요: 아이폰 Wi-Fi 목록에 ESP32Agent-XXXX 핫스폿이 보이고, 화면 미러링 목록에 ESP32 Agent가 나와요. 설정 네 단계가 각각 통과하고, 모델 연결에서 이미지 확인이 통과해요. 첫 작업은 Wi-Fi 설정 화면에서 끝나요. 실행 기록은 Runs 탭에 남아 단계별로 다시 볼 수 있어요.
이전 v0.1.0(컴퓨터 방식)을 연구하려면
이전 버전은 아이폰 옆에 맥이나 리눅스 컴퓨터를 두고 UxPlay와 Python 서버를 돌리는 방식이에요. 원문 docs/legacy.md는 아래 한 줄로 legacy 브랜치를 받고(또는 v0.1.0 태그로 바꾸고) 그 README를 따르라고 해요.
legacy 브랜치의 맨 앞은 지금 v0.1.1 태그(선택 사항인 CLI·MCP 접속 추가, 릴리스 페이지 없음)이고, GitHub 정식 릴리스는 v0.1.0이에요. 이전 펌웨어와 현재 펌웨어는 서로 바꿔 쓸 수 없으니, 쓰는 브랜치에 맞는 펌웨어를 올리세요.
시작하기 전에 꼭 알아둘 것 (보드·아이폰·데이터)
flash.sh는 포트를 주지 않으면 처음 찾은 USB 시리얼 장치(/dev/cu.usbmodem*·/dev/ttyACM*)에 리셋 신호를 보내고 펌웨어를 올려요. 깃밥이 스크립트를 읽어 보니, 포트를 넣어도 리셋 뒤에는 다시 처음 찾은 포트로 올리게 되어 있어요. 올리기 전에 다른 개발 보드와 USB 시리얼 장치는 빼고, 포트를 직접 넣으세요.
빌드 설정은 XIAO ESP32S3 기본형에 맞춘 8MB 플래시·OPI PSRAM으로 고정돼 있어요. 다른 ESP32-S3 보드라면 네이티브 USB(USB-C)와 PSRAM, 플래시 크기가 맞는지 먼저 확인하세요. 원문은 그런 보드도 '동작할 것'이라고만 적어요.
이전 버전(v0.1.0·legacy)과 현재 버전의 펌웨어는 서로 바꿔 쓸 수 없어요. 펌웨어가 잘못 올라갔을 때 되돌리는 방법은 원본 문서에 없어요.
실행하려면 AssistiveTouch를 켜 둬야 하고, 앱은 백그라운드에서도 Bluetooth로 보드와 연결해요(Bluetooth 상시 사용 권한). 깃밥 덧붙임: 시험을 마치면 보드를 빼고, 평소에 쓰지 않는다면 AssistiveTouch도 꺼 두세요.
에이전트가 도는 동안 아이폰의 Wi-Fi는 인터넷이 없는 보드 핫스폿에 연결돼요. 모델에는 셀룰러 데이터로 접속하니 데이터 요금과 신호를 확인하세요. 직접 운영하는 모델 서버도 셀룰러에서 닿아야 해요.
앱은 단계마다 아이폰 화면의 스크린숏과 작업 문장을 내가 설정한 모델 주소로 보내고, 그곳의 개인정보 정책이 적용돼요(원본 개인정보 문서). 프리셋에는 중국 본토 주소(Qwen · China, dashscope.aliyuncs.com)도 있고, OpenRouter에서는 무료 모델 중 하나로 자동 연결하는 openrouter/free도 고를 수 있어요. openrouter/free는 요청마다 OpenRouter가 모델을 고르니, 화면이 어느 회사 모델로 갈지 미리 정해지지 않아요. 깃밥 덧붙임: 어느 회사의 어느 모델로 화면이 가는지 확인한 뒤 키를 넣고, 은행·메시지·결제처럼 민감한 화면에서는 시험하지 마세요.
Xcode의 Debug 빌드는 iphoneagent://run?task=… 같은 주소로 작업을 시작하는 개발용 명령을 받아요. 원본 코드 주석은 릴리스 빌드였다면 어떤 웹페이지든 이 주소를 열 수 있어서 Debug 빌드에만 넣었다고 적어요. 깃밥 덧붙임: Xcode에서 그냥 실행하면 보통 Debug 빌드예요. 그 아이폰에서는 모르는 링크를 열지 말고, 시험할 때만 보드를 꽂아 두세요.
모델 키는 앱 설정에서 입력해 키체인에 두세요. Local.xcconfig의 IA_PRESET_KEY에 키를 넣으면 빌드 안에 키가 들어가고, 예제 파일도 키를 절대 커밋하지 말라고 적어요. 깃밥 덧붙임: 이 페이지는 IA_PRESET_KEY를 비워 두기를 권해요.
깃밥 덧붙임(원문에 없어 확실하지 않아요): Xcode로 직접 설치한 앱을 처음 실행하려면 아이폰에서 개발자 모드를 켜야 하고, 무료 Apple ID라면 설정에서 개발자 앱을 신뢰해야 할 가능성이 커요.
키보드 입력은 ASCII만 되고(한글·일본어 입력 불가), 가로 화면 앱은 아직 지원하지 않아요. 암호 입력·Apple Pay·DRM 영상 화면은 미러링되지 않아 에이전트가 볼 수 없고, 아이폰이 잠기면 미러링이 멈춰요.
원문은 내가 가진 기기와 쓸 권한이 있는 계정만 자동화하고 앱 약관을 지키라고 적어요. 에이전트는 내 손처럼 움직이니 지켜보고, 멈춤 버튼을 손 닿는 곳에 두세요.
AI 앱에게 준비를 맡기려면
아래 명령문을 Claude Code나 Codex에 붙여넣으면, 커밋을 고정한 README대로 펌웨어 올리기와 앱 빌드를 함께하면서 내려받기·설치·포트 선택·설정 파일 수정 전에는 먼저 물어봐요. 키 입력과 아이폰 설정, 작업 시작은 직접 하게 돼요. 명령문은 깃밥이 공식 문서를 바탕으로 썼어요.
보드는 AirPlay 영상을 BLE로 같은 아이폰 앱에 전달해요. 앱이 화면 이미지를 모델 API에 보내 동작을 고릅니다.
내 상황에 대입하면
어디서 화면을 받고, 누가 판단하고, 무엇이 입력하는지 나눠볼 때.
알아둘 점
BLE로 돌아오는 것은 H.264 영상 데이터예요. 영상 복호화와 JPEG 변환은 앱에서 하고, 아이폰 입력은 BLE HID가 아닌 USB HID입니다.
main은 아직 정식 릴리스가 없는 CHANGELOG의 Unreleased 버전입니다. 위 '실제 화면'에 실은 현재 앱 사진은 원본이 공개한 정지 화면이고, 작업 전체를 실행한 녹화는 아니에요. 이전 v0.1.0의 공식 알람 사진은 이전 버전이라고 표시했고, 최신 실행 결과처럼 사용하지 않았습니다.
근거: Henry Yuan 및 esp32-iphone-agent 기여자의 공식 소스. 설명도·모션: 깃밥. 나레이션: Google Flow. 코드 라이선스: MIT, AirPlay 부분 및 연결된 펌웨어 바이너리 GPL-3.0. 확인: 2026. 10. 19. 라이선스 구분 보기 ↗
04 · 선택 가이드
내 조건이라면 어느 쪽을 고를까요?
내 상황에 맞춰 고르기
질문 세 개로 결론까지
답을 고르면 아래 비교와 판단 근거를 바탕으로 깃밥이 정리한 결론이 바로 나와요.
세 가지를 고르면 결론이 나와요.
결론은 아래 비교와 '조건이 달라지면' 판단, 원래 분석의 추천·보류 조건을 그대로 옮긴 거예요. 원문: 이전 버전과 달라진 점 ↗
한눈에 비교
지금 main(68751e4)과 이전 v0.1.0을 비교했어요(docs/legacy.md 기준).
기준
현재 main
이전 v0.1.0
에이전트가 실행되는 곳
아이폰 앱이 모델 호출
맥·리눅스 Python 서버
화면과 명령 전달
보드가 AirPlay 수신 · BLE
컴퓨터가 AirPlay 수신 · Wi-Fi
컴퓨터가 필요한 시점
처음 빌드·설치 때만
작업 내내
모델에 접속하는 길
셀룰러 (Wi-Fi는 보드 핫스폿)
컴퓨터에서 접속
이럴 땐 현재 main초기 맥·Xcode 준비가 가능하고, 실행 중 별도 제어용 컴퓨터 없이 시험하려는 경우.
이럴 땐 이전 v0.1.0기존 Python·UxPlay 구조를 연구하거나, 이전 버전을 재현하려는 경우에만 해당 태그와 문서를 함께 확인하세요.
2026-10-19 확인, main 커밋 68751e4(2026-10-18 UTC) 고정. 이 버전은 정식 릴리스가 없고 CHANGELOG에 'Unreleased (main)'로만 적혀 있으며, 현재 버전이 처음 올라온 10월 15일(UTC) 뒤로 18일까지 main에 커밋이 25개 더 쌓일 만큼 빠르게 바뀌고 있어요. 공식 문서·코드를 바탕으로 깃밥이 쓴 설명이며, iPhone·ESP32 연결이나 성공률 시험은 하지 않았습니다. 원본이 공개한 현재 앱의 정지 화면(공식 스크린숏)은 실었지만, 작업 전체를 실행한 녹화는 아니에요. 예전 v0.1.0 사진은 이전 버전이라고 표시했고, 최신 버전의 실행 증거로 사용하지 않았습니다.
쓰임부터 이해하는 레포 해설
내 아이폰에서 시험하려면
아이폰에서 AI가 화면을 보고 조작하는 과정을 직접 시험하고 싶어요.
01 · 역할 나눠 보기
맡길 부분과 직접 챙길 부분
ESP32 iPhone Agent에 맡겨요
화면 전달·복호화, 모델 호출, 보드 입력, 단계별 실행 기록
직접 준비하고 운영해요
앱 빌드와 서명, 보드·네트워크 설정, 모델 비용과 데이터, 작업 중단과 결과 확인
“사용 중 컴퓨터 없이”를 시작하기 전에, 초기 빌드와 셀룰러·모델 연결부터 확인해보세요.
