Android Debug Bridge (adb)

‫Android Debug Bridge (adb) هي أداة متعددة الاستخدامات تعمل من سطر الأوامر وتتيح لك التواصل مع جهاز. يسهّل الأمر adb تنفيذ مجموعة متنوعة من إجراءات الجهاز، مثل تثبيت التطبيقات وتصحيح أخطائها. توفّر adb إمكانية الوصول إلى واجهة Unix يمكنك استخدامها لتنفيذ مجموعة متنوعة من الأوامر على جهاز. وهو برنامج يعمل بنظام العميل والخادم ويتضمّن ثلاثة مكوّنات:

• العميل، الذي يرسل الأوامر يتم تشغيل العميل على جهاز التطوير. يمكنك استدعاء عميل من وحدة طرفية لسطر الأوامر عن طريق إصدار أمر adb.
• برنامج خفي (adbd)، ينفّذ الأوامر على الجهاز يعمل البرنامج الخفي كعملية في الخلفية على كل جهاز.
• خادم يدير عملية التواصل بين العميل والبرنامج الخفي يعمل الخادم كعملية في الخلفية على جهاز التطوير.

يتم تضمين adb في حزمة "أدوات منصة حزمة تطوير البرامج (SDK) لنظام التشغيل Android". يمكنك تنزيل هذه الحزمة باستخدام مدير حزمة تطوير البرامج (SDK) الذي يثبّتها في android_sdk/platform-tools/. إذا كنت تريد حزمة "أدوات منصة حزمة تطوير البرامج (SDK) لنظام التشغيل Android" المستقلة، يمكنك تنزيلها من هنا.

للحصول على معلومات حول ربط جهاز لاستخدامه عبر adb، بما في ذلك كيفية استخدام "مساعد الربط" لتحديد المشاكل الشائعة وحلّها، يُرجى الاطّلاع على تشغيل التطبيقات على جهاز.

طريقة عمل adb

عند بدء تشغيل adb، يتحقّق البرنامج أولاً مما إذا كانت هناك عملية خادم adb قيد التشغيل. إذا لم يكن هناك خادم، سيبدأ عملية الخادم. عند بدء تشغيل الخادم، يتم ربطه بمنفذ TCP المحلي 5037 ويستمع إلى الأوامر المرسَلة من adb العملاء.

ملاحظة: تستخدم جميع برامج adb المنفذ 5037 للتواصل مع خادم adb.

بعد ذلك، يضبط الخادم عمليات الربط بجميع الأجهزة التي يتم تشغيلها. يتم تحديد موقع المحاكيات من خلال فحص المنافذ ذات الأرقام الفردية في النطاق من 5555 إلى 5585، وهو النطاق الذي تستخدمه أول 16 محاكيًا. عندما يعثر الخادم على برنامج adb خفي (adbd)، يتم إعداد اتصال بهذا المنفذ.

يستخدم كل محاكي زوجًا من المنافذ المتسلسلة، أي منفذًا يحمل رقمًا زوجيًا لعمليات ربط وحدة التحكّم ومنفذًا يحمل رقمًا فرديًا لعمليات ربط adb. على سبيل المثال:

المحاكي 1، وحدة التحكّم: 5554
المحاكي 1، adb: 5555
المحاكي 2، وحدة التحكّم: 5556
المحاكي 2، adb: 5557
وهكذا.

كما هو موضّح، فإنّ المحاكي المتصل بـ adb على المنفذ 5555 هو نفسه المحاكي الذي تستمع وحدة التحكّم الخاصة به على المنفذ 5554.

بعد أن يضبط الخادم عمليات الربط بجميع الأجهزة، يمكنك استخدام أوامر adb للوصول إلى هذه الأجهزة. بما أنّ الخادم يدير عمليات الاتصال بالأجهزة ويتعامل مع الأوامر الواردة من عدة عملاء adb، يمكنك التحكّم في أي جهاز من أي عميل أو من نص برمجي.

تفعيل تصحيح الأخطاء عبر adb على جهازك

لاستخدام adb مع جهاز متصل عبر USB، يجب تفعيل تصحيح أخطاء USB في إعدادات نظام الجهاز ضمن خيارات المطوّرين. في الإصدار 4.2 من نظام التشغيل Android (المستوى 17 لواجهة برمجة التطبيقات) والإصدارات الأحدث، تكون شاشة خيارات المطوّرين مخفية تلقائيًا. ولإظهارها، يجب تفعيل خيارات المطوّرين.

يمكنك الآن ربط جهازك باستخدام كابل USB. يمكنك التأكّد من أنّ جهازك متصل من خلال تنفيذ adb devices من الدليل android_sdk/platform-tools/. إذا كان الجهاز متصلاً، سيظهر اسمه ضمن "الأجهزة".

ملاحظة: عند توصيل جهاز يعمل بالإصدار 4.2.2 من نظام التشغيل Android (المستوى 17 من واجهة برمجة التطبيقات) أو إصدار أحدث، يعرض النظام مربّع حوار يسألك عمّا إذا كنت تريد قبول مفتاح RSA الذي يتيح تصحيح الأخطاء من خلال هذا الكمبيوتر. تحمي آلية الأمان هذه أجهزة المستخدمين لأنّها تضمن عدم إمكانية تنفيذ تصحيح أخطاء الجهاز عبر USB وأوامر Adb الأخرى إلا إذا كان بإمكانك فتح قفل الجهاز والموافقة على مربع الحوار.

لمزيد من المعلومات حول الربط بجهاز عبر USB، يُرجى الاطّلاع على تشغيل التطبيقات على جهاز.

الاتصال بجهاز عبر شبكة Wi-Fi

