نظرة عامة على مضيف USB

عندما يكون جهاز Android في وضع مضيف USB، يعمل كمضيف USB، ويشغّل الناقل، ويعدّد أجهزة USB المتصلة. يتوفّر وضع مضيف USB في الإصدار 3.1 من Android والإصدارات الأحدث.

نظرة عامة على واجهة برمجة التطبيقات

قبل البدء، من المهم فهم الفئات التي تحتاج إلى العمل معها. يوضّح الجدول التالي واجهات برمجة تطبيقات مضيف USB في حزمة android.hardware.usb.

الجدول 1: واجهات برمجة تطبيقات مضيف USB

الفئة الوصف
UsbManager يتيح لك هذا الإذن تعداد أجهزة USB المتصلة والتواصل معها.
UsbDevice يمثّل جهاز USB متصلاً ويحتوي على طرق للوصول إلى معلوماته التعريفية وواجهاته ونقاط النهاية.
UsbInterface تمثّل هذه الواجهة واجهة جهاز USB، والتي تحدّد مجموعة من الوظائف للجهاز. يمكن أن يحتوي الجهاز على واجهة واحدة أو أكثر للتواصل.
UsbEndpoint تمثّل نقطة نهاية الواجهة، وهي قناة اتصال لهذه الواجهة. يمكن أن تحتوي الواجهة على نقطة نهاية واحدة أو أكثر، وعادةً ما تحتوي على نقاط نهاية للإدخال والإخراج للتواصل ثنائي الاتجاه مع الجهاز.
UsbDeviceConnection يمثّل هذا الإذن اتصالاً بالجهاز ينقل البيانات على نقاط النهاية. تتيح لك هذه الفئة إرسال البيانات ذهابًا وإيابًا بشكل متزامن أو غير متزامن.
UsbRequest يمثّل هذا طلبًا غير متزامن للتواصل مع جهاز من خلال UsbDeviceConnection.
UsbConstants تحدّد هذه السياسة ثوابت USB التي تتوافق مع التعريفات في linux/usb/ch9.h لنواة Linux.

في معظم الحالات، تحتاج إلى استخدام جميع هذه الفئات (لا يلزم استخدام UsbRequest إلا إذا كنت تجري اتصالاً غير متزامن) عند الاتصال بجهاز USB. بشكل عام، يمكنك الحصول على UsbManager لاسترداد UsbDevice الذي تريده. عندما يكون لديك الجهاز، عليك العثور على UsbInterface المناسب وUsbEndpoint لتلك الواجهة للتواصل من خلالها. بعد الحصول على نقطة النهاية الصحيحة، افتح UsbDeviceConnection للتواصل مع جهاز USB.

متطلبات ملف بيان Android

توضّح القائمة التالية ما تحتاج إلى إضافته إلى ملف بيان تطبيقك قبل العمل مع واجهات برمجة التطبيقات لمضيف USB:

  • بما أنّه لا يمكن ضمان توافق جميع الأجهزة التي تعمل بنظام التشغيل Android مع واجهات برمجة التطبيقات لمضيف USB، يجب تضمين عنصر <uses-feature> يوضّح أنّ تطبيقك يستخدم ميزة android.hardware.usb.host.
  • اضبط الحد الأدنى لحزمة تطوير البرامج (SDK) للتطبيق على المستوى 12 من واجهة برمجة التطبيقات أو مستوًى أعلى. لا تتوفّر واجهات برمجة التطبيقات لمضيف USB في المستويات السابقة من واجهة برمجة التطبيقات.
  • إذا أردت أن يتم إشعار تطبيقك بجهاز USB متصل، حدِّد زوج عناصر <intent-filter> و<meta-data> لغرض android.hardware.usb.action.USB_DEVICE_ATTACHED في نشاطك الرئيسي. يشير العنصر <meta-data> إلى ملف موارد XML خارجي يوضّح معلومات تكشف الهوية عن الجهاز الذي تريد رصده.

    في ملف موارد XML، حدِّد عناصر <usb-device> لأجهزة USB التي تريد فلترتها. توضّح القائمة التالية سمات <usb-device>. بشكل عام، استخدِم معرّف المورّد والمنتج إذا كنت تريد الفلترة لجهاز معيّن، واستخدِم الفئة والفئة الفرعية والبروتوكول إذا كنت تريد الفلترة لمجموعة من أجهزة USB، مثل أجهزة التخزين الكبيرة أو الكاميرات الرقمية. يمكنك تحديد أيّ من هذه السمات أو جميعها. يؤدي عدم تحديد أي سمات إلى مطابقة كل أجهزة USB، لذا لا تفعل ذلك إلا إذا كان تطبيقك يتطلب ذلك:

    • vendor-id
    • product-id
    • class
    • subclass
    • ‫protocol (جهاز أو واجهة)

    احفظ ملف الموارد في دليل res/xml/. يجب أن يكون اسم ملف المورد (بدون الامتداد ‎ .xml) مطابقًا للاسم الذي حدّدته في العنصر <meta-data>. يظهر تنسيق ملف موارد XML في المثال التالي.

