USB Accessory-Android 6.0开发者文档

以下内容翻译自USB Accessory

一、USB accessory和USB host

Android系统对各种USB设备和Android USB配件（这些配件遵守Android accessory protocol）的支持基于两种模式：USB accessory和USB host。在USB accessory模式下，外部USB设备作为usb host，这些外部设备有：机器人控制器、扩展坞、音频设备、读卡器等。这个模式允许没有host能力的Android设备跟USB设备（此设备必须支持Android accessory communication protocol）交互。在USB host模式下，Android设备作为host。支持的外部设备有数码相机、键盘、鼠标、游戏主机等。

图1显示了两种模式的不同。Android设备在host模式时，作为USB host，并驱动通信总线。Android设备在accessory模式时，外部USB设备作为host并驱动数据总线。

Android从Android 3.1（API 12）开始支持这两种模式。USB accessory模式可以通过附加的library兼容到Android 2.3.4（API 10），以支持更多的设备。设备厂商可以自主选择是否将此library添加到系统中。

注意：对两种模式的支持，最终取决于设备硬件，而不是平台level。你可以用<uses-feature>标签过滤掉不支持这两种模式的设备

二、USB accessory

USB accessory模式允许用户连接到针对Android特别设计过的USB host设备。这些设备必须支持Android accessory development kit文档中描述的Android accessory protocol协议。这个协议使不能作为USB host的Android设备可以和USB设备通信。当Android设备处于USB accessory模式时，连接的USB设备作为host，为usb总线提供能量，并且可以枚举已连接设备。Android从Android 3.1（API 12）开始支持usb accessory模式，USB accessory模式可以通过附加的library兼容到Android 2.3.4（API 10），以支持更多的设备。

三、选择正确的usb accessory API

虽然USB accessory API从Android 3.1开始支持，但是你也可以通过Google API附加的library将它兼容到Android 2.3.4。由于这些API是通过外部library加入的，所以需要导入两个包。根据你想要支持的Android设备，你可以选择下面两个包中的一个：

• com.android.future.usb：这个包中的内容是为了将USB accessory兼容到Android 2.3.4在Google API附加的library。Android 3.1也可以导入这个包并调用其中的类。这个library是对android.hardware.usb中的accessory API的轻量包装，且不支持USB host模式。如果你想要兼容更多的设备，你可以将这个library导入到项目中。需要注意的是，不是所有的Android 2.3.4设备都支持USB accessory特性。设备厂商可以自主选择是否支持此特性，所以你最好在manifest文件中声明你需要此特性。

• android.hardware.usb：这个包中的内容是Android 3.1加入的支持USB accessory的类。这个包是框架API的一部分，所以Android 3.1不需要导入额外的library就可以支持USB accessory。如果你只需要支持Android 3.1及更高的设备，你可以使用这个包，并在manifest文件中声明特性。

四、API简介

由于附加的library是对框架API的封装，所以这些类都很相似。你甚至可以直接使用android.hardware.usb的文档使用附加library。

注意：在附加library和框架API之间还是存在一些细微差别的

下表描述了USB accessory API相关的类：

4.1 附加library和框架API之间的差别

附加library和框架API之间有两个差别。

如果你使用附加library，获取UsbManger对象方式如下：

UsbManager manager = UsbManager.getInstance(this);

如果你使用框架API，获取UsbManager对象方式如下：

UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);

当你用intent filter过滤已连接的accessory时，可以从传递到你的应用的intent中获取UsbAccessory对象。而如果你使用的是附加的library的话，你就需要用以下方式获取UsbAccessory对象了：

UsbAccessory accessory = UsbManager.getAccessory(intent);

如果你使用框架API，则代码如下：

UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);

五、Android manifest设置

下面描述的是在使用usb accessory API前需要在manifest文件中添加的东西：

• 由于不是所有设备都支持USB accessory API，所以请用标签声明你的应用会使用android.hardware.usb.accessory特性。
• 如果你使用的是附加的library，请添加<uses-librara>标签指定com.android.future.usb.accessory。
• 如果你使用的是附加的library，请将SDK最小值设为API 10，如果使用的是框架API，请设为12。

• 如果你希望你的应用可以收到附加usb accessory的信息，可以在activity中指定<intent-filter>和<meta-data>以接收指定intent。其中action为android.hardware.usb.action.USB_ACCESSORY_ATTACHED，<meta-data>指定一个包含你想要知道的识别信息的外部XML文件。
  XML文件中需要声明你想要过滤的accessory的信息（用<usb-accessory>标签）。每个<usb-accessory>标签都包含以下属性：

  • manufacturer
  • model
  • version

  将这个resource文件保存在res/xml/目录。resource文件名称必须与<meta-data>中（没有.xml后缀）所写一致。

