بروتوكول HID لتعقب الرأس

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يسمح بروتوكول جهاز واجهة الإنسان (HID) المتتبع للرأس ، والمتوفر للأجهزة التي تعمل بنظام Android 13 والإصدارات الأحدث ، بتوصيل جهاز تتبع الرأس بجهاز Android عبر USB أو Bluetooth والتعرض لإطار عمل Android والتطبيقات من خلال المستشعرات نطاق. يستخدم هذا البروتوكول للتحكم في تأثير المحاكاة الصوتية (الصوت ثلاثي الأبعاد). تستخدم هذه الصفحة مصطلحي الجهاز والمضيف بمعنى البلوتوث ، حيث يعني الجهاز جهاز تتبع الرأس والمضيف يعني مضيف Android.

يجب على الشركات المصنعة للأجهزة تكوين أجهزة Android الخاصة بهم لتمكين دعم بروتوكول HID لتعقب الرأس. لمزيد من المعلومات التفصيلية حول التكوين ، راجع Dynamic Sensors README .

تفترض هذه الصفحة الإلمام بالموارد التالية:

هيكل من المستوى الأعلى

يحدد إطار عمل Android جهاز تعقب الرأس كجهاز HID.

للحصول على مثال كامل لوصف HID صالح ، راجع الملحق 1: مثال على واصف HID .

في المستوى العلوي ، جهاز تعقب الرأس عبارة عن مجموعة تطبيقات مع صفحة Sensors ( 0x20 ) والأخرى Other: Custom ( 0xE1 ). يوجد داخل هذه المجموعة العديد من حقول البيانات ( المدخلات ) والخصائص ( الميزات ).

الخصائص وحقول البيانات

يصف هذا القسم الخصائص وحقول البيانات في مجموعة تطبيقات لجهاز تعقب الرأس.

الخاصية: وصف جهاز الاستشعار ( 0x0308 )

خاصية Sensor Description ( 0x0308 ) هي خاصية سلسلة ASCII للقراءة فقط (8 بت) والتي يجب أن تحتوي على القيمة التالية:

#AndroidHeadTracker#1.0

لا يُتوقع وجود فاصل قيم فارغ ، مما يعني أن الحجم الإجمالي لهذه الخاصية هو 23 حرفًا من 8 بت.

تعمل هذه الخاصية كعنصر تمييز لتجنب الاصطدامات مع أجهزة الاستشعار الأخرى المخصصة.

الخاصية: المعرف الفريد الثابت ( 0x0302 )

خاصية المعرف الفريد الثابت ( 0x0302 ) عبارة عن صفيف للقراءة فقط مكون من 16 عنصرًا ، 8 بت لكل عنصر (إجمالي 128 بت). من المتوقع عدم وجود فاصل فارغ. هذه الخاصية اختيارية.

تسمح هذه الخاصية لأجهزة تتبع الرأس المدمجة في أجهزة الصوت بالإشارة إلى جهاز الصوت الذي تم توصيله به. يتم دعم المخططات التالية.

تعقب رأس مستقل

إذا كانت خاصية المعرف الفريد الثابت ( 0x0302 ) غير موجودة أو تم تعيينها على جميع الأصفار ، فهذا يعني أن جهاز تعقب الرأس غير متصل بشكل دائم بجهاز صوت ويمكن استخدامه بشكل منفصل ، على سبيل المثال ، عن طريق السماح للمستخدم يدويًا قم بربط جهاز تعقب الرأس بجهاز صوت منفصل.

مرجع باستخدام عنوان Bluetooth MAC

ثماني 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
قيمة 0 0 0 0 0 0 0 0 ب تي بلوتوث ماك

في هذا المخطط ، يجب أن تكون الثمانيات الثمانية الأولى 0 ، ويجب أن تحتوي الثماني بتات 8 و 9 على قيم ASCII B و T على التوالي ، ويتم تفسير الثمانيات الستة التالية على أنها عنوان MAC لـ Bluetooth ، بافتراض أن جهاز تعقب الرأس ينطبق على أي جهاز صوت به عنوان MAC هذا.

مرجع باستخدام UUID

عندما يتم تعيين البت الأكثر أهمية (MSB) للثمانية 8 ( ≥0x80 ) ، يتم تفسير الحقل على أنه UUID ، كما هو محدد في RFC-4122 . يوفر جهاز الصوت المقابل نفس UUID ، المسجل في إطار عمل Android ، من خلال آلية غير محددة خاصة بنوع النقل المستخدم.

