USB-Host – Übersicht

Wenn sich dein Android-Gerät im USB-Hostmodus befindet, fungiert es als USB-Host, versorgt den Bus mit Strom und listet verbundene USB-Geräte auf. Der USB-Hostmodus wird ab Android 3.1 unterstützt.

API-Übersicht

Bevor Sie beginnen, sollten Sie sich mit den Klassen vertraut machen, mit denen Sie arbeiten müssen. In der folgenden Tabelle werden die USB-Host-APIs im Paket android.hardware.usb beschrieben.

Tabelle 1. USB-Host-APIs

Klasse Beschreibung
UsbManager Ermöglicht das Aufzählen von und die Kommunikation mit verbundenen USB-Geräten.
UsbDevice Stellt ein verbundenes USB-Gerät dar und enthält Methoden für den Zugriff auf seine identifizierenden Informationen, Schnittstellen und Endpunkte.
UsbInterface Stellt eine Schnittstelle eines USB-Geräts dar, die eine Reihe von Funktionen für das Gerät definiert. Ein Gerät kann eine oder mehrere Schnittstellen für die Kommunikation haben.
UsbEndpoint Stellt einen Schnittstellenendpunkt dar, der ein Kommunikationskanal für diese Schnittstelle ist. Eine Schnittstelle kann einen oder mehrere Endpunkte haben und hat in der Regel Eingabe- und Ausgabeendpunkte für die bidirektionale Kommunikation mit dem Gerät.
UsbDeviceConnection Stellt eine Verbindung zum Gerät dar, über die Daten an Endpunkte übertragen werden. Mit dieser Klasse können Sie Daten synchron oder asynchron senden und empfangen.
UsbRequest Stellt eine asynchrone Anfrage zur Kommunikation mit einem Gerät über ein UsbDeviceConnection dar.
UsbConstants Definiert USB-Konstanten, die den Definitionen in linux/usb/ch9.h des Linux-Kernels entsprechen.

In den meisten Fällen müssen Sie alle diese Klassen verwenden (UsbRequest ist nur für die asynchrone Kommunikation erforderlich), wenn Sie mit einem USB-Gerät kommunizieren. Im Allgemeinen rufen Sie einen UsbManager ab, um die gewünschte UsbDevice zu erhalten. Wenn Sie das Gerät haben, müssen Sie die entsprechende UsbInterface und die UsbEndpoint dieser Schnittstelle finden, um darüber zu kommunizieren. Sobald Sie den richtigen Endpunkt haben, öffnen Sie eine UsbDeviceConnection, um mit dem USB-Gerät zu kommunizieren.

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-Host-APIs arbeiten können:

  • Da nicht alle Android-Geräte die USB-Host-APIs unterstützen, sollten Sie ein <uses-feature>-Element einfügen, das deklariert, dass Ihre Anwendung die android.hardware.usb.host-Funktion verwendet.
  • Legen Sie das SDK-Mindestlevel der Anwendung auf API-Level 12 oder höher fest. Die USB-Host-APIs sind auf früheren API-Levels nicht vorhanden.
  • Wenn du möchtest, dass deine Anwendung über ein angeschlossenes USB-Gerät benachrichtigt wird, gib in deiner Hauptaktivität ein Elementpaar <intent-filter> und <meta-data> für den Intent android.hardware.usb.action.USB_DEVICE_ATTACHED an. Das Element <meta-data> verweist auf eine externe XML-Ressourcendatei, die personenidentifizierbare Informationen zu dem Gerät deklariert, das Sie erkennen möchten.

    Deklariere in der XML-Ressourcendatei <usb-device>-Elemente für die USB-Geräte, die du filtern möchtest. In der folgenden Liste werden die Attribute von <usb-device> beschrieben. Im Allgemeinen sollten Sie die Anbieter- und Produkt-ID verwenden, wenn Sie nach einem bestimmten Gerät filtern möchten, und die Klasse, Unterklasse und das Protokoll, wenn Sie nach einer Gruppe von USB-Geräten filtern möchten, z. B. Massenspeichergeräte oder Digitalkameras. Sie können keines oder alle dieser Attribute angeben. Wenn Sie keine Attribute angeben, werden alle USB-Geräte berücksichtigt. Tun Sie dies also nur, wenn es für Ihre Anwendung erforderlich ist:

    • vendor-id
    • product-id
    • class
    • subclass
    • protocol (Gerät oder Schnittstelle)

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

