`ubluepy` — Bluetooth LE periféria és központ¶

Az ubluepy modul a MicroPython nRF portjával szállított örökölt Bluetooth LE API. Lazán a Linux bluepy Python könyvtárra épül, és közvetlenül a Nordic SoftDevice tetején helyezkedik el — nincs hordozható háttérrendszer, így a modul csak Nordic célplatformokon érhető el (az OpenMV kínálatában az Arduino Nano 33 BLE Sense). Az újabb bluetooth / aioble API-k nincsenek engedélyezve ebben a build-ben, így az ubluepy az egyetlen módja a chipbe integrált rádió vezérlésének.

Az elérhető funkciókészlet a firmware által flashelt SoftDevice-tól függ:

s140 (Nano 33 BLE Sense) — mind a periféria, mind a központ (szkenner) szerepkör. Ezt szállítja az OpenMV firmware.
s132 — mind a periféria, mind a központ.
s110 — csak periféria; a szkenner / csatlakozási metódusok ki vannak fordítva.

Periféria példa¶

Bluetooth LE perifériaként hirdet egyetlen környezetérzékelő szolgáltatással, és értesítést küld egy hőmérséklet-karakterisztikáról a Client Characteristic Configuration Descriptor (CCCD) minden írásakor:

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

Központ példa¶

100 ms-ig keres a közelben lévő hirdető eszközöket, és dekódolja az egyes ScanEntry hirdetési adatait:

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

Modul tartalma¶

Osztályok¶

class ubluepy.UUID(value)¶

Létrehoz egy 16 vagy 128 bites Bluetooth UUID-t.

value

Az alábbiak egyike:

int — egy 16 bites numerikus UUID (UUID(0x180A)).
6 karakteres "0xXXXX" karakterlánc — egy 16 bites UUID, pl. UUID("0x181A").
36 karakteres "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" karakterlánc — egy teljes 128 bites UUID. A gyártóspecifikus rész a létrehozáskor regisztrálódik a SoftDevice-ban.
Egy másik UUID példány — másolatot készít.

Bármely más hossz ValueError("Invalid UUID string length") hibát vált ki.

binVal() → int¶: Visszaadja az UUID alsó 16 bitjét int értékként. A 128 bites UUID-knél csak a gyártóspecifikus UUID-ba ágyazott 16 bites mező kerül visszaadásra (a teljes 128 bites érték kizárólag a SoftDevice gyártóspecifikus indexén keresztül érhető el).

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

Definiál egy GATT szolgáltatást, amely a SoftDevice-ban regisztrálódik, amikor hozzáadják egy Peripheral objektumhoz.

uuid: Egy UUID példány. Nem UUID objektum átadása ValueError hibát vált ki.
type: Vagy a Service.PRIMARY (alapértelmezett), vagy a Service.SECONDARY. Más értékek ValueError hibát váltanak ki.

uuid() → UUID¶: Visszaadja a szolgáltatás UUID példányát.

addCharacteristic(characteristic: Characteristic) → None¶: Regisztrál egy Characteristic objektumot a szolgáltatáshoz. A karakterisztika GATT leírója (handle) ennek a hívásnak során kerül kiosztásra.

getCharacteristic(uuid: UUID) → Characteristic | None¶: Megkeres egy korábban hozzáadott Characteristic objektumot UUID alapján. Visszaadja a karakterisztika példányt, vagy None értéket, ha nincs találat.

getCharacteristics() → list¶: Visszaadja a szolgáltatáshoz hozzáadott összes karakterisztika listáját.

PRIMARY: int¶: Szolgáltatástípus-konstans az elsődleges szolgáltatásokhoz (1).

SECONDARY: int¶: Szolgáltatástípus-konstans a másodlagos szolgáltatásokhoz (2).

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

Definiál egy GATT karakterisztikát. Add hozzá egy Service objektumhoz a Service.addCharacteristic() segítségével, mielőtt a szülő Peripheral elkezdene hirdetni.

uuid: Egy UUID példány.
props (csak kulcsszóként): Egy vagy több Characteristic.PROP_* érték bitmaszkja, amely leírja, hogy a karakterisztika milyen műveleteket támogat.
attrs (csak kulcsszóként): További GATT attribútumok bitmaszkja. Használd a Characteristic.ATTR_CCCD értéket egy Client Characteristic Configuration Descriptor csatolásához — ez szükséges ahhoz, hogy a PROP_NOTIFY / PROP_INDICATE karakterisztikák működjenek.

