เมื่ออุปกรณ์ที่ทำงานด้วยระบบ Android อยู่ในโหมดโฮสต์ USB อุปกรณ์จะทำหน้าที่เป็นโฮสต์ USB, จ่ายไฟให้บัส และแจกแจงอุปกรณ์ USB ที่เชื่อมต่ออยู่ โหมดโฮสต์ USB รองรับใน Android 3.1 ขึ้นไป
ภาพรวมของ API
ก่อนเริ่มต้น คุณควรทำความเข้าใจคลาสที่ต้องใช้ ตารางต่อไปนี้อธิบาย API โฮสต์ USB ในแพ็กเกจ android.hardware.usb
ตารางที่ 1 USB Host API
| ชั้น | คำอธิบาย |
|---|---|
UsbManager |
ช่วยให้คุณแจกแจงและสื่อสารกับอุปกรณ์ USB ที่เชื่อมต่ออยู่ได้ |
UsbDevice |
แสดงอุปกรณ์ USB ที่เชื่อมต่อและมีเมธอดในการเข้าถึงข้อมูลระบุตัวบุคคล อินเทอร์เฟซ และปลายทาง |
UsbInterface |
แสดงอินเทอร์เฟซของอุปกรณ์ USB ซึ่งกำหนดชุดฟังก์ชันการทำงานสำหรับอุปกรณ์ อุปกรณ์หนึ่งเครื่องสามารถมีอินเทอร์เฟซที่ใช้สื่อสารได้มากกว่า 1 รายการ |
UsbEndpoint |
แสดงปลายทางของอินเทอร์เฟซ ซึ่งเป็นช่องทางการสื่อสารสำหรับอินเทอร์เฟซนี้ อินเทอร์เฟซอาจมีปลายทางอย่างน้อย 1 รายการ และมักจะมีปลายทางอินพุตและเอาต์พุตสำหรับการสื่อสารแบบ 2 ทางกับอุปกรณ์ |
UsbDeviceConnection |
แสดงถึงการเชื่อมต่อกับอุปกรณ์ ซึ่งจะโอนข้อมูลในปลายทาง คลาสนี้ช่วยให้คุณส่งข้อมูลไปมาแบบซิงโครนัสหรืออะซิงโครนัสได้ |
UsbRequest |
แสดงคำขอที่โหลดแบบอะซิงโครนัสเพื่อสื่อสารกับอุปกรณ์ผ่าน UsbDeviceConnection |
UsbConstants |
กำหนดค่าคงที่ USB ที่สอดคล้องกับคำจำกัดความใน linux/usb/ch9.h ของเคอร์เนล Linux |
ในสถานการณ์ส่วนใหญ่ คุณต้องใช้คลาสเหล่านี้ทั้งหมด (ต้องใช้ UsbRequest เฉพาะในกรณีที่คุณทำการสื่อสารแบบอะซิงโครนัส) เมื่อสื่อสารกับอุปกรณ์ USB โดยทั่วไป คุณจะได้รับ UsbManager เพื่อดึงข้อมูล UsbDevice ที่ต้องการ
เมื่อมีอุปกรณ์แล้ว คุณต้องค้นหา UsbInterface ที่เหมาะสมและ UsbEndpoint ของอินเทอร์เฟซนั้นเพื่อสื่อสาร เมื่อได้ปลายทางที่ถูกต้องแล้ว ให้เปิด UsbDeviceConnection เพื่อสื่อสารกับอุปกรณ์ USB
ข้อกำหนดของไฟล์ Manifest ของ Android
รายการต่อไปนี้อธิบายสิ่งที่คุณต้องเพิ่มลงในไฟล์ Manifest ของแอปพลิเคชันก่อนที่จะทำงานกับ USB Host API
- เนื่องจากอุปกรณ์ที่ทำงานด้วยระบบ Android บางรุ่นอาจไม่รองรับ API โฮสต์ USB ให้รวมองค์ประกอบ
<uses-feature>ที่ประกาศว่าแอปพลิเคชันของคุณใช้ฟีเจอร์android.hardware.usb.host - ตั้งค่า SDK ขั้นต่ำของแอปพลิเคชันเป็น ระดับ API 12 ขึ้นไป API โฮสต์ USB จะไม่แสดงในระดับ API ก่อนหน้า
- หากต้องการให้แอปพลิเคชันได้รับการแจ้งเตือนเกี่ยวกับอุปกรณ์ USB ที่เชื่อมต่อ ให้ระบุคู่องค์ประกอบ
<intent-filter>และ<meta-data>สำหรับ Intentandroid.hardware.usb.action.USB_DEVICE_ATTACHEDในกิจกรรมหลัก องค์ประกอบ<meta-data>ชี้ไปยังไฟล์ทรัพยากร XML ภายนอกที่ประกาศข้อมูลระบุตัวบุคคลเกี่ยวกับอุปกรณ์ที่คุณต้องการตรวจจับในไฟล์ทรัพยากร XML ให้ประกาศองค์ประกอบ
<usb-device>สำหรับอุปกรณ์ USB ที่ต้องการกรอง รายการต่อไปนี้อธิบายแอตทริบิวต์ของ<usb-device>โดยทั่วไป ให้ใช้รหัสผู้ให้บริการและรหัสผลิตภัณฑ์หากต้องการกรองอุปกรณ์ที่เฉพาะเจาะจง และใช้คลาส คลาสย่อย และโปรโตคอลหากต้องการกรองกลุ่มอุปกรณ์ USB เช่น อุปกรณ์จัดเก็บข้อมูลขนาดใหญ่หรือกล้องดิจิทัล คุณจะระบุแอตทริบิวต์เหล่านี้ทั้งหมดหรือจะไม่ระบุเลยก็ได้ การไม่ระบุแอตทริบิวต์จะจับคู่อุปกรณ์ USB ทุกเครื่อง ดังนั้นให้ทำเช่นนี้เฉพาะในกรณีที่แอปพลิเคชันของคุณต้องการเท่านั้นvendor-idproduct-idclasssubclassprotocol(อุปกรณ์หรืออินเทอร์เฟซ)
บันทึกไฟล์ทรัพยากรในไดเรกทอรี
res/xml/ชื่อไฟล์ทรัพยากร (ไม่มีนามสกุล .xml) ต้องเหมือนกับชื่อที่คุณระบุในองค์ประกอบ<meta-data>รูปแบบของไฟล์ทรัพยากร XML จะแสดงในตัวอย่างต่อไปนี้
ตัวอย่างไฟล์ Manifest และไฟล์ทรัพยากร
ตัวอย่างต่อไปนี้แสดงไฟล์ Manifest ตัวอย่างและไฟล์ทรัพยากรที่เกี่ยวข้อง
<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 จะระบุได้ว่าแอปพลิเคชันของคุณสนใจอุปกรณ์ที่เชื่อมต่อหรือไม่ หากมี คุณจะตั้งค่าการสื่อสารกับอุปกรณ์ได้หากต้องการ ซึ่งแอปพลิเคชันของคุณต้องทำดังนี้
- ค้นหาอุปกรณ์ USB ที่เชื่อมต่อโดยใช้ตัวกรอง Intent เพื่อรับการแจ้งเตือนเมื่อผู้ใช้เชื่อมต่ออุปกรณ์ USB หรือโดยการแจกแจงอุปกรณ์ USB ที่เชื่อมต่ออยู่แล้ว
- ขอสิทธิ์จากผู้ใช้เพื่อเชื่อมต่อกับอุปกรณ์ USB หากยังไม่ได้รับสิทธิ์
- สื่อสารกับอุปกรณ์ USB โดยการอ่านและเขียนข้อมูลบนปลายทางอินเทอร์เฟซที่เหมาะสม
ค้นหาอุปกรณ์
แอปพลิเคชันของคุณสามารถค้นหาอุปกรณ์ USB ได้โดยใช้ตัวกรอง Intent เพื่อรับการแจ้งเตือนเมื่อผู้ใช้เชื่อมต่ออุปกรณ์หรือโดยการแจกแจงอุปกรณ์ USB ที่เชื่อมต่ออยู่แล้ว การใช้ตัวกรอง Intent จะมีประโยชน์หากคุณต้องการให้แอปพลิเคชันตรวจหาอุปกรณ์ที่ต้องการโดยอัตโนมัติ การแจกแจงอุปกรณ์ USB ที่เชื่อมต่อจะมีประโยชน์หากคุณต้องการดูรายการอุปกรณ์ที่เชื่อมต่อทั้งหมด หรือหากแอปพลิเคชันไม่ได้กรอง Intent
ใช้ตัวกรอง Intent
หากต้องการให้แอปพลิเคชันค้นพบอุปกรณ์ USB ที่เฉพาะเจาะจง คุณสามารถระบุตัวกรอง Intent เพื่อกรอง Intent android.hardware.usb.action.USB_DEVICE_ATTACHED ได้ นอกจากตัวกรอง Intent นี้แล้ว คุณต้องระบุไฟล์ทรัพยากรที่ระบุพร็อพเพอร์ตี้ของอุปกรณ์ USB เช่น รหัสผลิตภัณฑ์และรหัสผู้ให้บริการ เมื่อผู้ใช้เชื่อมต่ออุปกรณ์ที่ตรงกับตัวกรองอุปกรณ์ของคุณ ระบบจะแสดงกล่องโต้ตอบที่ถามว่าต้องการเริ่มแอปพลิเคชันของคุณหรือไม่
หากผู้ใช้ยอมรับ แอปพลิเคชันของคุณจะมีสิทธิ์เข้าถึงอุปกรณ์โดยอัตโนมัติจนกว่าจะยกเลิกการเชื่อมต่ออุปกรณ์
ตัวอย่างต่อไปนี้แสดงวิธีประกาศตัวกรอง Intent
<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 ที่แสดงถึงอุปกรณ์ที่เชื่อมต่อจาก Intent ได้ดังนี้
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");
หากต้องการ คุณยังสามารถรับตัวทำซ้ำจากแฮชแมปและประมวลผลอุปกรณ์แต่ละเครื่องทีละเครื่องได้ด้วย ดังนี้
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 แอปพลิเคชันของคุณต้องได้รับสิทธิ์จากผู้ใช้
หมายเหตุ: หากแอปพลิเคชันใช้ตัวกรอง Intent เพื่อค้นหาอุปกรณ์ USB ขณะเชื่อมต่อ แอปพลิเคชันจะได้รับสิทธิ์โดยอัตโนมัติหากผู้ใช้อนุญาตให้แอปพลิเคชันจัดการ Intent หากไม่ คุณต้องขอสิทธิ์อย่างชัดแจ้งในแอปพลิเคชันก่อนเชื่อมต่อกับอุปกรณ์
การขอสิทธิ์อย่างชัดแจ้งอาจจำเป็นในบางสถานการณ์ เช่น เมื่อแอปพลิเคชันแจกแจงอุปกรณ์ USB ที่เชื่อมต่ออยู่แล้วและต้องการสื่อสารกับอุปกรณ์ดังกล่าว คุณต้องตรวจสอบสิทธิ์ในการเข้าถึงอุปกรณ์ก่อนที่จะพยายามสื่อสารกับอุปกรณ์ ไม่เช่นนั้น คุณจะได้รับข้อผิดพลาดขณะรันไทม์หากผู้ใช้ปฏิเสธสิทธิ์เข้าถึงอุปกรณ์
หากต้องการขอสิทธิ์อย่างชัดแจ้ง ให้สร้าง Broadcast Receiver ก่อน BroadcastReceiver นี้จะคอยฟัง Intent ที่มีการประกาศเมื่อคุณเรียกใช้ requestPermission() การเรียกใช้ requestPermission() จะแสดงกล่องโต้ตอบแก่ผู้ใช้เพื่อขอสิทธิ์เชื่อมต่อกับอุปกรณ์ โค้ดตัวอย่างต่อไปนี้แสดงวิธีสร้าง Broadcast Receiver
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); } } } } };
หากต้องการลงทะเบียน Broadcast Receiver ให้เพิ่มโค้ดนี้ในเมธอด 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);
เมื่อผู้ใช้ตอบกลับกล่องโต้ตอบ Broadcast Receiver จะได้รับ Intent ที่มี EXTRA_PERMISSION_GRANTED เพิ่มเติม ซึ่งเป็นบูลีนที่แสดงคำตอบ ตรวจสอบค่าของข้อมูลเพิ่มเติมนี้ว่าเป็นจริงก่อนเชื่อมต่อกับอุปกรณ์
สื่อสารกับอุปกรณ์
การสื่อสารกับอุปกรณ์ USB อาจเป็นแบบซิงโครนัสหรืออะซิงโครนัสก็ได้ ไม่ว่าในกรณีใด คุณควรสร้างชุดข้อความใหม่เพื่อใช้ในการส่งข้อมูลทั้งหมด เพื่อไม่ให้บล็อกเธรด UI หากต้องการตั้งค่าการสื่อสารกับอุปกรณ์อย่างถูกต้อง คุณต้องได้รับ UsbInterface และ UsbEndpoint ที่เหมาะสมของอุปกรณ์ที่ต้องการสื่อสารด้วย และส่งคำขอไปยังปลายทางนี้ด้วย UsbDeviceConnection โดยทั่วไปแล้ว โค้ดควรมีลักษณะดังนี้
- ตรวจสอบแอตทริบิวต์ของออบเจ็กต์
UsbDeviceเช่น รหัสสินค้า รหัสผู้ให้บริการ หรือคลาสอุปกรณ์ เพื่อดูว่าคุณต้องการสื่อสารกับอุปกรณ์หรือไม่ - เมื่อแน่ใจว่าต้องการสื่อสารกับอุปกรณ์ ให้ค้นหา
UsbInterfaceที่เหมาะสมซึ่งคุณต้องการใช้เพื่อสื่อสารพร้อมกับUsbEndpointที่เหมาะสมของอินเทอร์เฟซนั้น อินเทอร์เฟซอาจมีปลายทางอย่างน้อย 1 รายการ และโดยทั่วไปจะมีปลายทางอินพุตและเอาต์พุตสำหรับการสื่อสารแบบ 2 ทาง - เมื่อพบปลายทางที่ถูกต้องแล้ว ให้เปิด
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()
กำลังสิ้นสุดการสื่อสารกับอุปกรณ์
เมื่อสื่อสารกับอุปกรณ์เสร็จแล้วหรือหากอุปกรณ์ถูกถอดออก ให้ปิด UsbInterface และ UsbDeviceConnection โดยเรียกใช้ releaseInterface() และ close() หากต้องการฟังเหตุการณ์ที่แยกออก ให้สร้าง Broadcast Receiver ดังนี้
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 } } } };
การสร้าง Broadcast Receiver ภายในแอปพลิเคชัน ไม่ใช่ไฟล์ Manifest จะช่วยให้แอปพลิเคชันของคุณจัดการเฉพาะเหตุการณ์ที่แยกออกขณะที่แอปพลิเคชันทำงานอยู่ ด้วยวิธีนี้ ระบบจะส่งเหตุการณ์ที่แยกออกไปยังแอปพลิเคชันที่กำลังทำงานอยู่เท่านั้น และจะไม่เผยแพร่ไปยังแอปพลิเคชันทั้งหมด