Android как хост USB | android

Когда устройство на базе Android работает в режиме USB host, оно становится главным устройством на шине USB, подает питание на шину, и производит энумерацию для подключенных к шине устройств USB. Режим хоста USB поддерживается в Android 3.1 и более новых версиях. Непонятные термины касательно шины USB см. в USB in a NutShell [2] (на русском языке), а непонятные термины и сокращения, касающиеся Androd, в Словарике [5].

Чтобы разобраться в режиме USB host для Android, важно понимать, с какими классами устройств USB Вам предстоит работать. В следующей таблице описаны классы USB host API в пакете android.hardware.usb.

В большинстве ситуаций Вам нужно использовать все эти классы (UsbRequest требуется только если Вы осуществляете асинхронную связь), когда происходит взаимодействие с устройством USB device. Обычно Вы задействуете UsbManager для получения доступа к нужному UsbDevice. Когда Вы получили устройство USB, то для обмена данными нужно найти подходящий интерфейс UsbInterface и конечную точку UsbEndpoint на этом интерфейсе. Как только Вы получили правильную конечную точку, откройте соединение UsbDeviceConnection для обмена данными с устройством USB.

Следующий список описывает, что Вам нужно добавить в манифест приложения перед тем, как начать работать с USB host API:

• Поскольку не все устройства на базе Android гарантированно поддерживают USB host API, включите элемент < uses-feature >, который декларирует, что Ваше приложение использует фичу android.hardware.usb.host.
• Установите минимальный уровень SDK приложение на API Level 12 или более высокий, потому что USB host API не представлены в более старых уровнях API.
• Если Вы хотите, чтобы Ваше приложение получало оповещение о подключенных к шине USB устройствах, укажите пару элементов < intent-filter > и < meta-data > для intent android.hardware.usb.action.USB_DEVICE_ATTACHED в главной активности приложения. Элемент < meta-data > указывает на внешний XML-файл ресурса, в котором указана идентификационная информация об устройстве, подключение которого нужно детектировать.

В XML-файле ресурсов продекларируйте элементы < usb-device > для устройств USB, которые хотите отфильтровать. Следующий список описывает атрибуты элемента < usb-device >. Обычно указываются идентификаторы вендора (vendor ID, VID) и продукта (product ID, PID), если хотите фильтровать специфическое устройство, и используется class, subclass и protocol, если хотите фильтровать группы (классы) устройств USB, такие как устройства хранения (mass storage devices, MSD) или цифровые камеры. Вы можете не указывать ни одного из этих атрибутов, в этом случае фильтрация подойдет под любое устройство USB, не только то, что Вам нужно. Вот имена атрибутов для устройств USB:

Сохраните XML-файл ресурсов в директории res/xml/. Имя файла ресурса (без расширения .xml) должно быть то же самое, как указано в элементе < meta-data >. Формат файла ресурса XML показан в примере ниже (пример манифеста и соответствующего ему файла ресурсов):

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

В этом случае следующий файл ресурсов будет сохранен в файл res/xml/device_filter.xml (здесь указано, что должно фильтроваться любое устройство USB с указанными параметрами):

< ?xml version="1.0" encoding="utf-8"? >
 
< resources >
    < usb-device vendor-id="1234" product-id="5678" class="255" subclass="66" protocol="1" />
< /resources >

Примечание: указанные здесь в текстовом виде значения VID (vendor-id) и PID (product-id) должны быть не в шестнадцатеричном виде, а в десятичном. Таким образом, если например у Вас VID=0x16C0, PID=0x05DF, то вы должны преобразовать эти шестнадцатеричные значения в десятичные, и их в текстовом виде указать в XML:

Если необходимо, чтобы под фильтр попадали все без исключения подключаемые устройства USB, то просто удалите из элемента usb-device его атрибуты:

[Как работать с устройствами USB, подключенными к Android]

Когда пользователи подключают устройства USB к Android, то система Android может определить интересно ли подключенное устройство USB для Вашего приложения. Если это так, то Вы можете установить обмен с устройством, если это нужно. Для этого приложение должно выполнить:

1. Определение подключенных устройств USB, используя intent фильтр для оповещения о ситуациях, когда пользователь подключает устройство USB, или путем энумерации устройств USB, которые уже подключены.
2. Запросить у пользователя разрешение на подключение к устройству USB, если оно еще не получено.
3. Далее можно осуществлять взаимодействие с устройством USB путем чтения и записи данных через соответствующие конечные точки интерфейса (interface endpoints).

[Определение наличия подключенного устройства USB]

