11.10. Agire come central#

L’altro lato della conversazione e il central – il dispositivo che esegue la scansione delle periferiche in advertising, ne sceglie una con cui parlare, apre una connessione, percorre il database GATT remoto e legge o si iscrive alle caratteristiche su di esso. Una camera che raccoglie letture da un sensore indossabile, ascolta un beacon o parla con un microcontrollore companion e un central.

Il pattern del central in aioble si snoda attraverso quattro fasi: scansione, connessione, scoperta, operazione.

11.10.1. Scansione#

aioble.scan() restituisce un context manager asincrono che funge anche da iteratore asincrono sui dispositivi scoperti. L’uso tipico e eseguire la scansione finche non compare un dispositivo di interesse, poi uscire dall’iterazione:

import aioble
import asyncio
import bluetooth

HR_SERVICE = bluetooth.UUID(0x180D)

async def find_heart_rate():
    async with aioble.scan(duration_ms=5000, active=True) as scanner:
        async for result in scanner:
            if HR_SERVICE in result.services():
                return result.device
    return None

duration_ms=5000 limita la durata della scansione; duration_ms=0 esegue la scansione all’infinito (finche il context manager non esce). active=True richiede le scan response, che raddoppiano la dimensione del payload per dispositivo al costo di una piccola trasmissione aggiuntiva da entrambi i lati. I restanti argomenti keyword interval_us / window_us regolano il duty cycle radio dello scanner stesso e raramente vengono modificati rispetto ai valori predefiniti.

Ogni aioble.ScanResult espone l’indirizzo del dispositivo, l’ultimo RSSI, i byte grezzi di advertising e di scan response, e helper che effettuano il parsing dei campi standard:

  • result.device – un aioble.Device pronto per chiamarvi connect().

  • result.rssi – indicatore di intensita del segnale ricevuto in dBm, utile per la logica «scegli il piu vicino».

  • result.name() – la stringa del nome locale, oppure None se non viene pubblicizzata.

  • result.services() – un generatore di bluetooth.UUID per ogni servizio che il dispositivo pubblicizza.

  • result.manufacturer() – un generatore di tuple (company_id, data) per i campi specifici del produttore.

  • result.connectable – indica se l’advertisement piu recente era connettibile.

Lo stesso ScanResult viene ri-emesso man mano che arrivano nuovi dati di advertising per lo stesso dispositivo, cosi che un listener passivo che vuole semplicemente tracciare i dispositivi a tempo indefinito possa eseguire l’iteratore asincrono all’infinito e smistare a ogni evento.

11.10.2. Connessione#

Una volta identificato un dispositivo target, aprire una connessione e un singolo await

async def talk_to(device):
    connection = await device.connect()           # 10 s timeout
    async with connection:
        # ... do GATT work ...
        pass

aioble.Device.connect() accetta timeout_ms (quanto attendere che la connessione si stabilisca; predefinito 10 s) e min_conn_interval_us / max_conn_interval_us (l’intervallo richiesto di connection interval da Connessioni).

11.10.2.1. Riconnettersi a un peer noto senza scansione#

Una volta che esiste un bond con un peer, l’indirizzo e gia noto e un altro giro di scansione-e-scelta e tempo radio sprecato. Costruisci direttamente un aioble.Device con l’indirizzo salvato e salta direttamente a connect()

import aioble

KITCHEN_CAM = aioble.Device(aioble.ADDR_PUBLIC,
                            "aa:bb:cc:dd:ee:ff")

async def talk_to_kitchen():
    async with await KITCHEN_CAM.connect() as connection:
        # ... GATT work ...
        pass

Il primo argomento e uno tra aioble.ADDR_PUBLIC (l’indirizzo di fabbrica di un controller) o aioble.ADDR_RANDOM (un indirizzo privato statico generato o risolvibile); il secondo e o un valore bytes di sei byte o una stringa esadecimale separata da due punti. Gli attributi addr_type e addr di qualsiasi Device (ad esempio uno ottenuto in precedenza da un ScanResult) possono essere persistiti e reimmessi qui.

La aioble.DeviceConnection restituita e cio a cui si appende il resto del lavoro del central. async with garantisce che la connessione venga chiusa all’uscita dal blocco – in caso di successo, di cancellazione o di qualsiasi eccezione, inclusa aioble.DeviceDisconnectedError dovuta alla scomparsa del peer.

Se il central ha bisogno di un valore di caratteristica piu grande di quanto consenta l’MTU predefinito di 23 byte, questo e il punto in cui negoziarlo:

await connection.exchange_mtu(512)

(exchange_mtu() restituisce l’MTU effettivamente negoziato, che e il minimo tra il valore richiesto e quanto il peer supporta.)

11.10.3. Scoperta#

La scoperta percorre il database GATT remoto per trovare i servizi e le caratteristiche tramite i loro UUID. Ne esistono due varianti: mirata (conosci l’UUID e vuoi una cosa specifica) ed esaustiva (vuoi tutto).

Mirata – il caso comune:

service = await connection.service(HR_SERVICE)
if service is None:
    return                                        # no such service

char = await service.characteristic(HR_MEASUREMENT)
if char is None:
    return                                        # no such characteristic

aioble.DeviceConnection.service() e aioble.ClientService.characteristic() accettano ciascuna un bluetooth.UUID e restituiscono l’oggetto corrispondente (oppure None). Entrambe hanno un keyword timeout_ms per scoperta che ha come predefinito 2 s.

