bluetooth — alacsony szintű Bluetooth

Ez a modul interfészt biztosít a beépített Bluetooth vezérlőhöz. Támogatja a Bluetooth Low Energy (BLE) technológiát Central, Peripheral, Broadcaster és Observer szerepkörökben, valamint a GATT Server és Client és az L2CAP kapcsolatorientált csatornákat. Egy eszköz egyszerre több szerepkörben is működhet. A párosítás (pairing) és a kötés (bonding) is támogatott.

Ezt az API-t úgy tervezték, hogy illeszkedjen az alacsony szintű Bluetooth protokollhoz, és építőelemeket biztosítson a magasabb szintű absztrakciókhoz, mint például a konkrét eszköztípusokhoz.

Javaslat

A legtöbb alkalmazáshoz inkább a magasabb szintű aioble könyvtárat érdemes használni, amely egy asyncio-alapú burkolót biztosít e modul köré. Lásd: aioble — Aszinkron BLE.

class BLE

class bluetooth.BLE

Visszaadja a singleton BLE objektumot.

Konfiguráció

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

Opcionálisan módosítja a BLE rádió aktív állapotát, és visszaadja az aktuális állapotot.

A rádiót aktívvá kell tenni, mielőtt bármilyen más metódust használnánk ezen az osztályon.

config(param: str, /) → Any

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

Lekérdezi vagy beállítja a BLE interfész konfigurációs értékeit. Egy érték lekérdezéséhez a paraméter nevét sztringként idézőjelbe kell tenni, és egyszerre csak egy paraméter kérdezhető le. Értékek beállításához a kulcsszavas szintaxist kell használni, és egyszerre egy vagy több paraméter is beállítható.

A jelenleg támogatott értékek a következők:

• 'mac': A jelenleg használt cím, az aktuális címmódtól függően. Ez egy (addr_type, addr) tuple-t ad vissza.

  A címtípusokról a részleteket lásd a gap_scan leírásában.

  Ez csak akkor kérdezhető le, amíg az interfész éppen aktív.

• 'addr_mode': Beállítja a címmódot. Az értékek a következők:

  Érték	Név	Viselkedés
  0x00	PUBLIC	A vezérlő nyilvános címének használata.
  0x01	RANDOM	Egy generált statikus cím használata.
  0x02	RPA	Feloldható privát címek (resolvable private address) használata.
  0x03	NRPA	Nem feloldható privát címek (non-resolvable private address) használata.

  Alapértelmezés szerint az interfész PUBLIC címet használ, ha elérhető, egyébként RANDOM címet.

• 'gap_name': Lekérdezi/beállítja a Generic Access szolgáltatás (UUID 0x1800) Device Name karakterisztikája (UUID 0x2a00) által használt GAP eszköznevet. Ez bármikor beállítható és többször is módosítható.

• 'rxbuf': Lekérdezi/beállítja a bejövő események tárolására használt belső puffer méretét bájtban. Ez a puffer az egész BLE meghajtó számára globális, így minden esemény bejövő adatait kezeli, beleértve az összes karakterisztikát. Növelésével jobban kezelhető a szakaszosan érkező bejövő adat (például a beolvasási eredmények), és nagyobb karakterisztika-értékek fogadhatók.

• 'mtu': Lekérdezi/beállítja azt az MTU-t, amelyet egy ATT MTU-csere során használnak. Az eredményül kapott MTU ennek és a távoli eszköz MTU-jának a minimuma lesz. Az ATT MTU-csere nem történik meg automatikusan (kivéve, ha a távoli eszköz kezdeményezi), és manuálisan kell elindítani a gattc_exchange_mtu segítségével. Az _IRQ_MTU_EXCHANGED esemény segítségével deríthető ki egy adott kapcsolat MTU-ja.

• 'bond': Beállítja, hogy a kötés (bonding) engedélyezve legyen-e a párosítás során. Ha engedélyezve van, a párosítási kérések beállítják a „bond” jelzőt, és a kulcsokat mindkét eszköz eltárolja.

• 'mitm': Beállítja, hogy szükséges-e MITM-védelem a párosításhoz.

• 'io': Beállítja az eszköz I/O képességeit.

  Az elérhető opciók a következők:

  Konstans	Érték	Képesség
  _IO_CAPABILITY_DISPLAY_ONLY	0	Csak kijelző
  _IO_CAPABILITY_DISPLAY_YESNO	1	Kijelző igen/nem bemenettel
  _IO_CAPABILITY_KEYBOARD_ONLY	2	Csak billentyűzet
  _IO_CAPABILITY_NO_INPUT_OUTPUT	3	Nincs be- vagy kimenet
  _IO_CAPABILITY_KEYBOARD_DISPLAY	4	Billentyűzet és kijelző

