אנדרואיד Open Accessory Protocol 2.0, אנדרואיד Open Accessory Protocol 2.0

מסמך זה מתאר שינויים בפרוטוקול ה-Android Open Accessory (AOA) מאז השחרור הראשוני שלו ומשלים את תיעוד AOA 1.0 . AOAv2 מוסיף את התכונות הבאות:

  • פלט אודיו (הוצא משימוש באנדרואיד 8.0).
  • תמיכה באביזר הפועל כמכשיר ממשק אנושי אחד או יותר (HIDs) למכשיר האנדרואיד.

ממשקי API של Android SDK הזמינים למפתחי אפליקציות אנדרואיד אינם משתנים.

זיהוי תמיכת AOAv2

כדי לקבוע אם מכשיר אנדרואיד מחובר תומך באביזרים ובגרסת הפרוטוקול הנתמכת, אביזר חייב לשלוח getProtocol() ולבדוק את התוצאה. מכשירי אנדרואיד התומכים רק בתכונות ב-AOAv1 חייבים להחזיר 1 כגרסת הפרוטוקול; התקנים התומכים בתכונות הנוספות ב-AOAv2 חייבים להחזיר 2 כגרסת הפרוטוקול. AOAv2 תואם לאחור עם AOAv1, כך שאביזרים המיועדים לפרוטוקול האביזרים המקורי ממשיכים לעבוד עם מכשירי אנדרואיד חדשים יותר.

