bluetooth — nízkoúrovňový Bluetooth

Tento modul poskytuje rozhraní k vestavěnému Bluetooth řadiči. Podporuje Bluetooth Low Energy (BLE) v rolích Central, Peripheral, Broadcaster a Observer, stejně jako GATT Server a Client a L2CAP kanály orientované na spojení. Zařízení může pracovat ve více rolích současně. Podporováno je také párování (pairing) a vázání (bonding).

Toto API je navrženo tak, aby odpovídalo nízkoúrovňovému Bluetooth protokolu a poskytovalo stavební bloky pro abstrakce vyšší úrovně, jako jsou konkrétní typy zařízení.

Tip

Pro většinu aplikací upřednostněte knihovnu vyšší úrovně aioble, která poskytuje obal nad tímto modulem založený na asyncio. Viz aioble — Asynchronní BLE.

class BLE

class bluetooth.BLE

Vrací singletonový objekt BLE.

Konfigurace

active(active: bool | None = None, /) → bool

Volitelně změní aktivní stav BLE rádia a vrací aktuální stav.

Rádio musí být aktivováno před použitím jakýchkoli jiných metod této třídy.

config(param: str, /) → Any

config(*, **kwargs: Any) → None

Získá nebo nastaví konfigurační hodnoty BLE rozhraní. Pro získání hodnoty by měl být název parametru uveden jako řetězec v uvozovkách a najednou se dotazuje pouze jeden parametr. Pro nastavení hodnot použijte syntaxi klíčových slov; najednou lze nastavit jeden nebo více parametrů.

Aktuálně podporované hodnoty jsou:

• 'mac': Aktuálně používaná adresa, v závislosti na aktuálním režimu adres. Vrací n-tici (addr_type, addr).

  Podrobnosti o typu adresy viz gap_scan.

  Tuto hodnotu lze dotazovat pouze tehdy, je-li rozhraní právě aktivní.

• 'addr_mode': Nastaví režim adres. Hodnoty jsou:

  Hodnota	Název	Chování
  0x00	PUBLIC	Použije veřejnou adresu řadiče.
  0x01	RANDOM	Použije vygenerovanou statickou adresu.
  0x02	RPA	Použije rozlišitelné soukromé adresy (resolvable private addresses).
  0x03	NRPA	Použije nerozlišitelné soukromé adresy (non-resolvable private addresses).

  Ve výchozím nastavení použije rozhraní adresu PUBLIC, je-li dostupná, jinak použije adresu RANDOM.

• 'gap_name': Získá/nastaví GAP název zařízení používaný službou Generic Access (UUID 0x1800), charakteristikou Device Name (UUID 0x2a00). Lze jej nastavit kdykoli a vícekrát měnit.

• 'rxbuf': Získá/nastaví velikost interního bufferu (v bajtech) používaného pro ukládání příchozích událostí. Tento buffer je globální pro celý BLE ovladač, a tak zpracovává příchozí data pro všechny události, včetně všech charakteristik. Jeho zvětšení umožňuje lepší zpracování nárazově příchozích dat (například výsledků skenování) a schopnost přijímat větší hodnoty charakteristik.

• 'mtu': Získá/nastaví MTU, které bude použito během výměny ATT MTU. Výsledné MTU bude minimem z této hodnoty a MTU vzdáleného zařízení. Výměna ATT MTU neproběhne automaticky (pokud ji neiniciuje vzdálené zařízení) a musí být ručně iniciována pomocí gattc_exchange_mtu. Pro zjištění MTU daného spojení použijte událost _IRQ_MTU_EXCHANGED.

• 'bond': Nastaví, zda bude během párování povoleno vázání (bonding). Když je povoleno, požadavky na párování nastaví příznak „bond“ a klíče budou uloženy oběma zařízeními.

• 'mitm': Nastaví, zda je pro párování vyžadována ochrana MITM.

• 'io': Nastaví vstupně-výstupní (I/O) schopnosti tohoto zařízení.

  Dostupné možnosti jsou:

  Konstanta	Hodnota	Schopnost
  _IO_CAPABILITY_DISPLAY_ONLY	0	Pouze displej
  _IO_CAPABILITY_DISPLAY_YESNO	1	Displej se vstupem ano/ne
  _IO_CAPABILITY_KEYBOARD_ONLY	2	Pouze klávesnice
  _IO_CAPABILITY_NO_INPUT_OUTPUT	3	Žádný vstup ani výstup
  _IO_CAPABILITY_KEYBOARD_DISPLAY	4	Klávesnice a displej

