翻译Android USB HOST API

源码地址：http://developer.android.com/guide/topics/connectivity/usb/host.html

译者注：翻译的好不好不是太重要，重点是在翻译的过程中会把每句话都看认真看一遍，或者说是抱着翻译的思想来完成一个读懂的目的。

USB Host通信

当你的可供电Android设备处理USB host模式时，它担任着为USB总线供电，枚举连接的USB从设备等等一个主设备应用的工作。Android 3.1及以后版本开始支持USB host模式。

API概述

开始之前，有必要弄明白以后要用到的类。下表中描述了包含在android.hardware.usb包中的USB host APIs。

表1. USB host APIs.

多数情况下，在和USB设备进行通信的时候，你需要使用这里所有的类（UsbRequest只用在异步通信一个请求）。一般是这样的，使用UsbManager来获取UsbDevice。确定了设备，需要查找用于通信接口的UsbInterface和UsbEndpoint。一旦获取了恰当的端点，打开UsbDeviceConnection与USB设备进行通信。

下列表中描述了使用USB host APIs之前需要添加到应用程序的manifest文件中的内容：

由于并不是所有的Android带供电设备确保支持USB host APIs，添加 <uses-feature>对象来表明你的应用使用了android.hardware.usb.host特性。

SDK最低版本设置为12或者更高。USB host APIs不支持更老版本的API。

如果你想让你的应用检测一个USB设备的话，在主Activity指定 <intent-filter> 和<meta-data> 对象去匹配android.hardware.usb.action.USB_DEVICE_ATTACHED。<meta-data>对象指向一个外部的XML资源文件，文件中描述你想要探测的USB设备的过滤信息。

在这个XML资源文件中，为你想要过滤的USB设备声明<usb-device>对象。下列表中描述了<usb-device>的属性。通常，使用vendor 和 product ID过滤特殊设备，使用类，子类和协议来过滤一组设备，比如大容量存储设备(优盘)或者数码相机。你可以完全指定这个属性值，也可以一个也不指定。没有属性值说明会过滤每个一个USB设备。所以说，你的应用程序有这个需求的情况下可以指定。

• vendor-id
• product-id
• class
• subclass
• protocol (device or interface)

保存资源文件到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上时，无论你的应用程序是否对此USB设备感兴趣Android系统都会检测到。你可以和设备建立通信。你的应用程序需要做如下事情：

1.探测USB设备通过意图过滤器检测用户连接的设备，或者枚举已经连接的USB设备。

2.如果之前没有请求过，向用户请求权限以连接USB设备。

3.和USB设备进行通信，通过接口端点读写数据。

探测设备

应用程序可以通过两种方式进行USB设备的探测，使用意图过滤器监听用户连接设备或者枚举已经连接的USB设备。前者可以方便的实现自动检测设备。如果想列出所有的已连接设备或者没有使用意图过滤器过滤的设备，可以使用枚举设备来完成。

使用意图过滤器

探测设备可以指定意图过滤器来过滤android.hardware.usb.action.USB_DEVICE_ATTACHED意图。此外需要指定一个资源文件描述USB设备，比如product and vendor 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>

在你的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设备以及与设备通信。通信之前你需要检查权限，否则如果用户权限拒绝你将会收到一个运行错误。

申请权限，首先创建创建一个广播接收器。调用requestPermission()时，接收器监听广播意图。调用requestRermission()向给用户显示一个对话框请求连接该设备的权限。

下列代码显示如何创建这样一个广播接收器：

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

当用户回复对话框，你的广播接收器会收到的内容为EXTRA_PERMISSION_GRANTED意图，它是一个布尔代表答案。通信之前检查这个额外值是否为真。

与设备通信

通信方式可以是同步或者异步。在这两种情况下，你应该创建一个线程执行所有数据的传输，不要阻塞界面线程。建立一个通信，你需要获取需要通信设备的UsbInterface和UsbEndpoint,以及使用UsbDeviceConnection申请端点。一般地，你的代码应该是：

• 检查UsbDevice对象的属性,比如 product ID, vendor ID或者设备类别。以识别是不是需要通信的设备。
• 如果确定了是要通信的设备，检索出你需要通信设备的接口，以及该接口的端点。接口可以有一个或者多个端点，一般会有输入输出各一的双向通信的端点。
• 如果确定了端点，在该端点上打开 UsbDeviceConnection。 
• 使用bulkTransfer()或者controlTransfer()方法将需要传输的数据提供到端点上。你需要将上述操作实现在其它线程以免阻塞当前主界面线程。更多关于Android中线程的使用，见Processes and Threads.

下面的代码片段简单的实现了同步数据传输。你的代码应该使用更多逻辑上的来查找出正确的通信接口和端点，同样需要在主界面以外的线程中进行数据的传输：

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类初始化(initialize)和排队(queue)等候异步请求，然后使用requestWait()等待结果。

更多信息见AdbTest例子，它显示了如何进行块传输的方法异步通信，以及MissleLauncher sample它显示了如何监听中断端点异步。

终止通信

当完成了通信或者设备被移除了，调用releaseInterface()和close()来关闭UsbInterface和UsbDeviceConection。监听设备移除事件，创建一个广播接收器如下：

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中。仅在应用程序程序运行时处理设备移除事件。如此，移除事件只会发送给正在运行的应用而不是所有的应用。

感悟：

• 与原文无关纯属个人感想，USB通信越向下越复杂。Android封装好一些，其次是libusb，再然后就是Linux内核中进行的USB通信。依次需要了解的知识多少都不一样，比如这个完整的通信过程中并没有用到urb等等。
• 目前测试的Android4.2.2上通信的最大块为：16KiB。所以数据要分割为16KiB大小进行传输。
• 文件中提到的那个例子AdbTest和MissleLauncher的源码位于：development/samples/USB/中。前者功能是读取usb设备(同样也是Android系统)的LOG，后者功能是控制一个火箭发射器玩具。
• Android这套API并不能检测所有的USB设备，有些设备检测不到。比如无线数据的适配器。目前测试成功的有打印机。
• 关于对其了解的程度，我一直有个毛病就是了解一个东西没有上限。类似写文章没有主线，想到哪里就深入到哪里。我要逐渐改点这个习惯。我对这个的练习是将数据发送打印机，完成打印。当我刚刚实现的时候，我就又开始幻想我是不是可以做一个很牛叉的USB打印APP了。这个是可以实现的，但并不是目前的主要任务，如果我坚持做，很多东西都需要去实现，这也违背了我当前仅仅是了解Android USB host API的初衷。还好，这次我刹住了闸，毕竟我这次是真实的了解了，之前只知道在Linux内核中的通信以及基于Libusb通信，直接使用java通信的好处是解析xml等等在C语言中相对复杂的东西到java中都不显示复杂了。
• l 测试APK和上文提到的那两个例子打包上传到Here，方便那些没有Android系统源码的同志。