In diesem Fall sollte die folgende Ressourcendatei in res/xml/device_filter.xml gespeichert werden. Sie gibt an, dass alle USB-Geräte mit den angegebenen Attributen gefiltert werden sollen:

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

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

Mit Geräten arbeiten

Wenn Nutzer USB-Geräte mit einem Android-Gerät verbinden, kann das Android-System feststellen, ob deine Anwendung am verbundenen Gerät interessiert ist. Falls ja, kannst du die Kommunikation mit dem Gerät einrichten, wenn du möchtest. Dazu muss Ihre Anwendung Folgendes tun:

  1. Verbundene USB-Geräte können mithilfe eines Intent-Filters erkannt werden, um benachrichtigt zu werden, wenn der Nutzer ein USB-Gerät anschließt, oder indem bereits verbundene USB-Geräte aufgelistet werden.
  2. Den Nutzer um Erlaubnis bitten, eine Verbindung zum USB-Gerät herzustellen, falls diese noch nicht erteilt wurde.
  3. Kommuniziere mit dem USB-Gerät, indem du Daten an den entsprechenden Schnittstellenendpunkten liest und schreibst.

Gerät erkennen

Deine Anwendung kann USB-Geräte entweder mithilfe eines Intent-Filters erkennen, um benachrichtigt zu werden, wenn der Nutzer ein Gerät verbindet, oder indem sie bereits verbundene USB-Geräte auflistet. Ein Intent-Filter ist nützlich, wenn du möchtest, dass deine Anwendung ein gewünschtes Gerät automatisch erkennt. Das Auflisten verbundener USB-Geräte ist nützlich, wenn du eine Liste aller verbundenen Geräte abrufen möchtest oder wenn deine Anwendung nicht nach einem Intent gefiltert hat.

Intent-Filter verwenden

Damit deine Anwendung ein bestimmtes USB-Gerät erkennt, kannst du einen Intent-Filter angeben, um nach dem Intent android.hardware.usb.action.USB_DEVICE_ATTACHED zu filtern. Zusammen mit diesem Intent-Filter musst du eine Ressourcendatei angeben, die Attribute des USB-Geräts enthält, z. B. die Produkt- und Hersteller-ID. Wenn Nutzer ein Gerät verbinden, das mit deinem Gerätefilter übereinstimmt, wird ihnen ein Dialogfeld angezeigt, in dem sie gefragt werden, ob sie deine Anwendung starten möchten. Wenn Nutzer zustimmen, hat deine Anwendung automatisch die Berechtigung, auf das Gerät zuzugreifen, bis die Verbindung zum Gerät getrennt wird.

Das folgende Beispiel zeigt, wie der Intent-Filter deklariert wird:

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

Im folgenden Beispiel wird gezeigt, wie Sie die entsprechende Ressourcendatei deklarieren, in der die gewünschten USB-Geräte angegeben sind:

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

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

In Ihrer Aktivität können Sie das UsbDevice, das das verbundene Gerät darstellt, so aus dem Intent abrufen:

Kotlin

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

Java

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

Geräte auflisten

Wenn deine Anwendung alle derzeit verbundenen USB-Geräte prüfen soll, während sie ausgeführt wird, kann sie Geräte auf dem Bus aufzählen. Verwende die Methode getDeviceList(), um eine Hash-Map aller verbundenen USB-Geräte abzurufen. Die Hash-Map wird nach dem Namen des USB-Geräts verschlüsselt, wenn du ein Gerät aus der Map abrufen möchtest.

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

Wenn Sie möchten, können Sie auch einfach einen Iterator aus der Hash-Map abrufen und jedes Gerät einzeln verarbeiten:

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
}

Berechtigung zur Kommunikation mit einem Gerät einholen

Bevor deine Anwendung mit dem USB-Gerät kommunizieren kann, muss sie die Berechtigung von deinen Nutzern erhalten.

