`bluetooth` — niskorazinski Bluetooth¶

Ovaj modul pruža sučelje prema ugrađenom Bluetooth kontroleru. Podržava Bluetooth Low Energy (BLE) u ulogama Central, Peripheral, Broadcaster i Observer, kao i GATT poslužitelj i klijent te L2CAP veze orijentirane na vezu (connection-oriented kanali). Uređaj može istodobno raditi u više uloga. Također su podržani uparivanje (pairing) i povezivanje (bonding).

Ovaj API je osmišljen tako da odgovara niskorazinskom Bluetooth protokolu i pruža gradivne blokove za apstrakcije više razine, poput specifičnih tipova uređaja.

Savjet

Za većinu aplikacija preporučljivo je koristiti biblioteku više razine aioble, koja pruža omotač temeljen na asyncio oko ovog modula. Pogledajte aioble — Asinkroni BLE.

class BLE¶

class bluetooth.BLE¶

Vraća singleton BLE objekt.

Konfiguracija

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

Po izboru mijenja aktivno stanje BLE radija i vraća trenutno stanje.

Radio mora biti aktiviran prije korištenja bilo koje druge metode ove klase.

config(param: str, /) → Any¶

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

Dohvaća ili postavlja konfiguracijske vrijednosti BLE sučelja. Za dohvaćanje vrijednosti naziv parametra treba navesti kao niz pod navodnicima, a istodobno se dohvaća samo jedan parametar. Za postavljanje vrijednosti koristite sintaksu ključnih riječi, pri čemu se istodobno može postaviti jedan ili više parametara.

Trenutno podržane vrijednosti su:

'mac': Trenutno korištena adresa, ovisno o trenutnom načinu adresiranja. Vraća n-torku (addr_type, addr).

Pogledajte gap_scan za pojedinosti o tipu adrese.

Ovo se može dohvatiti samo dok je sučelje trenutno aktivno.

'addr_mode': Postavlja način adresiranja. Vrijednosti su:

Vrijednost	Naziv	Ponašanje
`0x00`	PUBLIC	Koristi javnu adresu kontrolera.
`0x01`	RANDOM	Koristi generiranu statičku adresu.
`0x02`	RPA	Koristi razrješive privatne adrese (resolvable private addresses).
`0x03`	NRPA	Koristi nerazrješive privatne adrese (non-resolvable private addresses).

Prema zadanim postavkama sučelje će koristiti PUBLIC adresu ako je dostupna, a u suprotnom će koristiti RANDOM adresu.

'gap_name': Dohvaća/postavlja GAP naziv uređaja koji koristi Generic Access usluga (UUID 0x1800), karakteristika Device Name (UUID 0x2a00). Ovo se može postaviti u bilo kojem trenutku i mijenjati više puta.
'rxbuf': Dohvaća/postavlja veličinu u bajtovima internog međuspremnika koji se koristi za pohranu dolaznih događaja. Ovaj je međuspremnik globalan za cijeli BLE upravljački program i stoga obrađuje dolazne podatke za sve događaje, uključujući sve karakteristike. Povećavanjem se omogućuje bolja obrada naglih navala dolaznih podataka (na primjer rezultata skeniranja) te mogućnost primanja većih vrijednosti karakteristika.
'mtu': Dohvaća/postavlja MTU koji će se koristiti tijekom ATT MTU razmjene. Rezultirajući MTU bit će minimum ove vrijednosti i MTU-a udaljenog uređaja. ATT MTU razmjena neće se dogoditi automatski (osim ako je udaljeni uređaj ne pokrene) te se mora ručno pokrenuti pomoću gattc_exchange_mtu. Koristite događaj _IRQ_MTU_EXCHANGED za otkrivanje MTU-a za danu vezu.
'bond': Postavlja hoće li povezivanje (bonding) biti omogućeno tijekom uparivanja. Kada je omogućeno, zahtjevi za uparivanje postavit će zastavicu „bond” i oba uređaja pohranit će ključeve.
'mitm': Postavlja je li za uparivanje potrebna MITM zaštita.

'io': Postavlja U/I (I/O) mogućnosti ovog uređaja.

Dostupne opcije su:

Konstanta	Vrijednost	Mogućnost
`_IO_CAPABILITY_DISPLAY_ONLY`	0	Samo prikaz
`_IO_CAPABILITY_DISPLAY_YESNO`	1	Prikaz s da/ne unosom
`_IO_CAPABILITY_KEYBOARD_ONLY`	2	Samo tipkovnica
`_IO_CAPABILITY_NO_INPUT_OUTPUT`	3	Bez ulaza ili izlaza
`_IO_CAPABILITY_KEYBOARD_DISPLAY`	4	Tipkovnica i prikaz

