USB 配件模式可讓使用者連接專為 Android 裝置設計的 USB 主機硬體。配件必須遵循 Android 配件開發套件說明文件中所述的 Android 配件通訊協定。這樣一來,無法做為 USB 主機的 Android 裝置仍可與 USB 硬體互動。當 Android 裝置處於 USB 配件模式時,連接的 Android USB 配件會做為主機,為 USB 匯流排供電,並列舉連結裝置。Android 3.1 (API 級別 12) 支援 USB 配件模式,這項功能也已向後移植到 Android 2.3.4 (API 級別 10),以便支援更多裝置。
選擇合適的 USB 配件 API
雖然 USB 配件 API 是在 Android 3.1 中導入平台,但也可以透過 Google API 外掛程式程式庫在 Android 2.3.4 中使用。由於這些 API 是使用外部程式庫向後移植,因此您可以匯入兩個套件來支援 USB 配件模式。視您要支援的 Android 裝置而定,您可能需要使用其中一種:
com.android.future.usb:為了在 Android 2.3.4 中支援 USB 配件模式,Google API 外掛程式庫包含向後移植的 USB 配件 API,且這些 API 包含在這個命名空間中。Android 3.1 也支援匯入及呼叫這個命名空間中的類別,以支援使用外掛程式庫編寫的應用程式。這個外掛程式庫是android.hardware.usb配件 API 的精簡包裝函式,不支援 USB 主機模式。如要支援最廣泛的 USB 配件模式裝置,請使用外掛程式庫並匯入這個套件。請注意,並非所有 Android 2.3.4 裝置都必須支援 USB 配件功能。各家裝置製造商會自行決定是否支援這項功能,因此您必須在資訊清單檔案中宣告這項功能。
android.hardware.usb:這個命名空間包含支援 Android 3.1 USB 配件模式的類別。這個套件包含在架構 API 中,因此 Android 3.1 支援 USB 配件模式,不需使用外掛程式程式庫。如果您只關心 Android 3.1 或更新版本裝置,且這些裝置具備 USB 配件模式的硬體支援,請使用此套件,您可以在資訊清單檔案中宣告。
安裝 Google API 外掛程式庫
如要安裝外掛程式,請使用 SDK Manager 安裝 Google API Android API 10 套件。如要進一步瞭解如何安裝外掛程式庫,請參閱「安裝 Google API 外掛程式」。
API 總覽
由於外掛程式庫是架構 API 的包裝函式,因此支援 USB 配件功能的類別也類似。即使您使用的是外掛程式庫,也可以使用 android.hardware.usb 的參考文件。
注意:不過,外掛程式庫和架構 API 之間有細微的使用差異,請務必留意。
下表說明支援 USB 配件 API 的類別:
| 類別 | 說明 |
|---|---|
UsbManager |
可讓您列舉連接的 USB 配件並與其通訊。 |
UsbAccessory |
代表 USB 配件,並包含存取其識別資訊的方法。 |
外掛程式程式庫和平台 API 的使用差異
使用 Google API 外掛程式庫和平台 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);
使用意圖篩選器篩選已連結的配件時,UsbAccessory 物件會包含在傳遞至應用程式的意圖中。如果您使用外掛程式庫,則必須以下列方式取得 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 資訊清單規定
下列清單說明在使用 USB 配件 API 之前,您需要在應用程式資訊清單檔案中新增的內容。資訊清單和資源檔案範例說明如何宣告這些項目:
- 並非所有搭載 Android 的裝置都保證支援 USB 配件 API,因此請加入
<uses-feature>元素,宣告應用程式會使用android.hardware.usb.accessory功能。 - 如果您使用的是外掛程式庫,請新增
<uses-library>元素,並為程式庫指定com.android.future.usb.accessory。 - 如果您使用的是外掛程式庫,請將應用程式的 SDK 下限設為 API 級別 10;如果您使用的是
android.hardware.usb套件,則設為 12。 -
如要讓應用程式在連接 USB 配件時收到通知,請在主要活動中為
android.hardware.usb.action.USB_ACCESSORY_ATTACHED意圖指定<intent-filter>和<meta-data>元素組合。<meta-data>元素指向外部 XML 資源檔案,該檔案會宣告要偵測的配件識別資訊。在 XML 資源檔案中,為要篩選的配件宣告
<usb-accessory>元素。每個<usb-accessory>都可以有下列屬性:manufacturermodelversion
不建議依
version篩選。配件或裝置不一定會指定版本字串 (無論有意或無意)。如果應用程式宣告版本屬性來篩選,而配件或裝置未指定版本字串,則在舊版 Android 上會導致NullPointerException。這個問題已在 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 系統可以判斷應用程式是否對連接的配件感興趣。如果是,您可以視需要設定與配件的通訊。為此,應用程式必須:
- 如要尋找已連結的配件,請使用意圖篩選器篩選配件附加事件,或列舉已連結的配件並找出合適的配件。
- 如果尚未取得權限,請向使用者要求與配件通訊的權限。
- 在適當的介面端點上讀取及寫入資料,與配件通訊。
探索配件
應用程式可以透過意圖篩選器,在使用者連接配件時收到通知,或列舉已連接的配件,藉此探索配件。如果您希望應用程式能自動偵測所需配件,可以使用意圖篩選器。如要取得所有已連結配件的清單,或應用程式未篩選意圖,則可列舉已連結的配件。
使用意圖篩選器
如要讓應用程式探索特定 USB 配件,您可以指定意圖篩選器,篩選 android.hardware.usb.action.USB_ACCESSORY_ATTACHED 意圖。除了這個意圖篩選器,您還需要指定資源檔案,用於指定 USB 配件的屬性,例如製造商、型號和版本。
以下範例說明如何宣告意圖篩選器:
<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,如下所示 (使用外掛程式庫):
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);
列舉配件
您可以讓應用程式在執行時,列舉已識別自身的配件。
使用 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 配件通訊。
注意:如果應用程式使用意圖篩選器,在配件連線時偵測配件,則只要使用者允許應用程式處理意圖,應用程式就會自動取得權限。如果沒有,您必須先在應用程式中明確要求權限,才能連線至配件。
在某些情況下,可能需要明確要求權限,例如應用程式列舉已連線的配件,然後想與其中一個配件通訊。您必須先檢查是否有權存取配件,才能嘗試與配件通訊。否則,如果使用者拒絕授予存取配件的權限,您會收到執行階段錯誤。
如要明確取得權限,請先建立廣播接收器。這個接收器會監聽呼叫 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); } } } } };
如要註冊廣播接收器,請將以下程式碼加入活動的 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);
如要顯示對話方塊,要求使用者授予連線至配件的權限,請呼叫 requestPermission() 方法:
Kotlin
lateinit var accessory: UsbAccessory ... usbManager.requestPermission(accessory, permissionIntent)
Java
UsbAccessory accessory; ... usbManager.requestPermission(accessory, permissionIntent);
使用者回覆對話方塊時,廣播接收器會收到包含 EXTRA_PERMISSION_GRANTED 額外項目的意圖,這是一個代表答案的布林值。在連線至配件前,請檢查這個額外項目的值是否為 true。
與配件通訊
您可以使用 UsbManager 與配件通訊,取得檔案描述元,以便設定輸入和輸出串流,對描述元讀取及寫入資料。串流代表配件的輸入和輸出大量端點。您應在其他執行緒中設定裝置與配件之間的通訊,以免鎖定主要 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(); } }
在執行緒的 run() 方法中,您可以使用 FileInputStream 或 FileOutputStream 物件讀取及寫入配件。使用 FileInputStream 物件從配件讀取資料時,請確保使用的緩衝區夠大,足以儲存 USB 封包資料。Android 配件通訊協定支援最多 16384 個位元組的封包緩衝區,因此您可以選擇一律將緩衝區宣告為這個大小,以求簡化。
注意:在較低層級,USB 全速配件的封包為 64 位元組,USB 高速配件的封包為 512 位元組。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 } } } };
在應用程式 (而非資訊清單) 中建立廣播接收器,可讓應用程式只在執行時處理中斷連線事件。這樣一來,分離事件只會傳送至目前執行的應用程式,而不會廣播至所有應用程式。