Протокол HID трекера головы

Протокол отслеживания положения головы (HID), доступный для устройств под управлением Android 13 и выше, позволяет подключать устройство отслеживания положения головы к устройству Android через USB или Bluetooth и предоставлять к нему доступ через платформу Android и приложения через платформу датчиков . Этот протокол используется для управления эффектом виртуализации звука (3D-аудио). На этой странице термины «устройство» и «хост» используются в значении Bluetooth, где «устройство» означает устройство отслеживания положения головы, а «хост» — хост Android.

Производители устройств должны настроить свои устройства Android для включения поддержки протокола HID для отслеживания положения головы. Более подробную информацию о настройке см. в файле README динамических датчиков .

Предполагается, что вы знакомы со следующими ресурсами:

Структура верхнего уровня

В среде Android устройство отслеживания положения головы идентифицируется как HID-устройство.

Полный пример допустимого дескриптора HID см. в Приложении 1: Пример дескриптора HID .

На верхнем уровне устройство отслеживания положения головы представляет собой набор приложений, включающий страницу Sensors ( 0x20 ) и раздел Other: Custom использование» ( 0xE1 ). Внутри этого набора находятся несколько полей данных ( входов ) и свойств ( функций ).

Свойства и поля данных

В этом разделе описываются свойства и поля данных в наборе приложений устройства отслеживания положения головы.

Свойство: Описание датчика ( 0x0308 )

Свойство «Описание датчика» ( 0x0308 ) представляет собой строковое свойство в формате ASCII (8 бит), доступное только для чтения, и должно содержать следующие значения:

Версия 1.0 системы отслеживания движений головы:

#AndroidHeadTracker#1.0

Версия 2.0 системы отслеживания движений головы (доступна в Android 15 и выше), которая включает поддержку звука LE:

#AndroidHeadTracker#2.0#x

x — целое число ( 1 , 2 , 3 ), указывающее на тип транспортируемой опоры:

  • 1: ACL
  • 2: ISO
  • 3: ACL + ISO

Нулевой терминатор не ожидается, а это значит, что общий размер этого свойства составляет 23 8-битных символа для версии 1.0.

Это свойство служит в качестве дискриминатора, позволяющего избежать столкновений с другими пользовательскими датчиками.

Свойство: Постоянный уникальный идентификатор ( 0x0302 )

Свойство Persistent Unique ID ( 0x0302 ) представляет собой массив из 16 элементов, доступных только для чтения, каждый по 8 бит (всего 128 бит). Нулевой символ-терминатор не ожидается. Это свойство является необязательным.

Это свойство позволяет устройствам отслеживания положения головы, встроенным в аудиоустройства, ссылаться на аудиоустройство, к которому они подключены. Поддерживаются следующие схемы.

Автономный трекер головы

Если свойство «Постоянный уникальный идентификатор» ( 0x0302 ) отсутствует или установлено на все нули, это означает, что устройство отслеживания положения головы не подключено постоянно к аудиоустройству и может использоваться отдельно, например, путем предоставления пользователю возможности вручную связать устройство отслеживания положения головы с отдельным аудиоустройством.

Ссылка на источник, использующая MAC-адрес Bluetooth.

Октет 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
Ценить 0 0 0 0 0 0 0 0 Б Т Bluetooth MAC

В этой схеме первые 8 октетов должны быть 0 , октеты 8 и 9 должны содержать значения ASCII B и T соответственно, а следующие 6 октетов интерпретируются как MAC-адрес Bluetooth, предполагая, что устройство отслеживания положения головы работает с любым аудиоустройством, имеющим этот MAC-адрес. Этот адрес должен быть идентификационным адресом, даже если устройство использует случайный MAC-адрес для установления соединения. Двухрежимные устройства, подключающиеся по Bluetooth Classic (формат HID v1.0) и Bluetooth LE (формат HID v2.0), должны предоставлять два дескриптора HID с одним и тем же идентификационным адресом. Двухрежимные устройства с раздельными левым и правым устройствами должны предоставлять Bluetooth LE HID, используя основное двухрежимное устройство, а не дополнительное устройство, работающее только с LE.

