安卓開放附件協議2.0,安卓開放附件協議2.0

本文檔描述了 Android 開放附件 (AOA) 協議自其初始版本以來的變化,並補充了AOA 1.0 文檔。 AOAv2 增加了以下功能:

  • 音頻輸出(在 Android 8.0 中已棄用)。
  • 支持充當 Android 設備的一個或多個人機接口設備 (HID) 的附件。

Android 應用程序開發人員可用的 Android SDK API 保持不變。

檢測 AOAv2 支持

要確定連接的 Android 設備是否支持配件和支持的協議版本,配件必鬚髮送getProtocol()命令並檢查結果。僅支持 AOAv1 中功能的 Android 設備必須返回1作為協議版本;支持 AOAv2 中附加功能的設備必須返回2作為協議版本。 AOAv2 與 AOAv1 向後兼容,因此為原始配件協議設計的配件繼續適用於較新的 Android 設備。

以下來自 Accessory Development Kit 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 產品 ID,適用於配件模式下可用的每種 USB 接口組合:

版本產品編號溝通描述
AOv1 0x2D00配飾提供兩個用於與 Android 應用程序通信的批量端點。
0x2D01附件 + adb用於附件開發期間的調試目的。僅當用戶在 Android 設備設置中啟用了USB 調試時才可用。
AOAv2 0x2D02聲音的用於將音頻從 Android 設備流式傳輸到附件。
0x2D03音頻 + adb
0x2D04配件+音頻
0x2D05配件 + 音頻 + adb

AOAv1 中使用的產品 ID( 0x2D000x2D01 )在 AOAv2 中繼續受支持。

音頻支持

AOAv2 支持通過標準 USB 音頻類接口將音頻從 Android 設備輸出到配件,該接口支持 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命令以進入附件模式之前發送。

隱藏支持

AOAv2 允許配件向 Android 設備註冊一個或多個 USB 人機接口設備 (HID)。這種方法顛倒了典型 USB HID 設備(例如 USB 鼠標和鍵盤)的通信方向。通常,HID 設備是連接到 USB 主機(即個人計算機)的外圍設備,但在 AOA 中,USB 主機可以充當 USB 外圍設備的一個或多個輸入設備。

HID 支持是標準 HID 事件的代理;該實現對事件的內容或類型不做任何假設,只是將其傳遞給輸入系統,使 AOAv2 附件能夠充當任何 HID 設備(鼠標、鍵盤、遊戲控制器等)。您可以使用 HID 支持來提供基本功能,例如媒體基座上的播放/暫停按鈕,或提供高級功能,例如帶有鼠標和完整 QWERTY 鍵盤的擴展塢。

AOAv2 添加了新的 USB 控制請求,允許配件充當 Android 設備的一個或多個 HID 輸入設備。 HID 支持完全通過端點零上的控制請求來處理,因此不需要新的 USB 接口。四個新的控制請求是:

  • ACCESSORY_REGISTER_HID向 Android 設備註冊一個新的 HID 設備。附件提供了一個 ID,用於識別其他三個呼叫的 HID 設備。此 ID 在 USB 斷開連接或配件發送ACCESSORY_UNREGISTER_HID以取消註冊 HID 設備之前有效。
  • ACCESSORY_UNREGISTER_HID取消註冊以前使用ACCESSORY_REGISTER_HID註冊的 HID 設備。
  • ACCESSORY_SET_HID_REPORT_DESC將 HID 設備的報告描述符發送到 Android 設備。此請求用於描述 HID 設備的功能,必須在向 Android 設備報告任何 HID 事件之前發送。如果報告描述符大於端點 0 的最大數據包大小,則發送多個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 支持的配件成為可能。只需將新功能與原始功能一起使用即可。

在沒有 Android 應用程序的情況下連接 AOAv2

您可以設計一個使用音頻和 HID 支持但不與 Android 設備上的應用程序通信的附件(例如音頻基座)。對於這些附件,用戶不需要接收對話框提示來查找新連接的附件並將其與可以與之通信的 Android 應用程序相關聯。

要在配件連接後抑制此類對話框,配件可以選擇不向 Android 設備發送製造商和型號名稱。當這些字符串沒有提供給 Android 設備時:

  • 系統不會嘗試找到與附件通信的應用程序。
  • 設備進入配件模式後,Android 設備 USB 配置中不存在配件 USB 接口。