'le_secure': Postavlja je li potrebno „LE Secure” uparivanje. Zadano je false (tj. dopušteno je „Legacy Pairing”).

Obrada događaja

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

Registrira povratni poziv za događaje iz BLE skupa (stack). handler prima dva argumenta, event (koji će biti jedan od kodova navedenih u nastavku) i data (što je n-torka vrijednosti specifična za događaj).

Napomena: Kao optimizacija radi sprječavanja nepotrebnih alokacija, unosi addr, adv_data, char_data, notify_data i uuid u n-torkama su instance memoryview samo za čitanje koje pokazuju na interni kružni međuspremnik (ringbuffer) modula bluetooth i valjani su samo tijekom poziva IRQ handler funkcije. Ako vaš program treba spremiti jednu od tih vrijednosti kako bi joj pristupio nakon što se IRQ handler vrati (npr. spremanjem u instancu klase ili globalnu varijablu), tada treba napraviti kopiju podataka, bilo pomoću bytes() ili bluetooth.UUID(), ovako:

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

Na primjer, IRQ handler za rezultat skeniranja mogao bi pregledati adv_data kako bi odlučio je li to ispravan uređaj te tek tada kopirati podatke o adresi za korištenje drugdje u programu. Za ispis podataka iz samog IRQ handlera bit će potreban print(bytes(addr)).

Handler tipično grana izvođenje prema kodu događaja i raspakirava n-torku korisnog tereta (payload) specifičnu za događaj:

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

Svaki kod događaja, koristan teret (payload) koji isporučuje i kratki opis navedeni su u nastavku. Za događaje kod kojih se spominje polje status, status je 0 u slučaju uspjeha i nenulta vrijednost specifična za implementaciju u slučaju neuspjeha.

