11.8. Modul aioble#

Specifikace Bluetooth Core poskytuje slovník, který se mapuje na dva moduly MicroPython.

  • bluetooth – nízkoúrovňová vazba na BLE řadič. Synchronní, řízená událostmi přes callback ve stylu IRQ a strukturovaná kolem bajtových bufferů, handlů a holých GATT primitiv. Vystavuje protokol takový, jaký je, nikoli takový, jak ho chtějí konzumovat aplikace v Pythonu.

  • aioble – vyšší úrovňový obal napsaný v Pythonu nad bluetooth, který každou vzdálenou operaci proměňuje na korutinu asyncio a každý BLE objekt (služby, charakteristiky, připojení, výsledky skenování, kanály L2CAP) na ergonomickou třídu v Pythonu. Skenování se stává asynchronními iterátory; připojení se stávají asynchronními kontextovými správci; oznámení se stávají awaitable.

11.8.1. Kdy sáhnout po nízkoúrovňovém modulu#

bluetooth je stále tou správnou odpovědí pro dva úzké případy:

  • Píšete druh kódu, ze kterého je vystavěn sám aioble – nový vzor, který potřebuje řízení protokolu na úrovni IRQ.

  • Běžíte na hardwarové platformě, kde balíček aioble není k dispozici, a tenká mezivrstva kolem řadiče je jedinou možností.

Pro každou kamerovou aplikaci je aioble tou správnou odpovědí.

11.8.2. Části programu aioble#

Každá aplikace založená na aioble má malou množinu pohyblivých částí, bez ohledu na to, jaké role hraje.

  • Dlouho běžící smyčka událostí asyncio. Vše v aioble je korutina, takže aplikace je strukturována jako jedna nebo více úloh na jediné smyčce událostí. Podrobnosti o smyčce, úlohách a výjimkách viz Asyncio.

  • Zapnuté rádio. aioble aktivuje BLE rádio implicitně při prvním použití, ale lze ho také řídit explicitně pomocí aioble.config() (které předává volání bluetooth.BLE.config() poté, co zajistí, že je rádio v provozu) a vypnout pomocí aioble.stop().

  • Jedna nebo více rolí najednou v běhu. Na straně periferie: registrovaná sada GATT služeb (viz aioble.register_services()) a běžící korutina aioble.advertise(). Na straně centrálního zařízení: běžící iterátor aioble.scan() nebo čekající aioble.Device.connect(). Rádio práci multiplexuje; aplikace vidí každou roli jako nezávislou úlohu.

11.8.3. Minimální periferie#

Nejmenší užitečný program aioble – periferie, která inzeruje jedinou charakteristiku pouze pro čtení – je krátký:

import aioble
import asyncio
import bluetooth

SERVICE_UUID = bluetooth.UUID(0x181A)            # Environmental Sensing
TEMP_UUID = bluetooth.UUID(0x2A6E)               # Temperature

service = aioble.Service(SERVICE_UUID)
temp = aioble.Characteristic(service, TEMP_UUID, read=True)
aioble.register_services(service)

async def main():
    while True:
        conn = await aioble.advertise(
            interval_us=250000,
            name="openmv-temp",
            services=[SERVICE_UUID],
        )
        async with conn:
            await conn.disconnected()

asyncio.run(main())

Centrální zařízení, které nedělá nic víc než se připojí a jednou přečte, je podobně krátké:

import aioble
import asyncio
import bluetooth

SERVICE_UUID = bluetooth.UUID(0x181A)
TEMP_UUID = bluetooth.UUID(0x2A6E)

async def main():
    device = None
    async with aioble.scan(duration_ms=5000, active=True) as scanner:
        async for result in scanner:
            if SERVICE_UUID in result.services():
                device = result.device
                break
    if device is None:
        return

    async with await device.connect() as conn:
        service = await conn.service(SERVICE_UUID)
        char = await service.characteristic(TEMP_UUID)
        print(await char.read())

asyncio.run(main())

Oba programy mají kolem patnácti řádků a pokrývají celý tok od „rádio je vypnuté“ po „užitečná práce hotova“.

11.8.4. Vypnutí rádia#