أمثلة على ملفات البيان والموارد

يوضّح المثال التالي نموذج بيان وملف الموارد المقابل له:

<manifest ...>
    <uses-feature android:name="android.hardware.usb.host" />
    <uses-sdk android:minSdkVersion="12" />
    ...
    <application>
        <activity ...>
            ...
            <intent-filter>
                <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
            </intent-filter>

            <meta-data android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
                android:resource="@xml/device_filter" />
        </activity>
    </application>
</manifest>

في هذه الحالة، يجب حفظ ملف الموارد التالي في res/xml/device_filter.xml، ويحدّد هذا الملف أنّه يجب فلترة أي جهاز USB يتضمّن السمات المحدّدة:

<?xml version="1.0" encoding="utf-8"?>

<resources>
    <usb-device vendor-id="1234" product-id="5678" class="255" subclass="66" protocol="1" />
</resources>

العمل مع الأجهزة

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

  1. يمكنك اكتشاف أجهزة USB المتصلة باستخدام intent filter ليتم إعلامك عندما يوصّل المستخدم جهاز USB أو من خلال تعداد أجهزة USB المتصلة حاليًا.
  2. اطلب من المستخدم الإذن بالاتصال بجهاز USB، إذا لم تكن قد حصلت عليه من قبل.
  3. التواصل مع جهاز USB من خلال قراءة البيانات وكتابتها على نقاط نهاية الواجهة المناسبة

العثور على جهاز

يمكن لتطبيقك اكتشاف أجهزة USB إما باستخدام فلتر الأهداف ليتم إعلامك عندما يقوم المستخدم بتوصيل جهاز أو عن طريق تعداد أجهزة USB المتصلة بالفعل. يُعد استخدام intent filter مفيدًا إذا كنت تريد أن يتمكن تطبيقك من اكتشاف الجهاز الذي تريده تلقائيًا. يُعدّ تعداد أجهزة USB المتصلة مفيدًا إذا كنت تريد الحصول على قائمة بجميع الأجهزة المتصلة أو إذا لم يفلتر تطبيقك هدفًا معيّنًا.

استخدام intent filter

لتمكين تطبيقك من اكتشاف جهاز USB معيّن، يمكنك تحديد فلتر intent للفلترة حسب intent android.hardware.usb.action.USB_DEVICE_ATTACHED. بالإضافة إلى فلتر الأغراض هذا، عليك تحديد ملف موارد يحدّد خصائص جهاز USB، مثل معرّف المنتج ومعرّف المورّد. عندما يربط المستخدمون جهازًا يتطابق مع فلتر جهازك، يعرض لهم النظام مربّع حوار يسألهم عمّا إذا كانوا يريدون بدء تطبيقك. إذا وافق المستخدمون، سيحصل تطبيقك تلقائيًا على إذن بالوصول إلى الجهاز إلى أن يتم فصله.

يوضّح المثال التالي كيفية الإعلان عن intent filter:

<activity ...>
...
    <intent-filter>
        <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
    </intent-filter>

    <meta-data android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
        android:resource="@xml/device_filter" />