• 'le_secure': Nastaví, zda je vyžadováno párování „LE Secure“. Výchozí hodnota je false (tj. povolit „Legacy Pairing“).

Zpracování událostí

irq(handler: Callable[[int, Tuple], Any | None], /) → None

Registruje callback pro události z BLE stacku. handler přijímá dva argumenty, event (který bude jedním z níže uvedených kódů) a data (což je n-tice hodnot specifická pro danou událost).

Poznámka: Jako optimalizace pro zabránění zbytečným alokacím jsou položky addr, adv_data, char_data, notify_data a uuid v n-ticích instance memoryview pouze pro čtení, které ukazují do interního kruhového bufferu modulu bluetooth, a jsou platné pouze během volání funkce obsluhy IRQ. Pokud váš program potřebuje uložit některou z těchto hodnot pro přístup poté, co se obsluha IRQ vrátí (např. uložením do instance třídy nebo globální proměnné), musí si pořídit kopii dat, a to buď pomocí bytes() nebo bluetooth.UUID(), takto:

connected_addr = bytes(addr)  # equivalently: adv_data, char_data, or notify_data
matched_uuid = bluetooth.UUID(uuid)

Například obsluha IRQ pro výsledek skenování může zkontrolovat adv_data, aby rozhodla, zda jde o správné zařízení, a teprve poté zkopírovat data adresy pro použití jinde v programu. A pro výpis dat z obsluhy IRQ bude potřeba print(bytes(addr)).

Obsluha typicky rozhoduje podle kódu události a rozbaluje n-tici dat specifickou pro danou událost:

def bt_irq(event, data):
    if event == _IRQ_CENTRAL_CONNECT:
        conn_handle, addr_type, addr = data
        ...
    elif event == _IRQ_SCAN_RESULT:
        addr_type, addr, adv_type, rssi, adv_data = data
        ...

Každý kód události, data, která doručuje, a krátký popis jsou uvedeny níže. U událostí, kde je zmíněno pole status, je status 0 při úspěchu a nenulová hodnota specifická pro implementaci při selhání.