الخاصية: حالة التقرير ( 0x0316 )

خاصية Reporting State ( 0x0316 ) هي خاصية قراءة / كتابة لها دلالات قياسية كما هو محدد في مواصفات HID. يستخدم المضيف هذه الخاصية ليشير للجهاز إلى الأحداث المراد الإبلاغ عنها. يتم استخدام القيم "بلا أحداث" ( 0x0840 ) وكافة الأحداث ( 0x0841 ) فقط.

يجب أن تكون القيمة الأولية لهذا الحقل "بلا أحداث" ويجب ألا يتم تعديلها أبدًا بواسطة الجهاز ، فقط بواسطة المضيف.

الخاصية: حالة الطاقة ( 0x0319 )

خاصية Power State ( 0x0319 ) هي خاصية قراءة / كتابة لها دلالات قياسية كما هو محدد في مواصفات HID. يستخدم المضيف هذه الخاصية ليشير للجهاز إلى حالة الطاقة التي يجب أن يكون فيها. يتم استخدام قيم الطاقة الكاملة ( 0x0851 ) وإيقاف التشغيل ( 0x0855 ) فقط.

يتم تحديد القيمة الأولية لهذا الحقل بواسطة الجهاز ويجب ألا يتم تعديلها أبدًا بواسطة الجهاز ، فقط بواسطة المضيف.

الخاصية: تقرير الفاصل ( 0x030E )

خاصية Report Interval ( 0x030E ) هي خاصية قراءة / كتابة لها دلالات قياسية كما هو محدد في مواصفات HID. يستخدم المضيف هذه الخاصية ليشير للجهاز إلى عدد مرات الإبلاغ عن قراءات البيانات الخاصة به. الوحدات هي ثواني. يتم تحديد النطاق الصالح لهذه القيمة بواسطة الجهاز ويتم وصفه باستخدام آلية الحد الأدنى / الحد الأقصى المادي. يجب دعم معدل إبلاغ عن 50 هرتز على الأقل ، ومعدل الإبلاغ الأقصى الموصى به هو 100 هرتز. لذلك ، يجب أن يكون الحد الأدنى لفترة التقرير أقل من أو يساوي 20 مللي ثانية ، ويوصى بأن يكون أكبر من أو يساوي 10 مللي ثانية.

حقل البيانات: القيمة المخصصة 1 ( 0x0544 )

حقل القيمة المخصصة 1 ( 0x0544 ) هو حقل إدخال يُستخدم للإبلاغ عن معلومات تتبع الرأس الفعلية. إنها مصفوفة مكونة من 3 عناصر ، مفسرة وفقًا لقواعد HID العادية للقيم المادية كما هو محدد في القسم 6.2.2.7 من مواصفات HID. النطاق الصالح لكل عنصر هو [-، π] rad. الوحدات دائمًا راديان.

يتم تفسير العناصر على النحو التالي: [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.
  • تم تعيين خاصية Reporting State على كافة الأحداث.
  • خاصية الفاصل الزمني للتقرير ليست صفرية.

تحدد خاصية "الفاصل الزمني لإعداد التقارير" عدد مرات إرسال التقارير. في حالة عدم استيفاء أي من الشروط المذكورة أعلاه ، يجب ألا يرسل الجهاز أي تقارير.

التوافق للأمام والخلف

يستخدم بروتوكول HID لتعقب الرأس نظام إصدار يسمح بالتحديثات ، مع السماح بالتشغيل البيني بين مضيف وجهاز يستخدم إصدارات مختلفة من البروتوكول. يتم تحديد إصدارات البروتوكول برقمين ، رئيسي وثانوي ، لهما دلالات مميزة كما هو موضح في الأقسام التالية.

يمكن تحديد الإصدارات التي يدعمها الجهاز من خلال فحص خاصية وصف المستشعر ( 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 لتحديد إصدارات البروتوكول التي ينفذها كل منهم ، ثم اختيار أحدث إصدار من البروتوكول الذي يدعمه المضيف. عند الاختيار ، يعمل المضيف مع البروتوكول الفردي الذي تم اختياره طوال مدة اتصال الجهاز.

الملحق 1: مثال على واصف 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,
};