Omówienie akcesoriów USB

Tryb akcesoriów USB umożliwia użytkownikom podłączanie sprzętu hosta USB zaprojektowanego specjalnie dla urządzeń z Androidem. Akcesoria muszą być zgodne z protokołem akcesoriów Androida opisanym w dokumentacji Android Accessory Development Kit. Dzięki temu urządzenia z Androidem, które nie mogą działać jako host USB, mogą nadal korzystać ze sprzętu USB. Gdy urządzenie z Androidem jest w trybie akcesoriów USB, podłączone akcesorium USB z Androidem działa jako host, zasila magistralę USB i wylicza połączone urządzenia. Android 3.1 (poziom interfejsu API 12) obsługuje tryb akcesoriów USB. Funkcja ta została też przeniesiona do Androida 2.3.4 (poziom interfejsu API 10), aby zapewnić obsługę szerszej gamy urządzeń.

Wybór odpowiednich interfejsów API akcesoriów USB

Chociaż interfejsy API akcesoriów USB zostały wprowadzone na platformie w Androidzie 3.1, są one również dostępne w Androidzie 2.3.4 dzięki bibliotece dodatków interfejsów API Google. Te interfejsy API zostały przeniesione wstecz przy użyciu zewnętrznej biblioteki, dlatego możesz zaimportować 2 pakiety, aby obsługiwać tryb akcesoriów USB. W zależności od tego, które urządzenia z Androidem chcesz obsługiwać, może być konieczne użycie jednego z tych rozwiązań:

  • com.android.future.usb: aby obsługiwać tryb akcesoriów USB w Androidzie 2.3.4, biblioteka dodatków interfejsów API Google zawiera przeniesione interfejsy API akcesoriów USB, które znajdują się w tej przestrzeni nazw. Android 3.1 obsługuje też importowanie i wywoływanie klas w tej przestrzeni nazw, aby obsługiwać aplikacje napisane za pomocą biblioteki dodatków. Ta biblioteka dodatków to cienka nakładka na interfejsy API akcesoriów android.hardware.usb, która nie obsługuje trybu hosta USB.

    Jeśli chcesz obsługiwać jak najszerszą gamę urządzeń, które obsługują tryb akcesoriów USB, użyj biblioteki dodatków i zaimportuj ten pakiet. Należy pamiętać, że nie wszystkie urządzenia z Androidem 2.3.4 muszą obsługiwać funkcję akcesoriów USB. Każdy producent urządzenia decyduje, czy obsługuje tę funkcję, dlatego musisz ją zadeklarować w pliku manifestu.

  • android.hardware.usb: ta przestrzeń nazw zawiera klasy obsługujące tryb akcesoriów USB w Androidzie 3.1. Ten pakiet jest częścią interfejsów API platformy, więc Android 3.1 obsługuje tryb akcesoriów USB bez użycia dodatkowej biblioteki. Użyj tego pakietu, jeśli interesują Cię tylko urządzenia z Androidem 3.1 lub nowszym, które mają sprzętową obsługę trybu akcesoriów USB, co możesz zadeklarować w pliku manifestu.

Instalowanie biblioteki dodatków interfejsów API Google

Jeśli chcesz zainstalować dodatek, możesz to zrobić, instalując pakiet interfejsów API Google Android API 10 za pomocą SDK Manager. Więcej informacji o instalowaniu biblioteki dodatku znajdziesz w artykule Instalowanie dodatku interfejsów API Google.

Przegląd interfejsów API

Biblioteka dodatków jest kodem otaczającym interfejsy API platformy, dlatego klasy obsługujące funkcję akcesoriów USB są podobne. Możesz korzystać z dokumentacji referencyjnej android.hardware.usb, nawet jeśli używasz biblioteki dodatków.

Uwaga: między biblioteką dodatku a interfejsami API platformy występuje jednak niewielka różnica w użyciu, o której warto pamiętać.

W tabeli poniżej opisano klasy, które obsługują interfejsy API akcesoriów USB:

Klasa Opis
UsbManager Umożliwia wyliczanie podłączonych akcesoriów USB i komunikowanie się z nimi.
UsbAccessory Reprezentuje akcesorium USB i zawiera metody dostępu do informacji umożliwiających jego identyfikację.

Różnice w korzystaniu z biblioteki dodatków i interfejsów API platformy

Istnieją 2 różnice między korzystaniem z biblioteki dodatków interfejsów API Google a interfejsami API platformy.

Jeśli używasz biblioteki dodatków, musisz uzyskać obiekt UsbManager w ten sposób:

Kotlin

val manager = UsbManager.getInstance(this)

Java

UsbManager manager = UsbManager.getInstance(this);

Jeśli nie używasz biblioteki dodatków, musisz uzyskać obiekt UsbManager w ten sposób:

Kotlin

val manager = getSystemService(Context.USB_SERVICE) as UsbManager

Java

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

Gdy filtrujesz połączone akcesoria za pomocą filtra intencji, obiekt UsbAccessory jest zawarty w intencji przekazywanej do aplikacji. Jeśli używasz biblioteki dodatków, musisz uzyskać obiekt UsbAccessory w ten sposób:

