`ubluepy` — Bluetooth LE periferie a centrála¶

Modul ubluepy je starší Bluetooth LE API dodávané s nRF portem MicroPythonu. Je volně modelováno podle Linuxové Python knihovny bluepy a leží přímo nad Nordic SoftDevice — neexistuje žádný přenositelný back-end, takže modul je dostupný pouze na Nordic cílech (v nabídce OpenMV jde o Arduino Nano 33 BLE Sense). Novější API bluetooth / aioble v tomto sestavení nejsou povolena, takže ubluepy je jediný způsob, jak ovládat integrovaný radiový modul.

Dostupná sada funkcí závisí na SoftDevice naprogramovaném firmwarem:

s140 (Nano 33 BLE Sense) — jak role periferie, tak centrály (skener). Toto dodává firmware OpenMV.
s132 — jak periferie, tak centrála.
s110 — pouze periferie; metody skeneru / připojení jsou vyřazeny z kompilace.

Příklad periferie¶

Inzeruje se jako Bluetooth LE periferie s jedinou službou environmentálního snímání a notifikuje charakteristiku teploty při každém zápisu do svého 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])

Příklad centrály¶

Skenuje okolní inzerující zařízení po dobu 100 ms a dekóduje data inzerce každého 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))

Obsah modulu¶

Třídy¶

class ubluepy.UUID(value)¶

Sestaví 16- nebo 128bitové Bluetooth UUID.

value

Jedna z hodnot:

int — 16bitové číselné UUID (UUID(0x180A)).
6znakový řetězec "0xXXXX" — 16bitové UUID, např. UUID("0x181A").
36znakový řetězec "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" — úplné 128bitové UUID. Část specifická pro výrobce je při konstrukci zaregistrována u SoftDevice.
Jiná instance UUID — provede kopii.

Jakákoli jiná délka vyvolá ValueError("Invalid UUID string length").

binVal() → int¶: Vrací spodních 16 bitů UUID jako int. U 128bitových UUID se vrací pouze 16bitové pole vložené uvnitř UUID specifického pro výrobce (úplná 128bitová hodnota je přístupná pouze přes vendor-specific index SoftDevice).

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

Definuje GATT službu, která bude zaregistrována u SoftDevice po přidání k Peripheral.

uuid: Instance UUID. Předání objektu, který není UUID, vyvolá ValueError.
type: Buď Service.PRIMARY (výchozí), nebo Service.SECONDARY. Jiné hodnoty vyvolají ValueError.

uuid() → UUID¶: Vrací instanci UUID dané služby.

addCharacteristic(characteristic: Characteristic) → None¶: Zaregistruje Characteristic ke službě. GATT handle charakteristiky je přiřazen během tohoto volání.

getCharacteristic(uuid: UUID) → Characteristic | None¶: Vyhledá dříve přidanou Characteristic podle UUID. Vrací instanci charakteristiky, nebo None, pokud není nalezena žádná shoda.

getCharacteristics() → list¶: Vrací seznam všech charakteristik přidaných ke službě.

PRIMARY: int¶: Konstanta typu služby pro primární služby (1).

SECONDARY: int¶: Konstanta typu služby pro sekundární služby (2).

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

Definuje GATT charakteristiku. Přidejte ji ke Service pomocí Service.addCharacteristic() dříve, než nadřazená Peripheral začne inzerovat.

uuid: Instance UUID.
props (pouze klíčové slovo): Bitová maska jedné nebo více hodnot Characteristic.PROP_* popisujících, jaké operace charakteristika podporuje.
attrs (pouze klíčové slovo): Bitová maska dalších GATT atributů. Použijte Characteristic.ATTR_CCCD pro připojení Client Characteristic Configuration Descriptor — nezbytné pro fungování charakteristik PROP_NOTIFY / PROP_INDICATE.

uuid() → UUID¶: Vrací instanci UUID dané charakteristiky.

properties() → int¶: Vrací bitovou masku props nastavenou v době konstrukce.