下面是一个manifest文件和对应resource文件示例：

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

resource文件保存为res/xml/accessory_filter.xml，并指定model、manufacturer、version：

<?xml version="1.0" encoding="utf-8"?>
<resources><usb-accessory model="DemoKit" manufacturer="Google" version="1.0"/>
</resources>

六、使用accessory

当用户将USB配件连接到Android设备时，Android系统会判断你的应用是否对此连接的配件感兴趣。如果是的话，你就可以跟此配件通信了。要声明你的应用对何种附件感兴趣，你可以：

1. 通过intent filter获取配件相关事件从而发现已连接配件，或直接枚举已连接配件
2. 向用户申请跟配件通信的权限
3. 在适当的接口上跟配件用读写操作通信

6.1 发现配件

当用户连接某个配件时，你的应用可以通过intent filter获取到它。你也可以直接枚举已连接的配件。如果你希望应用可以自动发现指定配件，你可以使用intent filter。如果你希望获取已连接设备列表或不想使用intent filter，可以使用枚举的方法。

6.1.1 使用intent filter

你可以使用添加了android.hardware.usb.action.USB_ACCESSORY_ATTACHED的intent filter指定你想要发现的USB配件。在这个intent filter中，你需要指定一个resource文件，在这个文件中包含你想要的USB配件的一些属性，如厂商、型号、版本。当用户将符合你的需求的配件连接到Android设备时，系统会通过intent通知你。

下面的例子显示了如何声明intent filter：

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

下面的例子显示了如何声明你感兴趣的配件：

<?xml version="1.0" encoding="utf-8"?>
<resources><usb-accessory manufacturer="Google, Inc." model="DemoKit" version="1.0" />
</resources>

在你的activity中，你可以用以下代码从intent中获取UsbAccessory：

UsbAccessory accessory = UsbManager.getAccessory(intent);

如果你使用的是框架API，则是使用以下代码：

UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);

6.1.2 枚举配件

你可以在应用运行时枚举到已注册的配件。

使用getAccessoryList()方法可以获取表示所有已连接usb配件的数组：

UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
UsbAccessory[] accessoryList = manager.getAcccessoryList();

注意：当前版本，每次只能获取一个已连接配件，在将来，会支持多配件获取

6.2 获取通信权限

在与USB配件通信前，你的应用必须向用户申请权限。

注意：如果你的应用使用intent filter方式发现配件，那么在用户允许你的应用处理相关intent时已经自动给予你的应用相关权限。如果使用的是其他方式，那么必须在连接配件前明确的申请权限。

显式申请权限在很多情况下都是必要的，比如你的应用要枚举已连接设备时。你必须在访问配件前检查相关权限，否则可能会收到运行时异常（如果用户拒绝给予你的应用权限）。

要显式的获取权限，首先需要创建一个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) {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);}}}}
};

在你的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()方法向用户申请权限：

UsbAccessory accessory;
...
mUsbManager.requestPermission(accessory, mPermissionIntent);

申请权限的对话框显示以后，用户的响应会通过广播发送给你的broadcast receiver，广播的intent包含名为“EXTRA_PERMISSION_GRANTED”的extra，其是一个boolean，表示用户是否给予权限。

6.3 与配件通信

你可以通过UsbManager获取file descriptor，然后通过输入输出流跟此descriptor通信。你应该在子线程跟配件通信，不要阻塞主线程。下面为打开配件并通信的示例：

UsbAccessory mAccessory;
ParcelFileDescriptor mFileDescriptor;
FileInputStream mInputStream;
FileOutputStream mOutputStream;
...
private void openAccessory() {Log.d(TAG, "openAccessory: " + accessory);mFileDescriptor = mUsbManager.openAccessory(mAccessory);if (mFileDescriptor != null) {FileDescriptor fd = mFileDescriptor.getFileDescriptor();mInputStream = new FileInputStream(fd);mOutputStream = new FileOutputStream(fd);Thread thread = new Thread(null, this, "AccessoryThread");thread.start();}
}

在“thread”的run()方法中，你可以用FileInputStream和FileOutputStream进行读写。当你用FileInputStream从配件中读数据时，请确保你使用的buffer足够存储USB数据包。Android accessory protocol支持的buffer大小最大为16384字节，所以你可以简单的将你的buffer设置为这个大小。

注意：在底层，USB full-speed配件的数据包为64字节，USB high-speed配件的数据包为512字节。Android accessory protocol会将两者统一成大小合乎逻辑的包。

6.4 终止与配件的通信

当你的通信结束或者配件与Android设备分离时，你可以用close()方法关闭file descriptor。要监听设备断开事件，可以用如下代码创建broadcast receiver：

BroadcastReceiver mUsbReceiver = 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}}}
};