Kafa izleyici HID protokolü

Android 13 ve sonraki sürümleri çalıştıran cihazlarda kullanılabilen kafa takip cihazı insan arayüz cihazı (HID) protokolü, bir kafa takip cihazının USB veya Bluetooth aracılığıyla bir Android cihaza bağlanmasına ve sensörler aracılığıyla Android çerçevesine ve uygulamalarına maruz kalmasına olanak tanır çerçeve. Bu protokol, bir ses sanallaştırıcı efektini (3D ses) kontrol etmek için kullanılır. Bu sayfada cihaz ve ana bilgisayar terimleri Bluetooth anlamında kullanılmaktadır; burada cihaz, kafa izleme cihazı anlamına gelir ve ana bilgisayar , Android ana bilgisayarı anlamına gelir.

Cihaz üreticilerinin Android cihazlarını kafa izleyici HID protokolü desteğini etkinleştirecek şekilde yapılandırmaları gerekir. Yapılandırma hakkında daha ayrıntılı bilgi için Dinamik Sensörler README'ye bakın.

Bu sayfa aşağıdaki kaynaklara aşina olduğunuzu varsayar:

Üst düzey yapı

Android çerçevesi, kafa izleme cihazını bir HID cihazı olarak tanımlar.

Geçerli bir HID tanımlayıcının tam örneği için bkz . Ek 1: HID Tanımlayıcı Örneği .

En üst düzeyde, kafa takip cihazı, Sensors sayfasını ( 0x20 ) ve Other: Custom kullanımı ( 0xE1 ) içeren bir uygulama koleksiyonudur. Bu koleksiyonun içinde çeşitli veri alanları ( girdiler ) ve özellikler ( özellikler ) bulunur.

Özellikler ve veri alanları

Bu bölümde bir kafa takip cihazının uygulama koleksiyonundaki özellikler ve veri alanları açıklanmaktadır.

Özellik: Sensör Açıklaması ( 0x0308 )

Sensör Açıklaması ( 0x0308 ) özelliği, aşağıdaki değeri içermesi gereken salt okunur bir ASCII (8 bit) dize özelliğidir:

#AndroidHeadTracker#1.0

Boş sonlandırıcı beklenmiyor; bu, bu özelliğin toplam boyutunun 23 adet 8 bitlik karakter olduğu anlamına gelir.

Bu özellik, diğer özel sensörlerle çarpışmayı önlemek için ayırıcı görevi görür.

Özellik: Kalıcı Benzersiz Kimlik ( 0x0302 )

Kalıcı Benzersiz Kimlik ( 0x0302 ) özelliği, her biri 8 bit (toplam 128 bit) olan 16 öğeden oluşan salt okunur bir dizidir. Boş sonlandırıcı beklenmiyor. Bu özellik isteğe bağlıdır.

Bu özellik, ses cihazlarına tümleşik olan kafa izleme cihazlarının, bağlı oldukları ses cihazına referans vermesine olanak tanır. Aşağıdaki şemalar desteklenmektedir.

Bağımsız kafa takip cihazı

Kalıcı Benzersiz Kimlik ( 0x0302 ) özelliği mevcut değilse veya tamamı sıfıra ayarlanmışsa, bu, kafa izleme cihazının bir ses cihazına kalıcı olarak bağlı olmadığı ve örneğin kullanıcıya manuel olarak izin verilerek ayrı olarak kullanılabileceği anlamına gelir. kafa takip cihazını ayrı bir ses cihazıyla ilişkilendirin.

Bluetooth MAC adresini kullanarak referans

sekizli 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
Değer 0 0 0 0 0 0 0 0 B T Bluetooth MAC'i

Bu şemada, ilk 8 sekizli 0 olmalıdır, sekizli 8 ve 9 sırasıyla ASCII değerleri B ve T içermelidir ve sonraki 6 sekizli, kafa takip cihazının herhangi bir ses cihazına uygulandığı varsayılarak bir Bluetooth MAC adresi olarak yorumlanır. bu MAC adresi.

UUID kullanarak referans

Sekizli 8'in en anlamlı biti (MSB) ayarlandığında ( ≥0x80 ), alan RFC-4122'de belirtildiği gibi bir UUID olarak yorumlanır. İlgili ses cihazı, Android çerçevesinde kayıtlı olan aynı UUID'yi, kullanılan aktarım türüne özel, belirtilmemiş bir mekanizma aracılığıyla sağlar.