Kotlin

val accessory = UsbManager.getAccessory(intent)

Java

UsbAccessory accessory = UsbManager.getAccessory(intent);

Jeśli nie używasz biblioteki dodatków, musisz uzyskać obiekt UsbAccessory w ten sposób:

Kotlin

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

Java

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

Wymagania dotyczące pliku manifestu Androida

Na liście poniżej znajdziesz informacje o tym, co musisz dodać do pliku manifestu aplikacji, zanim zaczniesz korzystać z interfejsów API akcesoriów USB. Przykłady plików manifestu i zasobów pokazują, jak zadeklarować te elementy:

  • Nie wszystkie urządzenia z Androidem obsługują interfejsy API akcesoriów USB, dlatego dodaj element <uses-feature>, który deklaruje, że aplikacja korzysta z funkcji android.hardware.usb.accessory.
  • Jeśli używasz biblioteki dodatków, dodaj element <uses-library>, określając com.android.future.usb.accessory dla biblioteki.
  • Jeśli używasz biblioteki dodatków, ustaw minimalny pakiet SDK aplikacji na poziom API 10, a jeśli używasz pakietu android.hardware.usb – na poziom API 12.
  • Jeśli chcesz, aby aplikacja otrzymywała powiadomienia o podłączonym akcesorium USB, określ parę elementów <intent-filter> i <meta-data> dla intencji android.hardware.usb.action.USB_ACCESSORY_ATTACHED w głównej aktywności. Element <meta-data> wskazuje zewnętrzny plik zasobów XML, który deklaruje informacje umożliwiające identyfikację akcesorium, które chcesz wykryć.

    W pliku zasobów XML zadeklaruj elementy <usb-accessory> dla akcesoriów, które chcesz filtrować. Każdy element <usb-accessory> może mieć te atrybuty:

    • manufacturer
    • model
    • version

    Filtrowanie według: version nie jest zalecane. Akcesoria lub urządzenia nie zawsze podają ciąg wersji (celowo lub nieumyślnie). Jeśli aplikacja deklaruje atrybut wersji do filtrowania, a akcesorium lub urządzenie nie określa ciągu wersji, w starszych wersjach Androida powoduje to błąd NullPointerException. Ten problem został rozwiązany w Androidzie 12.

    Zapisz plik zasobów w katalogu res/xml/. Nazwa pliku zasobu (bez rozszerzenia .xml) musi być taka sama jak nazwa określona w elemencie <meta-data>. Format pliku zasobów XML jest również pokazany w tym przykładzie.

Przykłady plików manifestu i zasobów

Poniższy przykład pokazuje przykładowy plik manifestu i odpowiadający mu plik zasobów:

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

W tym przypadku plik zasobów powinien zostać zapisany w res/xml/accessory_filter.xml i określać, że każde akcesorium, które ma odpowiedni model, producenta i wersję, powinno zostać odfiltrowane. Akcesorium wysyła te atrybuty do urządzenia z Androidem:

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

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

Praca z akcesoriami

Gdy użytkownicy podłączają akcesoria USB do urządzenia z Androidem, system Android może określić, czy Twoja aplikacja jest zainteresowana podłączonym akcesorium. Jeśli tak, możesz skonfigurować komunikację z akcesorium. Aby to zrobić, aplikacja musi:

  1. Odkryj połączone akcesoria, używając filtra intencji, który filtruje zdarzenia podłączonych akcesoriów, lub wyliczając połączone akcesoria i znajdując odpowiednie.
  2. Poproś użytkownika o zgodę na komunikację z akcesorium, jeśli nie została jeszcze udzielona.
  3. Komunikuj się z akcesorium, odczytując i zapisując dane w odpowiednich punktach końcowych interfejsu.

Wykrywanie akcesorium

Aplikacja może wykrywać akcesoria, używając filtra intencji, aby otrzymywać powiadomienia, gdy użytkownik podłączy akcesorium, lub wyliczając akcesoria, które są już podłączone. Użycie filtra intencji jest przydatne, jeśli chcesz, aby aplikacja automatycznie wykrywała wybrane akcesorium. Wyliczanie połączonych akcesoriów jest przydatne, jeśli chcesz uzyskać listę wszystkich połączonych akcesoriów lub jeśli aplikacja nie odfiltrowała intencji.

Używanie filtra intencji

Aby aplikacja mogła wykryć konkretne akcesorium USB, możesz określić filtr intencji, który będzie filtrować intencję android.hardware.usb.action.USB_ACCESSORY_ATTACHED. Oprócz tego filtra intencji musisz określić plik zasobów, który określa właściwości akcesorium USB, takie jak producent, model i wersja.

Poniższy przykład pokazuje, jak zadeklarować filtr intencji:

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

Poniższy przykład pokazuje, jak zadeklarować odpowiedni plik zasobów, który określa akcesoria USB, które Cię interesują:

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

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

