מצב אביזר USB מאפשר למשתמשים לחבר חומרת מארח USB שתוכננה במיוחד למכשירים עם Android. האביזרים חייבים לעמוד בדרישות של פרוטוקול האביזרים של Android, שמפורטות במסמכי התיעוד של ערכת הפיתוח לאביזרים של Android. כך מכשירים עם Android שלא יכולים לפעול כמארח USB עדיין יכולים לתקשר עם חומרת USB. כשמכשיר Android נמצא במצב אביזר USB, אביזר ה-USB של Android שמחובר אליו פועל כמארח, מספק חשמל לאפיק ה-USB וממיין את המכשירים המחוברים. ב-Android 3.1 (רמת API 12) יש תמיכה במצב אביזר USB, והתכונה הזו הוסבה גם לגרסאות מוקדמות יותר, כמו Android 2.3.4 (רמת API 10), כדי לאפשר תמיכה במגוון רחב יותר של מכשירים.
בחירת ממשקי ה-API המתאימים לאביזרי USB
למרות שממשקי ה-API של אביזרי USB נוספו לפלטפורמה ב-Android 3.1, הם זמינים גם ב-Android 2.3.4 באמצעות ספריית התוספים של Google APIs. מכיוון שממשקי ה-API האלה הוסבו בגרסאות מוקדמות יותר באמצעות ספרייה חיצונית, יש שתי חבילות שאפשר לייבא כדי לתמוך במצב אביזר USB. בהתאם למכשירי Android שבהם רוצים לתמוך, יכול להיות שתצטרכו להשתמש באחת מהאפשרויות הבאות:
com.android.future.usb: כדי לתמוך במצב אביזר USB ב-Android 2.3.4, ספריית התוספים של Google APIs כוללת את ממשקי ה-API של אביזרי USB שהוסבו לגרסאות מוקדמות יותר, והם כלולים במרחב השמות הזה. ב-Android 3.1 אפשר גם לייבא את המחלקות במרחב השמות הזה ולקרוא להן כדי לתמוך באפליקציות שנכתבו באמצעות ספריית התוספים. ספריית התוספים הזו היא מעטפת דקה מסביב לממשקי ה-API של האביזרים שלandroid.hardware.usbוהיא לא תומכת במצב מארח USB.אם אתם רוצים לתמוך במגוון הרחב ביותר של מכשירים שתומכים במצב אביזר USB, השתמשו בספריית התוספים וייבאו את החבילה הזו. חשוב לציין שלא כל מכשירי Android 2.3.4 נדרשים לתמוך בתכונה של אביזר ה-USB. כל יצרן מכשירים מחליט אם לתמוך ביכולת הזו או לא, ולכן צריך להצהיר על כך בקובץ המניפסט.
-
android.hardware.usb: מרחב השמות הזה מכיל את המחלקות שתומכות במצב אביזר USB ב-Android 3.1. החבילה הזו כלולה כחלק מממשקי ה-API של המסגרת, כך ש-Android 3.1 תומכת במצב אביזר USB בלי להשתמש בספריית תוספים. השתמשו בחבילה הזו אם אתם מתעניינים רק במכשירים עם Android 3.1 ואילך שיש להם תמיכה בחומרה למצב אביזר USB, שאותו אתם יכולים להצהיר בקובץ המניפסט.
התקנה של ספריית התוספים של Google APIs
אם רוצים להתקין את התוסף, אפשר לעשות את זה על ידי התקנת החבילה Google APIs Android API 10 באמצעות SDK Manager. במאמר התקנת התוסף של Google APIs מוסבר איך להתקין את ספריית התוספים.
סקירה כללית על ממשקי API
מכיוון שספריית התוספים היא wrapper לממשקי ה-API של ה-framework, המחלקות שתומכות בתכונה של אביזר ה-USB דומות. אתם יכולים להשתמש במאמרי העזרה של android.hardware.usb גם אם אתם משתמשים בספריית התוספים.
הערה: עם זאת, יש הבדל קל בשימוש בין ספריית התוספים לבין ממשקי ה-API של ה-framework שחשוב לשים לב אליו.
בטבלה הבאה מתוארות המחלקות שתומכות בממשקי ה-API של אביזרי USB:
| דרגה | תיאור |
|---|---|
UsbManager |
מאפשרת לכם למנות אביזרי USB מחוברים ולתקשר איתם. |
UsbAccessory |
מייצג אביזר USB ומכיל שיטות לגישה לפרטים המזהים שלו. |
הבדלים בשימוש בין ספריית התוספים לבין ממשקי ה-API של הפלטפורמה
יש שני הבדלים בין השימוש בספריית התוספים של Google APIs לבין השימוש בממשקי ה-API של הפלטפורמה.
אם אתם משתמשים בספריית התוספים, אתם צריכים לקבל את האובייקט UsbManager באופן הבא:
Kotlin
val manager = UsbManager.getInstance(this)
Java
UsbManager manager = UsbManager.getInstance(this);
אם אתם לא משתמשים בספריית התוספים, אתם צריכים לקבל את האובייקט UsbManager באופן הבא:
Kotlin
val manager = getSystemService(Context.USB_SERVICE) as UsbManager
Java
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
כשמסננים אביזר מחובר באמצעות מסנן Intent, האובייקט UsbAccessory נכלל ב-Intent שמועבר לאפליקציה. אם אתם משתמשים בספריית התוספים, אתם צריכים לקבל את האובייקט UsbAccessory באופן הבא:
Kotlin
val accessory = UsbManager.getAccessory(intent)
Java
UsbAccessory accessory = UsbManager.getAccessory(intent);
אם אתם לא משתמשים בספריית התוספים, אתם צריכים לקבל את האובייקט UsbAccessory באופן הבא:
Kotlin
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
Java
UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
דרישות למניפסט של Android
ברשימה הבאה מתואר מה צריך להוסיף לקובץ המניפסט של האפליקציה לפני שמתחילים לעבוד עם ממשקי ה-API של אביזרי USB. הדוגמאות לקובץ המניפסט ולקובץ המשאבים מראות איך להצהיר על הפריטים האלה:
- לא כל המכשירים עם Android תומכים בממשקי ה-API של אביזרי USB, לכן צריך לכלול רכיב
<uses-feature>שמצהיר שהאפליקציה משתמשת בתכונהandroid.hardware.usb.accessory. - אם אתם משתמשים בספריית התוספים, הוסיפו את הרכיב
<uses-library>וציינו אתcom.android.future.usb.accessoryלספרייה. - מגדירים את גרסת ה-SDK המינימלית של האפליקציה לרמת API 10 אם משתמשים בספריית התוספים,
או לרמה 12 אם משתמשים בחבילת
android.hardware.usb. -
אם אתם רוצים שהאפליקציה תקבל התראה על אביזר USB מחובר, ציינו צמד רכיבים של
<intent-filter>ו-<meta-data>ל-Intent שלandroid.hardware.usb.action.USB_ACCESSORY_ATTACHEDבפעילות הראשית. הרכיב<meta-data>מפנה לקובץ משאב XML חיצוני שמצהיר על פרטים אישיים מזהים לגבי האביזר שרוצים לזהות.בקובץ המשאבים בפורמט XML, מגדירים רכיבי
<usb-accessory>לאביזרים שרוצים לסנן. לכל<usb-accessory>יכולים להיות המאפיינים הבאים:manufacturermodelversion
לא מומלץ לסנן לפי
version. יכול להיות שאביזר או מכשיר לא תמיד יציינו מחרוזת גרסה (בכוונה או שלא בכוונה). אם האפליקציה מצהירה על מאפיין גרסה לסינון, והאביזר או המכשיר לא מציינים מחרוזת גרסה, זה גורם ל-NullPointerExceptionבגרסאות קודמות של Android. הבעיה הזו תוקנה ב-Android 12.שומרים את קובץ המשאבים בספרייה
res/xml/. שם הקובץ של המשאב (בלי הסיומת .xml) חייב להיות זהה לשם שציינתם ברכיב<meta-data>. הפורמט של קובץ המשאבים ב-XML מוצג גם בדוגמה הבאה.
דוגמאות לקובצי מניפסט ומשאבים
בדוגמה הבאה מוצג מניפסט לדוגמה וקובץ המשאבים התואם שלו:
<manifest ...> <uses-feature android:name="android.hardware.usb.accessory" /> <uses-sdk android:minSdkVersion="<version>" /> ... <application> <uses-library android:name="com.android.future.usb.accessory" /> <activity ...> ... <intent-filter> <action android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" /> </intent-filter> <meta-data android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" android:resource="@xml/accessory_filter" /> </activity> </application> </manifest>
במקרה כזה, צריך לשמור את קובץ המשאבים הבא ב-res/xml/accessory_filter.xml. הקובץ מציין שצריך לסנן כל אביזר עם הדגם, היצרן והגרסה התואמים. האביזר שולח את המאפיינים הבאים למכשיר Android:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-accessory model="DemoKit" manufacturer="Google" version="1.0"/> </resources>
עבודה עם אביזרים
כשמשתמשים מחברים אביזרי USB למכשיר Android, מערכת Android יכולה לקבוע אם האפליקציה שלכם מעוניינת באביזר המחובר. אם כן, אפשר להגדיר תקשורת עם האביזר. כדי לעשות את זה, האפליקציה צריכה:
- כדי לגלות אביזרים מחוברים, משתמשים במסנן Intent שמסנן אירועים של חיבור אביזרים, או סופרים את האביזרים המחוברים ומוצאים את האביזר המתאים.
- אם עדיין לא קיבלתם הרשאה מהמשתמש לתקשר עם האביזר, בקשו אותה.
- מתקשרים עם האביזר על ידי קריאה וכתיבה של נתונים בנקודות הקצה המתאימות של הממשק.
חיפוש אביזר
האפליקציה יכולה לגלות אביזרים באמצעות מסנן Intent כדי לקבל התראה כשהמשתמש מחבר אביזר, או על ידי ספירת אביזרים שכבר מחוברים. שימוש במסנן Intent שימושי אם רוצים שהאפליקציה תזהה באופן אוטומטי אביזר רצוי. ספירת האביזרים המחוברים שימושית אם רוצים לקבל רשימה של כל האביזרים המחוברים או אם האפליקציה לא סיננה Intent.
שימוש במסנן Intent
כדי שהאפליקציה תגלה אביזר USB מסוים, אפשר לציין מסנן Intent
כדי לסנן את ה-Intent android.hardware.usb.action.USB_ACCESSORY_ATTACHED. בנוסף למסנן ה-Intent הזה, צריך לציין קובץ משאבים שמציין את המאפיינים של אביזר ה-USB, כמו יצרן, דגם וגרסה.
בדוגמה הבאה אפשר לראות איך להצהיר על מסנן ה-Intent:
<activity ...> ... <intent-filter> <action android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" /> </intent-filter> <meta-data android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" android:resource="@xml/accessory_filter" /> </activity>
בדוגמה הבאה אפשר לראות איך להצהיר על קובץ המשאבים התואם שמציין את אביזרי ה-USB שאתם רוצים:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-accessory manufacturer="Google, Inc." model="DemoKit" version="1.0" /> </resources>
בפעילות, אפשר לקבל את ה-UsbAccessory שמייצג את האביזר המחובר מה-Intent באופן הבא (עם ספריית התוספים):
Kotlin
val accessory = UsbManager.getAccessory(intent)
Java
UsbAccessory accessory = UsbManager.getAccessory(intent);
או כך (באמצעות ממשקי ה-API של הפלטפורמה):
Kotlin
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
Java
UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
ספירת אביזרים
אתם יכולים להגדיר שהאפליקציה תמנה אביזרים שזיהו את עצמם בזמן שהאפליקציה פועלת.
משתמשים ב-method getAccessoryList() כדי לקבל מערך של כל אביזרי ה-USB שמחוברים:
Kotlin
val manager = getSystemService(Context.USB_SERVICE) as UsbManager val accessoryList: Array<out UsbAccessory> = manager.accessoryList
Java
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE); UsbAccessory[] accessoryList = manager.getAccessoryList();
הערה: אפשר לחבר רק אביזר אחד בכל פעם.
קבלת הרשאה לתקשר עם אביזר
כדי לתקשר עם אביזר ה-USB, האפליקציה צריכה לקבל הרשאה מהמשתמשים.
הערה: אם האפליקציה משתמשת במסנן Intent כדי לגלות אביזרים כשהם מחוברים, היא מקבלת הרשאה באופן אוטומטי אם המשתמש מאפשר לאפליקציה לטפל ב-Intent. אם לא, צריך לבקש הרשאה באופן מפורש באפליקציה לפני החיבור לאביזר.
יכול להיות שיהיה צורך לבקש הרשאה באופן מפורש במצבים מסוימים, למשל כשהאפליקציה מונה אביזרים שכבר מחוברים ואז רוצה לתקשר עם אחד מהם. לפני שמנסים לתקשר עם אביזר, צריך לבדוק אם יש הרשאה לגשת אליו. אם לא, תופיע שגיאת זמן ריצה אם המשתמש דחה את ההרשאה לגשת לאביזר.
כדי לקבל הרשאה באופן מפורש, קודם צריך ליצור מקלט שידור. המקלט הזה מאזין ל-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 accessory: UsbAccessory? = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) { accessory?.apply { // call method to set up accessory communication } } else { Log.d(TAG, "permission denied for accessory $accessory") } } } } }
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) { UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) { if(accessory != null){ // call method to set up accessory communication } } else { Log.d(TAG, "permission denied for accessory " + accessory); } } } } };
כדי לרשום את מקלט השידור, צריך להוסיף את הקוד הבא ל-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), 0) 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), 0); IntentFilter filter = new IntentFilter(ACTION_USB_PERMISSION); registerReceiver(usbReceiver, filter);
כדי להציג את תיבת הדו-שיח שבה המשתמשים מתבקשים לתת הרשאה להתחבר לאביזר, מפעילים את ה-method requestPermission():
Kotlin
lateinit var accessory: UsbAccessory ... usbManager.requestPermission(accessory, permissionIntent)
Java
UsbAccessory accessory; ... usbManager.requestPermission(accessory, permissionIntent);
כשהמשתמשים משיבים לתיבת הדו-שיח, מקלט השידור מקבל את ה-intent שמכיל את ה-extra של EXTRA_PERMISSION_GRANTED, שהוא ערך בוליאני שמייצג את התשובה. לפני שמתחברים לאביזר, צריך לבדוק אם הערך של ה-extra הזה הוא true.
תקשורת עם אביזר
כדי לתקשר עם האביזר, אפשר להשתמש ב-UsbManager כדי לקבל תיאור קובץ שאפשר להגדיר בו זרמי קלט ופלט לקריאת נתונים וכתיבת נתונים בתיאור. הזרמים מייצגים את נקודות הקצה (endpoint) של הקלט והפלט של האביזר. כדאי להגדיר את התקשורת בין המכשיר לאביזר בשרשור אחר, כדי לא לנעול את שרשור ה-UI הראשי. בדוגמה הבאה אפשר לראות איך פותחים אביזר כדי לתקשר איתו:
Kotlin
private lateinit var accessory: UsbAccessory private var fileDescriptor: ParcelFileDescriptor? = null private var inputStream: FileInputStream? = null private var outputStream: FileOutputStream? = null ... private fun openAccessory() { Log.d(TAG, "openAccessory: $mAccessory") fileDescriptor = usbManager.openAccessory(accessory) fileDescriptor?.fileDescriptor?.also { fd -> inputStream = FileInputStream(fd) outputStream = FileOutputStream(fd) val thread = Thread(null, this, "AccessoryThread") thread.start() } }
Java
UsbAccessory accessory; ParcelFileDescriptor fileDescriptor; FileInputStream inputStream; FileOutputStream outputStream; ... private void openAccessory() { Log.d(TAG, "openAccessory: " + accessory); fileDescriptor = usbManager.openAccessory(accessory); if (fileDescriptor != null) { FileDescriptor fd = fileDescriptor.getFileDescriptor(); inputStream = new FileInputStream(fd); outputStream = new FileOutputStream(fd); Thread thread = new Thread(null, this, "AccessoryThread"); thread.start(); } }
ב-method run() של ה-thread, אפשר לקרוא מהאביזר ולכתוב אליו באמצעות האובייקטים FileInputStream או FileOutputStream. כשקוראים נתונים מאביזר עם אובייקט FileInputStream, צריך לוודא שהמאגר שבו משתמשים גדול מספיק כדי לאחסן את נתוני חבילת ה-USB. פרוטוקול האביזרים של Android תומך במאגרי מנות בגודל של עד 16,384 בייטים, כך שאפשר לבחור להצהיר תמיד שהמאגר הוא בגודל הזה כדי לפשט את התהליך.
הערה: ברמה נמוכה יותר, החבילות הן בגודל 64 בייטים לאביזרי USB במהירות מלאה ו-512 בייטים לאביזרי USB במהירות גבוהה. כדי לפשט את התהליך, פרוטוקול האביזרים של Android מקבץ את החבילות של שתי המהירויות לחבילה לוגית אחת.
למידע נוסף על השימוש בשרשורים ב-Android, ראו תהליכים ושרשורים.
סיום התקשורת עם אביזר
כשמסיימים את התקשורת עם אביזר או אם האביזר נותק, סוגרים את תיאור הקובץ שנפתח באמצעות קריאה ל-close().
כדי להאזין לאירועים מנותקים, צריך ליצור מקלט שידור כמו בדוגמה הבאה:
Kotlin
var usbReceiver: BroadcastReceiver = object : BroadcastReceiver() { override fun onReceive(context: Context, intent: Intent) { if (UsbManager.ACTION_USB_ACCESSORY_DETACHED == intent.action) { val accessory: UsbAccessory? = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) accessory?.apply { // call your method that cleans up and closes communication with the accessory } } } }
Java
BroadcastReceiver usbReceiver = new BroadcastReceiver() { public void onReceive(Context context, Intent intent) { String action = intent.getAction(); if (UsbManager.ACTION_USB_ACCESSORY_DETACHED.equals(action)) { UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); if (accessory != null) { // call your method that cleans up and closes communication with the accessory } } } };
אם יוצרים את מקלט השידורים בתוך האפליקציה ולא במניפסט, האפליקציה יכולה לטפל באירועים מנותקים רק כשהיא פועלת. כך, אירועים מנותקים נשלחים רק לאפליקציה שפועלת כרגע ולא משודרים לכל האפליקציות.