Özellik: Raporlama Durumu ( 0x0316 )

Raporlama Durumu ( 0x0316 ) özelliği, HID spesifikasyonunda tanımlandığı gibi standart anlamlara sahip bir okuma/yazma özelliğidir. Ana bilgisayar, cihaza hangi olayların raporlanacağını belirtmek için bu özelliği kullanır. Yalnızca Olay Yok ( 0x0840 ) ve Tüm Olaylar ( 0x0841 ) değerleri kullanılır.

Bu alanın başlangıç ​​değeri Olay Yok olmalıdır ve hiçbir zaman cihaz tarafından değiştirilmemelidir; yalnızca ana bilgisayar tarafından değiştirilmelidir.

Özellik: Güç Durumu ( 0x0319 )

Güç Durumu ( 0x0319 ) özelliği, HID spesifikasyonunda tanımlandığı gibi standart anlamlara sahip bir okuma/yazma özelliğidir. Ana bilgisayar bu özelliği, aygıta hangi güç durumunda olması gerektiğini belirtmek için kullanır. Yalnızca Tam Güç ( 0x0851 ) ve Güç Kapalı ( 0x0855 ) değerleri kullanılır.

Bu alanın başlangıç ​​değeri cihaz tarafından belirlenir ve hiçbir zaman cihaz tarafından değiştirilmemelidir; yalnızca ana bilgisayar tarafından değiştirilmelidir.

Özellik: Rapor Aralığı ( 0x030E )

Rapor Aralığı ( 0x030E ) özelliği, HID belirtiminde tanımlandığı gibi standart anlambilime sahip bir okuma/yazma özelliğidir. Ana bilgisayar bu özelliği, cihaza veri okumalarını ne sıklıkta raporlayacağını belirtmek için kullanır. Birimler saniyedir. Bu değerin geçerli aralığı cihaz tarafından belirlenir ve Fiziksel Min/Maks mekanizması kullanılarak tanımlanır. En az 50 Hz raporlama hızı desteklenmelidir ve önerilen maksimum raporlama hızı 100 Hz'dir. Bu nedenle minimum rapor aralığının 20 ms'ye eşit veya daha az olması gerekir ve 10 ms'ye eşit veya daha büyük olması önerilir.

Veri alanı: Özel Değer 1 ( 0x0544 )

Özel Değer 1 ( 0x0544 ) alanı, gerçek kafa izleme bilgilerini raporlamak için kullanılan bir giriş alanıdır. Bu, HID spesifikasyonunun 6.2.2.7 bölümünde belirtilen fiziksel değerlere yönelik normal HID kurallarına göre yorumlanan 3 öğeli bir dizidir. Her öğe için geçerli aralık [-π, π] rad'dır. Birimler her zaman radyandır.

Öğeler şu şekilde yorumlanır: [rx, ry, rz] , öyle ki [rx, ry, rz] , referans çerçevesinden baş çerçeveye dönüşümü temsil eden bir dönme vektörüdür . Büyüklük [0..π] aralığında olmalıdır.

Referans çerçevesi isteğe bağlıdır, ancak genellikle sabittir ve sağ elle kullanılması gerekir. Az miktarda sapma kabul edilebilir. Kafa eksenleri şunlardır:

  • X sol kulaktan sağa
  • Y başın arkasından buruna (arkadan öne)
  • Z boyundan başın üstüne kadar

Veri alanı: Özel Değer 2 ( 0x0545 )

Özel Değer 2 ( 0x0545 ) alanı, gerçek kafa izleme bilgilerini raporlamak için kullanılan bir giriş alanıdır. Bu, fiziksel değerlere ilişkin normal HID kurallarına göre yorumlanan 3 öğeli sabit noktalı bir dizidir. Birimler her zaman radyan/saniyedir.

Öğeler şu şekilde yorumlanır: [vx, vy, vz] , öyle ki [vx, vy, vz] kafa çerçevesinin (kendisine göre) açısal hızını temsil eden bir dönme vektörüdür .

Veri alanı: Özel Değer 3 ( 0x0546 )