Ссылка с использованием UUID

Когда старший бит (MSB) 8-го октета установлен ( ≥0x80 ), поле интерпретируется как UUID, как указано в RFC-4122 . Соответствующее аудиоустройство предоставляет тот же UUID, который регистрируется в среде Android, посредством неуказанного механизма, специфичного для используемого типа транспорта.

Свойство: Отчитывающееся состояние ( 0x0316 )

Свойство Reporting State ( 0x0316 ) является свойством чтения/записи и имеет стандартную семантику, определенную в спецификации HID. Хост использует это свойство, чтобы указать устройству, какие события следует сообщать. Используются только значения No Events ( 0x0840 ) и All Events ( 0x0841 ).

Начальное значение этого поля должно быть «Нет событий», и оно никогда не должно изменяться устройством, только хостом.

Свойство: Состояние питания ( 0x0319 )

Свойство Power State ( 0x0319 ) является свойством чтения/записи и имеет стандартную семантику, определенную в спецификации HID. Хост использует это свойство, чтобы указать устройству, в каком состоянии питания оно должно находиться. Используются только значения Full Power ( 0x0851 ) и Power Off ( 0x0855 ).

Начальное значение этого поля определяется устройством и ни в коем случае не должно изменяться устройством, только хостом.

Свойство: Интервал отчета ( 0x030E )

Свойство «Интервал отчета» ( 0x030E ) — это свойство чтения/записи, имеющее стандартную семантику, определенную в спецификации HID. Хост использует это свойство, чтобы указать устройству, как часто следует сообщать о показаниях данных. Единицы измерения — секунды. Допустимый диапазон для этого значения определяется устройством и описывается с помощью механизма «Физический минимум/максимум». Должна поддерживаться частота отчетов не менее 50 Гц, а рекомендуемая максимальная частота составляет 100 Гц. Следовательно, минимальный интервал отчета должен быть меньше или равен 20 мс, а рекомендуемый — больше или равен 10 мс.

Объект: Зарезервированный продавцом LE Transport ( 0xF410 )

Свойство Vendor-reserved LE Transport ( 0xF410 ) является свойством чтения/записи и имеет стандартную семантику, определенную в спецификации HID. Хост использует это свойство для указания выбранного транспорта (ACL или ISO). Используются только значения ACL ( 0xF800 ) и ISO ( 0xF801 ), и оба должны быть включены в логическую коллекцию.

Этот параметр настраивается до включения питания или передачи данных.

Поле данных: Пользовательское значение 1 ( 0x0544 )

Поле «Пользовательское значение 1» ( 0x0544 ) — это поле ввода, используемое для отображения фактической информации о отслеживании положения головы. Это массив из 3 элементов, интерпретируемый в соответствии со стандартными правилами HID для физических значений, как указано в разделе 6.2.2.7 спецификации HID. Допустимый диапазон для каждого элемента — [-π, π] рад. Единицы измерения всегда — радианы.

Элементы интерпретируются как: [rx, ry, rz] , где [rx, ry, rz] — вектор вращения , представляющий преобразование из системы отсчета в систему координат головы. Величина должна находиться в диапазоне [0..π].

Система координат произвольная, но, как правило, фиксированная и должна быть правосторонней. Небольшое смещение допустимо. Оси головки:

  • X от левого уха к правому
  • Y от затылка к носу (сзади вперед).
  • Z от шеи до макушки головы

Поле данных: Пользовательское значение 2 ( 0x0545 )

Поле «Пользовательское значение 2» ( 0x0545 ) — это поле ввода, используемое для отображения фактической информации о отслеживании положения головы. Это массив из 3 элементов с фиксированной запятой, интерпретируемый в соответствии со стандартными правилами HID для физических значений. Единицы измерения всегда — радианы в секунду.

Элементы интерпретируются как: [vx, vy, vz] , где [vx, vy, vz] — вектор вращения , представляющий угловую скорость системы координат головы (относительно самой себя).

Поле данных: Пользовательское значение 3 ( 0x0546 )