ملاحظة: لا تنطبق التعليمات الواردة أدناه على أجهزة Wear التي تعمل بالإصدار Android 11 (مستوى واجهة برمجة التطبيقات 30). راجِع دليل تصحيح أخطاء تطبيق Wear OS للحصول على مزيد من المعلومات.

يتيح نظام التشغيل Android 11 (مستوى واجهة برمجة التطبيقات 30) والإصدارات الأحدث نشر تطبيقك وتصحيح أخطائه لاسلكيًا من محطة العمل باستخدام Android Debug Bridge (adb). على سبيل المثال، يمكنك نشر تطبيقك القابل للتصحيح على عدة أجهزة بعيدة بدون الحاجة إلى ربط جهازك فعليًا عبر USB. يؤدي ذلك إلى استبعاد الحاجة إلى التعامل مع مشاكل الاتصال الشائعة عبر USB، مثل تثبيت برنامج التشغيل.

يقدّم الإصدار 17 من نظام التشغيل Android، إلى جانب adb 37.0.0، الإصدار 2.0 من adb Wi-Fi الذي يحلّ العديد من مشاكل سهولة الاستخدام في الإصدار السابق. والجدير بالذكر أنّ الجهاز سيتصل تلقائيًا بمحطة العمل عند اتصاله بشبكة موثوق بها لتصحيح الأخطاء لاسلكيًا.

قبل البدء في استخدام ميزة "تصحيح الأخطاء اللاسلكي"، عليك تنفيذ ما يلي:

• تأكَّد من أنّ محطة العمل والجهاز متصلان بشبكة لاسلكية نفسها.