• 'le_secure': Beállítja, hogy szükséges-e „LE Secure” párosítás. Az alapértelmezés false (azaz a „Legacy Pairing” engedélyezett).

Eseménykezelés

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

Regisztrál egy visszahívást a BLE stack eseményeihez. A handler két argumentumot fogad: event (amely az alábbi kódok egyike lesz) és data (amely egy eseményspecifikus értéktuple).

Megjegyzés: A szükségtelen allokációk elkerülése érdekében végzett optimalizálásként a tuple-ökben szereplő addr, adv_data, char_data, notify_data és uuid bejegyzések csak olvasható memoryview példányok, amelyek a bluetooth belső gyűrűpufferére mutatnak, és csak az IRQ kezelőfüggvény meghívásának ideje alatt érvényesek. Ha a programnak az egyik ilyen értéket el kell mentenie, hogy az IRQ kezelő visszatérése után is hozzáférhessen (pl. egy osztálypéldányban vagy globális változóban mentve), akkor másolatot kell készítenie az adatról, akár bytes(), akár bluetooth.UUID() használatával, így:

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

Például egy beolvasási eredmény IRQ kezelője megvizsgálhatja az adv_data tartalmát, hogy eldöntse, ez-e a megfelelő eszköz, és csak ezután másolja le a cím adatát a program máshol történő használatára. Az IRQ kezelőn belüli adatok kiírásához pedig a print(bytes(addr)) szükséges.

Egy kezelő jellemzően az eseménykód alapján szétoszt (dispatch), és kicsomagolja az eseményspecifikus payload tuple-t:

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

Az összes eseménykódot, az általuk szállított payloadot és egy rövid leírást az alábbiakban sorolunk fel. Azon eseményeknél, ahol a status mező említésre kerül, a status siker esetén 0, hiba esetén pedig egy implementációfüggő, nem nulla érték.