Esaustiva:

async for service in connection.services():
    print("service:", service.uuid)
    async for char in service.characteristics():
        print("  characteristic:", char.uuid, "properties:", hex(char.properties))

Questo e cio che fanno le app generiche di esplorazione Bluetooth – utile per lo sviluppo, meno per il codice di produzione che conosce gia quali UUID si aspetta.

11.10.3.1. Ispezionare cosa supporta una caratteristica#

La scoperta restituisce la bitmask delle proprieta GATT che il peer ha pubblicizzato per ciascuna caratteristica come properties. I bit sono quelli definiti dal GATT – read (0x02), write-without-response (0x04), write (0x08), notify (0x10), indicate (0x20) e affini. Ispezionare la bitmask prima di emettere un’operazione permette a un client generico di adattarsi a caratteristiche le cui capacita non conosce in anticipo:

_PROP_READ = const(0x02)
_PROP_NOTIFY = const(0x10)

char = await service.characteristic(STATUS_UUID)
if char.properties & _PROP_NOTIFY:
    await char.subscribe(notify=True)
    value = await char.notified()
elif char.properties & _PROP_READ:
    value = await char.read()
else:
    value = None                                  # nothing the client can do

Il codice di produzione che gia conosce il profilo GATT del peer di solito non ne ha bisogno – gli UUID erano documentati fin dall’inizio. I client generici / esplorativi (una pagina di impostazioni che percorre un dispositivo sconosciuto, un host di plugin) vi si appoggiano.

11.10.4. Operazione#

Una volta che il central detiene una ClientCharacteristic, ogni operazione GATT e una singola chiamata a coroutine:

  • Read. Emetti una lettura GATT e ottieni indietro il valore:

    value = await char.read()
print("value:", value)

    Le letture lunghe (valori piu grandi dell’MTU) vengono gestite in modo trasparente.

  • Write. Invia un nuovo valore al server:

    await char.write(b"\\x01")

    response=True attende una write-response e solleva aioble.GattError se il server rifiuta la scrittura. response=False e una write-without-response: fire-and-forget. response=None (il predefinito) sceglie automaticamente in base a cio che il peer ha pubblicizzato.

  • Subscribe. Abilita le notifiche o le indicazioni scrivendo nel CCCD della caratteristica:

    await char.subscribe(notify=True)

    Dopo che questo ritorna, il central puo attendere i push in arrivo.

  • Notified / indicated. Attendi il prossimo push dal server:

    while True:
    data = await char.notified()
    print("push:", data)

    timeout_ms=None (il predefinito) attende all’infinito; passa un intero in millisecondi per rinunciare dopo un certo tempo.

Mettere insieme i quattro produce il programma central canonico «connetti, iscriviti, trasmetti»:

async def stream_heart_rate():
    async with aioble.scan(duration_ms=5000, active=True) as scanner:
        async for result in scanner:
            if HR_SERVICE in result.services():
                device = result.device
                break
        else:
            return

    async with await device.connect() as connection:
        service = await connection.service(HR_SERVICE)
        char = await service.characteristic(HR_MEASUREMENT)
        await char.subscribe(notify=True)
        while connection.is_connected():
            data = await char.notified()
            print("hr push:", data)

asyncio.run(stream_heart_rate())

L’intera cosa e lunga circa una dozzina di righe e copre il flusso da «nessun Bluetooth in esecuzione» a «dati in streaming dal vivo». L’iteratore di scansione corrisponde al pattern broadcaster/observer, connect apre la connessione GAP, service / characteristic percorre l’albero GATT, subscribe scrive il CCCD e notified attende i push.

11.10.5. Disconnessioni e riconnessione#

Qualsiasi cosa accada al collegamento radio affiora nella coroutine che era in attesa su di esso. aioble.DeviceDisconnectedError e il segnale che il peer e scomparso o che e scattato il supervision timeout; l’eccezione termina qualunque chiamata a read(), write() o notified() fosse in corso, e qualsiasi blocco async with connection esce in modo pulito.

Un central che deve riconnettersi in caso di perdita avvolge il lavoro nel proprio loop esterno:

async def keep_streaming():
    while True:
        try:
            await stream_heart_rate()
        except aioble.DeviceDisconnectedError:
            print("disconnected, retrying...")
            await asyncio.sleep(2)

11.10.5.1. Racchiudere una sequenza con timeout()#

Quando diverse operazioni GATT consecutive devono completarsi tutte entro un unico budget – e non ciascuna individualmente con il proprio timeout_ms – usa aioble.DeviceConnection.timeout() per avvolgerle. Il context manager restituito annulla il proprio corpo se il budget si esaurisce (sollevando asyncio.TimeoutError) o se il peer si disconnette (sollevando aioble.DeviceDisconnectedError):

async with await device.connect() as connection:
    try:
        with connection.timeout(2000):                    # 2 s for the whole block
            service = await connection.service(HR_SERVICE)
            char = await service.characteristic(HR_MEASUREMENT)
            await char.subscribe(notify=True)
    except asyncio.TimeoutError:
        print("discovery + subscribe took too long")

Questa e l’alternativa piu pulita all’avvolgere ogni chiamata individualmente in asyncio.wait_for() ed evita successi spuri in cui ogni chiamata rispetta la propria scadenza ma la sequenza nel suo complesso sfora. Passare timeout_ms=None a timeout() disabilita la scadenza e lascia attiva solo la protezione dalla disconnessione.