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