`ubluepy` — periferic și central Bluetooth LE#

Modulul ubluepy este vechea API Bluetooth LE livrată cu portul nRF al MicroPython. Este modelat în linii mari după biblioteca Python Linux bluepy și se află direct deasupra Nordic SoftDevice — nu există un back-end portabil, așa că modulul este disponibil doar pe ținte Nordic (Arduino Nano 33 BLE Sense din gama OpenMV). Noile API-uri bluetooth / aioble nu sunt activate în acest build, deci ubluepy este singura modalitate de a controla radioul integrat în cip.

Setul de funcționalități disponibile depinde de SoftDevice-ul scris în firmware:

s140 (Nano 33 BLE Sense) — atât rolul de periferic cât și cel de central (scaner). Acesta este cel livrat cu firmware-ul OpenMV.
s132 — atât periferic, cât și central.
s110 — doar periferic; metodele de scanare / conectare sunt excluse la compilare.

Exemplu de periferic#

Anunță-te ca periferic Bluetooth LE cu un singur serviciu de detectare a mediului și notifică o caracteristică de temperatură la fiecare scriere în Client Characteristic Configuration Descriptor (CCCD) al acesteia:

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])

Exemplu central#

Scanează dispozitivele care fac advertising din apropiere timp de 100 ms și decodează datele de advertising ale fiecărui 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))

Conținutul modulului#

Clase#

class ubluepy.UUID(value)#

Construiește un UUID Bluetooth pe 16 sau 128 de biți.

value

Una dintre:

int — un UUID numeric pe 16 biți (UUID(0x180A)).
șir de 6 caractere "0xXXXX" — un UUID pe 16 biți, de exemplu UUID("0x181A").
șir de 36 de caractere "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" — un UUID complet pe 128 de biți. Partea specifică furnizorului este înregistrată cu SoftDevice-ul la construire.
O altă instanță UUID — realizează o copie.

Orice altă lungime generează ValueError("Invalid UUID string length").

binVal() → int#: Returnează cei mai puțin semnificativi 16 biți ai UUID-ului ca int. Pentru UUID-urile pe 128 de biți se returnează doar câmpul de 16 biți încorporat în UUID-ul specific furnizorului (valoarea completă pe 128 de biți este accesibilă numai prin indexul specific furnizorului al SoftDevice-ului).

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

Definește un serviciu GATT care va fi înregistrat cu SoftDevice-ul atunci când este adăugat la un Peripheral.

uuid: O instanță UUID. Transmiterea unui obiect care nu este UUID generează ValueError.
type: Fie Service.PRIMARY (implicit), fie Service.SECONDARY. Alte valori generează ValueError.

uuid() → UUID#: Returnează instanța UUID a serviciului.

addCharacteristic(characteristic: Characteristic) → None#: Înregistrează o Characteristic în serviciu. Handle-ul GATT al caracteristicii este atribuit în timpul acestui apel.

getCharacteristic(uuid: UUID) → Characteristic | None#: Caută după UUID o Characteristic adăugată anterior. Returnează instanța caracteristicii sau None dacă nu se găsește nicio potrivire.

getCharacteristics() → list#: Returnează lista tuturor caracteristicilor adăugate serviciului.

PRIMARY: int#: Constantă de tip de serviciu pentru servicii primare (1).

SECONDARY: int#: Constantă de tip de serviciu pentru servicii secundare (2).

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

Definește o caracteristică GATT. Adaug-o la un Service cu Service.addCharacteristic() înainte ca Peripheral-ul părinte să înceapă advertising-ul.

uuid: O instanță UUID.
props (doar cuvânt-cheie): Mască de biți cu una sau mai multe valori Characteristic.PROP_* care descriu ce operații suportă caracteristica.
attrs (doar cuvânt-cheie): Mască de biți cu atribute GATT suplimentare. Folosiți Characteristic.ATTR_CCCD pentru a atașa un Client Characteristic Configuration Descriptor — necesar pentru a face să funcționeze caracteristicile PROP_NOTIFY / PROP_INDICATE.

uuid() → UUID#: Returnează instanța UUID a caracteristicii.