Hinweis: Wenn deine Anwendung einen Intent-Filter verwendet, um USB-Geräte zu erkennen, wenn sie verbunden werden, 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 Gerät herstellen.

In einigen Situationen kann es erforderlich sein, explizit um Erlaubnis zu bitten, z. B. wenn deine Anwendung bereits verbundene USB-Geräte auflistet und dann mit einem davon kommunizieren möchte. Sie müssen prüfen, ob Sie die Berechtigung für den Zugriff auf ein Gerät haben, bevor Sie versuchen, mit ihm zu kommunizieren. Andernfalls wird ein Laufzeitfehler ausgegeben, wenn der Nutzer die Berechtigung für den Zugriff auf das Gerät 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 ein Dialogfeld angezeigt, in dem der Nutzer aufgefordert wird, die Berechtigung zum Herstellen einer Verbindung zum Gerät zu erteilen. 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 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);
                }
            }
        }
    }
};

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

Wenn du das Dialogfeld anzeigen möchtest, in dem Nutzer um Erlaubnis gebeten werden, eine Verbindung zum Gerät herzustellen, rufe die Methode requestPermission() auf:

Kotlin

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

Java

UsbDevice device;
...
usbManager.requestPermission(device, 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-Wert „true“ ist, bevor du eine Verbindung zum Gerät herstellst.

Mit einem Gerät kommunizieren

Die Kommunikation mit einem USB-Gerät kann entweder synchron oder asynchron sein. In beiden Fällen solltest du einen neuen Thread erstellen, in dem alle Datenübertragungen ausgeführt werden, damit der UI-Thread nicht blockiert wird. Damit die Kommunikation mit einem Gerät richtig eingerichtet werden kann, musst du die entsprechende UsbInterface und UsbEndpoint des Geräts abrufen, mit dem du kommunizieren möchtest, und Anfragen an diesen Endpunkt mit einem UsbDeviceConnection senden. Im Allgemeinen sollte Ihr Code Folgendes tun:

  • Prüfe die Attribute eines UsbDevice-Objekts, z. B. die Produkt-ID, die Anbieter-ID oder die Geräteklasse, um festzustellen, ob du mit dem Gerät kommunizieren möchtest.
  • Wenn Sie sicher sind, dass Sie mit dem Gerät kommunizieren möchten, suchen Sie die entsprechende UsbInterface, die Sie für die Kommunikation verwenden möchten, sowie die entsprechende UsbEndpoint dieser Schnittstelle. Schnittstellen können einen oder mehrere Endpunkte haben und haben in der Regel einen Eingabe- und einen Ausgabeendpunkt für die bidirektionale Kommunikation.
  • Wenn Sie den richtigen Endpunkt gefunden haben, öffnen Sie einen UsbDeviceConnection für diesen Endpunkt.
  • Stellen Sie die Daten, die Sie an den Endpunkt übertragen möchten, mit der Methode bulkTransfer() oder controlTransfer() bereit. Du solltest diesen Schritt in einem anderen Thread ausführen, um zu verhindern, dass der Haupt-UI-Thread blockiert wird. Weitere Informationen zur Verwendung von Threads in Android finden Sie unter Prozesse und Threads.

Das folgende Code-Snippet zeigt eine einfache Möglichkeit, eine synchrone Datenübertragung durchzuführen. Dein Code sollte mehr Logik enthalten, um die richtige Schnittstelle und die richtigen Endpunkte für die Kommunikation zu finden. Außerdem sollte die Datenübertragung in einem anderen Thread als dem Haupt-UI-Thread erfolgen:

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

Wenn Sie Daten asynchron senden möchten, verwenden Sie die Klasse UsbRequest, um eine asynchrone Anfrage zu initialize und zu queue. Warten Sie dann mit requestWait() auf das Ergebnis.

Kommunikation mit einem Gerät beenden

Wenn du die Kommunikation mit einem Gerät beendet hast oder das Gerät getrennt wurde, schließe UsbInterface und UsbDeviceConnection, indem du releaseInterface() und close() aufrufst. Wenn du auf Ereignisse vom Typ „detached“ 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_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
            }
        }
    }
};

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.