Panoramica degli accessori USB

La modalità accessorio USB consente agli utenti di collegare hardware host USB progettato specificamente per i dispositivi Android. Gli accessori devono rispettare il protocollo degli accessori Android descritto nella documentazione di Android Accessory Development Kit. In questo modo, i dispositivi Android che non possono fungere da host USB possono comunque interagire con l'hardware USB. Quando un dispositivo Android è in modalità accessorio USB, l'accessorio USB Android collegato funge da host, fornisce alimentazione al bus USB ed enumera i dispositivi connessi. Android 3.1 (livello API 12) supporta la modalità accessorio USB e la funzionalità è stata anche sottoposta a backporting su Android 2.3.4 (livello API 10) per consentire il supporto di una gamma più ampia di dispositivi.

Scegli le API per accessori USB giuste

Sebbene le API per accessori USB siano state introdotte nella piattaforma in Android 3.1, sono disponibili anche in Android 2.3.4 utilizzando la libreria di componenti aggiuntivi delle API di Google. Poiché è stato eseguito il backporting di queste API utilizzando una libreria esterna, esistono due pacchetti che puoi importare per supportare la modalità accessorio USB. A seconda dei dispositivi Android che vuoi supportare, potresti dover utilizzare un'opzione piuttosto che un'altra:

  • com.android.future.usb: per supportare la modalità accessorio USB in Android 2.3.4, la libreria dei componenti aggiuntivi delle API di Google include le API degli accessori USB con backport, che sono contenute in questo spazio dei nomi. Android 3.1 supporta anche l'importazione e la chiamata delle classi all'interno di questo spazio dei nomi per supportare le applicazioni scritte con la libreria del componente aggiuntivo. Questa libreria di componenti aggiuntivi è un wrapper sottile attorno alle API degli accessori android.hardware.usb e non supporta la modalità host USB.

    Se vuoi supportare la più ampia gamma di dispositivi che supportano la modalità di accessori USB, utilizza la libreria di componenti aggiuntivi e importa questo pacchetto. È importante notare che non tutti i dispositivi Android 2.3.4 devono supportare la funzionalità degli accessori USB. Ogni singolo produttore di dispositivi decide se supportare o meno questa funzionalità, motivo per cui devi dichiararla nel file manifest.

  • android.hardware.usb: questo spazio dei nomi contiene le classi che supportano la modalità accessorio USB in Android 3.1. Questo pacchetto è incluso nelle API del framework, pertanto Android 3.1 supporta la modalità accessorio USB senza l'utilizzo di una libreria aggiuntiva. Utilizza questo pacchetto se ti interessano solo i dispositivi Android 3.1 o versioni successive che dispongono del supporto hardware per la modalità accessorio USB, che puoi dichiarare nel file manifest.

Installa la libreria dei componenti aggiuntivi delle API di Google

Se vuoi installare il componente aggiuntivo, puoi farlo installando il pacchetto API 10 di Android per le API di Google con SDK Manager. Per saperne di più sull'installazione della libreria dei componenti aggiuntivi, consulta Installazione del componente aggiuntivo API di Google.

Panoramica dell'API

Poiché la libreria del componente aggiuntivo è un wrapper per le API del framework, le classi che supportano la funzionalità degli accessori USB sono simili. Puoi utilizzare la documentazione di riferimento per android.hardware.usb anche se utilizzi la libreria dei componenti aggiuntivi.

Nota: esiste tuttavia una piccola differenza di utilizzo tra la libreria dei componenti aggiuntivi e le API del framework di cui devi essere a conoscenza.

La tabella seguente descrive le classi che supportano le API per gli accessori USB:

Classe Descrizione
UsbManager Consente di enumerare e comunicare con gli accessori USB connessi.
UsbAccessory Rappresenta un accessorio USB e contiene metodi per accedere alle relative informazioni identificative.

Differenze di utilizzo tra la libreria dei componenti aggiuntivi e le API della piattaforma

Esistono due differenze di utilizzo tra la libreria di componenti aggiuntivi delle API di Google e le API della piattaforma.

Se utilizzi la libreria dei componenti aggiuntivi, devi ottenere l'oggetto UsbManager nel seguente modo:

Kotlin

val manager = UsbManager.getInstance(this)

Java

UsbManager manager = UsbManager.getInstance(this);

Se non utilizzi la libreria dei componenti aggiuntivi, devi ottenere l'oggetto UsbManager nel seguente modo:

Kotlin

val manager = getSystemService(Context.USB_SERVICE) as UsbManager

Java

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

Quando filtri un accessorio connesso con un filtro per intent, l'oggetto UsbAccessory è contenuto all'interno dell'intent passato alla tua applicazione. Se utilizzi la libreria dei componenti aggiuntivi, devi ottenere l'oggetto UsbAccessory nel seguente modo:

Kotlin

val accessory = UsbManager.getAccessory(intent)

Java

UsbAccessory accessory = UsbManager.getAccessory(intent);

Se non utilizzi la libreria dei componenti aggiuntivi, devi ottenere l'oggetto UsbAccessory nel seguente modo:

Kotlin

val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory

Java

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

Requisiti del file manifest di Android

L'elenco seguente descrive cosa devi aggiungere al file manifest dell'applicazione prima di utilizzare le API per accessori USB. Gli esempi di file manifest e di risorse mostrano come dichiarare questi elementi:

  • Poiché non è garantito che tutti i dispositivi Android supportino le API degli accessori USB, includi un elemento <uses-feature> che dichiari che la tua applicazione utilizza la funzionalità android.hardware.usb.accessory.
  • Se utilizzi la libreria dei componenti aggiuntivi, aggiungi l'elemento <uses-library> specificando com.android.future.usb.accessory per la libreria.
  • Imposta l'SDK minimo dell'applicazione sul livello API 10 se utilizzi la libreria del componente aggiuntivo o 12 se utilizzi il pacchetto android.hardware.usb.
  • Se vuoi che la tua applicazione riceva una notifica di un accessorio USB collegato, specifica una coppia di elementi <intent-filter> e <meta-data> per l'intent android.hardware.usb.action.USB_ACCESSORY_ATTACHED nella tua attività principale. L'elemento <meta-data> rimanda a un file di risorse XML esterno che dichiara le informazioni identitarie relative all'accessorio che vuoi rilevare.

    Nel file di risorse XML, dichiara gli elementi <usb-accessory> per gli accessori che vuoi filtrare. Ogni <usb-accessory> può avere i seguenti attributi:

    • manufacturer
    • model
    • version

    Il filtro in base a version non è consigliato. Un accessorio o un dispositivo potrebbe non specificare sempre una stringa di versione (intenzionalmente o meno). Quando l'app dichiara un attributo di versione in base al quale filtrare e l'accessorio o il dispositivo non specifica una stringa di versione, si verifica un NullPointerException nelle versioni precedenti di Android. Questo problema è stato risolto in Android 12.

    Salva il file di risorse nella directory res/xml/. Il nome file della risorsa (senza l'estensione .xml) deve essere lo stesso specificato nell'elemento <meta-data>. Il formato del file di risorse XML è mostrato anche nel seguente esempio.

Esempi di file manifest e di risorse

L'esempio seguente mostra un manifest di esempio e il file di risorse corrispondente:

<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 questo caso, il seguente file di risorse deve essere salvato in res/xml/accessory_filter.xml e specifica che deve essere filtrato qualsiasi accessorio con modello, produttore e versione corrispondenti. L'accessorio invia questi attributi al dispositivo Android:

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

<resources>
    <usb-accessory model="DemoKit" manufacturer="Google" version="1.0"/>
</resources>

Utilizza gli accessori

Quando gli utenti collegano accessori USB a un dispositivo Android, il sistema Android può determinare se la tua applicazione è interessata all'accessorio collegato. In questo caso, puoi configurare la comunicazione con l'accessorio, se vuoi. A questo scopo, l'applicazione deve:

  1. Rileva gli accessori collegati utilizzando un filtro per intent che filtra gli eventi di collegamento degli accessori o enumerando gli accessori collegati e trovando quello appropriato.
  2. Chiedi all'utente l'autorizzazione a comunicare con l'accessorio, se non è già stata ottenuta.
  3. Comunica con l'accessorio leggendo e scrivendo dati sugli endpoint dell'interfaccia appropriati.

Scopri un accessorio

La tua applicazione può rilevare gli accessori utilizzando un filtro per intent per ricevere una notifica quando l'utente collega un accessorio o enumerando gli accessori già collegati. L'utilizzo di un filtro per intent è utile se vuoi che la tua applicazione rilevi automaticamente un accessorio che ti interessa. L'enumerazione degli accessori connessi è utile se vuoi ottenere un elenco di tutti gli accessori connessi o se la tua applicazione non ha filtrato per un intent.

Utilizza un filtro per intent

Per fare in modo che la tua applicazione rilevi un particolare accessorio USB, puoi specificare un filtro per intent per filtrare l'intent android.hardware.usb.action.USB_ACCESSORY_ATTACHED. Insieme a questo filtro per intent, devi specificare un file di risorse che indichi le proprietà dell'accessorio USB, come produttore, modello e versione.

L'esempio seguente mostra come dichiarare il filtro per 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>

L'esempio seguente mostra come dichiarare il file di risorse corrispondente che specifica gli accessori USB che ti interessano:

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

<resources>
    <usb-accessory manufacturer="Google, Inc." model="DemoKit" version="1.0" />
</resources>

Nella tua attività, puoi ottenere l'oggetto UsbAccessory che rappresenta l'accessorio collegato dall'intent in questo modo (con la libreria di componenti aggiuntivi):

Kotlin

val accessory = UsbManager.getAccessory(intent)

Java

UsbAccessory accessory = UsbManager.getAccessory(intent);

o così (con le API della piattaforma):

Kotlin

val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory

Java

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

Enumera gli accessori

Puoi fare in modo che la tua applicazione enumeri gli accessori che si sono identificati mentre l'applicazione è in esecuzione.

Utilizza il metodo getAccessoryList() per ottenere un array di tutti gli accessori USB collegati:

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

Nota: è supportato un solo accessorio connesso alla volta.

Ottenere l'autorizzazione per comunicare con un accessorio

Prima di comunicare con l'accessorio USB, l'applicazione deve avere l'autorizzazione degli utenti.

Nota: se l'applicazione utilizza un filtro per intent per rilevare gli accessori quando vengono collegati, riceve automaticamente l'autorizzazione se l'utente consente all'applicazione di gestire l'intent. In caso contrario, devi richiedere esplicitamente l'autorizzazione nella tua applicazione prima di connetterti all'accessorio.

La richiesta esplicita dell'autorizzazione potrebbe essere necessaria in alcune situazioni, ad esempio quando l'applicazione enumera gli accessori già connessi e vuole comunicare con uno di questi. Devi verificare l'autorizzazione ad accedere a un accessorio prima di provare a comunicare con questo. In caso contrario, riceverai un errore di runtime se l'utente ha negato l'autorizzazione ad accedere all'accessorio.

Per ottenere esplicitamente l'autorizzazione, crea innanzitutto un broadcast receiver. Questo ricevitore ascolta l'intent che viene trasmesso quando chiami requestPermission(). La chiamata a requestPermission() mostra all'utente una finestra di dialogo che chiede l'autorizzazione per connettersi all'accessorio. Il seguente codice campione mostra come creare il 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);
                }
            }
        }
    }
};