Konstanta	Hodnota	Událost	N-tice dat (payload)
_IRQ_CENTRAL_CONNECT	1	K této periferii se připojilo zařízení central.	(conn_handle, addr_type, addr)
_IRQ_CENTRAL_DISCONNECT	2	Zařízení central se odpojilo od této periferie.	(conn_handle, addr_type, addr)
_IRQ_GATTS_WRITE	3	Připojený klient zapsal do lokální charakteristiky nebo deskriptoru. Pro načtení nové hodnoty použijte gatts_read.	(conn_handle, attr_handle)
_IRQ_GATTS_READ_REQUEST	4	Připojený klient vydal požadavek na čtení. Vraťte nenulový chybový kód z tabulky níže pro zamítnutí čtení, nebo 0 / None pro jeho přijetí.	(conn_handle, attr_handle)
_IRQ_SCAN_RESULT	5	Během aktivního skenování byl přijat jediný advertising paket.	(addr_type, addr, adv_type, rssi, adv_data)
_IRQ_SCAN_DONE	6	Aktuální skenování skončilo, buď protože uplynula nakonfigurovaná doba trvání, nebo protože bylo voláno gap_scan(None).	()
_IRQ_PERIPHERAL_CONNECT	7	Dříve vydané gap_connect uspělo.	(conn_handle, addr_type, addr)
_IRQ_PERIPHERAL_DISCONNECT	8	Připojená periferie se odpojila.	(conn_handle, addr_type, addr)
_IRQ_GATTC_SERVICE_RESULT	9	Metoda gattc_discover_services nalezla jednu službu.	(conn_handle, start_handle, end_handle, uuid)
_IRQ_GATTC_SERVICE_DONE	10	Vyhledávání služeb skončilo.	(conn_handle, status)
_IRQ_GATTC_CHARACTERISTIC_RESULT	11	Metoda gattc_discover_characteristics nalezla jednu charakteristiku.	(conn_handle, end_handle, value_handle, properties, uuid)
_IRQ_GATTC_CHARACTERISTIC_DONE	12	Vyhledávání charakteristik skončilo.	(conn_handle, status)
_IRQ_GATTC_DESCRIPTOR_RESULT	13	Metoda gattc_discover_descriptors nalezla jeden deskriptor.	(conn_handle, dsc_handle, uuid)
_IRQ_GATTC_DESCRIPTOR_DONE	14	Vyhledávání deskriptorů skončilo.	(conn_handle, status)
_IRQ_GATTC_READ_RESULT	15	Dříve vydané gattc_read vrátilo data.	(conn_handle, value_handle, char_data)
_IRQ_GATTC_READ_DONE	16	Dříve vydané gattc_read skončilo.	(conn_handle, value_handle, status)
_IRQ_GATTC_WRITE_DONE	17	Dříve vydané gattc_write bylo potvrzeno.	(conn_handle, value_handle, status)
_IRQ_GATTC_NOTIFY	18	Vzdálený server odeslal (nepotvrzené) oznámení (notification).	(conn_handle, value_handle, notify_data)
_IRQ_GATTC_INDICATE	19	Vzdálený server odeslal (potvrzené) hlášení (indication).	(conn_handle, value_handle, notify_data)
_IRQ_GATTS_INDICATE_DONE	20	Dříve odeslané hlášení (indication) bylo potvrzeno klientem (nebo vypršel jeho časový limit).	(conn_handle, value_handle, status)
_IRQ_MTU_EXCHANGED	21	Výměna ATT MTU byla dokončena (iniciovaná kteroukoli stranou).	(conn_handle, mtu)
_IRQ_L2CAP_ACCEPT	22	Vzdálené zařízení požádalo o L2CAP spojení na PSM, na kterém toto zařízení naslouchá. Vraťte nenulové celé číslo pro odmítnutí, nebo 0 / None pro přijetí.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_CONNECT	23	L2CAP kanál je nyní navázán, buď přijetím příchozího požadavku, nebo dokončením odchozího l2cap_connect.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_DISCONNECT	24	L2CAP kanál byl odpojen. status je 0 pro čisté odpojení, nebo nenulový, pokud selhal pokus o odchozí spojení.	(conn_handle, cid, psm, status)
_IRQ_L2CAP_RECV	25	Na L2CAP kanál dorazila data. Pro jejich přečtení zavolejte l2cap_recvinto.	(conn_handle, cid)
_IRQ_L2CAP_SEND_READY	26	Předchozí l2cap_send, které vrátilo False, se vyprázdnilo a kanál je opět připraven. Nenulový status znamená, že přetekl odesílací buffer a aplikace musí data odeslat znovu.	(conn_handle, cid, status)
_IRQ_CONNECTION_UPDATE	27	Vzdálené zařízení aktualizovalo parametry spojení (interval, latence, supervision timeout).	(conn_handle, conn_interval, conn_latency, supervision_timeout, status)
_IRQ_ENCRYPTION_UPDATE	28	Stav šifrování spojení se změnil, typicky po dokončení párování nebo vázání.	(conn_handle, encrypted, authenticated, bonded, key_size)
_IRQ_GET_SECRET	29	Stack požaduje uložené tajemství vázání. Pokud je key None, vraťte indextou uloženou hodnotu typu sec_type; jinak vraťte hodnotu spojenou s daným (sec_type, key). Pokud není nic uloženo, vraťte None.	(sec_type, index, key)
_IRQ_SET_SECRET	30	Stack žádá aplikaci, aby trvale uložila tajemství vázání. Po uložení vraťte True.	(sec_type, key, value)
_IRQ_PASSKEY_ACTION	31	Jako součást párování je vyžadována akce s přístupovým kódem (passkey). Odpovězte pomocí gap_passkey; možné akce viz tabulka akcí passkey níže.	(conn_handle, action, passkey)

Pro událost _IRQ_GATTS_READ_REQUEST jsou dostupné tyto návratové kódy:

Konstanta	Hodnota	Význam
_GATTS_NO_ERROR	0x00	Přijmout čtení.
_GATTS_ERROR_READ_NOT_PERMITTED	0x02	Čtení není povoleno.
_GATTS_ERROR_WRITE_NOT_PERMITTED	0x03	Zápis není povolen.
_GATTS_ERROR_INSUFFICIENT_AUTHENTICATION	0x05	Klient není autentizován.
_GATTS_ERROR_INSUFFICIENT_AUTHORIZATION	0x08	Klient nemá oprávnění.
_GATTS_ERROR_INSUFFICIENT_ENCRYPTION	0x0f	Spojení není šifrované.

Pro událost _IRQ_PASSKEY_ACTION jsou dostupné tyto akce:

Konstanta	Hodnota	Význam
_PASSKEY_ACTION_NONE	0	Není vyžadována žádná akce.
_PASSKEY_ACTION_INPUT	2	Vyzve uživatele, aby zadal přístupový kód zobrazený na vzdáleném zařízení.
_PASSKEY_ACTION_DISPLAY	3	Zobrazí 6místný přístupový kód, který má vzdálené zařízení zadat.
_PASSKEY_ACTION_NUMERIC_COMPARISON	4	Potvrdí, že přístupový kód odpovídá tomu zobrazenému na vzdáleném zařízení.

