`ubluepy` — periferica e centrale Bluetooth LE¶

Il modulo ubluepy è la vecchia API Bluetooth LE distribuita con il port nRF di MicroPython. È modellato approssimativamente sulla libreria Python Linux bluepy e si appoggia direttamente sul SoftDevice Nordic — non esiste alcun back-end portabile, quindi il modulo è disponibile solo sui target Nordic (l’Arduino Nano 33 BLE Sense nella gamma OpenMV). Le più recenti API bluetooth / aioble non sono abilitate in questa build, quindi ubluepy è l’unico modo per pilotare la radio integrata nel chip.

L’insieme di funzionalità disponibili dipende dal SoftDevice flashato dal firmware:

s140 (Nano 33 BLE Sense) — entrambi i ruoli, periferica e centrale (scanner). È quanto distribuisce il firmware OpenMV.
s132 — sia periferica che centrale.
s110 — solo periferica; i metodi scanner / connect sono esclusi dalla compilazione.

Esempio di periferica¶

Pubblicizza il dispositivo come periferica Bluetooth LE con un singolo servizio di rilevamento ambientale e notifica una caratteristica di temperatura a ogni scrittura sul suo Client Characteristic Configuration Descriptor (CCCD):

from ubluepy import Service, Characteristic, UUID, Peripheral, constants
from machine import LED

notif_enabled = False

def event_handler(event_id, handle, data):
    global notif_enabled
    if event_id == constants.EVT_GAP_CONNECTED:
        LED("LED_GREEN").on()
    elif event_id == constants.EVT_GAP_DISCONNECTED:
        LED("LED_GREEN").off()
        periph.advertise(device_name="Nano 33", services=[svc])
    elif event_id == constants.EVT_GATTS_WRITE:
        notif_enabled = bool(data[0])

svc = Service(UUID("181A"))            # Environmental Sensing
char = Characteristic(UUID("2A6E"),
                      props=Characteristic.PROP_NOTIFY | Characteristic.PROP_READ,
                      attrs=Characteristic.ATTR_CCCD)
svc.addCharacteristic(char)

periph = Peripheral()
periph.addService(svc)
periph.setConnectionHandler(event_handler)
periph.advertise(device_name="Nano 33", services=[svc])

Esempio di centrale¶

Esegue la scansione dei dispositivi in advertising nelle vicinanze per 100 ms e decodifica i dati di advertising di ciascun ScanEntry

from ubluepy import Scanner, constants

s = Scanner()
for entry in s.scan(100):
    print(entry.addr(), entry.rssi(), "dBm")
    for ad_type, name, value in entry.getScanData():
        print(" ", ad_type, name, bytes(value))

Contenuto del modulo¶

Classi¶

class ubluepy.UUID(value)¶

Costruisce un UUID Bluetooth a 16 o 128 bit.

value

Uno tra:

int — un UUID numerico a 16 bit (UUID(0x180A)).
Stringa "0xXXXX" di 6 caratteri — un UUID a 16 bit, ad esempio UUID("0x181A").
Stringa "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" di 36 caratteri — un UUID completo a 128 bit. La porzione specifica del vendor viene registrata con il SoftDevice al momento della costruzione.
Un’altra istanza UUID — esegue una copia.

Qualsiasi altra lunghezza solleva ValueError("Invalid UUID string length").

binVal() → int¶: Restituisce i 16 bit meno significativi dell’UUID come int. Per gli UUID a 128 bit viene restituito solo il campo a 16 bit incorporato nell’UUID specifico del vendor (il valore completo a 128 bit è accessibile solo tramite l’indice specifico del vendor del SoftDevice).

class ubluepy.Service(uuid: UUID, type: int = Service.PRIMARY)¶

Definisce un servizio GATT che verrà registrato con il SoftDevice quando viene aggiunto a un Peripheral.

uuid: Un’istanza UUID. Passare un oggetto non UUID solleva ValueError.
type: Uno tra Service.PRIMARY (predefinito) o Service.SECONDARY. Altri valori sollevano ValueError.

uuid() → UUID¶: Restituisce l’istanza UUID del servizio.

addCharacteristic(characteristic: Characteristic) → None¶: Registra una Characteristic con il servizio. L’handle GATT della caratteristica viene assegnato durante questa chiamata.

