Descriptor: wat het is, Client Characteristic Configuration en voorbeelden

Wat is een descriptor in BLE?

Descriptor — is een attribuut van het GATT-protocol dat wordt gekoppeld aan een karakteristiek en aanvullende informatie geeft over de waarde of het gebruik ervan. In GATT-terminologie is de karakteristiek de gegevens en de descriptor is de metadata van die gegevens.

Elke karakteristiek kan nul of meer descriptors hebben. Descriptors worden gedefinieerd als afzonderlijke attributen in de GATT-tabel en hebben hun eigen 16-bits UUID in de Bluetooth SIG-ruimte. Descriptors kunnen niet zelfstandig bestaan — ze zijn altijd gekoppeld aan een specifieke karakteristiek.

Volgens Bluetooth Core Specification 5.4 (2023) worden descriptors onderverdeeld in twee categorieën: standaard (gedefinieerd door Bluetooth SIG) en aangepast (gedefinieerd door de ontwikkelaar). Standaard descriptors hebben UUID in het bereik 0x2900–0x2908 en vervullen strikt gedefinieerde functies. Aangepaste descriptors gebruiken 128-bits UUID, net als aangepaste services en karakteristieken.

Descriptors zijn het belangrijkste mechanisme voor gedragsconfiguratie van de BLE-verbinding. Zonder CCCD (0x2902) kunt u zich niet abonneren op meldingen, zonder Presentation Format (0x2904) weet Central niet hoe het de ruwe bytes van de karakteristiek moet interpreteren.

Client Characteristic Configuration Descriptor (CCCD)

CCCD met UUID 0x2902 is de belangrijkste en meest gebruikte descriptor in BLE. Het beheert het abonnement van Central op meldingen (Notify) en bevestigde meldingen (Indicate) van de karakteristiek. Zonder schrijven naar CCCD zal de karakteristiek geen meldingen verzenden, zelfs niet als deze de eigenschap Notify heeft.

CCCD is een 16-bits waarde waarin de minst significante bit (0x0001) Notify inschakelt en de tweede bit (0x0002) Indicate inschakelt. Central schrijft de gewenste waarde naar CCCD en abonneert zich zo op meldingen. Als Central 0x0000 schrijft — wordt het abonnement geannuleerd.

Het werkingsmechanisme van CCCD is als volgt: wanneer Central een karakteristiek met Notify-ondersteuning detecteert, vindt het de CCCD-descriptor en schrijft 0x0001. Daarna, elke keer dat Peripheral de waarde van de karakteristiek bijwerkt, wordt deze automatisch naar de geabonneerde Central gestuurd via Handle Value Notification (zonder verzoek van Central).

Volgens Apple Core Bluetooth Programming Guide wordt CCCD automatisch beheerd door het systeem bij aanroep van setNotifyValue voor de karakteristiek. De ontwikkelaar hoeft CCCD niet handmatig te zoeken en te schrijven — Core Bluetooth doet dit automatisch bij activering van meldingen.

Programmatisch abonneren op meldingen

In iOS gebeurt abonneren via de methode setNotifyValue op het CBPeripheral-object.

import CoreBluetooth

// Abonneer op karakteristiekmeldingen
peripheral.setNotifyValue(true, for: characteristic)

// Delegate ontvangt bijgewerkte waarden
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // characteristic.value heeft nieuwe gegevens
    guard let data = characteristic.value else { return }
}

Op Android gebeurt abonneren op meldingen via BluetoothGatt.setCharacteristicNotification. De ontwikkelaar moet ook handmatig de waarde 0x0001 naar CCCD schrijven.

import android.bluetooth.*;

// Meldingen inschakelen
bluetoothGatt.setCharacteristicNotification(characteristic, true);

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

Standaard Bluetooth SIG descriptors

Bluetooth SIG heeft 8 standaard descriptors gedefinieerd voor veelvoorkomende configuratietaken van karakteristieken. Elke descriptor heeft een strikt gedefinieerde UUID en waardeformaat.