Поле «Пользовательское значение 3» ( 0x0546 ) — это входное поле, используемое для отслеживания разрывов в системе координат. Это скалярное целое число размером 8 бит. Устройство должно увеличивать его (с циклом) каждый раз при изменении системы координат, например, если алгоритм фильтрации ориентации, используемый для определения ориентации, сбросил свое состояние. Это значение интерпретируется в соответствии с обычными правилами HID для физических значений. Однако физическое значение и единицы измерения не имеют значения. Единственная информация, имеющая значение для хоста, — это измененное значение. Чтобы избежать числовых проблем, связанных с потерей точности при преобразовании из логических единиц в физические, рекомендуется установить значения физического минимума, физического максимума и показателя степени единицы измерения равными нулю для этого поля.

Структура отчета

Группировка свойств в отчеты (по присвоению идентификаторов отчетов) является гибкой. Для повышения эффективности мы рекомендуем разделять свойства, доступные только для чтения, от свойств, доступных для чтения и записи.

Что касается полей данных, то поля «Пользовательское значение 1», «2» и «3» должны находиться в одном отчете и только в одном отчете для данного устройства (коллекции приложений).

Отправка отчетов о вводе

Устройство должно периодически и асинхронно (посредством сообщений HID INPUT) отправлять отчеты о входных данных, когда выполняются все эти условия:

  • Свойство Power State установлено в значение Full Power.
  • Для свойства «Состояние отчетности» установлено значение «Все события».
  • Свойство «Интервал отчетности» не равно нулю.

Свойство «Интервал отправки отчетов» определяет, как часто следует отправлять отчеты. Если какое-либо из вышеперечисленных условий не выполняется, устройство не должно отправлять никаких отчетов.

Прямая и обратная совместимость

Протокол отслеживания положения головы HID использует схему версионирования, которая позволяет обновлять протокол, обеспечивая при этом совместимость между хостом и устройством, использующими разные версии протокола. Версии протокола обозначаются двумя числами: основным и дополнительным, которые имеют различное значение, как описано в следующих разделах.

Поддерживаемые устройством версии можно определить, изучив свойство Sensor Description ( 0x0308 ).

Совместимость с минорными версиями

Изменения в минорной версии обратно совместимы с более ранними минорными версиями, основанными на той же основной версии. При обновлении минорной версии хост игнорирует дополнительные поля данных и свойства. Например, устройство, использующее протокол версии 1.6, совместимо с хостом, поддерживающим протокол версии 1.x, включая версию 1.5.

совместимость основных версий

Для внесения изменений в основные версии допускаются изменения, несовместимые с предыдущими версиями. Для обеспечения совместимости со старыми и новыми хостами и поддержки нескольких основных версий устройства могут указывать несколько коллекций приложений в своих дескрипторах отчетов. Например:

const unsigned char ReportDescriptor[] = {
    HID_USAGE_PAGE_SENSOR,
    HID_USAGE_SENSOR_TYPE_OTHER_CUSTOM,

    HID_COLLECTION(HID_APPLICATION),
        // Feature report 2 (read-only).
        HID_REPORT_ID(2),

        // Magic value: "#AndroidHeadTracker#1.5"
        HID_USAGE_SENSOR_PROPERTY_SENSOR_DESCRIPTION,
        HID_LOGICAL_MIN_8(0),
        HID_LOGICAL_MAX_8(0xFF),
        HID_REPORT_SIZE(8),
        HID_REPORT_COUNT(23),
        HID_FEATURE(HID_CONST_VAR_ABS),

      ...

    HID_END_COLLECTION,

    HID_COLLECTION(HID_APPLICATION),
        // Feature report 12 (read-only).
        HID_REPORT_ID(12),

        // Magic value: "#AndroidHeadTracker#2.4"
        HID_USAGE_SENSOR_PROPERTY_SENSOR_DESCRIPTION,
        HID_LOGICAL_MIN_8(0),
        HID_LOGICAL_MAX_8(0xFF),
        HID_REPORT_SIZE(8),
        HID_REPORT_COUNT(23),
        HID_FEATURE(HID_CONST_VAR_ABS),

      ...

    HID_END_COLLECTION,
};

