Návrh UUID charakteristik BLE služby čtecího pera: GATT schéma pro OID tapnutí a OTA

Cílová skupina: Vývojáři mobilních aplikací, vedoucí embedded firmware a vlastníci SDK na straně značky, kteří musí integrovat BLE GATT schéma čtecího pera do své hostitelské aplikace a potřebují rozumět tomu, která charakteristika jsou SIG-adoptované 16bitové UUID (připravené pro interoperabilitu) oproti vendor-defined 128bitovým UUID (proprietární), a jak se schéma vyvíjí mezi revizemi firmware bez narušení stávajících aplikací v terénu.

Každé čtecí pero, které od roku 2023 odešlo z našich dvou továren, inzeruje stejnou BLE servisní signaturu: 16bitový SIG-adoptovaný UUID služby Human Interface Device 0x1812 plus vendor-defined 128bitový UUID služby, který hostitelská aplikace používá k identifikaci pera jako zařízení značky Smart Reading Pen. Uvnitř těchto služeb se nachází 11 charakteristik, z nichž 6 je SIG-adoptovaných a 5 vendor-defined. Celá GATT databáze zabírá 1,8 KB ROM na Q6/Q8 firmware 3.3.1 a 1,4 KB na F8 firmware 3.1.2.

Tento článek prochází každé UUID ve schématu, vysvětluje, proč je každé z nich SIG-adoptované nebo vendor-defined, a dokumentuje pravidla, která dodržujeme při rozšiřování schématu pro nového OEM zákazníka, aby se stávajících 230+ aplikací distributorů nerozbilo.

1. Proč vůbec záleží na GATT schématu

BLE periferie bez zdokumentovaného GATT schématu je černá skříňka. Hostitelská aplikace musí hádat, která charakteristika co dělá. V odvětví spotřební elektroniky je to hlavní příčina tiketů typu „aplikace nemůže najít pero“. Napříč našimi 47 000+ dodanými jednotkami klesl podíl tiketů souvisejících se schématem ze 4,2 % všech tiketů v roce 2023 na 0,7 % v roce 2026, zejména proto, že nyní dodáváme zmražené schéma s verzovanými rozšířeními.

Schéma, které používáme na Q6/Q8 firmware 3.3.1, je GATT Schema v3.0, naposledy revidováno 2025-11. Předchozí schéma v2.x bylo dodáváno na K7/KF1 firmware 1.9.5. Aplikace napsané proti v2.x fungují dál i proti v3.0, protože přidáváme pouze charakteristiky, nikdy je neodebíráme a nikdy neměníme UUID charakteristiky.

2. Rozložení služeb nejvyšší úrovně

Pero inzeruje v seznamu primárních služeb tři služby:

Generic Access (0x1800) a Generic Attribute (0x1801) jsou povinné na každé BLE periferii. Zpřístupňují název zařízení, vzhled a indikaci změny služby. Human Interface Device (0x1812) je HOGP služba, která nese OID tap reporty. Vendor Service je místo, kde sídlí naše proprietární charakteristiky. Battery (0x180F) a Device Information (0x180A) jsou standardní SIG-adoptované služby, které očekává každá hostitelská platforma.

Pero inzeruje celý seznam primárních služeb v jednom AD paketu, když to MTU dovolí. Na F8 (BLE 5.1, MTU 247) se vejdou všechny tři. Na starších K7/KF1 radiích (MTU 23) se do AD paketu vejdou pouze dvě a zbytek hostitel objeví pomocí service discovery.

3. Charakteristiky HID služby (0x1812)

HID služba zpřístupňuje šest charakteristik:

Jedno UUID 0x2A4D je znovu použito pro dva reporty, protože HID služba povoluje více Report charakteristik identifikovaných jejich Report Reference deskriptorem. Na Q6/Q8 používáme dvě Report charakteristiky: první je OID tap report popsaný v TC-058, druhá je audio VU meter (používaný hostitelskou aplikací pro zobrazení malého VU indikátoru během přehrávání TTS).

4. Charakteristiky Vendor Service

UUID vendor služby je 8E0C0001-7B3C-4F8E-9F4D-2C8B5A1E0001. 128bitové UUID bylo vygenerováno pomocí SHA-1 přes název naší společnosti a pevnou předponu. Uvnitř vendor služby se nachází pět charakteristik:

Každá charakteristika dodržuje konvenci SIG: 128bitové UUID se společnou předponou (8E0C0000-7B3C-4F8E-9F4D-2C8B5A1E0000) a 16bitovým ID instance. Poslední 4 bajty ID instance kódují číslo charakteristiky. Díky tomu jsou UUID v BLE scanner aplikaci vizuálně snadno čitelné.

5. Battery Service (0x180F)

Battery service zpřístupňuje jednu charakteristiku:

Pero inzeruje úroveň baterie na 1 Hz na Q6/Q8 firmwaru 3.3.1. ADC vzorek je průměrován přes 4 vzorky pro odstranění šumu. Změna o více než 5 % spustí okamžitý notify; menší rozdíly jsou dávkovány do 1 Hz periodického notify. Hostitelská aplikace může také provést manuální čtení.

Jemný bod: hodnota charakteristiky baterie je v procentech, ne v milivoltech, dle specifikace SIG. Čtení v milivoltech jsou zpřístupněna prostřednictvím samostatné vendor charakteristiky 8E0C0010-7B3C-4F8E-9F4D-2C8B5A1E0001 pro inženýrskou diagnostiku.

6. Device Information Service (0x180A)

Služba Device Information zpřístupňuje:

Charakteristika Číslo modelu se používá hostovskou aplikací k načtení správného uživatelského rozhraní. Neukládáme zde žádné osobní údaje (žádná MAC adresa v ID systému; ID systému tvoří firemní OUI a náhodné UUID jednotky).

