Deskriptor: ano ito, Client Characteristic Configuration at mga halimbawa

Ano ang deskriptor sa BLE?

Deskriptor — ay isang katangian ng GATT protocol na nakakabit sa karakteristiko at nagbibigay ng karagdagang impormasyon tungkol sa halaga o paraan ng paggamit nito. Sa terminolohiya ng GATT, ang karakteristiko ay ang data, at ang deskriptor ay ang metadata ng data na iyon.

Ang bawat karakteristiko ay maaaring magkaroon ng zero o higit pang mga deskriptor. Ang mga deskriptor ay tinukoy bilang magkakahiwalay na katangian sa GATT table at may sariling 16-bit na UUID sa espasyo ng Bluetooth SIG. Ang mga deskriptor ay hindi maaaring umiral nang mag-isa — sila ay palaging nakatali sa isang tiyak na karakteristiko.

Ayon sa Bluetooth Core Specification 5.4 (2023), ang mga deskriptor ay nahahati sa dalawang kategorya: standard (tinukoy ng Bluetooth SIG) at custom (tinukoy ng developer). Ang mga standard na deskriptor ay may UUID sa saklaw na 0x2900–0x2908 at nagsasagawa ng mahigpit na tinukoy na mga function. Ang mga custom na deskriptor ay gumagamit ng 128-bit na UUID, katulad ng mga custom na serbisyo at karakteristiko.

Ang mga deskriptor ay ang pangunahing mekanismo para sa configuration ng pag-uugali ng koneksyon ng BLE. Kung walang CCCD (0x2902) hindi ka maaaring mag-subscribe sa mga notification, kung walang Presentation Format (0x2904) hindi malalaman ng Central kung paano i-interpret ang mga raw byte ng karakteristiko.

Client Characteristic Configuration Descriptor (CCCD)

CCCD na may UUID 0x2902 ay ang pinakamahalaga at pinakamalawak na ginagamit na deskriptor sa BLE. Pinamamahalaan nito ang subscription ng Central sa mga notification (Notify) at kumpirmadong notification (Indicate) mula sa karakteristiko. Kung walang pagsulat sa CCCD, hindi magpapadala ng mga notification ang karakteristiko, kahit na mayroon itong property na Notify.

Ang CCCD ay isang 16-bit na halaga kung saan ang pinakamababang bit (0x0001) ay nagpapagana ng Notify, at ang pangalawang bit (0x0002) ay nagpapagana ng Indicate. Isinusulat ng Central ang nais na halaga sa CCCD, sa gayon ay nag-subscribe sa mga notification. Kung ang Central ay sumulat ng 0x0000 — ang subscription ay kinakansela.

Ang mekanismo ng paggana ng CCCD ay ang mga sumusunod: kapag nakita ng Central ang isang karakteristiko na may suporta sa Notify, hinahanap nito ang CCCD deskriptor nito at isinusulat ang 0x0001. Pagkatapos nito, sa bawat oras na Peripheral ay nag-a-update ng halaga ng karakteristiko, ito ay awtomatikong ipinapadala sa naka-subscribe na Central sa pamamagitan ng Handle Value Notification (walang kahilingan mula sa Central).

Ayon sa Apple Core Bluetooth Programming Guide, ang CCCD ay awtomatikong pinamamahalaan ng system kapag tinawag ang setNotifyValue para sa karakteristiko. Ang developer ay hindi kailangang manu-manong hanapin at isulat ang CCCD — awtomatikong ginagawa ito ng Core Bluetooth kapag nag-activate ng mga notification.

Programatikong pag-subscribe sa mga notification

Sa iOS, ang pag-subscribe ay ginagawa sa pamamagitan ng setNotifyValue method sa CBPeripheral object.

import CoreBluetooth

// Mag-subscribe sa mga notification ng karakteristiko
peripheral.setNotifyValue(true, for: characteristic)

// Ang delegate ay tumatanggap ng mga na-update na halaga
func peripheral(
    _ peripheral: CBPeripheral,
    didUpdateValueFor characteristic: CBCharacteristic,
    error: Error?
) {
    // Ang characteristic.value ay may bagong data
    guard let data = characteristic.value else { return }
}

Sa Android, ang pag-subscribe sa mga notification ay ginagawa sa pamamagitan ng BluetoothGatt.setCharacteristicNotification. Dapat ding isulat ng developer ang halaga na 0x0001 sa CCCD nang manu-mano.

import android.bluetooth.*;

// I-activate ang mga notification
bluetoothGatt.setCharacteristicNotification(characteristic, true);

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

Mga standard na deskriptor ng Bluetooth SIG

Bluetooth SIG ay nagtakda ng 8 standard na deskriptor para sa mga karaniwang gawain ng configuration ng karakteristiko. Ang bawat deskriptor ay may mahigpit na tinukoy na UUID at format ng halaga.