getCharacteristic(uuid: UUID) → Characteristic | None¶: Cerca per UUID una Characteristic precedentemente aggiunta. Restituisce l’istanza della caratteristica, oppure None se non viene trovata alcuna corrispondenza.

getCharacteristics() → list¶: Restituisce l’elenco di tutte le caratteristiche aggiunte al servizio.

PRIMARY: int¶: Costante di tipo servizio per i servizi primari (1).

SECONDARY: int¶: Costante di tipo servizio per i servizi secondari (2).

class ubluepy.Characteristic(uuid: UUID, *, props: int = PROP_READ | PROP_WRITE, attrs: int = 0)¶

Definisce una caratteristica GATT. Aggiungila a un Service con Service.addCharacteristic() prima che il Peripheral genitore inizi l’advertising.

uuid: Un’istanza UUID.
props (solo keyword): Maschera di bit di uno o più valori Characteristic.PROP_* che descrivono quali operazioni la caratteristica supporta.
attrs (solo keyword): Maschera di bit di attributi GATT aggiuntivi. Usa Characteristic.ATTR_CCCD per associare un Client Characteristic Configuration Descriptor — necessario per far funzionare le caratteristiche PROP_NOTIFY / PROP_INDICATE.

uuid() → UUID¶: Restituisce l’istanza UUID della caratteristica.

properties() → int¶: Restituisce la maschera di bit props impostata al momento della costruzione.

read() → bytearray¶: Solo ruolo centrale. Legge il valore della caratteristica dal peer connesso. Restituisce un bytearray con il valore più recente. Su una periferica è un’operazione nulla e restituisce None.

write(data, *, with_response: bool = False) → None¶

Scrive sulla caratteristica.

Su una periferica, se PROP_NOTIFY è impostato nelle proprietà della caratteristica, il valore viene inviato come notifica GATT alla centrale connessa; altrimenti viene aggiornato il valore dell’attributo locale.
Su una centrale, il valore viene scritto sul peer remoto. Imposta with_response=True per emettere una richiesta di scrittura e attendere la conferma del peer invece di un comando di scrittura.

data è qualsiasi oggetto conforme al buffer protocol (bytes, bytearray, memoryview).

PROP_BROADCAST: int¶: La caratteristica può trasmettere in broadcast il proprio valore (0x01).

PROP_READ: int¶: La caratteristica supporta le letture (0x02).

PROP_WRITE_WO_RESP: int¶: La caratteristica supporta le scritture senza risposta (0x04).

PROP_WRITE: int¶: La caratteristica supporta le scritture con risposta (0x08).

PROP_NOTIFY: int¶: La caratteristica può inviare notifiche a una centrale sottoscritta (0x10).

PROP_INDICATE: int¶: La caratteristica può inviare indicazioni (notifiche con conferma) a una centrale sottoscritta (0x20).

PROP_AUTH_SIGNED_WR: int¶: La caratteristica supporta scritture firmate autenticate (0x40).

ATTR_CCCD: int¶: Aggiunge un Client Characteristic Configuration Descriptor alla caratteristica (0x01). Necessario affinché i client possano sottoscriversi a notifiche/indicazioni.

class ubluepy.Descriptor(uuid: UUID)¶: Classe stub per rappresentare i descrittori GATT. L’implementazione attuale si limita a memorizzare l’UUID e non espone alcun metodo — è fornita per compatibilità futura con revisioni successive del modulo.

class ubluepy.Peripheral¶

Il dispositivo Bluetooth LE locale. La stessa classe viene usata sia per il ruolo di periferica che per quello di centrale; il ruolo è selezionato in base ai metodi che si chiamano (advertise() seleziona la periferica, connect() seleziona la centrale).

addService(service: Service) → None¶: Registra un Service (e tutte le caratteristiche precedentemente aggiunte ad esso) con il server GATT locale.

getServices() → list¶: Restituisce l’elenco dei servizi attualmente registrati con questo Peripheral.

advertise(*, device_name: str | None = None, services: list | None = None, data: bytes | None = None, connectable: bool = True) → None¶

Avvia l’advertising nel ruolo di periferica.

