Tổng quan về máy chủ USB

Khi thiết bị chạy Android ở chế độ USB host, thiết bị sẽ đóng vai trò là USB host, cấp nguồn cho bus và liệt kê các thiết bị USB đã kết nối. Chế độ máy chủ USB được hỗ trợ trong Android 3.1 trở lên.

Tổng quan về API

Trước khi bắt đầu, bạn cần hiểu rõ các lớp mà bạn cần làm việc. Bảng sau đây mô tả các API máy chủ USB trong gói android.hardware.usb.

Bảng 1. API máy chủ USB

Lớp Mô tả
UsbManager Cho phép bạn liệt kê và giao tiếp với các thiết bị USB đã kết nối.
UsbDevice Đại diện cho một thiết bị USB đã kết nối và chứa các phương thức để truy cập vào thông tin nhận dạng, giao diện và điểm cuối của thiết bị đó.
UsbInterface Đại diện cho giao diện của thiết bị USB, xác định một tập hợp chức năng cho thiết bị. Một thiết bị có thể có một hoặc nhiều giao diện để giao tiếp.
UsbEndpoint Đại diện cho một điểm cuối giao diện, là kênh liên lạc cho giao diện này. Một giao diện có thể có một hoặc nhiều điểm cuối và thường có các điểm cuối đầu vào và đầu ra để giao tiếp hai chiều với thiết bị.
UsbDeviceConnection Đại diện cho một kết nối với thiết bị, giúp chuyển dữ liệu trên các điểm cuối. Lớp này cho phép bạn gửi dữ liệu qua lại một cách đồng bộ hoặc không đồng bộ.
UsbRequest Đại diện cho một yêu cầu không đồng bộ để giao tiếp với một thiết bị thông qua UsbDeviceConnection.
UsbConstants Xác định các hằng số USB tương ứng với các định nghĩa trong linux/usb/ch9.h của nhân Linux.

Trong hầu hết trường hợp, bạn cần sử dụng tất cả các lớp này (chỉ cần UsbRequest nếu bạn đang giao tiếp không đồng bộ) khi giao tiếp với thiết bị USB. Nói chung, bạn sẽ nhận được UsbManager để truy xuất UsbDevice mà bạn muốn. Khi có thiết bị, bạn cần tìm UsbInterface thích hợp và UsbEndpoint của giao diện đó để giao tiếp. Sau khi bạn có được điểm cuối chính xác, hãy mở UsbDeviceConnection để giao tiếp với thiết bị USB.

Yêu cầu đối với tệp kê khai Android

Danh sách sau đây mô tả những nội dung bạn cần thêm vào tệp kê khai của ứng dụng trước khi làm việc với các API máy chủ USB:

  • Vì không phải tất cả thiết bị chạy Android đều được đảm bảo hỗ trợ API máy chủ USB, hãy thêm một phần tử <uses-feature> khai báo rằng ứng dụng của bạn sử dụng tính năng android.hardware.usb.host.
  • Đặt SDK tối thiểu của ứng dụng thành cấp độ API 12 trở lên. Các API máy chủ USB không có trên các cấp độ API cũ hơn.
  • Nếu bạn muốn ứng dụng của mình nhận được thông báo về thiết bị USB được kết nối, hãy chỉ định một cặp phần tử <intent-filter> và <meta-data> cho ý định android.hardware.usb.action.USB_DEVICE_ATTACHED trong hoạt động chính. Phần tử <meta-data> trỏ đến một tệp tài nguyên XML bên ngoài khai báo thông tin nhận dạng về thiết bị mà bạn muốn phát hiện.

    Trong tệp tài nguyên XML, hãy khai báo các phần tử <usb-device> cho thiết bị USB mà bạn muốn lọc. Danh sách sau đây mô tả các thuộc tính của <usb-device>. Nhìn chung, hãy sử dụng mã nhà cung cấp và mã sản phẩm nếu bạn muốn lọc cho một thiết bị cụ thể và sử dụng lớp, lớp con và giao thức nếu bạn muốn lọc cho một nhóm thiết bị USB, chẳng hạn như thiết bị lưu trữ dung lượng lớn hoặc máy ảnh kỹ thuật số. Bạn có thể chỉ định không có hoặc tất cả các thuộc tính này. Việc không chỉ định thuộc tính nào sẽ khớp với mọi thiết bị USB, vì vậy, chỉ làm việc này nếu ứng dụng của bạn yêu cầu:

    • vendor-id
    • product-id
    • class
    • subclass
    • protocol (thiết bị hoặc giao diện)

    Lưu tệp tài nguyên trong thư mục res/xml/. Tên tệp tài nguyên (không có đuôi .xml) phải giống với tên tệp bạn đã chỉ định trong phần tử <meta-data>. Định dạng cho tệp tài nguyên XML được trình bày trong ví dụ sau đây.

