रीडिंग पेन BLE सर्विस कैरेक्टरिस्टिक UUID डिज़ाइन: OID टैप्स और OTA के लिए GATT स्कीमा

लक्षित दर्शक: मोबाइल-ऐप डेवलपर्स, एम्बेडेड फ़र्मवेयर लीड्स और ब्रांड-साइड SDK मालिक जिन्हें रीडिंग पेन के BLE GATT स्कीमा को अपने होस्ट एप्लिकेशन में एकीकृत करना होता है, और जिन्हें यह समझने की आवश्यकता है कि कौन-सी विशेषताएँ SIG-अपनाई गई 16-बिट UUID (इंटरऑप-रेडी) हैं बनाम वेंडर-परिभाषित 128-बिट UUID (मालिकाना), और फ़ील्ड में मौजूदा ऐप्स को तोड़े बिना यह स्कीमा फ़र्मवेयर रिवीज़न के बीच कैसे विकसित होती है।

हमारी दोनों फैक्ट्रियों से 2023 के बाद शिप होने वाला हर रीडिंग पेन एक ही BLE सर्विस सिग्नेचर का विज्ञापन करता है: एक 16-बिट SIG-अपनाई गई Human Interface Device सर्विस UUID 0x1812, साथ ही एक वेंडर-परिभाषित 128-बिट सर्विस UUID जिसका उपयोग होस्ट ऐप पेन को Smart Reading Pen-ब्रांडेड डिवाइस के रूप में पहचानने के लिए करता है। इन सर्विसेज़ के अंदर 11 विशेषताएँ हैं, जिनमें से 6 SIG-अपनाई गई हैं और 5 वेंडर-परिभाषित हैं। कुल GATT डेटाबेस Q6/Q8 फ़र्मवेयर 3.3.1 पर 1.8 KB ROM और F8 फ़र्मवेयर 3.1.2 पर 1.4 KB घेरता है।

यह लेख स्कीमा में मौजूद हर UUID के बारे में बताता है, यह समझाता है कि प्रत्येक SIG-अपनाई गई या वेंडर-परिभाषित क्यों है, और उन नियमों का दस्तावेज़ीकरण करता है जिनका हम नए OEM ग्राहक के लिए स्कीमा बढ़ाते समय पालन करते हैं ताकि मौजूदा 230+ डिस्ट्रीब्यूटर ऐप्स टूटें नहीं।

1. GATT स्कीमा का मायने ही क्यों रखता है

दस्तावेज़ीकृत GATT स्कीमा के बिना BLE पेरिफेरल एक ब्लैक बॉक्स है। होस्ट ऐप को अनुमान लगाना होता है कि कौन-सी विशेषता क्या करती है। कंज्यूमर इलेक्ट्रॉनिक्स उद्योग में, यह "ऐप को पेन नहीं मिल रहा" वाले टिकटों का #1 कारण है। हमारी 47,000+ शिप की गई यूनिट्स में, स्कीमा-संबंधी टिकट 2023 में सभी टिकटों के 4.2% से घटकर 2026 में 0.7% रह गए हैं, ज्यादातर इसलिए क्योंकि अब हम वर्ज़न वाले एक्सटेंशन के साथ एक फ़्रोज़न स्कीमा शिप करते हैं।

Q6/Q8 फ़र्मवेयर 3.3.1 पर हम जिस स्कीमा का उपयोग करते हैं वह है GATT स्कीमा v3.0, अंतिम बार 2025-11 में संशोधित। पिछली v2.x स्कीमा K7/KF1 फ़र्मवेयर 1.9.5 पर शिप हुई थी। v2.x के विरुद्ध लिखे गए ऐप्स v3.0 के विरुद्ध भी काम करते रहते हैं क्योंकि हम केवल विशेषताएँ जोड़ते हैं, कभी हटाते नहीं, और कभी किसी विशेषता का UUID नहीं बदलते।

2. टॉप-लेवल सर्विस लेआउट

पेन अपनी प्राथमिक सर्विस सूची में तीन सर्विसेज़ का विज्ञापन करता है:

Generic Access (0x1800) और Generic Attribute (0x1801) हर BLE पेरिफेरल पर अनिवार्य हैं। वे डिवाइस का नाम, अपीयरेंस और सर्विस-चेंज इंडिकेशन उजागर करते हैं। Human Interface Device (0x1812) HOGP सर्विस है जो OID टैप रिपोर्ट्स ले जाती है। Vendor Service वह जगह है जहाँ हमारी मालिकाना विशेषताएँ रहती हैं। Battery (0x180F) और Device Information (0x180A) मानक SIG-अपनाई गई सर्विसेज़ हैं जिनकी हर होस्ट प्लेटफ़ॉर्म अपेक्षा करता है।

पेन पूरी प्राथमिक सर्विस सूची का विज्ञापन एक ही AD पैकेट में करता है जब MTU अनुमति देता है। F8 (BLE 5.1, MTU 247) पर हम सभी छह फिट कर लेते हैं। पुराने K7/KF1 रेडियो (MTU 23) पर हम AD पैकेट में केवल दो फिट कर पाते हैं और बाकी होस्ट द्वारा सर्विस डिस्कवरी के माध्यम से खोजे जाते हैं।

3. HID सर्विस (0x1812) की विशेषताएँ

HID सर्विस छह विशेषताएँ उजागर करती है:

एक ही UUID 0x2A4D दो रिपोर्ट्स के लिए पुनः उपयोग किया गया है क्योंकि HID सर्विस अपने Report Reference descriptor से पहचानी जाने वाली कई Report characteristics की अनुमति देता है। Q6/Q8 पर हम दो Report characteristics का उपयोग करते हैं: पहली TC-058 में वर्णित OID टैप रिपोर्ट है, और दूसरी एक ऑडियो VU मीटर है (जिसका उपयोग TTS चलने के दौरान होस्ट ऐप में छोटा VU इंडिकेटर दिखाने के लिए किया जाता है)।

4. वेंडर सर्विस की विशेषताएँ

वेंडर सर्विस UUID 8E0C0001-7B3C-4F8E-9F4D-2C8B5A1E0001 है। यह 128-बिट UUID हमारी कंपनी के नाम पर SHA-1 और एक निश्चित प्रीफ़िक्स से बनाया गया है। वेंडर सर्विस के अंदर पाँच विशेषताएँ मौजूद हैं:

प्रत्येक characteristic SIG कन्वेंशन का पालन करती है: एक सामान्य prefix (8E0C0000-7B3C-4F8E-9F4D-2C8B5A1E0000) वाला 128-बिट UUID और एक 16-बिट instance ID। Instance ID के अंतिम 4 बाइट्स characteristic नंबर को encode करते हैं। इससे BLE स्कैनर ऐप में UUID आसानी से देखे जा सकते हैं।

5. बैटरी सर्विस (0x180F)

बैटरी सर्विस एक ही विशेषता प्रदर्शित करती है:

Q6/Q8 firmware 3.3.1 पर पेन 1 Hz पर बैटरी लेवल advertise करता है। ADC सैंपल को शोर हटाने के लिए 4 सैंपल पर औसत किया जाता है। 5% से अधिक का बदलाव तत्काल notify को ट्रिगर करता है; छोटे बदलावों को 1 Hz periodic notify में बैच किया जाता है। होस्ट ऐप मैन्युअल read भी जारी कर सकता है।

एक सूक्ष्म बिंदु: SIG स्पेसिफिकेशन के अनुसार, बैटरी characteristic का मान प्रतिशत में होता है, मिलीवोल्ट में नहीं। मिलीवोल्ट रीडिंग्स इंजीनियरिंग diagnostics के लिए एक अलग vendor characteristic 8E0C0010-7B3C-4F8E-9F4D-2C8B5A1E0001 के माध्यम से expose किए जाते हैं।

6. डिवाइस जानकारी सर्विस (0x180A)

डिवाइस जानकारी सर्विस यह प्रदर्शित करती है:

मॉडल नंबर कैरेक्टरिस्टिक का उपयोग होस्ट ऐप द्वारा सही UI स्किन लोड करने के लिए किया जाता है। हम यहाँ PII नहीं रखते (सिस्टम ID में MAC एड्रेस नहीं; सिस्टम ID कंपनी OUI प्लस प्रति-यूनिट रैंडम UUID है)।