Ваше приложение может распознать устройства USB либо с помощью использования intent-фильтра, который будет оповещать подключение пользователем устройств, либо путем энумерации устройств USB, которые уже подключены. Использование фильтра intent полезно, если Вы хотите иметь в приложении возможность автоматического детектирования (подключения) нужного устройства. Энумерация подключенных устройств USB полезна, если Вы хотите получить список всех подключенных устройств, или если Ваше приложение не делает фильтр для intent.

Чтобы приложение могло обнаружить какое-то отдельное устройство USB, Вы можете указать intent filter, чтобы фильтровать android.hardware.usb.action.USB_DEVICE_ATTACHED intent. Вместе с этим intent filter Вам нужно указать файл ресурса, который задает свойства устройства USB, такие как VID и/или PID. Когда пользователь подключает устройство, которое подходит под условие фильтра устройства, система представляет диалог, запрашивающий у пользователя, хочет ли он запустить Вашу программу. Если пользователь подтвердит запуск, то Ваше приложение автоматически будет иметь право на доступ (permission access) к устройству, пока устройство не будет отключено.

В следующем примере показано, как декларировать intent filter:

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

Следующий пример показывает, как декларировать соответствующий файл ресурса, который указывает интересующие Вас устройства USB:

< ?xml version="1.0" encoding="utf-8"? >
 
< resources >
    < usb-device vendor-id="1234" product-id="5678" />
< /resources >

В activity приложения Вы можете получить объект UsbDevice, который представляет подключенное устройство USB из intent примерно так:

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

Если Ваше приложение нуждается в инспекции всех устройств USB, уже подключенных во время работы приложения, то оно может произвести энумерацию устройств на шине USB. Используйте метод getDeviceList() для получения карты всех устройств USB (hash map), которые сейчас подключены. В списке hash map есть имена устройств USB, которые Вы можете использовать для получения доступа к устройству.

UsbManager manager = (UsbManager)getSystemService(Context.USB_SERVICE);
...  
HashMap < String, UsbDevice > deviceList = manager.getDeviceList();
UsbDevice device = deviceList.get("deviceName");

Если необходимо, Вы также можете просто получить итератор из hash map и обработать каждое устройство друг за другом:

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();
    //Ваш код
}

[Получение права на взаимодействие с устройством USB]

Перед тем, как начать обмен с устройством USB, Ваше приложение должно запросить на это разрешение от пользователя.

Примечание: если Ваше приложение использует intent filter, чтобы распознать подключенные устройства USB, то оно автоматически принимает разрешение, если пользователь разрешает разрешает Вашему приложению обработать intent. Если нет, то Вы должны в приложении явным образом запросить разрешение перед подключением к устройству.

Явный запрос на разрешение может быть необходим в некоторых ситуациях, таких как если Ваше приложение делает энумерацию уже подключенных устройств USB, и затем хочет обмениваться данными с ними. Вы должны проверить право на доступ к устройству, перед тем как сделать попытку взаимодействовать с ним. Если этого не сделать, то Вы получите runtime error (ошибка во время выполнения), когда пользователь не дал разрешения на доступ к устройству.

Чтобы явно получить разрешение, создайте сначала broadcast receiver (широковещательный приемник). Этот receiver прослушивает intent, которое получает broadcast, когда Вы вызываете requestPermission(). Вызов requestPermission() отображает диалог для пользователя с запросом разрешения на подключение к устройству USB. В следующем примере кода показано, как создать broadcast receiver:

private static final String ACTION_USB_PERMISSION =
    "com.android.example.USB_PERMISSION";
private final BroadcastReceiver mUsbReceiver = 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)
                    {
                       //Вызовите метод для установки обмена с устройством USB.
                    }
                } 
                else
                {
                    Log.d(TAG, "permission denied for device " + device);
                }
            }
        }
    }
};

Для того, чтобы зарегистрировать broadcast receiver, добавьте в метод onCreate() Вашей activity следующий код:

UsbManager mUsbManager = (UsbManager)getSystemService(Context.USB_SERVICE);
private static final String ACTION_USB_PERMISSION =
    "com.android.example.USB_PERMISSION";
...
mPermissionIntent = PendingIntent.getBroadcast(this, 0, new Intent(ACTION_USB_PERMISSION), 0);
IntentFilter filter = new IntentFilter(ACTION_USB_PERMISSION);
registerReceiver(mUsbReceiver, filter);

Чтобы отобразить диалог, запрашивающий у пользователей разрешение на подключение к устройству, вызовите метод requestPermission():