device_name: Nome locale completo pubblicizzato nel payload GAP.
services: Elenco di istanze Service da pubblicizzare. L’UUID di ciascun servizio è incluso nell’advertising.
data: Payload di advertising raw opzionale (bytes / bytearray) accodato all’header generato automaticamente. Usalo per payload specifici del vendor o per beacon come Eddystone.
connectable: Quando è True (predefinito), pubblicizza il dispositivo come connettibile e registra i gestori di eventi GAP / GATTS in modo che il callback configurato con setConnectionHandler() venga invocato in caso di connessione, disconnessione e scritture CCCD. Quando è False, pubblicizza il dispositivo come beacon — non viene associato alcun gestore e il dispositivo non può essere connesso.

advertise_stop() → None¶: Interrompe qualsiasi advertising in corso.

setConnectionHandler(func) → None¶: Registra un callback invocato in caso di eventi GAP e GATTS. Il callback viene chiamato come func(event_id, conn_handle, data) dove event_id è uno tra i valori constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED o constants.EVT_GATTS_WRITE, conn_handle è l’handle di connessione del SoftDevice (o l’handle di attributo per le scritture GATTS) e data è il payload raw dell’evento come bytearray (oppure None per connessione / disconnessione).

setNotificationHandler(func) → None¶: Registra un callback per gli eventi di notifica ricevuti nel ruolo di centrale.

withDelegate(delegate: DefaultDelegate) → None¶: Associa un’istanza DefaultDelegate per ricevere gli eventi GATT decodificati.

disconnect() → None¶: Chiude la connessione attiva (attualmente uno stub a operazione nulla in questa build).

connect(addr, *, addr_type: int = constants.ADDR_TYPE_PUBLIC) → None¶

Solo ruolo centrale. Si connette al peer con l’indirizzo indicato e ne scopre in modo sincrono i servizi primari e le caratteristiche. Si blocca finché la connessione non è stabilita e la discovery non è completata; i servizi scoperti sono quindi disponibili tramite getServices().

addr: Indirizzo del peer come stringa "xx:xx:xx:xx:xx:xx" di 17 caratteri (ad esempio quella ottenuta da ScanEntry.addr()).
addr_type (solo keyword): Uno tra constants.ADDR_TYPE_PUBLIC (predefinito) o constants.ADDR_TYPE_RANDOM_STATIC.

class ubluepy.Scanner¶

Observer GAP per scoprire i dispositivi in advertising nelle vicinanze. Disponibile solo quando il firmware è compilato con un SoftDevice dotato di supporto centrale (s132 / s140).

scan(timeout: int) → list¶: Esegue una scansione passiva per timeout millisecondi e restituisce un elenco di istanze ScanEntry — una per ciascun report di advertising ricevuto durante la finestra.

class ubluepy.ScanEntry¶

Un singolo report di advertising catturato da Scanner.scan(). Le istanze vengono restituite dallo scanner — non esiste un costruttore pubblico.

addr() → str¶: Restituisce l’indirizzo del peer come stringa "xx:xx:xx:xx:xx:xx" di 17 caratteri.

