O modo de acessório USB permite que os usuários conectem hardware de host USB projetado especificamente para dispositivos Android. Os acessórios precisam aderir ao protocolo de acessórios do Android descrito na documentação do Kit de desenvolvimento de acessórios do Android. Isso permite que dispositivos com tecnologia Android que não podem atuar como um host USB ainda interajam com o hardware USB. Quando um dispositivo Android está no modo de acessório USB, o acessório USB Android conectado atua como host, fornece energia ao barramento USB e enumera os dispositivos conectados. O Android 3.1 (nível 12 da API) oferece suporte ao modo de acessório USB, e o recurso também foi adaptado para o Android 2.3.4 (nível 10 da API) para oferecer suporte a uma variedade maior de dispositivos.
Escolha as APIs de acessório USB certas
Embora as APIs de acessório USB tenham sido introduzidas na plataforma no Android 3.1, elas também estão disponíveis no Android 2.3.4 usando a biblioteca de complementos das APIs do Google. Como essas APIs foram adaptadas usando uma biblioteca externa, há dois pacotes que podem ser importados para oferecer suporte ao modo de acessório USB. Dependendo dos dispositivos Android que você quer oferecer suporte, talvez seja necessário usar um em vez do outro:
com.android.future.usb: para oferecer suporte ao modo de acessório USB no Android 2.3.4, a biblioteca de complementos das APIs do Google inclui as APIs de acessório USB de backport, que estão contidas nesse namespace. O Android 3.1 também permite importar e chamar as classes nesse namespace para oferecer suporte a aplicativos escritos com a biblioteca de complementos. Essa biblioteca de complementos é um wrapper fino em torno das APIs de acessórioandroid.hardware.usbe não é compatível com o modo host USB.Se você quiser oferecer suporte à maior variedade de dispositivos que oferecem suporte ao modo de acessório USB, use a biblioteca de complementos e importe esse pacote. É importante observar que nem todos os dispositivos Android 2.3.4 precisam oferecer suporte ao recurso de acessório USB. Cada fabricante de dispositivo decide se vai oferecer suporte a esse recurso, por isso é necessário declará-lo no arquivo de manifesto.
android.hardware.usb: esse namespace contém as classes que oferecem suporte ao modo de acessório USB no Android 3.1. Esse pacote está incluído como parte das APIs do framework, portanto, o Android 3.1 oferece suporte ao modo de acessório USB sem o uso de uma biblioteca de complementos. Use esse pacote se você só se importa com dispositivos Android 3.1 ou mais recentes que têm suporte de hardware para o modo de acessório USB, que pode ser declarado no arquivo de manifesto.
Instalar a biblioteca de complementos das APIs do Google
Se você quiser instalar o complemento, instale o pacote da API 10 do Android para APIs do Google com o SDK Manager. Consulte Como instalar o complemento de APIs do Google para mais informações sobre como instalar a biblioteca de complementos.
Visão geral da API
Como a biblioteca de complementos é um wrapper para as APIs do framework, as classes que oferecem suporte ao
recurso de acessório USB são semelhantes. Você pode usar a documentação de referência do android.hardware.usb mesmo se estiver usando a biblioteca de complementos.
Observação: no entanto, há uma pequena diferença de uso entre a biblioteca de complementos e as APIs do framework que você precisa conhecer.
A tabela a seguir descreve as classes compatíveis com as APIs de acessório USB:
| Turma | Descrição |
|---|---|
UsbManager |
Permite enumerar e se comunicar com acessórios USB conectados. |
UsbAccessory |
Representa um acessório USB e contém métodos para acessar as informações de identificação dele. |
Diferenças de uso entre a biblioteca de complementos e as APIs de plataforma
Há duas diferenças de uso entre a biblioteca de complementos das APIs do Google e as APIs da plataforma.
Se você estiver usando a biblioteca de complementos, precisará recuperar o objeto UsbManager da seguinte maneira:
Kotlin
val manager = UsbManager.getInstance(this)
Java
UsbManager manager = UsbManager.getInstance(this);
Se você não estiver usando a biblioteca de complementos, precisará recuperar o objeto UsbManager da seguinte maneira:
Kotlin
val manager = getSystemService(Context.USB_SERVICE) as UsbManager
Java
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
Quando você filtra um acessório conectado com um filtro de intent, o objeto UsbAccessory é incluído na intent transmitida ao
aplicativo. Se você estiver usando a biblioteca de complementos, precisará recuperar o objeto UsbAccessory da seguinte maneira:
Kotlin
val accessory = UsbManager.getAccessory(intent)
Java
UsbAccessory accessory = UsbManager.getAccessory(intent);
Se você não estiver usando a biblioteca de complementos, precisará recuperar o objeto UsbAccessory da seguinte maneira:
Kotlin
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
Java
UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
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 acessório USB. Os exemplos de manifesto e arquivo de recurso mostram como declarar esses itens:
- Como nem todos os dispositivos Android oferecem suporte às APIs de acessórios USB,
inclua um elemento
<uses-feature>que declare que o aplicativo usa o recursoandroid.hardware.usb.accessory. - Se você estiver usando a
biblioteca de complementos,
adicione o elemento
<uses-library>especificandocom.android.future.usb.accessorypara a biblioteca. - Defina o SDK mínimo do aplicativo como o nível 10 da API se você estiver usando a biblioteca de complementos
ou 12 se estiver usando o pacote
android.hardware.usb. -
Se você quiser que o aplicativo seja notificado sobre um acessório USB conectado, especifique um par de elementos
<intent-filter>e<meta-data>para a intentandroid.hardware.usb.action.USB_ACCESSORY_ATTACHEDna atividade principal. O elemento<meta-data>aponta para um arquivo de recurso XML externo que declara informações de identificação sobre o acessório que você quer detectar.No arquivo de recurso XML, declare elementos
<usb-accessory>para os acessórios que você quer filtrar. Cada<usb-accessory>pode ter os seguintes atributos:manufacturermodelversion
Não é recomendável filtrar em
version. Um acessório ou dispositivo nem sempre especifica uma string de versão (intencionalmente ou não). Quando o app declara um atributo de versão para filtrar e o acessório ou dispositivo não especifica uma string de versão, isso causa umNullPointerExceptionem versões anteriores do Android. Esse problema foi corrigido no Android 12.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 também é 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.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>
Nesse caso, o arquivo de recurso abaixo precisa ser salvo em
res/xml/accessory_filter.xml e especifica que qualquer acessório que tenha o
modelo, o fabricante e a versão correspondentes precisa ser filtrado. O acessório envia estes
atributos ao dispositivo Android:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-accessory model="DemoKit" manufacturer="Google" version="1.0"/> </resources>
Trabalhar com acessórios
Quando os usuários conectam acessórios USB a um dispositivo Android, o sistema pode determinar se o aplicativo tem interesse no acessório conectado. Se sim, você poderá configurar a comunicação com o acessório, se quiser. Para fazer isso, seu app precisa:
- Descubra acessórios conectados usando um filtro de intent que filtra eventos de acessórios conectados ou enumerando acessórios conectados e encontrando o apropriado.
- Peça permissão ao usuário para se comunicar com o acessório, caso ainda não tenha feito isso.
- Comunique-se com o acessório lendo e gravando dados nos endpoints de interface adequados.
Descobrir um acessório
O aplicativo pode descobrir acessórios usando um filtro de intent para ser notificado quando o usuário conectar um acessório ou enumerando os acessórios que já estão conectados. Usar um filtro de intent é útil se você quiser que o aplicativo detecte automaticamente um acessório que você quer. A enumeração de acessórios conectados é útil se você quiser uma lista de todos os acessórios conectados ou se o aplicativo não tiver filtrado uma intent.
Usar um filtro de intent
Para que o aplicativo descubra um acessório USB específico, especifique um filtro de intent
para filtrar a intent android.hardware.usb.action.USB_ACCESSORY_ATTACHED. Além
desse filtro de intent, é necessário especificar um arquivo de recurso que especifique as propriedades do acessório
USB, como fabricante, modelo e versão.
O exemplo a seguir mostra como declarar o filtro de intent:
<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>
O exemplo a seguir mostra como declarar o arquivo de recurso correspondente que especifica os acessórios USB de seu interesse:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-accessory manufacturer="Google, Inc." model="DemoKit" version="1.0" /> </resources>
Na sua atividade, é possível receber o UsbAccessory que representa
o acessório conectado da intent desta forma (com a biblioteca de complementos):
Kotlin
val accessory = UsbManager.getAccessory(intent)
Java
UsbAccessory accessory = UsbManager.getAccessory(intent);
ou assim (com as APIs de plataforma):
Kotlin
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
Java
UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
Enumerar acessórios
É possível fazer com que o aplicativo enumere os acessórios que se identificaram enquanto o aplicativo está em execução.
Use o método getAccessoryList()
para receber uma matriz de todos os acessórios USB conectados:
Kotlin
val manager = getSystemService(Context.USB_SERVICE) as UsbManager val accessoryList: Array<out UsbAccessory> = manager.accessoryList
Java
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE); UsbAccessory[] accessoryList = manager.getAccessoryList();
Observação: só é possível conectar um acessório por vez.
Receber permissão para se comunicar com um acessório
Antes de se comunicar com o acessório USB, o aplicativo precisa ter permissão dos usuários.
Observação: se o aplicativo usar um filtro de intent para descobrir acessórios 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 acessório.
A solicitação explícita de permissão pode ser necessária em algumas situações, como quando o aplicativo enumera acessórios que já estão conectados e quer se comunicar com um deles. Você precisa verificar a permissão para acessar um acessório antes de tentar se comunicar com ele. Caso contrário, você vai receber um erro de tempo de execução se o usuário negar a permissão de acesso ao acessório.
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 acessório. 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 accessory: UsbAccessory? = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) if (intent.getBooleanExtra(UsbManager.EXTRA_PERMISSION_GRANTED, false)) { accessory?.apply { // call method to set up accessory communication } } else { Log.d(TAG, "permission denied for accessory $accessory") } } } } }
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) { 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); } } } } };
Para registrar o broadcast receiver, coloque o seguinte no método onCreate() da
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), 0) 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), 0); IntentFilter filter = new IntentFilter(ACTION_USB_PERMISSION); registerReceiver(usbReceiver, filter);
Para exibir a caixa de diálogo que pede permissão aos usuários para se conectar ao acessório, chame o
método requestPermission():
Kotlin
lateinit var accessory: UsbAccessory ... usbManager.requestPermission(accessory, permissionIntent)
Java
UsbAccessory accessory; ... usbManager.requestPermission(accessory, 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
acessório.
Comunicar-se com um acessório
É possível se comunicar com o acessório usando o UsbManager para
conseguir um descritor do arquivo que pode ser usado para configurar streams de entrada e saída para ler e gravar dados no
descritor. Os streams representam os endpoints em massa de entrada e saída do acessório. Configure
a comunicação entre o dispositivo e o acessório em outra linha de execução para não bloquear a
linha de execução de interface principal. O exemplo a seguir mostra como abrir um acessório para comunicação:
Kotlin
private lateinit var accessory: UsbAccessory private var fileDescriptor: ParcelFileDescriptor? = null private var inputStream: FileInputStream? = null private var outputStream: FileOutputStream? = null ... private fun openAccessory() { Log.d(TAG, "openAccessory: $mAccessory") fileDescriptor = usbManager.openAccessory(accessory) fileDescriptor?.fileDescriptor?.also { fd -> inputStream = FileInputStream(fd) outputStream = FileOutputStream(fd) val thread = Thread(null, this, "AccessoryThread") thread.start() } }
Java
UsbAccessory accessory; ParcelFileDescriptor fileDescriptor; FileInputStream inputStream; FileOutputStream outputStream; ... private void openAccessory() { Log.d(TAG, "openAccessory: " + accessory); fileDescriptor = usbManager.openAccessory(accessory); if (fileDescriptor != null) { FileDescriptor fd = fileDescriptor.getFileDescriptor(); inputStream = new FileInputStream(fd); outputStream = new FileOutputStream(fd); Thread thread = new Thread(null, this, "AccessoryThread"); thread.start(); } }
No método run() da linha de execução, é possível ler e gravar no acessório usando
os objetos FileInputStream ou FileOutputStream. Ao ler
dados de um acessório com um objeto FileInputStream, verifique se o buffer
usado é grande o suficiente para armazenar os dados do pacote USB. O protocolo de acessório do Android é compatível com
buffers de pacotes de até 16.384 bytes. Portanto, para simplificar, você pode declarar sempre o buffer com esse
tamanho.
Observação: em um nível mais baixo, os pacotes têm 64 bytes para acessórios USB de velocidade máxima e 512 bytes para acessórios USB de alta velocidade. O protocolo de acessório do Android agrupa os pacotes para as duas velocidades em um único pacote lógico para simplificar.
Para mais informações sobre o uso de linhas de execução no Android, consulte Processos e linhas de execução.
Encerrar a comunicação com um acessório
Quando terminar de se comunicar com um acessório ou se ele for desconectado, feche o
descritor do arquivo que você abriu chamando close().
Para ouvir eventos independentes, crie um broadcast receiver como abaixo:
Kotlin
var usbReceiver: BroadcastReceiver = object : BroadcastReceiver() { override fun onReceive(context: Context, intent: Intent) { if (UsbManager.ACTION_USB_ACCESSORY_DETACHED == intent.action) { val accessory: UsbAccessory? = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) accessory?.apply { // call your method that cleans up and closes communication with the accessory } } } }
Java
BroadcastReceiver usbReceiver = 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 } } } };
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.