From bde2b92f58952c51976573048874cd7b43c126a1 Mon Sep 17 00:00:00 2001 From: Robert Ly Date: Mon, 18 Apr 2011 10:18:30 -0700 Subject: [PATCH] Doc change: adding usb docs and removed ADK doc. ADK doc will be in another CL Change-Id: Ib6a5c3a958a77f5ef9322fb79b2da19763ec364d --- docs/html/guide/guide_toc.cs | 12 +- docs/html/guide/topics/usb/accessory.jd | 461 ++++++++++++++++++++++++ docs/html/guide/topics/usb/host.jd | 443 +++++++++++++++++++++++ docs/html/guide/topics/usb/index.jd | 67 ++++ docs/html/images/usb-host-accessory.png | Bin 0 -> 47143 bytes 5 files changed, 982 insertions(+), 1 deletion(-) create mode 100644 docs/html/guide/topics/usb/accessory.jd create mode 100644 docs/html/guide/topics/usb/host.jd create mode 100644 docs/html/guide/topics/usb/index.jd create mode 100644 docs/html/images/usb-host-accessory.png diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 46763c23f39da..5b8aa7af5d21e 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -301,6 +301,17 @@
  • Near Field Communication new!
    • +
  • +
    + USB + new! +
    + +
    • +
  • Session Initiation Protocol new! @@ -347,7 +358,6 @@ What To Test
    • - diff --git a/docs/html/guide/topics/usb/accessory.jd b/docs/html/guide/topics/usb/accessory.jd new file mode 100644 index 0000000000000..7638e3091d17d --- /dev/null +++ b/docs/html/guide/topics/usb/accessory.jd @@ -0,0 +1,461 @@ +page.title=USB Accessory +@jd:body + +
    + +
    + +

    USB accessory mode allows users to connect + USB host hardware specifically designed for Android-powered devices. The accessories must adhere + to the Android accessory protocol outlined in Android Accessory Development Kit documentation. + This allows Android-powered devices that cannot act as a USB host to still interact with USB + hardware. When an Android-powered device is in USB accessory mode, the attached Android USB + accessory acts as the host, provides power to the USB bus, and enumerates connected devices. + Android 3.1 (API level 12) supports USB accessory mode and the feature is also backported to + Android 2.3.4 (API level 10) to enable support for a broader range of devices.

    + +

    Choosing the Right USB Accessory APIs

    + +

    Although the USB accessory APIs were introduced to the platform in Android 3.1, they are also + available in Android 2.3.4 using the Google APIs add-on library. Because these APIs were + backported using an external library, there are two packages that you can import to support USB + accessory mode. Depending on what Android-powered devices you want to support, you might have to + use one over the other:

    + + + +

    Installing the Google APIs add-on library

    + +

    If you want to install the add-on, you can do so by installing the Google APIs Android API 10 + package with the SDK Manager. See Installing the Google APIs + Add-on for more information on installing the add-on library.

    + +

    API Overview

    + +

    Because the add-on library is a wrapper for the framework APIs, the classes that support the + USB accessory feature are similar. You can use the reference documentation for the {@link + android.hardware.usb} even if you are using the add-on library.

    + +

    Note: There is, however, a minor usage + difference between the add-on library and framework APIs that you should be aware of.

    + +

    The following table describes the classes that support the USB accessory APIs:

    + + + + + + + + + + + + + + + + + + + +
    ClassDescription
    {@link android.hardware.usb.UsbManager}Allows you to enumerate and communicate with connected USB accessories.
    {@link android.hardware.usb.UsbAccessory}Represents a USB accessory and contains methods to access its identifying + information.
    + +

    Usage differences between the add-on library and platform APIs

    + +

    There are two usage differences between using the Google APIs add-on library and the platform + APIs.

    + +

    If you are using the add-on library, you must obtain the {@link + android.hardware.usb.UsbManager} object in the following manner:

    + 
    +UsbManager manager = UsbManager.getInstance(this);
+
    + +

    If you are not using the add-on library, you must obtain the {@link + android.hardware.usb.UsbManager} object in the following manner:

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

    When you filter for a connected accessory with an intent filter, the {@link + android.hardware.usb.UsbAccessory} object is contained inside the intent that is passed to your + application. If you are using the add-on library, you must obtain the {@link + android.hardware.usb.UsbAccessory} object in the following manner:

    + 
    +UsbAccessory accessory = UsbManager.getAccessory(intent);
