Descriptor: o que é, Client Characteristic Configuration e exemplos

O que é um Descriptor em BLE?

Descriptor é um atributo do protocolo GATT que se anexa a uma Characteristic e fornece informações adicionais sobre seu valor ou modo de uso. Na terminologia GATT, a característica são os dados, e o descritor são os metadados desses dados.

Cada Characteristic pode ter zero ou mais descritores. Os descritores são definidos como atributos separados na tabela GATT e têm seus próprios UUIDs de 16 bits no espaço Bluetooth SIG. Os descritores não podem existir independentemente — estão sempre vinculados a uma característica específica.

De acordo com a Bluetooth Core Specification 5.4 (2023), os descritores são divididos em duas categorias: padrão (definidos pela Bluetooth SIG) e personalizados (definidos pelo desenvolvedor). Os descritores padrão têm UUIDs no intervalo 0x2900–0x2908 e executam funções estritamente definidas. Os descritores personalizados usam UUIDs de 128 bits, semelhantes a serviços e características personalizados.

Os descritores são um mecanismo chave para configurar o comportamento de uma conexão BLE. Sem CCCD (0x2902) é impossível assinar notificações, sem Presentation Format (0x2904) o Central não saberá como interpretar os bytes brutos da característica.

Client Characteristic Configuration Descriptor (CCCD)

CCCD com UUID 0x2902 é o descritor mais importante e amplamente utilizado em BLE. Ele gerencia a assinatura do Central em Notify e Indicate da característica. Sem escrever no CCCD, a característica não enviará notificações, mesmo que tenha a propriedade Notify.

CCCD é um valor de 16 bits onde o bit menos significativo (0x0001) habilita Notify, e o segundo bit (0x0002) habilita Indicate. O Central escreve o valor desejado no CCCD, inscrevendo-se assim nas notificações. Se o Central escrever 0x0000 — a assinatura é cancelada.

O mecanismo CCCD funciona assim: quando o Central descobre uma característica que suporta Notify, ele encontra seu descritor CCCD e escreve 0x0001. Depois disso, sempre que o Peripheral atualiza o valor da característica, ele é enviado automaticamente ao Central inscrito via Handle Value Notification (sem solicitação do Central).

De acordo com o Apple Core Bluetooth Programming Guide, o CCCD é gerenciado automaticamente pelo sistema quando setNotifyValue é chamado para uma característica. O desenvolvedor não precisa localizar e escrever manualmente o CCCD — o Core Bluetooth faz isso automaticamente ao ativar as notificações.

Assinatura programática de notificações

Em iOS, a assinatura é feita através do método setNotifyValue no objeto CBPeripheral.

import CoreBluetooth

// Assinar notificações da característica
peripheral.setNotifyValue(true, for: characteristic)

// O delegado recebe valores atualizados
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // characteristic.value tem novos dados
    guard let data = characteristic.value else { return }
}

No Android, a assinatura de notificações é feita através de BluetoothGatt.setCharacteristicNotification. O desenvolvedor também deve escrever manualmente o valor 0x0001 no CCCD.

import android.bluetooth.*;

// Ativar notificações
bluetoothGatt.setCharacteristicNotification(characteristic, true);

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

Descritores padrão Bluetooth SIG

Bluetooth SIG definiu 8 descritores padrão para tarefas comuns de configuração de características. Cada descritor tem um UUID estritamente definido e formato de valor.

Characteristic User Description (0x2901) é especialmente útil para IU: contém um nome legível da característica que pode ser exibido na interface do aplicativo. Por exemplo, uma característica Battery Level pode ter um descritor User Description com o valor “Nível de carga da bateria”.

Characteristic Presentation Format (0x2904) contém informações sobre como interpretar o valor da característica: formato (uint8, uint16, float), expoente, unidade de medida (via UUID do registro Bluetooth SIG), namespace e descrição. Por exemplo, a temperatura pode ser int16 com expoente -2 (valor de divisão 0,01°C) e unidade de medida “grau Celsius”.

Como usar Descriptors em iOS e Android

O acesso aos descritores difere no iOS e Android. O Core Bluetooth gerencia automaticamente o CCCD quando as notificações são ativadas, enquanto o Android requer escrita manual do valor no descritor. Vamos analisar ambas as abordagens.

iOS: Gerenciamento automático de CCCD

Em iOS, o desenvolvedor normalmente não interage diretamente com os descritores. O Core Bluetooth encontra automaticamente o CCCD e escreve o valor necessário quando setNotifyValue é chamado. Para ler descritores, usa-se o método discoverDescriptors.

// Descobrir descritores
peripheral.discoverDescriptors(for: characteristic)

// Ler o valor 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: Gerenciamento manual de CCCD

No Android, o desenvolvedor deve encontrar o descritor CCCD da característica e escrever o valor para ativar as notificações. Esta é uma etapa adicional em comparação ao iOS.

// Ler o valor do descritor User Description
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

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

Criação de descritores personalizados

Descritores personalizados são usados quando os descritores padrão Bluetooth SIG não são suficientes. Por exemplo, um fabricante de sensores médicos pode adicionar um descritor com informações de calibração do sensor ou um descritor com log de erros.

Um descritor personalizado é criado com um UUID de 128 bits, semelhante a uma característica personalizada. No lado do Peripheral, o desenvolvedor o adiciona à característica através da API apropriada. No lado do Central, o descritor é descoberto automaticamente ao chamar discoverDescriptors.

Ao criar um descritor personalizado, siga estas regras: o comprimento do valor deve corresponder ao tipo de dado esperado, e os direitos de acesso (leitura/escrita) devem ser explicitamente especificados. Não use UUIDs do intervalo de descritores padrão Bluetooth SIG (0x2900–0x2908) para fins personalizados.

Diferença entre Descriptor e Characteristic

Característica e descritor são diferentes níveis de atributos GATT. Uma característica é um ponto de dados, enquanto um descritor são seus metadados ou configuração. A diferença se manifesta em vários aspectos: propósito, UUID e regras de acesso.

Uma característica tem uma declaração obrigatória que está sempre presente na tabela GATT. Um descritor é opcional — uma característica pode não ter descritores. Uma característica pode ser lida, escrita ou enviar notificações independentemente. Um descritor está sempre vinculado a uma característica e não existe separadamente.

De acordo com a Bluetooth Core Specification 5.4, a ordem dos atributos na tabela GATT é a seguinte: declaração do serviço, declaração da característica, valor da característica, descritores da característica (se houver), depois o próximo serviço. Esta ordem é obrigatória para o correto funcionamento dos clientes GATT.