`ubluepy` — Bluetooth LE periferija i centralni uređaj¶

Modul ubluepy je naslijeđeni Bluetooth LE API koji se isporučuje s MicroPython nRF portom. Labavo je modeliran prema Linux bluepy Python biblioteci i smješten je izravno na vrh Nordic SoftDevicea — ne postoji prenosivi back-end, pa je modul dostupan samo na Nordic ciljnim uređajima (Arduino Nano 33 BLE Sense u OpenMV ponudi). Noviji bluetooth / aioble API-ji nisu omogućeni u ovoj verziji, pa je ubluepy jedini način upravljanja radijem na čipu.

Dostupni skup značajki ovisi o SoftDeviceu koji je ugrađeni program (firmware) zapisao u flash memoriju:

s140 (Nano 33 BLE Sense) — obje uloge: periferija i centralni uređaj (skener). To je ono što OpenMV ugrađeni program (firmware) isporučuje.
s132 — i periferija i centralni uređaj.
s110 — samo periferija; metode skenera / povezivanja isključene su iz kompilacije.

Primjer periferije¶

Oglašavanje kao Bluetooth LE periferija s jednom uslugom za očitavanje okoline i obavještavanje o karakteristici temperature pri svakom upisu u njezin 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])

Primjer centralnog uređaja¶

Skeniranje obližnjih uređaja koji se oglašavaju tijekom 100 ms i dekodiranje podataka oglašavanja svakog 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))

Sadržaj modula¶

Klase¶

class ubluepy.UUID(value)¶

Konstruira 16-bitni ili 128-bitni Bluetooth UUID.

value

Jedno od:

int — 16-bitni numerički UUID (UUID(0x180A)).
6-znakovni "0xXXXX" string — 16-bitni UUID, npr. UUID("0x181A").
36-znakovni "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" string — potpuni 128-bitni UUID. Dio specifičan za proizvođača registrira se sa SoftDeviceom prilikom konstrukcije.
Druga instanca UUID — izvodi kopiranje.

Bilo koja druga duljina podiže ValueError("Invalid UUID string length").

binVal() → int¶: Vraća donjih 16 bitova UUID-a kao int. Za 128-bitne UUID-ove vraća se samo 16-bitno polje ugrađeno unutar UUID-a specifičnog za proizvođača (potpuna 128-bitna vrijednost dostupna je samo putem SoftDeviceovog indeksa specifičnog za proizvođača).

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

Definira GATT uslugu koja će biti registrirana sa SoftDeviceom kada se doda u Peripheral.

uuid: Instanca UUID. Prosljeđivanje objekta koji nije UUID podiže ValueError.
type: Ili Service.PRIMARY (zadano) ili Service.SECONDARY. Druge vrijednosti podižu ValueError.

uuid() → UUID¶: Vraća instancu UUID usluge.

addCharacteristic(characteristic: Characteristic) → None¶: Registrira Characteristic u uslugu. GATT identifikator karakteristike dodjeljuje se tijekom ovog poziva.

getCharacteristic(uuid: UUID) → Characteristic | None¶: Traži prethodno dodanu Characteristic po UUID-u. Vraća instancu karakteristike ili None ako nema podudaranja.

getCharacteristics() → list¶: Vraća popis svake karakteristike dodane u uslugu.

PRIMARY: int¶: Konstanta tipa usluge za primarne usluge (1).

SECONDARY: int¶: Konstanta tipa usluge za sekundarne usluge (2).

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

Definira GATT karakteristiku. Dodajte je u Service pomoću Service.addCharacteristic() prije nego što nadređena Peripheral počne oglašavanje.

uuid: Instanca UUID.
props (samo ključna riječ): Bitovna maska jedne ili više Characteristic.PROP_* vrijednosti koje opisuju koje operacije karakteristika podržava.
attrs (samo ključna riječ): Bitovna maska dodatnih GATT atributa. Koristite Characteristic.ATTR_CCCD za pridruživanje Client Characteristic Configuration Descriptora — potreban je da bi PROP_NOTIFY / PROP_INDICATE karakteristike radile.

uuid() → UUID¶: Vraća instancu UUID karakteristike.

properties() → int¶: Vraća bitovnu masku props postavljenu prilikom konstrukcije.

