Descriptor: cos'è, Client Characteristic Configuration ed esempi

Cos'è un Descriptor in BLE?

Descriptor è un attributo del protocollo GATT che si collega a una Characteristic e fornisce informazioni aggiuntive sul suo valore o modalità d'uso. Nella terminologia GATT, la caratteristica sono i dati, e il descrittore sono i metadati di quei dati.

Ogni Characteristic può avere zero o più descrittori. I descrittori sono definiti come attributi separati nella tabella GATT e hanno i propri UUID a 16 bit nello spazio Bluetooth SIG. I descrittori non possono esistere indipendentemente — sono sempre legati a una caratteristica specifica.

Secondo la Bluetooth Core Specification 5.4 (2023), i descrittori sono divisi in due categorie: standard (definiti da Bluetooth SIG) e personalizzati (definiti dallo sviluppatore). I descrittori standard hanno UUID nell'intervallo 0x2900–0x2908 e svolgono funzioni strettamente definite. I descrittori personalizzati utilizzano UUID a 128 bit, simili a servizi e caratteristiche personalizzati.

I descrittori sono un meccanismo chiave per configurare il comportamento di una connessione BLE. Senza CCCD (0x2902) è impossibile abbonarsi alle notifiche, senza Presentation Format (0x2904) il Central non saprà come interpretare i byte grezzi della caratteristica.

Client Characteristic Configuration Descriptor (CCCD)

CCCD con UUID 0x2902 è il descrittore più importante e ampiamente utilizzato in BLE. Gestisce l'abbonamento del Central alle notifiche Notify e Indicate della caratteristica. Senza scrivere nel CCCD, la caratteristica non invierà notifiche, anche se ha la proprietà Notify.

CCCD è un valore a 16 bit dove il bit meno significativo (0x0001) abilita Notify e il secondo bit (0x0002) abilita Indicate. Il Central scrive il valore desiderato nel CCCD, abbonandosi così alle notifiche. Se il Central scrive 0x0000 — l'abbonamento viene annullato.

Il meccanismo CCCD funziona così: quando il Central scopre una caratteristica che supporta Notify, trova il suo descrittore CCCD e scrive 0x0001. Dopodiché, ogni volta che il Peripheral aggiorna il valore della caratteristica, viene automaticamente inviato al Central abbonato tramite Handle Value Notification (senza richiesta dal Central).

Secondo la Apple Core Bluetooth Programming Guide, CCCD viene gestito automaticamente dal sistema quando si chiama setNotifyValue per una caratteristica. Lo sviluppatore non deve cercare e scrivere manualmente CCCD — Core Bluetooth lo fa automaticamente all'attivazione delle notifiche.

Abbonamento programmatico alle notifiche

In iOS, l'abbonamento avviene tramite il metodo setNotifyValue sull'oggetto CBPeripheral.

import CoreBluetooth

// Abbonati alle notifiche della caratteristica
peripheral.setNotifyValue(true, for: characteristic)

// Il delegato riceve i valori aggiornati
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // characteristic.value ha nuovi dati
    guard let data = characteristic.value else { return }
}

Su Android, l'abbonamento alle notifiche avviene tramite BluetoothGatt.setCharacteristicNotification. Lo sviluppatore deve anche scrivere manualmente il valore 0x0001 in CCCD.

import android.bluetooth.*;

// Attiva notifiche
bluetoothGatt.setCharacteristicNotification(characteristic, true);

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

Descrittori standard Bluetooth SIG

Bluetooth SIG ha definito 8 descrittori standard per attività comuni di configurazione delle caratteristiche. Ogni descrittore ha un UUID e un formato di valore strettamente definiti.

Characteristic User Description (0x2901) è particolarmente utile per l'interfaccia utente: contiene un nome leggibile della caratteristica che può essere visualizzato nell'interfaccia dell'applicazione. Ad esempio, una caratteristica Battery Level può avere un descrittore User Description con il valore “Livello di carica della batteria”.

Characteristic Presentation Format (0x2904) contiene informazioni su come interpretare il valore della caratteristica: formato (uint8, uint16, float), esponente, unità di misura (tramite UUID dal registro Bluetooth SIG), namespace e descrizione. Ad esempio, la temperatura può essere un int16 con esponente -2 (valore di divisione 0,01°C) e unità di misura “grado Celsius”.

Come usare i Descriptor in iOS e Android

L'accesso ai descrittori differisce su iOS e Android. Core Bluetooth gestisce automaticamente CCCD quando le notifiche sono attivate, mentre Android richiede la scrittura manuale del valore nel descrittore. Esaminiamo entrambi gli approcci.

iOS: Gestione automatica di CCCD

In iOS, lo sviluppatore di solito non interagisce direttamente con i descrittori. Core Bluetooth trova automaticamente CCCD e scrive il valore richiesto quando viene chiamato setNotifyValue. Per leggere i descrittori si usa il metodo discoverDescriptors.

// Scopri descrittori
peripheral.discoverDescriptors(for: characteristic)

// Leggi il valore di 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: Gestione manuale di CCCD

Su Android, lo sviluppatore deve trovare il descrittore CCCD della caratteristica e scrivere il valore per attivare le notifiche. Questo è un passaggio aggiuntivo rispetto a iOS.

// Leggi il valore del descrittore User Description
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

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

Creazione di descrittori personalizzati

I descrittori personalizzati vengono utilizzati quando i descrittori standard Bluetooth SIG non sono sufficienti. Ad esempio, un produttore di sensori medici potrebbe aggiungere un descrittore con informazioni di calibrazione del sensore o un descrittore con un registro errori.

Un descrittore personalizzato viene creato con un UUID a 128 bit, simile a una caratteristica personalizzata. Sul lato Peripheral, lo sviluppatore lo aggiunge alla caratteristica tramite l'API appropriata. Sul lato Central, il descrittore viene scoperto automaticamente quando si chiama discoverDescriptors.

Quando si crea un descrittore personalizzato, seguire queste regole: la lunghezza del valore deve corrispondere al tipo di dati previsto e i diritti di accesso (lettura/scrittura) devono essere specificati esplicitamente. Non utilizzare UUID dell'intervallo dei descrittori standard Bluetooth SIG (0x2900–0x2908) per scopi personalizzati.

Differenza tra Descriptor e Characteristic

Caratteristica e descrittore sono diversi livelli di attributi GATT. Una caratteristica è un punto dati, mentre un descrittore sono i suoi metadati o configurazione. La differenza si manifesta in diversi aspetti: scopo, UUID e regole di accesso.

Una caratteristica ha una dichiarazione obbligatoria che è sempre presente nella tabella GATT. Un descrittore è opzionale — una caratteristica può non avere descrittori. Una caratteristica può essere letta, scritta o inviare notifiche indipendentemente. Un descrittore è sempre legato a una caratteristica e non esiste separatamente.

Secondo la Bluetooth Core Specification 5.4, l'ordine degli attributi nella tabella GATT è il seguente: dichiarazione del servizio, dichiarazione della caratteristica, valore della caratteristica, descrittori della caratteristica (se presenti), poi il servizio successivo. Questo ordine è obbligatorio per il corretto funzionamento dei client GATT.