دوز مباشرة للمحتوى الرئيسي
دروس فالذكاء الاصطناعي

صايب وكيل iPhone مدعوم بالذكاء الاصطناعي باستعمال ESP32-S3

تعلّم كيفاش تبرمجي ESP32-S3، وتعكس شاشة iPhone باستعمال UxPlay، وتربط موديل للرؤية متوافق مع OpenAI، وتعاير التحكّم بالمؤشر، وتشغّل مهام مؤتمتة بلا Xcode، ولا حساب مطوّر، ولا jailbreak، ولا تثبيت أي تطبيق فالتليفون.

حوالي 22 دقايق ديال القراية
صايب وكيل iPhone مدعوم بالذكاء الاصطناعي باستعمال ESP32-S3

شنو كيدير ESP32 iPhone Agent

ESP32 iPhone Agent كيخلي موديل ديال الذكاء الاصطناعي يشوف ويتحكم فـ iPhone حقيقي. كيستعمل عكس الشاشة عبر AirPlay باش يجيب المعطيات البصرية، ولوحة ESP32-S3 رخيصة باش تخدم كماوس وكلافي USB. حيت كيتفاعل مع الشاشة والمؤشر، ما كيحتاجش Xcode، ولا حساب مطوّر ديال Apple، ولا jailbreak، ولا Developer Mode، ولا تطبيق مساعد مركّب فالتليفون.

واجهة ESP32 iPhone Agent وiPhone مربوط

الكمبيوتر يقدر يخدم بـ macOS ولا Linux. كيشغّل UxPlay، وسيرفر Python، وواجهة الويب، والاتصال بموديل رؤية متوافق مع OpenAI. لوحة ESP32-S3 كترتبط بالكمبيوتر عبر Wi-Fi، وفنفس الوقت كتبان للـ iPhone بحال جهاز USB قياسي من نوع Human Interface Device.

كيفاش كيخدم السيستيم

AirPlay كيوفّر العينين

الـ iPhone كيعكس الشاشة ديالو على UxPlay فالكمبيوتر. واحد المسار ديال GStreamer كيحوّل داك البث لإطارات JPEG كيستعملهم كل من وكيل الذكاء الاصطناعي والعرض المباشر فالمتصفح.

ESP32-S3 كيوفّر اليدين

مني كتكون اللوحة مربوطة بالـ iPhone، كتخدم بحال ماوس وكلافي USB. مع تفعيل AssistiveTouch فـ iOS، كيتحوّلو كليكات الماوس لضغطات، وسحب المؤشر لسوايب، وعجلة التمرير لتمرير فالواجهة، وأوامر الكلافي لإدخال النصوص ولا الضغط على الاختصارات.

الفيرموير فيه عن قصد منطق قليل. السيرفر كيبعث أوامر فسطور، بحال move وclick وscroll وtype وkey عبر TCP. اللوحة كتجاوب بـ ok ولا برسالة خطأ.

Planner وactor كيوفّرو العقل

موديل planner كينشئ خطة قصيرة انطلاقاً من الهدف المطلوب والشاشة الحالية. موديل actor كيفحص كل لقطة شاشة جديدة وكيختار العملية الجاية، بحال الضغط، والسحب، ورسم مسار، والكتابة، والضغط على زر، والرجوع للصفحة الرئيسية، ولا الإنهاء. نفس موديل الرؤية يقدر يخدم الدورين بجوج.

التحققات فحلقة مغلقة كتحسّن الموثوقية

حركة المؤشر نسبية، وداكشي علاش السيرفر كيتبّع الموقع المقدّر ديالو. قبل أي ضغطة، يقدر يحرّك المؤشر شوية، يلقاه فالصورة المعكوسة، يصلّح الخطأ، ويحسّن المعايرة. من بعد أي عملية، الوكيل كيفحص واش تبدلات الشاشة. بهاد الطريقة يمكن ملاحظة العمليات اللي ما تنفذاتش وإعادة المحاولة، بلا ما تولّي أساس للخطوات اللي من بعدها.

