ESP32-S3 کے ساتھ AI سے چلنے والا iPhone ایجنٹ بنائیں

ESP32 iPhone Agent کیا کرتا ہے

ESP32 iPhone Agent ایک AI ماڈل کو حقیقی iPhone دیکھنے اور چلانے کی سہولت دیتا ہے۔ یہ بصری اِن پٹ کے لیے AirPlay اسکرین مررنگ اور USB ماؤس اور کی بورڈ کے طور پر ایک کم قیمت ESP32-S3 بورڈ استعمال کرتا ہے۔ چونکہ یہ اسکرین اور پوائنٹر کے ذریعے تعامل کرتا ہے، اس لیے اسے Xcode، Apple ڈویلپر اکاؤنٹ، جیل بریک، Developer Mode یا فون پر انسٹال کسی معاون ایپ کی ضرورت نہیں ہوتی۔

کمپیوٹر macOS یا Linux چلا سکتا ہے۔ اس پر UxPlay، Python سرور، ویب انٹرفیس اور OpenAI-compatible وژن ماڈل سے کنکشن چلتے ہیں۔ ESP32-S3 Wi-Fi کے ذریعے کمپیوٹر سے جڑتا ہے اور iPhone کو ایک معیاری USB Human Interface Device کے طور پر نظر آتا ہے۔

سسٹم کیسے کام کرتا ہے

AirPlay آنکھوں کا کام کرتا ہے

iPhone اپنی اسکرین کمپیوٹر پر موجود UxPlay پر مرر کرتا ہے۔ GStreamer پائپ لائن اس اسٹریم کو JPEG فریمز میں تبدیل کرتی ہے، جنہیں AI ایجنٹ اور براؤزر پر مبنی لائیو ویو دونوں استعمال کرتے ہیں۔

ESP32-S3 ہاتھوں کا کام کرتا ہے

iPhone سے منسلک ہونے پر یہ بورڈ USB ماؤس اور کی بورڈ کی طرح کام کرتا ہے۔ iOS AssistiveTouch فعال ہونے کی صورت میں ماؤس کلکس ٹیپس، پوائنٹر ڈریگ سوائپس، اسکرول وہیل انٹرفیس کو اسکرول، اور کی بورڈ کمانڈز متن درج یا شارٹ کٹس دبانے میں تبدیل ہو جاتی ہیں۔

فرم ویئر میں جان بوجھ کر بہت کم منطق رکھی گئی ہے۔ سرور TCP کے ذریعے لائن پر مبنی کمانڈز جیسے move، click، scroll، type اور key بھیجتا ہے۔ بورڈ ok یا خرابی کا پیغام واپس بھیجتا ہے۔

پلانر اور ایکٹر دماغ کا کام کرتے ہیں

پلانر ماڈل مطلوبہ ہدف اور موجودہ اسکرین سے ایک مختصر منصوبہ بناتا ہے۔ ایکٹر ماڈل ہر نئی اسکرین شاٹ کا جائزہ لے کر اگلی کارروائی منتخب کرتا ہے، جیسے ٹیپ کرنا، سوائپ کرنا، راستہ بنانا، ٹائپ کرنا، کوئی کلید دبانا، ہوم پر واپس جانا یا کام مکمل کرنا۔ ایک ہی وژن ماڈل دونوں کردار ادا کر سکتا ہے۔

بند لوپ کی جانچ قابلِ اعتماد کارکردگی بہتر بناتی ہے

پوائنٹر کی حرکت نسبتی ہوتی ہے، اس لیے سرور اس کی تخمینی پوزیشن محفوظ رکھتا ہے۔ ٹیپ سے پہلے یہ پوائنٹر کو ہلا سکتا ہے، مرر کی گئی تصویر میں اسے تلاش کر سکتا ہے، غلطی درست کر سکتا ہے اور کیلیبریشن بہتر بنا سکتا ہے۔ کسی کارروائی کے بعد ایجنٹ جانچتا ہے کہ آیا اسکرین تبدیل ہوئی ہے۔ یوں ناکام کارروائیوں کو محسوس کرکے دوبارہ آزمایا جا سکتا ہے، بجائے اس کے کہ وہ بعد کے مراحل کی بنیاد بن جائیں۔