W swojej aktywności możesz uzyskać obiekt UsbAccessory, który reprezentuje podłączone akcesorium, z intencji w ten sposób (z biblioteką dodatków):

Kotlin

val accessory = UsbManager.getAccessory(intent)

Java

UsbAccessory accessory = UsbManager.getAccessory(intent);

lub w ten sposób (za pomocą interfejsów API platformy):

Kotlin

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

Java

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

Wyświetlanie listy akcesoriów

Możesz skonfigurować aplikację tak, aby wyświetlała listę akcesoriów, które zostały zidentyfikowane podczas jej działania.

Aby uzyskać tablicę wszystkich podłączonych akcesoriów USB, użyj metody getAccessoryList():

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

Uwaga: jednocześnie można używać tylko jednego połączonego akcesorium.

Uzyskiwanie uprawnień do komunikacji z akcesorium

Zanim aplikacja będzie mogła komunikować się z akcesorium USB, musi uzyskać zgodę użytkowników.

Uwaga: jeśli aplikacja używa filtra intencji do wykrywania akcesoriów po ich podłączeniu, automatycznie otrzymuje uprawnienia, jeśli użytkownik zezwoli aplikacji na obsługę intencji. Jeśli nie, przed połączeniem z akcesorium musisz poprosić o uprawnienia w aplikacji.

Wyraźne poproszenie o uprawnienia może być konieczne w niektórych sytuacjach, np. gdy aplikacja wylicza akcesoria, które są już połączone, a następnie chce się z jednym z nich połączyć. Zanim spróbujesz nawiązać połączenie z akcesorium, musisz sprawdzić, czy masz uprawnienia dostępu do niego. Jeśli tego nie zrobisz, otrzymasz błąd środowiska wykonawczego, gdy użytkownik odmówi dostępu do akcesorium.

Aby uzyskać wyraźne uprawnienia, najpierw utwórz odbiornik transmisji. Ten odbiornik nasłuchuje intencji, która jest rozsyłana, gdy wywołujesz metodę requestPermission(). Wywołanie requestPermission() wyświetla użytkownikowi okno z prośbą o przyznanie uprawnień do połączenia z akcesorium. Poniższy przykładowy kod pokazuje, jak utworzyć odbiornik komunikatów:

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

Aby zarejestrować odbiornik, umieść ten kod w metodzie onCreate() w aktywności:

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

Aby wyświetlić okno z prośbą o przyznanie uprawnień do połączenia z akcesorium, wywołaj metodę requestPermission():

Kotlin

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

Java

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

Gdy użytkownicy odpowiedzą na okno, odbiorca komunikatu otrzyma intencję zawierającą dodatkowy element EXTRA_PERMISSION_GRANTED, który jest wartością logiczną reprezentującą odpowiedź. Przed połączeniem się z akcesorium sprawdź, czy ten parametr dodatkowy ma wartość „true”.

Komunikacja z akcesorium

Możesz komunikować się z akcesorium za pomocą UsbManager, aby uzyskać deskryptor pliku, który umożliwia skonfigurowanie strumieni wejściowych i wyjściowych do odczytu i zapisu danych w deskryptorze. Strumienie reprezentują wejściowe i wyjściowe punkty końcowe akcesorium. Komunikację między urządzeniem a akcesorium należy skonfigurować w innym wątku, aby nie blokować głównego wątku UI. Ten przykład pokazuje, jak otworzyć akcesorium, aby się z nim komunikować:

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

W metodzie run() wątku możesz odczytywać i zapisywać dane na akcesorium, używając obiektów FileInputStream lub FileOutputStream. Podczas odczytywania danych z akcesorium za pomocą obiektu FileInputStream upewnij się, że używany bufor jest wystarczająco duży, aby pomieścić dane pakietu USB. Protokół akcesoriów Androida obsługuje bufor pakietów o rozmiarze do 16 384 bajtów, więc dla uproszczenia możesz zawsze deklarować bufor o takim rozmiarze.

Uwaga: na niższym poziomie pakiety mają 64 bajty w przypadku akcesoriów USB o pełnej szybkości i 512 bajtów w przypadku akcesoriów USB o wysokiej szybkości. Protokół akcesoriów Androida łączy pakiety dla obu prędkości w jeden pakiet logiczny, aby uprościć proces.

Więcej informacji o używaniu wątków na Androidzie znajdziesz w artykule Procesy i wątki.

Zakończenie komunikacji z akcesorium

Po zakończeniu komunikacji z akcesorium lub po odłączeniu akcesorium zamknij deskryptor pliku, który został otwarty przez wywołanie metody close(). Aby wykrywać zdarzenia odłączenia, utwórz odbiornik, jak poniżej:

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

Utworzenie odbiornika w aplikacji, a nie w pliku manifestu, pozwala aplikacji obsługiwać zdarzenia odłączenia tylko wtedy, gdy jest uruchomiona. Dzięki temu odłączone zdarzenia są wysyłane tylko do aktualnie uruchomionej aplikacji, a nie do wszystkich aplikacji.