USB HOST-Android 6.0开发者文档

以下内容翻译自USB Host

一、usb host

当你的Android设备处于usb host模式时，它作为usb host，驱动总线，可以枚举已连接的usb设备。usb host模式从Android 3.1开始支持。

二、API简介

下表描述了android.hardware.usb包中的usb host相关API：

类	描述
UsbManager	包含枚举、通信接口
UsbDevice	表示一个已连接设备，包含访问已注册信息、接口、endpoint的方法
UsbInterface	表示usb设备的接口，定义了此设备支持的功能集合。一个设备可以有多个接口
UsbEndpoint	表示接口endpoint，即接口的通信通道。一个接口可以有多个endpoint，通常有输入、输出两个endpoint以支持双向通信
UsbDeviceConnection	表示一个连接，可以在endpoint上面传输数据。这个类中包含同步/异步读写数据的方法
UsbRequest	表示通过UsbDeviceConnection进行的异步请求
UsbConstants	一些usb相关常量

大多数情况下，当你与usb设备通信时，以上的类都会被用到（UsbRequest只在进行异步通信时需要）。通常情况下，建立连接的顺序为：通过UsbManager搜索目标UsbDevice，然后寻找适当的UsbInterface和对应的UsbEndpoint，找到endpoint以后，就可以打开一个UsbDeviceConnection进行通信了。

三、Android manifest设置

以下为在使用usb host相关API前需要在manifest文件中添加的内容：

• 由于不是所有的Android设备都支持usb host API，所以需要用<uses-feature>指定需要android.hardware.usb.host
• 设置最小SDK为API 12。usb host API不支持更早的系统版本

• 如果你希望你的应用可以在usb设备接入时收到通知，可以为activity指定<intent-filter>和<meta-data>。其中filter的action为android.hardware.usb.action.USB_DEVICE_ATTACHED，<meta-data>指定一个外部XML文件，此文件指定你关注的设备信息。
  在这个XML文件中，需要添加<usb-device>标签。下面描述的是<usb-device>支持的属性。通常情况下，你可以使用vendor-id和product-id指定你想要的某个设备，使用class、subclass、protocol指定你想要的一组设备（如存储设备或数码相机）。你可以指定下列属性中的一个或多个。不指定任何属性将会匹配到所有usb设备。

  • vendor-id
  • product-id
  • class
  • subclass
  • protocol

  将此XML文件保存在res/xml路径。XML文件的名称必须与<meta-data>中指定的（没有.xml后缀）一致

3.1 示例

下面是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>

在这个例子中，下面的xml文件将保存为res/xml/device_filter.xml：

<?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设备通信。要实现此功能，你需要：

1. 当usb设备接入时通过intent filter发现它，或者直接枚举已连接的usb设备
2. 向用户申请权限
3. 使用适当的endpoint接口与usb设备通信

4.1 发现设备

你可以通过两种方式发现usb设备，一是用intent filter在usb接入时由系统通知，一是用枚举接口直接获取已连接设备。如果你希望应用可以自动获取目标设备，可以使用intent filter的方式。如果你希望获取所有已连接设备列表，可以使用枚举接口。

4.1.1 使用intent filter

你可以在intent filter中指定action为android.hardware.usb.action.USB_DEVICE_ATTACHED来发现某个USB设备。在这个intent filter中，你还需要指定一个resource文件，此文件可以说明你要的usb设备的属性，如product id和vendor id。当用户将一个符合你要求的设备连接到Android设备时，系统会显示一个对话框，由用户决定是否启动你的应用处理此连接。如果用户选择了是，那么你的应用会自动获取访问设备的权限，直到设备连接断开。

下面是intent filter的示例：

<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设备的resource文件的示例：

<?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);

4.1.2 枚举设备

如果你的应用是对当前连接的所有usb设备感兴趣，你可以使用枚举接口。使用getDeviceList()方法可以获取当前连接的usb设备的哈希表。这个哈希表的键值是usb设备的名称。

UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
...  
HashMap<String, UsbDevice> deviceList = manager.getDeviceList();
UsbDevice device = deviceList.get("deviceName");

你也可以用iterator的方式访问设备：

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
}

4.2 获取访问设备的权限

在与usb设备通信前，你的应用需要获取相关权限。

注意：如果你的应用使用intent filter方式发现usb设备，那么在用户允许你的应用处理该intent时你的应用会自动获取相关权限。如果用户不允许，那么你在与usb设备建立连接前必须显式的申请权限

在某些情况下显式的申请权限是必要的，比如你的应用在枚举所有已连接设备时。你必须在与usb设备通信前检查是否有访问该设备的权限。如果不检查的话，可能会抛出运行时异常。

要显式的申请权限，你首先需要创建一个broadcast receiver，这个receiver会监听调用requestPermission()方法时由系统发出的广播。调用requestPermission()方法会弹出一个对话框要求用户授权。下面的代码为broadcast receiver示例：

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()方法中注册broadcast receiver：

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);

当用户完成操作后，你的broadcast receiver会收到包含EXTRA_PERMISSION_GRANTED的intent，这个extra为一个boolean，表示权限获取结果。

4.3 与设备通信

与usb设备的通信有两种方式，同步或异步。不论你用哪个方式，你都应该新开一个线程进行通信操作，以防阻塞UI线程。要与设备通信，你需要获取适当的UsbInterface和UsbEndpoint，然后用UsbDeviceConnection向endpoint发送请求。通常，你的代码应该：

• 检查UsbDevice的属性，如product ID，vendor ID，设备class
• 当你确定设备是你想要的后，需要找到你要对此UsbEndpoint通信的UsbInterface。每个interface可以对应多个endpoint，通常情况下需要输入输出两个endpoint以支持双向通信
• 当你找到正确的endpoint后，在此endpoint上打开UsbDeviceConnection
• 用bulkTransfer()或controlTransfer()方法提交你想要传输的数据。这些操作应该另起线程去做，不要阻塞UI线程

下面的代码简单介绍了同步数据传输的方法。你的代码应该更复杂，应该添加寻找interface和endpoint的逻辑：

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()方法等待结果。

更多的信息请看AdbTest sample（此为异步通信例子），或MissileLauncher sample（此为异步监听endpoint中断的例子）。

4.4 终止通信

当你与设备通信结束后，可以使用releaseInterface()或close()方法关闭UsbInterface或UsbDeviceConnection。你可以用以下的broadcast receiver监听设备分离事件：

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
            }
        }
    }
};