रीडिंग पेन HID रिपोर्ट डिस्क्रिप्टर और यूसेज पेज: OID टैप के लिए बाइट-स्तरीय मैप

दर्शक वर्ग: एम्बेडेड फ़र्मवेयर इंजीनियर, OS ड्राइवर इंटीग्रेटर और OEM प्रोडक्ट मैनेजर जिन्हें यह समझना है कि रीडिंग पेन के HID रिपोर्ट डिस्क्रिप्टर का हर बाइट वास्तव में क्या दर्शाता है, उपयोग पृष्ठ को जेनेरिक डेस्कटॉप पृष्ठ और वेंडर-परिभाषित पृष्ठ में क्यों विभाजित किया गया है, और फ़ील्ड में पहले से तैनात 230+ डिस्ट्रीब्यूटर-ग्रेड ड्राइवर को तोड़े बिना मैप का विस्तार कैसे करें।

HID रिपोर्ट डिस्क्रिप्टर रीडिंग पेन के फ़र्मवेयर का सबसे निर्णायक 80 से 200 बाइट्स होता है। यह पेन के MCU और हर होस्ट ऑपरेटिंग सिस्टम के बीच का अनुबंध है: Windows 10/11, macOS 12/13/14, ChromeOS, Android 9 से 14, iPadOS 15 से 17, और Linux कर्नेल 5.15+। डिस्क्रिप्टर गलत हो जाए, तो पेन गलत अक्षर टाइप करता है, OID टैप को अनदेखा करता है, या इससे भी बुरा, ऑडियो को गलत सिंक पर चुपचाप रूट कर देता है। हमारी 47,000+ शिपमेंट की गई यूनिट्स में, डिस्क्रिप्टर रिग्रेशन ने OCR इंजन को छोड़कर किसी भी अन्य फ़र्मवेयर सबसिस्टम से अधिक डिबगिंग घंटे खर्च किए हैं।

यह लेख TC-057 के कैनोनिकल डिस्क्रिप्टर को लेकर बाइट-दर-बाइट इसकी व्याख्या करता है, बताता है कि प्रत्येक फ़ील्ड जिस तरह सेट है उसका कारण क्या है, और दिखाता है कि ODM ब्रांड मैप का सुरक्षित रूप से विस्तार कहाँ कर सकता है और कहाँ नहीं।

1. HID अनुबंध की तीन परतें

एक HID रिपोर्ट डिस्क्रिप्टर तीन लॉजिकल परतों में पार्स होता है:

पार्सर स्टेटफुल है। एक Collection एक स्कोप खोलता है, और उस स्कोप के भीतर के Input/Output/Feature आइटम एक रिपोर्ट का वर्णन करते हैं। डिस्क्रिप्टर बाएँ-से-दाएँ प्रोसेस होता है, और हर बाइट वेल-फ़ॉर्म्ड होना चाहिए। एक भी विकृत बाइट होस्ट को पूरा डिस्क्रिप्टर अस्वीकार करने पर मजबूर कर देता है।

हमारा Q6/Q8 डिस्क्रिप्टर 92 बाइट्स का है। F8 डिस्क्रिप्टर 76 बाइट्स का है। T2/Y6 (हेडफ़ोन प्लेबैक के लिए पूर्ण कंज़्यूमर-कंट्रोल समर्थन के साथ) 168 बाइट्स का है। डिस्क्रिप्टर की लंबाई एन्यूमरेशन के समय HID डिस्क्रिप्टर में एन्कोड होती है, और होस्ट इसे कैश करता है। यदि आप किसी भविष्य के फ़र्मवेयर रिवीज़न पर डिस्क्रिप्टर बदलते हैं, तो होस्ट कैश्ड वर्शन का उपयोग जारी रख सकता है, और यही कारण है कि हम फ़र्मवेयर अपडेट पर हमेशा USB बस रीसेट लागू करते हैं (देखें TC-075).

2. रीडिंग पेन द्वारा उपयोग किए जाने वाले आइटम टैग

HID स्पेसिफ़िकेशन एक टैग तालिका परिभाषित करता है; पेन इनमें से केवल 12 का उपयोग करता है:

