Режим USB-аксессуара позволяет пользователям подключать USB-хост-оборудование, специально разработанное для устройств на базе Android. Аксессуары должны соответствовать протоколу Android, описанному в документации Android Accessory Development Kit. Это позволяет устройствам Android, которые не могут выступать в качестве USB-хоста, по-прежнему взаимодействовать с USB-оборудованием. Когда устройство Android находится в режиме USB-аксессуара, подключенный USB-аксессуар Android действует как хост, подает питание на шину USB и перечисляет подключенные устройства. Режим USB-аксессуара поддерживается в Android 3.1 (уровень API 12), а также в Android 2.3.4 (уровень API 10), что обеспечивает поддержку более широкого спектра устройств.
Как выбрать подходящие API для USB-аксессуаров
Хотя API USB-аксессуаров были представлены на платформе в Android 3.1, они также доступны в Android 2.3.4 при использовании дополнительной библиотеки API Google. Поскольку эти API были перенесены с помощью внешней библиотеки, для поддержки режима USB-аксессуара можно импортировать два пакета. В зависимости от того, какие устройства Android вы хотите поддерживать, вам может потребоваться использовать один из следующих вариантов:
com.android.future.usb– чтобы обеспечить поддержку режима USB-аксессуара в Android 2.3.4, в библиотеку дополнений API Google включены API USB-аксессуаров, которые содержатся в этом пространстве имен. Android 3.1 также поддерживает импорт и вызов классов в этом пространстве имен для поддержки приложений, написанных с помощью библиотеки дополнений. Эта библиотека дополнений представляет собой тонкую оболочку для API аксессуаровandroid.hardware.usbи не поддерживает режим USB-хоста.Если вы хотите поддерживать максимально широкий спектр устройств, поддерживающих режим USB-аксессуаров, используйте библиотеку дополнений и импортируйте этот пакет. Важно отметить, что не все устройства Android 2.3.4 должны поддерживать функцию USB-аксессуаров. Каждый производитель устройств решает, поддерживать ли эту возможность, поэтому вы должны объявить ее в файле манифеста.
android.hardware.usb– это пространство имен содержит классы, которые поддерживают режим USB-аксессуара в Android 3.1. Этот пакет включен в API платформы, поэтому Android 3.1 поддерживает режим USB-аксессуара без использования дополнительной библиотеки. Используйте этот пакет, если вас интересуют только устройства с Android 3.1 или более поздней версии, которые имеют аппаратную поддержку режима USB-аксессуара, которую вы можете объявить в файле манифеста.
Установите библиотеку дополнений API Google
Если вы хотите установить дополнение, вы можете сделать это, установив пакет API Google Android API 10 с помощью SDK Manager. Подробнее о том, как установить дополнение API Google…
Обзор API
Поскольку библиотека дополнений является оболочкой для API фреймворка, классы, поддерживающие функцию USB-аксессуара, похожи. Вы можете использовать справочную документацию по android.hardware.usb, даже если работаете с библиотекой дополнений.
Примечание. Однако между библиотекой дополнений и API фреймворка есть небольшая разница в использовании, о которой следует знать.
В таблице ниже описаны классы, поддерживающие API USB-аксессуаров.
| Класс | Описание |
|---|---|
UsbManager |
Позволяет перечислять подключенные USB-аксессуары и обмениваться данными с ними. |
UsbAccessory |
Представляет USB-аксессуар и содержит методы для доступа к его идентифицирующей информации. |
Различия в использовании библиотеки дополнений и API платформы
Есть два различия в использовании между библиотекой дополнений API Google и API платформы.
Если вы используете библиотеку дополнений, то должны получить объект UsbManager следующим образом:
Kotlin
val manager = UsbManager.getInstance(this)
Java
UsbManager manager = UsbManager.getInstance(this);
Если вы не используете библиотеку дополнений, то должны получить объект UsbManager следующим образом:
Kotlin
val manager = getSystemService(Context.USB_SERVICE) as UsbManager
Java
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
Если вы отфильтруете подключенные аксессуары с помощью фильтра интентов, объект UsbAccessory будет содержаться внутри интента, переданного вашему приложению. Если вы используете библиотеку дополнений, то должны получить объект UsbAccessory следующим образом:
Kotlin
val accessory = UsbManager.getAccessory(intent)
Java
UsbAccessory accessory = UsbManager.getAccessory(intent);
Если вы не используете библиотеку дополнений, то должны получить объект UsbAccessory следующим образом:
Kotlin
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
Java
UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
Требования к манифесту Android
Ниже описано, что нужно добавить в файл манифеста приложения, прежде чем начать работу с API USB-аксессуаров. В примерах манифеста и файла ресурсов показано, как объявлять эти элементы:
- Поскольку не все устройства Android поддерживают API USB-аксессуаров, добавьте элемент
<uses-feature>, который указывает, что ваше приложение использует функциюandroid.hardware.usb.accessory. - Если вы используете библиотеку дополнений, добавьте элемент
<uses-library>, указав для библиотекиcom.android.future.usb.accessory. - Установите минимальный уровень API для приложения: 10, если вы используете дополнительную библиотеку, или 12, если вы используете пакет
android.hardware.usb. -
Если вы хотите, чтобы ваше приложение получало уведомления о подключении USB-аксессуара, укажите пару элементов
<intent-filter>и<meta-data>для намеренияandroid.hardware.usb.action.USB_ACCESSORY_ATTACHEDв основном действии. Элемент<meta-data>указывает на внешний XML-файл ресурсов, в котором содержится идентифицирующая информация об аксессуаре, который вы хотите обнаружить.В XML-файле ресурсов объявите элементы
<usb-accessory>для аксессуаров, которые вы хотите отфильтровать. Каждый элемент<usb-accessory>может иметь следующие атрибуты:manufacturermodelversion
Фильтрация по параметру "
version" не рекомендуется. Строка версии может быть не указана (намеренно или нет). Если в приложении объявлен атрибут версии для фильтрации, а в аксессуаре или устройстве не указана строка версии, в более ранних версиях Android это приведет к ошибкеNullPointerException. Эта проблема устранена в Android 12.Сохраните файл ресурсов в каталоге
res/xml/. Название файла ресурса (без расширения .xml) должно совпадать с названием, указанным в элементе<meta-data>. Формат XML-файла ресурсов также показан в примере ниже.
Примеры манифестов и файлов ресурсов
Ниже приведен пример манифеста и соответствующего файла ресурсов.
<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>
В этом случае в папке res/xml/accessory_filter.xml нужно сохранить файл ресурсов, который указывает, что все аксессуары с соответствующей моделью, производителем и версией должны быть отфильтрованы. Аксессуар отправляет эти атрибуты на устройство Android:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-accessory model="DemoKit" manufacturer="Google" version="1.0"/> </resources>
Как работать с аксессуарами
Когда пользователи подключают USB-аксессуары к устройству Android, система Android может определить, заинтересовано ли ваше приложение в подключенном аксессуаре. Если да, вы можете настроить связь с аксессуаром. Для этого приложение должно:
- Обнаружение подключенных аксессуаров с помощью фильтра намерений, который фильтрует события, связанные с аксессуарами, или путем перечисления подключенных аксессуаров и поиска подходящего.
- Запросите у пользователя разрешение на обмен данными с аксессуаром, если оно ещё не получено.
- Обмениваться данными с аксессуаром, считывая и записывая их в конечных точках интерфейса.
Как найти аксессуар
Приложение может обнаруживать аксессуары, используя фильтр намерений, чтобы получать уведомления о подключении аксессуара пользователем, или перечисляя уже подключенные аксессуары. Фильтр интентов полезен, если вы хотите, чтобы приложение автоматически обнаруживало нужный аксессуар. Перечисление подключенных аксессуаров полезно, если вы хотите получить список всех подключенных аксессуаров или если ваше приложение не фильтровало намерение.
Используйте фильтр интентов
Чтобы приложение могло обнаружить определенный USB-аксессуар, можно указать фильтр интентов для фильтрации по интенту android.hardware.usb.action.USB_ACCESSORY_ATTACHED. Вместе с этим фильтром интентов необходимо указать файл ресурсов, в котором заданы свойства USB-аксессуара, такие как производитель, модель и версия.
В следующем примере показано, как объявить фильтр интентов:
<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>
В следующем примере показано, как объявить соответствующий файл ресурсов, в котором указаны интересующие вас USB-аксессуары:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-accessory manufacturer="Google, Inc." model="DemoKit" version="1.0" /> </resources>
В своем действии вы можете получить UsbAccessory, представляющий подключенный аксессуар, из намерения следующим образом (с помощью библиотеки дополнений):
Kotlin
val accessory = UsbManager.getAccessory(intent)
Java
UsbAccessory accessory = UsbManager.getAccessory(intent);
или так (с помощью API платформы):
Kotlin
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
Java
UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
Перечисление аксессуаров
Вы можете настроить приложение так, чтобы оно перечисляло аксессуары, которые идентифицировали себя во время его работы.
Чтобы получить массив всех подключенных USB-аксессуаров, используйте метод 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();
Примечание. Одновременно можно подключить только один аксессуар.
Получение разрешения на обмен данными с аксессуаром
Прежде чем взаимодействовать с USB-аксессуаром, приложение должно получить разрешение от пользователя.
Примечание. Если ваше приложение использует фильтр интентов для обнаружения подключаемых аксессуаров, оно автоматически получает разрешение, если пользователь разрешает приложению обрабатывать интент. Если нет, то перед подключением к аксессуару необходимо явно запросить разрешение в приложении.
Явный запрос разрешения может потребоваться в некоторых ситуациях, например когда приложение перечисляет уже подключенные аксессуары, а затем хочет связаться с одним из них. Прежде чем пытаться связаться с аксессуаром, необходимо проверить разрешение на доступ к нему. В противном случае, если пользователь запретит доступ к аксессуару, возникнет ошибка выполнения.
Чтобы явно получить разрешение, сначала создайте широковещательный приемник. Этот получатель прослушивает намерение, которое транслируется при вызове requestPermission(). Вызов requestPermission() показывает пользователю диалоговое окно с запросом на подключение к аксессуару. В следующем образце кода показано, как создать широковещательный приемник.
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); } } } } };
Чтобы зарегистрировать широковещательный приемник, добавьте в метод onCreate() своего класса activity следующий код:
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);
Чтобы показать диалоговое окно с запросом разрешения на подключение к аксессуару, вызовите метод requestPermission():
Kotlin
lateinit var accessory: UsbAccessory ... usbManager.requestPermission(accessory, permissionIntent)
Java
UsbAccessory accessory; ... usbManager.requestPermission(accessory, permissionIntent);
Когда пользователи отвечают на диалоговое окно, ваш широковещательный приемник получает намерение, содержащее дополнительное значение EXTRA_PERMISSION_GRANTED, которое является логическим значением, представляющим ответ. Прежде чем подключаться к аксессуару, убедитесь, что значение этого параметра – true.
Как обмениваться данными с аксессуаром
Вы можете обмениваться данными с аксессуаром, используя UsbManager, чтобы получить дескриптор файла, для которого можно настроить входные и выходные потоки для чтения и записи данных. Потоки представляют собой конечные точки ввода и вывода аксессуара. Чтобы не блокировать основной поток UI, настройте связь между устройством и аксессуаром в другом потоке. В следующем примере показано, как открыть аксессуар для связи:
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(); } }
В методе run() потока можно считывать данные с аксессуара и записывать их на него, используя объекты FileInputStream или FileOutputStream. При чтении данных из аксессуара с помощью объекта FileInputStream убедитесь, что используемый буфер достаточно велик для хранения данных USB-пакета. Протокол аксессуаров Android поддерживает буферы пакетов размером до 16 384 байт, поэтому для простоты вы можете всегда объявлять буфер такого размера.
Примечание. На более низком уровне пакеты имеют размер 64 байта для полноскоростных USB-аксессуаров и 512 байтов для высокоскоростных USB-аксессуаров. Для простоты протокол аксессуаров Android объединяет пакеты для обеих скоростей в один логический пакет.
Дополнительную информацию об использовании потоков в Android можно найти в статье Процессы и потоки.
Как прекратить обмен данными с аксессуаром
Когда вы закончите обмен данными с аксессуаром или если аксессуар был отсоединен, закройте дескриптор файла, который вы открыли, вызвав close().
Чтобы прослушивать события отсоединения, создайте широковещательный приемник, как показано ниже.
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 } } } };
Создание широковещательного приемника в приложении, а не в манифесте, позволяет приложению обрабатывать события отключения только во время работы. Таким образом, отсоединенные события отправляются только в приложение, которое в данный момент запущено, и не транслируются во все приложения.