Descripción general del host USB

Cuando tu dispositivo con Android está en modo de host USB, actúa como host USB, alimenta el bus y enumera los dispositivos USB conectados. El modo de host USB es compatible con Android 3.1 y versiones posteriores.

Descripción general de la API

Antes de comenzar, es importante comprender las clases con las que necesitas trabajar. En la siguiente tabla, se describen las APIs de host USB en el paquete android.hardware.usb.

Tabla 1: API del host USB

Clase Descripción
UsbManager Te permite enumerar los dispositivos USB conectados y comunicarte con ellos.
UsbDevice Representa un dispositivo USB conectado y contiene métodos para acceder a su información de identificación, interfaces y extremos.
UsbInterface Representa una interfaz de un dispositivo USB, que define un conjunto de funciones para el dispositivo. Un dispositivo puede tener una o más interfaces para comunicarse.
UsbEndpoint Representa un extremo de la interfaz, que es un canal de comunicación para esta. Una interfaz puede tener uno o más extremos y, por lo general, tiene extremos de entrada y salida para la comunicación bidireccional con el dispositivo.
UsbDeviceConnection Representa una conexión con el dispositivo, que transfiere datos en los extremos. Esta clase te permite enviar datos de ida y vuelta de forma síncrona o asíncrona.
UsbRequest Representa una solicitud asíncrona para comunicarse con un dispositivo a través de una UsbDeviceConnection.
UsbConstants Define constantes USB que corresponden a definiciones en linux/usb/ch9.h del kernel de Linux.

En la mayoría de los casos, debes usar todas estas clases (UsbRequest solo es necesaria si realizas una comunicación asíncrona) cuando te comunicas con un dispositivo USB. En general, obtienes un objeto UsbManager para recuperar el elemento UsbDevice que deseas. Cuando tengas el dispositivo, deberás encontrar el UsbInterface adecuado y el UsbEndpoint de esa interfaz para comunicarte. Una vez que obtengas el extremo correcto, abre una UsbDeviceConnection para comunicarte con el dispositivo USB.

Requisitos del manifiesto de Android

En la siguiente lista, se describe lo que debes agregar al archivo de manifiesto de tu aplicación antes de trabajar con las APIs de host USB:

  • Debido a que no se garantiza que todos los dispositivos con Android admitan las APIs de host USB, incluye un elemento <uses-feature> que declare que tu aplicación usa la función android.hardware.usb.host.
  • Establece la versión mínima del SDK de la aplicación en API nivel 12 o posterior. Las APIs de host USB no están presentes en los niveles de API anteriores.
  • Si quieres que se notifique a tu aplicación cuando se conecte un dispositivo USB, especifica un par de elementos <intent-filter> y <meta-data> para el intent android.hardware.usb.action.USB_DEVICE_ATTACHED en tu actividad principal. El elemento <meta-data> apunta a un archivo de recursos XML externo que declara información de identificación sobre el dispositivo que deseas detectar.

    En el archivo de recursos XML, declara los elementos <usb-device> para los dispositivos USB que quieras filtrar. En la siguiente lista, se describen los atributos de <usb-device>. En general, usa el ID del proveedor y del producto si deseas filtrar por un dispositivo específico, y usa la clase, la subclase y el protocolo si deseas filtrar por un grupo de dispositivos USB, como dispositivos de almacenamiento masivo o cámaras digitales. Puedes especificar ninguno o todos estos atributos. Si no especificas ningún atributo, se establecerá una coincidencia con todos los dispositivos USB, por lo que solo debes hacerlo si tu aplicación lo requiere:

    • vendor-id
    • product-id
    • class
    • subclass
    • protocol (dispositivo o interfaz)

    Guarda el archivo de recursos en el directorio res/xml/. El nombre de archivo del recurso (sin la extensión .xml) debe ser el mismo que especificaste en el elemento <meta-data>. El formato del archivo de recursos XML se muestra en el siguiente ejemplo.

Ejemplos de archivos de manifiesto y de recursos

A continuación, se muestra un ejemplo del manifiesto y de su archivo de recursos correspondiente:

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

En este caso, el siguiente archivo de recursos se debe guardar en res/xml/device_filter.xml y especifica que se debe filtrar cualquier dispositivo USB con los atributos especificados:

<?xml version="1.0" encoding="utf-8"?>

<resources>
    <usb-device vendor-id="1234" product-id="5678" class="255" subclass="66" protocol="1" />
</resources>

Cómo trabajar con dispositivos

Cuando los usuarios conectan dispositivos USB a un dispositivo con Android, el sistema Android puede determinar si tu aplicación está interesada en el dispositivo conectado. Si es así, puedes configurar la comunicación con el dispositivo si lo deseas. Para hacerlo, la aplicación debe realizar lo siguiente:

  1. Descubre los dispositivos USB conectados usando un filtro de intents para recibir una notificación cuando el usuario conecte un dispositivo USB o enumerando los dispositivos USB que ya están conectados.
  2. Si aún no lo tiene, debe solicitar permiso al usuario para conectarse al dispositivo USB.
  3. Comunícate con el dispositivo USB leyendo y escribiendo datos en los extremos de interfaz adecuados.