• تأكَّد من أنّ جهازك يعمل بالإصدار 11 من نظام التشغيل Android (المستوى 30 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث للهاتف أو الإصدار 13 من نظام التشغيل Android (المستوى 33 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث للتلفزيون وWearOS. لمزيد من المعلومات، يُرجى الاطّلاع على التحقّق من إصدار Android وتحديثه.

• على محطة العمل، يجب الترقية إلى أحدث إصدار من أدوات منصة حزمة تطوير البرامج (SDK).

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

ملاحظة: عليك ربط جهازك بمحطة العمل مرة واحدة فقط، وسيظل الجهاز مرتبطًا بمحطة العمل إلى أن توقف الربط أو تلغي أذونات تصحيح أخطاء adb على جهازك. وسيتصل الجهاز ومحطة العمل تلقائيًا عندما يكونان على الشبكة نفسها.

1. فعِّل خيارات المطوّرين على جهازك.

2. على جهازك، انقر على تصحيح الأخطاء لاسلكيًا:

   

   الشكل 1: طلب تصحيح الأخطاء لاسلكيًا على هاتف Google Pixel

3. السماح باستخدام ميزة "تصحيح الأخطاء اللاسلكي" على شبكتك يُرجى العِلم أنّ وضع علامة في مربّع الاختيار السماح باستخدام هذه الميزة على هذه الشبكة دائمًا يجعل الشبكة شبكة موثوق بها لتصحيح الأخطاء اللاسلكي. سيسمح جهازك دائمًا بتصحيح الأخطاء اللاسلكي على هذه الشبكة فور اتصال الجهاز بها.



الشكل 2: إعداد تصحيح الأخطاء عبر شبكة Wi-Fi على هاتف Google Pixel

ملاحظة: يمكن لمستخدمي Android Studio إقران أجهزتهم باستخدام رمز استجابة سريعة، وذلك من خلال النقر على إقران الجهاز باستخدام رمز الاستجابة السريعة ومسح رمز الاستجابة السريعة الذي تم الحصول عليه من مربّع الحوار "إقران الأجهزة عبر شبكة Wi-Fi" في Android Studio.

4. على جهازك، انقر على الإقران باستخدام رمز الإقران ودوِّن عنوان IP ورقم المنفذ ورمز الإقران المعروض على الجهاز.

5. على محطة العمل، افتح نافذة أوامر طرفية وانتقِل إلى android_sdk/platform-tools.

6. في نافذة الجهاز الطرفي لمحطة العمل، شغِّل الأمر adb pair ipaddr:port. استخدِم عنوان IP ورقم المنفذ المذكورَين أعلاه.

7. عندما يُطلب منك ذلك، أدخِل رمز الإقران كما هو موضّح أدناه.

   

   الشكل 3: ستظهر رسالة تشير إلى أنّه تم إقران جهازك بنجاح.

8. بعد إقران جهازك، تأكَّد من أنّه متصل، ويمكنك الآن استخدامه لاسلكيًا كما لو كنت تستخدم اتصال USB.

   لإلغاء إقران محطة العمل، انتقِل إلى تصحيح الأخطاء لاسلكيًا على جهازك. انقر على اسم محطة العمل ضِمن الأجهزة المقترنة، ثم اختَر حذف. بدلاً من ذلك، يمكنك النقر على إبطال أذونات تصحيح أخطاء adb في صفحة "الإعدادات" على جهازك لإلغاء إقران محطة العمل وجميع محطات العمل الأخرى التي سبق إقرانها.

9. إذا أردت تفعيل ميزة "تصحيح الأخطاء اللاسلكي" وإيقافها بسرعة، يمكنك استخدام مربّعات مطوّري البرامج في الإعدادات السريعة الخاصة بميزة تصحيح الأخطاء اللاسلكي، والتي يمكن العثور عليها في خيارات المطوّرين > مربّعات مطوّري البرامج في الإعدادات السريعة.

   

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

حلّ مشاكل الاتصال اللاسلكي

إذا كنت تواجه مشاكل في الاتصال بجهازك لاسلكيًا، جرِّب الخطوات التالية لتحديد المشاكل وحلّها.

التحقّق مما إذا كانت محطة العمل والجهاز يستوفيان المتطلبات الأساسية

تأكَّد من أنّ محطة العمل والجهاز يستوفيان المتطلبات الأساسية الواردة في بداية هذا القسم.

التحقّق مما إذا كان إعداد adb على محطة العمل صحيحًا

للتحقّق من صحة إعداد ADB على محطة العمل، افتح نافذة طرفية على محطة العمل وأدخِل adb server-status. تأكَّد من أنّ الناتج يعرض ما يلي:

• ‫version: "37.0.0" أو إصدار أحدث: إذا لم يكن الأمر كذلك، نزِّل أحدث إصدار من أدوات النظام الأساسي لحزمة SDK.
• mdns_enabled: true: إذا تم ضبط هذا الخيار على false، لن يتمكّن adb من العثور تلقائيًا على الأجهزة على شبكتك. لحلّ هذه المشكلة، عليك ضبط متغيّر البيئة ADB_MDNS على 1، ثم إعادة تشغيل خادم adb من خلال تنفيذ الأمر adb kill-server ثم الأمر adb start-server.
• mdns_backend: LIBADBMDNS: إذا لم يكن الأمر كذلك، يعني ذلك أنّ أداة adb تستخدم مكتبة قديمة لاكتشاف الأجهزة تلقائيًا على شبكتك. لحلّ هذه المشكلة، عليك ضبط متغيّر البيئة ADB_MDNS_OPENSCREEN على 0، ثم إعادة تشغيل خادم adb من خلال تنفيذ الأمر adb kill-server ثم الأمر adb start-server.

التحقّق مما إذا كانت شبكتك تتيح استخدام mDNS

تعتمد أداة تصحيح أخطاء Android (adb) على خدمة mDNS للبحث عن الأجهزة المقترنة والاتصال بها تلقائيًا. للتحقّق مما إذا كانت شبكتك تتيح استخدام mDNS، اتّبِع الخطوات التالية:

1. على جهازك، فعِّل تصحيح الأخطاء لاسلكيًا كما هو موضّح في قسم الاتصال بجهاز عبر شبكة Wi-Fi.

2. على محطة العمل، افتح نافذة طرفية وأدخِل adb mdns track-services --proto-text.

3. تأكَّد من أنّ الناتج ليس فارغًا ويتضمّن خدمة TLS مع عنوان IP ورقم منفذ جهازك. إذا كانت النتيجة فارغة، هذا يعني أنّ شبكتك لا تتوافق مع بروتوكول mDNS. مثال على الإخراج:

   tls {
     service {
       instance: "adb-35121FDJH000R8-xyMD0H"
       service: "_adb-tls-connect._tcp"
       ipv4: "192.168.84.23"
       ipv6: "fe80:0:0:0:fc7a:299d:8d38:6c1c"
       port: 37895
       product_model: "Pixel 8"
       build_version_sdk_full: "37.0"
       given_name: "sherifeid Pixel"
       serial: "35121FDJH000R8"
       mdns_service_version: "2.0"
       hostname: "Android_CXUKYJY1.local"
     }
   }
             

التحقّق مما إذا كان جهازك يتيح استخدام ميزة "تصحيح الأخطاء عبر Wi-Fi" (الإصدار 2.0)

ملاحظة: يتوافق الإصدار 2.0 من تصحيح أخطاء Android عبر Wi-Fi مع الإصدار 17 من نظام التشغيل Android والإصدارات الأحدث.

لمعرفة ما إذا كان جهازك يتيح استخدام ميزة "تصحيح الأخطاء عبر Wi-Fi" 2.0، اتّبِع الخطوات التالية:

1. على جهازك، فعِّل تصحيح الأخطاء لاسلكيًا كما هو موضّح في قسم الاتصال بجهاز عبر شبكة Wi-Fi.

2. على محطة العمل، افتح نافذة طرفية وأدخِل adb mdns track-services --proto-text.

3. تأكَّد من أنّ الناتج يحتوي على mdns_service_version: "2.0" أو إصدار أحدث. إذا لم يكن الأمر كذلك، يعني هذا أنّ جهازك لا يعمل بالإصدار 17 من نظام التشغيل Android أو إصدار أحدث ولا يتوافق مع الإصدار 2.0 من ميزة "تصحيح الأخطاء عبر Wi-Fi". للتحديث إلى الإصدار 17 من نظام التشغيل Android أو إصدار أحدث، تحقَّق مما إذا كان جهازك يتضمّن أي تحديثات معلّقة للنظام. التحقّق من إصدار Android وتحديثه

الإبلاغ عن مشكلة جديدة

إذا كنت لا تزال تواجه مشاكل في الاتصال بجهازك لاسلكيًا، يمكنك الإبلاغ عن مشكلة جديدة. يُرجى التأكّد من تقديم المعلومات التالية في بلاغك:

• سجلّات جهازك: أعِد إنتاج المشكلة وأرفِق سجلّات الجهاز.
• سجلّات adb على محطة العمل:
  1. اضبط متغيّر البيئة ADB_TRACE=all.
  2. أعِد تشغيل خادم adb من خلال تنفيذ الأمر adb kill-server ثم الأمر adb start-server.
  3. أعِد إظهار المشكلة.
  4. تحديد موقع ملفات السجلّ: شغِّل adb server-status وأرفِق ملف السجلّ المشار إليه في الناتج log_absolute_path.

الاتصال لاسلكيًا بجهاز بعد الاتصال الأوّلي عبر USB (الخيار الوحيد المتاح على الإصدار 10 من نظام التشغيل Android والإصدارات الأقدم)

ملاحظة: يمكن استخدام سير العمل هذا أيضًا على الإصدار 11 من نظام التشغيل Android (والإصدارات الأحدث)، مع العلم أنّه يتضمّن أيضًا عملية ربط *أولي* عبر كابل USB.

ملاحظة: لا تنطبق التعليمات التالية على أجهزة Wear التي تعمل بالإصدار Android 10 (مستوى واجهة برمجة التطبيقات 29) أو إصدار أقدم. راجِع الدليل حول تصحيح أخطاء تطبيق Wear OS للحصول على مزيد من المعلومات.

يتواصل adb عادةً مع الجهاز عبر USB، ولكن يمكنك أيضًا استخدام adb عبر شبكة Wi-Fi. لتوصيل جهاز يعمل بالإصدار 10 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 29) أو إصدار أقدم، اتّبِع الخطوات الأولية التالية عبر كابل USB:

1. وصِّل جهاز Android وadb الكمبيوتر المضيف بشبكة Wi-Fi مشتركة.

ملاحظة: يُرجى العِلم بأنّه ليست كل نقاط الوصول مناسبة. قد تحتاج إلى استخدام نقطة وصول تم ضبط جدار الحماية فيها بشكل صحيح لتتوافق مع adb.

2. وصِّل الجهاز بالكمبيوتر المضيف باستخدام كابل USB.
3. اضبط جهاز الاختبار على الاستماع إلى اتصال بروتوكول TCP/IP على المنفذ 5555:

   adb tcpip 5555
   

4. افصل كابل USB عن جهاز الاختبار.
5. ابحث عن عنوان IP لجهاز Android. على سبيل المثال، في جهاز Nexus، يمكنك العثور على عنوان IP من خلال الانتقال إلى الإعدادات > لمحة عن الجهاز اللوحي (أو لمحة عن الهاتف) > الحالة > عنوان IP.
6. اتّصِل بالجهاز من خلال عنوان IP الخاص به:

   adb connect device_ip_address:5555
   

7. تأكَّد من أنّ الكمبيوتر المضيف متصل بجهاز الاختبار:

   $ adb devices
   List of devices attached
   device_ip_address:5555 device
   

تم ربط جهازك الآن بشبكة "adb".

في حال فقدان اتصال adb بجهازك، اتّبِع الخطوات التالية:

• تأكَّد من أنّ الجهاز المضيف لا يزال متصلاً بشبكة Wi-Fi نفسها التي يتصل بها جهاز Android.
• أعِد الربط من خلال تنفيذ الخطوة adb connect مرة أخرى.
• إذا لم ينجح ذلك، أعِد ضبط مضيف adb باتّباع الخطوات التالية:

  adb kill-server
  

  بعد ذلك، ابدأ من جديد.

طلب البحث عن الأجهزة

قبل إصدار أوامر adb، من المفيد معرفة مثيلات الأجهزة المتصلة بخادم adb. أنشئ قائمة بالأجهزة المتصلة باستخدام الأمر devices:

  adb devices -l
  

في المقابل، تطبع adb معلومات الحالة التالية لكل جهاز:

• الرقم التسلسلي: adb ينشئ سلسلة لتحديد الجهاز بشكل فريد من خلال رقم المنفذ. في ما يلي مثال على الرقم التسلسلي: emulator-5554
• الحالة: يمكن أن تكون حالة اتصال الجهاز إحدى الحالات التالية:
  • offline: الجهاز غير متصل بشبكة adb أو لا يستجيب.
  • device: الجهاز متصل بخادم adb. يُرجى العِلم أنّ هذه الحالة لا تعني أنّ نظام Android قد تم تشغيله بالكامل وأصبح جاهزًا للعمل، لأنّ الجهاز يتصل بشبكة adb أثناء استمرار عملية تشغيل النظام. بعد بدء التشغيل، تكون هذه هي حالة التشغيل العادية للجهاز.
  • no device: لم يتم توصيل أي جهاز.
• الوصف: إذا تضمّن الأمر الخيار -l، سيخبرك الأمر devices بنوع الجهاز. وتكون هذه المعلومات مفيدة عندما تكون لديك أجهزة متعددة متصلة، ما يتيح لك التمييز بينها.

يوضّح المثال التالي الأمر devices ونتيجته. هناك ثلاثة أجهزة قيد التشغيل. أول سطرَين في القائمة هما محاكيان، أما السطر الثالث فهو جهاز متصل بالكمبيوتر.

$ adb devices
List of devices attached
emulator-5556 device product:sdk_google_phone_x86_64 model:Android_SDK_built_for_x86_64 device:generic_x86_64
emulator-5554 device product:sdk_google_phone_x86 model:Android_SDK_built_for_x86 device:generic_x86
0a388e93      device usb:1-1 product:razor model:Nexus_7 device:flo

المحاكي غير مُدرَج

يحتوي الأمر adb devices على تسلسل أوامر خاص بحالات نادرة يتسبّب في عدم ظهور المحاكيات قيد التشغيل في ناتج الأمر adb devices، على الرغم من أنّ المحاكيات تظهر على سطح المكتب. يحدث ذلك عندما تكون جميع الشروط التالية صحيحة:

• خادم adb ليس قيد التشغيل.
• يمكنك استخدام الأمر emulator مع الخيار -port أو -ports مع قيمة منفذ ذات رقم فردي بين 5554 و5584.
• المنفذ ذو الرقم الفردي الذي اخترته غير مشغول، لذا يمكن إجراء اتصال المنفذ على رقم المنفذ المحدّد، أو إذا كان مشغولاً، سيتم التبديل إلى منفذ آخر يستوفي المتطلبات الواردة في النقطة 2.
• يمكنك بدء تشغيل خادم adb بعد بدء تشغيل المحاكي.

إحدى طرق تجنُّب هذه المشكلة هي السماح للمحاكي باختيار منافذه الخاصة وعدم تشغيل أكثر من 16 محاكيًا في الوقت نفسه. هناك طريقة أخرى وهي بدء تشغيل خادم adb دائمًا قبل استخدام الأمر emulator، كما هو موضّح في الأمثلة التالية.

المثال 1: في تسلسل الأوامر التالي، يبدأ الأمر adb devices تشغيل الخادم adb، ولكن لا تظهر قائمة الأجهزة.

أوقِف خادم adb وأدخِل الأوامر التالية بالترتيب الموضّح. بالنسبة إلى اسم AVD، أدخِل اسم AVD صالحًا من نظامك. للحصول على قائمة بأسماء الأجهزة الافتراضية لنظام التشغيل Android، اكتب emulator -list-avds. يقع الأمر emulator في الدليل android_sdk/tools.

$ adb kill-server
$ emulator -avd Nexus_6_API_25 -port 5555
$ adb devices

List of devices attached
* daemon not running. starting it now on port 5037 *
* daemon started successfully *

المثال 2: في تسلسل الأوامر التالي، يعرض adb devices قائمة الأجهزة لأنّه تم بدء تشغيل الخادم adb أولاً.

للاطّلاع على المحاكي في الناتج adb devices، أوقِف الخادم adb، ثم أعِد تشغيله بعد استخدام الأمر emulator وقبل استخدام الأمر adb devices، كما يلي:

$ adb kill-server
$ emulator -avd Nexus_6_API_25 -port 5557
$ adb start-server
$ adb devices

List of devices attached
emulator-5557 device

لمزيد من المعلومات حول خيارات سطر الأوامر الخاصة بالمحاكي، يُرجى الاطّلاع على خيارات بدء التشغيل من سطر الأوامر.

إرسال أوامر إلى جهاز معيّن

إذا كانت عدة أجهزة تعمل، يجب تحديد جهاز الاختبار عند تنفيذ الأمر adb. لتحديد الهدف، اتّبِع الخطوات التالية:

1. استخدِم الأمر devices للحصول على الرقم التسلسلي للجهاز المستهدف.
2. بعد الحصول على الرقم التسلسلي، استخدِم الخيار -s مع الأوامر adb لتحديد الرقم التسلسلي.
   1. إذا كنت ستصدر الكثير من أوامر adb، يمكنك ضبط متغير البيئة $ANDROID_SERIAL ليحتوي على الرقم التسلسلي بدلاً من ذلك.
   2. في حال استخدام السمتَين -s و$ANDROID_SERIAL معًا، ستلغي السمة -s السمة $ANDROID_SERIAL.

في المثال التالي، يتم الحصول على قائمة الأجهزة المتصلة، ثم يتم استخدام الرقم التسلسلي لأحد الأجهزة لتثبيت helloWorld.apk على هذا الجهاز:

$ adb devices
List of devices attached
emulator-5554 device
emulator-5555 device
0.0.0.0:6520  device

# To install on emulator-5555
$ adb -s emulator-5555 install helloWorld.apk
# To install on 0.0.0.0:6520
$ adb -s 0.0.0.0:6520 install helloWorld.apk

ملاحظة: إذا أصدرت أمرًا بدون تحديد جهاز الاختبار عند توفّر أجهزة متعددة، ستعرض adb رسالة الخطأ "Adb: أكثر من جهاز واحد/محاكي واحد".

إذا كانت لديك أجهزة متعددة متاحة ولكن جهاز واحد فقط هو محاكي، استخدِم الخيار -e لإرسال الأوامر إلى المحاكي. إذا كانت هناك أجهزة متعددة ولكن تم توصيل جهاز واحد فقط، استخدِم الخيار -d لإرسال الأوامر إلى الجهاز.

تثبيت تطبيق

يمكنك استخدام adb لتثبيت حزمة APK على محاكي أو جهاز متصل باستخدام الأمر install:

adb install path_to_apk

يجب استخدام الخيار -t مع الأمر install عند تثبيت حزمة APK تجريبية. لمزيد من المعلومات، راجِع -t.

لتثبيت حِزم APK متعددة، استخدِم install-multiple. ويكون ذلك مفيدًا إذا نزّلت جميع حِزم APK الخاصة بجهاز معيّن لتطبيقك من Play Console وأردت تثبيتها على محاكي أو جهاز فعلي.

لمزيد من المعلومات حول كيفية إنشاء ملف APK يمكنك تثبيته على مثيل محاكي/جهاز، راجِع إنشاء تطبيقك وتشغيله.

ملاحظة: إذا كنت تستخدم "استوديو Android"، لن تحتاج إلى استخدام adb مباشرةً لتثبيت تطبيقك على المحاكي أو الجهاز. بدلاً من ذلك، يتولّى "استوديو Android" عملية تجميع التطبيق وتثبيته.

إعداد قاعدة إعادة توجيه المنفذ

استخدِم الأمر forward لإعداد إعادة توجيه منفذ عشوائي، ما يؤدي إلى إعادة توجيه الطلبات على منفذ مضيف معيّن إلى منفذ مختلف على جهاز. يضبط المثال التالي إعادة توجيه المنفذ 6100 للمضيف إلى المنفذ 7100 للجهاز:

adb forward tcp:6100 tcp:7100

يضبط المثال التالي إعادة توجيه منفذ المضيف 6100 إلى local:logd:

adb forward tcp:6100 local:logd

قد يكون ذلك مفيدًا إذا كنت تحاول تحديد ما يتم إرساله إلى منفذ معيّن على الجهاز. سيتم تسجيل جميع البيانات التي تم تلقّيها في برنامج خفي لتسجيل بيانات النظام وعرضها في سجلّات الجهاز.

نسخ الملفات من جهاز وإليه

استخدِم الأمرَين pull وpush لنسخ الملفات إلى جهاز ومنه. على عكس الأمر install، الذي ينسخ ملف APK فقط إلى موقع محدّد، يتيح لك الأمران pull وpush نسخ أدلة وملفات عشوائية إلى أي موقع على الجهاز.

لنسخ ملف أو دليل وأدلته الفرعية من الجهاز، اتّبِع الخطوات التالية:

adb pull remote local

لنسخ ملف أو دليل وأدلته الفرعية إلى الجهاز، اتّبِع الخطوات التالية:

adb push local remote

استبدِل local وremote بمسارات الملفات أو الدليل المستهدَف على جهاز التطوير (المحلي) وعلى الجهاز (عن بُعد). على سبيل المثال:

adb push myfile.txt /sdcard/myfile.txt

إيقاف خادم adb

في بعض الحالات، قد تحتاج إلى إنهاء عملية خادم adb ثم إعادة تشغيلها لحلّ المشكلة. على سبيل المثال، قد يحدث ذلك إذا لم يستجب adb لأحد الطلبات.

لإيقاف خادم adb، استخدِم الأمر adb kill-server. يمكنك بعد ذلك إعادة تشغيل الخادم عن طريق إصدار أي أمر adb آخر.

إصدار أوامر adb

أصدِر أوامر adb من سطر أوامر على جهاز التطوير أو من نص برمجي باستخدام ما يلي:

adb [-d | -e | -s serial_number] command

إذا كان هناك محاكي واحد فقط قيد التشغيل أو جهاز واحد فقط متصل، يتم إرسال الأمر adb إلى هذا الجهاز تلقائيًا. في حال تشغيل محاكيات متعددة و/أو ربط أجهزة متعددة، عليك استخدام الخيار -d أو -e أو -s لتحديد جهاز الاختبار الذي يجب توجيه الأمر إليه.

يمكنك الاطّلاع على قائمة مفصّلة بجميع أوامر adb المتوافقة باستخدام الأمر التالي:

adb --help

إصدار أوامر shell

يمكنك استخدام الأمر shell لإصدار أوامر الجهاز من خلال adb أو لبدء واجهة تفاعلية. لإصدار أمر واحد، استخدِم الأمر shell على النحو التالي:

adb [-d |-e | -s serial_number] shell shell_command

لبدء واجهة تفاعلية على جهاز، استخدِم الأمر shell على النحو التالي:

adb [-d | -e | -s serial_number] shell

للخروج من نافذة تفاعلية، اضغط على Control+D أو اكتب exit.

يوفّر نظام التشغيل Android معظم أدوات سطر الأوامر المعتادة في نظام Unix. للحصول على قائمة بالأدوات المتاحة، استخدِم الأمر التالي:

adb shell ls /system/bin

تتوفّر المساعدة لمعظم الأوامر من خلال الوسيطة --help. يتم توفير العديد من أوامر shell من خلال toybox. تتوفّر المساعدة العامة التي تنطبق على جميع أوامر Toybox من خلال toybox --help.

في الإصدار 23 والإصدارات الأحدث من "أدوات منصة Android"، تعالج أداة adb الوسيطات بالطريقة نفسها التي يعالجها الأمر ssh(1). وقد أدّى هذا التغيير إلى حلّ الكثير من المشاكل المتعلّقة بإدخال الأوامر، كما أتاح تنفيذ الأوامر التي تحتوي على أحرف وصفية في shell، مثل adb install Let\'sGo.apk، بأمان. ويعني هذا التغيير أيضًا أنّ طريقة تفسير أي أمر يحتوي على أحرف وصفية في shell قد تغيّرت.

على سبيل المثال، أصبح adb shell setprop key 'two words' الآن خطأ، لأنّ علامات الاقتباس يتم تجاهلها من خلال الصدفة المحلية، ويرى الجهاز adb shell setprop key two words. لكي يعمل الأمر، يجب وضع علامات اقتباس مرتين، مرة لصدفة الجهاز المحلي ومرة لصدفة الجهاز البعيد، كما تفعل مع ssh(1). على سبيل المثال، تعمل adb shell setprop key "'two words'" لأنّ الصدفة المحلية تأخذ مستوى الاقتباس الخارجي، بينما يظل الجهاز يرى مستوى الاقتباس الداخلي: setprop key 'two words'. يمكنك أيضًا استخدام علامة الهروب، ولكن عادةً ما يكون استخدام علامات الاقتباس مرتين أسهل.

راجِع أيضًا أداة سطر الأوامر Logcat، وهي أداة مفيدة لمراقبة سجلّ النظام.

مدير نشاط المكالمات

يمكنك داخل adb shell إصدار أوامر باستخدام أداة "مدير الأنشطة" (am) لتنفيذ إجراءات مختلفة في النظام، مثل بدء نشاط وإيقاف عملية بالقوة وبث هدف وتعديل خصائص شاشة الجهاز وغير ذلك.

أثناء استخدام shell، تكون بنية الجملة am كما يلي:

am command

يمكنك أيضًا إصدار أمر من "مدير الأنشطة" مباشرةً من adb بدون الدخول إلى shell عن بُعد. على سبيل المثال:

adb shell am start -a android.intent.action.VIEW

الجدول 1. الطلبات المتوفّرة في "إدارة النشاط"

مواصفات وسيطات الغرض

بالنسبة إلى أوامر "أداة إدارة الأنشطة" التي تتضمّن وسيطة intent، يمكنك تحديد الغرض باستخدام الخيارات التالية:

الاتصال بأداة إدارة الحِزم (pm)

في بيئة adb، يمكنك إصدار أوامر باستخدام أداة إدارة الحِزم (pm) لتنفيذ إجراءات وطلبات بحث على حِزم التطبيقات المثبَّتة على الجهاز.

أثناء استخدام shell، تكون بنية الجملة pm كما يلي:

pm command

يمكنك أيضًا إصدار أمر مدير حزمة مباشرةً من adb بدون الدخول إلى shell عن بُعد. على سبيل المثال:

adb shell pm uninstall com.example.MyApp

الجدول 2. أوامر مدير الحِزم المتاحة

الاتصال بمدير سياسات الأجهزة (dpm)

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

أثناء استخدام shell، تكون dpmالصيغة كما يلي:

dpm command

يمكنك أيضًا إصدار أمر "مدير سياسات الجهاز" مباشرةً من adb بدون إدخال shell عن بُعد:

adb shell dpm command

الجدول 3: أوامر "إدارة سياسات الأجهزة" المتاحة

أخذ لقطة شاشة

الأمر screencap هو أداة مساعدة في shell لالتقاط لقطة شاشة لجهاز.

أثناء استخدام shell، تكون بنية screencap كما يلي:

screencap filename

لاستخدام screencap من سطر الأوامر، أدخِل ما يلي:

adb shell screencap /sdcard/screen.png

في ما يلي مثال على جلسة لقطة شاشة، باستخدام shell adb لالتقاط لقطة الشاشة والأمر pull لتنزيل الملف من الجهاز:

$ adb shell
shell@ $ screencap /sdcard/screen.png
shell@ $ exit
$ adb pull /sdcard/screen.png

بدلاً من ذلك، إذا حذفت اسم الملف، ستكتب screencap الصورة في الإخراج العادي. عند دمجه مع الخيار -p لتحديد تنسيق PNG، يمكنك بث لقطة شاشة الجهاز مباشرةً إلى ملف على جهازك المحلي.

في ما يلي مثال على التقاط لقطة شاشة وحفظها محليًا في أمر واحد:

# use 'exec-out' instead of 'shell' to get raw data
$ adb exec-out screencap -p > screen.png

تسجيل فيديو

الأمر screenrecord هو أداة مساعدة في shell لتسجيل شاشة الأجهزة التي تعمل بالإصدار 4.4 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 19) والإصدارات الأحدث. تسجّل الأداة المساعدة نشاط الشاشة في ملف MPEG-4. يمكنك استخدام هذا الملف لإنشاء فيديوهات ترويجية أو تدريبية أو لتصحيح الأخطاء واختبارها.