हम जानबूझकर इस 12-टैग के उप-सेट तक सीमित रहते हैं। HID स्पेक कई और टैग की अनुमति देता है, लेकिन हर अतिरिक्त टैग OS-विशिष्ट विसंगतियों की संभावना बढ़ाता है। उदाहरण के लिए, Padding (0x5A) टैग तकनीकी रूप से वैध है, लेकिन Linux कर्नेल का hid-core.c सस्पेंड/रीज़्यूम के दौरान कुछ Padding क्रमों को अस्वीकार कर देता है।

3. तीन उपयोग पृष्ठ

Q6/Q8 डिस्क्रिप्टर तीन उपयोग पृष्ठों का उपयोग करता है:

Generic Desktop पृष्ठ वह कीबोर्ड संग्रह है जिसे हम शिप करते हैं। यह 1-बाइट मॉडिफायर (8 बिट, 1 बाइट रिपोर्ट साइज़, 8 रिपोर्ट काउंट) और 1-बाइट आरक्षित स्थिरांक (8 बिट, 1 रिपोर्ट साइज़, 1 काउंट) घोषित करता है। साथ मिलकर ये बूट कीबोर्ड रिपोर्ट हेड बनाते हैं।

Consumer पृष्ठ हेडफ़ोन प्लेबैक के लिए शिप किया गया वॉल्यूम अप / वॉल्यूम डाउन / प्ले-पॉज़ नियंत्रण है। यह कुल 3 बिट का होता है।

Vendor Defined पृष्ठ 0xFF00 OID इवेंट पेलोड है: प्रति रिपोर्ट 16 बाइट, Report ID रहित, एक Output रिपोर्ट में ताकि होस्ट आवश्यकता पड़ने पर पेन को 16 बाइट संदर्भ भी भेज सके।

4. Q6/Q8 फ़र्मवेयर 3.3.1 के लिए बाइट मानचित्र

नीचे Q6/Q8 प्लेटफ़ॉर्म के लिए कैनोनिकल डिस्क्रिप्टर, बाइट-अनुक्रमित है:

Q6/Q8 पर शेष बाइट्स (66 से 91) बाइट अलाइनमेंट के लिए पैडिंग और ब्रांड ID के लिए एक Feature रिपोर्ट हैं। F8 पर, बाइट 47 से आगे हटा दिए जाते हैं और डिस्क्रिप्टर बाइट 46 पर रुक जाता है।

5. बूट प्रोटोकॉल बनाम रिपोर्ट प्रोटोकॉल

रीडिंग पेन एक Protocol Mode कैरेक्टरिस्टिक (BLE पर UUID 0x2A4E, USB पर bInterfaceProtocol बाइट) एक्सपोज़ करता है। दो प्रोटोकॉल मान्य हैं:

Q6/Q8 फ़र्मवेयर 3.3.1 पर, डिफ़ॉल्ट रिपोर्ट प्रोटोकॉल है। होस्ट Protocol Mode कैरेक्टरिस्टिक पर 0x00 लिखकर बूट प्रोटोकॉल का अनुरोध कर सकता है, जिसे हमारा फ़र्मवेयर 16-बाइट OID रिपोर्ट को 8-बाइट बूट फ़ॉर्मेट में समेटकर पूरा करता है। हम कोई डेटा नहीं खोते; OID पेज ID और कोड बस कीकोड बाइट्स में फोल्ड हो जाते हैं।

12,000-यूनिट स्कूल प्रोग्राम के लिए, हमने बूट प्रोटोकॉल को डिफ़ॉल्ट रूप से सक्षम करने की सिफ़ारिश की क्योंकि स्कूल के लैपटॉप एक लॉक्ड-डाउन Windows इमेज पर चलते हैं जहाँ मानक HID ड्राइवर स्टैक 1.4 सेकंड में लोड होता है, जबकि पूरे रिपोर्ट प्रोटोकॉल पार्सर के लिए 4.8 सेकंड लगते हैं। जब क्लास की शुरुआत में 30 बच्चे कोल्ड-बूट करते हैं तो लेटेंसी बचत मायने रखती है।

6. वेंडर-डिफ़ाइंड पेज 0xFF00: हमने इसे आरक्षित क्यों किया

