Descriptor: nedir, Client Characteristic Configuration ve örnekler

BLE'de Descriptor Nedir?

Descriptor, bir Characteristic'e eklenen ve değeri veya kullanım şekli hakkında ek bilgi sağlayan bir GATT protokolü özelliğidir. GATT terminolojisinde, karakteristik veridir ve tanımlayıcı bu verinin meta verisidir.

Her Characteristic sıfır veya daha fazla tanımlayıcıya sahip olabilir. Tanımlayıcılar, GATT tablosunda ayrı özellikler olarak tanımlanır ve Bluetooth SIG alanında kendi 16 bit UUID'lerine sahiptir. Tanımlayıcılar bağımsız olarak var olamaz — her zaman belirli bir karakteristiğe bağlıdırlar.

Bluetooth Core Specification 5.4 (2023)'e göre tanımlayıcılar iki kategoriye ayrılır: standart (Bluetooth SIG tarafından tanımlanan) ve özel (geliştirici tarafından tanımlanan). Standart tanımlayıcıların UUID'leri 0x2900–0x2908 aralığındadır ve kesin olarak tanımlanmış işlevleri yerine getirir. Özel tanımlayıcılar, özel hizmetler ve karakteristikler gibi 128 bit UUID kullanır.

Tanımlayıcılar, bir BLE bağlantısının davranışını yapılandırmak için önemli bir mekanizmadır. CCCD (0x2902) olmadan bildirimlere abone olmak imkansızdır, Presentation Format (0x2904) olmadan Central, karakteristiğin ham baytlarını nasıl yorumlayacağını bilemez.

Client Characteristic Configuration Descriptor (CCCD)

CCCD (UUID 0x2902), BLE'deki en önemli ve yaygın olarak kullanılan tanımlayıcıdır. Karakteristikten Notify ve Indicate için Central'ın aboneliğini yönetir. CCCD'ye yazılmazsa, Notify özelliği olsa bile karakteristik bildirim göndermez.

CCCD, en düşük anlamlı bitin (0x0001) Notify'yi ve ikinci bitin (0x0002) Indicate'i etkinleştirdiği 16 bitlik bir değerdir. Central, CCCD'ye istenen değeri yazarak bildirimlere abone olur. Central 0x0000 yazarsa — abonelik iptal edilir.

CCCD mekanizması şöyle çalışır: Central, Notify'ı destekleyen bir karakteristik keşfettiğinde, CCCD tanımlayıcısını bulur ve 0x0001 yazar. Bundan sonra, Peripheral karakteristik değerini her güncellediğinde, Handle Value Notification aracılığıyla abone olan Central'a otomatik olarak gönderilir (Central'dan istek olmadan).

Apple Core Bluetooth Programming Guide'a göre, bir karakteristik için setNotifyValue çağrıldığında CCCD sistem tarafından otomatik olarak yönetilir. Geliştiricinin CCCD'yi manuel olarak bulup yazması gerekmez — Core Bluetooth, bildirimler etkinleştirildiğinde bunu otomatik olarak yapar.

Bildirimlere programatik abonelik

iOS'ta abonelik, CBPeripheral nesnesi üzerindeki setNotifyValue yöntemiyle yapılır.

import CoreBluetooth

// Karakteristik bildirimlerine abone ol
peripheral.setNotifyValue(true, for: characteristic)

// Temsilci güncellenmiş değerleri alır
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // characteristic.value yeni verilere sahip
    guard let data = characteristic.value else { return }
}

Android'de bildirimlere abonelik, BluetoothGatt.setCharacteristicNotification aracılığıyla yapılır. Geliştirici ayrıca CCCD'ye manuel olarak 0x0001 değerini yazmalıdır.

import android.bluetooth.*;

// Bildirimleri etkinleştir
bluetoothGatt.setCharacteristicNotification(characteristic, true);

// CCCD'ye 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 Tanımlayıcıları

Bluetooth SIG, yaygın karakteristik yapılandırma görevleri için 8 standart tanımlayıcı tanımlamıştır. Her tanımlayıcının kesin olarak tanımlanmış bir UUID'si ve değer biçimi vardır.

Characteristic User Description (0x2901), kullanıcı arayüzü için özellikle yararlıdır: uygulama arayüzünde görüntülenebilecek karakteristiğin insan tarafından okunabilir adını içerir. Örneğin, bir Battery Level karakteristiği, “Pil şarj seviyesi” değerine sahip bir User Description tanımlayıcısına sahip olabilir.

