حالت لوازم جانبی USB به کاربران امکان میدهد سختافزار میزبان USB را که بهطور خاص برای دستگاههای مجهز به Android طراحی شده است متصل کنند. لوازم جانبی باید از پروتکل لوازم جانبی Android که در سند کیت توسعه لوازم جانبی Android شرح داده شده است پیروی کنند. این کار به دستگاههای مجهز به Android که نمیتوانند بهعنوان میزبان USB عمل کنند اجازه میدهد همچنان با سختافزار USB تعامل داشته باشند. وقتی دستگاهی با سیستمعامل Android در حالت لوازم جانبی USB باشد، لوازم جانبی USB متصلشده به Android بهعنوان میزبان عمل میکند، برق گذرگاه USB را تأمین میکند، و دستگاههای متصل را شمارهگذاری میکند. Android 3.1 (سطح ایپیآی ۱۲) از حالت لوازم جانبی USB پشتیبانی میکند و این ویژگی به Android 2.3.4 (سطح ایپیآی ۱۰) نیز منتقل شده است تا پشتیبانی از طیف گستردهتری از دستگاهها را فعال کند.
انتخاب میاناهای برنامهسازی کاربردی مناسب برای لوازم جانبی USB
اگرچه میاناهای برنامهسازی کاربردی لوازم جانبی USB در Android 3.1 به پلاتفرم معرفی شدند، اما در Android 2.3.4 نیز بااستفاده از کتابخانه برافزای Google APIs دردسترس هستند. چون این میاناهای برنامهسازی کاربردی بااستفاده از کتابخانه خارجی بهعقب منتقل شدهاند، دو بسته وجود دارد که میتوانید برای پشتیبانی از حالت لوازم جانبی USB وارد کنید. بسته به اینکه از کدام دستگاههای مجهز به Android میخواهید پشتیبانی کنید، ممکن است مجبور شوید از یکی بهجای دیگری استفاده کنید:
com.android.future.usb: برای پشتیبانی از حالت لوازم جانبی USB در Android 2.3.4، کتابخانه برافزای Google APIs شامل میاناهای برنامهسازی کاربردی لوازم جانبی USB با پشتیبانی از نسخههای قدیمی است و این میاناهای برنامهسازی کاربردی در این فضای نام قرار دارند. Android 3.1 همچنین از وارد کردن و فراخوانی کلاسها در این فضای نام برای پشتیبانی از برنامههای نوشتهشده با کتابخانه برافزا پشتیبانی میکند. این کتابخانه برافزا یک پوشش نازک در اطراف میاناهای برنامهسازی کاربردی لوازم جانبیandroid.hardware.usbاست و از حالت میزبان USB پشتیبانی نمیکند.اگر میخواهید از گستردهترین طیف دستگاههایی که از حالت لوازم جانبی USB پشتیبانی میکنند پشتیبانی کنید، از کتابخانه برافزا استفاده کنید و این بسته را وارد کنید. توجه به این نکته مهم است که همه دستگاههای Android 2.3.4 ملزم به پشتیبانی از ویژگی لوازم جانبی USB نیستند. هر سازنده دستگاه بهطور جداگانه تصمیم میگیرد که از این قابلیت پشتیبانی کند یا نه، به همین دلیل است که باید آن را در فایل مانیفست خود اعلام کنید.
android.hardware.usb: این فضای نام حاوی کلاسهایی است که از حالت لوازم جانبی USB در Android 3.1 پشتیبانی میکنند. این بسته بهعنوان بخشی از میاناهای برنامهسازی کاربردی چارچوب گنجانده شده است، بنابراین Android 3.1 از حالت لوازم جانبی USB بدون استفاده از کتابخانه برافزا پشتیبانی میکند. اگر فقط به دستگاههای Android 3.1 یا جدیدتر که از حالت لوازم جانبی USB پشتیبانی سختافزاری دارند اهمیت میدهید، از این بسته استفاده کنید. میتوانید این موضوع را در فایل مانیفست خود اعلام کنید.
نصب کتابخانه برافزای Google APIs
اگر میخواهید برافزا را نصب کنید، میتوانید این کار را با نصب بسته Google APIs Android API 10 بااستفاده از «مدیر SDK» انجام دهید. برای اطلاعات بیشتر درباره نصب کتابخانه برافزا، به نصب برافزای Google APIs مراجعه کنید.
نمای کلی میانای برنامهسازی کاربردی
ازآنجاییکه کتابخانه برافزا پوششی برای میاناهای برنامهسازی کاربردی چارچوب است، کلاسهایی که از
ویژگی لوازم جانبی USB پشتیبانی میکنند مشابه هستند. حتی اگر از کتابخانه برافزا استفاده میکنید، میتوانید از اسناد مرجع برای android.hardware.usb استفاده کنید.
توجه: بااینحال، تفاوت جزئی در استفاده بین کتابخانه برافزا و میاناهای برنامهسازی کاربردی چارچوب وجود دارد که باید از آن مطلع باشید.
جدول زیر کلاسهایی را که از میاناهای برنامهسازی کاربردی لوازم جانبی USB پشتیبانی میکنند شرح میدهد:
| کلاس | شرح |
|---|---|
UsbManager |
به شما امکان میدهد لوازم جانبی USB متصل را فهرست کنید و با آنها ارتباط برقرار کنید. |
UsbAccessory |
نشاندهنده لوازم جانبی USB است و حاوی روشهایی برای دسترسی به اطلاعات شناسایی آن است. |
تفاوتهای استفاده بین کتابخانه برافزا و میاناهای برنامهسازی کاربردی پلاتفرم
دو تفاوت در استفاده از کتابخانه برافزای Google APIs و میاناهای برنامهسازی کاربردی پلاتفرم وجود دارد.
اگر از کتابخانه برافزا استفاده میکنید، باید شیء UsbManager را به روش زیر دریافت کنید:
کاتلین
val manager = UsbManager.getInstance(this)
جاوا
UsbManager manager = UsbManager.getInstance(this);
اگر از کتابخانه برافزا استفاده نمیکنید، باید شیء UsbManager را به روش زیر دریافت کنید:
کاتلین
val manager = getSystemService(Context.USB_SERVICE) as UsbManager
جاوا
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
وقتی لوازم جانبی متصل را با فیلتر قصد فیلتر میکنید، شیء UsbAccessory در داخل قصدی که به برنامه شما ارسال میشود قرار میگیرد. اگر از کتابخانه برافزا استفاده میکنید، باید شیء UsbAccessory را به روش زیر دریافت کنید:
کاتلین
val accessory = UsbManager.getAccessory(intent)
جاوا
UsbAccessory accessory = UsbManager.getAccessory(intent);
اگر از کتابخانه برافزا استفاده نمیکنید، باید شیء UsbAccessory را به روش زیر دریافت کنید:
کاتلین
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
جاوا
UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
الزامات مانیفست Android
فهرست زیر آنچه را که باید به فایل مانیفست برنامهتان اضافه کنید شرح میدهد، قبلاز اینکه با میاناهای برنامهسازی کاربردی لوازم جانبی USB کار کنید. نمونههای فایل مانیفست و منبع نشان میدهند که چگونه این موارد را اعلام کنید:
- چون تضمینی نیست که همه دستگاههای مجهز به Android از میاناهای برنامهسازی کاربردی لوازم جانبی USB پشتیبانی کنند،
عنصر
<uses-feature>را اضافه کنید که اعلام میکند برنامه شما از ویژگیandroid.hardware.usb.accessoryاستفاده میکند. - اگر از
کتابخانه برافزا استفاده میکنید،
عنصر
<uses-library>را با مشخص کردنcom.android.future.usb.accessoryبرای کتابخانه اضافه کنید. - اگر از کتابخانه برافزا استفاده میکنید، حداقل کیت توسعه نرمافزار برنامه را روی «سطح میانای برنامهسازی کاربردی ۱۰»
و اگر از بسته
android.hardware.usbاستفاده میکنید، روی ۱۲ تنظیم کنید. -
اگر میخواهید برنامهتان از لوازم جانبی USB متصلشده مطلع شود، یک جفت عنصر
<intent-filter>و<meta-data>برای هدفandroid.hardware.usb.action.USB_ACCESSORY_ATTACHEDدر فعالیت اصلیتان مشخص کنید. عنصر<meta-data>به فایل منبع XML خارجی اشاره میکند که اطلاعات شناساننده درباره لوازم جانبیای را که میخواهید شناسایی کنید اعلام میکند.در فایل منبع XML، عناصر
<usb-accessory>را برای لوازم جانبیای که میخواهید فیلتر کنید اعلام کنید. هر<usb-accessory>میتواند مشخصههای زیر را داشته باشد:manufacturermodelversion
فیلتر کردن براساس
versionتوصیه نمیشود. ممکن است لوازم جانبی یا دستگاه همیشه رشته نسخه را (عمداً یا سهواً) مشخص نکند. وقتی برنامهتان مشخصه نسخهای را برای فیلتر کردن اعلام میکند و لوازم جانبی یا دستگاه رشته نسخهای را مشخص نمیکند، این امر باعث ایجادNullPointerExceptionدر نسخههای قدیمیتر Android میشود. این مشکل در 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 میتواند تشخیص دهد که آیا برنامه شما به لوازم جانبی متصلشده علاقهمند است یا نه. اگر اینطور است، میتوانید درصورت تمایل، ارتباط با لوازم جانبی را راهاندازی کنید. برای انجام این کار، برنامه شما باید:
- لوازم جانبی متصل را بااستفاده از فیلتر قصد که رویدادهای متصلشده به لوازم جانبی را فیلتر میکند یا با شمارش لوازم جانبی متصل و پیدا کردن لوازم جانبی مناسب، کشف کنید.
- اگر قبلاً اجازه کاربر را برای برقراری ارتباط با لوازم جانبی دریافت نکردهاید، آن را درخواست کنید.
- با خواندن و نوشتن دادهها در نقطههای پایانی میانای مناسب، با لوازم جانبی ارتباط برقرار کنید.
پیدا کردن وسیله جانبی
برنامه شما میتواند بااستفاده از فیلتر قصد برای مطلع شدن هنگام اتصال وسیله جانبی توسط کاربر یا با شمارش وسایل جانبی که قبلاً متصل شدهاند، وسایل جانبی را کاوش کند. اگر میخواهید برنامهتان بتواند بهطور خودکار وسیله جانبی موردنظرتان را شناسایی کند، استفاده از فیلتر قصد مفید است. اگر میخواهید فهرستی از همه لوازم جانبی متصلشده دریافت کنید یا اگر برنامهتان برای قصدی فیلتر نشده است، شمارش لوازم جانبی متصلشده مفید است.
استفاده از فیلتر قصد
برای اینکه برنامهتان وسیله جانبی 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 را که نشاندهنده
لوازم جانبی متصلشده است از هدف بهاینصورت (با کتابخانه برافزا) دریافت کنید:
کاتلین
val accessory = UsbManager.getAccessory(intent)
جاوا
UsbAccessory accessory = UsbManager.getAccessory(intent);
یا به این صورت (با میاناهای برنامهسازی کاربردی پلاتفرم):
کاتلین
val accessory = intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY) as UsbAccessory
جاوا
UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY);
شمردن لوازم جانبی
میتوانید از برنامهتان بخواهید لوازم جانبیای را که خودشان را درحین اجرای برنامهتان شناسایی کردهاند، برشمارد.
از روش getAccessoryList()
برای دریافت آرایهای از همه لوازم جانبی USB متصلشده استفاده کنید:
کاتلین
val manager = getSystemService(Context.USB_SERVICE) as UsbManager val accessoryList: Array<out UsbAccessory> = manager.accessoryList
جاوا
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE); UsbAccessory[] accessoryList = manager.getAccessoryList();
توجه: در هر زمان فقط از یک لوازم جانبی متصل پشتیبانی میشود.
کسب اجازه برای برقراری ارتباط با وسیله جانبی
قبلاز برقراری ارتباط با لوازم جانبی USB، برنامه شما باید از کاربران شما اجازه داشته باشد.
توجه: اگر برنامه شما از فیلتر قصد استفاده میکند تا لوازم جانبی را هنگام اتصال شناسایی کند، بهطور خودکار اجازه دریافت میکند اگر کاربر به برنامه شما اجازه دهد قصد را مدیریت کند. اگر اینطور نیست، باید قبلاز اتصال به لوازم جانبی، بهطور صریح در برنامهتان درخواست اجازه کنید.
درخواست صریح برای اجازه ممکن است در برخی شرایط لازم باشد، مثلاً وقتی که برنامه شما لوازم جانبی را که قبلاً متصل شدهاند فهرست میکند و سپس میخواهد با یکی از آنها ارتباط برقرار کند. قبلاز تلاش برای برقراری ارتباط با لوازم جانبی، باید اجازه دسترسی به آن را بررسی کنید. اگر این کار را نکنید، درصورتیکه کاربر اجازه دسترسی به لوازم جانبی را رد کند، خطای زمان اجرا دریافت خواهید کرد.
برای دریافت صریح اجازه، ابتدا گیرنده رویداد ثبتشده ایجاد کنید. این گیرنده به قصدی که هنگام تماس با requestPermission() همهفرستی میشود گوش میدهد. فراخوانی requestPermission() کادر گفتگویی را به کاربر نمایش میدهد که از او برای اتصال به لوازم جانبی اجازه میخواهد. نمونه کد زیر نحوه ایجاد گیرنده رویداد ثبتشده را نشان میدهد:
کاتلین
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") } } } } }
جاوا
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() در فعالیتتان قرار دهید:
کاتلین
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)
جاوا
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() را فراخوانی کنید:
کاتلین
lateinit var accessory: UsbAccessory ... usbManager.requestPermission(accessory, permissionIntent)
جاوا
UsbAccessory accessory; ... usbManager.requestPermission(accessory, permissionIntent);
وقتی کاربران به کادر گفتگو پاسخ میدهند، گیرنده رویداد ثبتشده شما قصدی را دریافت میکند که حاوی
EXTRA_PERMISSION_GRANTED اضافی است که یک مقدار بولی
نشاندهنده پاسخ است. قبلاز متصل شدن به لوازم جانبی، این مقدار اضافی را برای مقدار true بررسی کنید.
برقراری ارتباط با لوازم جانبی
میتوانید بااستفاده از UsbManager با لوازم جانبی ارتباط برقرار کنید تا
توصیفگر فایلی را دریافت کنید که میتوانید جریانهای ورودی و خروجی را برای خواندن و نوشتن دادهها در
توصیفگر راهاندازی کنید. جریانها نشاندهنده نقاط پایانی انبوه ورودی و خروجی لوازم جانبی هستند. باید ارتباط بین دستگاه و لوازم جانبی را در رشته دیگری راهاندازی کنید تا رشته میانای کاربر اصلی را قفل نکنید. مثال زیر نحوه باز کردن وسیله جانبی برای برقراری ارتباط با آن را نشان میدهد:
کاتلین
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() } }
جاوا
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 از میانگیرهای بسته تا ۱۶۳۸۴ بایت پشتیبانی میکند، بنابراین برای سادگی میتوانید انتخاب کنید که همیشه میانگیر خود را با این اندازه اعلام کنید.
توجه: در سطح پایینتر، بستهها برای لوازم جانبی USB با سرعت کامل ۶۴ بایت و برای لوازم جانبی USB با سرعت بالا ۵۱۲ بایت هستند. پروتکل لوازم جانبی Android بستهها را برای هر دو سرعت در یک بسته منطقی برای سادگی دستهبندی میکند.
برای اطلاعات بیشتر درباره استفاده از رشتهها در Android، به فرایندها و رشتهها مراجعه کنید.
قطع ارتباط با لوازم جانبی
وقتی ارتباطتان با لوازم جانبی تمام شد یا اگر لوازم جانبی جدا شد،
توصیفگر فایلی را که با فراخوانی close() باز کردهاید ببندید.
برای گوش دادن به رویدادهای جداشده، یک گیرنده رویداد ثبتشده مانند زیر ایجاد کنید:
کاتلین
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 } } } }
جاوا
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 } } } };
ایجاد گیرنده رویداد ثبتشده در برنامه، و نه مانیفست، به برنامه شما اجازه میدهد فقط رویدادهای جداشده را درحین اجرا مدیریت کند. بهاینترتیب، رویدادهای جداشده فقط به برنامهای که درحالحاضر درحال اجرا است ارسال میشود و برای همه برنامهها پخش نمیشود.