סקירה כללית על מארח ה-USB

כשהמכשיר מבוסס-Android נמצא במצב מארח USB, הוא פועל כמארח USB, מפעיל את האפיק ומספור התקני USB מחוברים. מצב מארח USB נתמך ב-Android מגרסה 3.1 ואילך.

סקירה כללית על ממשקי API

לפני שמתחילים, חשוב להבין עם אילו מחלקות צריך לעבוד. בטבלה הבאה מתוארים ממשקי ה-API של מארח ה-USB בחבילה android.hardware.usb.

טבלה 1. ממשקי API של מארח 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

ברשימה הבאה מתואר מה צריך להוסיף לקובץ המניפסט של האפליקציה לפני שמתחילים לעבוד עם ממשקי ה-API של מארח ה-USB:

  • לא כל המכשירים עם Android תומכים בממשקי ה-API של מארח ה-USB, לכן צריך לכלול רכיב <uses-feature> שמצהיר שהאפליקציה משתמשת בתכונה android.hardware.usb.host.
  • מגדירים את ערכת ה-SDK המינימלית של האפליקציה לרמת API ‏12 ומעלה. ממשקי ה-API של מארח ה-USB לא קיימים ברמות API קודמות.
  • אם אתם רוצים שהאפליקציה תקבל התראה על התקן USB מחובר, ציינו צמד רכיבים של <intent-filter> ו-<meta-data> ל-Intent של 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 כדי לקבל התראה כשהמשתמש מחבר התקן USB, או למנות את התקני ה-USB שכבר מחוברים.
  2. אם עדיין לא קיבלתם הרשאה מהמשתמש להתחבר להתקן ה-USB, בקשו ממנו הרשאה.
  3. מתקשרים עם התקן ה-USB על ידי קריאה וכתיבה של נתונים בנקודות הקצה המתאימות של הממשק.

איך מוצאים מכשיר

האפליקציה יכולה לגלות התקני USB באמצעות מסנן Intent כדי לקבל התראה כשהמשתמש מחבר התקן, או על ידי ספירת התקני USB שכבר מחוברים. שימוש במסנן Intent שימושי אם רוצים שהאפליקציה תזהה באופן אוטומטי את המכשיר הרצוי. ספירת התקני USB מחוברים שימושית אם רוצים לקבל רשימה של כל המכשירים המחוברים או אם האפליקציה לא סיננה לפי Intent.

שימוש במסנן Intent

כדי שהאפליקציה תזהה התקן USB מסוים, אפשר לציין מסנן Intent שיסנן את ה-Intent מסוג android.hardware.usb.action.USB_DEVICE_ATTACHED. בנוסף למסנן ה-Intent הזה, צריך לציין קובץ משאבים שמפרט את המאפיינים של התקן ה-USB, כמו מזהה המוצר ומזהה הספק. כשמשתמשים מחברים מכשיר שתואם למסנן המכשירים, המערכת מציגה להם תיבת דו-שיח שבה הם נשאלים אם הם רוצים להפעיל את האפליקציה. אם המשתמשים מאשרים, לאפליקציה יש הרשאה אוטומטית לגשת למכשיר עד שהוא מתנתק.

בדוגמה הבאה אפשר לראות איך להצהיר על מסנן ה-Intent:

<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>

בפעילות, אתם יכולים לקבל את ה-UsbDevice שמייצג את המכשיר המחובר מה-Intent, באופן הבא:

Kotlin

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

Java

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

ספירת מכשירים

אם אתם רוצים שהאפליקציה תבדוק את כל התקני ה-USB שמחוברים כרגע בזמן שהיא פועלת, אתם יכולים למנות את המכשירים באפיק. משתמשים ב-method‏ getDeviceList() כדי לקבל מפת גיבוב (hash map) של כל התקני ה-USB שמחוברים. מפת הגיבוב (hash map) ממופתחת לפי שם התקן ה-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");