read() → bytearray¶: Samo uloga centralnog uređaja. Čita vrijednost karakteristike s povezanog ravnopravnog uređaja. Vraća bytearray s najnovijom vrijednošću. Na periferiji ovo nema učinka i vraća None.

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

Upisuje u karakteristiku.

Na periferiji, ako je PROP_NOTIFY postavljen u svojstvima karakteristike, vrijednost se šalje kao GATT obavijest povezanom centralnom uređaju; u suprotnom se ažurira lokalna vrijednost atributa.
Na centralnom uređaju, vrijednost se upisuje u udaljeni ravnopravni uređaj. Postavite with_response=True za izdavanje zahtjeva za upis i čekanje potvrde ravnopravnog uređaja umjesto naredbe za upis.

data je bilo koji objekt koji podržava buffer protokol (bytes, bytearray, memoryview).

PROP_BROADCAST: int¶: Karakteristika može emitirati svoju vrijednost (0x01).

PROP_READ: int¶: Karakteristika podržava čitanja (0x02).

PROP_WRITE_WO_RESP: int¶: Karakteristika podržava upise bez odgovora (0x04).

PROP_WRITE: int¶: Karakteristika podržava upise s odgovorom (0x08).

PROP_NOTIFY: int¶: Karakteristika može slati obavijesti pretplaćenom centralnom uređaju (0x10).

PROP_INDICATE: int¶: Karakteristika može slati indikacije (potvrđene obavijesti) pretplaćenom centralnom uređaju (0x20).

PROP_AUTH_SIGNED_WR: int¶: Karakteristika podržava autenticirane potpisane upise (0x40).

ATTR_CCCD: int¶: Dodaje Client Characteristic Configuration Descriptor karakteristici (0x01). Potreban je da bi se klijenti mogli pretplatiti na obavijesti/indikacije.

class ubluepy.Descriptor(uuid: UUID)¶: Stub klasa za predstavljanje GATT deskriptora. Trenutna implementacija pohranjuje samo UUID i ne izlaže nijednu metodu — pružena je radi buduće kompatibilnosti s budućim revizijama modula.

class ubluepy.Peripheral¶

Lokalni Bluetooth LE uređaj. Ista se klasa koristi za uloge periferije i centralnog uređaja; uloga se odabire prema tome koje metode pozivate (advertise() odabire periferiju, connect() odabire centralni uređaj).

addService(service: Service) → None¶: Registrira Service (i sve njezine prethodno dodane karakteristike) na lokalni GATT poslužitelj.

getServices() → list¶: Vraća popis usluga trenutno registriranih s ovom Peripheral.

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

Pokreće oglašavanje u ulozi periferije.

device_name: Potpuno lokalno ime oglašavano u GAP korisnom opterećenju.
services: Popis instanci Service koje treba oglasiti. UUID svake usluge uključen je u oglas.
data: Opcionalno sirovo korisno opterećenje oglasa (bytes / bytearray) pridruženo automatski generiranom zaglavlju. Koristite ovo za korisna opterećenja specifična za proizvođača ili beacon, poput Eddystonea.
connectable: Kada je True (zadano), oglašava se kao uređaj na koji se može povezati i registrira GAP / GATTS rukovatelje događajima tako da se konfigurirani setConnectionHandler() povratni poziv aktivira pri povezivanju, prekidu veze i upisima u CCCD. Kada je False, oglašava se kao beacon — ne pridružuju se rukovatelji i s uređajem se nije moguće povezati.

advertise_stop() → None¶: Zaustavlja sve oglašavanje u tijeku.

setConnectionHandler(func) → None¶: Registrira povratni poziv koji se poziva za GAP i GATTS događaje. Povratni poziv poziva se kao func(event_id, conn_handle, data) gdje je event_id jedna od vrijednosti constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED ili constants.EVT_GATTS_WRITE, conn_handle je SoftDeviceov identifikator veze (ili identifikator atributa za GATTS upise), a data je sirovo korisno opterećenje događaja kao bytearray (ili None za povezivanje / prekid veze).

setNotificationHandler(func) → None¶: Registrira povratni poziv za događaje obavijesti primljene u ulozi centralnog uređaja.