Aby se ušetřilo místo ve firmwaru, nejsou tyto konstanty zahrnuty v modulu bluetooth. Ty, které potřebujete, přidejte z výše uvedených seznamů do svého programu.

Role Broadcaster (Advertiser)

gap_advertise(interval_us: int | None, adv_data: bytes | None = None, *, resp_data: bytes | None = None, connectable: bool = True) → None

Zahájí advertising v zadaném intervalu (v mikrosekundách). Tento interval bude zaokrouhlen dolů na nejbližší násobek 625 us. Pro zastavení advertisingu nastavte interval_us na None.

adv_data a resp_data mohou být libovolného typu, který implementuje buffer protokol (např. bytes, bytearray, str). adv_data je zahrnuto ve všech vysíláních a resp_data se odesílá jako odpověď na aktivní skenování.

Poznámka: pokud je adv_data (nebo resp_data) None, pak se znovu použijí data předaná předchozímu volání gap_advertise. To umožňuje broadcasteru obnovit advertising pouze pomocí gap_advertise(interval_us). Pro vymazání advertising dat předejte prázdné bytes, tj. b''.

Role Observer (Scanner)

gap_scan(duration_ms: int | None, interval_us: int = 1280000, window_us: int = 11250, active: bool = False, /) → None

Spustí skenovací operaci trvající zadanou dobu (v milisekundách).

Pro neomezené skenování nastavte duration_ms na 0.

Pro zastavení skenování nastavte duration_ms na None.

Pomocí interval_us a window_us lze volitelně nakonfigurovat pracovní cyklus (duty cycle). Skener poběží window_us mikrosekund každých interval_us mikrosekund po celkovou dobu duration_ms milisekund. Výchozí interval a okno jsou 1,28 sekundy, resp. 11,25 milisekundy (skenování na pozadí).

Pro každý výsledek skenování bude vyvolána událost _IRQ_SCAN_RESULT s daty události (addr_type, addr, adv_type, rssi, adv_data).

Hodnoty addr_type označují veřejné nebo náhodné adresy:

Hodnota	Název	Význam
0x00	PUBLIC	Veřejná adresa zařízení.
0x01	RANDOM	Náhodná adresa (buď statická, RPA, nebo NRPA; typ je zakódován v samotné adrese).

Hodnoty adv_type odpovídají specifikaci Bluetooth:

Hodnota	Název	Význam
0x00	ADV_IND	Připojitelný a skenovatelný nesměrovaný advertising.
0x01	ADV_DIRECT_IND	Připojitelný směrovaný advertising.
0x02	ADV_SCAN_IND	Skenovatelný nesměrovaný advertising.
0x03	ADV_NONCONN_IND	Nepřipojitelný nesměrovaný advertising.
0x04	SCAN_RSP	Odpověď na skenování.

active lze nastavit na True, pokud chcete přijímat ve výsledcích odpovědi na skenování.

Když je skenování zastaveno (buď z důvodu uplynutí doby trvání, nebo při explicitním zastavení), bude vyvolána událost _IRQ_SCAN_DONE.

Role Central

Zařízení central se může připojit k periferiím, které objevilo pomocí role observer (viz gap_scan) nebo se známou adresou.

gap_connect(addr_type: int | None, addr: bytes | None = None, scan_duration_ms: int = 2000, min_conn_interval_us: int | None = None, max_conn_interval_us: int | None = None, /) → None

Připojí se k periferii.

Podrobnosti o typech adres viz gap_scan.

Pro předčasné zrušení nedokončeného pokusu o spojení zavolejte gap_connect(None).

Při úspěchu bude vyvolána událost _IRQ_PERIPHERAL_CONNECT. Při rušení pokusu o spojení bude vyvolána událost _IRQ_PERIPHERAL_DISCONNECT.

Zařízení bude čekat až scan_duration_ms na přijetí advertising dat od zařízení.

Interval spojení lze nakonfigurovat v mikrosekundách pomocí min_conn_interval_us a/nebo max_conn_interval_us. Jinak bude zvolen výchozí interval, typicky mezi 30000 a 50000 mikrosekundami. Kratší interval zvýší propustnost na úkor spotřeby energie.

Role Peripheral

Od periferního zařízení se očekává, že bude odesílat připojitelné advertisementy (viz gap_advertise). Obvykle bude fungovat jako GATT server, který nejprve zaregistroval služby a charakteristiky pomocí gatts_register_services.