אם רוצים, אפשר גם פשוט לקבל איטרטור ממפת הגיבוב (hash map) ולעבד כל מכשיר בנפרד:

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 כדי לגלות התקני USB כשהם מחוברים, היא מקבלת הרשאה באופן אוטומטי אם המשתמש מאפשר לאפליקציה לטפל ב-Intent. אם לא, צריך לבקש הרשאה באופן מפורש באפליקציה לפני החיבור למכשיר.

יכול להיות שתצטרכו לבקש הרשאה באופן מפורש במצבים מסוימים, למשל כשהאפליקציה שלכם סופרת את התקני ה-USB שכבר מחוברים ואז רוצה לתקשר עם אחד מהם. לפני שמנסים לתקשר עם מכשיר, צריך לבדוק אם יש הרשאה לגשת אליו. אם לא, תופיע שגיאת זמן ריצה אם המשתמש דחה את הרשאת הגישה למכשיר.

כדי לקבל הרשאה באופן מפורש, קודם צריך ליצור מקלט שידור. המקלט הזה מאזין ל-intent שמשודר כשקוראים ל-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);
                }
            }
        }
    }
};

כדי לרשום את מקלט השידור, מוסיפים את הקוד הבא ל-method‏ 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);

כדי להציג את תיבת הדו-שיח שבה המשתמשים מתבקשים לתת הרשאה להתחבר למכשיר, צריך להפעיל את ה-method‏ requestPermission():

Kotlin

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

Java

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

כשהמשתמשים משיבים לתיבת הדו-שיח, מקלט השידור מקבל את ה-intent שמכיל את ה-extra‏ EXTRA_PERMISSION_GRANTED, שהוא ערך בוליאני שמייצג את התשובה. לפני שמתחברים למכשיר, צריך לבדוק אם הערך של ה-extra הזה הוא true.

תקשורת עם מכשיר

התקשורת עם התקן USB יכולה להיות סינכרונית או אסינכרונית. בכל מקרה, כדאי ליצור שרשור חדש שבו יתבצעו כל העברות הנתונים, כדי לא לחסום את שרשור ה-UI. כדי להגדיר בצורה נכונה את התקשורת עם מכשיר, צריך לקבל את ה-UsbInterface וה-UsbEndpoint המתאימים של המכשיר שאיתו רוצים לתקשר, ולשלוח בקשות בנקודת הקצה הזו באמצעות UsbDeviceConnection. באופן כללי, הקוד צריך:

  • בודקים את המאפיינים של אובייקט UsbDevice, כמו מזהה המוצר, מזהה הספק או סוג המכשיר, כדי להחליט אם רוצים לתקשר עם המכשיר.
  • כשאתם בטוחים שאתם רוצים לתקשר עם המכשיר, אתרו את ה-UsbInterface המתאים שבו אתם רוצים להשתמש כדי לתקשר, יחד עם ה-UsbEndpoint המתאים של הממשק הזה. לממשקים יכולה להיות נקודת קצה אחת או יותר, ובדרך כלל תהיה להם נקודת קצה של קלט ופלט לתקשורת דו-כיוונית.
  • כשמוצאים את נקודת הקצה הנכונה, פותחים UsbDeviceConnection בנקודת הקצה הזו.
  • מספקים את הנתונים שרוצים להעביר בנקודת הקצה באמצעות השיטה bulkTransfer() או controlTransfer(). כדאי לבצע את השלב הזה בשרשור אחר כדי למנוע חסימה של שרשור UI הראשי. מידע נוסף על שימוש בשרשורים ב-Android זמין במאמר תהליכים ושרשורים.

קטע הקוד הבא הוא דרך פשוטה לבצע העברת נתונים סינכרונית. הקוד צריך לכלול יותר לוגיקה כדי למצוא את הממשק ונקודות הקצה הנכונים לתקשורת, וגם להעביר נתונים בשרשור שונה משרשור ה-UI הראשי:

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
            }
        }
    }
};

אם יוצרים את מקלט השידורים בתוך האפליקציה ולא במניפסט, האפליקציה יכולה לטפל באירועים מנותקים רק כשהיא פועלת. כך, אירועים מנותקים נשלחים רק לאפליקציה שפועלת כרגע ולא משודרים לכל האפליקציות.