Deskriptor: apa itu, Client Characteristic Configuration dan contoh

Apa itu deskriptor di BLE?

Deskriptor — adalah atribut protokol GATT yang melekat pada karakteristik dan memberikan informasi tambahan tentang nilai atau cara penggunaannya. Dalam terminologi GATT, karakteristik adalah data, dan deskriptor adalah metadata dari data tersebut.

Setiap karakteristik dapat memiliki nol atau lebih deskriptor. Deskriptor didefinisikan sebagai atribut terpisah dalam tabel GATT dan memiliki UUID 16-bit sendiri di ruang Bluetooth SIG. Deskriptor tidak dapat berdiri sendiri — mereka selalu terikat pada karakteristik tertentu.

Menurut Bluetooth Core Specification 5.4 (2023), deskriptor dibagi menjadi dua kategori: standar (ditentukan oleh Bluetooth SIG) dan kustom (ditentukan oleh pengembang). Deskriptor standar memiliki UUID dalam rentang 0x2900–0x2908 dan menjalankan fungsi yang ditentukan secara ketat. Deskriptor kustom menggunakan UUID 128-bit, mirip dengan layanan dan karakteristik kustom.

Deskriptor adalah mekanisme kunci untuk konfigurasi perilaku koneksi BLE. Tanpa CCCD (0x2902) tidak mungkin berlangganan notifikasi, tanpa Presentation Format (0x2904) Central tidak akan tahu cara menafsirkan byte mentah karakteristik.

Client Characteristic Configuration Descriptor (CCCD)

CCCD dengan UUID 0x2902 adalah deskriptor terpenting dan paling banyak digunakan di BLE. Ia mengelola langganan Central ke notifikasi (Notify) dan notifikasi terkonfirmasi (Indicate) dari karakteristik. Tanpa penulisan ke CCCD, karakteristik tidak akan mengirim notifikasi, bahkan jika ia memiliki properti Notify.

CCCD adalah nilai 16-bit di mana bit paling rendah (0x0001) mengaktifkan Notify, dan bit kedua (0x0002) mengaktifkan Indicate. Central menulis nilai yang diinginkan ke CCCD, dengan demikian berlangganan notifikasi. Jika Central menulis 0x0000 — langganan dibatalkan.

Mekanisme kerja CCCD adalah sebagai berikut: ketika Central mendeteksi karakteristik dengan dukungan Notify, ia menemukan deskriptor CCCD-nya dan menulis 0x0001. Setelah itu, setiap kali Peripheral memperbarui nilai karakteristik, nilai tersebut secara otomatis dikirim ke Central yang berlangganan melalui Handle Value Notification (tanpa permintaan dari Central).

Menurut Apple Core Bluetooth Programming Guide, CCCD dikelola secara otomatis oleh sistem saat setNotifyValue dipanggil untuk karakteristik. Pengembang tidak perlu mencari dan menulis CCCD secara manual — Core Bluetooth melakukannya secara otomatis saat aktivasi notifikasi.

Berlangganan notifikasi secara programatis

Di iOS, langganan dilakukan melalui metode setNotifyValue pada objek CBPeripheral.

import CoreBluetooth

// Berlangganan notifikasi karakteristik
peripheral.setNotifyValue(true, for: characteristic)

// Delegate menerima nilai yang diperbarui
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // characteristic.value memiliki data baru
    guard let data = characteristic.value else { return }
}

Di Android, langganan notifikasi dilakukan melalui BluetoothGatt.setCharacteristicNotification. Pengembang juga harus menulis nilai 0x0001 ke CCCD secara manual.

import android.bluetooth.*;

// Aktifkan notifikasi
bluetoothGatt.setCharacteristicNotification(characteristic, true);

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

Deskriptor standar Bluetooth SIG

Bluetooth SIG telah mendefinisikan 8 deskriptor standar untuk tugas konfigurasi karakteristik yang umum. Setiap deskriptor memiliki UUID dan format nilai yang ditentukan secara ketat.

Characteristic User Description (0x2901) sangat berguna untuk UI: ia berisi nama karakteristik yang dapat dibaca manusia yang dapat ditampilkan di antarmuka aplikasi. Misalnya, karakteristik Battery Level dapat memiliki deskriptor User Description dengan nilai “Tingkat pengisian baterai”.

Characteristic Presentation Format (0x2904) berisi informasi tentang cara menafsirkan nilai karakteristik: format (uint8, uint16, float), eksponen, satuan ukuran (melalui UUID dari registri Bluetooth SIG), ruang nama, dan deskripsi. Misalnya, suhu bisa int16 dengan eksponen -2 (nilai pembagian 0.01°C) dan satuan ukuran “derajat Celcius”.

Cara menggunakan deskriptor di iOS dan Android

Akses ke deskriptor berbeda di iOS dan Android. Core Bluetooth secara otomatis mengelola CCCD saat mengaktifkan notifikasi, sedangkan Android memerlukan penulisan manual nilai ke deskriptor. Mari kita lihat kedua pendekatan.

iOS: manajemen CCCD otomatis

Di iOS, pengembang biasanya tidak berinteraksi langsung dengan deskriptor. Core Bluetooth secara otomatis menemukan CCCD dan menulis nilai yang diperlukan saat setNotifyValue dipanggil. Untuk membaca deskriptor, digunakan metode discoverDescriptors.

// Temukan deskriptor
peripheral.discoverDescriptors(for: characteristic)

// Baca nilai 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: manajemen CCCD manual

Di Android, pengembang harus menemukan sendiri deskriptor CCCD karakteristik dan menulis nilai untuk mengaktifkan notifikasi. Ini adalah langkah tambahan dibandingkan dengan iOS.

// Baca nilai deskriptor User Description
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

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

Membuat deskriptor kustom

Deskriptor kustom digunakan ketika deskriptor standar Bluetooth SIG tidak mencukupi. Misalnya, produsen sensor medis dapat menambahkan deskriptor dengan informasi tentang kalibrasi sensor atau deskriptor dengan log kesalahan.

Deskriptor kustom dibuat dengan UUID 128-bit, seperti karakteristik kustom. Di sisi Peripheral, pengembang menambahkannya ke karakteristik melalui API yang sesuai. Di sisi Central, deskriptor terdeteksi secara otomatis saat discoverDescriptors dipanggil.

Saat membuat deskriptor kustom, patuhi aturan: panjang nilai harus sesuai dengan tipe data yang diharapkan, hak akses (read/write) harus ditentukan secara eksplisit. Jangan gunakan UUID dari rentang deskriptor standar Bluetooth SIG (0x2900–0x2908) untuk tujuan kustom.

Perbedaan deskriptor dan karakteristik

Karakteristik dan deskriptor — ini adalah tingkat atribut GATT yang berbeda. Karakteristik adalah titik data, dan deskriptor adalah metadata atau konfigurasinya. Perbedaan terlihat dalam beberapa aspek: tujuan, UUID, dan aturan akses.

Karakteristik memiliki deklarasi wajib (declaration) yang selalu ada dalam tabel GATT. Deskriptor bersifat opsional — karakteristik mungkin tidak memiliki deskriptor. Karakteristik dapat dibaca, ditulis, atau mengirim notifikasi secara independen. Deskriptor selalu terikat pada karakteristik dan tidak ada secara terpisah.

Menurut Bluetooth Core Specification 5.4, dalam tabel GATT urutan atribut adalah sebagai berikut: deklarasi layanan, deklarasi karakteristik, nilai karakteristik, deskriptor karakteristik (jika ada), kemudian layanan berikutnya. Urutan ini wajib untuk operasi klien GATT yang benar.