הדוגמה הבאה מספריית ה-Accessory Development Kit 2011 (< adk <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 אבזר מספק שתי נקודות קצה בכמות גדולה לתקשורת עם יישום אנדרואיד.
0x2D01 אביזר + adb למטרות איתור באגים במהלך פיתוח אביזרים. זמין רק אם המשתמש איפשר איתור באגים ב-USB בהגדרות מכשיר אנדרואיד.
AOAv2 0x2D02 שֶׁמַע להזרמת אודיו ממכשיר אנדרואיד לאביזר.
0x2D03 אודיו + adb
0x2D04 אביזר + אודיו
0x2D05 אביזר + אודיו + adb

מזהי מוצר המשמשים ב-AOAv1 ( 0x2D00 ו- 0x2D01 ) ממשיכים להיות נתמכים ב-AOAv2.

תמיכה באודיו

AOAv2 כולל תמיכה בפלט אודיו ממכשיר אנדרואיד לאביזר באמצעות ממשק USB אודיו סטנדרטי המסוגל לאודיו 2 ערוצים, 16 סיביות PCM עם קצב סיביות של 44100 Khz (ייתכן שיתווספו מצבי שמע נוספים בעתיד).

כדי לאפשר תמיכה בשמע, האביזר חייב לשלוח בקשת בקרת 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 מאפשר לאביזרים לרשום התקני ממשק אנושי USB אחד או יותר (HID) עם מכשיר אנדרואיד. גישה זו הופכת את כיוון התקשורת עבור התקני USB HID טיפוסיים כגון עכברי USB ומקלדות. בדרך כלל, התקן ה-HID הוא ציוד היקפי המחובר למארח USB (כלומר מחשב אישי), אך ב-AOA מארח ה-USB יכול לפעול כהתקן קלט אחד או יותר לציוד היקפי USB.

תמיכת HID היא פרוקסי לאירועי HID סטנדרטיים; היישום אינו מניח הנחות לגבי התוכן או סוג האירועים ופשוט מעביר אותם למערכת הקלט, מה שמאפשר לאביזר AOAv2 לפעול ככל התקן HID (עכבר, מקלדת, בקר משחק וכו'). אתה יכול להשתמש בתמיכת HID כדי לספק פונקציונליות בסיסית, כגון לחצן הפעלה/השהה בתחנת עגינה למדיה, או לפונקציונליות מתקדמת כגון תחנת עגינה עם עכבר ומקלדת QWERTY מלאה.

AOAv2 מוסיף בקשות חדשות לבקרת USB המאפשרות לאביזר לפעול כהתקן קלט HID אחד או יותר למכשיר האנדרואיד. תמיכת HID מטופלת כולה באמצעות בקשות בקרה בנקודת קצה אפס, כך שאין צורך בממשק USB חדש. ארבע בקשות הבקרה החדשות הן:

  • ACCESSORY_REGISTER_HID רושם מכשיר HID חדש במכשיר האנדרואיד. האביזר מספק מזהה המשמש לזיהוי התקן HID עבור שלוש השיחות האחרות. מזהה זה תקף עד שה-USB יתנתק או עד שהאביזר ישלח את ACCESSORY_UNREGISTER_HID כדי לבטל את הרישום של התקן HID.
  • ACCESSORY_UNREGISTER_HID מבטל את הרישום של מכשיר HID שנרשם בעבר ב- ACCESSORY_REGISTER_HID .
  • ACCESSORY_SET_HID_REPORT_DESC שולח מתאר דוח עבור מכשיר HID למכשיר Android. בקשה זו משמשת לתיאור היכולות של מכשיר ה-HID ויש לשלוח אותה לפני דיווח על אירועי HID למכשיר האנדרואיד. אם מתאר הדוח גדול מגודל החבילה המרבי עבור נקודת הקצה אפס, נשלחות מספר פקודות 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 ) מספק תמיכה עבור יישום אנדרואיד לתקשורת ישירה עם מארח USB (אביזר) באמצעות USB. AOAv2 ממשיך בתמיכה זו ומוסיף תכונות חדשות כדי לאפשר לאביזר לתקשר עם מערכת ההפעלה אנדרואיד עצמה (במיוחד מערכות השמע והקלט). העיצוב של AOAv2 מאפשר לבנות אביזר המשתמש בתמיכת האודיו וה-HID החדשה בנוסף למערך התכונות המקורי. פשוט השתמש בתכונות החדשות יחד עם התכונות המקוריות.

חיבור AOAv2 ללא אפליקציית אנדרואיד

ניתן לעצב אביזר (כגון תחנת עגינה לשמע) המשתמש בתמיכה באודיו וב-HID אך אינו מתקשר עם אפליקציה במכשיר האנדרואיד. עבור אביזרים אלו, המשתמשים אינם צריכים לקבל הודעות דו-שיח לאיתור ושיוך האביזר החדש שצורף לאפליקציית אנדרואיד שיכולה לתקשר איתו.

כדי לדכא דיאלוגים כאלה לאחר חיבור אביזר, האביזר יכול לבחור שלא לשלוח את שמות היצרן והדגמים למכשיר האנדרואיד. כאשר המחרוזות הללו אינן מסופקות למכשיר האנדרואיד:

  • המערכת לא מנסה למצוא אפליקציה לתקשורת עם האביזר.
  • ממשק ה-USB של האביזרים אינו קיים בתצורת ה-USB של מכשיר אנדרואיד לאחר שהמכשיר נכנס למצב אביזר.
,

מסמך זה מתאר שינויים בפרוטוקול ה-Android Open Accessory (AOA) מאז השחרור הראשוני שלו ומשלים את תיעוד AOA 1.0 . AOAv2 מוסיף את התכונות הבאות:

  • פלט אודיו (הוצא משימוש באנדרואיד 8.0).
  • תמיכה באביזר הפועל כמכשיר ממשק אנושי אחד או יותר (HIDs) למכשיר האנדרואיד.

ממשקי API של Android SDK הזמינים למפתחי אפליקציות אנדרואיד אינם משתנים.

זיהוי תמיכת AOAv2

כדי לקבוע אם מכשיר אנדרואיד מחובר תומך באביזרים ובגרסת הפרוטוקול הנתמכת, אביזר חייב לשלוח getProtocol() ולבדוק את התוצאה. מכשירי אנדרואיד התומכים רק בתכונות ב-AOAv1 חייבים להחזיר 1 כגרסת הפרוטוקול; התקנים התומכים בתכונות הנוספות ב-AOAv2 חייבים להחזיר 2 כגרסת הפרוטוקול. AOAv2 תואם לאחור עם AOAv1, כך שאביזרים המיועדים לפרוטוקול האביזרים המקורי ממשיכים לעבוד עם מכשירי אנדרואיד חדשים יותר.

הדוגמה הבאה מספריית ה-Accessory Development Kit 2011 (< adk <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 אבזר מספק שתי נקודות קצה בכמות גדולה לתקשורת עם יישום אנדרואיד.
0x2D01 אביזר + adb למטרות איתור באגים במהלך פיתוח אביזרים. זמין רק אם המשתמש איפשר איתור באגים ב-USB בהגדרות מכשיר אנדרואיד.
AOAv2 0x2D02 שֶׁמַע להזרמת אודיו ממכשיר אנדרואיד לאביזר.
0x2D03 אודיו + adb
0x2D04 אביזר + אודיו
0x2D05 אביזר + אודיו + adb

מזהי מוצר המשמשים ב-AOAv1 ( 0x2D00 ו- 0x2D01 ) ממשיכים להיות נתמכים ב-AOAv2.

תמיכה באודיו

AOAv2 כולל תמיכה בפלט אודיו ממכשיר אנדרואיד לאביזר באמצעות ממשק USB אודיו סטנדרטי המסוגל לאודיו 2 ערוצים, 16 סיביות PCM עם קצב סיביות של 44100 Khz (ייתכן שיתווספו מצבי שמע נוספים בעתיד).

כדי לאפשר תמיכה בשמע, האביזר חייב לשלוח בקשת בקרת 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 מאפשר לאביזרים לרשום התקני ממשק אנושי USB אחד או יותר (HID) עם מכשיר אנדרואיד. גישה זו הופכת את כיוון התקשורת עבור התקני USB HID טיפוסיים כגון עכברי USB ומקלדות. בדרך כלל, התקן ה-HID הוא ציוד היקפי המחובר למארח USB (כלומר מחשב אישי), אך ב-AOA מארח ה-USB יכול לפעול כהתקן קלט אחד או יותר לציוד היקפי USB.

תמיכת HID היא פרוקסי לאירועי HID סטנדרטיים; היישום אינו מניח הנחות לגבי התוכן או סוג האירועים ופשוט מעביר אותם למערכת הקלט, מה שמאפשר לאביזר AOAv2 לפעול ככל התקן HID (עכבר, מקלדת, בקר משחק וכו'). אתה יכול להשתמש בתמיכת HID כדי לספק פונקציונליות בסיסית, כגון לחצן הפעלה/השהה בתחנת עגינה למדיה, או לפונקציונליות מתקדמת כגון תחנת עגינה עם עכבר ומקלדת QWERTY מלאה.

AOAv2 מוסיף בקשות חדשות לבקרת USB המאפשרות לאביזר לפעול כהתקן קלט HID אחד או יותר למכשיר האנדרואיד. תמיכת HID מטופלת כולה באמצעות בקשות בקרה בנקודת קצה אפס, כך שאין צורך בממשק USB חדש. ארבע בקשות הבקרה החדשות הן:

  • ACCESSORY_REGISTER_HID רושם מכשיר HID חדש במכשיר האנדרואיד. האביזר מספק מזהה המשמש לזיהוי התקן HID עבור שלוש השיחות האחרות. מזהה זה תקף עד שה-USB יתנתק או עד שהאביזר ישלח את ACCESSORY_UNREGISTER_HID כדי לבטל את הרישום של התקן HID.
  • ACCESSORY_UNREGISTER_HID מבטל את הרישום של מכשיר HID שנרשם בעבר ב- ACCESSORY_REGISTER_HID .
  • ACCESSORY_SET_HID_REPORT_DESC שולח מתאר דוח עבור מכשיר HID למכשיר Android. בקשה זו משמשת לתיאור היכולות של מכשיר ה-HID ויש לשלוח אותה לפני דיווח על אירועי HID למכשיר האנדרואיד. אם מתאר הדוח גדול מגודל החבילה המרבי עבור נקודת הקצה אפס, נשלחות מספר פקודות 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 ) מספק תמיכה עבור יישום אנדרואיד לתקשורת ישירה עם מארח USB (אביזר) באמצעות USB. AOAv2 ממשיך בתמיכה זו ומוסיף תכונות חדשות כדי לאפשר לאביזר לתקשר עם מערכת ההפעלה אנדרואיד עצמה (במיוחד מערכות השמע והקלט). העיצוב של AOAv2 מאפשר לבנות אביזר המשתמש בתמיכת האודיו וה-HID החדשה בנוסף למערך התכונות המקורי. פשוט השתמש בתכונות החדשות יחד עם התכונות המקוריות.

חיבור AOAv2 ללא אפליקציית אנדרואיד

ניתן לעצב אביזר (כגון תחנת עגינה לשמע) המשתמש בתמיכה בשמע וב-HID אך אינו מתקשר עם אפליקציה במכשיר האנדרואיד. עבור אביזרים אלה, המשתמשים אינם צריכים לקבל הודעות דו-שיח לאיתור ושיוך האביזר החדש שצורף לאפליקציית אנדרואיד שיכולה לתקשר איתו.

כדי לדכא דיאלוגים כאלה לאחר חיבור אביזר, האביזר יכול לבחור שלא לשלוח את שמות היצרן והדגמים למכשיר האנדרואיד. כאשר המחרוזות הללו אינן מסופקות למכשיר האנדרואיד:

  • המערכת לא מנסה למצוא אפליקציה לתקשורת עם האביזר.
  • ממשק ה-USB של האביזרים אינו קיים בתצורת ה-USB של מכשיר אנדרואיד לאחר שהמכשיר נכנס למצב אביזר.