في shell، استخدِم البنية التالية:

screenrecord [options] filename

لاستخدام screenrecord من سطر الأوامر، أدخِل ما يلي:

adb shell screenrecord /sdcard/demo.mp4

أوقِف تسجيل الشاشة بالضغط على Control+C، وإلا سيتوقّف التسجيل تلقائيًا بعد ثلاث دقائق أو بعد انتهاء المهلة الزمنية التي حدّدتها --time-limit.

لبدء تسجيل شاشة جهازك، نفِّذ الأمر screenrecord لتسجيل الفيديو، ثم نفِّذ الأمر pull لتنزيل الفيديو من الجهاز إلى الكمبيوتر المضيف. إليك مثال على جلسة تسجيل:

$ adb shell
shell@ $ screenrecord --verbose /sdcard/demo.mp4
(press Control + C to stop)
shell@ $ exit
$ adb pull /sdcard/demo.mp4

يمكن لأداة screenrecord التسجيل بأي دقة ومعدل نقل بيانات متوافقَين تطلبهما، مع الاحتفاظ بنسبة العرض إلى الارتفاع لشاشة الجهاز. تسجّل الأداة تلقائيًا بدقة الشاشة الأصلية واتجاهها، وبمدة قصوى تبلغ ثلاث دقائق.

