Android USB Host

目錄
 [隱藏]
1USB主機
1.1文檔內容
1.2相關例子
1.3API概述
1.4Android中manifest檔案的需求
1.4.1Manifest檔案和資源檔的例子
1.5用配件工作
1.5.1發現裝置
1.5.1.1使用一個意圖過濾器
1.5.1.2枚舉所有配件
1.5.2獲得使用一個配件的許可權
1.5.3和裝置之間的“交流”
1.5.4中止和裝置的“交流”
USB主機
文檔內容
API概述
Android中manifest檔案需求
工作的裝置
發現裝置
獲得和裝置進行“交流”的許可權
和裝置進行“交流”
中止和裝置的“交流”
相關例子
Adb測試案例
相關連結
當您搭載Android系統的裝置處於USB主機模式時，它就像一個USB主機，為匯流排提供能源，並且列舉出所有已經串連上的裝置。在Android 3.1或者更高的版本中支援USB主機模式。
API概述
在您開始之前，有個很重要的一點就是您必須對將要用到的類有個瞭解。下面的表格就向您描述了在android.hardware.usb這個包下USB主機APIs的一些特點。
表1.USB主機APIs
Class/Interface  Description
UsbManager
允許您枚舉已串連的USB裝置並且與其進行“交流”。
UsbDevice
代表了一個已串連的USB的裝置並且包含具有該裝置驗證資訊，介面和存取點的方法。
UsbInterface
代表了一個USB裝置的一個介面，該介面定義了一系列關於裝置的函數。一個裝置在進行“交流”的時候可以有一個或者多個介面。
UsbEndpoint
代表一個介面的存取點，該存取點就是這個介面的通訊通道。一個介面可以有一個或者多個這樣的存取點，而且一般都是有輸入和輸出雙向通訊的存取點。
UsbDeviceConnection
代表該裝置的一個串連，用來在存取點上傳輸資料。這個類允許您能用同步或者非同步方式發送和返回資料。
UsbRequest
在通過UsbDeviceConnection和裝置進行“交流”的一個非同步請求。
UsbConstants
關於在linux核心中linux/usb/ch9.h的相關定義的USB常量。
在大多數的情況之下，在和一個USB裝置進行“交流”時，上面這些類都需要用到（UsbRequest這個類只有在您做非同步通訊的時候才會用到）。一般來說，您可以通過查詢要操作的UsbDevice來獲得一個UsbManager。當您有這個裝置時，您需要找到正確的UsbInterface以及和這個介面所對應的UsbEndpoint來進行和裝置的“交流”。一旦您獲得了正確的存取點，開啟UsbDeviceConnection來和該USB裝置進行“交流”。
Android中manifest檔案的需求
下面的列表就是描述您應該在用USB主機APIs之前應該在您的應用中的manifest檔案中添加些什麼：
因為不是所有的搭載Android系統的裝置都能保證支援USB主機的APIs，不能包含那個聲明您的應用使用android.hardware.usb.host這一特點的android.hardware.usb.host的這一元素。
設定您的應用的最低的SDK版本在12級或者更高。這個USB主機APIs不在更前面的版本之中。
如果您希望您的應用能夠被串連的USB裝置所提示，只要在您的主activity中在<intent-filter>和<meta-data>元素對中添加一個android.hardware.usb.action.USB_DEVICE_ATTACHED意圖。<meta-data>元素指向一個額外的XML資源檔，該檔案是用來聲明驗證您希望探測到的裝置的驗證資訊。
   在這個XML資源檔中，為您希望過濾的USB裝置宣告<usb-device>元素。下面的列表描述<usb-device>的屬性。一般來說，如果您想為一個特定的裝置過濾就使用該產品的供應商和產品ID，如果您希望為一組USB裝置，例如大量存放裝置或者是數位相機來進行過濾那麼就應該用類，子類和協議。您可以不指定這些屬性，也可以指定所有的屬性。不為每個裝置指定屬性，只有在您的應用需要它時才這麼做（這句話翻譯的一點問題^_^）：
供應商ID
產品ID
類
子類
協議（裝置或者借口）
   將您的資源檔儲存到res/xml/目錄下。資源檔名（不包含.xml的副檔名）必須和您在<meta-data>元素中指明的那個名字。在下面的例子中是這個XML資源檔的格式。
Manifest檔案和資源檔的例子
下面的例子告訴您一個manifest檔案以及與它相關資源檔的例子：
<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裝置，您可以為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>
 

 
<?xml version="1.0" encoding="utf-8"?>
 
<resources>
    <usb-device vendor-id="1234" product-id="5678" />
</resources>

 
 在您的activity檔案中，您可以從像這樣的意圖（有附加類的）中擷取UsbDevice來代表這個相關的配件：
 
