Android destekli cihazınız USB ana makine modundayken USB ana makinesi olarak çalışır, veri yoluna güç sağlar ve bağlı USB cihazlarını listeler. USB ana makine modu, Android 3.1 ve sonraki sürümlerde desteklenir.
API'ye Genel Bakış
Başlamadan önce, üzerinde çalışmanız gereken sınıfları anlamanız önemlidir. Aşağıdaki tabloda, android.hardware.usb paketindeki USB ana makine API'leri açıklanmaktadır.
Tablo 1. USB Ana Makine API'leri
| Sınıf | Açıklama |
|---|---|
UsbManager |
Bağlı USB cihazlarını listelemenize ve bunlarla iletişim kurmanıza olanak tanır. |
UsbDevice |
Bağlı bir USB cihazını temsil eder ve cihazın tanımlayıcı bilgilerine, arayüzlerine ve uç noktalarına erişmek için yöntemler içerir. |
UsbInterface |
Cihaz için bir dizi işlev tanımlayan bir USB cihazının arayüzünü temsil eder. Bir cihazın iletişim kurabileceği bir veya daha fazla arayüzü olabilir. |
UsbEndpoint |
Bu arayüz için bir iletişim kanalı olan arayüz uç noktasını temsil eder. Bir arayüzün bir veya daha fazla uç noktası olabilir ve genellikle cihazla iki yönlü iletişim için giriş ve çıkış uç noktaları bulunur. |
UsbDeviceConnection |
Uç noktalarda veri aktaran cihaza bağlantıyı temsil eder. Bu sınıf, verileri eşzamanlı veya eşzamansız olarak gönderip almanıza olanak tanır. |
UsbRequest |
UsbDeviceConnection üzerinden bir cihazla iletişim kurmak için asenkron bir isteği temsil eder. |
UsbConstants |
Linux çekirdeğinin linux/usb/ch9.h dosyasındaki tanımlara karşılık gelen USB sabitlerini tanımlar. |
Çoğu durumda, bir USB cihazıyla iletişim kurarken bu sınıfların tümünü kullanmanız gerekir (UsbRequest yalnızca eşzamansız iletişim kuruyorsanız gereklidir). Genel olarak, istediğiniz UsbDevice değerini almak için bir UsbManager elde edersiniz.
Cihazı aldığınızda, iletişim kurmak için uygun UsbInterface ve bu arayüzün UsbEndpoint değerini bulmanız gerekir. Doğru uç noktayı aldıktan sonra USB cihazıyla iletişim kurmak için bir UsbDeviceConnection açın.
Android manifest dosyasıyla ilgili şartlar
Aşağıdaki listede, USB ana makine API'leriyle çalışmadan önce uygulamanızın manifest dosyasına eklemeniz gerekenler açıklanmaktadır:
- Android destekli tüm cihazların USB ana makine API'lerini destekleyeceği garanti edilmediğinden, uygulamanızın
android.hardware.usb.hostözelliğini kullandığını beyan eden bir<uses-feature>öğesi ekleyin. - Uygulamanın minimum SDK'sını API düzeyi 12 veya daha yüksek bir sürüme ayarlayın. USB ana makine API'leri önceki API düzeylerinde mevcut değildir.
- Uygulamanızın bağlı bir USB cihazı hakkında bildirim almasını istiyorsanız ana etkinliğinizde
android.hardware.usb.action.USB_DEVICE_ATTACHEDintent'i için bir<intent-filter>ve<meta-data>öğe çifti belirtin.<meta-data>öğesi, algılamak istediğiniz cihazla ilgili kişisel verileri bildiren harici bir XML kaynak dosyasına işaret eder.XML kaynak dosyasında, filtrelemek istediğiniz USB cihazları için
<usb-device>öğelerini tanımlayın. Aşağıdaki listede<usb-device>öğesinin özellikleri açıklanmaktadır. Genel olarak, belirli bir cihazı filtrelemek istiyorsanız tedarikçi firma ve ürün kimliğini, yığın depolama cihazları veya dijital kameralar gibi bir USB cihaz grubunu filtrelemek istiyorsanız sınıf, alt sınıf ve protokolü kullanın. Bu özelliklerin hiçbirini veya tümünü belirtebilirsiniz. Hiçbir özellik belirtilmezse her USB cihazı eşleşir. Bu nedenle, yalnızca uygulamanız gerektiriyorsa bu işlemi yapın:vendor-idproduct-idclasssubclassprotocol(cihaz veya arayüz)
Kaynak dosyasını
res/xml/dizinine kaydedin. Kaynak dosya adı (.xml uzantısı olmadan),<meta-data>öğesinde belirttiğiniz adla aynı olmalıdır. XML kaynak dosyasının biçimi aşağıdaki örnekte gösterilmiştir.
Manifest ve kaynak dosyası örnekleri
Aşağıdaki örnekte, örnek bir manifest ve buna karşılık gelen kaynak dosyası gösterilmektedir:
<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>
Bu durumda, aşağıdaki kaynak dosyası res/xml/device_filter.xml dizinine kaydedilmeli ve belirtilen özelliklere sahip tüm USB cihazlarının filtrelenmesi gerektiğini belirtmelidir:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-device vendor-id="1234" product-id="5678" class="255" subclass="66" protocol="1" /> </resources>
Cihazlarla çalışma
Kullanıcılar USB cihazları Android destekli bir cihaza bağladığında Android sistemi, uygulamanızın bağlı cihazla ilgilenip ilgilenmediğini belirleyebilir. Bu durumda, isterseniz cihazla iletişim kurabilirsiniz. Bunun için uygulamanızın şunları yapması gerekir:
- Kullanıcı bir USB cihazı bağladığında bildirim almak için intent filtresi kullanarak veya önceden bağlanmış USB cihazlarını listeleyerek bağlı USB cihazlarını keşfedin.
- Henüz alınmadıysa kullanıcıdan USB cihazına bağlanma izni isteyin.
- Uygun arayüz uç noktalarındaki verileri okuyup yazarak USB cihazıyla iletişim kurma
Cihaz keşfetme
Uygulamanız, kullanıcı bir cihaz bağladığında bildirim almak için intent filtresi kullanarak veya önceden bağlanmış USB cihazlarını listeleyerek USB cihazlarını keşfedebilir. Uygulamanızın istediğiniz bir cihazı otomatik olarak algılamasını istiyorsanız intent filtresi kullanmak faydalı olur. Bağlı USB cihazlarını listelemek, bağlı tüm cihazların listesini almak istiyorsanız veya uygulamanız bir intent için filtreleme yapmadıysa kullanışlıdır.
Intent filtresi kullanma
Uygulamanızın belirli bir USB cihazını bulması için android.hardware.usb.action.USB_DEVICE_ATTACHED intent'ini filtreleyecek bir intent filtresi belirtebilirsiniz. Bu intent filtresiyle birlikte, USB cihazının ürün ve tedarikçi kimliği gibi özelliklerini belirten bir kaynak dosyası belirtmeniz gerekir. Kullanıcılar cihaz filtrenizle eşleşen bir cihaz bağladığında sistem, uygulamanızı başlatmak isteyip istemediklerini soran bir iletişim kutusu gösterir.
Kullanıcılar kabul ederse uygulamanız, cihazın bağlantısı kesilene kadar cihaza erişmek için otomatik olarak izin alır.
Aşağıdaki örnekte intent filtresinin nasıl tanımlanacağı gösterilmektedir:
<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>
Aşağıdaki örnekte, ilgilendiğiniz USB cihazlarını belirten ilgili kaynak dosyanın nasıl tanımlanacağı gösterilmektedir:
<?xml version="1.0" encoding="utf-8"?> <resources> <usb-device vendor-id="1234" product-id="5678" /> </resources>
Etkinliğinizde, bağlı cihazı temsil eden UsbDevice öğesini intent'ten şu şekilde alabilirsiniz:
Kotlin
val device: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)
Java
UsbDevice device = (UsbDevice) intent.getParcelableExtra(UsbManager.EXTRA_DEVICE);
Cihazları listeleme
Uygulamanız, çalışırken bağlı olan tüm USB cihazlarını incelemek istiyorsa veri yolundaki cihazları numaralandırabilir. Bağlı tüm USB cihazlarının karma haritasını almak için getDeviceList() yöntemini kullanın. Haritadan bir cihaz almak istiyorsanız karma harita, USB cihazının adıyla anahtarlanır.
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");
İsterseniz karma haritadan bir yineleyici alıp her cihazı tek tek işleyebilirsiniz:
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 }
Cihazla iletişim kurma izni alma
Uygulamanızın USB cihazıyla iletişim kurabilmesi için kullanıcılarınızdan izin alması gerekir.
Not: Uygulamanız, bağlı USB cihazlarını keşfetmek için intent filtresi kullanıyorsa kullanıcı, uygulamanızın intent'i işlemesine izin verdiğinde otomatik olarak izin alır. Aksi takdirde, cihaza bağlanmadan önce uygulamanızda açıkça izin istemeniz gerekir.
Uygulamanızın, önceden bağlanmış USB cihazlarını listelediği ve bunlardan biriyle iletişim kurmak istediği durumlar gibi bazı durumlarda açıkça izin istemek gerekebilir. Bir cihazla iletişim kurmaya çalışmadan önce cihaza erişim izniniz olup olmadığını kontrol etmeniz gerekir. Aksi takdirde, kullanıcı cihaza erişim iznini reddederse çalışma zamanı hatası alırsınız.
Açıkça izin almak için önce bir yayın alıcısı oluşturun. Bu alıcı, requestPermission() yöntemini çağırdığınızda yayınlanan intent'i dinler. requestPermission() çağrısı, kullanıcıya cihaza bağlanma izni isteyen bir iletişim kutusu gösterir. Aşağıdaki örnek kodda, yayın alıcısının nasıl oluşturulacağı gösterilmektedir:
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); } } } } };
Yayın alıcısını kaydetmek için etkinliğinizdeki onCreate() yönteminize şunu ekleyin:
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);
Kullanıcılardan cihaza bağlanma izni isteyen iletişim kutusunu göstermek için requestPermission() yöntemini çağırın:
Kotlin
lateinit var device: UsbDevice ... usbManager.requestPermission(device, permissionIntent)
Java
UsbDevice device; ... usbManager.requestPermission(device, permissionIntent);
Kullanıcılar iletişim kutusuna yanıt verdiğinde yayın alıcınız, yanıtı temsil eden bir boole olan EXTRA_PERMISSION_GRANTED ekini içeren intent'i alır. Cihaza bağlanmadan önce bu ekstranın değerinin doğru olup olmadığını kontrol edin.
Cihazla iletişim kurma
USB cihazıyla iletişim eşzamanlı veya eşzamansız olabilir. Her iki durumda da, kullanıcı arayüzü iş parçacığını engellememek için tüm veri aktarımlarını gerçekleştireceğiniz yeni bir iş parçacığı oluşturmanız gerekir. Bir cihazla iletişimi doğru şekilde ayarlamak için iletişim kurmak istediğiniz cihazın uygun UsbInterface ve UsbEndpoint değerlerini almanız ve bu uç noktada UsbDeviceConnection ile istek göndermeniz gerekir. Genel olarak kodunuz:
- Cihazla iletişim kurmak isteyip istemediğinizi belirlemek için
UsbDevicenesnesinin ürün kimliği, tedarikçi kimliği veya cihaz sınıfı gibi özelliklerini kontrol edin. - Cihazla iletişim kurmak istediğinizden emin olduğunuzda, iletişim kurmak için kullanmak istediğiniz uygun
UsbInterfaceve bu arayüzün uygunUsbEndpointdeğerini bulun. Arayüzlerin bir veya daha fazla uç noktası olabilir ve genellikle iki yönlü iletişim için bir giriş ve çıkış uç noktası bulunur. - Doğru uç noktayı bulduğunuzda bu uç noktada bir
UsbDeviceConnectionaçın. - Uç noktada iletmek istediğiniz verileri
bulkTransfer()veyacontrolTransfer()yöntemiyle sağlayın. Ana kullanıcı arayüzü iş parçacığının engellenmesini önlemek için bu adımı başka bir iş parçacığında gerçekleştirmeniz gerekir. Android'de iş parçacıklarını kullanma hakkında daha fazla bilgi için İşlemler ve İş Parçacıkları başlıklı makaleyi inceleyin.
Aşağıdaki kod snippet'i, eşzamanlı veri aktarımı yapmanın basit bir yoludur. Kodunuz, iletişim kurulacak doğru arayüzü ve uç noktaları doğru şekilde bulmak için daha fazla mantığa sahip olmalı ve tüm veri aktarımlarını ana kullanıcı arayüzü iş parçacığından farklı bir iş parçacığında yapmalıdır:
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
Verileri eşzamansız olarak göndermek için UsbRequest sınıfını kullanarak eşzamansız bir istek initialize ve queue, ardından requestWait() ile sonucu bekleyin.
Cihazla iletişimi sonlandırma
Bir cihazla iletişiminiz bittiğinde veya cihaz çıkarıldığında releaseInterface() ve close() yöntemlerini çağırarak UsbInterface ve UsbDeviceConnection nesnelerini kapatın. Bağlantısı kesilen etkinlikleri dinlemek için aşağıdaki gibi bir yayın alıcısı oluşturun:
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 } } } };
Yayın alıcıyı manifestte değil, uygulama içinde oluşturmak, uygulamanızın yalnızca çalışırken bağlantısı kesilen etkinlikleri işlemesine olanak tanır. Bu sayede, ayrılmış etkinlikler yalnızca o anda çalışan uygulamaya gönderilir ve tüm uygulamalara yayınlanmaz.