USB アクセサリの概要

USB アクセサリー モードを使用すると、Android 搭載デバイス専用に設計された USB ホスト ハードウェアを接続できます。アクセサリーは、Android Accessory Development Kit のドキュメントに記載されている Android アクセサリー プロトコルに準拠する必要があります。これにより、USB ホストとして動作できない Android 搭載デバイスでも、USB ハードウェアと通信できるようになります。Android 搭載デバイスが USB アクセサリー モードの場合、接続された Android USB アクセサリーがホストとして動作し、USB バスに電力を供給して、接続されたデバイスを列挙します。Android 3.1(API レベル 12)は USB アクセサリー モードをサポートしています。この機能は、より幅広いデバイスをサポートできるように、Android 2.3.4(API レベル 10)にもバックポートされています。

適切な USB アクセサリ API を選択する

USB アクセサリー API は Android 3.1 でプラットフォームに導入されましたが、Google API アドオン ライブラリを使用することで Android 2.3.4 でも利用できます。これらの API は外部ライブラリを使用してバックポートされているため、USB アクセサリー モードをサポートするためにインポートできるパッケージが 2 つあります。サポートする Android 搭載デバイスに応じて、どちらか一方を使用する必要があります。

  • com.android.future.usb: Android 2.3.4 で USB アクセサリー モードをサポートするため、Google API アドオン ライブラリには、バックポートされた USB アクセサリー API が含まれており、この名前空間に含まれています。Android 3.1 では、この名前空間内のクラスのインポートと呼び出しもサポートされており、アドオン ライブラリで記述されたアプリケーションをサポートしています。このアドオン ライブラリは、android.hardware.usb アクセサリー API のシンラッパーであり、USB ホストモードをサポートしていません。

    USB アクセサリー モードをサポートするデバイスを幅広くサポートする場合は、アドオン ライブラリを使用して、このパッケージをインポートします。すべての Android 2.3.4 デバイスが USB アクセサリー機能をサポートする必要があるわけではありません。この機能をサポートするかどうかは、個々のデバイス メーカーが決定します。そのため、マニフェスト ファイルでこの機能を宣言する必要があります。

  • android.hardware.usb: この名前空間には、Android 3.1 で USB アクセサリー モードをサポートするクラスが含まれています。このパッケージはフレームワーク API の一部として含まれているため、Android 3.1 ではアドオン ライブラリを使用せずに USB アクセサリー モードがサポートされます。USB アクセサリー モードのハードウェア サポートを備えた Android 3.1 以降のデバイスのみを対象とする場合は、このパッケージを使用します。このモードはマニフェスト ファイルで宣言できます。

Google API アドオン ライブラリをインストールする

このアドオンをインストールする場合は、SDK Manager を使用して Google API Android API 10 パッケージをインストールします。アドオン ライブラリのインストールについて詳しくは、Google API アドオンのインストールをご覧ください。

API の概要

アドオン ライブラリはフレームワーク API のラッパーであるため、USB アクセサリー機能をサポートするクラスは似ています。アドオン ライブラリを使用する場合でも、android.hardware.usb のリファレンス ドキュメントを使用できます。

注: ただし、アドオン ライブラリとフレームワーク API の間には、使用方法にわずかな違いがあります。

USB アクセサリ API をサポートしているクラスを、次の表に示します。

クラス 説明
UsbManager 接続されている USB アクセサリーを列挙して通信できるようにします。
UsbAccessory USB アクセサリーを表し、その識別情報にアクセスするためのメソッドが含まれています。

アドオン ライブラリとプラットフォーム API の使用方法の違い

Google API アドオン ライブラリとプラットフォーム API の使用には、2 つの違いがあります。

アドオン ライブラリを使用している場合は、次の方法で 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 マニフェストの要件

USB アクセサリー API を使用する前に、アプリのマニフェスト ファイルに追加する必要があるものを以下に示します。マニフェストとリソース ファイルの例は、これらのアイテムを宣言する方法を示しています。

  • すべての Android 搭載デバイスが USB アクセサリー API をサポートしているとは限らないため、アプリが android.hardware.usb.accessory 機能を使用することを宣言する <uses-feature> 要素を含めます。
  • アドオン ライブラリを使用している場合は、ライブラリに com.android.future.usb.accessory を指定する <uses-library> 要素を追加します。
  • アドオン ライブラリを使用している場合は、アプリケーションの最小 SDK を API レベル 10 に設定します。android.hardware.usb パッケージを使用している場合は、API レベル 12 に設定します。
  • USB アクセサリーが接続されたときにアプリに通知されるようにするには、メイン アクティビティの android.hardware.usb.action.USB_ACCESSORY_ATTACHED インテントに <intent-filter> 要素と <meta-data> 要素のペアを指定します。<meta-data> 要素は、検出するアクセサリーの識別情報を宣言する外部 XML リソース ファイルを指します。

    XML リソース ファイルで、フィルタするアクセサリーの <usb-accessory> 要素を宣言します。各 <usb-accessory> には次の属性を指定できます。

    • manufacturer
    • model
    • version

    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 システムは、接続されたアクセサリーがアプリに関連しているかどうかを判断できます。その場合は、必要に応じてアクセサリーとの通信をセットアップできます。そのためには、アプリで次の処理を行う必要があります。

  1. 接続されているアクセサリーを検出するには、アクセサリー接続イベントをフィルタするインテント フィルタを使用するか、接続されているアクセサリーを列挙して適切なアクセサリーを見つけます。
  2. アクセサリーと通信するための権限をユーザーに求めます(まだ取得していない場合)。
  3. 適切なインターフェース エンドポイントでデータを読み書きして、アクセサリーと通信します。

アクセサリを検出する

アプリは、インテント フィルタを使用してユーザーがアクセサリーを接続したときに通知を受け取るか、すでに接続されているアクセサリーを列挙することで、アクセサリーを検出できます。インテント フィルタを使用すると、目的のアクセサリーをアプリで自動的に検出できるようになります。接続されているアクセサリーを列挙することは、接続されているすべてのアクセサリーのリストを取得する場合や、アプリケーションがインテントをフィルタしなかった場合に役立ちます。

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

アプリケーションで特定の 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);

アクセサリを列挙する

アプリケーションの実行中に、アプリケーションで、自身を識別したアクセサリーを列挙できます。

getAccessoryList() メソッドを使用して、接続されているすべての USB アクセサリーの配列を取得します。

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

注: 一度にサポートされる接続アクセサリーは 1 つのみです。

アクセサリとの通信の権限を取得する

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 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() メソッドに次のコードを追加します。

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 バイトのパケット バッファをサポートしているため、簡素化のために、常にこのサイズのバッファを宣言することもできます。

注: 下位レベルでは、パケットは USB フルスピード アクセサリーの場合は 64 バイト、USB ハイスピード アクセサリーの場合は 512 バイトです。Android アクセサリー プロトコルは、簡素化のために、両方の速度のパケットを 1 つの論理パケットにまとめます。

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

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