USB ホストの概要

Android 搭載デバイスを USB ホストモードにすると、デバイスが USB ホストとして動作し、バスに電源を供給して、接続された USB デバイスを列挙します。USB ホストモードは Android 3.1 以降でサポートされています。

API の概要

まず、使用する必要のあるクラスを理解することが重要です。次の表に、android.hardware.usb パッケージの USB ホスト API を示します。

表 1. USB ホスト API

クラス 説明
UsbManager 接続されている USB デバイスを列挙して通信できるようにします。
UsbDevice 接続された USB デバイスを表し、その識別情報、インターフェース、エンドポイントにアクセスするためのメソッドが含まれています。
UsbInterface USB デバイスのインターフェースを表します。デバイスの一連の機能を定義します。デバイスは、通信するインターフェースを 1 つ以上持つことができます。
UsbEndpoint このインターフェースの通信チャネルである、インターフェースのエンドポイントを表します。インターフェースには 1 つ以上のエンドポイントがあり、通常はデバイスとの双方向通信用の入力エンドポイントと出力エンドポイントがあります。
UsbDeviceConnection エンドポイントのデータを転送する、デバイスへの接続を表します。このクラスを使用すると、データを同期または非同期で送受信できます。
UsbRequest UsbDeviceConnection を通じてデバイスと通信する非同期リクエストを表します。
UsbConstants Linux カーネルの linux/usb/ch9.h の定義に対応する USB 定数を定義します。

ほとんどの場合、USB デバイスと通信するときは、これらのクラスをすべて使用する必要があります(UsbRequest は、非同期通信を行う場合にのみ必要です)。一般に、UsbManager を取得して、必要な UsbDevice を取得します。デバイスを取得したら、通信する適切な UsbInterface とそのインターフェースの UsbEndpoint を見つける必要があります。正しいエンドポイントを取得したら、UsbDeviceConnection を開いて USB デバイスと通信します。

Android マニフェストの要件

USB ホスト API を使用する前に、アプリのマニフェスト ファイルに追加する必要があるものを以下に示します。

  • すべての Android 搭載デバイスが USB ホスト API をサポートしているとは限らないため、アプリが android.hardware.usb.host 機能を使用することを宣言する <uses-feature> 要素を記述します。
  • アプリの最小 SDK を API レベル 12 以上に設定します。USB ホスト API は、以前の API レベルには存在しません。
  • USB デバイスが接続されたときにアプリに通知されるようにするには、メイン アクティビティの android.hardware.usb.action.USB_DEVICE_ATTACHED インテントに <intent-filter> 要素と <meta-data> 要素のペアを指定します。<meta-data> 要素は、検出するデバイスに関する識別情報を宣言する外部 XML リソース ファイルを指します。

    XML リソース ファイルで、フィルタする USB デバイスの <usb-device> 要素を宣言します。次のリストに、<usb-device> の属性を示します。一般に、特定のデバイスをフィルタする場合はベンダー ID とプロダクト ID を使用し、USB デバイスのグループ(大容量ストレージ デバイスやデジタルカメラなど)をフィルタする場合はクラス、サブクラス、プロトコルを使用します。これらの属性は、すべて指定することも、まったく指定しないこともできます。属性を指定しないと、すべての USB デバイスと一致します。アプリで必要な場合にのみ、この操作を行ってください。

    • vendor-id
    • product-id
    • class
    • subclass
    • protocol(デバイスまたはインターフェース)

    リソース ファイルを 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>

デバイスと連携する

ユーザーが USB デバイスを Android 搭載デバイスに接続すると、Android システムは、接続されたデバイスがアプリにとって関心のあるものかどうかを判断できます。サポートしている場合は、必要に応じてデバイスとの通信をセットアップできます。そのためには、アプリで次の処理を行う必要があります。

  1. 接続されている USB デバイスを検出するには、インテント フィルタを使用して、ユーザーが USB デバイスを接続したときに通知を受け取るか、すでに接続されている USB デバイスを列挙します。
  2. USB デバイスへの接続を許可するようユーザーに求めます(まだ許可を取得していない場合)。
  3. 適切なインターフェース エンドポイントでデータを読み書きして、USB デバイスと通信します。

デバイスを検出する

アプリは、インテント フィルタを使用してユーザーがデバイスを接続したときに通知を受け取るか、すでに接続されている USB デバイスを列挙することで、USB デバイスを検出できます。インテント フィルタを使用すると、アプリケーションで目的のデバイスを自動的に検出できます。接続されている USB デバイスを列挙する方法は、接続されているすべてのデバイスのリストを取得する場合や、アプリケーションでインテントをフィルタしなかった場合に便利です。

インテント フィルタを使用する