Konstans	Érték	Esemény	Payload tuple
_IRQ_CENTRAL_CONNECT	1	Egy central csatlakozott ehhez a peripheralhez.	(conn_handle, addr_type, addr)
_IRQ_CENTRAL_DISCONNECT	2	Egy central lekapcsolódott erről a peripheralről.	(conn_handle, addr_type, addr)
_IRQ_GATTS_WRITE	3	Egy csatlakozott kliens írt egy helyi karakterisztikába vagy leíróba. Az új érték lekéréséhez használja a gatts_read metódust.	(conn_handle, attr_handle)
_IRQ_GATTS_READ_REQUEST	4	Egy csatlakozott kliens olvasást kezdeményezett. Az olvasás elutasításához adjon vissza egy nem nulla hibakódot az alábbi táblázatból, vagy 0 / None értéket az elfogadásához.	(conn_handle, attr_handle)
_IRQ_SCAN_RESULT	5	Egy aktív beolvasás során egyetlen hirdetési (advertising) csomag érkezett.	(addr_type, addr, adv_type, rssi, adv_data)
_IRQ_SCAN_DONE	6	Az aktuális beolvasás befejeződött, vagy mert a beállított időtartam letelt, vagy mert a gap_scan(None) hívás megtörtént.	()
_IRQ_PERIPHERAL_CONNECT	7	Egy korábban kiadott gap_connect sikeresen lefutott.	(conn_handle, addr_type, addr)
_IRQ_PERIPHERAL_DISCONNECT	8	Egy csatlakozott peripheral lekapcsolódott.	(conn_handle, addr_type, addr)
_IRQ_GATTC_SERVICE_RESULT	9	A gattc_discover_services egy szolgáltatást talált.	(conn_handle, start_handle, end_handle, uuid)
_IRQ_GATTC_SERVICE_DONE	10	A szolgáltatásfelderítés befejeződött.	(conn_handle, status)
_IRQ_GATTC_CHARACTERISTIC_RESULT	11	A gattc_discover_characteristics egy karakterisztikát talált.	(conn_handle, end_handle, value_handle, properties, uuid)
_IRQ_GATTC_CHARACTERISTIC_DONE	12	A karakterisztika-felderítés befejeződött.	(conn_handle, status)
_IRQ_GATTC_DESCRIPTOR_RESULT	13	A gattc_discover_descriptors egy leírót talált.	(conn_handle, dsc_handle, uuid)
_IRQ_GATTC_DESCRIPTOR_DONE	14	A leíró-felderítés befejeződött.	(conn_handle, status)
_IRQ_GATTC_READ_RESULT	15	Egy korábban kiadott gattc_read adatot adott vissza.	(conn_handle, value_handle, char_data)
_IRQ_GATTC_READ_DONE	16	Egy korábban kiadott gattc_read befejeződött.	(conn_handle, value_handle, status)
_IRQ_GATTC_WRITE_DONE	17	Egy korábban kiadott gattc_write nyugtázásra került.	(conn_handle, value_handle, status)
_IRQ_GATTC_NOTIFY	18	Egy távoli szerver (nem nyugtázott) értesítést (notification) küldött.	(conn_handle, value_handle, notify_data)
_IRQ_GATTC_INDICATE	19	Egy távoli szerver (nyugtázott) jelzést (indication) küldött.	(conn_handle, value_handle, notify_data)
_IRQ_GATTS_INDICATE_DONE	20	Egy korábban küldött jelzést a kliens nyugtázott (vagy időtúllépés történt).	(conn_handle, value_handle, status)
_IRQ_MTU_EXCHANGED	21	Egy ATT MTU-csere befejeződött (bármelyik oldal kezdeményezhette).	(conn_handle, mtu)
_IRQ_L2CAP_ACCEPT	22	Egy távoli eszköz L2CAP kapcsolatot kért egy PSM-en, amelyen ez az eszköz figyel. Az elutasításhoz adjon vissza egy nem nulla egész számot, vagy 0 / None értéket az elfogadásához.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_CONNECT	23	Egy L2CAP csatorna létrejött, akár egy bejövő kérés elfogadásával, akár egy kimenő l2cap_connect befejezésével.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_DISCONNECT	24	Egy L2CAP csatorna lekapcsolódott. A status 0 tiszta lekapcsolódás esetén, vagy nem nulla, ha egy kimenő kapcsolódási kísérlet meghiúsult.	(conn_handle, cid, psm, status)
_IRQ_L2CAP_RECV	25	Adat érkezett egy L2CAP csatornán. Az olvasáshoz hívja meg a l2cap_recvinto metódust.	(conn_handle, cid)
_IRQ_L2CAP_SEND_READY	26	Egy korábbi l2cap_send, amely False értéket adott vissza, kiürült, és a csatorna ismét készen áll. A nem nulla status azt jelenti, hogy az adóbuffer túlcsordult, és az alkalmazásnak újra kell küldenie az adatot.	(conn_handle, cid, status)
_IRQ_CONNECTION_UPDATE	27	A távoli eszköz frissítette a kapcsolat paramétereit (intervallum, késleltetés, felügyeleti időtúllépés).	(conn_handle, conn_interval, conn_latency, supervision_timeout, status)
_IRQ_ENCRYPTION_UPDATE	28	Egy kapcsolat titkosítási állapota megváltozott, jellemzően a párosítás vagy a kötés befejezése után.	(conn_handle, encrypted, authenticated, bonded, key_size)
_IRQ_GET_SECRET	29	A stack egy tárolt kötési titkot (bonding secret) kér. Ha a key None, adja vissza a sec_type index. tárolt értékét; egyébként adja vissza az adott (sec_type, key) párhoz tartozó értéket. Adjon vissza None értéket, ha semmi sincs tárolva.	(sec_type, index, key)
_IRQ_SET_SECRET	30	A stack arra kéri az alkalmazást, hogy egy kötési titkot tartósan tároljon. A tárolás után adjon vissza True értéket.	(sec_type, key, value)
_IRQ_PASSKEY_ACTION	31	A párosítás részeként egy jelszó (passkey) művelet szükséges. Válaszoljon a gap_passkey segítségével; a lehetséges műveleteket lásd az alábbi jelszóművelet-táblázatban.	(conn_handle, action, passkey)

Az _IRQ_GATTS_READ_REQUEST eseményhez a rendelkezésre álló visszatérési kódok a következők:

Konstans	Érték	Jelentés
_GATTS_NO_ERROR	0x00	Az olvasás elfogadása.
_GATTS_ERROR_READ_NOT_PERMITTED	0x02	Olvasás nem engedélyezett.
_GATTS_ERROR_WRITE_NOT_PERMITTED	0x03	Írás nem engedélyezett.
_GATTS_ERROR_INSUFFICIENT_AUTHENTICATION	0x05	A kliens nincs hitelesítve.
_GATTS_ERROR_INSUFFICIENT_AUTHORIZATION	0x08	A kliens nincs feljogosítva.
_GATTS_ERROR_INSUFFICIENT_ENCRYPTION	0x0f	A kapcsolat nincs titkosítva.