uuid() → UUID¶: Visszaadja a karakterisztika UUID példányát.

properties() → int¶: Visszaadja a létrehozáskor beállított props bitmaszkot.

read() → bytearray¶: Csak központ szerepkörben. Beolvassa a karakterisztika értékét a csatlakoztatott társeszközről. Egy bytearray objektumot ad vissza a legutóbbi értékkel. Periférián ez egy üres művelet, és None értéket ad vissza.

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

Ír a karakterisztikába.

Periférián, ha a PROP_NOTIFY be van állítva a karakterisztika tulajdonságaiban, az érték GATT értesítésként kerül elküldésre a csatlakoztatott központnak; egyébként a helyi attribútum értéke frissül.
Központon az érték a távoli társeszközre íródik. Állítsd a with_response=True értéket egy írási kérés kiadásához és a társeszköz visszaigazolásának bevárásához egy írási parancs helyett.

A data bármely puffer-protokollt megvalósító objektum (bytes, bytearray, memoryview).

PROP_BROADCAST: int¶: A karakterisztika sugározhatja az értékét (0x01).

PROP_READ: int¶: A karakterisztika támogatja az olvasásokat (0x02).

PROP_WRITE_WO_RESP: int¶: A karakterisztika támogatja a válasz nélküli írásokat (0x04).

PROP_WRITE: int¶: A karakterisztika támogatja a válasszal történő írásokat (0x08).

PROP_NOTIFY: int¶: A karakterisztika értesítéseket küldhet egy feliratkozott központnak (0x10).

PROP_INDICATE: int¶: A karakterisztika jelzéseket (visszaigazolt értesítéseket) küldhet egy feliratkozott központnak (0x20).

PROP_AUTH_SIGNED_WR: int¶: A karakterisztika támogatja a hitelesített aláírt írásokat (0x40).

ATTR_CCCD: int¶: Hozzáad egy Client Characteristic Configuration Descriptor leírót a karakterisztikához (0x01). Szükséges ahhoz, hogy a kliensek fel tudjanak iratkozni az értesítésekre/jelzésekre.

class ubluepy.Descriptor(uuid: UUID)¶: Csonkosztály a GATT leírók (descriptor) reprezentálásához. A jelenlegi megvalósítás csak az UUID-t tárolja, és nem tesz elérhetővé metódusokat — a modul jövőbeli verzióival való előremutató kompatibilitás érdekében biztosított.

class ubluepy.Peripheral¶

A helyi Bluetooth LE eszköz. Ugyanaz az osztály szolgál mind a periféria, mind a központ szerepkörhöz; a szerepkört az határozza meg, hogy mely metódusokat hívod meg (az advertise() a perifériát választja, a connect() a központot).

addService(service: Service) → None¶: Regisztrál egy Service objektumot (és annak összes korábban hozzáadott karakterisztikáját) a helyi GATT szerverrel.

getServices() → list¶: Visszaadja az ehhez a Peripheral objektumhoz jelenleg regisztrált szolgáltatások listáját.

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

Elkezd hirdetni periféria szerepkörben.

device_name: A GAP terhelésben hirdetett teljes helyi név.
services: A hirdetendő Service példányok listája. Minden szolgáltatás UUID-ja bekerül a hirdetésbe.
data: Opcionális nyers hirdetési terhelés (bytes / bytearray), amely az automatikusan generált fejléchez fűződik hozzá. Ezt gyártóspecifikus vagy beacon terhelésekhez használd, mint amilyen az Eddystone.
connectable: Ha True (alapértelmezett), csatlakoztatható eszközként hirdet, és regisztrálja a GAP / GATTS eseménykezelőket, így a beállított setConnectionHandler() visszahívás aktiválódik csatlakozáskor, bontáskor és CCCD írásokkor. Ha False, beaconként hirdet — nincsenek kezelők csatolva, és az eszközhöz nem lehet csatlakozni.

advertise_stop() → None¶: Leállít minden folyamatban lévő hirdetést.

setConnectionHandler(func) → None¶: Regisztrál egy visszahívást, amely a GAP és GATTS eseményekre hívódik meg. A visszahívás func(event_id, conn_handle, data) formában kerül meghívásra, ahol az event_id a constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED vagy constants.EVT_GATTS_WRITE értékek egyike, a conn_handle a SoftDevice kapcsolatleírója (vagy GATTS írások esetén az attribútumleíró), a data pedig a nyers eseményterhelés bytearray formában (vagy None csatlakozáskor / bontáskor).