في ما يلي القيود المفروضة على أداة screenrecord:

• لا يتم تسجيل الصوت مع ملف الفيديو.
• لا تتوفّر ميزة تسجيل الفيديو على الأجهزة التي تعمل بنظام التشغيل Wear OS.
• قد لا تتمكّن بعض الأجهزة من التسجيل بدقة العرض الأصلية. إذا واجهت مشاكل في تسجيل الشاشة، جرِّب استخدام دقة شاشة أقل.
• لا يمكن تدوير الشاشة أثناء التسجيل، وإذا تم تدويرها، سيتم قطع جزء من الشاشة في التسجيل.

الجدول 4. ‫screenrecord خيار

screenrecord --bit-rate 6000000 /sdcard/demo.mp4

قراءة ملفات ART الشخصية للتطبيقات

بدءًا من الإصدار 7.0 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 24)، يجمع وقت تشغيل Android (ART) ملفات تعريف التنفيذ للتطبيقات المثبَّتة، ويتم استخدامها لتحسين أداء التطبيق. يمكنك فحص ملفات التعريف التي تم جمعها لمعرفة الطرق التي يتم تنفيذها بشكل متكرر والفئات التي يتم استخدامها أثناء بدء تشغيل التطبيق.

ملاحظة: لا يمكن استرداد اسم ملف بيانات تنفيذ التطبيق إلا إذا كان لديك إذن وصول إلى جذر نظام الملفات، مثلاً على محاكي.