بار بار کارروائیوں کے بعد سسٹم دوبارہ منصوبہ بھی بنا سکتا ہے اور منقطع روابط یا ماڈل کے غلط جوابات سے بحال ہو سکتا ہے۔ Wi-Fi کنکشن منقطع ہونے پر بورڈ ماؤس کے بٹن چھوڑ کر خودکار طور پر دوبارہ جڑ جاتا ہے۔

اہم خصوصیات

• Apple ڈویلپمنٹ سیٹ اپ کی ضرورت نہیں: Xcode، ڈویلپر اکاؤنٹ، کوڈ سائننگ، Developer Mode یا ٹیسٹ رنر ایپ درکار نہیں۔
• وسیع ایپ مطابقت: ایجنٹ accessibility tree پر انحصار کرنے کے بجائے پکسلز پر کام کرتا ہے، اس لیے یہ عام ایپس اور گیمز میں کام کر سکتا ہے۔
• Mac یا Linux ہوسٹ: سرور صرف macOS تک محدود نہیں۔
• ماڈل کی لچک دار معاونت: تصاویر قبول کرنے والی کوئی بھی OpenAI-compatible chat API استعمال کی جا سکتی ہے۔
• دستی اور خودکار کنٹرول: ویب انٹرفیس براہِ راست ٹیپس، سوائپس، اسکرولنگ، ٹائپنگ، Home، Back اور AI سے چلنے والے کاموں کی معاونت کرتا ہے۔
• عمل کی نگرانی: انٹرفیس لائیو فون اسکرین، منصوبے، لاگز، اسکرین شاٹس، کارروائیاں، استدلال اور وقت سے متعلق معلومات دکھاتا ہے۔
• حفاظتی کنٹرولز: ایمرجنسی اسٹاپ ایجنٹ کو روک کر پوائنٹر چھوڑ دیتا ہے۔

آپ کو کیا درکار ہے

• ESP32-S3 بورڈ: اس پروجیکٹ کی جانچ ایک سادہ Seeed Studio XIAO ESP32S3 کے ساتھ کی گئی۔ کوئی دوسرا ESP32-S3 بورڈ بھی کام کر سکتا ہے، بشرطیکہ اس کا USB-C پورٹ چِپ کے native USB انٹرفیس سے منسلک ہو۔
• iPhone: USB-C ماڈلز براہِ راست منسلک ہو سکتے ہیں۔ Lightning ماڈلز کے لیے Lightning to USB Camera Adapter درکار ہے۔
• کمپیوٹر: iPhone کے اسی نیٹ ورک پر موجود macOS یا Linux مشین۔
• Wi-Fi: بورڈ کی تشکیل کے لیے 2.4 GHz نیٹ ورک کا نام اور پاس ورڈ درکار ہے۔
• وژن ماڈل: کوئی cloud یا local OpenAI-compatible endpoint جو تصویری اِن پٹ قبول کرے۔

iPhone بورڈ کو بجلی فراہم کرتا ہے۔ اگر فون کو اسی وقت چارج بھی کرنا ہو تو power pass-through والے USB-C hub کا استعمال کریں۔

ایجنٹ انسٹال اور تشکیل کریں

1. ریپوزٹری کلون کریں

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

2. ESP32-S3 تیار کرکے فلیش کریں

arduino-cli اور 3.x ESP32 core انسٹال کریں۔ ESP32-S3 کو USB کے ذریعے کمپیوٹر سے منسلک کریں، مثال کی secrets فائل کاپی کریں اور نئی فائل میں ترمیم کریں۔

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

hardware/hid_bridge/secrets.h میں 2.4 GHz Wi-Fi نیٹ ورک کا نام، Wi-Fi پاس ورڈ اور اس کمپیوٹر کا IP address درج کریں جو سرور چلائے گا۔ پھر بورڈ فلیش کریں:

hardware/flash.sh

فلیش اسکرپٹ اختیاری طور پر serial port اور --debug flag قبول کرتا ہے۔ ڈیبگ فرم ویئر USB serial کے ذریعے کمانڈز اور ان کے دورانیے دکھاتا ہے۔

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 اس نیٹ ورک سے قابل رسائی ہونا چاہیے جس سے بورڈ منسلک ہے۔