</activity>

يوضّح المثال التالي كيفية الإعلان عن ملف الموارد المقابل الذي يحدّد أجهزة USB التي تهمّك:

<?xml version="1.0" encoding="utf-8"?>

<resources>
    <usb-device vendor-id="1234" product-id="5678" />
</resources>

In your activity, you can obtain the UsbDevice that represents the attached device from the intent like this:

Kotlin

val device: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)

Java

UsbDevice device = (UsbDevice) intent.getParcelableExtra(UsbManager.EXTRA_DEVICE);

تعداد الأجهزة

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

Kotlin

val manager = getSystemService(Context.USB_SERVICE) as UsbManager
...
val deviceList = manager.getDeviceList()
val device = deviceList.get("deviceName")

Java

UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
...
HashMap<String, UsbDevice> deviceList = manager.getDeviceList();
UsbDevice device = deviceList.get("deviceName");

إذا أردت، يمكنك أيضًا الحصول على مكرّر من خريطة التجزئة ومعالجة كل جهاز واحدًا تلو الآخر:

Kotlin

val manager = getSystemService(Context.USB_SERVICE) as UsbManager
..
val deviceList: HashMap<String, UsbDevice> = manager.deviceList
deviceList.values.forEach { device ->
    // your code
}

Java

UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
...
HashMap<String, UsbDevice> deviceList = manager.getDeviceList();
Iterator<UsbDevice> deviceIterator = deviceList.values().iterator();
while(deviceIterator.hasNext()){
    UsbDevice device = deviceIterator.next();
    // your code
}

الحصول على إذن للاتصال بجهاز

قبل الاتصال بجهاز USB، يجب أن يحصل تطبيقك على إذن من المستخدمين.

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

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

للحصول على الإذن صراحةً، عليك أولاً إنشاء مستقبل بث. يستمع هذا المُستقبِل إلى الغرض الذي يتم بثه عند استدعاء requestPermission(). يؤدي استدعاء requestPermission() إلى عرض مربّع حوار للمستخدم يطلب منه الإذن بالاتصال بالجهاز. يوضّح الرمز النموذجي التالي كيفية إنشاء جهاز استقبال البث:

Kotlin

private const val ACTION_USB_PERMISSION = "com.android.example.USB_PERMISSION"

private val usbReceiver = object : BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (ACTION_USB_PERMISSION == intent.action) {
            synchronized(this) {
                val device: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)

                if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) {
                    device?.apply {
                        // call method to set up device communication
                    }
                } else {
                    Log.d(TAG, "permission denied for device $device")
                }
            }
        }
    }
}

Java

private static final String ACTION_USB_PERMISSION =
    "com.android.example.USB_PERMISSION";
private final BroadcastReceiver usbReceiver = new BroadcastReceiver() {

    public void onReceive(Context context, Intent intent) {
        String action = intent.getAction();
        if (ACTION_USB_PERMISSION.equals(action)) {
            synchronized (this) {
                UsbDevice device = (UsbDevice)intent.getParcelableExtra(UsbManager.EXTRA_DEVICE);

                if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) {
                    if(device != null){
                      // call method to set up device communication
                   }
                }
                else {
                    Log.d(TAG, "permission denied for device " + device);
                }
            }
        }
    }
};

لتسجيل جهاز استقبال البث، أضِف ما يلي في إجراء onCreate() في نشاطك:

Kotlin

private const val ACTION_USB_PERMISSION = "com.android.example.USB_PERMISSION"
...
val manager = getSystemService(Context.USB_SERVICE) as UsbManager
...
permissionIntent = PendingIntent.getBroadcast(this, 0,
                  Intent(ACTION_USB_PERMISSION), PendingIntent.FLAG_IMMUTABLE)
val filter = IntentFilter(ACTION_USB_PERMISSION)
registerReceiver(usbReceiver, filter)

Java

UsbManager usbManager = (UsbManager) getSystemService(Context.USB_SERVICE);
private static final String ACTION_USB_PERMISSION =
    "com.android.example.USB_PERMISSION";
