Deskriptor: co to je, Client Characteristic Configuration a příklady

Co je deskriptor v BLE?

Deskriptor — je atribut protokolu GATT, který se připojuje k charakteristice a poskytuje další informace o její hodnotě nebo způsobu použití. V terminologii GATT je charakteristika data a deskriptor jsou metadata těchto dat.

Každá charakteristika může mít nula nebo více deskriptorů. Deskriptory jsou definovány jako samostatné atributy v tabulce GATT a mají vlastní 16bitové UUID v prostoru Bluetooth SIG. Deskriptory nemohou existovat samostatně — jsou vždy vázány na konkrétní charakteristiku.

Podle Bluetooth Core Specification 5.4 (2023) se deskriptory dělí do dvou kategorií: standardní (definované Bluetooth SIG) a vlastní (definované vývojářem). Standardní deskriptory mají UUID v rozsahu 0x2900–0x2908 a plní přesně definované funkce. Vlastní deskriptory používají 128bitová UUID, podobně jako vlastní služby a charakteristiky.

Deskriptory jsou klíčovým mechanismem pro konfiguraci chování spojení BLE. Bez CCCD (0x2902) se nelze přihlásit k odběru oznámení, bez Presentation Format (0x2904) Central nebude vědět, jak interpretovat surové bajty charakteristiky.

Client Characteristic Configuration Descriptor (CCCD)

CCCD s UUID 0x2902 je nejdůležitější a nejpoužívanější deskriptor v BLE. Řídí odběr Centralu k oznámením (Notify) a potvrzeným oznámením (Indicate) z charakteristiky. Bez zápisu do CCCD nebude charakteristika odesílat oznámení, ani když má vlastnost Notify.

CCCD je 16bitová hodnota, ve které nejnižší bit (0x0001) zapíná Notify a druhý bit (0x0002) zapíná Indicate. Central zapisuje požadovanou hodnotu do CCCD, čímž se přihlašuje k odběru oznámení. Pokud Central zapíše 0x0000 — odběr se ruší.

Mechanismus fungování CCCD je následující: když Central objeví charakteristiku s podporou Notify, najde její CCCD deskriptor a zapíše 0x0001. Poté, pokaždé když Peripheral aktualizuje hodnotu charakteristiky, je automaticky odeslána přihlášenému Centralu prostřednictvím Handle Value Notification (bez požadavku od Centralu).

Podle Apple Core Bluetooth Programming Guide je CCCD automaticky spravován systémem při volání setNotifyValue pro charakteristiku. Vývojář nemusí ručně hledat a zapisovat CCCD — Core Bluetooth to dělá automaticky při aktivaci oznámení.

Programové přihlášení k odběru oznámení

V iOS se přihlášení prováDí pomocí metody setNotifyValue na objektu CBPeripheral.

import CoreBluetooth

// Přihlásit se k oznámením charakteristiky
peripheral.setNotifyValue(true, for: characteristic)

// Delegate obdrží aktualizované hodnoty
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // characteristic.value má nová data
    guard let data = characteristic.value else { return }
}

Na Androidu se přihlášení k odběru oznámení prováDí pomocí BluetoothGatt.setCharacteristicNotification. Vývojář také musí ručně zapsat hodnotu 0x0001 do CCCD.

import android.bluetooth.*;

// Povolit oznámení
bluetoothGatt.setCharacteristicNotification(characteristic, true);

// Zapsat 0x0001 do CCCD
BluetoothGattDescriptor descriptor = characteristic
    .getDescriptor(
        UUID.fromString("00002902-0000-1000-8000-00805F9B34FB")
    );
descriptor.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE);
bluetoothGatt.writeDescriptor(descriptor);

Standardní deskriptory Bluetooth SIG

Bluetooth SIG definoval 8 standardních deskriptorů pro běžné úkoly konfigurace charakteristik. Každý deskriptor má přesně definované UUID a formát hodnoty.

Characteristic User Description (0x2901) je zvláště užitečný pro UI: obsahuje lidsky čitelné jméno charakteristiky, které lze zobrazit v rozhraní aplikace. Například charakteristika Battery Level může mít deskriptor User Description s hodnotou „Úroveň nabití baterie“.

Characteristic Presentation Format (0x2904) obsahuje informace o tom, jak interpretovat hodnotu charakteristiky: formát (uint8, uint16, float), exponent, jednotku měření (prostřednictvím UUID z registru Bluetooth SIG), jmenný prostor a popis. Například teplota může být int16 s exponentem -2 (hodnota dělení 0.01°C) a jednotkou měření „stupně Celsia“.

Jak použít deskriptor v iOS a Androidu

Přístup k deskriptorům se liší na iOS a Androidu. Core Bluetooth automaticky spravuje CCCD při zapnutí oznámení, zatímco Android vyžaduje ruční zápis hodnoty do deskriptoru. Podívejme se na oba přístupy.

iOS: automatická správa CCCD

V iOS vývojář obvykle nepřichází do přímého kontaktu s deskriptory. Core Bluetooth automaticky najde CCCD a zapíše potřebnou hodnotu při volání setNotifyValue. Pro čtení deskriptorů se používá metoda discoverDescriptors.

// Objevit deskriptory
peripheral.discoverDescriptors(for: characteristic)

// Přečíst hodnotu User Description
func peripheral(
    _ peripheral: CBPeripheral,
    didDiscoverDescriptorsFor characteristic: CBCharacteristic,
    error: Error?
) {
    for descriptor in characteristic.descriptors ?? [] {
        if descriptor.uuid == CBUUID("2901") {
            peripheral.readValue(for: descriptor)
        }
    }
}

Android: ruční správa CCCD

Na Androidu musí vývojář sám najít CCCD deskriptor charakteristiky a zapsat hodnotu pro zapnutí oznámení. To je další krok ve srovnání s iOS.

// Přečíst hodnotu deskriptoru User Description
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

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

Vytváření vlastních deskriptorů

Vlastní deskriptory se používají, když standardní deskriptory Bluetooth SIG nestačí. Například výrobce lékařského senzoru může přidat deskriptor s informacemi o kalibraci senzoru nebo deskriptor s protokolem chyb.

Vlastní deskriptor se vytváří s 128bitovým UUID, stejně jako vlastní charakteristika. Na straně Peripheral jej vývojář přidá k charakteristice prostřednictvím příslušného API. Na straně Central je deskriptor automaticky objeven při volání discoverDescriptors.

Při vytváření vlastního deskriptoru dodržujte pravidla: délka hodnoty musí odpovídat očekávanému typu dat, přístupová práva (read/write) musí být výslovně uvedena. Nepoužívejte UUID z rozsahu standardních deskriptorů Bluetooth SIG (0x2900–0x2908) pro vlastní účely.

Rozdíl mezi deskriptorem a charakteristikou

Charakteristika a deskriptor — to jsou různé úRovně atributů GATT. Charakteristika je datový bod a deskriptor jsou její metadata nebo konfigurace. Rozdíl se projevuje v několika aspektech: účelu, UUID a přístupových právech.

Charakteristika má povinné prohlášení (declaration), které je vždy v tabulce GATT. Deskriptor je volitelný — charakteristika nemusí mít deskriptory. Charakteristika může být čtena, zapisována nebo odesílat oznámení nezávisle. Deskriptor je vždy vázán na charakteristiku a neexistuje samostatně.

Podle Bluetooth Core Specification 5.4 je v tabulce GATT pořadí atributů následující: prohlášení služby, prohlášení charakteristiky, hodnota charakteristiky, deskriptory charakteristiky (pokud existují), poté další služba. Toto pořadí je povinné pro správnou funkci klientů GATT.