أندرويد مفتوح الملحقات 2.0

يصف هذا المستند التغييرات في بروتوكول Android Open Accessories (AOA) منذ إصداره الأولي ويكمل وثائق AOA 1.0 . يضيف AOAv2 الميزات التالية:

  • إخراج الصوت (مهمل في Android 8.0).
  • دعم الملحق الذي يعمل كجهاز واجهة بشرية واحد أو أكثر (HIDs) لجهاز Android.

لم تتغير واجهات برمجة تطبيقات Android SDK المتاحة لمطوري تطبيقات Android.

الكشف عن دعم AOAv2

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

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

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 ملحق + بنك التنمية الآسيوي لأغراض تصحيح الأخطاء أثناء تطوير الملحقات. متاح فقط إذا قام المستخدم بتمكين تصحيح أخطاء USB في إعدادات جهاز Android.
AOAv2 0x2D02 صوتي لبث الصوت من جهاز Android إلى أحد الملحقات.
0x2D03 الصوت + بنك التنمية الآسيوي
0x2D04 ملحق + صوت
0x2D05 ملحق + صوت + 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 للدخول إلى وضع الملحقات.

اختبأ الدعم

يسمح AOAv2 للملحقات بتسجيل جهاز USB بشري واحد أو أكثر (HID) مع جهاز 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 بعد دخول الجهاز في وضع الملحق.