Descriptor : qu'est-ce que c'est, Client Characteristic Configuration et exemples

Qu'est-ce qu'un Descriptor en BLE ?

Descriptor est un attribut du protocole GATT qui se rattache à une Characteristic et fournit des informations supplémentaires sur sa valeur ou son mode d'utilisation. Dans la terminologie GATT, la caractéristique est la donnée, et le descripteur est la métadonnée de cette donnée.

Chaque Characteristic peut avoir zéro ou plusieurs descripteurs. Les descripteurs sont définis comme des attributs séparés dans la table GATT et ont leurs propres UUID 16 bits dans l'espace Bluetooth SIG. Les descripteurs ne peuvent pas exister indépendamment — ils sont toujours liés à une caractéristique spécifique.

Selon la Bluetooth Core Specification 5.4 (2023), les descripteurs sont divisés en deux catégories : standard (définis par Bluetooth SIG) et personnalisés (définis par le développeur). Les descripteurs standard ont des UUID dans la plage 0x2900–0x2908 et exécutent des fonctions strictement définies. Les descripteurs personnalisés utilisent des UUID 128 bits, similaires aux services et caractéristiques personnalisés.

Les descripteurs sont un mécanisme clé pour configurer le comportement d'une connexion BLE. Sans CCCD (0x2902), il est impossible de s'abonner aux notifications ; sans Presentation Format (0x2904), le Central ne saura pas comment interpréter les octets bruts de la caractéristique.

Client Characteristic Configuration Descriptor (CCCD)

CCCD avec l'UUID 0x2902 est le descripteur le plus important et le plus utilisé en BLE. Il gère l'abonnement du Central aux notifications Notify et Indicate de la caractéristique. Sans écriture dans le CCCD, la caractéristique n'enverra pas de notifications, même si elle possède la propriété Notify.

CCCD est une valeur 16 bits où le bit de poids faible (0x0001) active Notify, et le second bit (0x0002) active Indicate. Le Central écrit la valeur souhaitée dans le CCCD, s'abonnant ainsi aux notifications. Si le Central écrit 0x0000 — l'abonnement est annulé.

Le mécanisme du CCCD fonctionne ainsi : lorsque le Central découvre une caractéristique prenant en charge Notify, il trouve son descripteur CCCD et écrit 0x0001. Ensuite, chaque fois que le Peripheral met à jour la valeur de la caractéristique, elle est automatiquement envoyée au Central abonné via Handle Value Notification (sans demande du Central).

Selon le Apple Core Bluetooth Programming Guide, le CCCD est géré automatiquement par le système lors de l'appel à setNotifyValue pour une caractéristique. Le développeur n'a pas besoin de chercher et d'écrire manuellement le CCCD — Core Bluetooth le fait automatiquement lors de l'activation des notifications.

Abonnement programmatique aux notifications

Sous iOS, l'abonnement se fait via la méthode setNotifyValue sur l'objet CBPeripheral.

import CoreBluetooth

// S'abonner aux notifications de la caractéristique
peripheral.setNotifyValue(true, for: characteristic)

// Le délégué reçoit les valeurs mises à jour
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // characteristic.value contient de nouvelles données
    guard let data = characteristic.value else { return }
}

Sous Android, l'abonnement aux notifications se fait via BluetoothGatt.setCharacteristicNotification. Le développeur doit également écrire manuellement la valeur 0x0001 dans le CCCD.

import android.bluetooth.*;

// Activer les notifications
bluetoothGatt.setCharacteristicNotification(characteristic, true);

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

Descripteurs standard Bluetooth SIG

Bluetooth SIG a défini 8 descripteurs standard pour les tâches courantes de configuration des caractéristiques. Chaque descripteur a un UUID et un format de valeur strictement définis.

Characteristic User Description (0x2901) est particulièrement utile pour l'interface utilisateur : il contient un nom lisible de la caractéristique qui peut être affiché dans l'interface de l'application. Par exemple, une caractéristique Battery Level peut avoir un descripteur User Description avec la valeur « Niveau de charge de la batterie ».

Characteristic Presentation Format (0x2904) contient des informations sur la façon d'interpréter la valeur de la caractéristique : format (uint8, uint16, float), exposant, unité de mesure (via UUID du registre Bluetooth SIG), espace de noms et description. Par exemple, la température peut être un int16 avec exposant -2 (valeur de division 0,01 °C) et l'unité de mesure « degré Celsius ».

Utiliser les Descriptors sous iOS et Android

L'accès aux descripteurs diffère sous iOS et Android. Core Bluetooth gère automatiquement le CCCD lorsque les notifications sont activées, tandis qu'Android nécessite une écriture manuelle de la valeur dans le descripteur. Examinons les deux approches.

iOS : Gestion automatique du CCCD

Sous iOS, le développeur n'interagit généralement pas directement avec les descripteurs. Core Bluetooth trouve automatiquement le CCCD et écrit la valeur requise lors de l'appel à setNotifyValue. Pour lire les descripteurs, on utilise la méthode discoverDescriptors.

// Découvrir les descripteurs
peripheral.discoverDescriptors(for: characteristic)

// Lire la valeur de 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 : Gestion manuelle du CCCD

Sous Android, le développeur doit trouver le descripteur CCCD de la caractéristique et écrire la valeur pour activer les notifications. Il s'agit d'une étape supplémentaire par rapport à iOS.

// Lire la valeur du descripteur User Description
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

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

Création de descripteurs personnalisés

Les descripteurs personnalisés sont utilisés lorsque les descripteurs standard Bluetooth SIG ne suffisent pas. Par exemple, un fabricant de capteurs médicaux peut ajouter un descripteur avec des informations d'étalonnage du capteur ou un descripteur avec un journal d'erreurs.

Un descripteur personnalisé est créé avec un UUID 128 bits, comme une caractéristique personnalisée. Côté Peripheral, le développeur l'ajoute à la caractéristique via l'API appropriée. Côté Central, le descripteur est découvert automatiquement lors de l'appel à discoverDescriptors.

Lors de la création d'un descripteur personnalisé, suivez ces règles : la longueur de la valeur doit correspondre au type de données attendu, et les droits d'accès (lecture/écriture) doivent être explicitement spécifiés. N'utilisez pas d'UUID de la plage des descripteurs standard Bluetooth SIG (0x2900–0x2908) à des fins personnalisées.

Différence entre Descriptor et Characteristic

Caractéristique et descripteur sont des niveaux différents d'attributs GATT. Une caractéristique est un point de données, tandis qu'un descripteur est ses métadonnées ou sa configuration. La différence se manifeste à plusieurs égards : l'objectif, l'UUID et les règles d'accès.

Une caractéristique a une déclaration obligatoire qui est toujours présente dans la table GATT. Un descripteur est facultatif — une caractéristique peut n'avoir aucun descripteur. Une caractéristique peut être lue, écrite ou envoyer des notifications indépendamment. Un descripteur est toujours lié à une caractéristique et n'existe pas séparément.

Selon la Bluetooth Core Specification 5.4, l'ordre des attributs dans la table GATT est le suivant : déclaration de service, déclaration de caractéristique, valeur de caractéristique, descripteurs de caractéristique (le cas échéant), puis le service suivant. Cet ordre est obligatoire pour le bon fonctionnement des clients GATT.