Deskriptor: bu nədir, Client Characteristic Configuration və nümunələr

BLE-də deskriptor nədir?

Deskriptor — GATT protokolunun atributudur, o, xarakteristikaya əlavə olunur və onun dəyəri və ya istifadə üsulu haqqında əlavə məlumat verir. GATT terminologiyasında xarakteristika məlumatdır, deskriptor isə bu məlumatların metadatanıdır.

Hər bir xarakteristikanın sıfır və ya daha çox deskriptoru ola bilər. Deskriptorlar GATT cədvəlində ayrı atributlar kimi müəyyən edilir və Bluetooth SIG məkanında öz 16-bit UUID-lərinə malikdir. Deskriptorlar müstəqil mövcud ola bilməz — onlar həmişə konkret xarakteristikaya bağlıdır.

Bluetooth Core Specification 5.4 (2023)-ə görə, deskriptorlar iki kateqoriyaya bölünür: standart (Bluetooth SIG tərəfindən müəyyən edilmiş) və fərdi (tərtibatçı tərəfindən müəyyən edilən). Standart deskriptorlar 0x2900–0x2908 diapazonunda UUID-lərə malikdir və ciddi müəyyən edilmiş funksiyaları yerinə yetirir. Fərdi deskriptorlar fərdi xidmətlər və xarakteristikalar kimi 128-bit UUID-lərdən istifadə edir.

Deskriptorlar BLE əlaqəsinin davranış konfiqurasiyası üçün əsas mexanizmdir. CCCD (0x2902) olmadan bildirişlərə abunə olmaq mümkün deyil, Presentation Format (0x2904) olmadan Central xarakteristikanın xam baytlarını necə şərh edəcəyini bilməz.

Client Characteristic Configuration Descriptor (CCCD)

CCCD UUID 0x2902 ilə BLE-də ən vacib və geniş istifadə olunan deskriptordur. O, Central-ın xarakteristikadan bildirişlərə (Notify) və təsdiqlənmiş bildirişlərə (Indicate) abunəliyini idarə edir. CCCD-yə yazım olmadan, hətta xarakteristikanın Notify xüsusiyyəti olsa belə, bildiriş göndərməyəcəkdir.

CCCD 16-bitlik dəyərdir, burada ən kiçik bit (0x0001) Notify-i, ikinci bit (0x0002) isə Indicate-i aktivləşdirir. Central CCCD-yə lazımi dəyəri yazaraq bildirişlərə abunə olur. Central 0x0000 yazarsa — abunəlik ləğv edilir.

CCCD-nin işləmə mexanizmi belədir: Central Notify dəstəyi olan xarakteristikanı aşkarladıqda, onun CCCD deskriptorunu tapır və 0x0001 yazır. Bundan sonra, hər dəfə Peripheral xarakteristikanın dəyərini yenilədikdə, o, avtomatik olaraq abunə olunmuş Central-a Handle Value Notification vasitəsilə göndərilir (Central-dan sorğu olmadan).

Apple Core Bluetooth Programming Guide-a görə, CCCD avtomatik olaraq sistem tərəfindən idarə olunur, xarakteristika üçün setNotifyValue çağırıldıqda. Tərtibatçı əl ilə CCCD-ni axtarıb yazmalı deyil — Core Bluetooth bildirişlər aktivləşdirildikdə bunu avtomatik edir.

Proqram vasitəsilə bildirişlərə abunəlik

iOS-da abunəlik CBPeripheral obyektində setNotifyValue metodu vasitəsilə həyata keçirilir.

import CoreBluetooth

// Xarakteristikanın bildirişlərinə abunə ol
peripheral.setNotifyValue(true, for: characteristic)

// Delegate yenilənmiş dəyərləri alır
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // characteristic.value-də yeni məlumat var
    guard let data = characteristic.value else { return }
}

Android-də bildirişlərə abunəlik BluetoothGatt.setCharacteristicNotification vasitəsilə həyata keçirilir. Tərtibatçı həmçinin əl ilə CCCD-yə 0x0001 dəyərini yazmalıdır.

import android.bluetooth.*;

// Bildirişləri aktivləşdir
bluetoothGatt.setCharacteristicNotification(characteristic, true);

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

Bluetooth SIG standart deskriptorları

Bluetooth SIG xarakteristika konfiqurasiyasının ümumi tapşırıqları üçün 8 standart deskriptor müəyyən etmişdir. Hər deskriptorun ciddi müəyyən edilmiş UUID və dəyər formatı var.