+
    + +

    If you are not using the add-on library, you must obtain the {@link + android.hardware.usb.UsbAccessory} object in the following manner:

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

    Android Manifest requirements

    + +

    The following list describes what you need to add to your application's manifest file before + working with the USB accesory APIs. The manifest and resource file + examples show how to declare these items:

    + + + +

    Manifest and resource file examples

    + +

    The following example shows a sample manifest and its corresponding resource file:

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

    In this case, the following resource file should be saved in + res/xml/accessory_filter.xml and specifies that any accessory that has the + corresponding model, manufacturer, and version should be filtered. The accessory sends these + attributes the Android-powered device:

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

    Working with Accessories

    + +

    When users connect USB accessories to an Android-powered device, the Android system can + determine whether your application is interested in the connected accessory. If so, you can set + up communication with the accessory if desired. To do this, your application has to:

    + +
      +
    1. Discover connected accessories by using an intent filter that filters for accessory + attached events or by enumerating connected accessories and finding the appropriate one.
      2. + +
    2. Ask the user for permission to communicate with the accessory, if not already + obtained.
      3. + +
    3. Communicate with the accessory by reading and writing data on the appropriate interface + endpoints.
      4. +
    + +

    Discovering an accessory

    + +

    Your application can discover accessories by either using an intent filter to be notified when + the user connects an accessory or by enumerating accessories that are already connected. Using an + intent filter is useful if you want to be able to have your application automatically detect a + desired accessory. Enumerating connected accessories is useful if you want to get a list of all + connected accessories or if your application did not filter for an intent.

    + +

    Using an intent filter

    + +

    To have your application discover a particular USB accessory, you can specify an intent filter + to filter for the android.hardware.usb.action.USB_ACCESSORY_ATTACHED intent. Along + with this intent filter, you need to specify a resource file that specifies properties of the USB + accessory, such as manufacturer, model, and version. When users connect an accessory that matches + your accessory filter,

    + +

    The following example shows how to declare the 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>
+
    + +

    The following example shows how to declare the corresponding resource file that specifies the + USB accessories that you're interested in:

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

    In your activity, you can obtain the {@link android.hardware.usb.UsbAccessory} that represents + the attached accessory from the intent like this (with the add-on library):

    + 
    +UsbAccessory accessory = UsbManager.getAccessory(intent);
