Descriptor: Was ist das, Client Characteristic Configuration und Beispiele

Was ist ein Descriptor in BLE?

Descriptor ist ein Attribut des GATT-Protokolls, das an eine Characteristic angehängt wird und zusätzliche Informationen über ihren Wert oder ihre Verwendung bereitstellt. In der GATT-Terminologie ist die Charakteristik die Daten, und der Deskriptor sind die Metadaten dieser Daten.

Jede Characteristic kann null oder mehr Deskriptoren haben. Deskriptoren werden als separate Attribute in der GATT-Tabelle definiert und haben ihre eigenen 16-Bit-UUIDs im Bluetooth-SIG-Raum. Deskriptoren können nicht unabhängig existieren — sie sind immer an eine bestimmte Charakteristik gebunden.

Laut der Bluetooth Core Specification 5.4 (2023) werden Deskriptoren in zwei Kategorien unterteilt: Standard (von Bluetooth SIG definiert) und benutzerdefiniert (vom Entwickler definiert). Standarddeskriptoren haben UUIDs im Bereich 0x2900–0x2908 und führen streng definierte Funktionen aus. Benutzerdefinierte Deskriptoren verwenden 128-Bit-UUIDs, ähnlich wie benutzerdefinierte Dienste und Charakteristiken.

Deskriptoren sind ein Schlüsselmechanismus zur Konfiguration des Verhaltens einer BLE-Verbindung. Ohne CCCD (0x2902) ist es unmöglich, Benachrichtigungen zu abonnieren, ohne Presentation Format (0x2904) weiß der Central nicht, wie er die Rohbytes der Charakteristik interpretieren soll.

Client Characteristic Configuration Descriptor (CCCD)

CCCD mit UUID 0x2902 ist der wichtigste und am weitesten verbreitete Deskriptor in BLE. Er verwaltet das Abonnement des Central für Notify und Indicate der Charakteristik. Ohne Schreiben in das CCCD sendet die Charakteristik keine Benachrichtigungen, selbst wenn sie die Notify-Eigenschaft besitzt.

CCCD ist ein 16-Bit-Wert, bei dem das niederwertigste Bit (0x0001) Notify aktiviert und das zweite Bit (0x0002) Indicate aktiviert. Der Central schreibt den gewünschten Wert in das CCCD und abonniert damit Benachrichtigungen. Wenn der Central 0x0000 schreibt — wird das Abonnement gekündigt.

Der CCCD-Mechanismus funktioniert wie folgt: Wenn der Central eine Charakteristik entdeckt, die Notify unterstützt, findet er ihren CCCD-Deskriptor und schreibt 0x0001. Danach wird jedes Mal, wenn das Peripheral den Charakteristikwert aktualisiert, dieser automatisch an den abonnierten Central über Handle Value Notification gesendet (ohne Anfrage vom Central).

Laut dem Apple Core Bluetooth Programming Guide wird CCCD automatisch vom System verwaltet, wenn setNotifyValue für eine Charakteristik aufgerufen wird. Der Entwickler muss CCCD nicht manuell suchen und beschreiben — Core Bluetooth erledigt dies automatisch, wenn Benachrichtigungen aktiviert werden.

Programmatisches Abonnieren von Benachrichtigungen

In iOS erfolgt das Abonnieren über die Methode setNotifyValue auf dem CBPeripheral-Objekt.

import CoreBluetooth

// Charakteristikbenachrichtigungen abonnieren
peripheral.setNotifyValue(true, for: characteristic)

// Delegate empfängt aktualisierte Werte
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // characteristic.value hat neue Daten
    guard let data = characteristic.value else { return }
}

Auf Android erfolgt das Abonnieren von Benachrichtigungen über BluetoothGatt.setCharacteristicNotification. Der Entwickler muss außerdem manuell den Wert 0x0001 in das CCCD schreiben.

import android.bluetooth.*;

// Benachrichtigungen aktivieren
bluetoothGatt.setCharacteristicNotification(characteristic, true);

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

Standard-Bluetooth-SIG-Deskriptoren

Bluetooth SIG hat 8 Standarddeskriptoren für allgemeine Konfigurationsaufgaben von Charakteristiken definiert. Jeder Deskriptor hat eine streng definierte UUID und ein Wertformat.