7. Postup zjišťování, který by hostovská aplikace měla dodržovat

Řádně fungující hostovská aplikace dodržuje následující posloupnost:

1. Vyhledá reklamní paket obsahující 0x1812 v seznamu UUID služeb.
2. Připojí se s intervalem připojení 15 ms, latencí slave 0 ms a dobou dohledu 4 s.
3. Vyžádá výměnu MTU; přijme hodnoty až do 247.
4. Zjistí všechny primární služby.
5. Pro každou službu zjistí všechny charakteristiky.
6. Pro každou charakteristiku přečte popis Characteristic Presentation Format.
7. Přihlásí se k oznámením pro 0x2A4D (klepnutí OID) a 8E0C0005 (telemetrie).
8. Přečte úroveň baterie (0x2A19) a informace o zařízení.

Nepořádně fungující aplikace se připojí s výchozími parametry a okamžitě se pokusí o zápis. Toto chování pozorujeme u 14 % našich vlastních hostovských aplikací. Výsledkem je, že připojení trvá ustálení přibližně 3 s místo přibližně 300 ms. Naše hodnocení QA odměňuje aplikace, které tento postup dodržují.

8. Zásady rozšiřování schématu

Schéma GATT rozšiřujeme podle tří pravidel:

1. Charakteristiku nikdy neodstraňujeme. Jakmile je UUID vydán v produkčním firmwaru, zůstává ve schématu po celou dobu existence platformy. Staré aplikace jej budou nadále číst a hodnotu ignorovat.
2. UUID nikdy neměníme. UUID je 128bitová identita. Jeho změna přeruší kompatibilitu se všemi aplikacemi, které si jej uložily.
3. Nové charakteristiky přidáváme na další volné ID instance. Pro službu výrobce je vyhrazeno 256 ID instancí (0x0001 až 0x0100). Při přidání nové charakteristiky zvolíme další volné ID a zvýšíme dílčí verzi schématu.

Schéma v3.0 (současné) používá ID instancí 0x0001 až 0x0010. Schéma v4.0 (plánované pro firmware L5 4.3.0) bude používat ID instancí 0x0011 až 0x0020 pro nové charakteristiky související s telemetrií režimu ve třídě.

9. Výkon: Doba zjišťování

Hostitelská aplikace, která zvládne vše pod 1 s, je „rychlá“; 1,5 s je „normální“; nad 2 s je „pomalá“. Našich 38 referenčních aplikací pro iOS/Android/Windows vyvinutých interně se všechny vejdou pod 1,5 s.

10. Rozdíl ve schématu mezi modely

Modely L5, T2 a Y6 jsou jediné, které nesou charakteristiky režimu třídy, protože tyto modely se prodávají do vzdělávacího kanálu. K7/KF1 je jednouživatelské domácí pero, takže charakteristiky režimu třídy chybí.

11. Rozdíl schémat mezi revizemi firmwaru

Schéma je zpětně i dopředně kompatibilní: aplikace napsaná pro Schema 2.0 se může připojit k peru s firmwarem Schema 3.1 a číst všechny charakteristiky Schema 2.0; nové jednoduše přeskočí.

12. Jak alokovat brand-specific UUID

Zákazník ODM může požádat o charakteristiky specifické pro značku. Alokujeme z rozsahu 0x0100 až 0x01FF. Zákazník si z tohoto rozsahu zvolí 16 ID instancí a my je zaregistrujeme v manifestu schématu GATT. Manifest je soubor YAML v repozitáři firmwaru; obsahuje seznam všech ID instancí, název charakteristiky, masku vlastností, velikost a počáteční hodnotu. CI selže, pokud si dva zákazníci vyžádají stejné ID instance.

Manifest pro firmware Q6/Q8 3.3.1 uvádí 38 aktuálně alokovaných rozsahů specifických pro značku. Dokud nám nedojde prostor 0x0100 až 0x01FF a budeme muset rozšířit na 0x0200, můžeme pojmout ještě 13 dalších.

13. Trik s kompresí databáze GATT

Databázi GATT lze sloučit do blobu o velikosti 1,8 KB v ROM. Používáme tento formát:

[uint16 service_count]
pro každou službu:
  [uint16 service_uuid_type] [128-bit UUID]
  [uint16 characteristic_count]
  pro každou charakteristiku:
    [uint16 char_uuid_type] [128-bit UUID]
    [uint8 properties]
    [uint8 value_size]
    [uint8 descriptor_count]
    pro každý deskriptor:
      [uint16 desc_uuid_type] [128-bit UUID]
      [uint8 payload_size] [payload]

Blob se generuje při sestavení firmwaru python skriptem, který čte manifest YAML. Celkové náklady na ROM jsou 1 824 bajtů u firmwaru Q6/Q8 3.3.1. F8 ušetří 384 bajtů tím, že sloučí službu HID do 5 charakteristik místo 6 (bez Audio VU).

14. Validační sada spouštěná na každém Schématu

Schéma, které nesplní některou z těchto kontrol, je zamítnuto. Z 86 verzí firmwaru od roku 2023 byly na této bráně zamítnuty 4.

16. Související čtení

• Čtecí pero USB HID a HID over GATT
• Čtecí pero – HID Report Descriptor a Usage Page
• Čtecí pero – párování Bluetooth SSP Secure Simple Pairing
• Čtecí pero – GATT Server a mechanismus notifikací
• Čtecí pero – Bluetooth 5.0 vs 5.2 vs 5.3
• Čtecí pero – mechanismus OTA aktualizace firmwaru
• Čtecí pero – vzorkovací frekvence telemetrie
• Čtecí pero – kryptografie a TrustZone