Программирование USB в Android. Используем для связи интерфейс USB.

usbdroid

Опубликовано: журнал "Системный администратор" №6, 2014г. Печатается с некоторыми дополнениями.
В помощь разработчикам различных устройств автоматики с применением микроконтроллеров.

Цель данной статьи - попытка разобраться в вопросе использования интерфейса USB (Universal Serial Bus) в Android. А точнее — в том, как организовать обмен информацией между различными (в том числе и самостоятельно разработанными) электронными устройствами и аппаратами (планшетами или телефонами), работающими под управлением операционной системы (ОС) Android, с использованием USB. Для того чтобы не запутать читателя, в статье первые будут называться просто «устройствами», а вторые – «мобильными устройствами».

USB и Android

Уже сравнительно давно, начиная с Android Honeycomb (версия 3.1), в ОС от Google появилась возможность использовать мобильное устройство в режиме хоста (Host mode), в котором оно питает шину, может определять подключенные устройства и обмениваться с ними информацией с помощью прикладного программного интерфейса (API) на языке Java (см.[1] и рис.1). Устройство, работающее в хост-режиме является инициатором передачи данных и управляет процессом обмена информацией по каналу связи. USB Host API появился в Android середине 2011 года, однако информации в сети по его использованию на русском языке до сих пор очень мало. Интерес к этому вопросу подогревает наличие на рынке мобильных устройств, на которых работает этот API, стоимостью менее 3 тысяч рублей (см., например, тестирование в [2]).