properties() → int#: Returnează masca de biți props setată la momentul construirii.

read() → bytearray#: Numai rolul central. Citește valoarea caracteristicii de la peer-ul conectat. Returnează un bytearray cu cea mai recentă valoare. Pe un periferic aceasta nu face nimic și returnează None.

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

Scrie în caracteristică.

Pe un periferic, dacă PROP_NOTIFY este setat în proprietățile caracteristicii, valoarea este trimisă ca notificare GATT către centralul conectat; în caz contrar, valoarea atributului local este actualizată.
Pe un central, valoarea este scrisă în peer-ul de la distanță. Setați with_response=True pentru a emite o cerere de scriere și a aștepta confirmarea peer-ului în loc de o comandă de scriere.

data este orice obiect compatibil cu protocolul buffer (bytes, bytearray, memoryview).

PROP_BROADCAST: int#: Caracteristica își poate difuza valoarea (0x01).

PROP_READ: int#: Caracteristica suportă citiri (0x02).

PROP_WRITE_WO_RESP: int#: Caracteristica suportă scrieri fără răspuns (0x04).

PROP_WRITE: int#: Caracteristica suportă scrieri cu răspuns (0x08).

PROP_NOTIFY: int#: Caracteristica poate trimite notificări către un central abonat (0x10).

PROP_INDICATE: int#: Caracteristica poate trimite indicații (notificări confirmate) către un central abonat (0x20).

PROP_AUTH_SIGNED_WR: int#: Caracteristica suportă scrieri semnate autentificate (0x40).

ATTR_CCCD: int#: Adaugă caracteristicii un Client Characteristic Configuration Descriptor (0x01). Necesar pentru ca clienții să se poată abona la notificări/indicații.

class ubluepy.Descriptor(uuid: UUID)#: Clasă stub pentru reprezentarea descriptorilor GATT. Implementarea actuală stochează doar UUID-ul și nu expune nicio metodă — este furnizată pentru compatibilitatea ulterioară cu viitoarele revizii ale modulului.

class ubluepy.Peripheral#

Dispozitivul Bluetooth LE local. Aceeași clasă este folosită atât pentru rolul de periferic, cât și pentru cel de central; rolul este selectat de metodele pe care le apelați (advertise() selectează perifericul, connect() selectează centralul).

addService(service: Service) → None#: Înregistrează un Service (și toate caracteristicile adăugate anterior la acesta) cu serverul GATT local.

getServices() → list#: Returnează lista serviciilor înregistrate în prezent cu acest Peripheral.

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

Începe advertising-ul în rolul de periferic.

device_name: Numele local complet anunțat în payload-ul GAP.
services: Lista instanțelor Service de anunțat. UUID-ul fiecărui serviciu este inclus în advertising.
data: Payload brut opțional de advertising (bytes / bytearray) atașat antetului generat automat. Folosiți acest lucru pentru payload-uri specifice furnizorului sau de tip beacon, cum ar fi Eddystone.
connectable: Când este True (implicit), anunță ca dispozitiv conectabil și înregistrează gestionari de evenimente GAP / GATTS, astfel încât funcția de retroapelare (callback) configurată prin setConnectionHandler() să se declanșeze la conectare, deconectare și scrieri CCCD. Când este False, anunță ca beacon — niciun gestionar nu este atașat, iar dispozitivul nu poate fi conectat.

advertise_stop() → None#: Oprește orice advertising în curs de desfășurare.

setConnectionHandler(func) → None#: Înregistrează o funcție de retroapelare (callback) invocată la evenimente GAP și GATTS. Funcția de retroapelare este apelată ca func(event_id, conn_handle, data), unde event_id este una dintre valorile constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED sau constants.EVT_GATTS_WRITE, conn_handle este handle-ul de conexiune SoftDevice (sau handle-ul de atribut pentru scrierile GATTS), iar data este payload-ul brut al evenimentului sub forma unui bytearray (sau None pentru conectare / deconectare).

setNotificationHandler(func) → None#: Înregistrează o funcție de retroapelare (callback) pentru evenimentele de notificare primite în rolul de central.