В этом случае хост может перечислить все различные коллекции приложений, рекламируемые устройством, изучив свойство Sensor Description, чтобы определить версии протоколов, которые реализует каждая из них, а затем выбрать последнюю поддерживаемую хостом версию протокола. После выбора хост будет работать с единственным протоколом, выбранным на протяжении всего времени подключения устройства.

Приложение: Пример дескриптора HID

В следующем примере показан типичный допустимый дескриптор HID-датчика. В нем используются широко распространенные макросы C, описанные в разделе «Использование HID-датчиков» (раздел 4.1).

const unsigned char ReportDescriptor[] = {
    HID_USAGE_PAGE_SENSOR,
    HID_USAGE_SENSOR_TYPE_OTHER_CUSTOM,
    HID_COLLECTION(HID_APPLICATION),
        // Feature report 2 (read-only).
        HID_REPORT_ID(2),

        // Magic value: "#AndroidHeadTracker#1.0"
        HID_USAGE_SENSOR_PROPERTY_SENSOR_DESCRIPTION,
        HID_LOGICAL_MIN_8(0),
        HID_LOGICAL_MAX_8(0xFF),
        HID_REPORT_SIZE(8),
        HID_REPORT_COUNT(23),
        HID_FEATURE(HID_CONST_VAR_ABS),

        // UUID.
        HID_USAGE_SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID,
        HID_LOGICAL_MIN_8(0),
        HID_LOGICAL_MAX_8(0xFF),
        HID_REPORT_SIZE(8),
        HID_REPORT_COUNT(16),
        HID_FEATURE(HID_CONST_VAR_ABS),

        // Feature report 1 (read/write).
        HID_REPORT_ID(1),

        // 1-bit on/off reporting state.
        HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE,
        HID_LOGICAL_MIN_8(0),
        HID_LOGICAL_MAX_8(1),
        HID_REPORT_SIZE(1),
        HID_REPORT_COUNT(1),
        HID_COLLECTION(HID_LOGICAL),
            HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_NO_EVENTS,
            HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_ALL_EVENTS,
            HID_FEATURE(HID_DATA_ARR_ABS),
        HID_END_COLLECTION,

        // 1-bit on/off power state.
        HID_USAGE_SENSOR_PROPERTY_POWER_STATE,
        HID_LOGICAL_MIN_8(0),
        HID_LOGICAL_MAX_8(1),
        HID_REPORT_SIZE(1),
        HID_REPORT_COUNT(1),
        HID_COLLECTION(HID_LOGICAL),
            HID_USAGE_SENSOR_PROPERTY_POWER_STATE_D4_POWER_OFF,
            HID_USAGE_SENSOR_PROPERTY_POWER_STATE_D0_FULL_POWER,
            HID_FEATURE(HID_DATA_ARR_ABS),
        HID_END_COLLECTION,

        // 6-bit reporting interval, with values [0x00..0x3F] corresponding to [10ms..100ms].
        HID_USAGE_SENSOR_PROPERTY_REPORT_INTERVAL,
        HID_LOGICAL_MIN_8(0x00),
        HID_LOGICAL_MAX_8(0x3F),
        HID_PHYSICAL_MIN_8(10),
        HID_PHYSICAL_MAX_8(100),
        HID_REPORT_SIZE(6),
        HID_REPORT_COUNT(1),
        HID_USAGE_SENSOR_UNITS_SECOND,
        HID_UNIT_EXPONENT(0xD),  // 10^-3
        HID_FEATURE(HID_DATA_VAR_ABS),

        // Input report 1

        // Orientation as rotation vector (scaled to [-pi..pi] rad).
        HID_USAGE_SENSOR_DATA_CUSTOM_VALUE_1,
        HID_LOGICAL_MIN_16(0x01, 0x80), // LOGICAL_MINIMUM (-32767)
        HID_LOGICAL_MAX_16(0xFF, 0x7F), // LOGICAL_MAXIMUM (32767)
        HID_PHYSICAL_MIN_32(0x60, 0x4F, 0x46, 0xED),  // -314159265
        HID_PHYSICAL_MAX_32(0xA1, 0xB0, 0xB9, 0x12),  // 314159265
        HID_UNIT_EXPONENT(0x08),  // 10^-8
        HID_REPORT_SIZE(16),
        HID_REPORT_COUNT(3),
        HID_INPUT(HID_DATA_VAR_ABS),

        // Angular velocity as rotation vector (scaled to [-32..32] rad/sec).
        HID_USAGE_SENSOR_DATA_CUSTOM_VALUE_2,
        HID_LOGICAL_MIN_16(0x01, 0x80), // LOGICAL_MINIMUM (-32767)
        HID_LOGICAL_MAX_16(0xFF, 0x7F), // LOGICAL_MAXIMUM (32767)
        HID_PHYSICAL_MIN_8(0xE0),
        HID_PHYSICAL_MAX_8(0x20),
        HID_UNIT_EXPONENT(0x00),  // 10^0
        HID_REPORT_SIZE(16),
        HID_REPORT_COUNT(3),
        HID_INPUT(HID_DATA_VAR_ABS),

        // Reference frame reset counter.
        HID_USAGE_SENSOR_DATA_CUSTOM_VALUE_3,
        HID_LOGICAL_MIN_16(0x00, 0x00), // LOGICAL_MINIMUM (0)
        HID_LOGICAL_MAX_16(0xFF, 0x00), // LOGICAL_MAXIMUM (255)
        HID_PHYSICAL_MIN_8(0x00),
        HID_PHYSICAL_MAX_8(0x00),
        HID_UNIT_EXPONENT(0x00),  // 10^0
        HID_REPORT_SIZE(8),
        HID_REPORT_COUNT(1),
        HID_INPUT(HID_DATA_VAR_ABS),

    HID_END_COLLECTION,
};