7. होस्ट ऐप को डिस्कवरी प्रक्रिया का पालन करना चाहिए

एक सुव्यवस्थित होस्ट ऐप इस क्रम का पालन करता है:

1. सर्विस UUID सूची में 0x1812 वाले विज्ञापन पैकेट के लिए स्कैन करें।
2. 15 ms कनेक्शन इंटरवल, 0 ms स्लेव लेटेंसी, 4 s सुपरविज़न टाइमआउट के साथ कनेक्ट करें।
3. MTU एक्सचेंज का अनुरोध करें; 247 तक स्वीकार करें।
4. सभी प्राइमरी सर्विसेज़ खोजें।
5. प्रत्येक सर्विस के लिए, सभी कैरेक्टरिस्टिक्स खोजें।
6. प्रत्येक कैरेक्टरिस्टिक के लिए, कैरेक्टरिस्टिक प्रेज़ेंटेशन फ़ॉर्मेट डिस्क्रिप्टर पढ़ें।
7. 0x2A4D (OID टैप) और 8E0C0005 (टेलीमेट्री) पर नोटिफ़िकेशन के लिए सब्सक्राइब करें।
8. बैटरी लेवल (0x2A19) और डिवाइस जानकारी पढ़ें।

एक खराब व्यवहार वाला ऐप डिफ़ॉल्ट पैरामीटर्स के साथ कनेक्ट होता है और तुरंत राइट करने का प्रयास करता है। हम फ़र्स्ट-पार्टी होस्ट ऐप्स में यह 14% में देखते हैं। इसका परिणाम यह होता है कि कनेक्शन ~300 ms की बजाय ~3 s में सेटल होता है। हमारी QA स्कोरिंग उन ऐप्स को पुरस्कृत करती है जो प्रक्रिया का पालन करते हैं।

8. स्कीमा एक्सटेंशन पॉलिसी

हम GATT स्कीमा को तीन नियमों का पालन करते हुए विस्तारित करते हैं:

1. कभी भी किसी कैरेक्टरिस्टिक को डिलीट न करें। एक बार जब कोई UUID प्रोडक्शन फ़र्मवेयर में शिप हो जाता है, तो वह UUID प्लेटफ़ॉर्म के जीवनकाल तक स्कीमा में रहता है। पुराने ऐप्स इसे पढ़ते रहते हैं और वैल्यू को अनदेखा करते हैं।
2. कभी भी UUID न बदलें। UUID एक 128-बिट पहचान है। इसे बदलना हर उस ऐप को तोड़ देता है जिसने इसे नोट किया था।
3. नई कैरेक्टरिस्टिक्स को अगले फ़्री इंस्टेंस ID पर जोड़ें। वेंडर सर्विस में 256 इंस्टेंस ID रिज़र्व हैं (0x0001 से 0x0100)। जब हम एक नई कैरेक्टरिस्टिक जोड़ते हैं, तो हम अगली फ़्री ID चुनते हैं और स्कीमा माइनर वर्शन को बढ़ाते हैं।

स्कीमा v3.0 (वर्तमान) इंस्टेंस ID 0x0001 से 0x0010 का उपयोग करता है। स्कीमा v4.0 (L5 फ़र्मवेयर 4.3.0 के लिए नियोजित) क्लासरूम-मोड टेलीमेट्री से संबंधित नई कैरेक्टरिस्टिक्स के लिए इंस्टेंस ID 0x0011 से 0x0020 का उपयोग करेगा।

9. परफ़ॉर्मेंस: डिस्कवरी टाइम

जो होस्ट एप यह सब 1 सेकंड से कम में पूरा करती है वह "तेज़" है; 1.5 सेकंड "सामान्य" है; 2 सेकंड से अधिक "ख़राब" है। हमारी 38 इन-हाउस iOS/Android/Windows रेफ़रेंस ऐप्स सभी 1.5 सेकंड से कम में पूरी होती हैं।

10. मॉडलों के बीच स्कीमा अंतर

L5, T2 और Y6 ही एकमात्र ऐसे मॉडल हैं जिनमें क्लासरूम-मोड की विशेषताएँ मौजूद हैं, क्योंकि ये मॉडल शिक्षा चैनल में बेचे जाते हैं। K7/KF1 एकल-उपयोगकर्ता होम पेन है, इसलिए इसमें क्लासरूम की विशेषताएँ नहीं हैं।