setNotificationHandler(func) → None¶: Regisztrál egy visszahívást a központ szerepkörben fogadott értesítési eseményekhez.

withDelegate(delegate: DefaultDelegate) → None¶: Csatol egy DefaultDelegate példányt a dekódolt GATT események fogadásához.

disconnect() → None¶: Bontja az aktív kapcsolatot (jelenleg üres műveletet végző csonk ebben a build-ben).

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

Csak központ szerepkörben. Csatlakozik a megadott című társeszközhöz, és szinkron módon felderíti annak elsődleges szolgáltatásait és karakterisztikáit. Blokkol, amíg a kapcsolat létre nem jön és a felderítés be nem fejeződik; a felderített szolgáltatások ezután a getServices() segítségével érhetők el.

addr: A társeszköz címe 17 karakteres "xx:xx:xx:xx:xx:xx" karakterláncként (pl. a ScanEntry.addr() metódusból véve).
addr_type (csak kulcsszóként): Vagy a constants.ADDR_TYPE_PUBLIC (alapértelmezett), vagy a constants.ADDR_TYPE_RANDOM_STATIC.

class ubluepy.Scanner¶

GAP megfigyelő a közelben lévő hirdető eszközök felderítéséhez. Csak akkor érhető el, ha a firmware központtámogatással rendelkező SoftDevice ellen lett fordítva (s132 / s140).

scan(timeout: int) → list¶: Passzív keresést futtat timeout ezredmásodpercig, és visszaadja a ScanEntry példányok listáját — egyet az ablak során fogadott minden egyes hirdetési jelentéshez.

class ubluepy.ScanEntry¶

Egyetlen hirdetési jelentés, amelyet a Scanner.scan() rögzített. A példányokat a szkenner adja vissza — nincs nyilvános konstruktor.

addr() → str¶: Visszaadja a társeszköz címét 17 karakteres "xx:xx:xx:xx:xx:xx" karakterláncként.

addr_type() → int¶: Visszaadja a társeszköz címtípusát (constants.ADDR_TYPE_PUBLIC vagy constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int¶: Visszaadja a jelerősség-jelzőt dBm-ben.

getScanData() → list¶: Dekódolja a hirdetési terhelést egy (ad_type, description, value) rendezett párokból álló listára. Az ad_type a numerikus AD-típus bájt (lásd constants.ad_types), a description a megfelelő konstans neve karakterláncként (vagy None, ha a típus ismeretlen), a value pedig az AD rekord törzse bytearray formában.

class ubluepy.DefaultDelegate¶

Az Peripheral.withDelegate() metódusnak átadott objektumok alaposztálya. Származtasd le, és írd felül a handleConnection() / handleNotification() metódusokat a GATT eseményekre való reagáláshoz.

handleConnection() → None¶: GAP csatlakozási / bontási eseményekre hívódik meg. Az alapértelmezett megvalósítás üres.

handleNotification() → None¶: Bejövő GATT értesítésekre hívódik meg. Az alapértelmezett megvalósítás üres.

Konstansok¶

A modul constants attribútuma egy névtér, amely GAP/GATT eseményazonosítókat, címtípus-értékeket és a beágyazott ad_types névteret tartalmazza.

ubluepy.constants: type¶: Az alábbi konstansokat elérhetővé tevő tároló.

constants.EVT_GAP_CONNECTED: int¶: A Peripheral kapcsolatkezelő event_id értéke GAP csatlakozáshoz (16).

constants.EVT_GAP_DISCONNECTED: int¶: A Peripheral kapcsolatkezelő event_id értéke GAP bontáshoz (17).

constants.EVT_GATTS_WRITE: int¶: A Peripheral kapcsolatkezelő event_id értéke egy helyi GATT attribútumba történő íráshoz, beleértve az értesítéseket engedélyező/letiltó CCCD-be történő írásokat is (80).

constants.UUID_CCCD: int¶: A Client Characteristic Configuration Descriptor szabványos Bluetooth UUID-ja (0x2902).

constants.ADDR_TYPE_PUBLIC: int¶: Nyilvános Bluetooth eszközcím (0).

constants.ADDR_TYPE_RANDOM_STATIC: int¶: Statikus véletlenszerű Bluetooth eszközcím (1).

constants.ad_types: type¶

A hirdetési adatok AD-típus konstansainak névtere a Bluetooth Core Specification Supplement alapján. Minden név a megfelelő 1 bájtos AD-típushoz tartozik:

Név	Érték
`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 periféria és központ¶