Android Open Accessory 2.0

يصف هذا المستند التغييرات التي طرأت على بروتوكول "ملحق Android المفتوح" (AOA) منذ إصداره الأول، ويكمل مستندات AOA 1.0. أضافت AOAv2 الميزات التالية:

  • إخراج الصوت (ميزة متوقّفة نهائيًا في Android 8.0)
  • أن يكون الملحق متوافقًا مع جهاز Android لكي يعمل كجهاز واجهة بشرية واحد أو أكثر (HID)

لم يتم إجراء أي تغيير على واجهات برمجة تطبيقات Android SDK المتاحة لمطوّري تطبيقات Android.

رصد مدى توفّر بروتوكول AOAv2

لتحديد ما إذا كان جهاز Android المتصل متوافقًا مع الملحقات و إصدار البروتوكول المتوافق، يجب أن يرسل الملحق getProtocol() أمرًا ويتحقّق من النتيجة. بالنسبة إلى أجهزة Android التي تتيح استخدام الميزات في AOAv1 فقط، يجب أن تعرض القيمة 1 كإصدار البروتوكول، أما الأجهزة التي تتيح استخدام الميزات الإضافية في AOAv2، فيجب أن تعرض القيمة 2 كإصدار البروتوكول. يتوافق AOAv2 مع الإصدار الأول من AOAv، لذا تستمر الملحقات المصمّمة وفقًا لبروتوكول الملحقات الأصلي في العمل مع أجهزة Android الأحدث.

يوضّح المثال التالي من مكتبة رمز المصدر (<adk-src>/adk1/board/AndroidAccessory/AndroidAccessory.cpp) للعام 2011 من "مجموعة تطوير الملحقات" عملية التحقّق من البروتوكول:

bool AndroidAccessory::switchDevice(byte addr)
{
    int protocol = getProtocol(addr);
    if (protocol >= 1) {
        Serial.print("device supports protocol 1 or higher\n");
    } else {
        Serial.print("could not read device protocol version\n");
        return false;
    }

    sendString(addr, ACCESSORY_STRING_MANUFACTURER, manufacturer);
    sendString(addr, ACCESSORY_STRING_MODEL, model);
    sendString(addr, ACCESSORY_STRING_DESCRIPTION, description);
    sendString(addr, ACCESSORY_STRING_VERSION, version);
    sendString(addr, ACCESSORY_STRING_URI, uri);
    sendString(addr, ACCESSORY_STRING_SERIAL, serial);

    usb.ctrlReq(addr, 0, USB_SETUP_HOST_TO_DEVICE | USB_SETUP_TYPE_VENDOR |
                USB_SETUP_RECIPIENT_DEVICE, ACCESSORY_START, 0, 0, 0, 0, NULL);
    return true;
}

يتضمّن AOAv2 معرّفات منتجات USB جديدة لكل مجموعة من واجهات USB المتوفّرة في وضع الملحق:

الإصدار معرّف المنتج التواصل الوصف
AOAv1 0x2D00 الإكسسوار يوفّر نقطتَي نهاية مجمّعتَين للتواصل مع تطبيق Android.
0x2D01 الإكسسوار + adb لأغراض تصحيح الأخطاء أثناء تطوير الملحقات لا تتوفّر هذه الميزة إلا إذا كان المستخدم قد فعّل ميزة تصحيح أخطاء USB في إعدادات جهاز Android.
AOAv2 0x2D02 بعدّة لغات" لبث الصوت من جهاز Android إلى ملحق
0x2D03 audio + adb
0x2D04 إكسسوارات وملفات صوتية
0x2D05 accessory + audio + adb

إنّ أرقام تعريف المنتجات المستخدَمة في AOAv1 (0x2D00 و0x2D01) لا تزال متوافقة مع AOAv2.

الدعم الصوتي

يتضمّن AOAv2 ميزة إخراج الصوت من جهاز Android إلى أحد الملحقات من خلال واجهة فئة صوت USB عادية يمكنها بث صوت PCM بقناتَين و16 بت وبمعدل نقل بيانات يبلغ 44100 كيلوهرتز (قد تتم إضافة أوضاع صوت إضافية في المستقبل).

لتفعيل ميزة الصوت، يجب أن يرسل الملحق طلب التحكّم عبر USB الجديد: 

**SET_AUDIO_MODE**
requestType:    USB_DIR_OUT | USB_TYPE_VENDOR
request:        58
value:          0 for no audio (default),
                1 for 2 channel, 16-bit PCM at 44100 KHz
index:          0
data            none

يجب إرسال هذا الأمر قبل إرسال الأمر ACCESSORY_START للدخول إلى وضع الملحق.

إتاحة استخدام أجهزة HID

يسمح معيار AOAv2 للإكسسوارات بتسجيل جهاز واحد أو أكثر من أجهزة HID USB مع جهاز Android. يعكس هذا النهج اتجاه الاتصال لأجهزة USB HID النموذجية، مثل أجهزة الماوس ولوحات المفاتيح USB. عادةً ما يكون جهاز HID جهازًا ملحفًا متصلاً بمضيف USB (أي كمبيوتر شخصي)، ولكن في AOA يمكن أن يعمل مضيف USB كجهاز إدخال واحد أو أكثر لجهاز USB ملحق.

توفُّر HID هو بديل لأحداث HID العادية، ولا يستند التنفيذ إلى أي افتراضات حول محتوى الأحداث أو نوعها، بل يمررها ببساطة إلى نظام الإدخال، ما يتيح لملحق AOAv2 التصرف مثل أي جهاز HID (ماوس أو لوحة مفاتيح أو ذراع تحكّم في الألعاب أو غير ذلك). يمكنك استخدام HID لتوفير وظائف أساسية، مثل زر التشغيل/الإيقاف على محطة تثبيت الوسائط، أو لتوفير وظائف متقدّمة، مثل محطة تثبيت مزودة بماوس و لوحة مفاتيح QWERTY كاملة.