Cómo descubrir un dispositivo

Tu aplicación puede descubrir dispositivos USB usando un filtro de intents para recibir una notificación cuando el usuario conecta un dispositivo o enumerando los dispositivos USB que ya están conectados. Usar un filtro de intents es útil si quieres que tu aplicación detecte automáticamente un dispositivo que desees. Enumerar los dispositivos USB conectados es útil si quieres obtener una lista de todos los dispositivos conectados o si tu aplicación no filtró un intent.

Cómo usar un filtro de intents

Para que tu aplicación descubra un dispositivo USB en particular, puedes especificar un filtro de intents para filtrar el intent android.hardware.usb.action.USB_DEVICE_ATTACHED. Junto con este filtro de intents, debes especificar un archivo de recursos que indique las propiedades del dispositivo USB, como el ID de producto y de proveedor. Cuando los usuarios conectan un dispositivo que coincide con tu filtro de dispositivos, el sistema les presenta un diálogo en el que se les pregunta si quieren iniciar tu aplicación. Si los usuarios aceptan, tu aplicación tendrá permiso automáticamente para acceder al dispositivo hasta que se desconecte.

En el siguiente ejemplo, se muestra cómo declarar el filtro de intents:

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

En el siguiente ejemplo, se muestra cómo declarar el archivo de recursos correspondiente que especifica los dispositivos USB que te interesan:

<?xml version="1.0" encoding="utf-8"?>

<resources>
    <usb-device vendor-id="1234" product-id="5678" />
</resources>

En tu actividad, puedes obtener el UsbDevice que representa el dispositivo conectado desde el intent de la siguiente manera:

Kotlin

val device: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)

Java

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

Cómo enumerar dispositivos

Si tu aplicación está interesada en inspeccionar todos los dispositivos USB conectados actualmente mientras se ejecuta, puede enumerar los dispositivos en el bus. Usa el método getDeviceList() para obtener un mapa de hash de todos los dispositivos USB conectados. El mapa de hash se indexa por el nombre del dispositivo USB si quieres obtener un dispositivo del mapa.

Kotlin

val manager = getSystemService(Context.USB_SERVICE) as UsbManager
...
val deviceList = manager.getDeviceList()
val device = deviceList.get("deviceName")

Java

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

Si lo deseas, también puedes obtener un iterador del mapa de hash y procesar cada dispositivo uno por uno:

Kotlin

val manager = getSystemService(Context.USB_SERVICE) as UsbManager
..
val deviceList: HashMap<String, UsbDevice> = manager.deviceList
deviceList.values.forEach { device ->
    // your code
}

Java

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
}

Cómo obtener permiso para comunicarse con un dispositivo

Antes de comunicarse con el dispositivo USB, la aplicación debe tener el permiso de los usuarios.

Nota: Si tu aplicación usa un filtro de intents para descubrir dispositivos USB a medida que se conectan, recibe automáticamente el permiso si el usuario permite que tu aplicación controle el intent. De lo contrario, debes solicitar permiso de forma explícita en tu aplicación antes de conectarte al dispositivo.

Es posible que, en algunas situaciones, sea necesario solicitar permiso de forma explícita, como cuando tu aplicación enumera los dispositivos USB que ya están conectados y, luego, quiere comunicarse con uno. Debes verificar que se haya otorgado permiso para acceder a un dispositivo antes de intentar comunicarte con él. De lo contrario, recibirás un error de tiempo de ejecución si el usuario rechazó el permiso para acceder al dispositivo.

A fin de obtener permiso de manera explícita, primero crea un receptor de emisión. Este receptor escucha el intent que se transmite cuando llamas a requestPermission(). La llamada a requestPermission() muestra un diálogo al usuario en el que se le solicita permiso para conectarse al dispositivo. En el siguiente código de muestra, se indica cómo crear el receptor de transmisiones:

Kotlin

private const val ACTION_USB_PERMISSION = "com.android.example.USB_PERMISSION"

private val usbReceiver = object : BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (ACTION_USB_PERMISSION == intent.action) {
            synchronized(this) {
                val device: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)

                if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) {
                    device?.apply {
                        // call method to set up device communication
                    }
                } else {
                    Log.d(TAG, "permission denied for device $device")
                }
            }
        }
    }
}

Java

private static final String ACTION_USB_PERMISSION =
    "com.android.example.USB_PERMISSION";
private final BroadcastReceiver usbReceiver = 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);
                }
            }
        }
    }
};

Para registrar el receptor de transmisiones, agrega lo siguiente en el método onCreate() de tu actividad:

Kotlin

private const val ACTION_USB_PERMISSION = "com.android.example.USB_PERMISSION"
...
val manager = getSystemService(Context.USB_SERVICE) as UsbManager
...
permissionIntent = PendingIntent.getBroadcast(this, 0,
                  Intent(ACTION_USB_PERMISSION), PendingIntent.FLAG_IMMUTABLE)