Özel Değer 3 ( 0x0546 ) alanı, referans çerçevesindeki süreksizlikleri izlemek için kullanılan bir giriş alanıdır. Boyutu 8 bit olan skaler bir tam sayıdır. Referans çerçevesi her değiştirildiğinde, örneğin yönlendirmeyi belirlemek için kullanılan bir yönlendirme filtre algoritmasının durumu sıfırlanmışsa, cihaz tarafından (sarma ile) artırılmalıdır. Bu değer, fiziksel değerler için normal HID kurallarına göre yorumlanır. Ancak fiziksel değeri ve birimleri önemli değildir. Ana bilgisayarla ilgili tek bilgi değiştirilmiş bir değerdir. Mantıksal birimlerden fiziksel birimlere dönüştürme sırasında hassasiyet kaybıyla ilgili sayısal sorunları önlemek amacıyla, bu alan için fiziksel minimum, fiziksel maksimum ve birim üssü değerlerinin sıfıra ayarlanması önerilir.

Rapor yapısı

Özelliklerin raporlarda gruplandırılması (rapor kimliklerinin atanması yoluyla) esnektir. Verimlilik açısından salt okunur özellikleri okuma/yazma özelliklerinden ayırmanızı öneririz.

Veri alanları için Özel Değer 1, 2 ve 3 alanları aynı raporda olmalı ve belirli bir cihaz için yalnızca bir raporda yer almalıdır (uygulama koleksiyonu).

Giriş raporlarını gönder

Tüm bu koşullar karşılandığında cihazın periyodik ve asenkron olarak (HID INPUT mesajları aracılığıyla) giriş raporları göndermesi gerekir:

  • Güç Durumu özelliği Tam Güç olarak ayarlanmıştır.
  • Raporlama Durumu özelliği Tüm Etkinlikler olarak ayarlanmıştır.
  • Raporlama Aralığı özelliği sıfır değildir.

Raporlama Aralığı özelliği, raporların ne sıklıkta gönderileceğini belirler. Yukarıdaki koşullardan herhangi biri karşılanmadığında cihaz herhangi bir rapor göndermemelidir.

İleri ve geri uyumluluk

Head tracker HID protokolü, bir ana bilgisayar ile protokolün farklı sürümlerini kullanan bir cihaz arasında birlikte çalışabilirliğe izin verirken aynı zamanda güncellemelere izin veren bir sürüm oluşturma şeması kullanır. Protokolün sürümleri, aşağıdaki bölümlerde açıklandığı gibi farklı anlamlara sahip olan majör ve minör olmak üzere iki sayıyla tanımlanır.

Bir cihazın desteklediği versiyonlar, Sensör Açıklaması ( 0x0308 ) özelliği incelenerek belirlenebilir.

Küçük sürüm uyumluluğu

Alt sürümde yapılan değişiklikler, aynı ana sürümü temel alan önceki alt sürümlerle geriye dönük olarak uyumludur. İkincil sürüme yapılan güncellemelerde ana bilgisayar, ek veri alanlarını ve özellikleri yok sayar. Örneğin, protokol sürümü 1.6'yı kullanan bir cihaz, sürüm 1.5 dahil olmak üzere protokol sürümü 1.x'i destekleyen bir ana bilgisayarla uyumludur.

Ana sürüm uyumluluğu

Ana sürümlerde yapılan değişiklikler için geriye dönük uyumlu olmayan değişikliklere izin verilir. Eski ve yeni ana bilgisayarlarla birlikte çalışabilirlik amacıyla birden fazla ana sürümü desteklemek için cihazlar, rapor tanımlayıcılarında birden fazla uygulama koleksiyonu belirtebilir. Örneğin:

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,
};

Bu durumda, ana bilgisayar, cihaz tarafından tanıtılan tüm farklı uygulama koleksiyonlarını sıralayabilir, her birinin uyguladığı protokol sürümlerini belirlemek için Sensör Açıklaması özelliklerini inceleyebilir ve ardından ana bilgisayarın desteklediği en son protokol sürümünü seçebilir. Seçildiğinde ana bilgisayar, cihaz bağlantısının ömrü boyunca seçilen tek protokolle çalışır.

Ek: HID tanımlayıcı örneği

Aşağıdaki örnek tipik bir geçerli HID tanımlayıcısını göstermektedir. HID Sensör Kullanımları (bölüm 4.1) bölümünde sağlanan yaygın olarak kullanılan C makrolarını kullanır.

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,
};