Az _IRQ_PASSKEY_ACTION eseményhez a rendelkezésre álló műveletek a következők:

Konstans	Érték	Jelentés
_PASSKEY_ACTION_NONE	0	Nincs szükség műveletre.
_PASSKEY_ACTION_INPUT	2	Kérje meg a felhasználót, hogy adja meg a távoli eszközön megjelenített jelszót.
_PASSKEY_ACTION_DISPLAY	3	Jelenítsen meg egy 6 jegyű jelszót, amelyet a távoli eszközön kell megadni.
_PASSKEY_ACTION_NUMERIC_COMPARISON	4	Erősítse meg, hogy a jelszó megegyezik a távoli eszközön megjelenítettel.

A firmware helytakarékossága érdekében ezek a konstansok nincsenek belefoglalva a bluetooth modulba. A fenti listákból adja hozzá a programjához azokat, amelyekre szüksége van.

Broadcaster szerepkör (hirdető)

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

Megkezdi a hirdetést a megadott intervallummal (mikroszekundumban). Ez az intervallum lefelé kerekítődik a legközelebbi 625us-ra. A hirdetés leállításához állítsa az interval_us értékét None-ra.

Az adv_data és a resp_data bármilyen olyan típus lehet, amely megvalósítja a buffer protokollt (pl. bytes, bytearray, str). Az adv_data minden adásban szerepel, a resp_data pedig egy aktív beolvasásra adott válaszként kerül elküldésre.

Megjegyzés: ha az adv_data (vagy a resp_data) None, akkor a gap_advertise előző hívásának átadott adatot használja újra. Ez lehetővé teszi, hogy a broadcaster mindössze egy gap_advertise(interval_us) hívással folytassa a hirdetést. A hirdetési payload törléséhez adjon át egy üres bytes értéket, azaz b''.

Observer szerepkör (beolvasó)

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

Lefuttat egy beolvasási műveletet a megadott időtartamra (milliszekundumban).

A határozatlan idejű beolvasáshoz állítsa a duration_ms értékét 0-ra.

A beolvasás leállításához állítsa a duration_ms értékét None-ra.

Az interval_us és a window_us segítségével opcionálisan konfigurálható a kitöltési tényező (duty cycle). A beolvasó window_us mikroszekundumig fut minden interval_us mikroszekundumban, összesen duration_ms milliszekundumig. Az alapértelmezett intervallum és ablak 1,28 másodperc, illetve 11,25 milliszekundum (háttérbeli beolvasás).

Minden beolvasási eredményhez kiváltódik az _IRQ_SCAN_RESULT esemény, (addr_type, addr, adv_type, rssi, adv_data) eseményadattal.

Az addr_type értékek nyilvános vagy véletlenszerű címeket jeleznek:

Érték	Név	Jelentés
0x00	PUBLIC	Nyilvános eszközcím.
0x01	RANDOM	Véletlenszerű cím (statikus, RPA vagy NRPA; a típus magában a címben van kódolva).

Az adv_type értékek a Bluetooth specifikációnak felelnek meg:

Érték	Név	Jelentés
0x00	ADV_IND	Csatlakoztatható és beolvasható, irányítatlan hirdetés.
0x01	ADV_DIRECT_IND	Csatlakoztatható, irányított hirdetés.
0x02	ADV_SCAN_IND	Beolvasható, irányítatlan hirdetés.
0x03	ADV_NONCONN_IND	Nem csatlakoztatható, irányítatlan hirdetés.
0x04	SCAN_RSP	Beolvasási válasz.

Az active True-ra állítható, ha az eredményekben beolvasási válaszokat is fogadni szeretne.

Amikor a beolvasás leáll (akár az időtartam lejárta miatt, akár kifejezett leállításkor), kiváltódik az _IRQ_SCAN_DONE esemény.

Central szerepkör

Egy central eszköz csatlakozhat olyan peripheralekhez, amelyeket az observer szerepkör segítségével fedezett fel (lásd gap_scan), vagy ismert cím alapján.

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

Csatlakozás egy peripheralhez.

A címtípusokról a részleteket lásd a gap_scan leírásában.

Egy folyamatban lévő kapcsolódási kísérlet korai megszakításához hívja meg a gap_connect(None) metódust.

Siker esetén kiváltódik az _IRQ_PERIPHERAL_CONNECT esemény. Egy kapcsolódási kísérlet megszakításakor pedig az _IRQ_PERIPHERAL_DISCONNECT esemény váltódik ki.

Az eszköz legfeljebb scan_duration_ms ideig vár, hogy hirdetési payloadot kapjon az eszköztől.

