Im USB-Zubehörmodus können Nutzer USB-Hosthardware verbinden, die speziell für Android-Geräte entwickelt wurde. Das Zubehör muss dem Android-Zubehörprotokoll entsprechen, das in der Dokumentation zum Android Accessory Development Kit beschrieben ist. So können Android-Geräte, die nicht als USB-Host fungieren können, trotzdem mit USB-Hardware interagieren. Wenn sich ein Android-Gerät im USB-Zubehörmodus befindet, fungiert das angeschlossene Android-USB-Zubehör als Host, versorgt den USB-Bus mit Strom und listet verbundene Geräte auf. Android 3.1 (API-Level 12) unterstützt den USB-Zubehörmodus. Die Funktion wurde auch auf Android 2.3.4 (API-Level 10) rückportiert, um die Unterstützung für eine größere Anzahl von Geräten zu ermöglichen.
Die richtigen USB-Zubehör-APIs auswählen
Obwohl die USB-Zubehör-APIs in Android 3.1 eingeführt wurden, sind sie auch in Android 2.3.4 über die Google APIs-Add-on-Bibliothek verfügbar. Da diese APIs mithilfe einer externen Bibliothek rückportiert wurden, gibt es zwei Pakete, die du importieren kannst, um den USB-Zubehörmodus zu unterstützen. Je nachdem, welche Android-Geräte du unterstützen möchtest, musst du möglicherweise eine der beiden Optionen bevorzugen:
com.android.future.usb: Zur Unterstützung des USB-Zubehörmodus in Android 2.3.4 enthält die Google APIs-Add-on-Bibliothek die rückportierten USB-Zubehör-APIs, die in diesem Namespace enthalten sind. Android 3.1 unterstützt auch das Importieren und Aufrufen der Klassen in diesem Namespace, um Anwendungen zu unterstützen, die mit der Add-on-Bibliothek geschrieben wurden. Diese Add-on-Bibliothek ist ein dünner Wrapper um dieandroid.hardware.usb-Zubehör-APIs und unterstützt den USB-Hostmodus nicht.Wenn du möglichst viele Geräte unterstützen möchtest, die den USB-Zubehörmodus unterstützen, verwende die Add-on-Bibliothek und importiere dieses Paket. Nicht alle Android 2.3.4-Geräte müssen die USB-Zubehörfunktion unterstützen. Jeder Gerätehersteller entscheidet selbst, ob er diese Funktion unterstützt. Daher musst du sie in deiner Manifestdatei deklarieren.
android.hardware.usb: Dieser Namespace enthält die Klassen, die den USB-Zubehörmodus in Android 3.1 unterstützen. Dieses Paket ist Teil der Framework APIs. Android 3.1 unterstützt den USB-Zubehörmodus also ohne die Verwendung einer Add-on-Bibliothek. Verwende dieses Paket, wenn du nur Geräte mit Android 3.1 oder höher hast, die Hardwareunterstützung für den USB-Zubehörmodus bieten. Dies kannst du in deiner Manifestdatei deklarieren.
Google APIs-Add-on-Bibliothek installieren
Wenn Sie das Add-on installieren möchten, können Sie das Google APIs Android API 10-Paket mit dem SDK-Manager installieren. Weitere Informationen zur Installation der Add-on-Bibliothek finden Sie unter Google APIs-Add-on installieren.
API-Übersicht
Da die Add-on-Bibliothek ein Wrapper für die Framework-APIs ist, sind die Klassen, die die USB-Zubehörfunktion unterstützen, ähnlich. Sie können die Referenzdokumentation für android.hardware.usb auch dann verwenden, wenn Sie die Add-on-Bibliothek nutzen.
Hinweis: Es gibt jedoch einen kleinen Unterschied bei der Verwendung der Add-on-Bibliothek und der Framework APIs, den Sie beachten sollten.
In der folgenden Tabelle werden die Klassen beschrieben, die die USB-Zubehör-APIs unterstützen:
| Klasse | Beschreibung |
|---|---|
UsbManager |
Ermöglicht das Aufzählen von und die Kommunikation mit verbundenem USB-Zubehör. |
UsbAccessory |
Stellt ein USB-Zubehör dar und enthält Methoden für den Zugriff auf die zugehörigen Identifikationsinformationen. |
Nutzungsunterschiede zwischen der Add-on-Bibliothek und den Plattform-APIs
Es gibt zwei Unterschiede zwischen der Verwendung der Google APIs-Add-on-Bibliothek und der Plattform-APIs.
Wenn Sie die Add-on-Bibliothek verwenden, müssen Sie das UsbManager-Objekt so abrufen:
Kotlin
val manager = UsbManager.getInstance(this)
Java
UsbManager manager = UsbManager.getInstance(this);
Wenn Sie die Add-on-Bibliothek nicht verwenden, müssen Sie das UsbManager-Objekt so abrufen:
Kotlin
val manager = getSystemService(Context.USB_SERVICE) as UsbManager
Java
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
Wenn du mit einem Intent-Filter nach einem verbundenen Zubehör filterst, ist das UsbAccessory-Objekt im Intent enthalten, der an deine Anwendung übergeben wird. Wenn Sie die Add-on-Bibliothek verwenden, müssen Sie das UsbAccessory-Objekt so abrufen:
Kotlin
val accessory = UsbManager.getAccessory(intent)
Java
UsbAccessory accessory = UsbManager.getAccessory(intent);
Wenn Sie die Add-on-Bibliothek nicht verwenden, müssen Sie das UsbAccessory-Objekt so abrufen:
Kotlin
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
Java
UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
Anforderungen an das Android-Manifest
In der folgenden Liste wird beschrieben, was Sie der Manifestdatei Ihrer Anwendung hinzufügen müssen, bevor Sie mit den USB-Zubehör-APIs arbeiten können. In den Beispielen für Manifest- und Ressourcendateien wird gezeigt, wie diese Elemente deklariert werden:
- Da nicht alle Android-Geräte die USB-Zubehör-APIs unterstützen, fügen Sie ein
<uses-feature>-Element hinzu, das deklariert, dass Ihre Anwendung dieandroid.hardware.usb.accessory-Funktion verwendet. - Wenn Sie die Add-on-Bibliothek verwenden, fügen Sie das Element
<uses-library>hinzu und geben Siecom.android.future.usb.accessoryfür die Bibliothek an. - Legen Sie das SDK-Mindestlevel der Anwendung auf API-Level 10 fest, wenn Sie die Add-on-Bibliothek verwenden, oder auf 12, wenn Sie das Paket
android.hardware.usbverwenden. -
Wenn du möchtest, dass deine Anwendung über ein angeschlossenes USB-Zubehör benachrichtigt wird, gib in deiner Hauptaktivität ein Elementpaar
<intent-filter>und<meta-data>für den Intentandroid.hardware.usb.action.USB_ACCESSORY_ATTACHEDan. Das<meta-data>-Element verweist auf eine externe XML-Ressourcendatei, die personenidentifizierbare Informationen zum Zubehör deklariert, das Sie erkennen möchten.Deklariere in der XML-Ressourcendatei
<usb-accessory>-Elemente für das Zubehör, das du filtern möchtest. Jedes<usb-accessory>kann die folgenden Attribute haben:manufacturermodelversion
Das Filtern nach
versionwird nicht empfohlen. Ein Zubehör oder Gerät gibt möglicherweise nicht immer einen Versionsstring an (absichtlich oder unabsichtlich). Wenn deine App ein Versionsattribut zum Filtern deklariert und das Zubehör oder Gerät keinen Versionsstring angibt, führt dies bei früheren Android-Versionen zu einerNullPointerException. Dieses Problem wurde in Android 12 behoben.Speichern Sie die Ressourcendatei im Verzeichnis
res/xml/. Der Name der Ressourcendatei (ohne die Erweiterung „.xml“) muss mit dem Namen übereinstimmen, den Sie im Element<meta-data>angegeben haben. Das Format für die XML-Ressourcendatei wird auch im folgenden Beispiel gezeigt.
Beispiele für Manifest- und Ressourcendateien
Das folgende Beispiel zeigt ein Beispielmanifest und die entsprechende Ressourcendatei:
<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 diesem Fall sollte die folgende Ressourcendatei in res/xml/accessory_filter.xml gespeichert werden. Sie gibt an, dass jedes Zubehör mit dem entsprechenden Modell, Hersteller und der entsprechenden Version gefiltert werden soll. Das Zubehör sendet diese Attribute an das Android-Gerät:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-accessory model="DemoKit" manufacturer="Google" version="1.0"/> </resources>
Mit Zubehör arbeiten
Wenn Nutzer USB-Zubehör mit einem Android-Gerät verbinden, kann das Android-System feststellen, ob deine Anwendung am verbundenen Zubehör interessiert ist. In diesem Fall können Sie die Kommunikation mit dem Zubehör einrichten, wenn Sie möchten. Dazu muss Ihre Anwendung Folgendes tun:
- Verbundene Zubehörgeräte können Sie mithilfe eines Intent-Filters finden, der nach Ereignissen für angeschlossene Zubehörgeräte filtert, oder indem Sie verbundene Zubehörgeräte auflisten und das entsprechende Gerät suchen.
- Bitte den Nutzer um Erlaubnis, mit dem Zubehör zu kommunizieren, falls du diese noch nicht hast.
- Kommuniziere mit dem Zubehör, indem du Daten an den entsprechenden Schnittstellenendpunkten liest und schreibst.
Zubehör entdecken
Deine Anwendung kann Zubehör entweder über einen Intent-Filter erkennen, um benachrichtigt zu werden, wenn der Nutzer ein Zubehör verbindet, oder indem sie bereits verbundenes Zubehör auflistet. Die Verwendung eines Intent-Filters ist nützlich, wenn du möchtest, dass deine Anwendung ein gewünschtes Zubehör automatisch erkennt. Das Aufzählen verbundener Zubehörteile ist nützlich, wenn du eine Liste aller verbundenen Zubehörteile abrufen möchtest oder wenn deine Anwendung nicht nach einem Intent gefiltert hat.
Intent-Filter verwenden
Damit deine Anwendung ein bestimmtes USB-Zubehör erkennt, kannst du einen Intent-Filter angeben, um nach dem Intent android.hardware.usb.action.USB_ACCESSORY_ATTACHED zu filtern. Zusammen mit diesem Intent-Filter musst du eine Ressourcendatei angeben, die Attribute des USB-Zubehörs wie Hersteller, Modell und Version enthält.
Das folgende Beispiel zeigt, wie der Intent-Filter deklariert wird:
<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>
Im folgenden Beispiel wird gezeigt, wie die entsprechende Ressourcendatei deklariert wird, in der das gewünschte USB-Zubehör angegeben ist:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-accessory manufacturer="Google, Inc." model="DemoKit" version="1.0" /> </resources>
In deiner Aktivität kannst du das UsbAccessory, das das angeschlossene Zubehör darstellt, so aus dem Intent abrufen (mit der Add-on-Bibliothek):
Kotlin
val accessory = UsbManager.getAccessory(intent)
Java
UsbAccessory accessory = UsbManager.getAccessory(intent);
oder so (mit den Plattform-APIs):
Kotlin
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
Java
UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
Zubehör aufzählen
Sie können Ihre Anwendung so konfigurieren, dass sie Zubehör auflistet, das sich während der Ausführung Ihrer Anwendung identifiziert hat.
Verwenden Sie die Methode getAccessoryList(), um ein Array aller verbundenen USB-Zubehörteile abzurufen:
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();
Hinweis: Es wird jeweils nur ein verbundenes Zubehör unterstützt.
Berechtigung zur Kommunikation mit einem Zubehörteil einholen
Bevor deine Anwendung mit dem USB-Zubehör kommunizieren kann, muss sie die Berechtigung von deinen Nutzern erhalten.
Hinweis: Wenn deine Anwendung einen Intent-Filter verwendet, um Zubehör zu erkennen, wenn es verbunden wird, erhält sie automatisch die Berechtigung, wenn der Nutzer deiner Anwendung erlaubt, den Intent zu verarbeiten. Wenn nicht, müssen Sie die Berechtigung explizit in Ihrer Anwendung anfordern, bevor Sie eine Verbindung zum Zubehör herstellen.
In einigen Situationen kann es erforderlich sein, explizit um Erlaubnis zu bitten, z. B. wenn deine Anwendung bereits verbundene Zubehörteile auflistet und dann mit einem davon kommunizieren möchte. Du musst prüfen, ob du die Berechtigung hast, auf ein Zubehör zuzugreifen, bevor du versuchst, mit ihm zu kommunizieren. Andernfalls erhalten Sie einen Laufzeitfehler, wenn der Nutzer die Berechtigung für den Zugriff auf das Zubehör verweigert hat.
Wenn Sie die Berechtigung explizit einholen möchten, erstellen Sie zuerst einen Übertragungsempfänger. Dieser Empfänger wartet auf den Intent, der gesendet wird, wenn du requestPermission() aufrufst. Durch den Aufruf von requestPermission() wird dem Nutzer ein Dialogfeld angezeigt, in dem er um Erlaubnis gebeten wird, eine Verbindung zum Zubehör herzustellen. Im folgenden Beispielcode wird gezeigt, wie der Übertragungsempfänger erstellt wird:
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); } } } } };
Fügen Sie Folgendes in die Methode onCreate() Ihrer Aktivität ein, um den Übertragungsempfänger zu registrieren:
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);
Wenn du das Dialogfeld anzeigen möchtest, in dem Nutzer um Erlaubnis gebeten werden, eine Verbindung zum Zubehör herzustellen, rufe die Methode requestPermission() auf:
Kotlin
lateinit var accessory: UsbAccessory ... usbManager.requestPermission(accessory, permissionIntent)
Java
UsbAccessory accessory; ... usbManager.requestPermission(accessory, permissionIntent);
Wenn Nutzer auf das Dialogfeld antworten, empfängt dein Übertragungsempfänger den Intent, der das Extra EXTRA_PERMISSION_GRANTED enthält. Das ist ein boolescher Wert, der die Antwort darstellt. Prüfe, ob dieser Extra den Wert „true“ hat, bevor du eine Verbindung zum Zubehör herstellst.
Mit einem Zubehör kommunizieren
Du kannst mit dem Zubehör kommunizieren, indem du mit dem UsbManager einen Dateideskriptor abrufst, für den du Eingabe- und Ausgabestreams einrichten kannst, um Daten in den Deskriptor zu schreiben und daraus zu lesen. Die Streams stellen die Bulk-Endpunkte für die Ein- und Ausgabe des Zubehörs dar. Du solltest die Kommunikation zwischen dem Gerät und dem Zubehör in einem anderen Thread einrichten, damit der Haupt-UI-Thread nicht gesperrt wird. Das folgende Beispiel zeigt, wie Sie ein Zubehör öffnen, um mit ihm zu kommunizieren:
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(); } }
In der run()-Methode des Threads kannst du mit den FileInputStream- oder FileOutputStream-Objekten Daten vom Zubehör lesen und darauf schreiben. Wenn du Daten von einem Zubehör mit einem FileInputStream-Objekt liest, muss der verwendete Zwischenspeicher groß genug sein, um die USB-Paketdaten zu speichern. Das Android-Zubehörprotokoll unterstützt Paketpuffer mit bis zu 16.384 Byte. Du kannst also der Einfachheit halber festlegen, dass dein Puffer immer diese Größe hat.
Hinweis: Auf einer niedrigeren Ebene sind die Pakete für USB-Full-Speed-Zubehör 64 Byte und für USB-High-Speed-Zubehör 512 Byte groß. Das Android-Zubehörprotokoll bündelt die Pakete für beide Geschwindigkeiten der Einfachheit halber in einem logischen Paket.
Weitere Informationen zur Verwendung von Threads in Android findest du unter Prozesse und Threads.
Kommunikation mit einem Zubehör beenden
Wenn du die Kommunikation mit einem Zubehör beendet hast oder das Zubehör getrennt wurde, schließe den Dateideskriptor, den du durch Aufrufen von close() geöffnet hast.
Wenn du auf „detached“-Ereignisse warten möchtest, erstelle einen Übertragungsempfänger wie unten:
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 } } } };
Wenn du den Übertragungsempfänger in der Anwendung und nicht im Manifest erstellst, kann deine Anwendung nur dann getrennte Ereignisse verarbeiten, wenn sie ausgeführt wird. So werden losgelöste Ereignisse nur an die aktuell ausgeführte Anwendung gesendet und nicht an alle Anwendungen übertragen.