Descriptor: mi ez, Client Characteristic Configuration és példák

Mi az a descriptor a BLE-ben?

Descriptor — a GATT protokoll attribútuma, amely a jellemzőhöz csatlakozik és további információkat nyújt annak értékéről vagy használati módjáról. A GATT terminológiájában a jellemző az adat, a descriptor pedig ezen adatok metaadata.

Minden jellemzőnek lehet nulla vagy több deskriptora. A deskriptorok különálló attribútumokként vannak meghatározva a GATT táblában, és saját 16 bites UUID-val rendelkeznek a Bluetooth SIG térben. A deskriptorok nem létezhetnek önállóan — mindig egy adott jellemzőhöz kötődnek.

A Bluetooth Core Specification 5.4 (2023) szerint a deskriptorok két kategóriába sorolhatók: szabványos (Bluetooth SIG által meghatározott) és egyedi (fejlesztő által meghatározott). A szabványos deskriptorok UUID-je a 0x2900–0x2908 tartományba esik, és szigorúan meghatározott funkciókat látnak el. Az egyedi deskriptorok 128 bites UUID-t használnak, hasonlóan az egyedi szolgáltatásokhoz és jellemzőkhöz.

A deskriptorok kulcsfontosságú mechanizmust jelentenek a BLE kapcsolat viselkedésének konfigurálásához. CCCD (0x2902) nélkül nem lehet feliratkozni az értesítésekre, Presentation Format (0x2904) nélkül a Central nem tudja, hogyan kell értelmezni a jellemző nyers bájtjait.

Client Characteristic Configuration Descriptor (CCCD)

CCCD 0x2902 UUID-val a legfontosabb és legszélesebb körben használt descriptor a BLE-ben. Kezeli a Central feliratkozását a jellemző értesítéseire (Notify) és megerősített értesítéseire (Indicate). CCCD-be írás nélkül a jellemző nem küld értesítéseket, még akkor sem, ha rendelkezik Notify tulajdonsággal.

CCCD egy 16 bites érték, amelyben a legkisebb bit (0x0001) a Notify-ot, a második bit (0x0002) pedig az Indicate-ot kapcsolja be. A Central a kívánt értéket írja a CCCD-be, ezzel feliratkozik az értesítésekre. Ha a Central 0x0000-t ír — a feliratkozás törlődik.

A CCCD működési mechanizmusa a következő: amikor a Central észlel egy Notify támogatással rendelkező jellemzőt, megkeresi annak CCCD deskriptorát és 0x0001-et ír. Ezután, minden alkalommal, amikor a Peripheral frissíti a jellemző értékét, az automatikusan elküldésre kerül a feliratkozott Central-nak Handle Value Notification útján (a Central kérése nélkül).

Az Apple Core Bluetooth Programming Guide szerint a CCCD automatikusan kezelődik a rendszer által a setNotifyValue jellemzőre történő meghívásakor. A fejlesztőnek nem kell kézzel keresnie és írnia a CCCD-t — a Core Bluetooth ezt automatikusan elvégzi az értesítések aktiválásakor.

Programozott feliratkozás értesítésekre

iOS-ben a feliratkozás a setNotifyValue metódussal történik a CBPeripheral objektumon.

import CoreBluetooth

// Feliratkozás a jellemző értesítéseire
peripheral.setNotifyValue(true, for: characteristic)

// A delegate megkapja a frissített értékeket
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // A characteristic.value új adatokkal rendelkezik
    guard let data = characteristic.value else { return }
}

Android-on az értesítésekre való feliratkozás a BluetoothGatt.setCharacteristicNotification segítségével történik. A fejlesztőnek kézzel kell írnia a 0x0001 értéket a CCCD-be.

import android.bluetooth.*;

// Értesítések bekapcsolása
bluetoothGatt.setCharacteristicNotification(characteristic, true);

// 0x0001 írása a CCCD-be
BluetoothGattDescriptor descriptor = characteristic
    .getDescriptor(
        UUID.fromString("00002902-0000-1000-8000-00805F9B34FB")
    );
descriptor.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE);
bluetoothGatt.writeDescriptor(descriptor);

Bluetooth SIG szabványos deskriptorok

Bluetooth SIG 8 szabványos deskriptort határozott meg a jellemzők konfigurálásának általános feladataihoz. Minden deskriptornak szigorúan meghatározott UUID-je és értékformátuma van.