withDelegate(delegate: DefaultDelegate) → None¶: Pridružuje instancu DefaultDelegate za primanje dekodiranih GATT događaja.

disconnect() → None¶: Prekida aktivnu vezu (trenutno stub bez učinka u ovoj verziji).

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

Samo uloga centralnog uređaja. Povezuje se s ravnopravnim uređajem na zadanoj adresi i sinkrono otkriva njegove primarne usluge i karakteristike. Blokira dok se veza ne uspostavi i otkrivanje ne dovrši; otkrivene usluge zatim su dostupne putem getServices().

addr: Adresa ravnopravnog uređaja kao 17-znakovni "xx:xx:xx:xx:xx:xx" string (npr. preuzeta iz ScanEntry.addr()).
addr_type (samo ključna riječ): Ili constants.ADDR_TYPE_PUBLIC (zadano) ili constants.ADDR_TYPE_RANDOM_STATIC.

class ubluepy.Scanner¶

GAP promatrač za otkrivanje obližnjih uređaja koji se oglašavaju. Dostupan je samo kada je ugrađeni program (firmware) izgrađen s SoftDeviceom koji podržava centralni uređaj (s132 / s140).

scan(timeout: int) → list¶: Pokreće pasivno skeniranje tijekom timeout milisekundi i vraća popis instanci ScanEntry — po jednu za svaki izvještaj oglasa primljen tijekom prozora.

class ubluepy.ScanEntry¶

Pojedinačni izvještaj oglasa koji je zabilježio Scanner.scan(). Instance vraća skener — ne postoji javni konstruktor.

addr() → str¶: Vraća adresu ravnopravnog uređaja kao 17-znakovni "xx:xx:xx:xx:xx:xx" string.

addr_type() → int¶: Vraća tip adrese ravnopravnog uređaja (constants.ADDR_TYPE_PUBLIC ili constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int¶: Vraća indikator jakosti signala u dBm.

getScanData() → list¶: Dekodira korisno opterećenje oglasa u popis (ad_type, description, value) n-torki. ad_type je numerički bajt AD tipa (pogledajte constants.ad_types), description je ime odgovarajuće konstante kao string (ili None ako je tip nepoznat), a value je tijelo AD zapisa kao bytearray.

class ubluepy.DefaultDelegate¶

Bazna klasa za objekte koji se prosljeđuju metodi Peripheral.withDelegate(). Naslijedite je i nadjačajte handleConnection() / handleNotification() za reagiranje na GATT događaje.

handleConnection() → None¶: Poziva se za GAP događaje povezivanja / prekida veze. Zadana implementacija je prazna.

handleNotification() → None¶: Poziva se za dolazne GATT obavijesti. Zadana implementacija je prazna.

Konstante¶

Atribut constants modula je imenski prostor koji sadrži GAP/GATT identifikatore događaja, vrijednosti tipova adresa i ugniježđeni imenski prostor ad_types.

ubluepy.constants: type¶: Spremnik koji izlaže konstante u nastavku.

constants.EVT_GAP_CONNECTED: int¶: Vrijednost event_id rukovatelja vezom Peripheral za GAP povezivanje (16).

constants.EVT_GAP_DISCONNECTED: int¶: Vrijednost event_id rukovatelja vezom Peripheral za GAP prekid veze (17).

constants.EVT_GATTS_WRITE: int¶: Vrijednost event_id rukovatelja vezom Peripheral za upis u lokalni GATT atribut, uključujući upise u CCCD koji omogućuju/onemogućuju obavijesti (80).

constants.UUID_CCCD: int¶: Standardni Bluetooth UUID za Client Characteristic Configuration Descriptor (0x2902).

constants.ADDR_TYPE_PUBLIC: int¶: Javna Bluetooth adresa uređaja (0).

constants.ADDR_TYPE_RANDOM_STATIC: int¶: Statička slučajna Bluetooth adresa uređaja (1).

constants.ad_types: type¶

Imenski prostor konstanti AD tipova podataka oglašavanja iz Bluetooth Core Specification Supplementa. Svako ime mapira se na odgovarajući 1-bajtni AD tip:

Ime	Vrijednost
`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 — Bluetooth LE periferija i centralni uređaj¶