read() → bytearray¶: Pouze role centrály. Přečte hodnotu charakteristiky z připojeného protějšku. Vrací bytearray s nejnovější hodnotou. Na periferii nemá tato operace efekt a vrací None.

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

Zapíše do charakteristiky.

Na periferii, pokud je ve vlastnostech charakteristiky nastaveno PROP_NOTIFY, je hodnota odeslána jako GATT notifikace připojené centrále; jinak se aktualizuje hodnota lokálního atributu.
Na centrále se hodnota zapíše do vzdáleného protějšku. Nastavte with_response=True pro vydání write requestu a čekání na potvrzení protějšku namísto write commandu.

data je libovolný objekt podporující buffer protokol (bytes, bytearray, memoryview).

PROP_BROADCAST: int¶: Charakteristika může vysílat svou hodnotu (0x01).

PROP_READ: int¶: Charakteristika podporuje čtení (0x02).

PROP_WRITE_WO_RESP: int¶: Charakteristika podporuje zápisy bez odpovědi (0x04).

PROP_WRITE: int¶: Charakteristika podporuje zápisy s odpovědí (0x08).

PROP_NOTIFY: int¶: Charakteristika může odesílat notifikace odebírající centrále (0x10).

PROP_INDICATE: int¶: Charakteristika může odesílat indikace (potvrzované notifikace) odebírající centrále (0x20).

PROP_AUTH_SIGNED_WR: int¶: Charakteristika podporuje autentizované podepsané zápisy (0x40).

ATTR_CCCD: int¶: Přidá k charakteristice Client Characteristic Configuration Descriptor (0x01). Nezbytné, aby se klienti mohli přihlásit k odběru notifikací/indikací.

class ubluepy.Descriptor(uuid: UUID)¶: Pahýlová třída pro reprezentaci GATT deskriptorů. Aktuální implementace pouze ukládá UUID a nevystavuje žádné metody — je poskytována pro dopřednou kompatibilitu s budoucími verzemi modulu.

class ubluepy.Peripheral¶

Lokální Bluetooth LE zařízení. Stejná třída se používá pro role periferie i centrály; role je vybrána podle toho, které metody zavoláte (advertise() vybírá periferii, connect() vybírá centrálu).

addService(service: Service) → None¶: Zaregistruje Service (a všechny její dříve přidané charakteristiky) u lokálního GATT serveru.

getServices() → list¶: Vrací seznam služeb aktuálně zaregistrovaných u této Peripheral.

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

Spustí inzerci v roli periferie.

device_name: Úplný lokální název inzerovaný v GAP payloadu.
services: Seznam instancí Service, které se mají inzerovat. UUID každé služby je zahrnuto v inzerci.
data: Volitelný surový payload inzerce (bytes / bytearray) připojený za automaticky generovanou hlavičku. Použijte jej pro payloady specifické pro výrobce nebo beacony, jako je Eddystone.
connectable: Při True (výchozí) se inzeruje jako připojitelné zařízení a registrují se obslužné rutiny GAP / GATTS událostí, takže nakonfigurovaný callback setConnectionHandler() se spustí při připojení, odpojení a zápisech do CCCD. Při False se inzeruje jako beacon — nepřipojují se žádné obslužné rutiny a k zařízení se nelze připojit.

advertise_stop() → None¶: Zastaví jakoukoli probíhající inzerci.

setConnectionHandler(func) → None¶: Zaregistruje callback vyvolávaný při GAP a GATTS událostech. Callback je volán jako func(event_id, conn_handle, data), kde event_id je jedna z hodnot constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED nebo constants.EVT_GATTS_WRITE, conn_handle je SoftDevice connection handle (nebo attribute handle pro GATTS zápisy) a data je surový payload události jako bytearray (nebo None pro připojení / odpojení).

setNotificationHandler(func) → None¶: Zaregistruje callback pro notifikační události přijaté v roli centrály.