Characteristic User Description (0x2901) különösen hasznos a UI számára: tartalmazza a jellemző ember által olvasható nevét, amely megjeleníthető az alkalmazás felületén. Például a Battery Level jellemző rendelkezhet egy User Description deskriptorral, amelynek értéke „Akkumulátor töltési szintje”.

Characteristic Presentation Format (0x2904) információkat tartalmaz arról, hogyan kell értelmezni a jellemző értékét: formátum (uint8, uint16, float), kitevő, mértékegység (UUID-n keresztül a Bluetooth SIG nyilvántartásból), névtér és leírás. Például a hőmérséklet lehet int16 -2 kitevővel (osztási érték 0.01°C) és „Celsius-fok” mértékegységgel.

Hogyan használjuk a deskriptort iOS-ben és Android-ban

Hozzáférés a deskriptorokhoz eltér iOS és Android között. A Core Bluetooth automatikusan kezeli a CCCD-t az értesítések bekapcsolásakor, míg Android kézi értékírást igényel a deskriptorba. Vizsgáljuk meg mindkét megközelítést.

iOS: CCCD automatikus kezelése

iOS-ben a fejlesztő általában nem lép közvetlenül kapcsolatba a deskriptorokkal. A Core Bluetooth automatikusan megtalálja a CCCD-t és beírja a szükséges értéket a setNotifyValue meghívásakor. A deskriptorok olvasásához a discoverDescriptors metódust használjuk.

// Deskriptorok felfedezése
peripheral.discoverDescriptors(for: characteristic)

// User Description érték olvasása
func peripheral(
    _ peripheral: CBPeripheral,
    didDiscoverDescriptorsFor characteristic: CBCharacteristic,
    error: Error?
) {
    for descriptor in characteristic.descriptors ?? [] {
        if descriptor.uuid == CBUUID("2901") {
            peripheral.readValue(for: descriptor)
        }
    }
}

Android: CCCD kézi kezelése

Android-on a fejlesztőnek magának kell megtalálnia a jellemző CCCD deskriptorát és értéket kell írnia az értesítések bekapcsolásához. Ez egy további lépés az iOS-hez képest.

// A User Description deskriptor értékének olvasása
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

if (userDesc != null) {
    bluetoothGatt.readDescriptor(userDesc);
}

Egyedi deskriptorok létrehozása

Egyedi deskriptorokat akkor használunk, ha a Bluetooth SIG szabványos deskriptorai nem elegendőek. Például egy orvosi érzékelő gyártója hozzáadhat egy deskriptort az érzékelő kalibrációjának információival vagy egy deskriptort hibanaplóval.

Az egyedi deskriptor 128 bites UUID-val jön létre, mint az egyedi jellemző. A Peripheral oldalán a fejlesztő a megfelelő API-n keresztül adja hozzá a jellemzőhöz. A Central oldalán a deskriptor automatikusan észlelésre kerül a discoverDescriptors meghívásakor.

Az egyedi deskriptor létrehozásakor kövesse a szabályokat: az érték hosszának meg kell felelnie a várt adattípusnak, a hozzáférési jogokat (read/write) kifejezetten meg kell adni. Ne használjon UUID-t a Bluetooth SIG szabványos deskriptorainak tartományából (0x2900–0x2908) egyedi célokra.

Különbség a descriptor és a jellemző között

Jellemző és descriptor — a GATT attribútumok különböző szintjei. A jellemző egy adatpont, a descriptor pedig annak metaadata vagy konfigurációja. A különbség több szempontból is megnyilvánul: cél, UUID és hozzáférési szabályok.

A jellemző rendelkezik egy kötelező deklarációval (declaration), amely mindig megtalálható a GATT táblában. A descriptor opcionális — a jellemzőnek nem feltétlenül kell deskriptorokkal rendelkeznie. A jellemző függetlenül olvasható, írható vagy küldhet értesítéseket. A descriptor mindig a jellemzőhöz kötődik és nem létezik külön.

A Bluetooth Core Specification 5.4 szerint a GATT táblában az attribútumok sorrendje a következő: szolgáltatás deklarációja, jellemző deklarációja, jellemző értéke, jellemző deskriptorai (ha vannak), majd a következő szolgáltatás. Ez a sorrend kötelező a GATT kliensek helyes működéséhez.