السيستيم يقدر حتى يعاود يخطط من بعد عمليات متكررة، ويتعافى من الروابط اللي كتقطع ولا من أجوبة الموديل غير الصالحة. إلا تقطع اتصال Wi-Fi، اللوحة كتحرر أزرار الماوس وكتعاود الاتصال بوحدها.

المزايا الرئيسية

  • ما كايناش حاجة لإعدادات تطوير Apple: ما كاين لا Xcode، لا حساب مطوّر، لا توقيع الكود، لا Developer Mode، ولا تطبيق لتجريب الكود.
  • توافق واسع مع التطبيقات: الوكيل كيخدم على البيكسلات بلا ما يعتمد على شجرة الوصول، وبهذا يقدر يخدم مع التطبيقات والألعاب العادية.
  • كمبيوتر Mac ولا Linux: السيرفر ماشي محدود فـ macOS.
  • دعم مرن للموديلات: يمكن استعمال أي API ديال المحادثة متوافق مع OpenAI وكيقبل الصور.
  • تحكم يدوي ومستقل: واجهة الويب كتدعم الضغطات المباشرة، والسوايب، والتمرير، والكتابة، وHome، وBack، والمهام اللي كيسوقها الذكاء الاصطناعي.
  • تنفيذ قابل للمراقبة: الواجهة كتعرض شاشة التليفون مباشرة، والخطط، والسجلات، ولقطات الشاشة، والعمليات، والاستدلال، ومعلومات التوقيت.
  • ضوابط السلامة: زر التوقيف الاستعجالي كيوقف الوكيل وكيحرر المؤشر.

شنو خاصك

  • لوحة ESP32-S3: المشروع تجرّب مع Seeed Studio XIAO ESP32S3 بلا مكونات إضافية. لوحة أخرى من نوع ESP32-S3 تقدر تخدم إلا كان منفذ USB-C ديالها مربوط بواجهة USB الأصلية ديال الشريحة.
  • iPhone: الموديلات اللي فيها USB-C تقدر تربطها مباشرة. الموديلات اللي فيها Lightning خاصها Lightning to USB Camera Adapter.
  • الكمبيوتر: جهاز macOS ولا Linux فـ نفس الشبكة مع الـ iPhone.
  • Wi-Fi: إعدادات اللوحة كتحتاج اسم شبكة 2.4 GHz وكلمة السر.
  • موديل الرؤية: نقطة اتصال سحابية ولا محلية متوافقة مع OpenAI وكتقبل إدخال الصور.

الـ iPhone كيمدّ اللوحة بالطاقة. إلا كان خاص التليفون يتشارجا فنفس الوقت، استعمل 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. ربط ESP32-S3 بالكمبيوتر عبر USB، نسخ ملف الأسرار النموذجي، وبدّل الملف الجديد.

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

فـ hardware/hid_bridge/secrets.h، دخل اسم شبكة Wi-Fi ديال 2.4 GHz، وكلمة سر Wi-Fi، وعنوان IP ديال الكمبيوتر اللي غادي يشغّل السيرفر. من بعد فلّاشي اللوحة:

hardware/flash.sh

سكريبت الفلاش كيقبل اختيارياً منفذ تسلسلي وراية --debug. الفيرموير ديال التصحيح كيعيد إرسال الأوامر والمدد ديالها عبر USB serial.

3. ثبّت UxPlay

فـ macOS، ثبّت UxPlay باستعمال Homebrew:

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

الـ planner كينشئ خطة قصيرة، والـ actor كيراجع السكرينشوط الحالي بشكل متكرر وكيختار إجراء. تفرج فالعرض المباشر ديال الهاتف واللوغ ملي كتكون المهمة خدامة.

حائط الخطوات كيسجّل السكرينشوط المستعمل فكل قرار. وكيبيّن حتى النقر أو السحب المختار فوق الصورة، وكيعرض التفكير والتوقيت ديال الموديل. إلا اخترتي بطاقة خطوة، كتحلّ لك عرض أكبر.