A kapcsolat intervalluma mikroszekundumban konfigurálható a min_conn_interval_us és max_conn_interval_us egyikével vagy mindkettővel. Egyébként egy alapértelmezett intervallum kerül kiválasztásra, jellemzően 30000 és 50000 mikroszekundum között. A rövidebb intervallum növeli az átviteli teljesítményt, az energiafogyasztás rovására.

Peripheral szerepkör

Egy peripheral eszköztől elvárt, hogy csatlakoztatható hirdetéseket küldjön (lásd gap_advertise). Általában GATT szerverként működik, miután először regisztrálta a szolgáltatásokat és karakterisztikákat a gatts_register_services segítségével.

Amikor egy central csatlakozik, kiváltódik az _IRQ_CENTRAL_CONNECT esemény.

Central és Peripheral szerepkörök

gap_disconnect(conn_handle: int, /) → bool

Lekapcsolja a megadott kapcsolatkezelőt (connection handle). Ez lehet egy central, amely ehhez az eszközhöz csatlakozott (ha peripheralként működik), vagy egy peripheral, amelyhez ez az eszköz korábban csatlakozott (ha centralként működik).

Siker esetén kiváltódik az _IRQ_PERIPHERAL_DISCONNECT vagy az _IRQ_CENTRAL_DISCONNECT esemény.

False értéket ad vissza, ha a kapcsolatkezelő nem volt csatlakoztatva, egyébként True értéket.

GATT Server

Egy GATT szervernek van egy regisztrált szolgáltatáskészlete. Minden szolgáltatás tartalmazhat karakterisztikákat, amelyeknek mindegyike rendelkezik egy értékkel. A karakterisztikák leírókat is tartalmazhatnak, amelyeknek szintén vannak értékeik.

Ezek az értékek helyileg vannak tárolva, és a szolgáltatásregisztráció során generált „value handle” segítségével érhetők el. Egy távoli kliens eszköz is olvashatja vagy írhatja őket. Ezenkívül egy szerver „értesítheti” (notify) egy karakterisztikáról egy csatlakozott klienst egy kapcsolatkezelőn keresztül.

Egy central vagy peripheral szerepkörű eszköz egyaránt működhet GATT szerverként, azonban a legtöbb esetben gyakoribb, hogy egy peripheral eszköz lát el szerver szerepet.

A karakterisztikák és leírók alapértelmezett maximális mérete 20 bájt (az alapértelmezett 23 bájtos ATT MTU mínusz egy 3 bájtos ATT fejléc; egy nagyobb egyeztetett MTU önmagában nem emeli meg ezt a korlátot). Bármi, amit egy kliens beléjük ír, erre a hosszra csonkolódik. Azonban bármilyen helyi írás megnöveli a maximális méretet, így ha lehetővé szeretné tenni egy kliens számára a nagyobb írásokat egy adott karakterisztikába, használja a gatts_write metódust a regisztráció után, pl. gatts_write(char_handle, bytes(100)).

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

Konfigurálja a szervert a megadott szolgáltatásokkal, lecserélve minden meglévő szolgáltatást.

A services_definition a szolgáltatások (services) listája, ahol minden szolgáltatás egy kételemű tuple, amely egy UUID-t és a karakterisztikák listáját tartalmazza.

Minden karakterisztika egy két- vagy háromelemű tuple, amely egy UUID-t, egy flags értéket és opcionálisan a leírók listáját tartalmazza.

Minden leíró egy kételemű tuple, amely egy UUID-t és egy flags értéket tartalmaz.

A flags az alább definiált jelzők bitenkénti VAGY (OR) kombinációja. Ezek beállítják mind a karakterisztika (vagy leíró) viselkedését, mind a biztonsági és adatvédelmi követelményeket.

A visszatérési érték egy lista (szolgáltatásonként egy elem), amely tuple-öket tartalmaz (minden elem egy value handle). A karakterisztika- és leíró-kezelők ugyanabba a tuple-be vannak laposítva, a definiálásuk sorrendjében.

A következő példa két szolgáltatást regisztrál (Heart Rate és 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),
)

A három value handle (hr, tx, rx) használható a gatts_read, gatts_write, gatts_notify és gatts_indicate metódusokkal.

Megjegyzés: A hirdetést le kell állítani a szolgáltatások regisztrálása előtt.

A karakterisztikákhoz és leírókhoz elérhető jelzők a következők:

Konstans	Érték	Jelentés
_FLAG_BROADCAST	0x0001	A karakterisztika sugározható (broadcast).
_FLAG_READ	0x0002	A kliens olvashatja az értéket.
_FLAG_WRITE_NO_RESPONSE	0x0004	A kliens írhat anélkül, hogy választ várna.
_FLAG_WRITE	0x0008	A kliens nyugtázott válasszal írhat.
_FLAG_NOTIFY	0x0010	A szerver értesítéseket küldhet (nem nyugtázott).
_FLAG_INDICATE	0x0020	A szerver jelzéseket küldhet (nyugtázott).
_FLAG_AUTHENTICATED_SIGNED_WRITE	0x0040	A kliens aláírt írásokat hajthat végre.
_FLAG_AUX_WRITE	0x0100	Kiterjesztett tulajdonságok: sorba állított/megbízható írások engedélyezettek.
_FLAG_READ_ENCRYPTED	0x0200	Az olvasás titkosított kapcsolatot igényel.
_FLAG_READ_AUTHENTICATED	0x0400	Az olvasás hitelesített (MITM-védett) kapcsolatot igényel.
_FLAG_READ_AUTHORIZED	0x0800	Az olvasás alkalmazásszintű feljogosítást igényel.
_FLAG_WRITE_ENCRYPTED	0x1000	Az írás titkosított kapcsolatot igényel.
_FLAG_WRITE_AUTHENTICATED	0x2000	Az írás hitelesített (MITM-védett) kapcsolatot igényel.
_FLAG_WRITE_AUTHORIZED	0x4000	Az írás alkalmazásszintű feljogosítást igényel.

A fenti eseménykonstansokhoz hasonlóan ezeket a jelzőket sem biztosítja a bluetooth modul; másolja a programjába azokat, amelyekre szüksége van.

gatts_read(value_handle: int, /) → bytes

Beolvassa az ehhez a handle-höz tartozó helyi értéket (amelyet vagy a gatts_write írt, vagy egy távoli kliens).

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

Beírja az ehhez a handle-höz tartozó helyi értéket, amelyet egy kliens olvashat.

Ha a send_update True, akkor minden feliratkozott kliens értesítést (vagy jelzést, attól függően, hogy mire iratkoztak fel, és milyen műveleteket támogat a karakterisztika) kap erről az írásról.

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

Értesítési kérést küld egy csatlakozott kliensnek.

Ha a data None (az alapértelmezés), akkor az aktuális helyi érték (amelyet a gatts_write állított be) kerül elküldésre.

Egyébként, ha a data nem None, akkor ez az érték kerül elküldésre a kliensnek az értesítés részeként. A helyi érték nem módosul.

Megjegyzés: Az értesítés a kliens ezen karakterisztikára vonatkozó feliratkozási állapotától függetlenül kerül elküldésre.

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

Jelzési kérést küld egy csatlakozott kliensnek.

Ha a data None (az alapértelmezés), akkor az aktuális helyi érték (amelyet a gatts_write állított be) kerül elküldésre.

Egyébként, ha a data nem None, akkor ez az érték kerül elküldésre a kliensnek a jelzés részeként. A helyi érték nem módosul.

Nyugtázáskor (vagy hiba, pl. időtúllépés esetén) kiváltódik az _IRQ_GATTS_INDICATE_DONE esemény.

Megjegyzés: A jelzés a kliens ezen karakterisztikára vonatkozó feliratkozási állapotától függetlenül kerül elküldésre.

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

Beállítja egy érték belső pufferméretét bájtban. Ez korlátozza a fogadható legnagyobb írás méretét. Az alapértelmezés 20 bájt (az alapértelmezett 23 bájtos ATT MTU mínusz a 3 bájtos ATT fejléc).

Az append True-ra állítása azt eredményezi, hogy minden távoli írás hozzáfűződik az aktuális értékhez, ahelyett, hogy lecserélné azt. Ily módon legfeljebb len bájt pufferelhető. Amikor a gatts_read metódust használja, az érték az olvasás után törlődik. Ez a funkció hasznos olyasmi megvalósításakor, mint a Nordic UART Service.

GATT Client

Egy GATT kliens felderítheti és olvashatja/írhatja a karakterisztikákat egy távoli GATT szerveren.

Gyakoribb, hogy egy central szerepkörű eszköz működik GATT kliensként, azonban egy peripheral is működhet kliensként, hogy információt derítsen ki a hozzá csatlakozott centralról (pl. az eszköznevet olvassa ki az eszközinformációs szolgáltatásból).

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

Lekérdezi egy csatlakozott szerver szolgáltatásait.

Opcionálisan adjon meg egy szolgáltatás uuid értéket, hogy csak azt a szolgáltatást kérdezze le.