USB Host и Accessory
рис.1 Иллюстрация работы Android устройства в режимах USB Host и Accessory (рисунок с сайта http://developer.android.com)

Отметим, что использование USB - не единственный способ связи с тем же самодельным устройством. Android позволяет использовать еще Bluetooth, NFC, Wi-Fi P2P, SIP, а также стандартное сетевое подключение [3]. Так что в арсенале разработчика достаточно возможностей для осуществления своих самых смелых замыслов.

Другим распространенным вариантом связи с различными устройствами до сих пор является использование переходника USB-COM. Материал в сети по применению переходника USB-COM в Android есть — см., например, [4]. Популярность такого подключения обусловлена наличием большого количества уже разработанных с использованием различных микроконтроллеров устройств, связь с которыми осуществляется с помощью COM-порта (последовательного порта), что лет 10 назад являлось почти стандартным способом передать данные от компьютера к самодельной «железке».

В сравнении с COM-портом, использование USB позволяет существенно повысить скорость передачи данных и сделать этот процесс удобным для пользователя. Cкорость передачи, которая даже в случае низкоскоростных устройств (клавиатуры, мыши, джойстики), составляет 10-1500 Кбит/c, простота и невысокая стоимость кабельной системы и подключений, самоидентификация устройств с автоматическим конфигурированием, скрытие подробностей электрического подключения от конечного пользователя (плюс возможность отключения кабеля без выключения устройств), контроль ошибок и их восстановление на уровне протокола — вот неоспоримые преимущества данной технологии (см. [5], с.12).

Вообще, говоря об использовании USB для передачи данных, нелишним будет упомянуть книгу П.Агурова «Интерфейс USB» [5]. Она, хотя часто критикуется в сети и выпущена последний раз в 2006 году, не раз помогла найти верное решение при поиске информации по различным аспектам применения этой технологии. В книге рассмотрены вопросы: от выбора микросхемы и схемотехники для контроллера до написания программы микроконтроллера и примеров программирования передачи данных по протоколу USB со стороны компьютера. Нельзя не указать и "первоисточник" данных по этому вопросу - сайт некоммерческой организации USB IF (USB Implementers Forum), занимающейся разработкой спецификаций этого интерфейса - [6 - http://www.usb.org], правда данный материал на английском языке. Однако именно там вы найдете исчерпывающие сведения об устройстве интерфейса USB. Есть неплохой перевод частей спецификации - [7]. Интересующимся программными решениями со стороны микроконтроллера также можно посмотреть ссылку [8].

Данная статья адресована прежде всего тем, у кого есть какое-либо электронное устройство (разработанное самостоятельно или кем-то еще), протокол обмена данными с которым хорошо известен (например, уже есть программа, работающая с этим устройством в Windows/Linux) и хотелось бы иметь программу, работающую с ним в Android.

Немного о классах USB-устройств

Необходимо отметить, что разработка программного обеспечения для обмена данными с конкретным устройством сильно зависит от его реализации на уровне микроконтроллера. Привести примеры программ связи для всех типов USB-устройств в рамках одной статьи, по понятным причинам, невозможно (начальные сведения о программировании различных типов устройств можно почерпнуть в [5]). Однако, мы ограничимся тем, что приведем код, реализующий поиск устройства и доступ к его контрольным точкам для обмена информацией. Также разберем отправку данных на примере одного из типов USB-устройств, а именно, класса устройств HID (human interface device — класс устройств для взаимодействия с человеком). Этот класс включает в себя «медленные» устройства, такие как клавиатура, мышь, джойстик и примеров его реализации с помощью различных микроконтроллеров в сети достаточно (есть, например, и в [8]).

Почему именно класс HID так полюбился изготовителям различных самодельных устройств? Процитируем Википедию [9]: «Помимо детальных спецификаций классических устройств ввода (типа клавиатур и мышек) стандарт HID определяет особый класс устройств без детальных спецификаций. Этот класс именуется USB HID Consumer Control и представляет собой по сути нерегламентированный канал связи с устройством. При этом устройство пользуется теми же стандартными для операционной системы драйверами что и мышка с клавиатурой. Таким образом, можно создать USB устройство которое не требует создания и инсталляции специальных драйверов в большинстве распространенных компьютерных операционных систем». Остается добавить только, что работает эта спецификация и в ОС Android (не исключая прошивок CyanogenMod).

Одним из вариантов обмена данными с HID-устройством является передача по прерываниям (interrupt transfer), которая используется в том случае, когда необходимо передать пакеты данных небольшого размера (максимальный размер пакета зависит от скорости передачи и составляет от 64 до 1024 байт) через заданный временной интервал. Пакет для передачи называется репортом (англ. - report, см. [5] с.71, 95). Такой длины репорта обычно вполне хватает для обмена информацией с самодельным устройством, 64 байта информации в одном пакете, например, - это довольно много для контроллера, ведь для передачи состояний светодиода или простейшего датчика достаточно 1 бита информации.

Необходимые инструменты

Итак, нам понадобятся — планшет или телефон с Android версии не ниже 3.1. Здесь необходимо отметить, что вышеуказанный USB Host API полностью реализован не на всех мобильных устройствах (об этом упоминается и на сайте developer.android.com, см. ссылку [1]). В некоторых планшетах/телефонах разъем USB используется только для зарядки и связи с персональным компьютером. Еще раз отправлю читателя к списку мобильных устройств, пригодных или непригодных для наших опытов (см. [2]).

Понадобится также какое-либо USB-устройство (для первых опытов будет достаточно обычного USB-флеш-накопителя), переходник OTG (On-The-Go - см. рис. 2) и/или шнур USB для связи с устройством. В Википедии по поводу OTG говорится: «При подключении через USB OTG ранг устройства (ведущий или ведомый) определяется наличием или отсутствием перемычки между контактами 4 и 5 в штекере соединительного кабеля. В USB OTG кабеле такая перемычка устанавливается лишь в одном из двух разъемов (см. [10]).» Соответственно, нам необходима такая перемычка со стороны мобильного устройства.

OTG cable
Рис.2 Различия в схеме обычного USB-кабеля и OTG-кабеля (рисунок с сайта http://tech.firstpost.com)

Такой OTG-кабель для Вашего устройства можно спаять и самостоятельно. Для этого необходимо купить в радиомагазине подходящий разъем, плюс автор, например, использовал старый кабель от переносного жесткого диска:

OTG кабель можно и спаять самому! OTG кабель можно и спаять самому!

Неплохим подспорьем в работе будет также программа USB Device Info, установленная из хранилища Google Play Market. Программа умеет определять подключенные к USB-разъему планшета/телефона устройства как с помощью Java API так и с помощью ядра Linux. То есть, если Ваше устройство не определилось с помощью Java USB Host API в USB Device Info, то, с большой вероятностью, тщетно будет использовать для этого мобильного устройства какую-либо (в том числе и свою) Android-программу, написанную с помощью Java и USB Host API.

Иногда, также, очень полезной бывает информация, выводимая командой lsusb операционной системы Linux. С ключами -v и -d lsusb выводит о USB-устройстве все, или почти все, что необходимо разработчику программного обеспечения для устройств этого класса (см. рис.3).

lsusb in terminal
Рис.3 Пример вывода команд lsusb и lsusb -v -d

Далее, необходим компьютер с установленным Android SDK и интегрированной средой разработки (IDE) Eclipse с плагином ADT (хотя можно обойтись и только SDK). Как создать и установить приложение для Android можно посмотреть, например, в [11], [12] или в сети Интернет.

Ну и, конечно, необходимо хотя бы минимальное знание языка программирования Java а также желание добиться результата, без него никак! Отмечу, что на выяснение некоторых технических вопросов применения USB в Android автором, потребовались недели кропотливого поиска информации.

Классы Java для работы с USB в Android API

Итак, как говорится на сайте разработчиков USB Host API для Android (см. [13]) — «прежде чем начать, важно понять какие классы вы будете использовать в работе». В таблице 1 приведено описание важнейших классов для работы с USB Host API (попытка перевода информации с http://developer.android.com).

Таблица 1. Описание классов для работы с USB в Android

Название класса Описание
UsbManager Allows you to enumerate and communicate with connected USB devices.
Позволяет определять подключенное USB-устройство и обмениваться с ним данными.
UsbDevice Represents a connected USB device and contains methods to access its identifying information, interfaces, and endpoints.
Представляет подключенное USB-устройство и содержит методы для доступа к его идентификационной информации, интерфейсам, и конечным точкам.
UsbInterface Represents an interface of a USB device, which defines a set of functionality for the device. A device can have one or more interfaces on which to communicate on.
Представляет «интерфейс» USB-устройства, который определяет набор функций для данного устройства. Одно устройство может иметь один или несколько интерфейсов для обмена информацией.
UsbEndpoint Represents an interface endpoint, which is a communication channel for this interface. An interface can have one or more endpoints, and usually has input and output endpoints for two-way communication with the device.
Представляет «конечную точку» интерфейса, которая и является каналом связи для этого интерфейса. Интерфейс может иметь одну и более конечных точек, и обычно имеет конечные точки для получения информации и для ее передачи.
UsbDeviceConnection Represents a connection to the device, which transfers data on endpoints. This class allows you to send data back and forth sychronously or asynchronously.
Представляет «подключение» к данному устройству. Необходимо для передачи данных в конечную точку. Этот класс позволяет получать данные или передавать синхронно или асинхронно.
UsbRequest Represents an asynchronous request to communicate with a device through a UsbDeviceConnection.
Представляет асинхронный запрос на обмен данными с устройством через UsbDeviceConnection.
UsbConstants Defines USB constants that correspond to definitions in linux/usb/ch9.h of the Linux kernel..
Определяет константы, которые соответствуют определениям в linux/usb/ch9.h ядра Linux.

Практически во всех случаях применения USB Host API программист использует эти классы в своей работе. Алгоритм их применения выглядит примерно так: определяем устройства (цель - программный доступ к классу UsbDevice), подключенные к хосту (мобильному устройству), с помощью UsbManager. Когда программный доступ устройству получен, необходимо определить соответствующие UsbInterface и UsbEndpoint для общения с ним. Как только вы получили в свое распоряжение конечную точку, откройте UsbDeviceConnection, чтобы общаться с USB-устройством. Если конечная точка работает в режиме асинхронной передачи, используем класс UsbRequest.

Дополнительная информация: Конечная точка (Endpoint) - это часть USB-устройства, имеющая уникальный идентификатор и являющаяся получателем или отправителем информации, передаваемой по шине USB. Проще говоря, это буфер, сохраняющий несколько байт. Обычно это блок памяти или регистр микроконтроллера. Данные, хранящиеся в конечной точке, могут быть либо принятыми данными, либо данными, ожидающими передачи. Хост также имеет буфер для приема и передачи данных, но хост не имеет конечных точек (см.[5] с.78)

Давайте попробуем со всем этим разобраться создав простое приложение, которое, используя этот API, определит подключенное к хосту с ОС Android устройство и выведет о нем некоторую информацию на экран телефона или планшета.

Создаем проект

В Eclipse проект создается с помощью пунктов меню File->New->Android Application Project. Заметим также, что код, приведенный ниже заимствован из приложений-примеров, поставляемых с Android SDK (папка android sdk samples/android-N(API Level)/USB) речь идет о программе управления USB-игрушкой Missile Launcher (см. рис. 4) Примеры приложений загружаются через Android SDK Manager (нужно отметить пункт - Samples for SDK [посмотреть в 11]). В листингах, приведенных ниже, примеры кода снабжены комментариями, которые объясняют суть происходяшего.

Missile Launcher
Рис.4 Забавная игрушка "Ракетозапускалка"

Создавая проект не забудьте отметить нужный API Level в опции Minimum Requared SDK (API Level 12, соответствующий версии Android 3.1 /Honeycomb/, или выше). В проекте будет очень простой интерфейс пользователя - главное окно (Activity) и TextView для вывода информации. Подобный проект подробно рассмотрен в [12].

В созданном автоматически классе для Activity нашего проекта необходимо определить следующие экземпляры классов для работы с USB:

    private TextView lgView;
    private UsbManager mUsbManager;
    private UsbDevice mDevice;
    private UsbDeviceConnection mConnection;
    private UsbEndpoint mEndpointIntr;

Далее, в обработчике onCreate() Activity создадим TextView для записи сообщений нашей программы (также не забываем указать об этом в xml-файле разметки в res/layout):

lgView = (TextView)findViewById(R.id.logTextView);

и получаем доступ к классу UsbManager

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

Создадим еще обработчик события onResume(). Добьемся цели - чтобы информация о подключенных устройствах обновлялась при активизации окна нашего приложения (см. Листинг 1).

Листинг 1. Обработчик события onResume()

public void onResume() {
    super.onResume();

    //заполняем контейнер списком устройств
    HashMap<String, UsbDevice> deviceList = mUsbManager.getDeviceList();
    Iterator<UsbDevice> deviceIterator = deviceList.values().iterator();

    lgView.setText( "Devices Count:" + deviceList.size() );

    while (deviceIterator.hasNext()) {
      UsbDevice device = (UsbDevice) deviceIterator.next();

      //пример определения ProductID устройства
      lgView.setText( lgView.getText() + "\n" + "Device ProductID: " + device.getProductId() );
    }
      //определяем намерение, описанное в фильтре
      // намерений AndroidManifest.xml
      Intent intent = getIntent();
      lgView.setText( lgView.getText() + "\n" + "intent: " + intent);
      String action = intent.getAction();

      //если устройство подключено, передаем ссылку в
      //в функцию setDevice()
      UsbDevice device = (UsbDevice)intent.getParcelableExtra(UsbManager.EXTRA_DEVICE);
      if (UsbManager.ACTION_USB_DEVICE_ATTACHED.equals(action)) {
          setDevice(device);
          lgView.setText( lgView.getText() + "\n" + "UsbManager.ACTION_USB_DEVICE_ATTACHED.equals(action) is TRUE");
      } else if (UsbManager.ACTION_USB_DEVICE_DETACHED.equals(action)) {
          if (mDevice != null && mDevice.equals(device)) {
              setDevice(null);
              lgView.setText( lgView.getText() + "\n" + "UsbManager.ACTION_USB_DEVICE_DETACHED.equals(action) is TRUE");
          }
      }

}

Далее, для Activity создадим функцию setDevice(), необходимую для работы с нашим устройством (см. Листинг 2). В обработчике onResume() и в функции setDevice() мы в точности выполнили алгоритм применения USB Host API, описанный в предыдущем разделе.

Листинг 2. Функция setDevice()

 private void setDevice(UsbDevice device) {
  lgView.setText( lgView.getText() + "\n" + "setDevice " + device);

  //определяем доступные интерфейсы устройства
  if (device.getInterfaceCount() != 1) {
 
   lgView.setText( lgView.getText() + "\n" + "could not find interface");
   return;
  }
  UsbInterface intf = device.getInterface(0);
 
  //определяем конечные точки устройства
  if (intf.getEndpointCount() == 0) {
 
    lgView.setText( lgView.getText() + "\n" +  "could not find endpoint");
    return;
  } else {
    lgView.setText( lgView.getText() + "\n" + "Endpoints Count: " + intf.getEndpointCount() );
  }
 
  UsbEndpoint epIN = null;
  UsbEndpoint epOUT = null;

  //ищем конечные точки для передачи по прерываниям
  for (int i = 0; i < intf.getEndpointCount(); i++) {
    if (intf.getEndpoint(i).getType() == UsbConstants.USB_ENDPOINT_XFER_INT) {
      if (intf.getEndpoint(i).getDirection() == UsbConstants.USB_DIR_IN) {
        epIN = intf.getEndpoint(i);
        lgView.setText( lgView.getText() + "\n" + "IN endpoint: " + intf.getEndpoint(i) );
    }
    else {
    epOUT = intf.getEndpoint(i);
    lgView.setText( lgView.getText() + "\n" + "OUT endpoint: " + intf.getEndpoint(i) );
    }
  } else { lgView.setText( lgView.getText() + "\n" + "no endpoints for INTERRUPT_TRANSFER"); }
  }
 
  mDevice = device;
  mEndpointIntr = epOUT;
 
  //открываем устройство для передачи данных
  if (device != null) {
    UsbDeviceConnection connection = mUsbManager.openDevice(device);
    if (connection != null && connection.claimInterface(intf, true)) {
   
      lgView.setText( lgView.getText() + "\n" + "open device SUCCESS!");
      mConnection = connection;

  } else {
 
      lgView.setText( lgView.getText() + "\n" + "open device FAIL!");
      mConnection = null;
  }
  }
  }
}

В дополнение к приведенному коду, который, как уже наверняка догадался внимательный читатель, открывает устройство для приема-передачи данных, остается лишь задействовать протокол обмена данными, который, повторюсь, должен быть хорошо известен разработчику. Приведем лишь, как было обещано, код, который отправит HID устройству некоторый пакет данных message используя передачу по прерываниям, класс UsbRequest и соответствующую конечную точку — см. Листинг 3.

Листинг 3. Пример кода для отправки данных устройству

//определение размера буфера для отправки
//исходя из максимального размера пакета
int bufferDataLength = mEndpointIntr.getMaxPacketSize();

lgView.setText( lgView.getText() + "\n" + mEndpointIntr.getMaxPacketSize() );

ByteBuffer buffer = ByteBuffer.allocate(bufferDataLength + 1);

UsbRequest request = new UsbRequest();

buffer.put(message);

request.initialize(mConnection, mEndpointIntr);

request.queue(buffer, bufferDataLength);

try

{

    if (request.equals(mConnection.requestWait()))

    {

        //отправка прошла успешно
        //lgView.setText( lgView.getText() + "\n" +  "sending CLEAR!!!");

    }

}

catch (Exception ex)

{

        //что-то не так...
        //lgView.setText( lgView.getText() + "\n" +  "sending not clear...");

}

Фильтрация устройств в AndroidManifest.xml

Хотя в нашем приложении нет нужды в поиске конкретного устройства с известными VID (Vendor-ID) и PID (Product-ID), инженеры Google не приводят примеров приложений без секции intent-filter в манифест файле, и автору не удалось добиться работы программы без фильтрации устройств в AndroidManifest.xml [13].

Напомню, что Vendor-ID и Product-ID это уникальные идентификаторы USB-устройств. То есть, используя фильтрацию, можно создать приложение, которое взаимодействует лишь с определенным устройством или каким-то классом устройств. Отметим, что производители устройств должны согласовать эти номера с организацией USB IF.

Приложение, манифест файл которого приведен в листинге 4, а файл с условием фильтрации в листинге 5, например, с успехом распознает подключенные к мобильному устройству USB-флеш-накопители, но не распознает клавиатуру и мыши, имеющиеся у автора. Это приложение вместе с исходным кодом можно скачать по ссылке [14].

Листинг 4. Файл AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="<a href="http://schemas.android.com/apk/res/android"
">
http://schemas.android.com/apk/res/android"
</a>    package="ru.learn2prog.usbhostexample"
    android:versionCode="1"
    android:versionName="1.0" >

    <uses-sdk
       android:minSdkVersion="12"
       android:targetSdkVersion="14" />
   
    <uses-feature android:name="android.hardware.usb.host" />

    <application
       android:allowBackup="true"
       android:icon="@drawable/ic_launcher"
       android:label="@string/app_name"
       android:theme="@style/AppTheme" >
        <activity
           android:name="ru.learn2prog.usbhostexample.MainActivity"
           android:label="@string/app_name" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
           
            <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>

Листинг 5. Файл фильтра device_filter.xml (каталог /res/xml)

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

<resources>
       <usb-device />
</resources>

Операции по сборке и установке нашего приложения ничем не отличаются от обычных (см. примеры в [11], [12]). Хочу обратить внимание на действия фильтра намерений — при подключении устройства к хосту ОС запрашивает пользователя о запуске нашего приложения.

***

Итак, в статье мы рассмотрели вопросы, связанные с поиском устройств, подключенных по интерфейсу USB к мобильному устройству, а также пример кода для обмена данными по протоколу USB между хостом и другим устройством, используя передачу по прерыванию и класс HID. Прошу искушенного читателя простить возможные неточности и ошибки в применении технических терминов спецификации USB, так как теоретические знания в наше время не всегда успевают за практической потребностью, а, как уже отмечалось, информации по этому вопросу на русском языке не так много. Напомню, статья — накопленный практический опыт автора, которым хотелось поделиться. Было бы интересно узнать как используют интерфейс USB для передачи данных другие программисты.


Литература/Ссылки:
1. http://developer.android.com/intl/ru/guide/topics/connectivity/usb/index...
2. http://www.learn2prog.ru/paracelsm список мобильных устройств, протестированных для работы с USB Host API
3. http://developer.android.com/intl/ru/guide/topics/connectivity/index.html
4. http://habrahabr.ru/post/163913/ использование переходника USB-COM для связи с устройством в Android
5. П.Агуров «Интерфейс USB» 2005г., BHV-СПб ISBN: 5-94157-202-6
6. http://www.usb.org сайт организации USB IF
7. http://www.soel.ru/issues/?id=299302 Д. Чекунов «Программисту USB устройств. Часть 1, 2, 3»
8. http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=2... USB Framework for PIC18, PIC24 & PIC32
9. http://ru.wikipedia.org/wiki/USB_HID
10. http://ru.wikipedia.org/wiki/OTG#USB_OTG Википедия, OTG-кабель
11. Программирование для Android? Это просто! Часть 2. //Системный администратор, №7-8, 2013г.
12. Программирование для Android. Изучаем ресурсы и делаем приложение в ADT. //Системный администратор №11, 2013г.
13. http://developer.android.com/guide/topics/connectivity/usb/host.html - обзор классов, необходимых для работы с USB в Android
14. http://www.learn2prog.ru/android-prog-usb ссылка на исходники приложения

Комментарии

Наткнулся на статью Е.Рахно в журнале "СОВРЕМЕННАЯ ЭЛЕКТРОНИКА" No 3 2012 "USB для начинающих", где рассмотрено использование контроллера PIC18F14K50 фирмы Microchip. Статью - в подшивку! Скачать можно прямо с сайта - https://www.soel.ru/ в поиск забить "USB". Кстати ссылка на статьи Дмитрия Чекунова - устарела, найти статьи можно также через поиск по запросу "USB".

Страницы