Characteristic User Description (0x2901) ay lalong kapaki-pakinabang para sa UI: naglalaman ito ng pangalan ng karakteristiko na nababasa ng tao na maaaring ipakita sa interface ng application. Halimbawa, ang karakteristiko na Battery Level ay maaaring magkaroon ng User Description deskriptor na may halagang “Antas ng pag-charge ng baterya”.

Characteristic Presentation Format (0x2904) ay naglalaman ng impormasyon kung paano i-interpret ang halaga ng karakteristiko: format (uint8, uint16, float), exponent, yunit ng pagsukat (sa pamamagitan ng UUID mula sa rehistro ng Bluetooth SIG), namespace at deskripsyon. Halimbawa, ang temperatura ay maaaring int16 na may exponent -2 (halaga ng paghahati 0.01°C) at yunit ng pagsukat na “degree Celsius”.

Paano gamitin ang deskriptor sa iOS at Android

Access sa mga deskriptor ay naiiba sa iOS at Android. Awtomatikong pinamamahalaan ng Core Bluetooth ang CCCD kapag nag-a-activate ng mga notification, habang ang Android ay nangangailangan ng manu-manong pagsulat ng halaga sa deskriptor. Tingnan natin ang parehong approach.

iOS: awtomatikong pamamahala ng CCCD

Sa iOS, ang developer ay karaniwang hindi direktang nakikipag-ugnayan sa mga deskriptor. Awtomatikong hinahanap ng Core Bluetooth ang CCCD at isinusulat ang kinakailangang halaga kapag tinawag ang setNotifyValue. Para sa pagbabasa ng mga deskriptor, ginagamit ang discoverDescriptors method.

// Tuklasin ang mga deskriptor
peripheral.discoverDescriptors(for: characteristic)

// Basahin ang halaga ng 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: manu-manong pamamahala ng CCCD

Sa Android, dapat hanapin mismo ng developer ang CCCD deskriptor ng karakteristiko at isulat ang halaga para i-activate ang mga notification. Ito ay isang karagdagang hakbang kumpara sa iOS.

// Basahin ang halaga ng User Description deskriptor
BluetoothGattDescriptor userDesc = characteristic
    .getDescriptor(
        UUID.fromString("00002901-0000-1000-8000-00805F9B34FB")
    );

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

Paglikha ng mga custom na deskriptor

Mga custom na deskriptor ay ginagamit kapag ang mga standard na deskriptor ng Bluetooth SIG ay hindi sapat. Halimbawa, ang isang manufacturer ng medical sensor ay maaaring magdagdag ng deskriptor na may impormasyon tungkol sa calibration ng sensor o isang deskriptor na may error log.

Ang isang custom na deskriptor ay nilikha gamit ang 128-bit na UUID, tulad ng isang custom na karakteristiko. Sa panig ng Peripheral, idinadagdag ito ng developer sa karakteristiko sa pamamagitan ng kaukulang API. Sa panig ng Central, ang deskriptor ay awtomatikong natutuklasan kapag tinawag ang discoverDescriptors.

Sa paglikha ng custom na deskriptor, sundin ang mga patakaran: ang haba ng halaga ay dapat tumugma sa inaasahang uri ng data, ang mga karapatan sa pag-access (read/write) ay dapat na tahasang tinukoy. Huwag gumamit ng UUID mula sa saklaw ng mga standard na deskriptor ng Bluetooth SIG (0x2900–0x2908) para sa mga custom na layunin.

Pagkakaiba ng deskriptor at karakteristiko

Karakteristiko at deskriptor — ito ay magkaibang antas ng GATT attributes. Ang karakteristiko ay isang punto ng data, at ang deskriptor ay ang metadata o configuration nito. Ang pagkakaiba ay makikita sa ilang aspeto: layunin, UUID at mga patakaran sa pag-access.

Ang karakteristiko ay may mandatoryong deklarasyon (declaration) na laging nasa GATT table. Ang deskriptor ay opsyonal — ang karakteristiko ay maaaring walang mga deskriptor. Ang karakteristiko ay maaaring basahin, isulat o magpadala ng mga notification nang hiwalay. Ang deskriptor ay palaging nakatali sa karakteristiko at hindi umiiral nang hiwalay.

Ayon sa Bluetooth Core Specification 5.4, sa GATT table ang pagkakasunod-sunod ng mga attribute ay ang mga sumusunod: deklarasyon ng serbisyo, deklarasyon ng karakteristiko, halaga ng karakteristiko, mga deskriptor ng karakteristiko (kung mayroon), pagkatapos ay ang susunod na serbisyo. Ang pagkakasunod-sunod na ito ay sapilitan para sa tamang operasyon ng mga GATT client.