Lukupiirtimen BLE-palvelun karakteristiikan UUID-suunnittelu: GATT-kaavio OID-tapauksille ja OTA-päivityksille

Kohderyhmä: Mobiilisovelluskehittäjät, sulautettujen laiteohjelmistojen vastaavat sekä brändipuolen SDK-omistajat, joiden on integroitava lukukynän BLE GATT -skeema isäntäsovellukseensa ja jotka tarvitsevat ymmärrystä siitä, mitkä karakteristiikat ovat SIG:n hyväksymiä 16-bittisiä UUID-tunnuksia (yhteensopivia) ja mitkä valmistajakohtaisia 128-bittisiä UUID-tunnuksia (omisteisia), sekä miten skeema kehittyy laiteohjelmistoversioiden välillä rikkomatta jo käytössä olevia sovelluksia.

Jokainen kahdelta tehtaaltamme vuodesta 2023 lähtien toimitettu lukukynä on mainostanut samaa BLE-palvelusignatuuria: 16-bittinen SIG:n hyväksymä Human Interface Device -palvelun UUID 0x1812 sekä valmistajakohtainen 128-bittinen palvelun UUID, jota isäntäsovellus käyttää tunnistaakseen kynän Smart Reading Pen -brändätyksi laitteeksi. Näiden palveluiden sisällä on 11 karakteristiikkaa, joista 6 on SIG:n hyväksymiä ja 5 valmistajakohtaisia. GATT-tietokanta vie 1,8 KB ROM-muistia Q6/Q8-laiteohjelmistossa 3.3.1 ja 1,4 KB F8-laiteohjelmistossa 3.1.2.

Tämä artikkeli käy läpi jokaisen UUID:n skeemassa, selittää miksi kukin niistä on SIG:n hyväksymä tai valmistajakohtainen, sekä dokumentoi säännöt, joita noudatamme laajentaessamme skeemaa uudelle OEM-asiakkaalle, jotta olemassa olevat 230+ jakelijasovellukset eivät rikkoudu.

1. Miksi GATT-skeemalla on ylipäänsä väliä

BLE-oheislaite ilman dokumentoitu GATT-skeemaa on musta laatikko. Isäntäsovelluksen täytyy arvata, mikä karakteristiikka tekee mitäkin. Kulutuselektroniikkateollisuudessa tämä on yleisin syy ”sovellus ei löydä kynää” -tukipyyntöihin. Yli 47 000 toimitetun yksikön joukossa skeemaan liittyvät tukipyynnöt ovat pudonneet 4,2 %:sta kaikista tukipyynnöistä vuonna 2023 vain 0,7 %:iin vuonna 2026, pääasiassa siksi, että toimitamme nyt jäädytetyn skeeman versioiduilla laajennuksilla.

Q6/Q8-laiteohjelmiston 3.3.1 käyttämä skeema on GATT-skeema v3.0, viimeksi päivitetty 2025-11. Edellinen v2.x-skeema toimitettiin K7/KF1-laiteohjelmistossa 1.9.5. v2.x:ää vastaan kirjoitetut sovellukset toimivat edelleen v3.0:aa vasten, koska lisäämme vain karakteristiikkoja, emme koskaan poista niitä, emmekä koskaan muuta karakteristiikan UUID-tunnusta.

2. Ylätason palvelurakenne

Kynä mainostaa kolmea palvelua ensisijaisten palveluiden listassaan:

Generic Access (0x1800) ja Generic Attribute (0x1801) ovat pakollisia jokaisella BLE-oheislaitteella. Ne tarjoavat laitteen nimen, ulkonäön ja palvelumuutosindikaation. Human Interface Device (0x1812) on HOGP-palvelu, joka välittää OID-painallusraportit. Vendor Service sisältää omisteiset karakteristiikkamme. Battery (0x180F) ja Device Information (0x180A) ovat SIG:n standardoimia palveluita, joita jokainen isäntäalusta odottaa.

Kynä mainostaa koko ensisijaisten palveluiden listan yhdessä AD-paketissa, kun MTU sen sallii. F8:ssa (BLE 5.1, MTU 247) kaikki kuusi mahtuvat mukaan. Vanhemmissa K7/KF1-radioissa (MTU 23) AD-pakettiin mahtuu vain kaksi, ja loput isäntä löytää palveluiden haun kautta.

3. HID-palvelun (0x1812) karakteristiikat

HID-palvelu tarjoaa kuusi karakteristiikkaa:

Yhtä UUID:a 0x2A4D käytetään uudelleen kahdelle raportille, koska HID-palvelu sallii useita Report-ominaisuuksia, jotka tunnistetaan niiden Report Reference -kuvaimen avulla. Q6/Q8-malleissa käytämme kahta Report-ominaisuutta: ensimmäinen on TC-058:ssa kuvattu OID-painallusraportti, ja toinen on audion VU-mittari (isäntäsovellus käyttää sitä pienen VU-ilmaisimen näyttämiseen TTS-toiston aikana).

4. Valmistajakohtaisen palvelun ominaisuudet

Valmistajakohtaisen palvelun UUID on 8E0C0001-7B3C-4F8E-9F4D-2C8B5A1E0001. 128-bittinen UUID luotiin SHA-1-tiivisteellä yhtiömme nimestä ja kiinteästä etuliitteestä. Valmistajakohtaisen palvelun sisällä on viisi ominaisuutta:

Kukin ominaisuus noudattaa SIG-käytäntöä: 128-bittinen UUID, jossa on yhteinen etuliite (8E0C0000-7B3C-4F8E-9F4D-2C8B5A1E0000) ja 16-bittinen ilmentymän tunniste. Ilmentymän tunnisteen 4 viimeistä tavua koodaavat ominaisuuden numeron. Tämä tekee UUID:ista visuaalisesti helposti selattavia BLE-skannaussovelluksessa.

5. Akkupalvelu (0x180F)

Akkupalvelu tarjoaa yhden ominaisuuden:

Kynä mainostaa akun varaustasoa 1 Hz:n taajuudella Q6/Q8-laiteohjelmistolla 3.3.1. ADC-näyte keskiarvoistetaan 4 näytteen yli kohinan poistamiseksi. Yli 5 %:n muutos käynnistää välittömän ilmoituksen; pienemmät erot kootaan 1 Hz:n jaksotettuun ilmoitukseen. Isäntäsovellus voi myös tehdä manuaalisen lukukyselyn.

Huomaa, että akun ominaisuuden arvo on prosentteina, ei millivoltteina, SIG-määrityksen mukaisesti. Millivolttiluennat tarjotaan erillisen valmistajakohtaisen ominaisuuden 8E0C0010-7B3C-4F8E-9F4D-2C8B5A1E0001 kautta suunnitteludiagnostiikkaa varten.

6. Laitetietopalvelu (0x180A)

Laitetietopalvelu tarjoaa:

Mallinumero-ominaisuutta käyttää isäntäsovellus ladataakseen oikean käyttöliittymäteeman. Emme sijoita tähän henkilötietoja (ei MAC-osoitetta järjestelmätunnuksessa; järjestelmätunnus on yrityksen OUI ja perusyksikön satunnainen UUID).

7. Isäntäsovelluksen noudattama etsintämenettely

Hyvin käyttäytyvä isäntäsovellus noudattaa tätä järjestystä:

1. Etsi mainospakettia, jonka palveluiden UUID-luettelossa on 0x1812.
2. Muodosta yhteys 15 ms yhteysvälillä, 0 ms orjan viiveellä ja 4 s valvonta-ajalla.
3. Pyydä MTU-vaihtoa; hyväksy enintään 247.
4. Hae kaikki ensisijaiset palvelut.
5. Hae kullekin palvelulle kaikki ominaisuudet.
6. Lue kullekin ominaisuudelle Characteristic Presentation Format -kuvaaja.
7. Tilaa ilmoitukset arvoille 0x2A4D (OID-painallus) ja 8E0C0005 (telemetria).
8. Lue akun varaustaso (0x2A19) ja laitetiedot.

Huonosti käyttäytyvä sovellus muodostaa yhteyden oletusparametreilla ja yrittää heti kirjoittaa. Näemme tämän 14 %:ssa ensimmäisen osapuolen isäntäsovelluksista. Tuloksena on, että yhteyden vakiintuminen kestää noin 3 s noin 300 ms sijaan. Laadunvarmistuspisteemme palkitsee sovellukset, jotka noudattavat menettelyä.

8. Skeeman laajennuskäytäntö

Laajennamme GATT-skeemaa kolmen säännön mukaisesti:

1. Älä koskaan poista ominaisuutta. Kun UUID on kerran toimitettu tuotantolaiteohjelmistossa, se pysyy skeemassa alustan koko elinkaaren ajan. Vanhat sovellukset jatkavat sen lukemista ja jättävät arvon huomiotta.
2. Älä koskaan muuta UUID:tä. UUID on 128-bittinen tunniste. Sen muuttaminen rikkoo jokaisen sovelluksen, joka on tallentanut sen.
3. Lisää uudet ominaisuudet seuraavaan vapaaseen instanssitunnukseen. Toimittajapalvelulla on 256 instanssitunnusta varattuna (0x0001–0x0100). Kun lisäämme uuden ominaisuuden, valitsemme seuraavan vapaan tunnuksen ja kasvatamme skeeman pikkuversiota.