val filter = IntentFilter(ACTION_USB_PERMISSION)
registerReceiver(usbReceiver, filter)

Java

UsbManager usbManager = (UsbManager) getSystemService(Context.USB_SERVICE);
private static final String ACTION_USB_PERMISSION =
    "com.android.example.USB_PERMISSION";
...
permissionIntent = PendingIntent.getBroadcast(this, 0,
              new Intent(ACTION_USB_PERMISSION), PendingIntent.FLAG_IMMUTABLE);
IntentFilter filter = new IntentFilter(ACTION_USB_PERMISSION);
registerReceiver(usbReceiver, filter);

Para que aparezca el diálogo en el que se solicita permiso de acceso al dispositivo, llama al método requestPermission():

Kotlin

lateinit var device: UsbDevice
...
usbManager.requestPermission(device, permissionIntent)

Java

UsbDevice device;
...
usbManager.requestPermission(device, permissionIntent);

Cuando los usuarios responden al diálogo, tu receptor de transmisiones recibe el intent que contiene el elemento adicional EXTRA_PERMISSION_GRANTED, que es un valor booleano que representa la respuesta. Verifica este extra para obtener un valor de verdadero antes de conectarte al dispositivo.

Cómo comunicarse con un dispositivo

La comunicación con un dispositivo USB puede ser síncrona o asíncrona. En cualquier caso, debes crear un subproceso nuevo en el que se realicen todas las transmisiones de datos para no bloquear el subproceso de IU. Para configurar correctamente la comunicación con un dispositivo, debes obtener el UsbInterface y el UsbEndpoint adecuados del dispositivo con el que deseas comunicarte y enviar solicitudes en este extremo con un UsbDeviceConnection. En general, debes realizar lo siguiente:

  • Verifica los atributos de un objeto UsbDevice, como el ID del producto, el ID del proveedor o la clase de dispositivo, para determinar si deseas comunicarte con el dispositivo.
  • Cuando tengas la certeza de que quieres comunicarte con el dispositivo, busca el UsbInterface adecuado que quieras usar para comunicarte junto con el UsbEndpoint adecuado de esa interfaz. Las interfaces pueden tener uno o más extremos y, por lo general, tendrán un extremo de entrada y uno de salida para la comunicación bidireccional.
  • Cuando encuentres el extremo correcto, abre un UsbDeviceConnection en ese extremo.
  • Proporciona los datos que deseas transmitir en el extremo con el método bulkTransfer() o controlTransfer(). Debes realizar este paso en otro subproceso para evitar que se bloquee el subproceso de IU principal. Para obtener más información sobre el uso de subprocesos en Android, consulta Procesos y subprocesos.

El siguiente fragmento de código es una forma trivial de realizar una transferencia de datos síncrona. Tu código debería tener más lógica para encontrar correctamente la interfaz y los extremos adecuados para la comunicación, y también debería transferir datos en un subproceso diferente del subproceso de IU principal:

Kotlin

private lateinit var bytes: ByteArray
private val TIMEOUT = 0
private val forceClaim = true

...

device?.getInterface(0)?.also { intf ->
    intf.getEndpoint(0)?.also { endpoint ->
        usbManager.openDevice(device)?.apply {
            claimInterface(intf, forceClaim)
            bulkTransfer(endpoint, bytes, bytes.size, TIMEOUT) //do in another thread
        }
    }
}

Java

private Byte[] bytes;
private static int TIMEOUT = 0;
private boolean forceClaim = true;

...

UsbInterface intf = device.getInterface(0);
UsbEndpoint endpoint = intf.getEndpoint(0);
UsbDeviceConnection connection = usbManager.openDevice(device);
connection.claimInterface(intf, forceClaim);
connection.bulkTransfer(endpoint, bytes, bytes.length, TIMEOUT); //do in another thread

Para enviar datos de forma asíncrona, usa la clase UsbRequest para initialize y queue una solicitud asíncrona y, luego, espera el resultado con requestWait().

Cómo finalizar la comunicación con un dispositivo

Cuando termines de comunicarte con un dispositivo o si este se desconectó, cierra UsbInterface y UsbDeviceConnection llamando a releaseInterface() y close(). Para escuchar eventos de desconexión, crea un receptor de transmisiones como el que se muestra a continuación:

Kotlin

var usbReceiver: BroadcastReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {

        if (UsbManager.ACTION_USB_DEVICE_DETACHED == intent.action) {
            val device: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)
            device?.apply {
                // call your method that cleans up and closes communication with the device
            }
        }
    }
}

Java

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

Crear el receptor de transmisiones dentro de la aplicación, y no en el manifiesto, permite que tu aplicación solo controle los eventos de desconexión mientras se está ejecutando. De esta manera, los eventos desconectados solo se envían a la aplicación que se está ejecutando en ese momento y no se transmiten a todas las aplicaciones.