UsbDevice device;
...
mUsbManager.requestPermission(device, mPermissionIntent);

Когда пользователь ответит на этот диалог, Ваш broadcast receiver получит intent, который содержит расширение EXTRA_PERMISSION_GRANTED, представляющее суть ответа в двоичном виде. Проверьте его на значение true перед тем, как подключиться к устройству.

Обмен с устройством USB может быть либо синхронным, либо асинхронным. В любом случае Вы должны создать новый поток, который будет обрабатывать все перемещения данных, чтобы не блокировать на ожидании поток интерфейса (UI thread). Чтобы правильно установить обмен с устройством, Вам нужно получить соответствующие объекты UsbInterface и UsbEndpoint устройства, с которым Вы хотите наладить обмен, и отправлять запросы в эти конечные точки с помощью UsbDeviceConnection. В общем случае Ваш код должен делать следующее:

• Нужно проверить атрибуты объекта UsbDevice, такие как product ID (идентификатор продукта, PID), vendor ID (идентификатор производителя, VID), или класс устройства - чтобы определить, хотите ли Вы соединиться именно с этим устройством USB.

• Когда принято положительное решение на обмен с этим устройством USB, найдите подходящий UsbInterface (), который Вы хотите использовать для обмена с подходящей UsbEndpoint интерфейса (конечные точки и их привязка к интерфейсу также задана в дескрипторах USB).

Прим. переводчика: интерфейс - это некая логическая сущность, описывающая метод взаимодействия с устройством USB. И интерфейсу привязаны конечные точки - другая логическая сущность, олицетворяющая какой-то буфер данных в устройстве USB. Наличие конкретного интерфейса (он обычно в устройстве USB один, но интерфейсом может быть и несколько), его тип, привязка к интерфейсу конечных точек, тип конечных точек - все это зависит от дескрипторов устройства USB (подробнее см. [2]). Дескрипторы устройств USB автоматически считываются системой Android при энумерации и подключении устройств USB.

Интерфейсу может принадлежать одна или большее количество конечных точек (endpoint). Обычно для осуществления двунаправленного обмена имеются 2 конечные точки - одна конечная точка работает на ввод от устройства (IN endpoint), а другая на вывод в устройство (OUT endpoint).

• Когда Вы нашли корректную конечную точку, откройте UsbDeviceConnection к этой конечной точке.

• Предоставьте данные, которые Вы хотите передать в конечную точку методами bulkTransfer() или controlTransfer(). Вы должны провести эту операцию передачи данных в другом потоке, чтобы не блокировать главный поток интерфейса пользователя (main UI thread). Для дополнительной информации по использованию потоков в Android см. [3].

Следующий кусок кода показывает тривиальный способ осуществить синхронную передачу данных. Ваш реальный рабочий код должен содержать больше логики, чтобы корректно найти нужный интерфейс и конечные точки для обмена, и также должен передавать данные в отдельном потоке (чтобы не блокировать main UI thread, и чтобы приложение визуально не тормозило [4]):

private Byte[] bytes
private static int TIMEOUT = 0;
private boolean forceClaim = true;
 
...
 
UsbInterface intf = device.getInterface(0);
UsbEndpoint endpoint = intf.getEndpoint(0);
UsbDeviceConnection connection = mUsbManager.openDevice(device); 
connection.claimInterface(intf, forceClaim);
//Это действие лучше делать в другом потоке:
connection.bulkTransfer(endpoint, bytes, bytes.length, TIMEOUT);

Чтобы отправить данные асинхронно (без ожидания), используйте класс UsbRequest для инициализации очереди на асинхронном запросе, и затем ждите результата с помощью вызова requestWait().

Для дополнительной информации см. пример AdbTest, который показывает как делать асинхронные bulk передачи, и пример MissleLauncher, который показывает как асинхронно слушать interrupt endpoint.

Когда Вы завершили обмен с устройством USB, или устройство USB было отключено, закройте UsbInterface и UsbDeviceConnection вызовом releaseInterface() и close(). Чтобы прослушивать события отключения, создайте broadcast receiver примерно так:

BroadcastReceiver mUsbReceiver = 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)
            {
                //Вызовите Ваш метод, который сделает очистку и закроет обмен с устройством USB.
                ...
            }
        }
    }
};

Создание broadcast receiver в приложении, не в манифесте, позволит Вашему приложению во время выполнения обрабатывать только события отключения. С таким методом события отключения будут отправлены только приложению, которое сейчас работает, и не всем приложениям.