Když se připojí zařízení central, bude vyvolána událost _IRQ_CENTRAL_CONNECT.

Role Central a Peripheral

gap_disconnect(conn_handle: int, /) → bool

Odpojí zadaný handle spojení. Může to být buď zařízení central, které se připojilo k tomuto zařízení (pokud funguje jako periferie), nebo periferie, ke které se toto zařízení dříve připojilo (pokud funguje jako central).

Při úspěchu bude vyvolána událost _IRQ_PERIPHERAL_DISCONNECT nebo _IRQ_CENTRAL_DISCONNECT.

Vrací False, pokud handle spojení nebyl připojen, jinak True.

GATT Server

GATT server má sadu zaregistrovaných služeb. Každá služba může obsahovat charakteristiky, z nichž každá má hodnotu. Charakteristiky mohou také obsahovat deskriptory, které samy mají hodnoty.

Tyto hodnoty jsou uloženy lokálně a přistupuje se k nim pomocí jejich „value handle“, který se generuje během registrace služby. Mohou být také čteny nebo zapisovány vzdáleným klientským zařízením. Server navíc může vzdálenému klientovi „oznámit“ (notify) charakteristiku prostřednictvím handle spojení.

Zařízení v roli central nebo peripheral může fungovat jako GATT server, ve většině případů však bude běžnější, aby jako server fungovalo periferní zařízení.

Charakteristiky a deskriptory mají výchozí maximální velikost 20 bajtů (výchozí ATT MTU 23 bajtů minus 3bajtová hlavička ATT; větší vyjednané MTU samo o sobě tento limit nezvyšuje). Cokoli do nich klient zapíše, bude na tuto délku zkráceno. Jakýkoli lokální zápis však maximální velikost zvýší, takže pokud chcete povolit větší zápisy od klienta do dané charakteristiky, použijte po registraci gatts_write. Např. gatts_write(char_handle, bytes(100)).

gatts_register_services(services_definition: Sequence[Sequence], /) → Sequence[Sequence[int]]

Nakonfiguruje server se zadanými službami a nahradí všechny existující služby.

services_definition je seznam služeb, kde každá služba je dvouprvková n-tice obsahující UUID a seznam charakteristik.

Každá charakteristika je dvou- nebo tříprvková n-tice obsahující UUID, hodnotu flags a volitelně seznam deskriptorů.

Každý deskriptor je dvouprvková n-tice obsahující UUID a hodnotu flags.

flags jsou kombinací příznaků definovaných níže spojených bitovým OR. Nastavují jak chování charakteristiky (nebo deskriptoru), tak požadavky na zabezpečení a soukromí.

Návratovou hodnotou je seznam (jeden prvek na službu) n-tic (každý prvek je value handle). Handly charakteristik a deskriptorů jsou zploštěny do stejné n-tice v pořadí, v jakém jsou definovány.

Následující příklad registruje dvě služby (Heart Rate a Nordic UART):

bt = bluetooth.BLE()
bt.active(True)

# Heart Rate service: one Heart Rate Measurement characteristic.
HR_SERVICE = (
    bluetooth.UUID(0x180D),
    (
        (bluetooth.UUID(0x2A37),
         bluetooth.FLAG_READ | bluetooth.FLAG_NOTIFY),
    ),
)

# Nordic UART service: a TX characteristic the client subscribes
# to for notifications, and an RX characteristic it writes to.
UART_SERVICE = (
    bluetooth.UUID('6E400001-B5A3-F393-E0A9-E50E24DCCA9E'),
    (
        (bluetooth.UUID('6E400003-B5A3-F393-E0A9-E50E24DCCA9E'),
         bluetooth.FLAG_READ | bluetooth.FLAG_NOTIFY),
        (bluetooth.UUID('6E400002-B5A3-F393-E0A9-E50E24DCCA9E'),
         bluetooth.FLAG_WRITE),
    ),
)

((hr,), (tx, rx)) = bt.gatts_register_services(
    (HR_SERVICE, UART_SERVICE),
)

Tři value handly (hr, tx, rx) lze použít s gatts_read, gatts_write, gatts_notify a gatts_indicate.

Poznámka: Před registrací služeb musí být zastaven advertising.

Dostupné příznaky pro charakteristiky a deskriptory jsou:

Konstanta	Hodnota	Význam
_FLAG_BROADCAST	0x0001	Charakteristika může být vysílána (broadcast).
_FLAG_READ	0x0002	Klient může číst hodnotu.
_FLAG_WRITE_NO_RESPONSE	0x0004	Klient může zapisovat bez očekávání odpovědi.
_FLAG_WRITE	0x0008	Klient může zapisovat s potvrzenou odpovědí.
_FLAG_NOTIFY	0x0010	Server může odesílat oznámení (notifications, nepotvrzená).
_FLAG_INDICATE	0x0020	Server může odesílat hlášení (indications, potvrzená).
_FLAG_AUTHENTICATED_SIGNED_WRITE	0x0040	Klient může vydávat podepsané zápisy.
_FLAG_AUX_WRITE	0x0100	Rozšířené vlastnosti: jsou povoleny zápisy do fronty / spolehlivé zápisy.
_FLAG_READ_ENCRYPTED	0x0200	Čtení vyžaduje šifrované spojení.
_FLAG_READ_AUTHENTICATED	0x0400	Čtení vyžaduje autentizované (MITM-chráněné) spojení.
_FLAG_READ_AUTHORIZED	0x0800	Čtení vyžaduje autorizaci na úrovni aplikace.
_FLAG_WRITE_ENCRYPTED	0x1000	Zápis vyžaduje šifrované spojení.
_FLAG_WRITE_AUTHENTICATED	0x2000	Zápis vyžaduje autentizované (MITM-chráněné) spojení.
_FLAG_WRITE_AUTHORIZED	0x4000	Zápis vyžaduje autorizaci na úrovni aplikace.

Stejně jako u konstant událostí výše, ani tyto příznaky nejsou poskytovány modulem bluetooth; zkopírujte si do svého programu ty, které potřebujete.

gatts_read(value_handle: int, /) → bytes

Přečte lokální hodnotu pro tento handle (která byla buď zapsána pomocí gatts_write, nebo vzdáleným klientem).

gatts_write(value_handle: int, data: bytes, send_update: bool = False, /) → None

Zapíše lokální hodnotu pro tento handle, kterou může klient číst.

Pokud je send_update True, pak budou všichni přihlášení (subscribed) klienti o tomto zápisu informováni oznámením (notification) nebo hlášením (indication), v závislosti na tom, k čemu jsou přihlášeni a které operace charakteristika podporuje.

gatts_notify(conn_handle: int, value_handle: int, data: bytes | None = None, /) → None

Odešle požadavek na oznámení (notification) připojenému klientovi.

Pokud je data None (výchozí), pak bude odeslána aktuální lokální hodnota (nastavená pomocí gatts_write).

Jinak, pokud data není None, pak je tato hodnota odeslána klientovi jako součást oznámení. Lokální hodnota nebude změněna.

Poznámka: Oznámení bude odesláno bez ohledu na stav přihlášení klienta k této charakteristice.

gatts_indicate(conn_handle: int, value_handle: int, data: bytes | None = None, /) → None

Odešle požadavek na hlášení (indication) připojenému klientovi.

Pokud je data None (výchozí), pak bude odeslána aktuální lokální hodnota (nastavená pomocí gatts_write).

Jinak, pokud data není None, pak je tato hodnota odeslána klientovi jako součást hlášení. Lokální hodnota nebude změněna.

Při potvrzení (nebo selhání, např. vypršení časového limitu) bude vyvolána událost _IRQ_GATTS_INDICATE_DONE.

Poznámka: Hlášení bude odesláno bez ohledu na stav přihlášení klienta k této charakteristice.

gatts_set_buffer(value_handle: int, len: int, append: bool = False, /) → None

Nastaví velikost interního bufferu pro hodnotu v bajtech. To omezí největší možný zápis, který lze přijmout. Výchozí hodnota je 20 bajtů (výchozí ATT MTU 23 minus 3bajtová hlavička ATT).

Nastavení append na True způsobí, že všechny vzdálené zápisy budou připojovány k aktuální hodnotě, místo aby ji nahrazovaly. Tímto způsobem lze uložit do bufferu nejvýše len bajtů. Když použijete gatts_read, hodnota bude po přečtení vymazána. Tato funkce je užitečná při implementaci něčeho jako Nordic UART Service.

GATT Client

GATT client může objevovat a číst/zapisovat charakteristiky na vzdáleném GATT serveru.

Je běžnější, aby jako GATT client fungovalo zařízení v roli central, je však také možné, aby jako klient fungovala periferie za účelem zjištění informací o zařízení central, které se k ní připojilo (např. pro přečtení názvu zařízení ze služby device information).

gattc_discover_services(conn_handle: int, uuid: UUID | None = None, /) → None

Dotáže se připojeného serveru na jeho služby.

Volitelně zadejte uuid služby pro dotaz pouze na danou službu.