Ví dụ về tệp kê khai và tệp tài nguyên

Ví dụ sau đây cho thấy một tệp kê khai mẫu và tệp tài nguyên tương ứng:

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

Trong trường hợp này, tệp tài nguyên sau đây phải được lưu trong res/xml/device_filter.xml và chỉ định rằng mọi thiết bị USB có các thuộc tính được chỉ định đều phải được lọc:

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

<resources>
    <usb-device vendor-id="1234" product-id="5678" class="255" subclass="66" protocol="1" />
</resources>

Làm việc với thiết bị

Khi người dùng kết nối thiết bị USB với thiết bị chạy Android, hệ thống Android có thể xác định xem ứng dụng của bạn có quan tâm đến thiết bị thông minh hay không. Nếu có, bạn có thể thiết lập giao tiếp với thiết bị nếu muốn. Để làm được việc này, ứng dụng của bạn phải:

  1. Khám phá các thiết bị USB đã kết nối bằng cách sử dụng bộ lọc ý định để nhận thông báo khi người dùng kết nối thiết bị USB hoặc bằng cách liệt kê các thiết bị USB đã kết nối.
  2. Yêu cầu người dùng cấp quyền kết nối với thiết bị USB, nếu chưa được cấp.
  3. Giao tiếp với thiết bị USB bằng cách đọc và ghi dữ liệu trên các điểm cuối giao diện thích hợp.

Khám phá thiết bị

Ứng dụng của bạn có thể khám phá các thiết bị USB bằng cách sử dụng bộ lọc ý định để nhận thông báo khi người dùng kết nối thiết bị hoặc bằng cách liệt kê các thiết bị USB đã kết nối. Việc sử dụng bộ lọc ý định sẽ hữu ích nếu bạn muốn ứng dụng của mình tự động phát hiện thiết bị mà bạn muốn. Việc liệt kê các thiết bị USB đã kết nối sẽ hữu ích nếu bạn muốn lấy danh sách tất cả thiết bị đã kết nối hoặc nếu ứng dụng của bạn không lọc theo ý định.

Sử dụng bộ lọc ý định

Để ứng dụng của bạn khám phá một thiết bị USB cụ thể, bạn có thể chỉ định một bộ lọc ý định để lọc ý định android.hardware.usb.action.USB_DEVICE_ATTACHED. Cùng với bộ lọc ý định này, bạn cần chỉ định một tệp tài nguyên chỉ định các thuộc tính của thiết bị USB, chẳng hạn như mã sản phẩm và mã nhà cung cấp. Khi người dùng kết nối một thiết bị khớp với bộ lọc thiết bị của bạn, hệ thống sẽ hiển thị cho họ một hộp thoại hỏi xem họ có muốn khởi động ứng dụng của bạn hay không. Nếu người dùng chấp nhận, ứng dụng của bạn sẽ tự động có quyền truy cập vào thiết bị cho đến khi thiết bị bị ngắt kết nối.

Ví dụ sau đây cho biết cách khai báo bộ lọc ý định:

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

Ví dụ sau đây cho thấy cách khai báo tệp tài nguyên tương ứng chỉ định các thiết bị USB mà bạn quan tâm:

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

<resources>
    <usb-device vendor-id="1234" product-id="5678" />
</resources>

Trong hoạt động, bạn có thể lấy UsbDevice đại diện cho thiết bị được đính kèm từ ý định như sau:

Kotlin

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

Java

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

Liệt kê thiết bị

Nếu ứng dụng của bạn muốn kiểm tra tất cả thiết bị USB hiện đang kết nối trong khi ứng dụng đang chạy, thì ứng dụng có thể liệt kê các thiết bị trên bus. Sử dụng phương thức getDeviceList() để lấy bản đồ băm của tất cả thiết bị USB được kết nối. Bản đồ băm được khoá bằng tên của thiết bị USB nếu bạn muốn lấy thiết bị từ bản đồ.

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

Nếu muốn, bạn cũng có thể lấy một trình lặp từ bản đồ băm và xử lý từng thiết bị:

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
}

Xin quyền giao tiếp với thiết bị

Trước khi giao tiếp với thiết bị USB, ứng dụng của bạn phải được người dùng cấp quyền.

Lưu ý: Nếu ứng dụng của bạn sử dụng bộ lọc ý định để khám phá các thiết bị USB khi chúng được kết nối, thì ứng dụng sẽ tự động nhận được quyền nếu người dùng cho phép ứng dụng xử lý ý định. Nếu không, bạn phải yêu cầu cấp quyền một cách rõ ràng trong ứng dụng trước khi kết nối với thiết bị.