...
permissionIntent = PendingIntent.getBroadcast(this, 0,
              new Intent(ACTION_USB_PERMISSION), PendingIntent.FLAG_IMMUTABLE);
IntentFilter filter = new IntentFilter(ACTION_USB_PERMISSION);
registerReceiver(usbReceiver, filter);

لعرض مربّع الحوار الذي يطلب من المستخدمين الإذن بالاتصال بالجهاز، يمكنك استدعاء طريقة requestPermission():

Kotlin

lateinit var device: UsbDevice
...
usbManager.requestPermission(device, permissionIntent)

Java

UsbDevice device;
...
usbManager.requestPermission(device, permissionIntent);

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

التواصل مع جهاز

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

  • تحقَّق من سمات عنصر UsbDevice، مثل معرّف المنتج أو معرّف المورّد أو فئة الجهاز لمعرفة ما إذا كنت تريد الاتصال بالجهاز أم لا.
  • عند التأكّد من رغبتك في التواصل مع الجهاز، ابحث عن UsbInterface المناسب الذي تريد استخدامه للتواصل مع UsbEndpoint المناسب لتلك الواجهة. يمكن أن تحتوي الواجهات على نقطة نهاية واحدة أو أكثر، وعادةً ما تحتوي على نقطة نهاية للإدخال والإخراج للاتصال ثنائي الاتجاه.
  • عند العثور على نقطة النهاية الصحيحة، افتح UsbDeviceConnection على نقطة النهاية هذه.
  • قدِّم البيانات التي تريد نقلها على نقطة النهاية باستخدام طريقة bulkTransfer() أو controlTransfer(). يجب تنفيذ هذه الخطوة في سلسلة تعليمات أخرى لمنع حظر سلسلة واجهة المستخدم الرئيسية. لمزيد من المعلومات حول استخدام سلاسل المحادثات في Android، يُرجى الاطّلاع على العمليات وسلاسل المحادثات.

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

Kotlin

private lateinit var bytes: ByteArray
private val TIMEOUT = 0
private val forceClaim = true

...

device?.getInterface(0)?.also { intf ->
    intf.getEndpoint(0)?.also { endpoint ->
        usbManager.openDevice(device)?.apply {
            claimInterface(intf, forceClaim)
            bulkTransfer(endpoint, bytes, bytes.size, TIMEOUT) //do in another thread
        }
    }
}

Java

private Byte[] bytes;
private static int TIMEOUT = 0;
private boolean forceClaim = true;

...

UsbInterface intf = device.getInterface(0);
UsbEndpoint endpoint = intf.getEndpoint(0);
UsbDeviceConnection connection = usbManager.openDevice(device);
connection.claimInterface(intf, forceClaim);
connection.bulkTransfer(endpoint, bytes, bytes.length, TIMEOUT); //do in another thread

لإرسال البيانات بشكل غير متزامن، استخدِم فئة UsbRequest من أجل initialize وqueue طلب غير متزامن، ثم انتظِر النتيجة باستخدام requestWait().

إنهاء الاتصال بجهاز

عند الانتهاء من الاتصال بجهاز أو إذا تم فصل الجهاز، أغلِق UsbInterface وUsbDeviceConnection من خلال استدعاء releaseInterface() و close(). للاستماع إلى أحداث الفصل، أنشِئ جهاز استقبال بث مثل ما يلي:

Kotlin

var usbReceiver: BroadcastReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {

        if (UsbManager.ACTION_USB_DEVICE_DETACHED == intent.action) {
            val device: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)
            device?.apply {
                // call your method that cleans up and closes communication with the device
            }
        }
    }
}

Java

BroadcastReceiver usbReceiver = new BroadcastReceiver() {
    public void onReceive(Context context, Intent intent) {
        String action = intent.getAction();

      if (UsbManager.ACTION_USB_DEVICE_DETACHED.equals(action)) {
            UsbDevice device = (UsbDevice)intent.getParcelableExtra(UsbManager.EXTRA_DEVICE);
            if (device != null) {
                // call your method that cleans up and closes communication with the device
            }
        }
    }
};

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