Дескриптор: шта је, Client Characteristic Configuration и примери

Шта је дескриптор у BLE-у?

Дескриптор — је атрибут GATT протокола који се прикачује на карактеристику и пружа додатне информације о њеној вредности или начину коришћења. У терминологији GATT-а, карактеристика је податак, а дескриптор је метаподатак тих података.

Свака карактеристика може имати нулу или више дескриптора. Дескриптори су дефинисани као засебни атрибути у GATT табели и имају сопствене 16-битне UUID у простору Bluetooth SIG-а. Дескриптори не могу постојати самостално — увек су везани за одређену карактеристику.

Према Bluetooth Core Specification 5.4 (2023), дескриптори се деле на двије категорије: стандардне (одређене од стране Bluetooth SIG-а) и прилагођене (које дефинише програмер). Стандардни дескриптори имају UUID у опсегу 0x2900–0x2908 и обављају строго одређене функције. Прилагођени дескриптори користе 128-битне UUID, као и прилагођени сервиси и карактеристике.

Дескриптори су кључни механизам за конфигурацију понашања BLE везе. Без CCCD (0x2902) не можете да се претплатите на обавештења, без Presentation Format (0x2904) Central неће знати како да тумачи сирове бајтове карактеристике.

Client Characteristic Configuration Descriptor (CCCD)

CCCD са UUID 0x2902 је најважнији и најшире коришћени дескриптор у BLE-у. Он управља претплатом Central-а на обавештења (Notify) и потврђена обавештења (Indicate) од карактеристике. Без уписа у CCCD, карактеристика неће слати обавештења, чак и ако има својство Notify.

CCCD је 16-битна вредност у којој најмањи бит (0x0001) укључује Notify, а други бит (0x0002) укључује Indicate. Central уписује потребну вредност у CCCD, чиме се претплаћује на обавештења. Ако Central упише 0x0000 — претплата се отказује.

Механизам рада CCCD-а је сљедећи: када Central открије карактеристику са подршком за Notify, проналази њен CCCD дескриптор и уписује 0x0001. Након тога, сваки пут када Peripheral ажурира вредност карактеристике, она се аутоматски шаље претплаћеном Central-у путем Handle Value Notification (без захтјева од Central-а).

Према Apple Core Bluetooth Programming Guide, CCCD-ом аутоматски управља систем при позиву setNotifyValue за карактеристику. Програмер не мора ручно да тражи и уписује CCCD — Core Bluetooth то ради аутоматски при активацији обавештења.

Програмско претплаћивање на обавештења

У iOS-у, претплаћивање се врши путем методе setNotifyValue на објекту CBPeripheral.

import CoreBluetooth

// Претплати се на обавештења карактеристике
peripheral.setNotifyValue(true, for: characteristic)

// Delegate прима ажуриране вриједности
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // characteristic.value има нове податке
    guard let data = characteristic.value else { return }
}

На Android-у, претплаћивање на обавештења се врши путем BluetoothGatt.setCharacteristicNotification. Програмер такође мора ручно да упише вриједност 0x0001 у CCCD.

import android.bluetooth.*;

// Укључи обавештења
bluetoothGatt.setCharacteristicNotification(characteristic, true);

// Упиши 0x0001 у CCCD
BluetoothGattDescriptor descriptor = characteristic
    .getDescriptor(
        UUID.fromString("00002902-0000-1000-8000-00805F9B34FB")
    );
descriptor.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE);
bluetoothGatt.writeDescriptor(descriptor);

Стандардни дескриптори Bluetooth SIG-а

Bluetooth SIG је дефинисао 8 стандардних дескриптора за уобичајене задатке конфигурације карактеристика. Сваки дескриптор има строго дефинисан UUID и формат вриједности.

Characteristic User Description (0x2901) је посебно користан за UI: садржи људски читљиво име карактеристике које се може приказати у корисничком интерфејсу апликације. На примјер, карактеристика Battery Level може имати дескриптор User Description са вриједношћу „Ниво напуњености батерије“.

Characteristic Presentation Format (0x2904) садржи информације о томе како тумачити вриједност карактеристике: формат (uint8, uint16, float), експонент, јединица мере (путем UUID-а из регистра Bluetooth SIG-а), именски простор и опис. На примјер, температура може бити int16 са експонентом -2 (вриједност подјеле 0.01°C) и јединицом мере „степен Целзијуса“.

Како користити дескриптор у iOS-у и Android-у

Приступ дескрипторима се разликује на iOS-у и Android-у. Core Bluetooth аутоматски управља CCCD-ом при укључивању обавештења, а Android захтијева ручно уписана вриједност у дескриптор. Размотримо оба приступа.

iOS: аутоматско управљање CCCD-ом

У iOS-у, програмер обично не интерагује директно са дескрипторима. Core Bluetooth аутоматски проналази CCCD и уписује потребну вриједност при позиву setNotifyValue. За читање дескриптора користи се метода discoverDescriptors.

// Откриј дескрипторе
peripheral.discoverDescriptors(for: characteristic)

// Прочитај вриједност 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: ручно управљање CCCD-ом

На Android-у, програмер мора сам да пронађе CCCD дескриптор карактеристике и упише вриједност за укључивање обавештења. Ово је додатни корак у поређењу са iOS-ом.

// Прочитај вриједност дескриптора User Description
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

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

Креирање прилагођених дескриптора

Прилагођени дескриптори се користе када стандардни дескриптори Bluetooth SIG-а нису довољни. На примјер, произвођач медицинског сензора може додати дескриптор са информацијама о калибрацији сензора или дескриптор са евиденцијом грешака.

Прилагођени дескриптор се креира са 128-битним UUID, као и прилагођена карактеристика. На страни Peripheral-а, програмер га додаје карактеристици путем одговарајућег API-ја. На страни Central-а, дескриптор се аутоматски открива при позиву discoverDescriptors.

При креирању прилагођеног дескриптора поштујте правила: дужина вриједности мора одговарати очекиваном типу података, права приступа (read/write) морају бити јасно наведена. Не користите UUID-ове из опсега стандардних дескриптора Bluetooth SIG-а (0x2900–0x2908) за прилагођене сврхе.

Разлика између дескриптора и карактеристике

Карактеристика и дескриптор су различити нивои GATT атрибута. Карактеристика је тачка података, а дескриптор је њен метаподатак или конфигурација. Разлика се манифестује у неколико аспеката: намјени, UUID-а и правилима приступа.

Карактеристика има обавезну декларацију (declaration) која се увијек налази у GATT табели. Дескриптор је опционалан — карактеристика може да нема дескриптора. Карактеристика може бити прочитана, записана или слати обавештења независно. Дескриптор је увијек везан за карактеристику и не постоји одвојено.

Према Bluetooth Core Specification 5.4, у GATT табели редослијед атрибута је сљедећи: декларација сервиса, декларација карактеристике, вриједност карактеристике, дескриптори карактеристике (ако има), затим сљедећи сервис. Овај редослијед је обавезан за исправан рад GATT клијената.