Pro každou objevenou službu bude vyvolána událost _IRQ_GATTC_SERVICE_RESULT, následovaná po dokončení událostí _IRQ_GATTC_SERVICE_DONE.

gattc_discover_characteristics(conn_handle: int, start_handle: int, end_handle: int, uuid: UUID | None = None, /) → None

Dotáže se připojeného serveru na charakteristiky v zadaném rozsahu.

Volitelně zadejte uuid charakteristiky pro dotaz pouze na danou charakteristiku.

Předání start_handle=1 a end_handle=0xffff pokrývá celý rozsah handlů GATT atributů, takže tato kombinace efektivně prohledá každou službu na vzdáleném zařízení.

Pro každou objevenou charakteristiku bude vyvolána událost _IRQ_GATTC_CHARACTERISTIC_RESULT, následovaná po dokončení událostí _IRQ_GATTC_CHARACTERISTIC_DONE.

gattc_discover_descriptors(conn_handle: int, start_handle: int, end_handle: int, /) → None

Dotáže se připojeného serveru na deskriptory v zadaném rozsahu.

Pro každý objevený deskriptor bude vyvolána událost _IRQ_GATTC_DESCRIPTOR_RESULT, následovaná po dokončení událostí _IRQ_GATTC_DESCRIPTOR_DONE.

gattc_read(conn_handle: int, value_handle: int, /) → None

Vydá vzdálené čtení připojenému serveru pro zadaný handle charakteristiky nebo deskriptoru.

Když je hodnota dostupná, bude vyvolána událost _IRQ_GATTC_READ_RESULT, následovaná po dokončení událostí _IRQ_GATTC_READ_DONE.

gattc_write(conn_handle: int, value_handle: int, data: bytes, mode: int = 0, /) → None

Vydá vzdálený zápis připojenému serveru pro zadaný handle charakteristiky nebo deskriptoru.

Argument mode specifikuje chování zápisu, přičemž aktuálně podporované hodnoty jsou:

• mode=0 (výchozí) je zápis bez odpovědi: zápis bude odeslán vzdálenému serveru, ale nebude vráceno žádné potvrzení a nebude vyvolána žádná událost.

• mode=1 je zápis s odpovědí: vzdálený server je požádán, aby odeslal odpověď/potvrzení, že data přijal.

Pokud je od vzdáleného serveru přijata odpověď, bude vyvolána událost _IRQ_GATTC_WRITE_DONE.

gattc_exchange_mtu(conn_handle: int, /) → None

Zahájí výměnu MTU s připojeným serverem za použití preferovaného MTU nastaveného pomocí BLE.config(mtu=value).

Když je výměna MTU dokončena, bude vyvolána událost _IRQ_MTU_EXCHANGED.

Výměnu MTU typicky iniciuje zařízení central; NimBLE podporuje obě role.

L2CAP kanály orientované na spojení

Tato funkce umožňuje výměnu dat mezi dvěma BLE zařízeními podobnou socketům. Jakmile jsou zařízení propojena přes GAP, může kterékoli z nich naslouchat na číselném PSM (Protocol/Service Multiplexer), aby se k němu druhé připojilo.

V daném okamžiku může být aktivní pouze jeden L2CAP kanál (tj. nelze se připojovat během naslouchání).

Aktivní L2CAP kanály jsou identifikovány handlem spojení, na kterém byly navázány, a CID (channel ID).

Kanály orientované na spojení mají vestavěné řízení toku založené na kreditech. Na rozdíl od ATT, kde zařízení vyjednávají sdílené MTU, nastavuje naslouchající i připojující zařízení každé nezávislé MTU, které omezuje maximální množství nevyřízených dat, jež vzdálené zařízení může odeslat dříve, než jsou plně spotřebována v l2cap_recvinto.

l2cap_listen(psm: int, mtu: int, /) → None

Začne naslouchat příchozím požadavkům na L2CAP kanál na zadaném psm s lokálním MTU nastaveným na mtu.

Když vzdálené zařízení iniciuje spojení, bude vyvolána událost _IRQ_L2CAP_ACCEPT, která dává naslouchajícímu serveru možnost příchozí spojení odmítnout (vrácením nenulového celého čísla).

Jakmile je spojení přijato, bude vyvolána událost _IRQ_L2CAP_CONNECT, která serveru umožní získat channel ID (CID) a lokální i vzdálené MTU.

Poznámka: Aktuálně není možné naslouchání zastavit.

l2cap_connect(conn_handle: int, psm: int, mtu: int, /) → None