Konstanta	Vrijednost	Događaj	N-torka korisnog tereta
`_IRQ_CENTRAL_CONNECT`	1	Central se povezao s ovim periferalom.	`(conn_handle, addr_type, addr)`
`_IRQ_CENTRAL_DISCONNECT`	2	Central se odspojio s ovog periferala.	`(conn_handle, addr_type, addr)`
`_IRQ_GATTS_WRITE`	3	Povezani klijent zapisao je u lokalnu karakteristiku ili deskriptor. Koristite `gatts_read` za dohvaćanje nove vrijednosti.	`(conn_handle, attr_handle)`
`_IRQ_GATTS_READ_REQUEST`	4	Povezani klijent izdao je zahtjev za čitanje. Vratite nenulti kod pogreške iz tablice u nastavku da biste odbili čitanje ili `0` / `None` da biste ga prihvatili.	`(conn_handle, attr_handle)`
`_IRQ_SCAN_RESULT`	5	Tijekom aktivnog skeniranja primljen je jedan oglasni paket (advertising packet).	`(addr_type, addr, adv_type, rssi, adv_data)`
`_IRQ_SCAN_DONE`	6	Trenutno skeniranje je završilo, bilo zato što je isteklo konfigurirano trajanje ili zato što je pozvan `gap_scan(None)`.	`()`
`_IRQ_PERIPHERAL_CONNECT`	7	Prethodno izdani `gap_connect` je uspio.	`(conn_handle, addr_type, addr)`
`_IRQ_PERIPHERAL_DISCONNECT`	8	Povezani periferal se odspojio.	`(conn_handle, addr_type, addr)`
`_IRQ_GATTC_SERVICE_RESULT`	9	Jedna usluga pronađena je pomoću `gattc_discover_services`.	`(conn_handle, start_handle, end_handle, uuid)`
`_IRQ_GATTC_SERVICE_DONE`	10	Otkrivanje usluga je završilo.	`(conn_handle, status)`
`_IRQ_GATTC_CHARACTERISTIC_RESULT`	11	Jedna karakteristika pronađena je pomoću `gattc_discover_characteristics`.	`(conn_handle, end_handle, value_handle, properties, uuid)`
`_IRQ_GATTC_CHARACTERISTIC_DONE`	12	Otkrivanje karakteristika je završilo.	`(conn_handle, status)`
`_IRQ_GATTC_DESCRIPTOR_RESULT`	13	Jedan deskriptor pronađen je pomoću `gattc_discover_descriptors`.	`(conn_handle, dsc_handle, uuid)`
`_IRQ_GATTC_DESCRIPTOR_DONE`	14	Otkrivanje deskriptora je završilo.	`(conn_handle, status)`
`_IRQ_GATTC_READ_RESULT`	15	Prethodno izdani `gattc_read` vratio je podatke.	`(conn_handle, value_handle, char_data)`
`_IRQ_GATTC_READ_DONE`	16	Prethodno izdani `gattc_read` je završio.	`(conn_handle, value_handle, status)`
`_IRQ_GATTC_WRITE_DONE`	17	Prethodno izdani `gattc_write` je potvrđen.	`(conn_handle, value_handle, status)`
`_IRQ_GATTC_NOTIFY`	18	Udaljeni poslužitelj poslao je (nepotvrđenu) obavijest.	`(conn_handle, value_handle, notify_data)`
`_IRQ_GATTC_INDICATE`	19	Udaljeni poslužitelj poslao je (potvrđenu) indikaciju.	`(conn_handle, value_handle, notify_data)`
`_IRQ_GATTS_INDICATE_DONE`	20	Prethodno poslanu indikaciju klijent je potvrdio (ili je isteklo vrijeme).	`(conn_handle, value_handle, status)`
`_IRQ_MTU_EXCHANGED`	21	ATT MTU razmjena je dovršena (pokrenuta od bilo koje strane).	`(conn_handle, mtu)`
`_IRQ_L2CAP_ACCEPT`	22	Udaljeni uređaj zatražio je L2CAP vezu na PSM-u koji ovaj uređaj osluškuje. Vratite nenulti cijeli broj za odbijanje ili `0` / `None` za prihvaćanje.	`(conn_handle, cid, psm, our_mtu, peer_mtu)`
`_IRQ_L2CAP_CONNECT`	23	L2CAP kanal je sada uspostavljen, bilo prihvaćanjem dolaznog zahtjeva ili dovršavanjem odlaznog `l2cap_connect`.	`(conn_handle, cid, psm, our_mtu, peer_mtu)`
`_IRQ_L2CAP_DISCONNECT`	24	L2CAP kanal je odspojen. `status` je `0` za čisto odspajanje ili nenulti ako odlazni pokušaj povezivanja nije uspio.	`(conn_handle, cid, psm, status)`
`_IRQ_L2CAP_RECV`	25	Podaci su stigli na L2CAP kanal. Pozovite `l2cap_recvinto` za njihovo čitanje.	`(conn_handle, cid)`
`_IRQ_L2CAP_SEND_READY`	26	Prethodni `l2cap_send` koji je vratio `False` se ispraznio i kanal je ponovno spreman. Nenulti `status` znači da se međuspremnik za slanje prepunio i aplikacija mora ponovno poslati podatke.	`(conn_handle, cid, status)`
`_IRQ_CONNECTION_UPDATE`	27	Udaljeni uređaj ažurirao je parametre veze (interval, latency, supervision timeout).	`(conn_handle, conn_interval, conn_latency, supervision_timeout, status)`
`_IRQ_ENCRYPTION_UPDATE`	28	Stanje enkripcije veze se promijenilo, tipično nakon dovršetka uparivanja ili povezivanja.	`(conn_handle, encrypted, authenticated, bonded, key_size)`
`_IRQ_GET_SECRET`	29	Skup (stack) zahtijeva pohranjenu tajnu povezivanja (bonding secret). Ako je `key` jednak `None`, vratite `index`-tu pohranjenu vrijednost tipa `sec_type`; u suprotnom vratite vrijednost povezanu s danim `(sec_type, key)`. Vratite `None` ako ništa nije pohranjeno.	`(sec_type, index, key)`
`_IRQ_SET_SECRET`	30	Skup (stack) traži od aplikacije da trajno pohrani tajnu povezivanja (bonding secret). Vratite `True` nakon pohrane.	`(sec_type, key, value)`
`_IRQ_PASSKEY_ACTION`	31	Kao dio uparivanja potrebna je radnja s pristupnim ključem (passkey). Odgovorite pomoću `gap_passkey`; pogledajte tablicu radnji s pristupnim ključem u nastavku za moguće radnje.	`(conn_handle, action, passkey)`

Za događaj _IRQ_GATTS_READ_REQUEST dostupni povratni kodovi su:

Konstanta	Vrijednost	Značenje
`_GATTS_NO_ERROR`	`0x00`	Prihvati čitanje.
`_GATTS_ERROR_READ_NOT_PERMITTED`	`0x02`	Čitanje nije dopušteno.
`_GATTS_ERROR_WRITE_NOT_PERMITTED`	`0x03`	Pisanje nije dopušteno.
`_GATTS_ERROR_INSUFFICIENT_AUTHENTICATION`	`0x05`	Klijent nije autentificiran.
`_GATTS_ERROR_INSUFFICIENT_AUTHORIZATION`	`0x08`	Klijent nije ovlašten.
`_GATTS_ERROR_INSUFFICIENT_ENCRYPTION`	`0x0f`	Veza nije šifrirana.

Za događaj _IRQ_PASSKEY_ACTION dostupne radnje su:

Konstanta	Vrijednost	Značenje
`_PASSKEY_ACTION_NONE`	0	Nije potrebna radnja.
`_PASSKEY_ACTION_INPUT`	2	Zatraži od korisnika da unese pristupni ključ (passkey) prikazan na udaljenom uređaju.
`_PASSKEY_ACTION_DISPLAY`	3	Prikaži 6-znamenkasti pristupni ključ (passkey) koji udaljeni uređaj treba unijeti.
`_PASSKEY_ACTION_NUMERIC_COMPARISON`	4	Potvrdi da se pristupni ključ (passkey) podudara s onim prikazanim na udaljenom uređaju.

Kako bi se uštedio prostor u ugrađenom programu (firmware), ove konstante nisu uključene u modul bluetooth. Dodajte one koje su vam potrebne iz gornjih popisa u svoj program.

Broadcaster uloga (oglašivač)

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

Započinje oglašavanje na navedenom intervalu (u mikrosekundama). Ovaj će interval biti zaokružen prema dolje na najbližih 625us. Za zaustavljanje oglašavanja postavite interval_us na None.

adv_data i resp_data mogu biti bilo koji tip koji implementira buffer protokol (npr. bytes, bytearray, str). adv_data je uključen u sva odašiljanja, a resp_data se šalje kao odgovor na aktivno skeniranje.

Napomena: ako je adv_data (ili resp_data) jednak None, tada će se ponovno upotrijebiti podaci proslijeđeni prethodnom pozivu gap_advertise. To omogućuje oglašivaču da nastavi oglašavanje samo s gap_advertise(interval_us). Za brisanje korisnog tereta (payload) oglašavanja proslijedite prazan bytes, tj. b''.

Observer uloga (skener)

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

Pokreće operaciju skeniranja koja traje navedeno vrijeme (u milisekundama).

Za neograničeno skeniranje postavite duration_ms na 0.

Za zaustavljanje skeniranja postavite duration_ms na None.

Koristite interval_us i window_us za opcionalno konfiguriranje radnog ciklusa (duty cycle). Skener će raditi window_us mikrosekundi svakih interval_us mikrosekundi, ukupno tijekom duration_ms milisekundi. Zadani interval i prozor su 1,28 sekundi odnosno 11,25 milisekundi (skeniranje u pozadini).

Za svaki rezultat skeniranja podići će se događaj _IRQ_SCAN_RESULT s podacima događaja (addr_type, addr, adv_type, rssi, adv_data).

Vrijednosti addr_type označavaju javne ili nasumične adrese:

Vrijednost	Naziv	Značenje
`0x00`	PUBLIC	Javna adresa uređaja.
`0x01`	RANDOM	Nasumična adresa (statička, RPA ili NRPA; tip je kodiran u samoj adresi).

Vrijednosti adv_type odgovaraju Bluetooth specifikaciji:

Vrijednost	Naziv	Značenje
`0x00`	ADV_IND	Povezivo i skenirajuće neusmjereno oglašavanje.
`0x01`	ADV_DIRECT_IND	Povezivo usmjereno oglašavanje.
`0x02`	ADV_SCAN_IND	Skenirajuće neusmjereno oglašavanje.
`0x03`	ADV_NONCONN_IND	Nepovezivo neusmjereno oglašavanje.
`0x04`	SCAN_RSP	Odgovor na skeniranje.

active se može postaviti na True ako želite primati odgovore na skeniranje u rezultatima.

Kada se skeniranje zaustavi (bilo zbog isteka trajanja ili eksplicitnog zaustavljanja), podići će se događaj _IRQ_SCAN_DONE.

Central uloga

Central uređaj može se povezati s periferalima koje je otkrio koristeći observer ulogu (pogledajte gap_scan) ili s poznatom adresom.

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¶