Characteristic User Description (0x2901) is vooral nuttig voor de UI: het bevat een voor mensen leesbare naam van de karakteristiek die in de applicatie-interface kan worden weergegeven. Bijvoorbeeld, de karakteristiek Battery Level kan een User Description-descriptor hebben met de waarde „Batterijniveau”.

Characteristic Presentation Format (0x2904) bevat informatie over hoe de waarde van de karakteristiek te interpreteren: formaat (uint8, uint16, float), exponent, meeteenheid (via UUID uit het Bluetooth SIG-register), naamruimte en beschrijving. Bijvoorbeeld, temperatuur kan int16 zijn met exponent -2 (deelwaarde 0.01°C) en meeteenheid „graden Celsius”.

Descriptor gebruiken in iOS en Android

Toegang tot descriptors verschilt tussen iOS en Android. Core Bluetooth beheert CCCD automatisch bij het inschakelen van meldingen, terwijl Android handmatig schrijven van de waarde naar de descriptor vereist. Laten we beide benaderingen bekijken.

iOS: automatisch beheer van CCCD

In iOS heeft de ontwikkelaar meestal geen directe interactie met descriptors. Core Bluetooth vindt automatisch CCCD en schrijft de benodigde waarde bij aanroep van setNotifyValue. Voor het lezen van descriptors wordt de methode discoverDescriptors gebruikt.

// Ontdek descriptors
peripheral.discoverDescriptors(for: characteristic)

// Lees User Description-waarde
func peripheral(
    _ peripheral: CBPeripheral,
    didDiscoverDescriptorsFor characteristic: CBCharacteristic,
    error: Error?
) {
    for descriptor in characteristic.descriptors ?? [] {
        if descriptor.uuid == CBUUID("2901") {
            peripheral.readValue(for: descriptor)
        }
    }
}

Android: handmatig beheer van CCCD

Op Android moet de ontwikkelaar zelf de CCCD-descriptor van de karakteristiek vinden en de waarde schrijven om meldingen in te schakelen. Dit is een extra stap vergeleken met iOS.

// Lees de waarde van de User Description-descriptor
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

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

Aangepaste descriptors maken

Aangepaste descriptors worden gebruikt wanneer de standaard Bluetooth SIG descriptors niet voldoende zijn. Bijvoorbeeld, een fabrikant van medische sensoren kan een descriptor toevoegen met informatie over de kalibratie van de sensor of een descriptor met een foutenlogboek.

Een aangepaste descriptor wordt gemaakt met een 128-bits UUID, net als een aangepaste karakteristiek. Aan de Peripheral-kant voegt de ontwikkelaar deze toe aan de karakteristiek via de juiste API. Aan de Central-kant wordt de descriptor automatisch gedetecteerd bij aanroep van discoverDescriptors.

Houd bij het maken van een aangepaste descriptor de regels aan: de lengte van de waarde moet overeenkomen met het verwachte gegevenstype, toegangsrechten (read/write) moeten expliciet worden vermeld. Gebruik geen UUIDs uit het bereik van standaard Bluetooth SIG descriptors (0x2900–0x2908) voor aangepaste doeleinden.

Verschil tussen descriptor en karakteristiek

Karakteristiek en descriptor — dit zijn verschillende niveaus van GATT-attributen. De karakteristiek is een gegevenspunt, de descriptor is de metadata of configuratie ervan. Het verschil komt tot uiting in verschillende aspecten: doel, UUID en toegangsregels.

De karakteristiek heeft een verplichte declaratie (declaration) die altijd in de GATT-tabel staat. De descriptor is optioneel — de karakteristiek kan geen descriptors hebben. De karakteristiek kan onafhankelijk worden gelezen, geschreven of meldingen verzenden. De descriptor is altijd gekoppeld aan de karakteristiek en bestaat niet apart.

Volgens Bluetooth Core Specification 5.4 is de volgorde van attributen in de GATT-tabel als volgt: servicedeclaratie, karakteristiekdeclaratie, waarde van de karakteristiek, descriptors van de karakteristiek (indien aanwezig), dan de volgende service. Deze volgorde is verplicht voor de correcte werking van GATT-cliënten.