हमने 2022 में USB-IF वेंडर सूची में 0xFF00 आरक्षित किया था। यह आरक्षण हमें उस पेज पर 0x01 से 0xFFFF तक के किसी भी उपयोग ID को परिभाषित करने का कानूनी अधिकार देता है, और कोई भी तीसरा पक्ष जो हमारे पेन के साथ इंटरऑपरेट करना चाहता है, उसे हमसे उपयोग-ID रेंज पर बातचीत करनी होगी। ODM कस्टमर को उनके ब्रांड ID के लिए 32-उपयोग की उप-रेंज आवंटित की जाती है। उन 32 में से पहले 8 हमारे आंतरिक उपयोग के लिए आरक्षित हैं, ब्रांड के लिए 24 उपयोग शेष रहते हैं।

यह है कि कैसे वही Q6/Q8 फ़र्मवेयर 230+ डिस्ट्रीब्यूटर्स के लिए शिप होता है बिना उनके ऐप के किसी अन्य डिस्ट्रीब्यूटर के पेन से गलती से बात किए।

7. OID रिपोर्ट लेआउट

16-बाइट OID पेलोड रिपोर्ट इस प्रकार लेआउट की गई है:

फ़्लैग बाइट ही एकमात्र ऐसा है जिसे कस्टमर ब्रांड को फिर से परिभाषित करने की अनुमति है। हम बिट 2–7 को ब्रांड-विशिष्ट फ़्लैग्स के लिए आवंटित करते हैं (जैसे, "टेस्ट मोड," "डायग्नोस्टिक," "फ़ैक्ट्री फ़्लोर QA")। बिट 0–1 हमारे फ़र्मवेयर के लिए आरक्षित हैं।

8. फ़ीचर रिपोर्ट (ब्रांड ID)

डिस्क्रिप्टर के अंत में एक 4-बाइट की फ़ीचर रिपोर्ट ब्रांड ID रखती है। फ़ीचर रिपोर्ट होस्ट से रीड-ओनली है और फ़ैक्ट्री प्रोविज़निंग के दौरान सेट की जाती है। यह दो उद्देश्यों को पूरा करती है:

1. कंपैनियन ऐप कौन सी कंटेंट कैटलॉग लोड करनी है, यह तय करने के लिए ब्रांड ID पढ़ता है।
2. QA स्टेशन फ़र्मवेयर लोड अखंडता को सत्यापित करने के लिए ब्रांड ID पढ़ता है।

0x09, 0x03,        // Usage (Brand ID)
0x15, 0x00,        // Logical Minimum 0
0x26, 0xFF, 0x00,  // Logical Maximum 255
0x75, 0x08,        // Report Size 8
0x95, 0x04,        // Report Count 4
0xB1, 0x02,        // Feature (Data, Variable, Absolute)

पहला बाइट ब्रांड इंडेक्स है (हमारे पास वर्तमान में 38 ब्रांड इंडेक्स असाइंड हैं), दूसरा एक रीजन कोड है (1=EU, 2=US, 3=APAC, 4=MENA, 5=LATAM, 6=SSA), तीसरा एक कंटेंट रिविज़न है (0–255), और चौथा पहले तीन पर एक CRC है।

9. डिस्क्रिप्टर GATT से कैसे मैप होता है

जब पेन BLE पर होता है, तो वही डिस्क्रिप्टर बाइट्स कैरेक्टरिस्टिक 0x2A4B (रिपोर्ट डिस्क्रिप्टर) द्वारा सर्व की जाती हैं। रिपोर्ट स्वयं कैरेक्टरिस्टिक 0x2A4D पर नोटिफ़िकेशन के माध्यम से भेजी जाती है। Protocol Mode 0x2A4E पर है। ब्रांड ID फ़ीचर रिपोर्ट उसी HID सर्विस पर वेंडर-डिफ़ाइंड कैरेक्टरिस्टिक 0x9F01 (रीड-ओनली) पर एक्सपोज़ की जाती है।

यह TC-060 में प्रलेखित GATT टेबल है।

10. हम हर डिस्क्रिप्टर बिल्ड पर जो वैलिडेशन सूट चलाते हैं

एक डिस्क्रिप्टर शिप होने से पहले, उसे ये पास करना होगा:

यदि इनमें से कोई भी विफल होता है, तो डिस्क्रिप्टर अस्वीकृत कर दिया जाता है और फ़र्मवेयर बिल्ड रोक दिया जाता है। 2023 के बाद से 86 फ़र्मवेयर रिलीज़ में से 6 इस गेट पर अस्वीकृत किए गए और रोल बैक किए गए हैं। सबसे सामान्य कारण गलत एक्सटेंडेड-लेंथ एन्कोडिंग वाला Usage Page टैग है, जो macOS जाँच को विफल कर देता है लेकिन Windows पर पास हो जाता है।

11. ग्राहकों द्वारा आमतौर पर की जाने वाली गलतियाँ

जब कोई ODM ग्राहक अपना स्वयं का डिस्क्रिप्टर ड्राफ़्ट लाता है, तो अस्वीकृति का ~80% केवल तीन गलतियों के कारण होता है:

1. मॉडिफायर के बाद के रिज़र्व्ड बाइट को छोड़ देना। macOS बूट कीबोर्ड रिपोर्ट में बिल्कुल 9 बाइट्स की अपेक्षा करता है (8 मॉडिफायर + 1 रिज़र्व्ड + 6 कीकोड)। ग्राहक अक्सर इसे 8 बाइट्स तक संपीड़ित कर देते हैं, जो Mac पर बूट प्रोटोकॉल को तोड़ देता है।
2. एक्सटेंडेड टैग (0x26) के बिना Logical Maximum 0x00FF का उपयोग करना। शॉर्ट फ़ॉर्म 0x25 0xFF 127 तक के मानों के लिए काम करता है। 255 तक के मानों के लिए, एक्सटेंडेड टैग अनिवार्य है। ग्राहक भूल जाते हैं और डिस्क्रिप्टर Linux पर चुपचाप ट्रंकेट हो जाता है।
3. Output कलेक्शन के अंदर Input रिपोर्ट घोषित करना। HID पार्सर सख्ती से केवल Output कलेक्शन लागू नहीं करता, लेकिन कुछ OS ड्राइवर करते हैं। हम सममिति को स्पष्ट बनाने के लिए OID कलेक्शन में हमेशा Output घोषित करते हैं।

12. परफ़ॉर्मेंस बजट

होस्ट साइड पर, डिस्क्रिप्टर को एन्यूमरेशन के समय एक बार पार्स किया जाता है। डिवाइस साइड पर, हर रिपोर्ट असेंबली डिस्क्रिप्टर मैप को छूती है। Q6/Q8 फ़र्मवेयर 3.3.1 पर हमारा आंतरिक बेंचमार्क:

9.1 µs USB आँकड़ा ही 6.4 ms एंड-टू-एंड लेटेंसी को संभव बनाता है। BLE आँकड़ा 32 ms BLE लेटेंसी का प्रमुख घटक है।

13. बड़ा परिप्रेक्ष्य

यदि आप ऐसी पेन का मूल्यांकन कर रहे हैं जो अपना HID रिपोर्ट डिस्क्रिप्टर खुलकर प्रकाशित नहीं करती, तो यही पहली चीज़ है जो आपको माँगनी चाहिए। जो वेंडर डिस्क्रिप्टर साझा करने से मना करता है, वह या तो गैर-अनुपालन छिपा रहा है, या ऐसे नॉन-HID स्टैक पर निर्माण कर रहा है जिसके लिए आपकी ओर से ड्राइवर कार्य की आवश्यकता होगी। Q6/Q8 फ़र्मवेयर 3.3.1 के लिए हमारा डिस्क्रिप्टर 92 बाइट्स का है और हम इसे अनुरोध पर योग्य ODM ग्राहकों को NDA के तहत प्रकाशित करते हैं।

15. संबंधित रीडिंग

• Reading Pen USB HID और GATT पर HID
• Reading Pen ब्लूटूथ पेयरिंग SSP सिक्योर सिंपल पेयरिंग
• रीडिंग पेन BLE सर्विस कैरेक्टरिस्टिक UUID डिज़ाइन
• रीडिंग पेन GATT सर्वर और नोटिफ़िकेशन मैकेनिज़्म
• रीडिंग पेन USB Type-C चार्जिंग PD QC और BC1.2
• रीडिंग पेन ब्लूटूथ 5.0 बनाम 5.2 बनाम 5.3
• रीडिंग पेन OTA फ़र्मवेयर अपडेट मैकेनिज़्म
• रीडिंग पेन डिक्शनरी फ़ाइल फ़ॉर्मेट और एडिशन