Povezuje se s periferalom.

Pogledajte gap_scan za pojedinosti o tipovima adresa.

Za rano otkazivanje neriješenog pokušaja povezivanja pozovite gap_connect(None).

U slučaju uspjeha podići će se događaj _IRQ_PERIPHERAL_CONNECT. Ako se otkazuje pokušaj povezivanja, podići će se događaj _IRQ_PERIPHERAL_DISCONNECT.

Uređaj će čekati do scan_duration_ms da primi korisni teret (payload) oglašavanja od uređaja.

Interval veze može se konfigurirati u mikrosekundama korištenjem jednog ili oba parametra min_conn_interval_us i max_conn_interval_us. U suprotnom će se odabrati zadani interval, tipično između 30000 i 50000 mikrosekundi. Kraći interval povećat će propusnost, ali na štetu potrošnje energije.

Peripheral uloga

Od periferalnog uređaja očekuje se da šalje poveziva oglašavanja (pogledajte gap_advertise). Obično će djelovati kao GATT poslužitelj, nakon što je prvo registrirao usluge i karakteristike pomoću gatts_register_services.

Kada se central poveže, podići će se događaj _IRQ_CENTRAL_CONNECT.

Central i Peripheral uloge

gap_disconnect(conn_handle: int, /) → bool¶

Odspaja navedeni handle veze. Ovo može biti central koji se povezao s ovim uređajem (ako djeluje kao periferal) ili periferal s kojim se ovaj uređaj prethodno povezao (ako djeluje kao central).

U slučaju uspjeha podići će se događaj _IRQ_PERIPHERAL_DISCONNECT ili _IRQ_CENTRAL_DISCONNECT.

Vraća False ako handle veze nije bio povezan, a inače True.

GATT poslužitelj

GATT poslužitelj ima skup registriranih usluga. Svaka usluga može sadržavati karakteristike, od kojih svaka ima vrijednost. Karakteristike također mogu sadržavati deskriptore, koji i sami imaju vrijednosti.

Te vrijednosti pohranjuju se lokalno, a pristupa im se putem njihovog „value handle” koji se generira tijekom registracije usluge. Također ih može čitati ili u njih pisati udaljeni klijentski uređaj. Dodatno, poslužitelj može „obavijestiti” povezanog klijenta o karakteristici putem handle veze.

Uređaj u central ili peripheral ulozi može funkcionirati kao GATT poslužitelj, no u većini će slučajeva biti uobičajenije da periferalni uređaj djeluje kao poslužitelj.

Karakteristike i deskriptori imaju zadanu maksimalnu veličinu od 20 bajtova (zadani ATT MTU od 23 bajta umanjen za 3-bajtno ATT zaglavlje; veći dogovoreni MTU sam po sebi ne podiže ovo ograničenje). Sve što klijent u njih zapiše bit će skraćeno na tu duljinu. Međutim, svaki lokalni upis povećat će maksimalnu veličinu, pa ako želite dopustiti veće upise od klijenta u danu karakteristiku, koristite gatts_write nakon registracije. Npr. gatts_write(char_handle, bytes(100)).

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

Konfigurira poslužitelj s navedenim uslugama, zamjenjujući sve postojeće usluge.

services_definition je popis usluga, gdje je svaka usluga dvoelementna n-torka koja sadrži UUID i popis karakteristika.

Svaka karakteristika je n-torka s dva ili tri elementa koja sadrži UUID, vrijednost flags i opcionalno popis deskriptora.

Svaki deskriptor je dvoelementna n-torka koja sadrži UUID i vrijednost flags.

flags su kombinacija zastavica definiranih u nastavku pomoću bitovnog OR-a. One postavljaju i ponašanje karakteristike (ili deskriptora) te zahtjeve sigurnosti i privatnosti.

Povratna vrijednost je popis (jedan element po usluzi) n-torki (svaki je element value handle). Handlevi karakteristika i deskriptora spljošteni su u istu n-torku, redoslijedom kojim su definirani.

Sljedeći primjer registrira dvije usluge (Heart Rate i 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),
)

Tri value handlea (hr, tx, rx) mogu se koristiti s gatts_read, gatts_write, gatts_notify i gatts_indicate.

Napomena: Oglašavanje se mora zaustaviti prije registracije usluga.

Dostupne zastavice za karakteristike i deskriptore su:

Konstanta	Vrijednost	Značenje
`_FLAG_BROADCAST`	`0x0001`	Karakteristika se može odašiljati.
`_FLAG_READ`	`0x0002`	Klijent može čitati vrijednost.
`_FLAG_WRITE_NO_RESPONSE`	`0x0004`	Klijent može pisati bez očekivanja odgovora.
`_FLAG_WRITE`	`0x0008`	Klijent može pisati s potvrđenim odgovorom.
`_FLAG_NOTIFY`	`0x0010`	Poslužitelj može slati obavijesti (nepotvrđene).
`_FLAG_INDICATE`	`0x0020`	Poslužitelj može slati indikacije (potvrđene).
`_FLAG_AUTHENTICATED_SIGNED_WRITE`	`0x0040`	Klijent može izdavati potpisane upise.
`_FLAG_AUX_WRITE`	`0x0100`	Proširena svojstva: dopušteni su upisi u redu čekanja / pouzdani upisi.
`_FLAG_READ_ENCRYPTED`	`0x0200`	Čitanje zahtijeva šifriranu vezu.
`_FLAG_READ_AUTHENTICATED`	`0x0400`	Čitanje zahtijeva autentificiranu (MITM-zaštićenu) vezu.
`_FLAG_READ_AUTHORIZED`	`0x0800`	Čitanje zahtijeva ovlaštenje na razini aplikacije.
`_FLAG_WRITE_ENCRYPTED`	`0x1000`	Pisanje zahtijeva šifriranu vezu.
`_FLAG_WRITE_AUTHENTICATED`	`0x2000`	Pisanje zahtijeva autentificiranu (MITM-zaštićenu) vezu.
`_FLAG_WRITE_AUTHORIZED`	`0x4000`	Pisanje zahtijeva ovlaštenje na razini aplikacije.

Kao i kod gornjih konstanti događaja, ove zastavice ne pruža modul bluetooth; kopirajte one koje su vam potrebne u svoj program.

gatts_read(value_handle: int, /) → bytes¶: Čita lokalnu vrijednost za ovaj handle (koja je zapisana ili pomoću gatts_write ili od strane udaljenog klijenta).

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

Zapisuje lokalnu vrijednost za ovaj handle, koju klijent može pročitati.

Ako je send_update jednak True, tada će svi pretplaćeni klijenti biti obaviješteni (ili će im biti indicirano, ovisno o tome na što su pretplaćeni i koje operacije karakteristika podržava) o ovom upisu.

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

Šalje zahtjev za obavijest povezanom klijentu.

Ako je data jednak None (zadano), tada će se poslati trenutna lokalna vrijednost (kako je postavljena s gatts_write).

U suprotnom, ako data nije None, tada se ta vrijednost šalje klijentu kao dio obavijesti. Lokalna vrijednost neće se mijenjati.

Napomena: Obavijest će se poslati bez obzira na status pretplate klijenta na ovu karakteristiku.

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

Šalje zahtjev za indikaciju povezanom klijentu.

Ako je data jednak None (zadano), tada će se poslati trenutna lokalna vrijednost (kako je postavljena s gatts_write).

U suprotnom, ako data nije None, tada se ta vrijednost šalje klijentu kao dio indikacije. Lokalna vrijednost neće se mijenjati.

Po potvrdi (ili neuspjehu, npr. isteku vremena) podići će se događaj _IRQ_GATTS_INDICATE_DONE.

Napomena: Indikacija će se poslati bez obzira na status pretplate klijenta na ovu karakteristiku.

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

Postavlja veličinu internog međuspremnika za vrijednost u bajtovima. To će ograničiti najveći mogući upis koji se može primiti. Zadano je 20 bajtova (zadani ATT MTU od 23 umanjen za 3-bajtno ATT zaglavlje).

Postavljanje append na True učinit će da se svi udaljeni upisi dodaju trenutnoj vrijednosti, umjesto da je zamijene. Na ovaj se način može međuspremiti najviše len bajtova. Kada koristite gatts_read, vrijednost će biti obrisana nakon čitanja. Ova je značajka korisna pri implementaciji nečega poput Nordic UART usluge.

GATT klijent

GATT klijent može otkrivati i čitati/pisati karakteristike na udaljenom GATT poslužitelju.

Uobičajenije je da uređaj u central ulozi djeluje kao GATT klijent, no također je moguće da periferal djeluje kao klijent kako bi otkrio informacije o centralu koji se s njim povezao (npr. za čitanje naziva uređaja iz usluge informacija o uređaju).

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

Upituje povezani poslužitelj o njegovim uslugama.