Připojí se k naslouchajícímu protějšku na zadaném psm s lokálním MTU nastaveným na mtu.

Při úspěšném spojení bude vyvolána událost _IRQ_L2CAP_CONNECT, která klientovi umožní získat CID a lokální i vzdálené (peer) MTU.

Neúspěšné spojení vyvolá událost _IRQ_L2CAP_DISCONNECT s nenulovým stavem.

l2cap_disconnect(conn_handle: int, cid: int, /) → None

Odpojí aktivní L2CAP kanál se zadaným conn_handle a cid.

l2cap_send(conn_handle: int, cid: int, buf: bytes, /) → bool

Odešle zadaný buf (který musí podporovat buffer protokol) na L2CAP kanálu identifikovaném pomocí conn_handle a cid.

Buffer musí splňovat oba limity: nesmí překročit vzdálené (peer) MTU a nesmí překročit dvojnásobek lokálního MTU.

Toto vrátí False, pokud je kanál nyní „zaseknutý“ (stalled), což znamená, že l2cap_send nesmí být znovu voláno, dokud není přijata událost _IRQ_L2CAP_SEND_READY (k čemuž dojde, když vzdálené zařízení udělí více kreditů, typicky poté, co data přijalo a zpracovalo).

l2cap_recvinto(conn_handle: int, cid: int, buf: Any | None, /) → int

Přijme data ze zadaného conn_handle a cid do poskytnutého buf (který musí podporovat buffer protokol, např. bytearray nebo memoryview).

Vrací počet bajtů přečtených z kanálu.

Pokud je buf None, pak vrací počet dostupných bajtů.

Poznámka: Po přijetí události _IRQ_L2CAP_RECV by aplikace měla nadále volat l2cap_recvinto, dokud nejsou v přijímacím bufferu dostupné žádné další bajty (typicky až do velikosti vzdáleného (peer) MTU).

Dokud není přijímací buffer prázdný, vzdálenému zařízení nebudou uděleny žádné další kanálové kredity a nebude moci odeslat žádná další data.

Párování a vázání (Pairing and Bonding)

Párování umožňuje, aby bylo spojení šifrované a autentizované prostřednictvím výměny tajemství (s volitelnou ochranou MITM pomocí autentizace přístupovým kódem).

Vázání (bonding) je proces ukládání těchto tajemství do trvalého úložiště. Po navázání (bonded) je zařízení schopno rozlišit rozlišitelnou soukromou adresu (RPA) jiného zařízení na základě uloženého identity resolving key (IRK). Pro podporu vázání musí aplikace implementovat události _IRQ_GET_SECRET a _IRQ_SET_SECRET.

gap_pair(conn_handle: int, /) → None

Zahájí párování se vzdáleným zařízením.

Před voláním tohoto se ujistěte, že jsou nastaveny konfigurační možnosti io, mitm, le_secure a bond (pomocí config).

Při úspěšném párování bude vyvolána událost _IRQ_ENCRYPTION_UPDATE.

gap_passkey(conn_handle: int, action: int, passkey: int, /) → None

Odpoví na událost _IRQ_PASSKEY_ACTION pro zadané conn_handle a action. Význam passkey závisí na action (které zase závisí na nakonfigurované I/O schopnosti):

Akce	Požadovaná odpověď passkey
_PASSKEY_ACTION_INPUT	Přístupový kód, který uživatel přečte ze vzdáleného zařízení.
_PASSKEY_ACTION_DISPLAY	Lokálně vygenerovaný náhodný 6místný přístupový kód zobrazený uživateli.
_PASSKEY_ACTION_NUMERIC_COMPARISON	1 pro přijetí přístupového kódu zobrazeného v události _IRQ_PASSKEY_ACTION, nebo 0 pro zrušení párování.

class UUID

class bluetooth.UUID(value: int | bytes | str, /)

Vytvoří instanci UUID se zadanou hodnotou value. Bluetooth používá tři šířky UUID; UUID přijímá kteroukoli z nich:

Šířka UUID	Přijímané typy value	Příklad
16bitové	int nebo 2bajtový buffer (little-endian)	UUID(0x2908) nebo UUID(b'\x08\x29')
32bitové	4bajtový buffer (little-endian)	UUID(b'\x08\x29\x00\x00')
128bitové	16bajtový buffer nebo řetězec s pomlčkami	UUID('6E400001-B5A3-F393-E0A9-E50E24DCCA9E')

16- a 32bitová UUID jsou typicky identifikátory přidělené SIG (viz přidělená čísla Bluetooth); 128bitová UUID jsou obvykle definována dodavatelem.