GATT — cos'è, Generic Attribute Profile e implementazione in Android

Cos'è GATT?

GATT (Generic Attribute Profile) è un profilo Bluetooth Low Energy (BLE) che definisce come due dispositivi BLE scambiano dati attraverso l'Attribute Protocol (ATT). GATT standardizza la struttura dei dati: tutti i dati sono organizzati in una gerarchia “servizio → caratteristica → descrittore”. Il profilo è stato introdotto nella specifica Bluetooth 4.0 (2010) insieme a BLE e da allora rimane il meccanismo principale di trasferimento dati per dispositivi Bluetooth a basso consumo. A differenza del Bluetooth classico, dove i dati vengono trasmessi attraverso una porta seriale (SPP), GATT fornisce un accesso strutturato ai dati attraverso operazioni di lettura, scrittura e notifica.

Il ruolo di GATT nello stack BLE

Lo stack BLE è composto da diversi livelli: Livello Fisico (radio), Livello Collegamento (gestione connessione), L2CAP (controllo canale logico), ATT (Attribute Protocol — accesso agli attributi) e GATT (profilo basato su ATT). GATT è il livello più alto con cui lavorano gli sviluppatori di applicazioni. L'ATT sottostante fornisce operazioni di base: lettura, scrittura, notifica e indicazione degli attributi. GATT aggiunge semantica: definisce cosa sono un servizio e una caratteristica, come sono raggruppati e quali regole si applicano durante la lettura e scrittura. Secondo la Bluetooth Core Specification 5.4 (2023), GATT supporta fino a 65.535 attributi (servizi + caratteristiche + descrittori) su un singolo dispositivo.

Architettura GATT: servizi, caratteristiche e descrittori

La gerarchia GATT è composta da tre livelli. Un Servizio è un gruppo logico di caratteristiche che risolve un compito (ad esempio, “Servizio Batteria” o “Servizio Frequenza Cardiaca”). Una Caratteristica è un'unità di dati con un tipo noto: livello batteria attuale, lettura sensore, stato interruttore. Ogni caratteristica ha un valore e uno o più Descrittori che descrivono metadati: unità di misura, impostazioni di notifica, intervallo di valori. UUID (Identificatore Univoco Universale) identifica in modo univoco ogni servizio e ogni caratteristica.

Tipi di operazioni con le caratteristiche

GATT supporta quattro tipi di operazioni per interagire con le caratteristiche. Read — il client richiede il valore corrente di una caratteristica al server. Write — il client invia un nuovo valore al server. Notify — il server invia un valore al client senza conferma (più veloce ma meno affidabile). Indicate — il server invia un valore con conferma di ricezione (più affidabile ma più lento). Lo sviluppatore sceglie il tipo in base allo scenario: per le letture del sensore di frequenza cardiaca, Notify è sufficiente; per scrivere la configurazione di una serratura intelligente, è necessario Write con conferma.

// Struttura dati GATT nel codice Android
data class BleService(
    val uuid: UUID,
    val characteristics: List<BleCharacteristic>
)

data class BleCharacteristic(
    val uuid: UUID,
    val properties: Int, // READ, WRITE, NOTIFY, INDICATE
    val descriptors: List<BleDescriptor>,
    var value: ByteArray?
)

GATT e GAP: differenze tra i profili BLE

La specifica BLE definisce due profili principali: GAP (Generic Access Profile) e GATT (Generic Attribute Profile). GAP è responsabile della scoperta dei dispositivi, dell'instaurazione della connessione e della gestione della visibilità — è il “livello di rete” del BLE. GATT è responsabile dello scambio di dati dopo l'instaurazione della connessione — il “livello applicativo”. Lo sviluppatore usa GAP per scansionare e connettersi a un dispositivo, e GATT per leggere, scrivere e ricevere notifiche dal dispositivo connesso.

Ruoli in GATT

GATT definisce due ruoli: Server GATT e Client GATT. Il Server è un dispositivo che fornisce dati (ad esempio, un fitness tracker che invia letture della frequenza cardiaca). Il Client è un dispositivo che richiede dati (ad esempio, uno smartphone che legge le letture). Nella maggior parte degli scenari, l'app Android agisce come Client GATT e il periferico BLE agisce come Server GATT. Tuttavia, Android può anche essere un Server GATT — ad esempio, quando un'app emula un dispositivo BLE per altri dispositivi. Il ruolo è determinato nella fase di configurazione della connessione GATT e non cambia durante la sessione.

Come funziona la comunicazione GATT in BLE

Il processo di comunicazione GATT inizia dopo l'instaurazione della connessione BLE tra i dispositivi. Prima, il Client GATT scopre i servizi sul Server GATT attraverso Service Discovery — Android lo fa automaticamente alla connessione tramite BluetoothGatt.discoverServices(). Dopo la scoperta, il client ottiene un elenco di servizi, caratteristiche e descrittori disponibili. Quindi, il client può leggere i valori delle caratteristiche (Read), scrivere nuovi valori (Write) o iscriversi alle notifiche (Set Notify/Indicate). Il Server GATT può inviare Notify/Indicate al client in qualsiasi momento dopo l'instaurazione della connessione.

MTU — Unità Massima di Trasmissione

Per impostazione predefinita, la dimensione di un singolo pacchetto GATT (MTU) in BLE è di 23 byte, di cui 3 byte sono l'intestazione ATT e 20 byte sono dati utili. Se l'applicazione deve trasmettere più dati (ad esempio, aggiornamento firmware OTA), è possibile richiedere un aumento dell'MTU fino a 517 byte tramite requestMtu() in Android. Un MTU maggiore riduce il numero di pacchetti necessari per trasmettere un blocco di dati — invece di 50 pacchetti piccoli, puoi inviarne 2 grandi, riducendo il consumo energetico e accelerando la trasmissione. L'MTU massimo dipende dalla versione BLE e dalle capacità del chip — Bluetooth 5.0 supporta fino a 517 byte, le versioni precedenti fino a 247 byte.