تضيف AOAv2 طلبات تحكّم جديدة عبر USB تسمح للإكسسوار بالعمل كأحد أجهزة إدخال HID أو أكثر على جهاز Android. تتم معالجة واجهة HID تمامًا من خلال طلبات التحكّم في نقطة النهاية صفر، لذا لا يلزم استخدام واجهة USB جديدة. طلبات التحكّم الجديدة الأربعة هي:

  • يُسجِّل ACCESSORY_REGISTER_HID جهاز HID جديدًا على جهاز Android. يقدّم الملحق رقم تعريف يُستخدَم لتحديد جهاز HID في الطلبات الثلاثة الأخرى. يظل هذا المعرّف صالحًا إلى أن ينقطع الاتصال عبر USB أو إلى أن يُرسِل الملحق ACCESSORY_UNREGISTER_HID لإلغاء تسجيل جهاز HID.
  • تؤدي رسالة ACCESSORY_UNREGISTER_HID إلى إلغاء تسجيل جهاز HID سبق أن تم تسجيله باستخدام ACCESSORY_REGISTER_HID.
  • يُرسِل ACCESSORY_SET_HID_REPORT_DESC وصف تقرير لجهاز HID إلى جهاز Android. يُستخدَم هذا الطلب لوصف إمكانات جهاز HID، ويجب إرساله قبل الإبلاغ عن أي أحداث HID على جهاز Android. إذا كان وصف التقرير أكبر من الحد الأقصى لحجم الحزمة لنقطة النهاية صفر، يتم إرسال عدة أوامر ACCESSORY_SET_HID_REPORT_DESC لنقل الوصف بالكامل.
  • يُرسِل ACCESSORY_SEND_HID_EVENT أحداث الإدخال من الملحق إلى جهاز Android.

في ما يلي تعريفات الرموز لطلبات التحكّم الجديدة:

/* Control request for registering a HID device.
 * Upon registering, a unique ID is sent by the accessory in the
 * value parameter. This ID will be used for future commands for
 * the device
 *
 *  requestType:    USB_DIR_OUT | USB_TYPE_VENDOR
 *  request:        ACCESSORY_REGISTER_HID_DEVICE
 *  value:          Accessory assigned ID for the HID device
 *  index:          total length of the HID report descriptor
 *  data            none
 */
#define ACCESSORY_REGISTER_HID         54

/* Control request for unregistering a HID device.
 *
 *  requestType:    USB_DIR_OUT | USB_TYPE_VENDOR
 *  request:        ACCESSORY_REGISTER_HID
 *  value:          Accessory assigned ID for the HID device
 *  index:          0
 *  data            none
 */
#define ACCESSORY_UNREGISTER_HID         55

/* Control request for sending the HID report descriptor.
 * If the HID descriptor is longer than the endpoint zero max packet size,
 * the descriptor will be sent in multiple ACCESSORY_SET_HID_REPORT_DESC
 * commands. The data for the descriptor must be sent sequentially
 * if multiple packets are needed.
 *
 *  requestType:    USB_DIR_OUT | USB_TYPE_VENDOR
 *  request:        ACCESSORY_SET_HID_REPORT_DESC
 *  value:          Accessory assigned ID for the HID device
 *  index:          offset of data in descriptor
 *                      (needed when HID descriptor is too big for one packet)
 *  data            the HID report descriptor
 */
#define ACCESSORY_SET_HID_REPORT_DESC         56

/* Control request for sending HID events.
 *
 *  requestType:    USB_DIR_OUT | USB_TYPE_VENDOR
 *  request:        ACCESSORY_SEND_HID_EVENT
 *  value:          Accessory assigned ID for the HID device
 *  index:          0
 *  data            the HID report for the event
 */
#define ACCESSORY_SEND_HID_EVENT         57

إمكانية التشغيل التفاعلي مع AOAv1

يقدّم البروتوكول الأصلي (AOAv1) إمكانية اتصال تطبيق Android مباشرةً بمنصّة USB (ملحق) عبر USB. يواصل AOAv2 توفير هذه الميزة ويضيف ميزات جديدة للسماح للملحق بالتواصل مع نظام التشغيل Android نفسه (وتحديدًا نظامَي الصوت والإدخال). يتيح تصميم AOAv2 إنشاء ملحق يستخدم ميزتَي الصوت وHID الجديدتَين بالإضافة إلى مجموعة الميزات الأصلية. ما عليك سوى استخدام الميزات الجديدة مع الميزات الأصلية.

ربط AOAv2 بدون تطبيق Android

يمكنك تصميم ملحق (مثل قاعدة صوتية) يستخدم ميزتَي الصوت وHID ، ولكن لا يتواصل مع تطبيق على جهاز Android. بالنسبة إلى هذه الملحقات، لا يحتاج المستخدمون إلى تلقّي طلبات حوار للعثور على الملحق المُرفق حديثًا وربطه بتطبيق Android يمكنه التواصل معه.

لإيقاف هذه المحادثات بعد توصيل أحد الملحقات، يمكن للملحق عدم إرسال اسم الشركة المصنّعة واسم الطراز إلى جهاز Android. في حال عدم تقديم هذه السلاسل إلى جهاز Android:

  • لا يحاول النظام العثور على تطبيق للتواصل مع الملحق.
  • لا تتوفّر واجهة USB المخصّصة للإكسسوار في إعدادات USB لجهاز Android بعد دخول الجهاز إلى وضع الإكسسوار.