آئی فون ترتیب دیں

فون کی درج ذیل ترتیب عام طور پر صرف ایک بار درکار ہوتی ہے:

1. Settings کھولیں، پھر Accessibility، Touch، اور AssistiveTouch پر جائیں۔
2. AssistiveTouch کو آن کریں۔
3. فلیش کیے گئے بورڈ کو کمپیوٹر سے منقطع کریں اور آئی فون سے منسلک کریں۔
4. تصدیق کریں کہ ایک گول پوائنٹر ظاہر ہو رہا ہے اور ویب صفحہ کنٹرولر کو منسلک دکھا رہا ہے۔
5. آئی فون پر Control Center کھولیں اور Screen Mirroring منتخب کریں۔
6. iPhone Agent منتخب کریں۔ فون کا لائیو ڈسپلے ویب انٹرفیس میں ظاہر ہونا چاہیے۔
7. ویب انٹرفیس میں Manual controls کھولیں اور Calibrate منتخب کریں۔
8. لائیو اسکرین میں نظر آنے والے پوائنٹر پر عین کلک کریں۔

اگر آپ بعد میں AssistiveTouch کی ٹریکنگ رفتار تبدیل کریں تو دوبارہ کیلیبریٹ کریں۔

اپنا پہلا کام چلائیں

ویب انٹرفیس میں ایک مقصد درج کریں اور Start دبائیں۔ مثال کے طور پر:

Open Settings and go to Wi-Fi

پلانر ایک مختصر منصوبہ بناتا ہے، جبکہ ایکٹر موجودہ اسکرین شاٹ کا بار بار جائزہ لے کر ایک کارروائی منتخب کرتا ہے۔ کام چلتے وقت فون کے لائیو منظر اور لاگ پر نظر رکھیں۔

اسٹیپ وال ہر فیصلے کے لیے استعمال ہونے والا اسکرین شاٹ محفوظ کرتی ہے۔ یہ تصویر پر منتخب کردہ ٹیپ یا سوائپ بھی دکھاتی ہے اور ماڈل کی منطق اور وقت کی تفصیل ظاہر کرتی ہے۔ کسی اسٹیپ کارڈ کو منتخب کرنے سے بڑا منظر کھل جاتا ہے۔

دستی کنٹرولز استعمال کریں

• اس پوزیشن پر ٹیپ کرنے کے لیے فون کی لائیو تصویر پر کلک کریں۔
• سوائپ کرنے کے لیے تصویر پر ڈریگ کریں۔
• فون کو اسکرول کرنے کے لیے اسکرول ان پٹ استعمال کریں۔
• Home، Back، متن درج کرنے، اور کیز کے لیے فراہم کردہ کنٹرولز استعمال کریں۔

اگر ایجنٹ غیر متوقع رویہ دکھائے تو Emergency stop فعال کریں یا Esc دبائیں۔ اس سے رن رک جائے گا اور پوائنٹر آزاد ہو جائے گا۔ انٹرفیس میں عمل درآمد کی تاریخ صاف کرنے کا کنٹرول بھی موجود ہے۔

اہم ترتیب کے اختیارات

• LLM_BASE_URL: OpenAI سے ہم آہنگ اینڈ پوائنٹ۔ طے شدہ قدر http://localhost:8000/v1 ہے۔
• LLM_MODEL اور LLM_API_KEY: ماڈل کا نام اور API اسناد۔
• LLM_EXTRA_BODY: ہر ماڈل درخواست میں ضم کیا جانے والا JSON، مثلاً وہ ترتیبات جو ماڈل کے سوچنے کے موڈ کو غیر فعال کرتی ہیں۔
• ACTOR_* اور PLANNER_*: متعلقہ LLM_* ترتیبات کے لیے کردار کے لحاظ سے مخصوص اووررائیڈز۔
• AIRPLAY_NAME: آئی فون کی Screen Mirroring فہرست میں دکھایا جانے والا وصول کنندہ نام۔ طے شدہ نام iPhone Agent ہے۔
• PORT: ویب انٹرفیس کا پورٹ، طے شدہ قدر 8890 ہے۔
• DEVICE_PORT: ESP32-S3 کے زیر استعمال پورٹ، طے شدہ قدر 7300 ہے۔
• HIDAGENT_DATA: کیلیبریشن اور ٹریس ڈائریکٹری، طے شدہ قدر ~/.hidagent ہے۔
• HIDAGENT_DEBUG: قدر 1 مقرر ہونے پر سرور سائیڈ ڈیبگ لاگنگ فعال کرتا ہے۔