// Iscriviti alle notifiche delle caratteristiche
fun enableNotifications(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic) {
    gatt.setCharacteristicNotification(characteristic, true)

    // Abilita CCCD (Descrittore di Configurazione Caratteristica Client)
    val cccdUuid = UUID.fromString("00002902-0000-1000-8000-00805f9b34fb")
    val descriptor = characteristic.getDescriptor(cccdUuid)
    descriptor?.let {
        it.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE)
        gatt.writeDescriptor(it)
    }
}

Gestione delle notifiche

Per ricevere notifiche dal Server GATT su Android, è necessario implementare il callback BluetoothGattCallback.onCharacteristicChanged(). In questo metodo, l'app riceve il valore aggiornato della caratteristica ogni volta che il server invia Notify o Indicate. Per l'elaborazione dei dati in tempo reale, utilizza un buffer e le coroutine Kotlin — questo impedisce il blocco del thread UI durante notifiche intensive (ad esempio, più di 100 letture della frequenza cardiaca al secondo). Per le Indicazioni, devi chiamare gatt.sendResponse() lato server — sul client Android, questo viene gestito automaticamente.

Implementazione di GATT su Android

Su Android, il lavoro con GATT è implementato attraverso le classi del pacchetto android.bluetooth: BluetoothGatt (connessione), BluetoothGattService (servizio), BluetoothGattCharacteristic (caratteristica) e BluetoothGattDescriptor (descrittore). La connessione a un dispositivo BLE inizia chiamando BluetoothDevice.connectGatt() — questo metodo restituisce un BluetoothGatt attraverso il quale vengono eseguite tutte le operazioni successive. Tutti i callback GATT arrivano in BluetoothGattCallback — questa è un'interfaccia asincrona che viene chiamata nello stesso thread in cui è stato creato BluetoothGatt. Importante: tutte le operazioni GATT devono essere eseguite sequenzialmente — chiamare più operazioni contemporaneamente sullo stesso BluetoothGatt causa errori.

Ciclo di vita della connessione GATT

La corretta gestione del ciclo di vita della connessione GATT è fondamentale per la stabilità dell'app BLE. Dopo aver chiamato connectGatt(), l'app attende il callback onConnectionStateChange() con lo stato STATE_CONNECTED. Quindi, il sistema avvia automaticamente Service Discovery, dopo il completamento del quale viene chiamato onServicesDiscovered(). Solo dopo puoi eseguire letture, scritture e iscrizioni. Al termine, chiama sempre gatt.close() in onDestroy() o onPause() — le connessioni GATT non chiuse consumano batteria e possono bloccare la riconnessione allo stesso dispositivo su Android.

// Connetti al dispositivo BLE tramite GATT
private val gattCallback = object : BluetoothGattCallback() {
    override fun onConnectionStateChange(
        gatt: BluetoothGatt, status: Int, newState: Int
    ) {
        if (newState == BluetoothProfile.STATE_CONNECTED) {
            gatt.discoverServices()
        }
    }

    override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
        val service = gatt.getService(UUID.fromString("180D"))
        val characteristic = service?.getCharacteristic(
            UUID.fromString("2A37")
        )
        characteristic?.let { enableNotifications(gatt, it) }
    }
}

Profili e servizi GATT standard

Bluetooth SIG definisce decine di profili e servizi GATT standard con UUID a 16 bit fissi. I più comuni: Battery Service (UUID 180F, caratteristica Battery Level 2A19), servizio Heart Rate (UUID 180D, caratteristica Heart Rate Measurement 2A37), servizio Device Information (UUID 180A, caratteristiche Manufacturer Name e Serial Number). L'uso di servizi standard garantisce la compatibilità tra dispositivi di diversi produttori — qualsiasi braccialetto fitness con un servizio Heart Rate dovrebbe funzionare con qualsiasi app Android che lo supporti.

Progettazione di servizi GATT personalizzati

Se i servizi standard non coprono il compito, lo sviluppatore può creare servizi GATT personalizzati con UUID a 128 bit. Nella progettazione di un servizio personalizzato, è necessario: definire un gruppo logico di caratteristiche (ad esempio, “Servizio di Controllo Serratura”), assegnare a ciascuna caratteristica le proprietà corrette (Read, Write, Notify), definire i valori consentiti e le unità di misura tramite il descrittore Characteristic Presentation Format. Per protocolli complessi, si consiglia di includere una caratteristica Command con proprietà Write e una caratteristica Status con Notify — questo segue il pattern Command/Status adottato nelle applicazioni BLE industriali.

// Crea servizio GATT personalizzato (Android come Server GATT)
private fun createCustomService(): BluetoothGattService {
    val serviceUuid = UUID.fromString("12345678-1234-5678-1234-56789abcdef0")
    val service = BluetoothGattService(
        serviceUuid, BluetoothGattService.SERVICE_TYPE_PRIMARY
    )

    val charUuid = UUID.fromString("12345678-1234-5678-1234-56789abcdef1")
    val characteristic = BluetoothGattCharacteristic(
        charUuid,
        BluetoothGattCharacteristic.PROPERTY_READ or
        BluetoothGattCharacteristic.PROPERTY_NOTIFY,
        BluetoothGattCharacteristic.PERMISSION_READ
    )
    service.addCharacteristic(characteristic)
    return service
}