Приложение 2: Пример дескриптора HID версии 2.0

В следующем примере показан дескриптор HID версии 2.0 для устройства, поддерживающего только транспортный протокол Bluetooth LE ACL.

const unsigned char ReportDescriptor[] = {
    HID_USAGE_PAGE_SENSOR,
    HID_USAGE_SENSOR_TYPE_OTHER_CUSTOM,
    HID_COLLECTION(HID_APPLICATION),
        // Feature report 2 (read-only).
        HID_REPORT_ID(2),

        // Magic value: "#AndroidHeadTracker#2.0#1"
        HID_USAGE_SENSOR_PROPERTY_SENSOR_DESCRIPTION,
        HID_LOGICAL_MIN_8(0),
        HID_LOGICAL_MAX_8(0xFF),
        HID_REPORT_SIZE(8),
        HID_REPORT_COUNT(25),
        HID_FEATURE(HID_CONST_VAR_ABS),

        // UUID.
        HID_USAGE_SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID,
        HID_LOGICAL_MIN_8(0),
        HID_LOGICAL_MAX_8(0xFF),
        HID_REPORT_SIZE(8),
        HID_REPORT_COUNT(16),
        HID_FEATURE(HID_CONST_VAR_ABS),

        // Feature report 1 (read/write).
        HID_REPORT_ID(1),

        // 1-bit on/off reporting state.
        HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE,
        HID_LOGICAL_MIN_8(0),
        HID_LOGICAL_MAX_8(1),
        HID_REPORT_SIZE(1),
        HID_REPORT_COUNT(1),
        HID_COLLECTION(HID_LOGICAL),
            HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_NO_EVENTS,
            HID_USAGE_SENSOR_PROPERTY_REPORTING_STATE_ALL_EVENTS,
            HID_FEATURE(HID_DATA_ARR_ABS),
        HID_END_COLLECTION,

        // 1-bit on/off power state.
        HID_USAGE_SENSOR_PROPERTY_POWER_STATE,
        HID_LOGICAL_MIN_8(0),
        HID_LOGICAL_MAX_8(1),
        HID_REPORT_SIZE(1),
        HID_REPORT_COUNT(1),
        HID_COLLECTION(HID_LOGICAL),
            HID_USAGE_SENSOR_PROPERTY_POWER_STATE_D4_POWER_OFF,
            HID_USAGE_SENSOR_PROPERTY_POWER_STATE_D0_FULL_POWER,
            HID_FEATURE(HID_DATA_ARR_ABS),
        HID_END_COLLECTION,

        // 6-bit reporting interval, with values [0x00..0x3F] corresponding to [10ms..100ms].
        HID_USAGE_SENSOR_PROPERTY_REPORT_INTERVAL,
        HID_LOGICAL_MIN_8(0x00),
        HID_LOGICAL_MAX_8(0x3F),
        HID_PHYSICAL_MIN_8(10),
        HID_PHYSICAL_MAX_8(100),
        HID_REPORT_SIZE(6),
        HID_REPORT_COUNT(1),
        HID_USAGE_SENSOR_UNITS_SECOND,
        HID_UNIT_EXPONENT(0xD),  // 10^-3
        HID_FEATURE(HID_DATA_VAR_ABS),

        // 1-bit transport selection
        HID_USAGE_SENSOR_PROPERTY_VENDOR_LE_TRANSPORT,
        HID_LOGICAL_MIN_8(0),
        HID_LOGICAL_MAX_8(1),
        HID_REPORT_SIZE(1),
        HID_REPORT_COUNT(1),
        HID_COLLECTION(HID_LOGICAL),
            HID_USAGE_SENSOR_PROPERTY_VENDOR_LE_TRANSPORT_ACL,
            HID_USAGE_SENSOR_PROPERTY_VENDOR_LE_TRANSPORT_ISO,
            HID_FEATURE(HID_DATA_ARR_ABS),
        HID_END_COLLECTION,

        // Input report 1

        // Orientation as rotation vector (scaled to [-pi..pi] rad).
        HID_USAGE_SENSOR_DATA_CUSTOM_VALUE_1,
        HID_LOGICAL_MIN_16(0x01, 0x80), // LOGICAL_MINIMUM (-32767)
        HID_LOGICAL_MAX_16(0xFF, 0x7F), // LOGICAL_MAXIMUM (32767)
        HID_PHYSICAL_MIN_32(0x60, 0x4F, 0x46, 0xED),  // -314159265
        HID_PHYSICAL_MAX_32(0xA1, 0xB0, 0xB9, 0x12),  // 314159265
        HID_UNIT_EXPONENT(0x08),  // 10^-8
        HID_REPORT_SIZE(16),
        HID_REPORT_COUNT(3),
        HID_INPUT(HID_DATA_VAR_ABS),

        // Angular velocity as rotation vector (scaled to [-32..32] rad/sec).
        HID_USAGE_SENSOR_DATA_CUSTOM_VALUE_2,
        HID_LOGICAL_MIN_16(0x01, 0x80), // LOGICAL_MINIMUM (-32767)
        HID_LOGICAL_MAX_16(0xFF, 0x7F), // LOGICAL_MAXIMUM (32767)
        HID_PHYSICAL_MIN_8(0xE0),
        HID_PHYSICAL_MAX_8(0x20),
        HID_UNIT_EXPONENT(0x00),  // 10^0
        HID_REPORT_SIZE(16),
        HID_REPORT_COUNT(3),
        HID_INPUT(HID_DATA_VAR_ABS),

        // Reference frame reset counter.
        HID_USAGE_SENSOR_DATA_CUSTOM_VALUE_3,
        HID_LOGICAL_MIN_16(0x00, 0x00), // LOGICAL_MINIMUM (0)
        HID_LOGICAL_MAX_16(0xFF, 0x00), // LOGICAL_MAXIMUM (255)
        HID_PHYSICAL_MIN_8(0x00),
        HID_PHYSICAL_MAX_8(0x00),
        HID_UNIT_EXPONENT(0x00),  // 10^0
        HID_REPORT_SIZE(8),
        HID_REPORT_COUNT(1),
        HID_INPUT(HID_DATA_VAR_ABS),

    HID_END_COLLECTION,
};