UsbDevice device = (UsbDevice) intent.getParcelableExtra(UsbManager.EXTRA_DEVICE);

枚舉所有配件
您可以使您的應用在運行時列舉出所有能夠被識別的USB裝置。通過getDeviceList()方法來獲得一個包含所有已串連USB配件的數組：
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
... 
HashMap<String, UsbDevice> deviceList = manager.getDeviceList();
UsbDevice device = deviceList.get("deviceName");
 
如果您喜歡，您也可以一個接一個的從每一個裝置的雜湊圖和過程中擷取一個迭代器：
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()這個方法為使用者跳出一個是否串連該裝置的對話方塊。下面的例子告訴您如何建立一個廣播接收器：
private static final String ACTION_USB_PERMISSION =
    "com.android.example.USB_PERMISSION";
private final BroadcastReceiver mUsbReceiver = 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);
                }
            }
        }
    }
};

 
為了註冊您的廣播接收器，將其放在您activity中的onCreate()方法中去:
UsbManager mUsbManager = (UsbManager) getSystemService(Context.USB_SERVICE);
private static final String ACTION_USB_PERMISSION =
    "com.android.example.USB_PERMISSION";
...
mPermissionIntent = PendingIntent.getBroadcast(this, 0, new Intent(ACTION_USB_PERMISSION), 0);
IntentFilter filter = new IntentFilter(ACTION_USB_PERMISSION);
registerReceiver(mUsbReceiver, filter);

 
當您需要展示徵求使用者同意串連這個裝置的許可權的對話方塊時，調用requestPermission()這個方法：
UsbDevice device;
...
mUsbManager.requestPermission(device, mPermissionIntent);

 
當使用者回應這個對話方塊時，你的廣播接收器就會收到一個包含用一個boolean值來表示結果的EXTRA_PERMISSION_GRANTED欄位的意圖。在您串連裝置之前檢查這個欄位的值是否為true。
和裝置之間的“交流”
我們可以同步或者非同步和USB裝置進行“交流”。在任意一種情況之下，您都應該建立一個新的線程來進行資料轉送，這樣就不會阻塞您的主線程了。要想正確的設定好和一個裝置之間的串連，您需要獲得該裝置正確的UsbInterface和UsbEndpoint來和您進行“交流”以及通過UsbDeviceConnection在這個存取點上發送請求。一般來說，您的代碼應該這樣：
檢查一個UsbDevice對象的屬性，例如產品ID，供應商ID，或者是關於裝置的類，以此來確認您是否希望和該裝置進行“交流”。
當您確信您希望和該裝置進行“交流”時，找到關於該裝置正確的UsbInterface以及和該介面所對應的UsbEndpoint。介面可以有一個或者多個存取點，而且一般都會有一個雙向通訊的輸入和輸出存取點。
當您找到正確的存取點時，在該存取點時開啟一個UsbDeviceConnection。
您可以通過bulkTransfer()和controlTransfer()這兩個方法在存取點上傳輸您所需要傳遞的資料。您最好在另起一個新的線程來進行這個步驟以避免阻塞主線程。想要詳細地瞭解關於Android中使用線程的資訊，詳見線程和進程。
下面的程式碼片段是做同步資料轉送的一個簡單方式。您的代碼應該有更多的邏輯來準確地找到和裝置“交流”的介面和存取點，而且應該能夠在不同於主線程的線程中能夠傳輸任何的資料轉送。
private Byte[] bytes
private static int TIMEOUT = 0;
private boolean forceClaim = true;
 
...
 
UsbInterface intf = device.getInterface(0);
UsbEndpoint endpoint = intf.getEndpoint(0);
UsbDeviceConnection connection = mUsbManager.openDevice(device);
connection.claimInterface(intf, forceClaim);
connection.bulkTransfer(endpoint, bytes, bytes.length, TIMEOUT); //do in another thread

 
為了能夠非同步傳輸資料，使用UsbRequest類來初始和隊列化一個非同步請求，然後等待requestWait()方法的結果。
想要瞭解更多地資訊，請您參考Adb Test sample，這個參考將會告訴您如何進行非同步批量傳輸，還有MissleLauncher sample將會告訴您如何非同步監聽一個中斷端點。
中止和裝置的“交流”
 
當您在完成和裝置的“交流”之後，又或者該裝置被移除了，通過調用releaseInterface()和close()的方法來關閉UseInterface和UsbDeviceConnection。為了監聽分離這樣的事件，您需要建立一個如下的廣播接收器：
 
BroadcastReceiver mUsbReceiver = 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
            }
        }
    }
};
 

 
在您的應用中建立這個廣播接收器，不是在manifest檔案中，允許您的應用只能在它啟動並執行時候處理這樣的裝置分離事件。這樣的話，裝置分離這個事件就只向正在啟動並執行應用廣播，而不是向所有的應用進行廣播。