Characteristic User Description (0x2901) UI üçün xüsusilə faydalıdır: o, proqram interfeysində göstərilə bilən, insan tərəfindən oxuna bilən xarakteristika adını ehtiva edir. Məsələn, Battery Level xarakteristikası „Batareya doldurma səviyyəsi” dəyərinə malik User Description deskriptoruna sahib ola bilər.

Characteristic Presentation Format (0x2904) xarakteristikanın dəyərinin necə şərh ediləcəyi haqqında məlumat ehtiva edir: format (uint8, uint16, float), eksponent, ölçü vahidi (Bluetooth SIG reyestrindən UUID vasitəsilə), ad sahəsi və təsvir. Məsələn, temperatur eksponent -2 (bölmə dəyəri 0.01°C) və „selsi dərəcəsi” ölçü vahidi ilə int16 ola bilər.

iOS və Android-də deskriptordan necə istifadə etməli

Deskriptorlara giriş iOS və Android-də fərqlidir. Core Bluetooth bildirişlər aktivləşdirildikdə CCCD-ni avtomatik idarə edir, Android isə deskriptora əl ilə dəyər yazmağı tələb edir. Hər iki yanaşmanı nəzərdən keçirək.

iOS: CCCD-nin avtomatik idarə edilməsi

iOS-da tərtibatçı adətən deskriptorlarla birbaşa qarşılıqlı əlaqədə olmur. Core Bluetooth avtomatik olaraq CCCD-ni tapır və setNotifyValue çağırıldıqda ona lazımi dəyəri yazır. Deskriptorları oxumaq üçün discoverDescriptors metodundan istifadə olunur.

// Deskriptorları aşkarla
peripheral.discoverDescriptors(for: characteristic)

// User Description dəyərini oxu
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-nin əl ilə idarə edilməsi

Android-də tərtibatçı xarakteristikanın CCCD deskriptorunu özü tapmalı və bildirişləri aktivləşdirmək üçün ona dəyər yazmalıdır. Bu, iOS ilə müqayisədə əlavə addımdır.

// User Description deskriptorunun dəyərini oxu
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

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

Fərdi deskriptorların yaradılması

Fərdi deskriptorlar Bluetooth SIG standart deskriptorları kifayət etmədikdə istifadə olunur. Məsələn, tibbi sensor istehsalçısı sensorun kalibrasiyası haqqında məlumatı olan deskriptor və ya xəta jurnalı olan deskriptor əlavə edə bilər.

Fərdi deskriptor fərdi xarakteristika kimi 128-bit UUID ilə yaradılır. Peripheral tərəfində tərtibatçı onu müvafiq API vasitƏşəsilə xarakteristikaya əlavə edir. Central tərəfində deskriptor discoverDescriptors çağırıldıqda avtomatik aşkarlanır.

Fərdi deskriptor yaradarkən qaydalara əməl edin: dəyərin uzunluğu gözlənilən məlumat növünə uyğun olmalıdır, giriş hüquqları (read/write) açıqşa göstərilməlidir. Fərdi məqsədlər üçün Bluetooth SIG standart deskriptorlarının UUID diapazonundan (0x2900–0x2908) istifadə etməyin.

Deskriptor ilə xarakteristika arasındakı fərq

Xarakteristika və deskriptor — bunlar GATT atributlarının müxtəlif səviyyələridir. Xarakteristika məlumat nöqtəsidir, deskriptor isə onun metadatanı və ya konfiqurasiyasıdır. Fərq bir neçə aspektdə özünü göstərir: təyinat, UUID və giriş qaydaları.

Xarakteristikanın həmişə GATT cədvəlində olan məcburi bəyannaməsi (declaration) var. Deskriptor isteğidir — xarakteristikanın deskriptorları olmaya da bilər. Xarakteristika müstəqil şəkildə oxuna, yazıla və ya bildiriş göndərə bilər. Deskriptor həmişə xarakteristikaya bağlıdır və ayrıca mövcud deyil.

Bluetooth Core Specification 5.4-a görə, GATT cədvəlində atributların sırası belədir: xidmət bəyannaməsi, xarakteristika bəyannaməsi, xarakteristikanın dəyəri, xarakteristikanın deskriptorları (varsa), sonra növbəti xidmət. Bu sıra GATT müştərilərinin düzgün işləməsi üçün məcburidir.