withDelegate(delegate: DefaultDelegate) → None#: Atașează o instanță DefaultDelegate pentru a primi evenimente GATT decodate.

disconnect() → None#: Întrerupe conexiunea activă (în prezent un stub care nu face nimic în acest build).

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

Numai rolul central. Se conectează la peer-ul cu adresa dată și descoperă sincron serviciile și caracteristicile sale primare. Blochează până când conexiunea este stabilită și descoperirea se finalizează; serviciile descoperite sunt apoi disponibile prin getServices().

addr: Adresa peer-ului sub forma unui șir de 17 caractere "xx:xx:xx:xx:xx:xx" (de exemplu, preluată din ScanEntry.addr()).
addr_type (doar cuvânt-cheie): Fie constants.ADDR_TYPE_PUBLIC (implicit), fie constants.ADDR_TYPE_RANDOM_STATIC.

class ubluepy.Scanner#

Observator GAP pentru descoperirea dispozitivelor din apropiere care fac advertising. Disponibil numai atunci când firmware-ul este construit cu un SoftDevice cu suport pentru rolul central (s132 / s140).

scan(timeout: int) → list#: Rulează o scanare pasivă timp de timeout milisecunde și returnează o listă de instanțe ScanEntry — una pentru fiecare raport de advertising primit în timpul ferestrei.

class ubluepy.ScanEntry#

Un singur raport de advertising capturat de Scanner.scan(). Instanțele sunt returnate de scaner — nu există un constructor public.

addr() → str#: Returnează adresa peer-ului sub forma unui șir de 17 caractere "xx:xx:xx:xx:xx:xx".

addr_type() → int#: Returnează tipul adresei peer-ului (constants.ADDR_TYPE_PUBLIC sau constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int#: Returnează indicatorul de putere a semnalului în dBm.

getScanData() → list#: Decodează payload-ul de advertising într-o listă de tupluri (ad_type, description, value). ad_type este octetul numeric al tipului AD (consultați constants.ad_types), description este numele constantei corespunzătoare sub formă de șir (sau None dacă tipul este necunoscut), iar value este corpul înregistrării AD sub forma unui bytearray.

class ubluepy.DefaultDelegate#

Clasă de bază pentru obiectele transmise către Peripheral.withDelegate(). Creați o subclasă a acesteia și suprascrieți handleConnection() / handleNotification() pentru a reacționa la evenimente GATT.

handleConnection() → None#: Apelată la evenimente GAP de conectare / deconectare. Implementarea implicită este goală.

handleNotification() → None#: Apelată la notificările GATT primite. Implementarea implicită este goală.

Constante#

Atributul constants al modulului este un spațiu de nume care conține identificatori de evenimente GAP/GATT, valori de tip de adresă și spațiul de nume imbricat ad_types.

ubluepy.constants: type#: Container care expune constantele de mai jos.

constants.EVT_GAP_CONNECTED: int#: Valoarea event_id a gestionarului de conexiune al Peripheral pentru conectare GAP (16).

constants.EVT_GAP_DISCONNECTED: int#: Valoarea event_id a gestionarului de conexiune al Peripheral pentru deconectare GAP (17).

constants.EVT_GATTS_WRITE: int#: Valoarea event_id a gestionarului de conexiune al Peripheral pentru o scriere într-un atribut GATT local, inclusiv scrieri într-un CCCD care activează/dezactivează notificările (80).

constants.UUID_CCCD: int#: UUID Bluetooth standard pentru Client Characteristic Configuration Descriptor (0x2902).

constants.ADDR_TYPE_PUBLIC: int#: Adresă publică de dispozitiv Bluetooth (0).

constants.ADDR_TYPE_RANDOM_STATIC: int#: Adresă aleatorie statică de dispozitiv Bluetooth (1).

constants.ad_types: type#

Spațiu de nume al constantelor de tip AD pentru datele de advertising din Bluetooth Core Specification Supplement. Fiecare nume se mapează la tipul AD corespunzător de 1 octet:

Nume	Valoare
`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 — periferic și central Bluetooth LE#