لإنشاء نموذج نصي لمعلومات الملف الشخصي، استخدِم الأمر التالي:

adb shell cmd package dump-profiles package

لاسترداد الملف الناتج، استخدِم الأمر التالي:

adb pull /data/misc/profman/package.prof.txt

إعادة ضبط الأجهزة الاختبارية

إذا كنت تختبِر تطبيقك على عدة أجهزة اختبارية، قد يكون من المفيد إعادة ضبط جهازك بين الاختبارات، مثلاً لإزالة بيانات المستخدم وإعادة ضبط بيئة الاختبار. يمكنك إعادة ضبط جهاز اختباري يعمل بالإصدار 10 من نظام التشغيل Android (المستوى 29 من واجهة برمجة التطبيقات) أو إصدار أحدث على الإعدادات الأصلية باستخدام أمر shell testharness adb، كما هو موضّح أدناه:

adb shell cmd testharness enable

عند استعادة الجهاز باستخدام testharness، يتم تلقائيًا الاحتفاظ بنسخة احتياطية من مفتاح RSA الذي يتيح تصحيح الأخطاء من خلال محطة العمل الحالية في موقع جغرافي دائم. أي أنّه بعد إعادة ضبط الجهاز، يمكن أن تواصل محطة العمل تصحيح الأخطاء وإصدار أوامر adb للجهاز بدون تسجيل مفتاح جديد يدويًا.