Bạn có thể cần phải yêu cầu cấp quyền một cách rõ ràng trong một số trường hợp, chẳng hạn như khi ứng dụng của bạn liệt kê các thiết bị USB đã kết nối và sau đó muốn giao tiếp với một thiết bị. Bạn phải kiểm tra quyền truy cập vào thiết bị trước khi cố gắng giao tiếp với thiết bị đó. Nếu không, bạn sẽ nhận được lỗi thời gian chạy nếu người dùng từ chối cấp quyền truy cập vào thiết bị.

Để có được quyền một cách rõ ràng, trước tiên, hãy tạo một bộ nhận tín hiệu truyền tin. Bộ thu này sẽ lắng nghe ý định được truyền phát khi bạn gọi requestPermission(). Lệnh gọi đến requestPermission() sẽ hiển thị một hộp thoại cho người dùng để yêu cầu cấp quyền kết nối với thiết bị. Mã mẫu sau đây cho biết cách tạo bộ nhận tín hiệu truyền tin:

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

Để đăng ký bộ nhận tín hiệu truyền tin, hãy thêm đoạn mã này vào phương thức onCreate() trong hoạt động của bạn:

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

Để hiển thị hộp thoại yêu cầu người dùng cấp quyền kết nối với thiết bị, hãy gọi phương thức requestPermission():

Kotlin

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

Java

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

Khi người dùng trả lời hộp thoại, bộ nhận tín hiệu truyền tin sẽ nhận được ý định chứa dữ liệu bổ sung EXTRA_PERMISSION_GRANTED, đây là một giá trị boolean đại diện cho câu trả lời. Hãy kiểm tra giá trị true của phần bổ sung này trước khi kết nối với thiết bị.

Giao tiếp với thiết bị

Hoạt động giao tiếp với thiết bị USB có thể đồng bộ hoặc không đồng bộ. Trong cả hai trường hợp, bạn nên tạo một luồng mới để thực hiện tất cả các hoạt động truyền dữ liệu, nhờ đó không chặn luồng giao diện người dùng. Để thiết lập đúng cách hoạt động giao tiếp với một thiết bị, bạn cần lấy UsbInterface và UsbEndpoint thích hợp của thiết bị mà bạn muốn giao tiếp và gửi yêu cầu trên điểm cuối này bằng UsbDeviceConnection. Nhìn chung, mã của bạn phải:

  • Kiểm tra các thuộc tính của đối tượng UsbDevice, chẳng hạn như mã sản phẩm, mã nhà cung cấp hoặc lớp thiết bị để xác định xem bạn có muốn giao tiếp với thiết bị hay không.
  • Khi chắc chắn rằng bạn muốn giao tiếp với thiết bị, hãy tìm UsbInterface thích hợp mà bạn muốn dùng để giao tiếp cùng với UsbEndpoint thích hợp của giao diện đó. Giao diện có thể có một hoặc nhiều điểm cuối và thường sẽ có một điểm cuối đầu vào và đầu ra để giao tiếp hai chiều.
  • Khi bạn tìm thấy điểm cuối chính xác, hãy mở một UsbDeviceConnection trên điểm cuối đó.
  • Cung cấp dữ liệu mà bạn muốn truyền trên điểm cuối bằng phương thức bulkTransfer() hoặc controlTransfer(). Bạn nên thực hiện bước này trong một luồng khác để tránh chặn luồng giao diện người dùng chính. Để biết thêm thông tin về cách sử dụng luồng trong Android, hãy xem phần Quy trình và luồng.

Đoạn mã sau đây là một cách đơn giản để thực hiện việc chuyển dữ liệu đồng bộ. Mã của bạn phải có nhiều logic hơn để tìm đúng giao diện và điểm cuối chính xác để giao tiếp, đồng thời cũng phải thực hiện mọi hoạt động chuyển dữ liệu trong một luồng khác với luồng giao diện người dùng chính:

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

Để gửi dữ liệu không đồng bộ, hãy sử dụng lớp UsbRequest để initialize và queue một tài nguyên không đồng bộ, sau đó chờ kết quả bằng requestWait().

Chấm dứt giao tiếp với thiết bị

Khi bạn giao tiếp xong với một thiết bị hoặc nếu thiết bị đã bị tháo, hãy đóng UsbInterface và UsbDeviceConnection bằng cách gọi releaseInterface() và close(). Để lắng nghe các sự kiện đã tách, hãy tạo một bộ nhận tín hiệu truyền tin như bên dưới:

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

Việc tạo bộ nhận tín hiệu truyền tin trong ứng dụng chứ không phải tệp kê khai cho phép ứng dụng của bạn chỉ xử lý các sự kiện tách rời khi ứng dụng đang chạy. Bằng cách này, các sự kiện tách rời chỉ được gửi đến ứng dụng đang chạy và không được truyền phát đến tất cả ứng dụng.