اعلیٰ استعمال اور خرابیوں کا ازالہ

الگ پلانر اور ایکٹر ماڈلز مقرر کریں

پلانر اور ایکٹر ایک ہی ماڈل استعمال کر سکتے ہیں، لیکن کردار کے لحاظ سے مخصوص ماحولیاتی متغیرات آپ کو ماڈل کی ترتیبات الگ الگ اووررائیڈ کرنے دیتے ہیں۔ جب الگ اینڈ پوائنٹس یا ماڈلز درکار ہوں تو متعلقہ LLM_* متغیرات کی PLANNER_* اور ACTOR_* شکلیں استعمال کریں۔

مقامی ماڈل سرور سے منسلک ہوں

ویژن ماڈل والا کوئی بھی OpenAI سے ہم آہنگ سرور اسی طرح ترتیب دیا جا سکتا ہے، جس میں vLLM، SGLang، llama.cpp، اور Ollama شامل ہیں۔ یہ منصوبہ NVIDIA Qwen3.8-Flash-Next-NVFP4 کے ساتھ تیار اور ٹائم کیا گیا تھا، جسے ٹینسر متوازی کاری کے ذریعے دو NVIDIA DGX Sparks پر چلایا گیا۔

اس ترتیب کی ایک مثالی کنفیگریشن یہ ہے:

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 اشتہار کو اس انٹرفیس تک محدود کریں جو فون کے نیٹ ورک سے منسلک ہے۔

معلوم حدود

• iOS پاس کوڈ کا اندراج، Apple Pay، DRM سے محفوظ ویڈیو، اور کچھ دیگر محفوظ اسکرینیں منعکس نہیں کرتا، اس لیے ایجنٹ انہیں نہیں دیکھ سکتا۔
• فون لاک ہونے پر اسکرین مررنگ رک جاتی ہے۔ ایجنٹ کے چلنے کے دوران خودکار لاک کو غیر فعال رکھیں۔
• کی بورڈ کے ذریعے متن کا اندراج صرف ASCII تک محدود ہے۔
• AssistiveTouch کی ٹریکنگ رفتار تبدیل کرنے کے بعد پوائنٹر کیلیبریشن دوبارہ کرنا ضروری ہے۔
• ایجنٹ کا انحصار بورڈ اور سرور کے درمیان فعال نیٹ ورک راستے، اور فون اور کمپیوٹر کے درمیان دستیاب AirPlay اسٹریم پر ہے۔

ذمہ دارانہ استعمال

صرف ان ڈیوائسز اور اکاؤنٹس کو خودکار بنائیں جو آپ کی ملکیت ہوں یا جنہیں استعمال کرنے کی آپ کو اجازت ہو، اور متعلقہ ایپلیکیشنز کی شرائط پر عمل کریں۔

چونکہ ایجنٹ انسان جیسے ہی ان پٹ کے ذریعے کارروائی کر سکتا ہے، فعال رنز کی نگرانی کریں اور ایمرجنسی اسٹاپ کو قابل رسائی رکھیں۔

نتیجہ

ESP32 iPhone Agent، AirPlay مررنگ، کم لاگت والے ESP32-S3 USB HID برج، اور OpenAI سے مطابقت رکھنے والے وژن ماڈل کو یکجا کر کے Apple کے روایتی ڈویلپمنٹ ٹول چین کے بغیر ایک حقیقی iPhone کو خودکار بناتا ہے۔ فرم ویئر، سرور، ماڈل اینڈ پوائنٹ، AssistiveTouch، مررنگ، اور پوائنٹر کیلیبریشن ترتیب دینے کے بعد، آپ قدرتی زبان میں اہداف دے سکتے ہیں، ہر فیصلے کا معائنہ کر سکتے ہیں، دستی مداخلت کر سکتے ہیں، اور ڈیبگنگ کے لیے تفصیلی ٹریسز جمع کر سکتے ہیں۔