استعمل التحكم اليدوي

  • كليك على صورة الهاتف المباشرة باش تنقر فداك الموضع.
  • جرّ فوق الصورة باش تدير سحب.
  • استعمل إدخال التمرير باش تمرّر فالهاتف.
  • استعمل أدوات التحكم المتوفرة ديال Home وBack وإدخال النص والمفاتيح.

إلا بدا الـ agent كيتصرف بشكل غير متوقع، فعّل 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.

استعمال متقدم وحل المشاكل

عيّن موديلات منفصلة للـ planner والـ actor

الـ planner والـ actor يقدرو يستعملو نفس الموديل، ولكن متغيرات البيئة الخاصة بكل دور كتخليك تبدّل إعدادات الموديل بشكل مستقل. استعمل الصيغ PLANNER_* وACTOR_* ديال متغيرات LLM_* المناسبة ملي كتحتاج واجهات أو موديلات منفصلة.

ربط سيرفر موديل محلي

أي سيرفر متوافق مع 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

وضع التصحيح كيسجّل كل أمر ديال البورد والمدة ديالو. وكيصايب حتى مجلد واحد لكل تشغيل ديال الـ agent تحت ~/.hidagent/traces/. المجلد فيه steps.jsonl، اللي كيشمل prompts ديال الموديل، والردود الخام، وقياسات المدة، والإجراءات، وزيد عليهم السكرينشوطات اللي شافتها استدعاءات الموديل.

فهم بروتوكول البورد

  • ping كيدير فحص ديال الحالة.
  • home كيدفع المؤشر للزاوية الفوقانية اليسرى باش يحدد موضع معروف.
  • move <dx> <dy> كيحرّك المؤشر نسبياً وبسرعة ثابتة.
  • press وrelease وclick كيتحكمو فزر الفأرة اليسر.
  • scroll <v> <h> كيرسل إدخال ديال عجلة التمرير العمودي والأفقي.
  • type <text> كيدخل نص ASCII.
  • key <combo> كيرسل المفاتيح أو التركيبات بحال enter وcmd+h ولا cmd+space.

حل مشاكل اكتشاف AirPlay فـ Linux

إلا كان فالكمبيوتر كثر من واجهة شبكة، والـ iPhone ما كيبانش ليه المستقبل، حدّد إعلانات Avahi mDNS فالواجهة اللي مربوطة بشبكة الهاتف.

القيود المعروفة

  • ‏iOS ما كيعكسش إدخال رمز الدخول، وApple Pay، والفيديو المحمي بـ DRM، وبعض الشاشات المحمية الأخرى، وهادي علاش الوكيل ما كيقدرش يشوفهم.
  • كيوقف انعكاس الشاشة ملي كيتقفل الهاتف. عطّل القفل التلقائي مادام الوكيل خدام.
  • إدخال النص من لوحة المفاتيح محدود بـ ASCII.
  • خاص معايرة المؤشر تعاود من بعد تغيير سرعة التتبع ديال AssistiveTouch.
  • الوكيل كيعتمد على مسار شبكة خدام بين اللوحة والخادم، وعلى بث AirPlay متوفر بين الهاتف والكمبيوتر.

الاستعمال المسؤول

أتمت غير الأجهزة والحسابات اللي كتملكها أو عندك الصلاحية تستعملها، وتبع شروط التطبيقات المعنية.

حيت الوكيل يقدر يتصرف بنفس أنواع الإدخال اللي كيستعملها الشخص، راقب التشغيلات النشيطة وخلي زر التوقيف الاستعجالي ساهل الوصول.

الخلاصة

كيجمع ESP32 iPhone Agent بين انعكاس AirPlay، وجسر USB HID منخفض التكلفة مبني على ESP32-S3، ونموذج رؤية متوافق مع OpenAI، باش يأتمت iPhone فعلي بلا سلسلة أدوات التطوير التقليدية ديال Apple. منين كتوجد البرنامج الثابت، والخادم، ونقطة نهاية النموذج، وAssistiveTouch، والانعكاس، ومعايرة المؤشر، تقدر تعطي أهداف باللغة الطبيعية، وتفحص كل قرار، وتتدخل يدوياً، وتجمع سجلات مفصلة للتصحيح.