Po izboru navedite uuid usluge za upit samo o toj usluzi.

Za svaku otkrivenu uslugu podići će se događaj _IRQ_GATTC_SERVICE_RESULT, a po dovršetku _IRQ_GATTC_SERVICE_DONE.

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

Upituje povezani poslužitelj o karakteristikama u navedenom rasponu.

Po izboru navedite uuid karakteristike za upit samo o toj karakteristici.

Prosljeđivanje start_handle=1 i end_handle=0xffff pokriva cijeli raspon GATT handleva atributa, pa ova kombinacija zapravo pretražuje svaku uslugu na udaljenom uređaju.

Za svaku otkrivenu karakteristiku podići će se događaj _IRQ_GATTC_CHARACTERISTIC_RESULT, a po dovršetku _IRQ_GATTC_CHARACTERISTIC_DONE.

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

Upituje povezani poslužitelj o deskriptorima u navedenom rasponu.

Za svaki otkriveni deskriptor podići će se događaj _IRQ_GATTC_DESCRIPTOR_RESULT, a po dovršetku _IRQ_GATTC_DESCRIPTOR_DONE.

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

Izdaje udaljeno čitanje povezanom poslužitelju za navedeni handle karakteristike ili deskriptora.

Kada vrijednost postane dostupna, podići će se događaj _IRQ_GATTC_READ_RESULT, a po dovršetku _IRQ_GATTC_READ_DONE.

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

Izdaje udaljeni upis povezanom poslužitelju za navedeni handle karakteristike ili deskriptora.

Argument mode određuje ponašanje upisa, pri čemu su trenutno podržane vrijednosti:

mode=0 (zadano) je upis bez odgovora (write-without-response): upis će biti poslan udaljenom poslužitelju, ali neće se vratiti potvrda i neće se podići nijedan događaj.

mode=1 je upis s odgovorom (write-with-response): od udaljenog poslužitelja zahtijeva se da pošalje odgovor/potvrdu da je primio podatke.

Ako se od udaljenog poslužitelja primi odgovor, podići će se događaj _IRQ_GATTC_WRITE_DONE.

gattc_exchange_mtu(conn_handle: int, /) → None¶

Pokreće MTU razmjenu s povezanim poslužiteljem, koristeći preferirani MTU postavljen pomoću BLE.config(mtu=value).

Događaj _IRQ_MTU_EXCHANGED podići će se kada MTU razmjena završi.

MTU razmjenu tipično pokreće central; NimBLE podržava obje uloge.

L2CAP kanali orijentirani na vezu (connection-oriented)

Ova značajka omogućuje razmjenu podataka sličnu socketima između dva BLE uređaja. Nakon što su uređaji povezani putem GAP-a, bilo koji uređaj može osluškivati da se drugi poveže na numeričkom PSM-u (Protocol/Service Multiplexer).

Istodobno može biti aktivan samo jedan L2CAP kanal (tj. ne možete se povezivati dok osluškujete).

Aktivni L2CAP kanali identificiraju se prema handleu veze na kojem su uspostavljeni i prema CID-u (channel ID).

Kanali orijentirani na vezu imaju ugrađenu kontrolu protoka temeljenu na kreditima (credit-based flow control). Za razliku od ATT-a, gdje uređaji dogovaraju zajednički MTU, i uređaj koji osluškuje i onaj koji se povezuje svaki postavljaju neovisan MTU koji ograničava maksimalnu količinu neobrađenih podataka koje udaljeni uređaj može poslati prije nego što se u potpunosti potroše u l2cap_recvinto.

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

Započinje osluškivanje dolaznih zahtjeva za L2CAP kanal na navedenom psm s lokalnim MTU-om postavljenim na mtu.

Kada udaljeni uređaj pokrene vezu, podići će se događaj _IRQ_L2CAP_ACCEPT, koji poslužitelju koji osluškuje daje priliku da odbije dolaznu vezu (vraćanjem nenultog cijelog broja).

Nakon što se veza prihvati, podići će se događaj _IRQ_L2CAP_CONNECT, omogućujući poslužitelju da dobije channel ID (CID) te lokalni i udaljeni MTU.

Napomena: Trenutno nije moguće zaustaviti osluškivanje.

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

Povezuje se s peerom koji osluškuje na navedenom psm s lokalnim MTU-om postavljenim na mtu.

Po uspješnom povezivanju podići će se događaj _IRQ_L2CAP_CONNECT, omogućujući klijentu da dobije CID te lokalni i udaljeni (peer) MTU.