11. फ़र्मवेयर रिवीज़न के बीच स्कीमा अंतर

स्कीमा फॉरवर्ड-संगत है: स्कीमा 2.0 के विरुद्ध लिखा गया ऐप स्कीमा 3.1 फर्मवेयर चलाने वाले पेन से कनेक्ट हो सकता है और स्कीमा 2.0 की सभी विशेषताओं को पढ़ सकता है; यह बस नई विशेषताओं को छोड़ देगा।

12. ब्रांड-विशिष्ट UUID कैसे आवंटित करें

एक ODM ग्राहक ब्रांड-विशिष्ट विशेषताओं का अनुरोध कर सकता है। हम 0x0100 से 0x01FF रेंज से आवंटित करते हैं। ग्राहक इस रेंज से 16 इंस्टेंस ID चुनता है, और हम उन्हें GATT स्कीमा मैनिफेस्ट में पंजीकृत करते हैं। मैनिफेस्ट फर्मवेयर रिपॉजिटरी में एक YAML फ़ाइल है; यह सभी इंस्टेंस ID, विशेषता का नाम, प्रॉपर्टी मास्क, आकार और प्रारंभिक मान सूचीबद्ध करता है। यदि दो ग्राहक एक ही इंस्टेंस ID का अनुरोध करते हैं तो CI विफल हो जाता है।

Q6/Q8 फर्मवेयर 3.3.1 के लिए मैनिफेस्ट 38 वर्तमान में आवंटित ब्रांड-विशिष्ट रेंज सूचीबद्ध करता है। हम और 13 रेंज समायोजित कर सकते हैं इससे पहले कि 0x0100 से 0x01FF स्थान समाप्त हो जाए और 0x0200 तक विस्तार की आवश्यकता हो।

13. GATT डेटाबेस कंप्रेशन ट्रिक

एक GATT डेटाबेस को ROM में 1.8 KB ब्लॉब में चपटा किया जा सकता है। हम जो प्रारूप उपयोग करते हैं:

[uint16 service_count]
प्रत्येक सेवा के लिए:
  [uint16 service_uuid_type] [128-bit UUID]
  [uint16 characteristic_count]
  प्रत्येक विशेषता के लिए:
    [uint16 char_uuid_type] [128-bit UUID]
    [uint8 properties]
    [uint8 value_size]
    [uint8 descriptor_count]
    प्रत्येक डिस्क्रिप्टर के लिए:
      [uint16 desc_uuid_type] [128-bit UUID]
      [uint8 payload_size] [payload]

ब्लॉब फर्मवेयर बिल्ड समय पर एक Python स्क्रिप्ट द्वारा उत्पन्न होता है जो YAML मैनिफेस्ट पढ़ता है। Q6/Q8 फर्मवेयर 3.3.1 पर कुल ROM लागत 1,824 बाइट्स है। F8 HID सेवा को 5 विशेषताओं में संक्षिप्त करके 384 बाइट्स बचाता है, 6 के बजाय (कोई Audio VU नहीं)।

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

इनमें से किसी भी जाँच में विफल होने वाली स्कीमा को अस्वीकार कर दिया जाता है। 2023 के बाद से 86 फर्मवेयर रिलीज़ में से 4 को इस गेट पर अस्वीकार किया गया है।

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

• रीडिंग पेन USB HID और HID over GATT
• रीडिंग पेन HID रिपोर्ट डिस्क्रिप्टर और यूज़ेज पेज
• रीडिंग पेन ब्लूटूथ पेयरिंग SSP सिक्योर सिंपल पेयरिंग
• रीडिंग पेन GATT सर्वर और नोटिफिकेशन मैकेनिज्म
• रीडिंग पेन ब्लूटूथ 5.0 vs 5.2 vs 5.3
• रीडिंग पेन OTA फर्मवेयर अपडेट मैकेनिज्म
• रीडिंग पेन टेलीमेट्री सैंपल रेट
• रीडिंग पेन क्रिप्टोग्राफ़ी और TrustZone