+
    + +

    or like this (with the platform APIs):

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

    Enumerating accessories

    + +

    You can have your application enumerate accesories that have identified themselves while your + application is running.

    + +

    Use the {@link android.hardware.usb.UsbManager#getAccessoryList() getAccessoryList()} method + to get an array all the USB accessories that are connected:

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

    Note: Currently, only one connected accessory is supported at + one time, but the API is designed to support multiple accessories in the future.

    + +

    Obtaining permission to communicate with an accessory

    + +

    Before communicating with the USB accessory, your applicaton must have permission from your + users.

    + +

    Note: If your application uses an + intent filter to discover accessories as they're connected, it automatically receives + permission if the user allows your application to handle the intent. If not, you must request + permission explicitly in your application before connecting to the accessory.

    + +

    Explicitly asking for permission might be neccessary in some situations such as when your + application enumerates accessories that are already connected and then wants to communicate with + one. You must check for permission to access an accessory before trying to communicate with it. + If not, you will receive a runtime error if the user denied permission to access the + accessory.

    + +

    To explicitly obtain permission, first create a broadcast receiver. This receiver listens for + the intent that gets broadcast when you call {@link + android.hardware.usb.UsbManager#requestPermission requestPermission()}. The call to {@link + android.hardware.usb.UsbManager#requestPermission requestPermission()} displays a dialog to the + user asking for permission to connect to the accessory. The following sample code shows how to + create the 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);
+                }
+            }
+        }
+    }
+};
+
    + +

    To register the broadcast receiver, put this in your onCreate() method in your + activity:

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

    To display the dialog that asks users for permission to connect to the accessory, call the + {@link android.hardware.usb.UsbManager#requestPermission requestPermission()} method:

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

    When users reply to the dialog, your broadcast receiver receives the intent that contains the + {@link android.hardware.usb.UsbManager#EXTRA_PERMISSION_GRANTED} extra, which is a boolean + representing the answer. Check this extra for a value of true before connecting to the + accessory.

    + +

    Communicating with an accessory

    + +

    You can communicate with the accessory by using the {@link android.hardware.usb.UsbManager} to + obtain a file descriptor that you can set up input and output streams to read and write data to + descriptor. The streams represent the accessory's input and output bulk endpoints. You should set + up the communication between the device and accessory in another thread, so you don't lock the + main UI thread. The following example shows how to open an accessory to communicate with:

    + 
    +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();
+    }
+}
+
    + +

    In the thread's run() method, you can read and write to the accessory by using + the {@link java.io.FileInputStream} or {@link java.io.FileOutputStream} objects. When reading + data from an accessory with a {@link java.io.FileInputStream} object, ensure that the buffer that + you use is big enough to store the USB packet data. The Android accessory protocol supports + packet buffers up to 16384 bytes, so you can choose to always declare your buffer to be of this + size for simplicity.

    + +

    Note: At a lower level, the packets are 64 bytes for USB + full-speed accessories and 512 bytes for USB high-speed accessories. The Android accessory + protocol bundles the packets together for both speeds into one logical packet for simplicity.

    + +

    For more information about using threads in Android, see Processes and + Threads.

    + +

    Terminating communication with an accessory

    + +

    When you are done communicating with an accessory or if the accessory was detached, close the + file descriptor that you opened by calling {@link android.os.ParcelFileDescriptor#close close()}. + To listen for detached events, create a broadcast receiver like below:

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

    Creating the broadcast receiver within the application, and not the manifest, allows your + application to only handle detached events while it is running. This way, detached events are + only sent to the application that is currently running and not broadcast to all applications.

    + diff --git a/docs/html/guide/topics/usb/host.jd b/docs/html/guide/topics/usb/host.jd new file mode 100644 index 0000000000000..942708dabf74a --- /dev/null +++ b/docs/html/guide/topics/usb/host.jd @@ -0,0 +1,443 @@ +page.title=USB Host +@jd:body + +
    + +
    + +

    When your Android-powered device is in USB host mode, it acts as the USB host, powers the bus, + and enumerates connected USB devices. USB host mode is supported in Android 3.1 and higher.

    + +

    API Overview

    + +

    Before you begin, it is important to understand the classes that you need to work with. The + following table describes the USB host APIs in the {@link android.hardware.usb} package.

    + +

    Table 1. USB Host APIs

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ClassDescription
    {@link android.hardware.usb.UsbManager}Allows you to enumerate and communicate with connected USB devices.
    {@link android.hardware.usb.UsbDevice}Represents a connected USB device and contains methods to access its identifying + information, interfaces, and endpoints.
    {@link android.hardware.usb.UsbInterface}Represents an interface of a USB device, which defines a set of functionality for the + device. A device can have one or more interfaces on which to communicate on.
    {@link android.hardware.usb.UsbEndpoint}Represents an interface endpoint, which is a communication channel for this interface. An + interface can have one or more endpoints, and usually has input and output endpoints for + two-way communication with the device.
    {@link android.hardware.usb.UsbDeviceConnection}Represents a connection to the device, which transfers data on endpoints. This class + allows you to send data back and forth sychronously or asynchronously.
    {@link android.hardware.usb.UsbRequest}Represents an asynchronous request to communicate with a device through a {@link + android.hardware.usb.UsbDeviceConnection}.
    {@link android.hardware.usb.UsbConstants}Defines USB constants that correspond to definitions in linux/usb/ch9.h of the Linux + kernel.
    + +

    In most situations, you need to use all of these classes ({@link + android.hardware.usb.UsbRequest} is only required if you are doing asynchronous communication) + when communicating with a USB device. In general, you obtain a {@link + android.hardware.usb.UsbManager} to retrieve the desired {@link android.hardware.usb.UsbDevice}. + When you have the device, you need to find the appropriate {@link + android.hardware.usb.UsbInterface} and the {@link android.hardware.usb.UsbEndpoint} of that + interface to communicate on. Once you obtain the correct endpoint, open a {@link + android.hardware.usb.UsbDeviceConnection} to communicate with the USB device.

    + +

    Android Manifest Requirements

    + +

    The following list describes what you need to add to your application's manifest file before + working with the USB host APIs:

    + + + +

    Manifest and resource file examples

    + +

    The following example shows a sample manifest and its corresponding resource file:

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

    In this case, the following resource file should be saved in + res/xml/device_filter.xml and specifies that any USB device with the corresponding + vendor ID and product ID should be filtered. These IDs are specific to the device and are + specified by the device's manufacturer:

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

    Working with Devices

    + +

    When users connect USB devices to an Android-powered device, the Android system can determine + whether your application is interested in the connected device. If so, you can set up + communication with the device if desired. To do this, your application has to:

    + +
      +
    1. Discover connected USB devices by using an intent filter to be notified when the user + connects a USB device or by enumerating USB devices that are already connected.
      2. + +
    2. Ask the user for permission to connect to the USB device, if not already obtained.
      3. + +
    3. Communicate with the USB device by reading and writing data on the appropriate interface + endpoints.
      4. +
    + +

    Discovering a device

    + +

    Your application can discover USB devices by either using an intent filter to be notified when + the user connects a device or by enumerating USB devices that are already connected. Using an + intent filter is useful if you want to be able to have your application automatically detect a + desired device. Enumerating connected USB devices is useful if you want to get a list of all + connected devices or if your application did not filter for an intent.

    + +

    Using an intent filter

    + +

    To have your application discover a particular USB device, you can specify an intent filter to + filter for the android.hardware.usb.action.USB_DEVICE_ATTACHED intent. Along with + this intent filter, you need to specify a resource file that specifies properties of the USB + device, such as product and vendor ID. When users connect a device that matches your device + filter, the system presents them with a dialog that asks if they want to start your application. + If users accept, your application automatically has permission to access the device until the + device is disconnected.

    + +

    The following example shows how to declare the 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>
+
    + +

    The following example shows how to declare the corresponding resource file that specifies the + USB devices that you're interested in:

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

    In your activity, you can obtain the {@link android.hardware.usb.UsbDevice} that represents + the attached device from the intent like this:

    + 
    +UsbDevice device = (UsbDevice) intent.getParcelableExtra(UsbManager.EXTRA_DEVICE);
+
    + +

    Enumerating devices

    + +

    If your application is interested in inspecting all of the USB devices currently connected + while your application is running, it can enumerate devices on the bus. Use the {@link + android.hardware.usb.UsbManager#getDeviceList() getDeviceList()} method to get a hash map of all + the USB devices that are connected. The hash map is keyed by the USB device's name if you want to + obtain a device from the map.

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

    If desired, you can also just obtain an iterator from the hash map and process each device one + by one:

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

    Obtaining permission to communicate with a device

    + +

    Before communicating with the USB device, your applicaton must have permission from your + users.

    + +

    Note: If your application uses an + intent filter to discover USB devices as they're connected, it automatically receives + permission if the user allows your application to handle the intent. If not, you must request + permission explicitly in your application before connecting to the device.

    + +

    Explicitly asking for permission might be neccessary in some situations such as when your + application enumerates USB devices that are already connected and then wants to communicate with + one. You must check for permission to access a device before trying to communicate with it. If + not, you will receive a runtime error if the user denied permission to access the device.

    + +

    To explicitly obtain permission, first create a broadcast receiver. This receiver listens for + the intent that gets broadcast when you call {@link + android.hardware.usb.UsbManager#requestPermission requestPermission()}. The call to {@link + android.hardware.usb.UsbManager#requestPermission requestPermission()} displays a dialog to the + user asking for permission to connect to the device. The following sample code shows how to + create the 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);
+                }
+            }
+        }
+    }
+};
+
    + +

    To register the broadcast receiver, add this in your onCreate() method in your + activity:

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

    To display the dialog that asks users for permission to connect to the device, call the {@link + android.hardware.usb.UsbManager#requestPermission requestPermission()} method:

    + 
    +UsbDevice device;
+...
+mUsbManager.requestPermission(device, mPermissionIntent);
+
    + +

    When users reply to the dialog, your broadcast receiver receives the intent that contains the + {@link android.hardware.usb.UsbManager#EXTRA_PERMISSION_GRANTED} extra, which is a boolean + representing the answer. Check this extra for a value of true before connecting to the + device.

    + +

    Communicating with a device

    + +

    Communication with a USB device can be either synchronous or asynchronous. In either case, you + should create a new thread on which to carry out all data transmissions, so you don't block the + UI thread. To properly set up communication with a device, you need to obtain the appropriate + {@link android.hardware.usb.UsbInterface} and {@link android.hardware.usb.UsbEndpoint} of the + device that you want to communicate on and send requests on this endpoint with a {@link + android.hardware.usb.UsbDeviceConnection}. In general, your code should:

    + + + +

    The following code snippet is a trivial way to do a synchronous data transfer. Your code + should have more logic to correctly find the correct interface and endpoints to communicate on + and also should do any transferring of data in a different thread than the main UI thread:

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

    To send data asynchronously, use the {@link android.hardware.usb.UsbRequest} class to {@link + android.hardware.usb.UsbRequest#initialize initialize} and {@link + android.hardware.usb.UsbRequest#queue queue} an asynchronous request, then wait for the result + with {@link android.hardware.usb.UsbDeviceConnection#requestWait requestWait()}.

    + +

    For more information, see the AdbTest sample, which shows how to do + asynchronous bulk transfers, and the MissleLauncher sample, which + shows how to listen on an interrupt endpoint asynchronously.

    + +

    Terminating communication with a device

    + +

    When you are done communicating with a device or if the device was detached, close the {@link + android.hardware.usb.UsbInterface} and {@link android.hardware.usb.UsbDeviceConnection} by + calling {@link android.hardware.usb.UsbDeviceConnection#releaseInterface releaseInterface()} and + {@link android.hardware.usb.UsbDeviceConnection#close() close()}. To listen for detached events, + create a broadcast receiver like below:

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

    Creating the broadcast receiver within the application, and not the manifest, allows your + application to only handle detached events while it is running. This way, detached events are + only sent to the application that is currently running and not broadcast to all applications.

    + diff --git a/docs/html/guide/topics/usb/index.jd b/docs/html/guide/topics/usb/index.jd new file mode 100644 index 0000000000000..18af06ac666c3 --- /dev/null +++ b/docs/html/guide/topics/usb/index.jd @@ -0,0 +1,67 @@ +page.title=USB Host and Accessory +@jd:body + +
    +
    +

    Topics

    + +
      +
    1. USB Accessory
      2. + +
    2. USB Host
      3. +
    +
    +
    + +

    Android supports a variety of USB peripherals and Android USB accessories (hardware that + implements the Android accessory protocol) through two modes: USB accessory and USB host. In USB + accessory mode, the external USB hardware act as the USB hosts. Examples of accessories might + include robotics controllers; docking stations; diagnostic and musical equipment; kiosks; card + readers; and much more. This gives Android-powered devices that do not have host capabilities the + ability to interact with USB hardware. Android USB accessories must be designed to work with + Android-powered devices and must adhere to the Android accessory communication protocol. In USB + host mode, the Android-powered device acts as the host. Examples of devices include digital + cameras, keyboards, mice, and game controllers. USB devices that are designed for a wide range of + applications and environments can still interact with Android applications that can correctly + communicate with the device.

    + +

    Figure 1 shows the differences between the two modes. When the Android-powered device is in + host mode, it acts as the USB host and powers the bus. When the Android-powered device is in USB + accessory mode, the connected USB hardware (an Android USB accessory in this case) acts as the + host and powers the bus.

    + +

    Figure 1. USB Host and Accessory Modes

    + +

    USB accessory and host modes are directly supported in Android 3.1 (API level 12) or newer + platforms. USB accessory mode is also backported to Android 2.3.4 (API level 10) as an add-on + library to support a broader range of devices. Device manufacturers can choose whether or not to + include the add-on library on the device's system image.

    + +

    Note: Support for USB host and accessory modes are ultimately + dependant on the device's hardware, regardless of platform level. You can filter for devices that + support USB host and accessory through a <uses-feature> element. See + the USB accessory and host documentation for more details.

    + +

    Debugging considerations

    + +

    When debugging applications that use USB accessory or host features, you most likely will have + USB hardware connected to your Android-powered device. This will prevent you from having an + adb connection to the Android-powered device via USB. You can still access + adb over a network connection. To enable adb over a network + connection:

    + +
      +
    1. Connect the Android-powered device via USB to your computer.
      2. + +
    2. From your SDK platform-tools/ directory, enter adb tcpip 5555 at + the command prompt.
      3. + +
    3. Enter adb connect <device-ip-address>:5555 You should now be connected + to the Android-powered device and can issue the usual adb commands like adb + logcat.
      4. + +
    4. To set your device to listen on USB, enter adb usb.
      5. +
    diff --git a/docs/html/images/usb-host-accessory.png b/docs/html/images/usb-host-accessory.png new file mode 100644 index 0000000000000000000000000000000000000000..f82fd6ffd7daaf6afa42e312231549e055dc9246 GIT binary patch literal 47143 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