Neuspješno povezivanje podići će događaj _IRQ_L2CAP_DISCONNECT s nenultim statusom.

l2cap_disconnect(conn_handle: int, cid: int, /) → None¶: Odspaja aktivni L2CAP kanal s navedenim conn_handle i cid.

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

Šalje navedeni buf (koji mora podržavati buffer protokol) na L2CAP kanalu identificiranom pomoću conn_handle i cid.

Međuspremnik mora zadovoljiti oba ograničenja: ne smije premašiti udaljeni (peer) MTU i ne smije premašiti dvostruki lokalni MTU.

Ovo će vratiti False ako je kanal sada „zaustavljen” (stalled), što znači da se l2cap_send ne smije ponovno pozvati dok se ne primi događaj _IRQ_L2CAP_SEND_READY (što će se dogoditi kada udaljeni uređaj dodijeli više kredita, tipično nakon što je primio i obradio podatke).

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

Prima podatke s navedenih conn_handle i cid u priloženi buf (koji mora podržavati buffer protokol, npr. bytearray ili memoryview).

Vraća broj bajtova pročitanih s kanala.

Ako je buf jednak None, tada vraća broj dostupnih bajtova.

Napomena: Nakon primanja događaja _IRQ_L2CAP_RECV, aplikacija treba nastaviti pozivati l2cap_recvinto dok u prijemnom međuspremniku više nema dostupnih bajtova (tipično do veličine udaljenog (peer) MTU-a).

Dok prijemni međuspremnik nije prazan, udaljenom uređaju neće biti dodijeljeno više kreditâ kanala i neće moći slati više podataka.

Uparivanje i povezivanje (pairing i bonding)

Uparivanje omogućuje da veza bude šifrirana i autentificirana razmjenom tajni (uz opcionalnu MITM zaštitu putem autentifikacije pristupnim ključem).

Povezivanje (bonding) je proces pohranjivanja tih tajni u nepostojanu pohranu. Kada je povezan, uređaj može razriješiti razrješivu privatnu adresu (RPA) drugog uređaja na temelju pohranjenog identitetskog razrješujućeg ključa (IRK). Za podršku povezivanju aplikacija mora implementirati događaje _IRQ_GET_SECRET i _IRQ_SET_SECRET.

gap_pair(conn_handle: int, /) → None¶

Pokreće uparivanje s udaljenim uređajem.

Prije nego što ovo pozovete, provjerite jesu li postavljene konfiguracijske opcije io, mitm, le_secure i bond (putem config).

Po uspješnom uparivanju podići će se događaj _IRQ_ENCRYPTION_UPDATE.

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

Odgovara na događaj _IRQ_PASSKEY_ACTION za navedeni conn_handle i action. Značenje passkey ovisi o action (što pak ovisi o konfiguriranoj U/I (I/O) mogućnosti):

Radnja	Potreban odgovor passkey
`_PASSKEY_ACTION_INPUT`	Pristupni ključ (passkey) koji korisnik očita s udaljenog uređaja.
`_PASSKEY_ACTION_DISPLAY`	Lokalno generiran nasumični 6-znamenkasti pristupni ključ (passkey) prikazan korisniku.
`_PASSKEY_ACTION_NUMERIC_COMPARISON`	`1` za prihvaćanje pristupnog ključa prikazanog u događaju `_IRQ_PASSKEY_ACTION` ili `0` za otkazivanje uparivanja.

class UUID¶

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

Stvara instancu UUID-a s navedenom value. Bluetooth koristi tri širine UUID-a; UUID prihvaća bilo koju od njih:

Širina UUID-a	Prihvaćeni tipovi `value`	Primjer
16-bitni	`int` ili 2-bajtni međuspremnik (little-endian)	`UUID(0x2908)` ili `UUID(b'\x08\x29')`
32-bitni	4-bajtni međuspremnik (little-endian)	`UUID(b'\x08\x29\x00\x00')`
128-bitni	16-bajtni međuspremnik ili niz s crticama	`UUID('6E400001-B5A3-F393-E0A9-E50E24DCCA9E')`

16- i 32-bitni UUID-ovi tipično su identifikatori koje dodjeljuje SIG (pogledajte Bluetooth dodijeljeni brojevi); 128-bitni UUID-ovi obično su definirani od strane proizvođača.

bluetooth — niskorazinski Bluetooth¶

class BLE¶

class UUID¶

`bluetooth` — niskorazinski Bluetooth¶