Skeema v3.0 (nykyinen) käyttää instanssitunnuksia 0x0001–0x0010. Skeema v4.0 (suunniteltu L5-laiteohjelmistoon 4.3.0) käyttää instanssitunnuksia 0x0011–0x0020 uusille luokkahuonetilan telemetriaan liittyville ominaisuuksille.

9. Suorituskyky: etsintäaika

Isäntäsovellus, joka suorittaa kaiken tämän alle sekunnissa, on ”nopea”; 1,5 s on ”normaali”; yli 2 s on ”heikko”. Kaikki 38 sisäistä iOS-/Android-/Windows-viitesovellustamme sijoittuvat alle 1,5 sekuntiin.

10. Mallien välinen skeemaero

Vain mallit L5, T2 ja Y6 sisältävät luokkahuonetilan ominaisuudet, koska näitä malleja myydään koulutuskanavaan. K7/KF1 on yhden käyttäjän kotikäyttöön tarkoitettu kynä, joten luokkahuoneominaisuudet puuttuvat siitä.

11. Laiteohjelmistoversioiden välinen skeemaero

Schema on taaksepäin ja eteenpäin yhteensopiva: Schema 2.0:aa vastaan kirjoitettu sovellus voi muodostaa yhteyden kynään, jossa on Schema 3.1 -laiteohjelmisto, ja lukea kaikki Schema 2.0 -ominaisuudet; uudet ominaisuudet ohitetaan yksinkertaisesti.

12. Brändikohtaisten UUID-tunnusten varaaminen

ODM-asiakas voi pyytää brändikohtaisia ominaisuuksia. Varaamme ne alueelta 0x0100–0x01FF. Asiakas valitsee tältä alueelta 16 instanssitunnusta, ja me rekisteröimme ne GATT-skeeman manifestiin. Manifesto on YAML-tiedosto laiteohjelmistovarastossa; se sisältää luettelon kaikista instanssitunnuksista, ominaisuuden nimen, ominaisuusbitin, koon ja alkuarvon. CI epäonnistuu, jos kaksi asiakasta pyytää samaa instanssitunnusta.

Q6/Q8-laiteohjelmiston 3.3.1 manifestissa on 318 tällä hetkellä varattua brändikohtaista aluetta. Voimme ottaa vastaan 13 lisää ennen kuin 0x0100–0x01FF-alue loppuu ja meidän on laajennettava alueeseen 0x0200.

13. GATT-tietokannan pakkauskikka

GATT-tietokanta voidaan litistää 1,8 KB:n möykyksi ROM-muistiin. Käyttämämme muoto:

[uint16 service_count]
jokaiselle palvelulle:
  [uint16 service_uuid_type] [128-bit UUID]
  [uint16 characteristic_count]
  jokaiselle ominaisuudelle:
    [uint16 char_uuid_type] [128-bit UUID]
    [uint8 properties]
    [uint8 value_size]
    [uint8 descriptor_count]
    jokaiselle deskriptorille:
      [uint16 desc_uuid_type] [128-bit UUID]
      [uint8 payload_size] [payload]

Möykky luodaan laiteohjelmiston rakennusaikana Python-skriptillä, joka lukee YAML-manifestin. Kokonaiskustannus ROM-muistissa on 1 824 tavua Q6/Q8-laiteohjelmistossa 3.3.1. F8 säästää 384 tavua yhdistämällä HID-palvelun 5 ominaisuuteen 6 sijaan (ei Audio VU:ta).

14. Jokaiselle skeemalle ajettava validointipaketti

Skeema, joka ei läpäise jotakin näistä tarkistuksista, hylätään. Vuodesta 2023 lähtien 86 laiteohjelmistojulkaisusta 4 on hylätty tässä portissa.

16. Aiheeseen liittyvää luettavaa

• Lukukynän USB HID ja HID over GATT
• Lukukynän HID-raporttideskriptori ja Usage Page
• Lukukynän Bluetooth-pariliitos SSP Secure Simple Pairing
• Lukukynän GATT-palvelin ja ilmoitusmekanismi
• Lukukynän Bluetooth 5.0 vs 5.2 vs 5.3
• Lukukynän OTA-laiteohjelmistopäivitysmekanismi
• Lukukynän telemetrian näytteenottotaajuus
• Lukukynän kryptografia ja TrustZone