Characteristic Presentation Format (0x2904), karakteristik değerinin nasıl yorumlanacağı hakkında bilgi içerir: biçim (uint8, uint16, float), üs, ölçüm birimi (Bluetooth SIG kayıt defterinden UUID aracılığıyla), ad alanı ve açıklama. Örneğin, sıcaklık üs -2 (bölme değeri 0,01°C) ve “Santigrat derece” ölçüm birimiyle int16 olabilir.

iOS ve Android'de Descriptor Kullanımı

Tanımlayıcılara erişim iOS ve Android'de farklılık gösterir. Core Bluetooth, bildirimler etkinleştirildiğinde CCCD'yi otomatik olarak yönetirken, Android tanımlayıcıya manuel olarak değer yazılmasını gerektirir. Her iki yaklaşıma da bakalım.

iOS: Otomatik CCCD Yönetimi

iOS'ta geliştirici genellikle tanımlayıcılarla doğrudan etkileşime girmez. setNotifyValue çağrıldığında Core Bluetooth otomatik olarak CCCD'yi bulur ve gerekli değeri yazar. Tanımlayıcıları okumak için discoverDescriptors yöntemi kullanılır.

// Tanımlayıcıları keşfet
peripheral.discoverDescriptors(for: characteristic)

// User Description değerini oku
func peripheral(
    _ peripheral: CBPeripheral,
    didDiscoverDescriptorsFor characteristic: CBCharacteristic,
    error: Error?
) {
    for descriptor in characteristic.descriptors ?? [] {
        if descriptor.uuid == CBUUID("2901") {
            peripheral.readValue(for: descriptor)
        }
    }
}

Android: Manuel CCCD Yönetimi

Android'de geliştirici, karakteristiğin CCCD tanımlayıcısını bulmalı ve bildirimleri etkinleştirmek için değeri yazmalıdır. Bu, iOS'a kıyasla ek bir adımdır.

// User Description tanımlayıcı değerini oku
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

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

Özel Tanımlayıcı Oluşturma

Özel tanımlayıcılar, Bluetooth SIG standart tanımlayıcıları yeterli olmadığında kullanılır. Örneğin, bir tıbbi sensör üreticisi, sensör kalibrasyon bilgilerini içeren bir tanımlayıcı veya hata günlüğü olan bir tanımlayıcı ekleyebilir.

Özel bir tanımlayıcı, özel bir karakteristik gibi 128 bit UUID ile oluşturulur. Peripheral tarafında, geliştirici onu uygun API aracılığıyla karakteristiğe ekler. Central tarafında, tanımlayıcı discoverDescriptors çağrıldığında otomatik olarak keşfedilir.

Özel bir tanımlayıcı oluştururken şu kurallara uyun: değer uzunluğu beklenen veri türüyle eşleşmeli ve erişim hakları (okuma/yazma) açıkça belirtilmelidir. Özel amaçlar için Bluetooth SIG standart tanımlayıcı aralığındaki (0x2900–0x2908) UUID'leri kullanmayın.

Descriptor ve Characteristic Arasındaki Fark

Karakteristik ve tanımlayıcı, GATT özelliklerinin farklı seviyeleridir. Karakteristik bir veri noktasıdır, tanımlayıcı ise onun meta verisi veya yapılandırmasıdır. Fark, birkaç açıdan kendini gösterir: amaç, UUID ve erişim kuralları.

Bir karakteristiğin GATT tablosunda her zaman bulunan zorunlu bir bildirimi vardır. Tanımlayıcı isteğe bağlıdır — bir karakteristiğin hiç tanımlayıcısı olmayabilir. Bir karakteristik bağımsız olarak okunabilir, yazılabilir veya bildirim gönderebilir. Bir tanımlayıcı her zaman bir karakteristiğe bağlıdır ve ayrı olarak var olmaz.

Bluetooth Core Specification 5.4'e göre, GATT tablosundaki özelliklerin sırası şöyledir: hizmet bildirimi, karakteristik bildirimi, karakteristik değeri, karakteristik tanımlayıcıları (varsa), ardından bir sonraki hizmet. Bu sıra, GATT istemcilerinin doğru çalışması için zorunludur.