withDelegate(delegate: DefaultDelegate) → None¶: Připojí instanci DefaultDelegate pro příjem dekódovaných GATT událostí.

disconnect() → None¶: Zruší aktivní připojení (v tomto sestavení aktuálně pahýl bez efektu).

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

Pouze role centrály. Připojí se k protějšku se zadanou adresou a synchronně zjistí jeho primární služby a charakteristiky. Blokuje, dokud není připojení navázáno a zjišťování dokončeno; zjištěné služby jsou poté dostupné přes getServices().

addr: Adresa protějšku jako 17znakový řetězec "xx:xx:xx:xx:xx:xx" (např. získaný z ScanEntry.addr()).
addr_type (pouze klíčové slovo): Buď constants.ADDR_TYPE_PUBLIC (výchozí), nebo constants.ADDR_TYPE_RANDOM_STATIC.

class ubluepy.Scanner¶

GAP pozorovatel pro zjišťování okolních inzerujících zařízení. Dostupný pouze tehdy, když je firmware sestaven proti SoftDevice s podporou centrály (s132 / s140).

scan(timeout: int) → list¶: Spustí pasivní sken po dobu timeout milisekund a vrátí seznam instancí ScanEntry — jednu na každou zprávu inzerce přijatou během okna.

class ubluepy.ScanEntry¶

Jedna zpráva inzerce zachycená metodou Scanner.scan(). Instance jsou vraceny ze skeneru — neexistuje žádný veřejný konstruktor.

addr() → str¶: Vrací adresu protějšku jako 17znakový řetězec "xx:xx:xx:xx:xx:xx".

addr_type() → int¶: Vrací typ adresy protějšku (constants.ADDR_TYPE_PUBLIC nebo constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int¶: Vrací indikátor síly signálu v dBm.

getScanData() → list¶: Dekóduje payload inzerce do seznamu n-tic (ad_type, description, value). ad_type je číselný bajt AD typu (viz constants.ad_types), description je název odpovídající konstanty jako řetězec (nebo None, pokud je typ neznámý) a value je tělo AD záznamu jako bytearray.

class ubluepy.DefaultDelegate¶

Základní třída pro objekty předávané metodě Peripheral.withDelegate(). Vytvořte její podtřídu a přepište handleConnection() / handleNotification() pro reakci na GATT události.

handleConnection() → None¶: Voláno při GAP událostech připojení / odpojení. Výchozí implementace je prázdná.

handleNotification() → None¶: Voláno při příchozích GATT notifikacích. Výchozí implementace je prázdná.

Konstanty¶

Atribut constants modulu je jmenný prostor obsahující identifikátory GAP/GATT událostí, hodnoty typů adres a vnořený jmenný prostor ad_types.

ubluepy.constants: type¶: Kontejner vystavující níže uvedené konstanty.

constants.EVT_GAP_CONNECTED: int¶: Hodnota event_id obslužné rutiny připojení Peripheral pro GAP připojení (16).

constants.EVT_GAP_DISCONNECTED: int¶: Hodnota event_id obslužné rutiny připojení Peripheral pro GAP odpojení (17).

constants.EVT_GATTS_WRITE: int¶: Hodnota event_id obslužné rutiny připojení Peripheral pro zápis do lokálního GATT atributu, včetně zápisů do CCCD, které povolují/zakazují notifikace (80).

constants.UUID_CCCD: int¶: Standardní Bluetooth UUID pro Client Characteristic Configuration Descriptor (0x2902).

constants.ADDR_TYPE_PUBLIC: int¶: Veřejná Bluetooth Device Address (0).

constants.ADDR_TYPE_RANDOM_STATIC: int¶: Statická náhodná Bluetooth Device Address (1).

constants.ad_types: type¶

Jmenný prostor konstant AD typů inzerčních dat z Bluetooth Core Specification Supplement. Každý název mapuje na odpovídající 1bajtový AD typ:

Název	Hodnota
`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 periferie a centrála¶