بالإضافة إلى ذلك، للمساعدة في تسهيل عملية مواصلة اختبار تطبيقك وجعلها أكثر أمانًا، يؤدي استخدام testharness لاستعادة جهاز إلى تغيير إعدادات الجهاز التالية أيضًا:

• يضبط الجهاز بعض إعدادات النظام حتى لا تظهر معالجات الإعداد الأوّلي للجهاز. أي أنّ الجهاز يدخل في حالة يمكنك من خلالها تثبيت تطبيقك وتصحيحه واختباره بسرعة.
• الإعدادات:
  • يؤدي هذا الخيار إلى إيقاف شاشة القفل.
  • يتم إيقاف تنبيهات الطوارئ.
  • توقِف هذه الميزة المزامنة التلقائية للحسابات.
  • يؤدي هذا الخيار إلى إيقاف التحديثات التلقائية للنظام.
• غير ذلك:
  • يؤدي ذلك إلى إيقاف تطبيقات الأمان المثبَّتة مسبقًا.

إذا كان تطبيقك بحاجة إلى رصد الإعدادات التلقائية للأمر testharness والتكيّف معها، استخدِم ActivityManager.isRunningInUserTestHarness().

sqlite

يبدأ sqlite3 برنامج سطر الأوامر sqlite لفحص قواعد بيانات SQLite. ويتضمّن أوامر مثل .dump لطباعة محتويات جدول و.schema لطباعة عبارة SQL CREATE لجدول حالي. يمكنك أيضًا تنفيذ أوامر SQLite من سطر الأوامر، كما هو موضّح:

$ adb -s emulator-5554 shell
$ sqlite3 /data/data/com.example.app/databases/rssitems.db
SQLite version 3.3.12
Enter ".help" for instructions

ملاحظة: لا يمكن الوصول إلى قاعدة بيانات SQLite إلا إذا كان لديك إذن وصول إلى الجذر في نظام الملفات، مثلاً على محاكي.

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات سطر الأوامر الخاصة بـ sqlite3.

برامج الخلفية الخاصة بـ adb عبر USB

يمكن لخادم adb التفاعل مع حزمة بروتوكول USB من خلال نظامَي خلفية. يمكن أن يستخدم إما الخلفية الأصلية لنظام التشغيل (Windows أو Linux أو macOS) أو الخلفية libusb. لا تتوفّر بعض الميزات، مثل attach وdetach ورصد سرعة USB، إلا عند استخدام libusb كخادم خلفي.

يمكنك اختيار واجهة خلفية باستخدام متغيّر البيئة ADB_LIBUSB. إذا لم يتم ضبطها، سيستخدم adb الخلفية التلقائية. يختلف السلوك التلقائي باختلاف نظام التشغيل. اعتبارًا من الإصدار 34 من Android Debug Bridge، يتم استخدام الخلفية liubusb تلقائيًا على جميع أنظمة التشغيل باستثناء Windows، حيث يتم استخدام الخلفية الأصلية تلقائيًا. في حال ضبط ADB_LIBUSB، يحدّد هذا الإعداد ما إذا كان سيتم استخدام الخلفية الأصلية أو libusb. لمزيد من المعلومات حول متغيرات بيئة adb، راجِع صفحة دليل adb.

برامج الخلفية لنظام mDNS في adb

يستخدم ADB بروتوكول mDNS (نظام أسماء النطاقات المتعدد البث) للربط تلقائيًا بين الخادم والأجهزة من أجل تصحيح الأخطاء لاسلكيًا. اعتبارًا من الإصدار 37 من ADB، يتضمّن خادم ADB نظامَي mDNS أساسيَّين، هما libadbmdns وopenscreen.

libadbmdns هو الخادم الخلفي التلقائي والمُقترَح. يمكن تغيير هذا السلوك باستخدام متغيّر البيئة ADB_MDNS_OPENSCREEN (يجب ضبطه على 1 أو 0). يتوفّر الإصدار 35 من "جسر تصحيح أخطاء Android" (ADB) أو الإصدارات الأحدث على أجهزة macOS. يتوافق الإصدار 34 من "جسر تصحيح أخطاء Android" مع نظامَي التشغيل Windows وLinux.

وضع "اللقطات المتتالية" في أداة تصحيح أخطاء Android (بدءًا من الإصدار 36.0.0)

"وضع الالتقاط المتتابع" هو ميزة تجريبية تتيح لأداة ADB مواصلة إرسال حِزم إلى جهاز حتى قبل أن يستجيب الجهاز للحزمة السابقة، ما يؤدي إلى زيادة معدل نقل البيانات في أداة ADB بشكل كبير عند نقل الملفات الكبيرة، كما يقلّل من وقت الاستجابة أثناء تصحيح الأخطاء.

يكون "وضع التصوير المتتابع" غير مفعّل تلقائيًا. لتفعيل الميزة، اتّبِع أحد الإجراءات التالية:

• اضبط متغيّر البيئة ADB_BURST_MODE على 1.
• في "استوديو Android"، انتقِل إلى إعدادات مصحّح الأخطاء من خلال ملف (File) (أو استوديو Android (Android Studio) على نظام التشغيل macOS) > الإعدادات (Settings) > الإنشاء والتنفيذ والنشر (Build, Execution, Deployment) > مصحّح الأخطاء (Debugger)، ثم اضبط وضع التشغيل السريع لخادم ADB (ADB Server Burst Mode) على مفعّل (Enabled).