アプリで特定の USB デバイスを検出するには、android.hardware.usb.action.USB_DEVICE_ATTACHED インテントをフィルタするインテント フィルタを指定します。このインテント フィルタとともに、USB デバイスのプロパティ(製品 ID やベンダー ID など)を指定するリソース ファイルを指定する必要があります。ユーザーがデバイス フィルタに一致するデバイスを接続すると、アプリケーションを起動するかどうかを尋ねるダイアログが表示されます。ユーザーが許可すると、アプリはデバイスが接続解除されるまで、デバイスにアクセスする権限を自動的に取得します。

インテント フィルタを宣言する方法の例を次に示します。

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

アクティビティでは、次のようにインテントから、接続されたデバイスを表す UsbDevice を取得できます。

Kotlin

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

Java

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

デバイスを列挙する

アプリの実行中に、現在接続されているすべての USB デバイスを検査する場合は、バス上のデバイスを列挙できます。getDeviceList() メソッドを使用して、接続されているすべての USB デバイスのハッシュマップを取得します。マップからデバイスを取得する場合は、USB デバイスの名前をキーとしてハッシュマップを使用します。

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

必要に応じて、ハッシュマップからイテレータを取得し、各デバイスを 1 つずつ処理することもできます。

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
}

デバイスとの通信の権限を取得する

USB デバイスと通信する前に、アプリはユーザーから権限を取得する必要があります。

注: アプリがインテント フィルタを使用して、接続されている USB デバイスを検出する場合、ユーザーがアプリにインテントの処理を許可すると、アプリは自動的に権限を受け取ります。そうでない場合は、デバイスに接続する前に、アプリケーションで明示的に権限をリクエストする必要があります。

明示的に権限をリクエストする必要があるのは、たとえば、アプリがすでに接続されている USB デバイスを列挙し、そのうちの 1 つと通信する場合などです。デバイスと通信する前に、デバイスへのアクセス権限があるかを確認する必要があります。そうしないと、ユーザーがデバイスへのアクセス許可を拒否した場合に、ランタイム エラーが発生します。

明示的に権限を取得するには、まずブロードキャスト レシーバを作成します。このレシーバは、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 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);
                }
            }
        }
    }
};

ブロードキャスト レシーバを登録するには、アクティビティの onCreate() メソッドに以下を追加します。

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

ユーザーにデバイスへの接続の権限を求めるダイアログを表示するには、次のように requestPermission() メソッドを呼び出します。

Kotlin

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

Java

UsbDevice device;
...
usbManager.requestPermission(device, permissionIntent);

ユーザーがダイアログに返信すると、ブロードキャスト レシーバは、回答を表すブール値である EXTRA_PERMISSION_GRANTED エクストラを含むインテントを受け取ります。デバイスに接続する前に、このエクストラの値が true であることを確認します。

デバイスと通信する

USB デバイスとの通信は、同期または非同期のいずれかになります。いずれの場合も、UI スレッドをブロックしないように、すべてのデータ送信を実行する新しいスレッドを作成する必要があります。デバイスとの通信を適切に設定するには、通信するデバイスの適切な UsbInterface と UsbEndpoint を取得し、UsbDeviceConnection を使用してこのエンドポイントにリクエストを送信する必要があります。通常、コードは次のようになります。

  • UsbDevice オブジェクトの属性(プロダクト ID、ベンダー ID、デバイスクラスなど)をチェックして、デバイスと通信するかどうかを判断します。
  • デバイスと通信することが確実な場合は、通信に使用する適切な UsbInterface と、そのインターフェースの適切な UsbEndpoint を見つけます。インターフェースには 1 つ以上のエンドポイントを設定できます。通常は、双方向通信用の入力エンドポイントと出力エンドポイントを設定します。
  • 正しいエンドポイントが見つかったら、そのエンドポイントで UsbDeviceConnection を開きます。
  • そのエンドポイントで送信するデータを bulkTransfer() または controlTransfer() メソッドで提供します。メイン UI スレッドがブロックされないように、このステップは別のスレッドで実行する必要があります。Android でのスレッドの使用について詳しくは、プロセスとスレッドをご覧ください。

次のコード スニペットは、同期データ転送を行う簡単な方法を示しています。コードには、通信する正しいインターフェースとエンドポイントを正しく見つけるためのロジックをさらに追加する必要があります。また、メイン UI スレッドとは異なるスレッドでデータの転送を行う必要があります。

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

データを非同期で送信するには、UsbRequest クラスを使用して非同期リクエストを initialize および queue し、requestWait() で結果を待ちます。

デバイスとの通信の終了

デバイスとの通信が完了したとき、またはデバイスが取り外されたときは、releaseInterface() と close() を呼び出して UsbInterface と UsbDeviceConnection を閉じます。デタッチ イベントをリッスンするには、次のようにブロードキャスト レシーバを作成します。

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

マニフェストではなくアプリケーション内でブロードキャスト レシーバを作成すると、アプリケーションは実行中にのみ切断イベントを処理できます。これにより、デタッチ イベントは現在実行中のアプリにのみ送信され、すべてのアプリにブロードキャストされることはありません。