Per registrare il broadcast receiver, inserisci questo codice nel metodo onCreate() della tua attività:

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

Per visualizzare la finestra di dialogo che chiede agli utenti l'autorizzazione per connettersi all'accessorio, chiama il metodo requestPermission():

Kotlin

lateinit var accessory: UsbAccessory
...
usbManager.requestPermission(accessory, permissionIntent)

Java

UsbAccessory accessory;
...
usbManager.requestPermission(accessory, permissionIntent);

Quando gli utenti rispondono alla finestra di dialogo, il tuo broadcast receiver riceve l'intent che contiene l'extra EXTRA_PERMISSION_GRANTED, ovvero un valore booleano che rappresenta la risposta. Controlla questo extra per un valore true prima di connetterti all'accessorio.

Comunicare con un accessorio

Puoi comunicare con l'accessorio utilizzando UsbManager per ottenere un descrittore del file che puoi configurare per i flussi di input e output per leggere e scrivere dati nel descrittore. Gli stream rappresentano gli endpoint collettivi di input e output dell'accessorio. Devi configurare la comunicazione tra il dispositivo e l'accessorio in un altro thread, in modo da non bloccare il thread dell'interfaccia utente principale. L'esempio seguente mostra come aprire un accessorio con cui comunicare:

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

Nel metodo run() del thread, puoi leggere e scrivere nell'accessorio utilizzando gli oggetti FileInputStream o FileOutputStream. Quando leggi i dati da un accessorio con un oggetto FileInputStream, assicurati che il buffer che utilizzi sia abbastanza grande da archiviare i dati del pacchetto USB. Il protocollo degli accessori Android supporta buffer di pacchetti fino a 16.384 byte, quindi per semplicità puoi scegliere di dichiarare sempre il buffer di queste dimensioni.

bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size that is appropriate for your speed. Use the bulk transfer size Il protocollo degli accessori Android raggruppa i pacchetti per entrambe le velocità in un unico pacchetto logico per semplicità.

Per ulteriori informazioni sull'utilizzo dei thread in Android, consulta Processi e thread.

Interrompere la comunicazione con un accessorio

Al termine della comunicazione con un accessorio o se l'accessorio è stato scollegato, chiudi il descrittore del file che hai aperto chiamando close(). Per ascoltare gli eventi di scollegamento, crea un broadcast receiver come segue:

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

La creazione del broadcast receiver all'interno dell'applicazione, e non del manifest, consente all'applicazione di gestire gli eventi di scollegamento solo mentre è in esecuzione. In questo modo, gli eventi scollegati vengono inviati solo all'applicazione attualmente in esecuzione e non vengono trasmessi a tutte le applicazioni.