Characteristic User Description (0x2901) ist besonders nützlich für die Benutzeroberfläche: Sie enthält einen menschenlesbaren Namen der Charakteristik, der in der Anwendungsoberfläche angezeigt werden kann. Beispielsweise kann eine Battery-Level-Charakteristik einen User-Description-Deskriptor mit dem Wert „Akku-Ladezustand“ haben.

Characteristic Presentation Format (0x2904) enthält Informationen zur Interpretation des Charakteristikwerts: Format (uint8, uint16, float), Exponent, Maßeinheit (über UUID aus dem Bluetooth-SIG-Register), Namensraum und Beschreibung. Beispielsweise kann die Temperatur ein int16 mit Exponent -2 (Teilungswert 0,01°C) und der Maßeinheit „Grad Celsius“ sein.

Verwendung von Descriptors in iOS und Android

Der Zugriff auf Deskriptoren unterscheidet sich unter iOS und Android. Core Bluetooth verwaltet CCCD automatisch, wenn Benachrichtigungen aktiviert werden, während Android das manuelle Schreiben des Werts in den Deskriptor erfordert. Betrachten wir beide Ansätze.

iOS: Automatische CCCD-Verwaltung

In iOS interagiert der Entwickler normalerweise nicht direkt mit Deskriptoren. Core Bluetooth findet automatisch CCCD und schreibt den erforderlichen Wert, wenn setNotifyValue aufgerufen wird. Zum Lesen von Deskriptoren wird die Methode discoverDescriptors verwendet.

// Deskriptoren entdecken
peripheral.discoverDescriptors(for: characteristic)

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

Android: Manuelle CCCD-Verwaltung

Auf Android muss der Entwickler den CCCD-Deskriptor der Charakteristik finden und den Wert schreiben, um Benachrichtigungen zu aktivieren. Dies ist ein zusätzlicher Schritt im Vergleich zu iOS.

// User-Description-Deskriptorwert lesen
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

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

Erstellung benutzerdefinierter Deskriptoren

Benutzerdefinierte Deskriptoren werden verwendet, wenn die Standarddeskriptoren von Bluetooth SIG nicht ausreichen. Beispielsweise kann ein Hersteller medizinischer Sensoren einen Deskriptor mit Sensor-Kalibrierungsinformationen oder einen Deskriptor mit einem Fehlerprotokoll hinzufügen.

Ein benutzerdefinierter Deskriptor wird mit einer 128-Bit-UUID erstellt, ähnlich wie eine benutzerdefinierte Charakteristik. Auf der Peripheral-Seite fügt der Entwickler ihn über die entsprechende API zur Charakteristik hinzu. Auf der Central-Seite wird der Deskriptor automatisch erkannt, wenn discoverDescriptors aufgerufen wird.

Beim Erstellen eines benutzerdefinierten Deskriptors beachten Sie folgende Regeln: Die Wertlänge muss dem erwarteten Datentyp entsprechen, und die Zugriffsrechte (Lesen/Schreiben) müssen explizit angegeben werden. Verwenden Sie keine UUIDs aus dem Standarddeskriptorbereich von Bluetooth SIG (0x2900–0x2908) für benutzerdefinierte Zwecke.

Unterschied zwischen Descriptor und Characteristic

Charakteristik und Deskriptor sind verschiedene Ebenen von GATT-Attributen. Eine Charakteristik ist ein Datenpunkt, während ein Deskriptor ihre Metadaten oder Konfiguration ist. Der Unterschied zeigt sich in mehreren Aspekten: Zweck, UUID und Zugriffsregeln.

Eine Charakteristik hat eine obligatorische Deklaration, die immer in der GATT-Tabelle vorhanden ist. Ein Deskriptor ist optional — eine Charakteristik kann keine Deskriptoren haben. Eine Charakteristik kann unabhängig gelesen, geschrieben oder Benachrichtigungen senden. Ein Deskriptor ist immer an eine Charakteristik gebunden und existiert nicht separat.

Laut der Bluetooth Core Specification 5.4 ist die Reihenfolge der Attribute in der GATT-Tabelle wie folgt: Dienstdeklaration, Charakteristikdeklaration, Charakteristikwert, Charakteristikdeskriptoren (falls vorhanden), dann der nächste Dienst. Diese Reihenfolge ist für den korrekten Betrieb von GATT-Clients verbindlich.