Minden felfedezett szolgáltatáshoz kiváltódik az _IRQ_GATTC_SERVICE_RESULT esemény, majd a befejezéskor az _IRQ_GATTC_SERVICE_DONE esemény.

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

Lekérdezi egy csatlakozott szerver karakterisztikáit a megadott tartományban.

Opcionálisan adjon meg egy karakterisztika uuid értéket, hogy csak azt a karakterisztikát kérdezze le.

A start_handle=1 és end_handle=0xffff átadása a teljes GATT attribútumkezelő-tartományt lefedi, így ez a kombináció gyakorlatilag a távoli eszköz minden szolgáltatásában keres.

Minden felfedezett karakterisztikához kiváltódik az _IRQ_GATTC_CHARACTERISTIC_RESULT esemény, majd a befejezéskor az _IRQ_GATTC_CHARACTERISTIC_DONE esemény.

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

Lekérdezi egy csatlakozott szerver leíróit a megadott tartományban.

Minden felfedezett leíróhoz kiváltódik az _IRQ_GATTC_DESCRIPTOR_RESULT esemény, majd a befejezéskor az _IRQ_GATTC_DESCRIPTOR_DONE esemény.

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

Távoli olvasást kezdeményez egy csatlakozott szerveren a megadott karakterisztika- vagy leíró-handle-höz.

Amikor egy érték elérhetővé válik, kiváltódik az _IRQ_GATTC_READ_RESULT esemény, majd a befejezéskor az _IRQ_GATTC_READ_DONE esemény.

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

Távoli írást kezdeményez egy csatlakozott szerveren a megadott karakterisztika- vagy leíró-handle-höz.

A mode argumentum határozza meg az írási viselkedést, a jelenleg támogatott értékek a következők:

• A mode=0 (alapértelmezett) egy válasz nélküli írás: az írás elküldésre kerül a távoli szervernek, de nem érkezik visszaigazolás, és nem váltódik ki esemény.

• A mode=1 egy válasszal történő írás: a távoli szervert arra kérik, hogy küldjön választ/nyugtázást arról, hogy megkapta az adatot.

Ha válasz érkezik a távoli szervertől, kiváltódik az _IRQ_GATTC_WRITE_DONE esemény.

gattc_exchange_mtu(conn_handle: int, /) → None

Elindítja az MTU-cserét egy csatlakozott szerverrel, a BLE.config(mtu=value) segítségével beállított preferált MTU használatával.

Az _IRQ_MTU_EXCHANGED esemény kiváltódik, amikor az MTU-csere befejeződik.

Az MTU-cserét jellemzően a central kezdeményezi; a NimBLE mindkét szerepkört támogatja.

L2CAP kapcsolatorientált csatornák

Ez a funkció socket-szerű adatcserét tesz lehetővé két BLE eszköz között. Miután az eszközök GAP-on keresztül csatlakoztak, bármelyik eszköz figyelhet arra, hogy a másik egy numerikus PSM-en (Protocol/Service Multiplexer) csatlakozzon.

Egy adott időpontban csak egy L2CAP csatorna lehet aktív (azaz nem csatlakozhat, miközben figyel).

Az aktív L2CAP csatornákat a kapcsolatkezelő, amelyen létrejöttek, és egy CID (channel ID) azonosítja.

A kapcsolatorientált csatornák beépített kredit-alapú folyamszabályozással rendelkeznek. Az ATT-vel ellentétben, ahol az eszközök egy közös MTU-t egyeztetnek, mind a figyelő, mind a csatlakozó eszköz egymástól független MTU-t állít be, amely korlátozza azt a maximális kintlévő adatmennyiséget, amelyet a távoli eszköz elküldhet, mielőtt az teljesen feldolgozásra kerülne a l2cap_recvinto metódusban.

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

Megkezdi a bejövő L2CAP csatornakérések figyelését a megadott psm-en, a helyi MTU-t mtu-ra állítva.

Amikor egy távoli eszköz kapcsolatot kezdeményez, kiváltódik az _IRQ_L2CAP_ACCEPT esemény, amely lehetőséget ad a figyelő szervernek a bejövő kapcsolat elutasítására (egy nem nulla egész szám visszaadásával).

Miután a kapcsolat elfogadásra került, kiváltódik az _IRQ_L2CAP_CONNECT esemény, lehetővé téve a szerver számára a channel ID (CID), valamint a helyi és a távoli MTU megszerzését.

Megjegyzés: Jelenleg nem lehet leállítani a figyelést.

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