,

本文檔描述了 Android 開放附件 (AOA) 協議自其初始版本以來的變化,並補充了AOA 1.0 文檔。 AOAv2 增加了以下功能:

  • 音頻輸出(在 Android 8.0 中已棄用)。
  • 支持充當 Android 設備的一個或多個人機接口設備 (HID) 的附件。

Android 應用程序開發人員可用的 Android SDK API 保持不變。

檢測 AOAv2 支持

要確定連接的 Android 設備是否支持配件和支持的協議版本,配件必鬚髮送getProtocol()命令並檢查結果。僅支持 AOAv1 中功能的 Android 設備必須返回1作為協議版本;支持 AOAv2 中附加功能的設備必須返回2作為協議版本。 AOAv2 與 AOAv1 向後兼容,因此為原始配件協議設計的配件繼續適用於較新的 Android 設備。

以下來自 Accessory Development Kit 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 產品 ID,適用於配件模式下可用的每種 USB 接口組合:

版本產品編號溝通描述
AOv1 0x2D00配飾提供兩個用於與 Android 應用程序通信的批量端點。
0x2D01附件 + adb用於附件開發期間的調試目的。僅當用戶在 Android 設備設置中啟用了USB 調試時才可用。
AOAv2 0x2D02聲音的用於將音頻從 Android 設備流式傳輸到附件。
0x2D03音頻 + adb
0x2D04配件+音頻
0x2D05配件 + 音頻 + adb

AOAv1 中使用的產品 ID( 0x2D000x2D01 )在 AOAv2 中繼續受支持。

音頻支持

AOAv2 支持通過標準 USB 音頻類接口將音頻從 Android 設備輸出到配件,該接口支持 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命令以進入附件模式之前發送。

隱藏支持

AOAv2 允許配件向 Android 設備註冊一個或多個 USB 人機接口設備 (HID)。這種方法顛倒了典型 USB HID 設備(例如 USB 鼠標和鍵盤)的通信方向。通常,HID 設備是連接到 USB 主機(即個人計算機)的外圍設備,但在 AOA 中,USB 主機可以充當 USB 外圍設備的一個或多個輸入設備。

HID 支持是標準 HID 事件的代理;該實現對事件的內容或類型不做任何假設,只是將其傳遞給輸入系統,使 AOAv2 附件能夠充當任何 HID 設備(鼠標、鍵盤、遊戲控制器等)。您可以使用 HID 支持來提供基本功能,例如媒體基座上的播放/暫停按鈕,或提供高級功能,例如帶有鼠標和完整 QWERTY 鍵盤的擴展塢。

AOAv2 添加了新的 USB 控制請求,允許配件充當 Android 設備的一個或多個 HID 輸入設備。 HID 支持完全通過端點零上的控制請求來處理,因此不需要新的 USB 接口。四個新的控制請求是:

  • ACCESSORY_REGISTER_HID向 Android 設備註冊一個新的 HID 設備。附件提供了一個 ID,用於識別其他三個呼叫的 HID 設備。此 ID 在 USB 斷開連接或配件發送ACCESSORY_UNREGISTER_HID以取消註冊 HID 設備之前有效。
  • ACCESSORY_UNREGISTER_HID取消註冊以前使用ACCESSORY_REGISTER_HID註冊的 HID 設備。
  • ACCESSORY_SET_HID_REPORT_DESC將 HID 設備的報告描述符發送到 Android 設備。此請求用於描述 HID 設備的功能,必須在向 Android 設備報告任何 HID 事件之前發送。如果報告描述符大於端點 0 的最大數據包大小,則發送多個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 支持的配件成為可能。只需將新功能與原始功能一起使用即可。

在沒有 Android 應用程序的情況下連接 AOAv2

您可以設計一個使用音頻和 HID 支持但不與 Android 設備上的應用程序通信的附件(例如音頻基座)。對於這些附件,用戶不需要接收對話框提示來查找新連接的附件並將其與可以與之通信的 Android 應用程序相關聯。

要在配件連接後抑制此類對話框,配件可以選擇不向 Android 設備發送製造商和型號名稱。當這些字符串沒有提供給 Android 設備時:

  • 系統不會嘗試找到與附件通信的應用程序。
  • 設備進入配件模式後,Android 設備 USB 配置中不存在配件 USB 接口。