addr_type() → int¶: Restituisce il tipo di indirizzo del peer (constants.ADDR_TYPE_PUBLIC o constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int¶: Restituisce l’indicatore di intensità del segnale in dBm.

getScanData() → list¶: Decodifica il payload di advertising in un elenco di tuple (ad_type, description, value). ad_type è il byte numerico del tipo AD (vedi constants.ad_types), description è il nome della costante corrispondente come stringa (oppure None se il tipo è sconosciuto) e value è il corpo del record AD come bytearray.

class ubluepy.DefaultDelegate¶

Classe base per gli oggetti passati a Peripheral.withDelegate(). Crea una sottoclasse ed esegui l’override di handleConnection() / handleNotification() per reagire agli eventi GATT.

handleConnection() → None¶: Chiamato in caso di eventi GAP di connessione / disconnessione. L’implementazione predefinita è vuota.

handleNotification() → None¶: Chiamato in caso di notifiche GATT in arrivo. L’implementazione predefinita è vuota.

Costanti¶

L’attributo constants del modulo è uno spazio dei nomi contenente gli identificatori degli eventi GAP/GATT, i valori di tipo indirizzo e lo spazio dei nomi annidato ad_types.

ubluepy.constants: type¶: Contenitore che espone le costanti elencate di seguito.

constants.EVT_GAP_CONNECTED: int¶: Valore di event_id del gestore di connessione di Peripheral per la connessione GAP (16).

constants.EVT_GAP_DISCONNECTED: int¶: Valore di event_id del gestore di connessione di Peripheral per la disconnessione GAP (17).

constants.EVT_GATTS_WRITE: int¶: Valore di event_id del gestore di connessione di Peripheral per una scrittura su un attributo GATT locale, incluse le scritture su un CCCD che abilitano/disabilitano le notifiche (80).

constants.UUID_CCCD: int¶: UUID Bluetooth standard per il Client Characteristic Configuration Descriptor (0x2902).

constants.ADDR_TYPE_PUBLIC: int¶: Indirizzo di dispositivo Bluetooth pubblico (0).

constants.ADDR_TYPE_RANDOM_STATIC: int¶: Indirizzo di dispositivo Bluetooth casuale statico (1).

constants.ad_types: type¶

Spazio dei nomi delle costanti di tipo AD per i dati di advertising tratte dal Bluetooth Core Specification Supplement. Ogni nome corrisponde al relativo tipo AD a 1 byte:

Nome	Valore
`AD_TYPE_FLAGS`	`0x01`
`AD_TYPE_16BIT_SERVICE_UUID_MORE_AVAILABLE`	`0x02`
`AD_TYPE_16BIT_SERVICE_UUID_COMPLETE`	`0x03`
`AD_TYPE_32BIT_SERVICE_UUID_MORE_AVAILABLE`	`0x04`
`AD_TYPE_32BIT_SERVICE_UUID_COMPLETE`	`0x05`
`AD_TYPE_128BIT_SERVICE_UUID_MORE_AVAILABLE`	`0x06`
`AD_TYPE_128BIT_SERVICE_UUID_COMPLETE`	`0x07`
`AD_TYPE_SHORT_LOCAL_NAME`	`0x08`
`AD_TYPE_COMPLETE_LOCAL_NAME`	`0x09`
`AD_TYPE_TX_POWER_LEVEL`	`0x0A`
`AD_TYPE_CLASS_OF_DEVICE`	`0x0D`
`AD_TYPE_SIMPLE_PAIRING_HASH_C`	`0x0E`
`AD_TYPE_SIMPLE_PAIRING_RANDOMIZER_R`	`0x0F`
`AD_TYPE_SECURITY_MANAGER_TK_VALUE`	`0x10`
`AD_TYPE_SECURITY_MANAGER_OOB_FLAGS`	`0x11`
`AD_TYPE_SLAVE_CONNECTION_INTERVAL_RANGE`	`0x12`
`AD_TYPE_SOLICITED_SERVICE_UUIDS_16BIT`	`0x14`
`AD_TYPE_SOLICITED_SERVICE_UUIDS_128BIT`	`0x15`
`AD_TYPE_SERVICE_DATA`	`0x16`
`AD_TYPE_PUBLIC_TARGET_ADDRESS`	`0x17`
`AD_TYPE_RANDOM_TARGET_ADDRESS`	`0x18`
`AD_TYPE_APPEARANCE`	`0x19`
`AD_TYPE_ADVERTISING_INTERVAL`	`0x1A`
`AD_TYPE_LE_BLUETOOTH_DEVICE_ADDRESS`	`0x1B`
`AD_TYPE_LE_ROLE`	`0x1C`
`AD_TYPE_SIMPLE_PAIRING_HASH_C256`	`0x1D`
`AD_TYPE_SIMPLE_PAIRING_RANDOMIZER_R256`	`0x1E`
`AD_TYPE_SERVICE_DATA_32BIT_UUID`	`0x20`
`AD_TYPE_SERVICE_DATA_128BIT_UUID`	`0x21`
`AD_TYPE_URI`	`0x24`
`AD_TYPE_3D_INFORMATION_DATA`	`0x3D`
`AD_TYPE_MANUFACTURER_SPECIFIC_DATA`	`0xFF`

ubluepy — periferica e centrale Bluetooth LE¶