Csatlakozás egy figyelő partnerhez a megadott psm-en, a helyi MTU-t mtu-ra állítva.

Sikeres kapcsolódáskor kiváltódik az _IRQ_L2CAP_CONNECT esemény, lehetővé téve a kliens számára a CID, valamint a helyi és a távoli (peer) MTU megszerzését.

Egy sikertelen kapcsolódás az _IRQ_L2CAP_DISCONNECT eseményt váltja ki nem nulla státusszal.

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

Lekapcsol egy aktív L2CAP csatornát a megadott conn_handle és cid segítségével.

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

Elküldi a megadott buf-ot (amelynek támogatnia kell a buffer protokollt) a conn_handle és cid által azonosított L2CAP csatornán.

A puffernek mindkét korlátnak meg kell felelnie: nem haladhatja meg a távoli (peer) MTU-t, és nem haladhatja meg a helyi MTU kétszeresét.

Ez False értéket ad vissza, ha a csatorna most „elakadt” (stalled), ami azt jelenti, hogy a l2cap_send metódust nem szabad újra meghívni, amíg az _IRQ_L2CAP_SEND_READY esemény meg nem érkezik (ami akkor történik, amikor a távoli eszköz több kreditet ad, jellemzően miután megkapta és feldolgozta az adatot).

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

Adatot fogad a megadott conn_handle és cid segítségével a megadott buf-ba (amelynek támogatnia kell a buffer protokollt, pl. bytearray vagy memoryview).

Visszaadja a csatornáról beolvasott bájtok számát.

Ha a buf None, akkor a rendelkezésre álló bájtok számát adja vissza.

Megjegyzés: Az _IRQ_L2CAP_RECV esemény fogadása után az alkalmazásnak addig kell folytatnia a l2cap_recvinto hívását, amíg nincs több bájt a fogadópufferben (jellemzően a távoli (peer) MTU méretéig).

Amíg a fogadópuffer ki nem ürül, a távoli eszköz nem kap több csatornakreditet, és nem tud több adatot küldeni.

Párosítás és kötés

A párosítás (pairing) lehetővé teszi egy kapcsolat titkosítását és hitelesítését titkok cseréjén keresztül (opcionális MITM-védelemmel jelszó-hitelesítés révén).

A kötés (bonding) e titkok nem felejtő tárolóban való tárolásának folyamata. Kötés esetén egy eszköz képes feloldani egy másik eszköz feloldható privát címét (RPA) a tárolt identitásfeloldó kulcs (IRK) alapján. A kötés támogatásához az alkalmazásnak meg kell valósítania az _IRQ_GET_SECRET és _IRQ_SET_SECRET eseményeket.

gap_pair(conn_handle: int, /) → None

Elindítja a párosítást a távoli eszközzel.

Mielőtt ezt meghívná, győződjön meg róla, hogy az io, mitm, le_secure és bond konfigurációs opciók be vannak állítva (a config segítségével).

Sikeres párosításkor kiváltódik az _IRQ_ENCRYPTION_UPDATE esemény.

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

Válaszol egy _IRQ_PASSKEY_ACTION eseményre a megadott conn_handle és action esetén. A passkey jelentése az action-tól függ (amely viszont a konfigurált I/O képességtől függ):

Művelet	Szükséges passkey válasz
_PASSKEY_ACTION_INPUT	Az a jelszó, amelyet a felhasználó leolvas a távoli eszközről.
_PASSKEY_ACTION_DISPLAY	Egy helyileg generált, véletlenszerű 6 jegyű jelszó, amelyet a felhasználónak megjelenítenek.
_PASSKEY_ACTION_NUMERIC_COMPARISON	1 az _IRQ_PASSKEY_ACTION eseményben megjelenített jelszó elfogadásához, vagy 0 a párosítás megszakításához.

class UUID

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

Létrehoz egy UUID példányt a megadott value értékkel. A Bluetooth három UUID-szélességet használ; az UUID bármelyiket elfogadja:

UUID szélesség	Elfogadott value típusok	Példa
16 bites	int vagy egy 2 bájtos puffer (little-endian)	UUID(0x2908) vagy UUID(b'\x08\x29')
32 bites	4 bájtos puffer (little-endian)	UUID(b'\x08\x29\x00\x00')
128 bites	16 bájtos puffer vagy egy kötőjeles sztring	UUID('6E400001-B5A3-F393-E0A9-E50E24DCCA9E')

A 16 és 32 bites UUID-k jellemzően SIG által kiosztott azonosítók (lásd a Bluetooth assigned numbers oldalt); a 128 bites UUID-k általában gyártó által definiáltak.