Descriptor: що це, Client Characteristic Configuration та приклади

Що таке Descriptor у BLE?

Descriptor — це атрибут GATT-протоколу, який прикріплюється до Characteristic та надає додаткову інформацію про її значення або спосіб використання. У термінології GATT, характеристика — це дані, а дескриптор — це метадані цих даних.

Кожна Characteristic може мати нуль або більше дескрипторів. Дескриптори визначаються як окремі атрибути в 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)

// Делегат отримує оновлені значення
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) та одиницею вимірювання «градус Цельсія».

Як використовувати Descriptor у 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.

При створенні кастомного дескриптора дотримуйтеся правил: довжина значення повинна відповідати очікуваному типу даних, права доступу (читання/запис) мають бути явно вказані. Не використовуйте UUID з діапазону стандартних дескрипторів Bluetooth SIG (0x2900–0x2908) для кастомних цілей.

Відмінність Descriptor від Characteristic

Характеристика та дескриптор — це різні рівні GATT-атрибутів. Характеристика — це точка даних, а дескриптор — її метадані або конфігурація. Різниця проявляється в кількох аспектах: призначенні, UUID та правилах доступу.

Характеристика має обов'язкове оголошення, яке завжди знаходиться в GATT-таблиці. Дескриптор опціональний — характеристика може не мати дескрипторів. Характеристика може бути прочитана, записана або надсилати сповіщення незалежно. Дескриптор завжди прив'язаний до характеристики та не існує окремо.

За даними Bluetooth Core Specification 5.4, у GATT-таблиці порядок атрибутів наступний: оголошення сервісу, оголошення характеристики, значення характеристики, дескриптори характеристики (якщо є), потім наступний сервіс. Цей порядок обов'язковий для коректної роботи GATT-клієнтів.