當 Android 裝置處於 USB 主機模式時,會做為 USB 主機、為匯流排供電,並列舉已連接的 USB 裝置。Android 3.1 以上版本支援 USB 主機模式。
API 總覽
開始之前,請務必瞭解您需要使用的類別。下表說明 android.hardware.usb 套件中的 USB 主機 API。
表 1. USB 主機 API
| 類別 | 說明 |
|---|---|
UsbManager |
可讓您列舉已連結的 USB 裝置並與其通訊。 |
UsbDevice |
代表已連結的 USB 裝置,並包含存取其識別資訊、介面和端點的方法。 |
UsbInterface |
代表 USB 裝置的介面,可定義裝置的一組功能。一部裝置可以有一或多個通訊介面。 |
UsbEndpoint |
代表介面端點,也就是這個介面的通訊管道。介面可以有一或多個端點,通常具有輸入和輸出端點,可與裝置進行雙向通訊。 |
UsbDeviceConnection |
代表與裝置的連線,可在端點上傳輸資料。這個類別可讓您以同步或非同步方式來回傳送資料。 |
UsbRequest |
代表透過 UsbDeviceConnection 與裝置通訊的非同步要求。 |
UsbConstants |
定義 USB 常數,對應 Linux 核心 linux/usb/ch9.h 中的定義。 |
在大多數情況下,與 USB 裝置通訊時,您需要使用所有這些類別 (只有在執行非同步通訊時,才需要 UsbRequest)。一般來說,您會取得 UsbManager 來擷取所需的 UsbDevice。取得裝置後,您必須找出適當的 UsbInterface 和該介面的 UsbEndpoint,才能進行通訊。取得正確的端點後,請開啟 UsbDeviceConnection 與 USB 裝置通訊。
Android 資訊清單規定
下列清單說明在使用 USB 主機 API 之前,您需要在應用程式資訊清單檔案中新增的內容:
- 並非所有搭載 Android 的裝置都保證支援 USB 主機 API,因此請加入
<uses-feature>元素,宣告應用程式會使用android.hardware.usb.host功能。 - 將應用程式的 SDK 最低版本設為 API 級別 12 以上。USB 主機 API 不存在於較早的 API 級別。
- 如要讓應用程式在 USB 裝置連接時收到通知,請在主要活動中為
android.hardware.usb.action.USB_DEVICE_ATTACHED意圖指定<intent-filter>和<meta-data>元素組合。<meta-data>元素指向外部 XML 資源檔案,該檔案會宣告要偵測的裝置識別資訊。在 XML 資源檔案中,為要篩選的 USB 裝置宣告
<usb-device>元素。以下清單說明<usb-device>的屬性。一般來說,如要篩選特定裝置,請使用供應商和產品 ID;如要篩選一組 USB 裝置 (例如高容量儲存裝置或數位相機),請使用類別、子類別和通訊協定。您可以指定部分或全部屬性。不指定任何屬性會比對所有 USB 裝置,因此請僅在應用程式需要時才這樣做:vendor-idproduct-idclasssubclassprotocol(裝置或介面)
將資源檔案儲存在
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 裝置,請使用意圖篩選器,在使用者連接 USB 裝置時接收通知,或列舉已連接的 USB 裝置。
- 如果尚未取得使用者同意,請徵求使用者同意連線至 USB 裝置。
- 在適當的介面端點上讀取及寫入資料,與 USB 裝置通訊。
探索裝置
應用程式可以透過意圖篩選器,在使用者連接裝置時接收通知,或列舉已連接的 USB 裝置,藉此偵測 USB 裝置。如果您希望應用程式能自動偵測所需裝置,可以使用意圖篩選器。如果您想取得所有已連結裝置的清單,或應用程式未篩選意圖,則列舉已連結的 USB 裝置會很有幫助。
使用意圖篩選器
如要讓應用程式探索特定 USB 裝置,您可以指定意圖篩選器,篩選 android.hardware.usb.action.USB_DEVICE_ATTACHED 意圖。除了這個意圖篩選器,您還需要指定資源檔案,用於指定 USB 裝置的屬性,例如產品和供應商 ID。當使用者連結符合裝置篩選條件的裝置時,系統會顯示對話方塊,詢問是否要啟動應用程式。如果使用者接受,應用程式就會自動取得裝置存取權限,直到裝置中斷連線為止。
以下範例說明如何宣告意圖篩選器:
<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,如下所示:
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 裝置通訊。
注意:如果應用程式使用意圖篩選器偵測已連接的 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 額外項目的意圖,這是一個代表答案的布林值。請先檢查這個額外項目的值是否為 true,再連線至裝置。
與裝置通訊
與 USB 裝置的通訊可以同步或非同步進行。無論是哪種情況,都應建立新的執行緒來執行所有資料傳輸,以免封鎖 UI 執行緒。如要正確設定與裝置的通訊,您必須取得要通訊的裝置的適當 UsbInterface 和 UsbEndpoint,並使用 UsbDeviceConnection 在這個端點上傳送要求。一般來說,程式碼應:
- 檢查
UsbDevice物件的屬性 (例如產品 ID、供應商 ID 或裝置類別),判斷是否要與裝置通訊。 - 確定要與裝置通訊後,請找出要用於通訊的適當
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() 等待結果。
終止與裝置的通訊
與裝置通訊完畢或裝置已卸除時,請呼叫 releaseInterface() 和 close(),關閉 UsbInterface 和 UsbDeviceConnection。如要監聽中斷連線事件,請建立廣播接收器,如下所示:
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 } } } };
在應用程式 (而非資訊清單) 中建立廣播接收器,可讓應用程式只在執行時處理中斷連線事件。這樣一來,分離事件只會傳送至目前執行的應用程式,而不會廣播至所有應用程式。