Na kameře napájené z baterie je BLE rádio největším volitelným odběrem z rozpočtu. Záleží na dvou regulátorech.

První je implicitní: aioble aktivuje rádio při prvním použití a rádio mezi naplánovanými událostmi (inzertní dávky, události připojení, skenovací okna) automaticky usíná. Volba delších intervalů u aioble.advertise() / aioble.scan() a dohoda na delším intervalu připojení v čase connect() udržuje rádio vypnuté úměrně více času. Praktickým vodítkem je zde tabulka inzerce v Vysílání (advertising) a skenování.

Druhým je explicitní vypnutí:

import aioble

await do_burst_of_ble_work()
aioble.stop()                             # radio deactivated; in-flight tasks unwound
await asyncio.sleep(60)                   # sleep with the radio off
# ... next aioble call brings the radio back up automatically

aioble.stop() deaktivuje podkladové BLE rádio a strhne vše, co je v běhu – otevřená připojení vypadnou, skenery a inzerující se zruší, kanály L2CAP se zavřou. Korutiny, které na tyto operace čekaly, vyvolají své obvyklé výjimky (DeviceDisconnectedError a podobné), což je úklidový mechanismus, pro který byly okolní bloky async with napsány. Volání jakékoli korutiny aioble poté znovu aktivuje rádio ze studeného stavu.

Typický vzor pro periodickou senzorovou kameru napájenou z baterie je:

  • Probudit se podle plánu (časovač, pohybový senzor, tlačítko).

  • Spustit dávku BLE práce – inzerovat, přijmout připojení, odeslat hodnotu, odpojit.

  • Zavolat aioble.stop() a spát do dalšího probuzení.

11.8.5. Co aioble nedělá#

aioble záměrně pokrývá GATT, GAP a L2CAP – vrstvy, které aplikace používá. Tři části jsou mimo rozsah:

  • Cokoli pod linkovou vrstvou. Výběr kanálu, frekvenční skákání, potvrzování paketů a šifrování na linkové vrstvě se vše odehrává uvnitř BLE portu a křemíku řadiče; aioble na této úrovni nevystavuje žádné háčky.

  • Klasický Bluetooth. aioble je pouze pro BLE. Audio spoje, RFCOMM, A2DP a další funkce klasických profilů nejsou součástí API.

  • Bluetooth Mesh. Vrstva síťování typu mesh od Bluetooth SIG (samostatný stack nad BLE inzercí) není na kameře implementována. Kamera může inzerovat a pozorovat, ale nemůže se účastnit rolí relay / friend / proxy v mesh síti.

11.8.6. Výjimky#

Z aioble vychází čtyři typy výjimek. Každá vystřelí zevnitř korutiny, která čekala na operaci, když se něco pokazilo; bloky async with se při jejich propagaci čistě rozvinou.

  • aioble.DeviceDisconnectedError – BLE spoj k protějšku vypadl, zatímco byla v běhu GATT operace (read, write, notified, indicated, subscribe, exchange_mtu, …). Vyvolána uvnitř té korutiny, která čekala. Zdaleka nejběžnější výjimka; zachyťte ji v jakémkoli kódu, který se má při ztrátě znovu připojit.

  • aioble.GattError – GATT operace dosáhla protějšku, ale dokončila se s nenulovým ATT stavem (write-with-response odmítnuto, indicate nepotvrzeno, read-not-permitted, …). Stavový kód je na atributu _status výjimky.

  • aioble.L2CAPDisconnectedError – kanál L2CAP vypadl, zatímco bylo v běhu send(), recvinto() nebo flush(). Kanál mohla zavřít kterákoli ze stran, nebo zaniklo podkladové GAP připojení.

  • aioble.L2CAPConnectionError – vyvolána l2cap_connect(), když naslouchající odmítl nebo řadič selhal při sestavení kanálu. Stavový kód Bluetooth je prvním poziční argumentem.

Operace, které berou explicitní timeout_ms (volání connect / discovery / read / write / pair, plus timeout() jako obal), navíc vyvolají asyncio.TimeoutError z asyncio, když časový limit uplyne dříve, než se operace dokončí.