Målgruppe: Mobilapp-udviklere, indlejrede firmware-ansvarlige og brand-side SDK-ejere, som skal integrere en læseblyants BLE GATT-skema i deres værtsapplikation, og som har behov for at forstå, hvilke karakteristika der er SIG-vedtagne 16-bit UUID'er (interop-klar) versus leverandørdefinerede 128-bit UUID'er (proprietære), og hvordan skemaet udvikler sig mellem firmware-revisioner uden at bryde eksisterende apps i felten.
Hver læseblyant, der er sendt fra vores to fabrikker siden 2023, har annonceret den samme BLE-servicessignatur: en 16-bit SIG-vedtagen Human Interface Device-service-UUID 0x1812, plus en leverandørdefineret 128-bit service-UUID, som værtsappen bruger til at identificere blyanten som en Smart Reading Pen-mærket enhed. Inde i disse tjenester sidder 11 karakteristika, hvoraf 6 er SIG-vedtagne og 5 er leverandørdefinerede. Den samlede GATT-database fylder 1,8 KB ROM på Q6/Q8 firmware 3.3.1 og 1,4 KB på F8 firmware 3.1.2.
Denne artikel gennemgår hver UUID i skemaet, forklarer hvorfor hver enkelt er SIG-vedtaget eller leverandørdefineret, og dokumenterer de regler, vi følger, når vi udvider skemaet til en ny OEM-kunde, så de eksisterende 230+ distributor-apps ikke bryder.
1. Hvorfor et GATT-skema overhovedet betyder noget
En BLE-periferienhed uden dokumenteret GATT-skema er en sort boks. Værtsappen skal gætte, hvilken karakteristik der gør hvad. I forbrugerelektronikindustrien er dette den #1-årsag til sager om "appen kan ikke finde blyanten". På tværs af vores 47.000+ sendte enheder er de skema-relaterede sager faldet fra 4,2 % af alle sager i 2023 til 0,7 % i 2026, hovedsageligt fordi vi nu leverer et frosset skema med versionsstyrede udvidelser.
Det skema, vi bruger på Q6/Q8 firmware 3.3.1, er GATT-skema v3.0, sidst revideret 2025-11. Det tidligere v2.x-skema blev leveret på K7/KF1 firmware 1.9.5. Apps skrevet mod v2.x fortsætter med at virke mod v3.0, fordi vi kun tilføjer karakteristika, aldrig fjerner dem, og vi ændrer aldrig en karakteristiks UUID.
2. Det overordnede service-layout
Blyanten annoncerer tre tjenester i sin primære serviceliste:
| Tjeneste | UUID | Type | Påkrævet |
|---|---|---|---|
| Generic Access | 0x1800 | SIG 16-bit | Ja |
| Generic Attribute | 0x1801 | SIG 16-bit | Ja |
| Human Interface Device | 0x1812 | SIG 16-bit | Ja |
| Smart Reading Pen Vendor Service | 8E0C0001-7B3C-4F8E-9F4D-2C8B5A1E0001 | Leverandør 128-bit | Ja |
| Battery Service | 0x180F | SIG 16-bit | Ja |
| Device Information | 0x180A | SIG 16-bit | Ja |
Generic Access (0x1800) og Generic Attribute (0x1801) er obligatoriske på hver BLE-periferienhed. De eksponerer enhedsnavn, udseende og serviceændringsindikation. Human Interface Device (0x1812) er HOGP-tjenesten, der bærer OID-tap-rapporterne. Leverandørtjenesten er hvor vores proprietære karakteristika bor. Battery (0x180F) og Device Information (0x180A) er standard SIG-vedtagne tjenester, som alle værtsplatforme forventer.
Blyanten annoncerer den fulde primære serviceliste i en enkelt AD-pakke, når MTU'en tillader det. På F8 (BLE 5.1, MTU 247) passer alle seks. På ældre K7/KF1-radioer (MTU 23) er der kun plads til to i AD-pakken, og resten opdages af værten via serviceopdagelse.
3. HID-tjenestens (0x1812) karakteristika
HID-tjenesten eksponerer seks karakteristika:
| Karakteristik | UUID | Egenskaber | Noter |
|---|---|---|---|
| HID Information | 0x2A4A | Read | bcdHID, bCountryCode, flags |
| Report Map | 0x2A4B | Read | Deskriptor-blobben fra TC-058 |
| Protocol Mode | 0x2A4E | Read, Write | Report vs Boot |
| HID Control Point | 0x2A4C | SkrivUdenSvar | Pause / Genoptag |
| Rapport (Reference 1) | 0x2A4D | Notificer, Skriv, SkrivUdenSvar | OID-tap-rapport |
| Rapport (Reference 2) | 0x2A4D | Notificer | Audio VU-måler |
Den enkelte UUID 0x2A4D genbruges til to rapporter, fordi HID-tjenesten tillader flere Report-karakteristika identificeret ved deres Report Reference-deskriptor. På Q6\/Q8 bruger vi to Report-karakteristika: det første er OID-tap-rapporten beskrevet i TC-058, det andet er en audio VU-måler (brugt af host-appen til at vise en lille VU-indikator, mens TTS afspilles).
4. Vendor-tjenestens karakteristika
Vendor-tjenestens UUID er 8E0C0001-7B3C-4F8E-9F4D-2C8B5A1E0001. Den 128-bit UUID blev genereret ved hjælp af en SHA-1 over vores virksomhedsnavn og et fast prefix. Inde i vendor-tjenesten sidder fem karakteristika:
| Karakteristikum | UUID | Egenskaber | Formål |
|---|---|---|---|
| Brand-ID | 8E0C0002-7B3C-4F8E-9F4D-2C8B5A1E0001 | Læs | Frosset 4-byte brandidentifikator |
| Ordbogsstatus | 8E0C0003-7B3C-4F8E-9F4D-2C8B5A1E0001 | Læs, Notificer | Aktuelt indlæst sprogpakke |
| Lydstyring | 8E0C0004-7B3C-4F8E-9F4D-2C8B5A1E0001 | Skriv | Lydstyrke, mute, EQ-forindstilling |
| Telemetri | 8E0C0005-7B3C-4F8E-9F4D-2C8B5A1E0001 | Notificer, Indiker | Logs, fejlkoder |
| OTA-styring | 8E0C0006-7B3C-4F8E-9F4D-2C8B5A1E0001 | Skriv, Indiker | Firmware-opdateringsudløser |
Hvert karakteristikum følger SIG-konventionen: en 128-bit UUID med et fælles prefix (8E0C0000-7B3C-4F8E-9F4D-2C8B5A1E0000) og et 16-bit instans-ID. De sidste 4 bytes af instans-ID'et koder karakteristikumets nummer. Det gør UUID'erne visuelt nemme at scanne i en BLE-scanner-app.
5. Batteritjenesten (0x180F)
Batteritjenesten eksponerer et enkelt karakteristikum:
| Karakteristikum | UUID | Egenskaber | Formål |
|---|---|---|---|
| Batteriniveau | 0x2A19 | Læs, Notificer | 0–100% opladning |
Pennen annoncerer batteriniveau ved 1 Hz på Q6\/Q8 firmware 3.3.1. ADC-prøven midles over 4 prøver for at fjerne støj. En ændring på mere end 5% udløser en øjeblikkelig notificering; mindre deltaer batches i den periodiske 1 Hz-notificering. Host-appen kan også udstede et manuelt læs.
Et subtilt punkt: batterikarakteristikumets værdi er i procent, ikke millivolt, i henhold til SIG-specifikationen. Millivolt-aflæsninger eksponeres via et separat vendor-karakteristikum 8E0C0010-7B3C-4F8E-9F4D-2C8B5A1E0001 til teknisk diagnostik.
6. Device Information-tjenesten (0x180A)
Device Information-tjenesten eksponerer:
| Karakteristikum | UUID | Egenskaber | Værdi på Q6\/Q8 |
|---|---|---|---|
| Producentnavn | 0x2A29 | Læs | "Smart Reading Pen Mfg Co." |
| Modelnummer | 0x2A24 | Læs | "Q8" |
| Serienummer | 0x2A25 | Læs | 12-tegns ASCII pr. enhed |
| Hardware-revision | 0x2A26 | Læs | "Rev. D" |
| Firmware-revision | 0x2A26 | Læs | "3.3.1" |
| Software-revision | 0x2A28 | Læs | "Build 8642" |
| System-ID | 0x2A23 | Læs | OUI + UUID pr. enhed |
Modelnummer-karakteristikken bruges af host-appen til at indlæse den korrekte UI-skin. Vi lægger ikke PII her (ingen MAC-adresse i System-ID; System-ID'et er virksomhedens OUI plus den tilfældige UUID pr. enhed).
7. Den opdagelsesprocedure, host-appen bør følge
En velopdragen host-app følger denne rækkefølge:
- Scan efter annoncepakke, der indeholder 0x1812 i tjeneste-UUID-listen.
- Opret forbindelse med 15 ms forbindelsesinterval, 0 ms slave-latency og 4 s supervisionstimeout.
- Anmod om MTU-udveksling; accepter op til 247.
- Opdag alle primære tjenester.
- Opdag alle karakteristikker for hver tjeneste.
- Læs Characteristic Presentation Format-deskriptoren for hver karakteristik.
- Abonnér på notifikationer på 0x2A4D (OID-tryk) og 8E0C0005 (telemetri).
- Læs batteriniveau (0x2A19) og enhedsinformation.
En dårligt opført app opretter forbindelse med standardparametre og forsøger straks at skrive. Det ser vi i 14 % af first-party host-apps. Resultatet er, at forbindelsen bruger ~3 s på at stabilisere sig i stedet for ~300 ms. Vores QA-scoringssystem belønner apps, der følger proceduren.
8. Skema-udvidelsespolitikken
Vi udvider GATT-skemaet efter tre regler:
- Slet aldrig en karakteristik. Når en UUID først sendes i en produktionsfirmware, forbliver den UUID i skemaet i hele platformens levetid. Gamle apps læser den stadig og ignorerer værdien.
- Ændr aldrig en UUID. UUID'en er en 128-bit-identitet. Hvis den ændres, knækker det alle apps, der har noteret den.
- Tilføj nye karakteristikker ved det næste ledige instans-ID. Leverandørtjenesten har 256 instans-ID'er reserveret (0x0001 til 0x0100). Når vi tilføjer en ny karakteristik, vælger vi den næste ledige og øger skemaets minor-version.
Skema v3.0 (nuværende) bruger instans-ID'er 0x0001 til 0x0010. Skema v4.0 (planlagt til L5-firmware 4.3.0) vil bruge instans-ID'er 0x0011 til 0x0020 til nye karakteristikker relateret til telemetri i klasserums-tilstand.
9. Ydelse: Opdagelsestid
| Trin | Tid på Q6/Q8 | Tid på F8 | Tid på K7/KF1 |
|---|---|---|---|
| Opret forbindelse til første tjeneste | 95 ms | 110 ms | 145 ms |
| Alle tjenester opdaget | 280 ms | 330 ms | 520 ms |
| Alle karakteristikker opdaget | 410 ms | 490 ms | 880 ms |
| CCCD-deskriptorer læst | 220 ms | 280 ms | 480 ms |
| MTU-udveksling | 38 ms | 42 ms | 65 ms |
| Samlet første par | 1,04 s | 1,25 s | 2,1 s |
En host-app, der gør alt dette på under 1 s, er "hurtig"; 1,5 s er "normal"; over 2 s er "dårlig". Vores 38 interne referenceapps til iOS/Android/Windows ligger alle under 1,5 s.
10. Skemaforskellen mellem modeller
| Karakteristik | Q6/Q8 | F8 | K7/KF1 | L5 | T2/Y6 | P2 |
|---|---|---|---|---|---|---|
| HID 0x2A4D (OID) | Ja | Ja | Ja | Ja | Ja | Ja |
| HID 0x2A4D (VU) | Ja | Nej | Nej | Ja | Ja | Nej |
| Batteri 0x2A19 | Ja | Ja | Ja | Ja | Ja | Ja |
| Brand-ID 8E0C0002 | Ja | Ja | Ja | Ja | Ja | Ja |
| Ordbogsstatus 8E0C0003 | Ja | Ja | Ja | Ja | Ja | Ja |
| Lydstyring 8E0C0004 | Ja | Nej | Nej | Ja | Ja | Nej |
| Telemetri 8E0C0005 | Ja | Ja | Ja | Ja | Ja | Ja |
| OTA-styring 8E0C0006 | Ja | Ja | Ja | Ja | Ja | Ja |
| Leverandørlyd VU 8E0C0007 | Ja | Nej | Nej | Ja | Ja | Nej |
| Leverandørtesttilstand 8E0C0008 | Ja | Ja | Nej | Ja | Ja | Nej |
| Leverandørklassetilstand 8E0C0009 | Nej | Nej | Nej | Ja | Ja | Nej |
L5, T2 og Y6 er de eneste modeller, der har klasseundervisningsegenskaberne, da det er de modeller, der sælges til uddannelseskanalen. K7/KF1 er en enkeltbrugers hjemmepen, så klasseundervisningsegenskaber er fraværende.
11. Skemaforskellen mellem firmware-revisioner
| Firmware | Skemaversion | Tilføj | Fjern | Kompatibel med |
|---|---|---|---|---|
| K7 1.9.0 | 2.0 | — | — | Skema 2.0 |
| K7 1.9.5 | 2.1 | 8E0C0006 OTA | — | Skema 2.0, 2.1 |
| F8 3.1.0 | 2.5 | 8E0C0007 VU | — | Skema 2.5 |
| F8 3.1.2 | 2.5.1 | — | — | Skema 2.5 |
| Q6/Q8 3.3.0 | 3.0 | 8E0C0008 Test | — | Skema 3.0 |
| Q6/Q8 3.3.1 | 3.0 | — | — | Skema 3.0 |
| L5 4.2.0 | 3.1 | 8E0C0009 Classroom | — | Skema 3.1 |
| T2/Y6 2.6.4 | 3.1 | — | — | Skema 3.1 |
Skemaet er fremadkompatibelt: en app, der er skrevet mod Skema 2.0, kan oprette forbindelse til en pen, der kører Skema 3.1-firmware, og læse alle Skema 2.0-egenskaberne; den vil blot springe de nye over.
12. Sådan tildeles brandspecifikke UUID'er
En ODM-kunde kan anmode om brandspecifikke egenskaber. Vi tildeler fra intervallet 0x0100 til 0x01FF. Kunden vælger 16 instans-ID'er fra dette interval, og vi registrerer dem i GATT-skemamanifestet. Manifestet er en YAML-fil i firmware-repositoriet; det indeholder alle instans-ID'er, egenskabsnavnet, egenskabsmasken, størrelsen og den initiale værdi. CI fejler, hvis to kunder anmoder om det samme instans-ID.
Manifestet for Q6/Q8-firmware 3.3.1 angiver 38 aktuelt tildelte brandspecifikke intervaller. Vi kan rumme 13 mere, før vi løber tør for pladsen 0x0100 til 0x01FF og skal udvide til 0x0200.
13. GATT-databasekompressionstricket
En GATT-database kan fladtrykkes til en 1,8 KB-blob i ROM. Det format, vi bruger:
[uint16 service_count]
for hver service:
[uint16 service_uuid_type] [128-bit UUID]
[uint16 characteristic_count]
for hver egenskab:
[uint16 char_uuid_type] [128-bit UUID]
[uint8 properties]
[uint8 value_size]
[uint8 descriptor_count]
for hver descriptor:
[uint16 desc_uuid_type] [128-bit UUID]
[uint8 payload_size] [payload]
Blobben genereres på firmware-byggetidspunktet af et Python-script, der læser YAML-manifestet. De samlede ROM-omkostninger er 1.824 bytes på Q6/Q8-firmware 3.3.1. F8 sparer 384 bytes ved at sammenfolde HID-service til 5 egenskaber i stedet for 6 (ingen Audio VU).
14. Valideringssuite, vi kører på hvert skema
| Kontrol | Værktøj | Godkendelseskriterium |
|---|---|---|
| UUID-unikhed | Python CI-script | Ingen duplikerede UUID'er i manifestet |
| Skema fremadkompat | Brugerdefineret Python-stativ | Skema N+1 kan parses som Skema N |
| Discovery-tid | Saleae + Wireshark | Under 1,5 s på Q6/Q8 |
| Batterinotifikationsrate | Logikanalysator | Nøjagtigt 1 Hz ±5% |
| OTA-egenskab | CI-script | OTA-egenskab til stede på al produktionsfirmware |
Et skema, der ikke består en af disse kontroller, afvises. Blandt 86 firmware-udgivelser siden 2023 er 4 blevet afvist ved denne gate.
16. Relateret læsning
- Læsepen USB HID og HID over GATT
- Læsepens HID Report Descriptor og Usage Page
- Læsepen Bluetooth-parring SSP Secure Simple Pairing
- Læsepen GATT-server og notifikationsmekanisme
- Læsepen Bluetooth 5.0 vs 5.2 vs 5.3
- Læsepen OTA-firmwareopdateringsmekanisme
- Læsepens telemetri-samplingfrekvens
- Læsepens kryptografi og TrustZone