Quando o dispositivo Android está no modo host USB, ele atua como host USB, alimenta o barramento e enumera os dispositivos USB conectados. O modo de host USB é compatível com o Android 3.1 e posterior.
Visão geral da API
Antes de começar, é importante entender as classes com as quais você precisa trabalhar. A
tabela a seguir descreve as APIs de host USB no pacote android.hardware.usb.
Tabela 1. APIs de host USB
| Turma | Descrição |
|---|---|
UsbManager |
Permite enumerar e se comunicar com dispositivos USB conectados. |
UsbDevice |
Representa um dispositivo USB conectado e contém métodos para acessar as informações de identificação, as interfaces e os endpoints dele. |
UsbInterface |
Representa uma interface de um dispositivo USB, que define um conjunto de funcionalidades para o dispositivo. Um dispositivo pode ter uma ou mais interfaces de comunicação. |
UsbEndpoint |
Representa um endpoint da interface, que é um canal de comunicação dessa interface. Uma interface pode ter um ou mais endpoints e geralmente tem endpoints de entrada e saída para comunicação bidirecional com o dispositivo. |
UsbDeviceConnection |
Representa uma conexão com o dispositivo, que transfere dados em endpoints. Essa classe permite enviar dados de forma síncrona ou assíncrona. |
UsbRequest |
Representa uma solicitação assíncrona para se comunicar com um dispositivo por meio de UsbDeviceConnection. |
UsbConstants |
Define constantes USB que correspondem às definições em linux/usb/ch9.h do kernel do Linux. |
Na maioria das situações, é necessário usar todas essas classes (UsbRequest só é necessária se você estiver fazendo comunicação assíncrona)
ao se comunicar com um dispositivo USB. Em geral, você recebe um UsbManager para recuperar o UsbDevice que quer.
Quando você tiver o dispositivo, será necessário encontrar o UsbInterface e o UsbEndpoint adequados dessa
interface para se comunicar. Depois de ter o endpoint correto, abra um UsbDeviceConnection para se comunicar com o dispositivo USB.
Requisitos de manifesto do Android
A lista a seguir descreve o que você precisa adicionar ao arquivo de manifesto do aplicativo antes de trabalhar com as APIs de host USB:
- Como nem todos os dispositivos Android são compatíveis com as APIs de host USB,
inclua um elemento
<uses-feature>que declare que o aplicativo usa o recursoandroid.hardware.usb.host. - Defina o SDK mínimo do app como a API nível 12 ou posterior. As APIs de host USB não estão presentes em níveis de API anteriores.
- Se você quiser que o aplicativo seja notificado sobre um dispositivo USB conectado, especifique um
par de elementos
<intent-filter>e<meta-data>para a intentandroid.hardware.usb.action.USB_DEVICE_ATTACHEDna atividade principal. O elemento<meta-data>aponta para um arquivo de recurso XML externo que declara informações de identificação sobre o dispositivo que você quer detectar.No arquivo de recurso XML, declare elementos
<usb-device>para os dispositivos USB que você quer filtrar. A lista a seguir descreve os atributos de<usb-device>. Em geral, use o ID do fornecedor e do produto se quiser filtrar um dispositivo específico e use a classe, subclasse e protocolo se quiser filtrar um grupo de dispositivos USB, como dispositivos de armazenamento em massa ou câmeras digitais. É possível especificar nenhum ou todos esses atributos. Não especificar atributos corresponde a todos os dispositivos USB. Portanto, faça isso apenas se o aplicativo exigir:vendor-idproduct-idclasssubclassprotocol(dispositivo ou interface)
Salve o arquivo de recurso no diretório
res/xml/. O nome do arquivo de recurso (sem a extensão .xml) precisa ser igual ao especificado no elemento<meta-data>. O formato do arquivo de recurso XML é mostrado no exemplo abaixo.
Exemplos de arquivo de manifesto e recurso
O exemplo a seguir mostra um manifesto e o arquivo de recurso correspondente:
<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>
Nesse caso, o arquivo de recurso a seguir precisa ser salvo em
res/xml/device_filter.xml e especifica que qualquer dispositivo USB com os atributos
especificados precisa ser filtrado:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-device vendor-id="1234" product-id="5678" class="255" subclass="66" protocol="1" /> </resources>
Trabalhar com dispositivos
Quando os usuários conectam dispositivos USB a um dispositivo Android, o sistema pode determinar se o aplicativo tem interesse no dispositivo conectado. Se sim, você poderá configurar a comunicação com o dispositivo, se quiser. Para fazer isso, seu app precisa:
- Descubra dispositivos USB conectados usando um filtro de intent para receber notificações quando o usuário conectar um dispositivo USB ou enumerando os dispositivos USB que já estão conectados.
- pedir permissão ao usuário para se conectar ao dispositivo USB, se ainda não tiver recebido;
- Comunique-se com o dispositivo USB lendo e gravando dados nos endpoints de interface adequados.
Descobrir um dispositivo
O aplicativo pode descobrir dispositivos USB usando um filtro de intent para ser notificado quando o usuário conectar um dispositivo ou enumerando os dispositivos USB que já estão conectados. Usar um filtro de intent é útil se você quiser que o aplicativo detecte automaticamente um dispositivo. A enumeração de dispositivos USB conectados é útil para receber uma lista de todos os dispositivos conectados ou se o aplicativo não tiver filtrado uma intent.
Usar um filtro de intent
Para que o aplicativo descubra um dispositivo USB específico, especifique um filtro de intent para
filtrar a intent android.hardware.usb.action.USB_DEVICE_ATTACHED. Além desse
filtro de intent, é necessário especificar um arquivo de recurso que especifique as propriedades do dispositivo
USB, como o ID do produto e do fornecedor. Quando os usuários conectam um dispositivo que corresponde ao filtro, o sistema mostra uma caixa de diálogo perguntando se eles querem iniciar o aplicativo.
Se os usuários aceitarem, o aplicativo terá permissão automática para acessar o dispositivo até que ele seja desconectado.
O exemplo a seguir mostra como declarar o filtro de intent:
<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>
O exemplo a seguir mostra como declarar o arquivo de recurso correspondente que especifica os dispositivos USB de seu interesse:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-device vendor-id="1234" product-id="5678" /> </resources>
Na sua atividade, é possível receber o UsbDevice que representa
o dispositivo conectado da intent desta forma:
Kotlin
val device: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)
Java
UsbDevice device = (UsbDevice) intent.getParcelableExtra(UsbManager.EXTRA_DEVICE);
Enumerar dispositivos
Se o aplicativo precisar inspecionar todos os dispositivos USB conectados
enquanto estiver em execução, ele poderá enumerar os dispositivos no barramento. Use o método getDeviceList() para receber um mapa de hash de todos
os dispositivos USB conectados. O mapa de hash é codificado pelo nome do dispositivo USB se você quiser
obter um dispositivo do 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");
Se quiser, você também pode receber um iterador do mapa de hash e processar cada dispositivo um por um:
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 }
Receber permissão para se comunicar com um dispositivo
Antes de se comunicar com o dispositivo USB, o aplicativo precisa ter permissão dos usuários.
Observação: se o aplicativo usar um filtro de intent para descobrir dispositivos USB quando eles forem conectados, ele vai receber automaticamente a permissão se o usuário permitir que o aplicativo processe a intent. Caso contrário, você precisará solicitar permissão explicitamente no aplicativo antes de se conectar ao dispositivo.
Pedir permissão explicitamente pode ser necessário em algumas situações, como quando o aplicativo enumera dispositivos USB que já estão conectados e quer se comunicar com um deles. Você precisa verificar a permissão para acessar um dispositivo antes de tentar se comunicar com ele. Caso contrário, você vai receber um erro de tempo de execução se o usuário tiver negado a permissão de acesso ao dispositivo.
Para receber permissão explicitamente, primeiro crie um broadcast receiver. Esse receptor detecta
a intent que é transmitida quando você chama requestPermission(). A chamada para requestPermission() mostra uma caixa de diálogo ao
usuário pedindo permissão para se conectar ao dispositivo. O exemplo de código a seguir mostra como
criar o broadcast receiver:
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 o broadcast receiver, adicione o seguinte ao método onCreate() na sua
atividade:
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 exibir a caixa de diálogo que solicita aos usuários permissão para se conectar ao dispositivo, chame o método requestPermission():
Kotlin
lateinit var device: UsbDevice ... usbManager.requestPermission(device, permissionIntent)
Java
UsbDevice device; ... usbManager.requestPermission(device, permissionIntent);
Quando os usuários respondem à caixa de diálogo, o broadcast receiver recebe a intent que contém o
extra EXTRA_PERMISSION_GRANTED, que é um booleano
que representa a resposta. Verifique se esse extra tem um valor verdadeiro antes de se conectar ao
dispositivo.
Comunicar-se com um dispositivo
A comunicação com um dispositivo USB pode ser síncrona ou assíncrona. Em ambos os casos, crie uma nova linha de execução para realizar todas as transmissões de dados, de modo que você não bloqueie a
linha de execução de interface. Para configurar corretamente a comunicação com um dispositivo, você precisa receber o
UsbInterface e o UsbEndpoint adequados do
dispositivo com que você quer se comunicar e enviar solicitações nesse endpoint com um UsbDeviceConnection. Em geral, seu código precisa:
- Verifique os atributos de um objeto
UsbDevice, como ID do produto, ID do fornecedor ou classe do dispositivo, para descobrir se você quer se comunicar com o dispositivo. - Quando tiver certeza de que quer se comunicar com o dispositivo, encontre o
UsbInterfaceadequado que você quer usar para se comunicar com oUsbEndpointapropriado dessa interface. As interfaces podem ter um ou mais endpoints e, geralmente, têm um endpoint de entrada e um de saída para comunicação bidirecional. - Quando encontrar o endpoint correto, abra um
UsbDeviceConnectionnele. - fornecer os dados que você quer transmitir no endpoint com o método
bulkTransfer()oucontrolTransfer(). Realize essa etapa em outra linha de execução para evitar o bloqueio da linha de execução de interface principal. Para mais informações sobre o uso de linhas de execução no Android, consulte Processos e linhas de execução.
O snippet de código a seguir é uma maneira fácil de fazer uma transferência de dados síncrona. Seu código precisa ter mais lógica para encontrar corretamente a interface e os endpoints certos para se comunicar e também precisa transferir dados em uma linha de execução diferente da linha de execução de interface 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 dados de forma assíncrona, use a classe UsbRequest para initialize e queue uma solicitação assíncrona e aguarde o resultado
com requestWait().
Como encerrar a comunicação com um dispositivo
Quando terminar de se comunicar com um dispositivo ou se ele for desconectado, feche o UsbInterface e o UsbDeviceConnection
chamando releaseInterface() e
close(). Para detectar eventos desconectados,
crie um broadcast receiver como este:
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 } } } };
Criar o broadcast receiver no aplicativo, e não no manifesto, permite que o aplicativo processe apenas eventos desconectados enquanto estiver em execução. Dessa forma, os eventos desconectados são enviados apenas para o aplicativo em execução, e não transmitidos para todos os aplicativos.