bluetooth — lågnivå-Bluetooth

Den här modulen tillhandahåller ett gränssnitt till den inbyggda Bluetooth-styrenheten. Den stöder Bluetooth Low Energy (BLE) i rollerna Central, Peripheral, Broadcaster och Observer, samt GATT Server och Client och anslutningsorienterade L2CAP-kanaler. En enhet kan fungera i flera roller samtidigt. Parkoppling (pairing) och bindning (bonding) stöds också.

Detta API är avsett att matcha lågnivåprotokollet för Bluetooth och tillhandahålla byggstenar för abstraktioner på högre nivå, såsom specifika enhetstyper.

Tips

För de flesta tillämpningar bör du föredra biblioteket aioble på högre nivå, som tillhandahåller en asyncio-baserad omslutning runt den här modulen. Se aioble — Asynkron BLE.

class BLE

class bluetooth.BLE

Returnerar singleton-objektet BLE.

Konfiguration

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

Ändrar valfritt det aktiva tillståndet för BLE-radion och returnerar det aktuella tillståndet.

Radion måste göras aktiv innan du använder några andra metoder i den här klassen.

config(param: str, /) → Any

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

Hämta eller ange konfigurationsvärden för BLE-gränssnittet. För att hämta ett värde ska parameternamnet anges som en sträng med citattecken, och endast en parameter efterfrågas åt gången. För att ange värden används nyckelordssyntaxen, och en eller flera parametrar kan anges åt gången.

För närvarande stöds följande värden:

• 'mac': Den aktuella adressen som används, beroende på det aktuella adressläget. Detta returnerar en tupel av (addr_type, addr).

  Se gap_scan för detaljer om adresstyp.

  Detta kan endast efterfrågas medan gränssnittet för närvarande är aktivt.

• 'addr_mode': Anger adressläget. Värdena är:

  Värde	Namn	Beteende
  0x00	PUBLIC	Använd styrenhetens publika adress.
  0x01	RANDOM	Använd en genererad statisk adress.
  0x02	RPA	Använd lösbara privata adresser (resolvable private addresses).
  0x03	NRPA	Använd icke-lösbara privata adresser (non-resolvable private addresses).

  Som standard kommer gränssnittet att använda en PUBLIC-adress om en sådan finns tillgänglig, annars används en RANDOM-adress.

• 'gap_name': Hämta/ange det GAP-enhetsnamn som används av tjänsten Generic Access (UUID 0x1800), karakteristiken Device Name (UUID 0x2a00). Detta kan anges när som helst och ändras flera gånger.

• 'rxbuf': Hämta/ange storleken i byte för den interna buffert som används för att lagra inkommande händelser. Denna buffert är global för hela BLE-drivrutinen och hanterar därför inkommande data för alla händelser, inklusive alla karakteristiker. Att öka den möjliggör bättre hantering av stötvis inkommande data (till exempel skanningsresultat) samt möjligheten att ta emot större karakteristikvärden.

• 'mtu': Hämta/ange den MTU som ska användas under ett ATT-MTU-utbyte. Den resulterande MTU:n blir minimum av denna och fjärrenhetens MTU. ATT-MTU-utbyte sker inte automatiskt (om inte fjärrenheten initierar det) och måste initieras manuellt med gattc_exchange_mtu. Använd händelsen _IRQ_MTU_EXCHANGED för att ta reda på MTU:n för en given anslutning.

• 'bond': Anger huruvida bindning ska aktiveras under parkoppling. När det är aktiverat sätter parkopplingsbegäranden flaggan ”bond” och nycklarna lagras av båda enheterna.

• 'mitm': Anger huruvida MITM-skydd krävs för parkoppling.

• 'io': Anger I/O-kapabiliteterna för den här enheten.

  Tillgängliga alternativ är:

  Konstant	Värde	Kapabilitet
  _IO_CAPABILITY_DISPLAY_ONLY	0	Endast visning
  _IO_CAPABILITY_DISPLAY_YESNO	1	Visning med ja/nej-inmatning
  _IO_CAPABILITY_KEYBOARD_ONLY	2	Endast tangentbord
  _IO_CAPABILITY_NO_INPUT_OUTPUT	3	Ingen inmatning eller utmatning
  _IO_CAPABILITY_KEYBOARD_DISPLAY	4	Tangentbord och visning

• 'le_secure': Anger huruvida ”LE Secure”-parkoppling krävs. Standardvärdet är false (dvs. tillåt ”Legacy Pairing”).

Händelsehantering

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

Registrerar ett återanrop för händelser från BLE-stacken. handler tar två argument, event (som är en av koderna nedan) och data (som är en händelsespecifik tupel av värden).

Obs: Som en optimering för att förhindra onödiga allokeringar är posterna addr, adv_data, char_data, notify_data och uuid i tuplerna skrivskyddade memoryview-instanser som pekar på bluetooth-modulens interna ringbuffert, och är endast giltiga under anropet av IRQ-hanterarfunktionen. Om ditt program behöver spara ett av dessa värden för åtkomst efter att IRQ-hanteraren har återvänt (t.ex. genom att spara det i en klassinstans eller global variabel), måste det ta en kopia av datan, antingen med bytes() eller bluetooth.UUID(), så här:

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

Till exempel kan IRQ-hanteraren för ett skanningsresultat inspektera adv_data för att avgöra om det är rätt enhet, och först därefter kopiera adressdatan för att användas på annat ställe i programmet. Och för att skriva ut data inifrån IRQ-hanteraren behövs print(bytes(addr)).

En hanterare avgör vanligtvis utifrån händelsekoden och packar upp den händelsespecifika nyttolasttupeln:

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

Varje händelsekod, den nyttolast den levererar och en kort beskrivning listas nedan. För händelser där fältet status nämns är status 0 vid framgång och ett implementationsspecifikt värde skilt från noll vid misslyckande.

Konstant	Värde	Händelse	Nyttolasttupel
_IRQ_CENTRAL_CONNECT	1	En central har anslutit till denna peripheral.	(conn_handle, addr_type, addr)
_IRQ_CENTRAL_DISCONNECT	2	En central har kopplat från denna peripheral.	(conn_handle, addr_type, addr)
_IRQ_GATTS_WRITE	3	En ansluten klient har skrivit till en lokal karakteristik eller deskriptor. Använd gatts_read för att hämta det nya värdet.	(conn_handle, attr_handle)
_IRQ_GATTS_READ_REQUEST	4	En ansluten klient har utfört en läsning. Returnera en felkod skild från noll från tabellen nedan för att neka läsningen, eller 0 / None för att acceptera den.	(conn_handle, attr_handle)
_IRQ_SCAN_RESULT	5	Ett enstaka annonseringspaket togs emot under en aktiv skanning.	(addr_type, addr, adv_type, rssi, adv_data)
_IRQ_SCAN_DONE	6	Den aktuella skanningen har avslutats, antingen för att den konfigurerade varaktigheten löpt ut eller för att gap_scan(None) anropades.	()
_IRQ_PERIPHERAL_CONNECT	7	En tidigare utfärdad gap_connect har lyckats.	(conn_handle, addr_type, addr)
_IRQ_PERIPHERAL_DISCONNECT	8	En ansluten peripheral har kopplat från.	(conn_handle, addr_type, addr)
_IRQ_GATTC_SERVICE_RESULT	9	En tjänst hittades av gattc_discover_services.	(conn_handle, start_handle, end_handle, uuid)
_IRQ_GATTC_SERVICE_DONE	10	Tjänsteupptäckt har slutförts.	(conn_handle, status)
_IRQ_GATTC_CHARACTERISTIC_RESULT	11	En karakteristik hittades av gattc_discover_characteristics.	(conn_handle, end_handle, value_handle, properties, uuid)
_IRQ_GATTC_CHARACTERISTIC_DONE	12	Karakteristikupptäckt har slutförts.	(conn_handle, status)
_IRQ_GATTC_DESCRIPTOR_RESULT	13	En deskriptor hittades av gattc_discover_descriptors.	(conn_handle, dsc_handle, uuid)
_IRQ_GATTC_DESCRIPTOR_DONE	14	Deskriptorupptäckt har slutförts.	(conn_handle, status)
_IRQ_GATTC_READ_RESULT	15	En tidigare utfärdad gattc_read har returnerat data.	(conn_handle, value_handle, char_data)
_IRQ_GATTC_READ_DONE	16	En tidigare utfärdad gattc_read har slutförts.	(conn_handle, value_handle, status)
_IRQ_GATTC_WRITE_DONE	17	En tidigare utfärdad gattc_write har bekräftats.	(conn_handle, value_handle, status)
_IRQ_GATTC_NOTIFY	18	En fjärrserver har skickat en (obekräftad) notifiering.	(conn_handle, value_handle, notify_data)
_IRQ_GATTC_INDICATE	19	En fjärrserver har skickat en (bekräftad) indikering.	(conn_handle, value_handle, notify_data)
_IRQ_GATTS_INDICATE_DONE	20	En tidigare skickad indikering har bekräftats av klienten (eller har gått ut i tid).	(conn_handle, value_handle, status)
_IRQ_MTU_EXCHANGED	21	Ett ATT-MTU-utbyte har slutförts (initierat av endera sidan).	(conn_handle, mtu)
_IRQ_L2CAP_ACCEPT	22	En fjärrenhet har begärt en L2CAP-anslutning på en PSM som den här enheten lyssnar på. Returnera ett heltal skilt från noll för att avvisa, eller 0 / None för att acceptera.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_CONNECT	23	En L2CAP-kanal är nu etablerad, antingen genom att acceptera en inkommande begäran eller genom att slutföra en utgående l2cap_connect.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_DISCONNECT	24	En L2CAP-kanal har kopplats från. status är 0 vid en ren frånkoppling, eller skilt från noll om ett utgående anslutningsförsök misslyckades.	(conn_handle, cid, psm, status)
_IRQ_L2CAP_RECV	25	Data har anlänt på en L2CAP-kanal. Anropa l2cap_recvinto för att läsa den.	(conn_handle, cid)
_IRQ_L2CAP_SEND_READY	26	En tidigare l2cap_send som returnerade False har tömts och kanalen är redo igen. En status skild från noll innebär att sändningsbufferten svämmade över och att applikationen måste skicka om datan.	(conn_handle, cid, status)
_IRQ_CONNECTION_UPDATE	27	Fjärrenheten har uppdaterat anslutningsparametrarna (intervall, latens, övervakningstidsgräns).	(conn_handle, conn_interval, conn_latency, supervision_timeout, status)
_IRQ_ENCRYPTION_UPDATE	28	Krypteringstillståndet för en anslutning har ändrats, vanligtvis efter att parkoppling eller bindning slutförts.	(conn_handle, encrypted, authenticated, bonded, key_size)
_IRQ_GET_SECRET	29	Stacken begär en lagrad bindningshemlighet. Om key är None, returnera det index:e lagrade värdet av sec_type; annars returnera värdet som är kopplat till den givna (sec_type, key). Returnera None om inget är lagrat.	(sec_type, index, key)
_IRQ_SET_SECRET	30	Stacken ber applikationen att spara en bindningshemlighet beständigt. Returnera True när den har lagrats.	(sec_type, key, value)
_IRQ_PASSKEY_ACTION	31	En lösenkodsåtgärd krävs som en del av parkopplingen. Svara med gap_passkey; se tabellen över lösenkodsåtgärder nedan för de möjliga åtgärderna.	(conn_handle, action, passkey)

För händelsen _IRQ_GATTS_READ_REQUEST är de tillgängliga returkoderna:

Konstant	Värde	Betydelse
_GATTS_NO_ERROR	0x00	Acceptera läsningen.
_GATTS_ERROR_READ_NOT_PERMITTED	0x02	Läsning ej tillåten.
_GATTS_ERROR_WRITE_NOT_PERMITTED	0x03	Skrivning ej tillåten.
_GATTS_ERROR_INSUFFICIENT_AUTHENTICATION	0x05	Klienten är inte autentiserad.
_GATTS_ERROR_INSUFFICIENT_AUTHORIZATION	0x08	Klienten är inte auktoriserad.
_GATTS_ERROR_INSUFFICIENT_ENCRYPTION	0x0f	Länken är inte krypterad.

För händelsen _IRQ_PASSKEY_ACTION är de tillgängliga åtgärderna:

Konstant	Värde	Betydelse
_PASSKEY_ACTION_NONE	0	Ingen åtgärd krävs.
_PASSKEY_ACTION_INPUT	2	Uppmana användaren att ange den lösenkod som visas på fjärrenheten.
_PASSKEY_ACTION_DISPLAY	3	Visa en sexsiffrig lösenkod som fjärrenheten ska ange.
_PASSKEY_ACTION_NUMERIC_COMPARISON	4	Bekräfta att lösenkoden matchar den som visas på fjärrenheten.

För att spara utrymme i den fasta programvaran ingår dessa konstanter inte i bluetooth-modulen. Lägg till de du behöver från listorna ovan i ditt program.

Broadcaster-roll (annonserare)

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

Startar annonsering med det angivna intervallet (i mikrosekunder). Detta intervall avrundas nedåt till närmaste 625 us. För att stoppa annonseringen, sätt interval_us till None.

adv_data och resp_data kan vara vilken typ som helst som implementerar buffertprotokollet (t.ex. bytes, bytearray, str). adv_data inkluderas i alla utsändningar, och resp_data skickas som svar på en aktiv skanning.

Obs: om adv_data (eller resp_data) är None, återanvänds datan som skickades till det föregående anropet av gap_advertise. Detta gör att en broadcaster kan återuppta annonsering med enbart gap_advertise(interval_us). För att rensa annonseringsnyttolasten, skicka en tom bytes, dvs. b''.

Observer-roll (skanner)

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

Kör en skanningsoperation som varar den angivna varaktigheten (i millisekunder).

För att skanna obegränsat, sätt duration_ms till 0.

För att stoppa skanningen, sätt duration_ms till None.

Använd interval_us och window_us för att valfritt konfigurera arbetscykeln. Skannern körs i window_us mikrosekunder var interval_us mikrosekund under totalt duration_ms millisekunder. Standardintervallet och -fönstret är 1,28 sekunder respektive 11,25 millisekunder (bakgrundsskanning).

För varje skanningsresultat utlöses händelsen _IRQ_SCAN_RESULT, med händelsedatan (addr_type, addr, adv_type, rssi, adv_data).

addr_type-värden anger publika eller slumpmässiga adresser:

Värde	Namn	Betydelse
0x00	PUBLIC	Publik enhetsadress.
0x01	RANDOM	Slumpmässig adress (antingen statisk, RPA eller NRPA; typen är kodad i själva adressen).

adv_type-värden motsvarar Bluetooth-specifikationen:

Värde	Namn	Betydelse
0x00	ADV_IND	Anslutningsbar och skanningsbar oriktad annonsering.
0x01	ADV_DIRECT_IND	Anslutningsbar riktad annonsering.
0x02	ADV_SCAN_IND	Skanningsbar oriktad annonsering.
0x03	ADV_NONCONN_IND	Icke anslutningsbar oriktad annonsering.
0x04	SCAN_RSP	Skanningssvar.

active kan sättas till True om du vill ta emot skanningssvar i resultaten.

När skanningen stoppas (antingen för att varaktigheten löpt ut eller när den stoppas explicit) utlöses händelsen _IRQ_SCAN_DONE.

Central-roll

En central enhet kan ansluta till peripheraler som den har upptäckt med observer-rollen (se gap_scan) eller med en känd adress.

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

Anslut till en peripheral.

Se gap_scan för detaljer om adresstyper.

För att avbryta ett utestående anslutningsförsök i förtid, anropa gap_connect(None).

Vid framgång utlöses händelsen _IRQ_PERIPHERAL_CONNECT. Om ett anslutningsförsök avbryts utlöses händelsen _IRQ_PERIPHERAL_DISCONNECT.

Enheten väntar upp till scan_duration_ms på att ta emot en annonseringsnyttolast från enheten.

Anslutningsintervallet kan konfigureras i mikrosekunder med antingen eller båda av min_conn_interval_us och max_conn_interval_us. Annars väljs ett standardintervall, vanligtvis mellan 30000 och 50000 mikrosekunder. Ett kortare intervall ökar genomströmningen, på bekostnad av strömförbrukningen.

Peripheral-roll

En peripheral enhet förväntas skicka anslutningsbara annonseringar (se gap_advertise). Den fungerar vanligtvis som en GATT-server, efter att först ha registrerat tjänster och karakteristiker med gatts_register_services.

När en central ansluter utlöses händelsen _IRQ_CENTRAL_CONNECT.

Central- och peripheral-roller

gap_disconnect(conn_handle: int, /) → bool

Koppla från det angivna anslutningshandtaget. Detta kan antingen vara en central som har anslutit till den här enheten (om den fungerar som peripheral) eller en peripheral som den här enheten tidigare anslutit till (om den fungerar som central).

Vid framgång utlöses händelsen _IRQ_PERIPHERAL_DISCONNECT eller _IRQ_CENTRAL_DISCONNECT.

Returnerar False om anslutningshandtaget inte var anslutet, och True annars.

GATT Server

En GATT-server har en uppsättning registrerade tjänster. Varje tjänst kan innehålla karakteristiker, som var och en har ett värde. Karakteristiker kan också innehålla deskriptorer, som själva har värden.

Dessa värden lagras lokalt och nås via sitt ”värdehandtag” som genereras under tjänsteregistreringen. De kan också läsas från eller skrivas till av en fjärrklientenhet. Dessutom kan en server ”notifiera” en karakteristik till en ansluten klient via ett anslutningshandtag.

En enhet i antingen central- eller peripheral-rollen kan fungera som GATT-server, men i de flesta fall är det vanligare att en peripheral enhet fungerar som server.

Karakteristiker och deskriptorer har en standardmaxstorlek på 20 byte (standard-ATT-MTU på 23 byte minus en 3-byte ATT-header; en större förhandlad MTU höjer inte i sig denna gräns). Allt som skrivs till dem av en klient trunkeras till denna längd. Däremot ökar varje lokal skrivning maxstorleken, så om du vill tillåta större skrivningar från en klient till en given karakteristik, använd gatts_write efter registreringen, t.ex. gatts_write(char_handle, bytes(100)).

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

Konfigurerar servern med de angivna tjänsterna och ersätter eventuella befintliga tjänster.

services_definition är en lista över services, där varje service är en tupel med två element som innehåller en UUID och en lista över characteristics.

Varje characteristic är en tupel med två eller tre element som innehåller en UUID, ett flags-värde och valfritt en lista över descriptors.

Varje descriptor är en tupel med två element som innehåller en UUID och ett flags-värde.

flags är en bitvis OR-kombination av flaggorna som definieras nedan. Dessa anger både beteendet hos karakteristiken (eller deskriptorn) samt säkerhets- och integritetskraven.

Returvärdet är en lista (ett element per tjänst) av tupler (varje element är ett värdehandtag). Karakteristik- och deskriptorhandtag plattas ut i samma tupel, i den ordning de definieras.

Följande exempel registrerar två tjänster (Heart Rate och 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),
)

De tre värdehandtagen (hr, tx, rx) kan användas med gatts_read, gatts_write, gatts_notify och gatts_indicate.

Obs: Annonsering måste stoppas innan tjänster registreras.

Tillgängliga flaggor för karakteristiker och deskriptorer är:

Konstant	Värde	Betydelse
_FLAG_BROADCAST	0x0001	Karakteristiken får sändas ut (broadcast).
_FLAG_READ	0x0002	Klienten får läsa värdet.
_FLAG_WRITE_NO_RESPONSE	0x0004	Klienten får skriva utan att förvänta sig ett svar.
_FLAG_WRITE	0x0008	Klienten får skriva med ett bekräftat svar.
_FLAG_NOTIFY	0x0010	Servern får skicka notifieringar (obekräftade).
_FLAG_INDICATE	0x0020	Servern får skicka indikeringar (bekräftade).
_FLAG_AUTHENTICATED_SIGNED_WRITE	0x0040	Klienten får utfärda signerade skrivningar.
_FLAG_AUX_WRITE	0x0100	Utökade egenskaper: köade/tillförlitliga skrivningar är tillåtna.
_FLAG_READ_ENCRYPTED	0x0200	Läsning kräver en krypterad länk.
_FLAG_READ_AUTHENTICATED	0x0400	Läsning kräver en autentiserad (MITM-skyddad) länk.
_FLAG_READ_AUTHORIZED	0x0800	Läsning kräver auktorisering på applikationsnivå.
_FLAG_WRITE_ENCRYPTED	0x1000	Skrivning kräver en krypterad länk.
_FLAG_WRITE_AUTHENTICATED	0x2000	Skrivning kräver en autentiserad (MITM-skyddad) länk.
_FLAG_WRITE_AUTHORIZED	0x4000	Skrivning kräver auktorisering på applikationsnivå.

Liksom med händelsekonstanterna ovan tillhandahålls dessa flaggor inte av bluetooth-modulen; kopiera de du behöver in i ditt program.

gatts_read(value_handle: int, /) → bytes

Läser det lokala värdet för detta handtag (som antingen har skrivits av gatts_write eller av en fjärrklient).

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

Skriver det lokala värdet för detta handtag, vilket kan läsas av en klient.

Om send_update är True kommer alla prenumererande klienter att notifieras (eller indikeras, beroende på vad de prenumererar på och vilka operationer karakteristiken stöder) om denna skrivning.

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

Skickar en notifieringsbegäran till en ansluten klient.

Om data är None (standard) skickas det aktuella lokala värdet (som angetts med gatts_write).

Annars, om data inte är None, skickas det värdet till klienten som en del av notifieringen. Det lokala värdet ändras inte.

Obs: Notifieringen skickas oavsett klientens prenumerationsstatus för denna karakteristik.

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

Skickar en indikeringsbegäran till en ansluten klient.

Om data är None (standard) skickas det aktuella lokala värdet (som angetts med gatts_write).

Annars, om data inte är None, skickas det värdet till klienten som en del av indikeringen. Det lokala värdet ändras inte.

Vid bekräftelse (eller misslyckande, t.ex. timeout) utlöses händelsen _IRQ_GATTS_INDICATE_DONE.

Obs: Indikeringen skickas oavsett klientens prenumerationsstatus för denna karakteristik.

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

Anger den interna buffertstorleken för ett värde i byte. Detta begränsar den största möjliga skrivning som kan tas emot. Standardvärdet är 20 byte (standard-ATT-MTU på 23 minus den 3-byte ATT-headern).

Att sätta append till True gör att alla fjärrskrivningar läggs till i, snarare än ersätter, det aktuella värdet. Som mest len byte kan buffras på detta sätt. När du använder gatts_read rensas värdet efter läsning. Denna funktion är användbar vid implementering av något som Nordic UART Service.

GATT Client

En GATT-klient kan upptäcka och läsa/skriva karakteristiker på en fjärr-GATT-server.

Det är vanligare att en enhet i central-rollen fungerar som GATT-klient, men det är också möjligt för en peripheral att fungera som klient för att upptäcka information om den central som har anslutit till den (t.ex. att läsa enhetsnamnet från enhetsinformationstjänsten).

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

Efterfrågar en ansluten servers tjänster.

Ange valfritt en tjänst-uuid för att endast efterfråga den tjänsten.

För varje upptäckt tjänst utlöses händelsen _IRQ_GATTC_SERVICE_RESULT, följt av _IRQ_GATTC_SERVICE_DONE vid slutförande.

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

Efterfrågar en ansluten server om karakteristiker i det angivna intervallet.

Ange valfritt en karakteristik-uuid för att endast efterfråga den karakteristiken.

Att skicka start_handle=1 och end_handle=0xffff täcker hela GATT-attributhandtagsintervallet, så denna kombination söker i praktiken igenom alla tjänster på fjärrenheten.

För varje upptäckt karakteristik utlöses händelsen _IRQ_GATTC_CHARACTERISTIC_RESULT, följt av _IRQ_GATTC_CHARACTERISTIC_DONE vid slutförande.

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

Efterfrågar en ansluten server om deskriptorer i det angivna intervallet.

För varje upptäckt deskriptor utlöses händelsen _IRQ_GATTC_DESCRIPTOR_RESULT, följt av _IRQ_GATTC_DESCRIPTOR_DONE vid slutförande.

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

Utfärdar en fjärrläsning till en ansluten server för det angivna karakteristik- eller deskriptorhandtaget.

När ett värde är tillgängligt utlöses händelsen _IRQ_GATTC_READ_RESULT, följt av _IRQ_GATTC_READ_DONE vid slutförande.

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

Utfärdar en fjärrskrivning till en ansluten server för det angivna karakteristik- eller deskriptorhandtaget.

Argumentet mode anger skrivbeteendet, där de värden som för närvarande stöds är:

• mode=0 (standard) är en skrivning utan svar: skrivningen skickas till fjärrservern men ingen bekräftelse returneras, och ingen händelse utlöses.

• mode=1 är en skrivning med svar: fjärrservern ombeds att skicka ett svar/en bekräftelse på att den tog emot datan.

Om ett svar tas emot från fjärrservern utlöses händelsen _IRQ_GATTC_WRITE_DONE.

gattc_exchange_mtu(conn_handle: int, /) → None

Initierar MTU-utbyte med en ansluten server, med den föredragna MTU:n som angetts med BLE.config(mtu=value).

Händelsen _IRQ_MTU_EXCHANGED utlöses när MTU-utbytet slutförs.

MTU-utbyte initieras vanligtvis av den centrala enheten; NimBLE stöder båda rollerna.

L2CAP anslutningsorienterade kanaler

Denna funktion möjliggör socketliknande datautbyte mellan två BLE-enheter. När enheterna är anslutna via GAP kan endera enheten lyssna efter att den andra ska ansluta på en numerisk PSM (Protocol/Service Multiplexer).

Endast en L2CAP-kanal kan vara aktiv åt gången (dvs. du kan inte ansluta medan du lyssnar).

Aktiva L2CAP-kanaler identifieras av anslutningshandtaget som de etablerades på och en CID (channel ID).

Anslutningsorienterade kanaler har inbyggd kreditbaserad flödeskontroll. Till skillnad från ATT, där enheter förhandlar om en gemensam MTU, anger både den lyssnande och den anslutande enheten var sin oberoende MTU som begränsar den maximala mängd utestående data som fjärrenheten kan skicka innan den är fullständigt konsumerad i l2cap_recvinto.

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

Börjar lyssna efter inkommande L2CAP-kanalbegäranden på den angivna psm med den lokala MTU:n satt till mtu.

När en fjärrenhet initierar en anslutning utlöses händelsen _IRQ_L2CAP_ACCEPT, vilket ger den lyssnande servern en chans att avvisa den inkommande anslutningen (genom att returnera ett heltal skilt från noll).

När anslutningen accepteras utlöses händelsen _IRQ_L2CAP_CONNECT, vilket gör att servern kan erhålla kanal-ID:t (CID) samt den lokala och fjärrens MTU.

Obs: Det är för närvarande inte möjligt att sluta lyssna.

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

Ansluter till en lyssnande motpart på den angivna psm med den lokala MTU:n satt till mtu.

Vid lyckad anslutning utlöses händelsen _IRQ_L2CAP_CONNECT, vilket gör att klienten kan erhålla CID:t samt den lokala och fjärrens (motpartens) MTU.

En misslyckad anslutning utlöser händelsen _IRQ_L2CAP_DISCONNECT med en status skild från noll.

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

Kopplar från en aktiv L2CAP-kanal med den angivna conn_handle och cid.

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

Skickar den angivna buf (som måste stödja buffertprotokollet) på L2CAP-kanalen som identifieras av conn_handle och cid.

Bufferten måste uppfylla båda gränserna: den får inte överskrida fjärrens (motpartens) MTU, och den får inte överskrida två gånger den lokala MTU:n.

Detta returnerar False om kanalen nu är ”stoppad” (stalled), vilket innebär att l2cap_send inte får anropas igen förrän händelsen _IRQ_L2CAP_SEND_READY tas emot (vilket sker när fjärrenheten beviljar fler krediter, vanligtvis efter att den har tagit emot och bearbetat datan).

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

Tar emot data från den angivna conn_handle och cid in i den tillhandahållna buf (som måste stödja buffertprotokollet, t.ex. bytearray eller memoryview).

Returnerar antalet byte som lästs från kanalen.

Om buf är None returneras antalet tillgängliga byte.

Obs: Efter att ha tagit emot händelsen _IRQ_L2CAP_RECV bör applikationen fortsätta anropa l2cap_recvinto tills inga fler byte är tillgängliga i mottagningsbufferten (vanligtvis upp till storleken på fjärrens (motpartens) MTU).

Tills mottagningsbufferten är tom beviljas fjärrenheten inga fler kanalkrediter och kan inte skicka mer data.

Parkoppling och bindning

Parkoppling gör att en anslutning kan krypteras och autentiseras via utbyte av hemligheter (med valfritt MITM-skydd via lösenkodsautentisering).

Bindning är processen att lagra dessa hemligheter i beständig lagring. När en enhet är bunden kan den lösa en lösbar privat adress (RPA) från en annan enhet baserat på den lagrade identitetslösningsnyckeln (IRK). För att stödja bindning måste en applikation implementera händelserna _IRQ_GET_SECRET och _IRQ_SET_SECRET.

gap_pair(conn_handle: int, /) → None

Initierar parkoppling med fjärrenheten.

Innan du anropar detta, säkerställ att konfigurationsalternativen io, mitm, le_secure och bond är inställda (via config).

Vid lyckad parkoppling utlöses händelsen _IRQ_ENCRYPTION_UPDATE.

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

Svarar på en _IRQ_PASSKEY_ACTION-händelse för den angivna conn_handle och action. Betydelsen av passkey beror på action (som i sin tur beror på den konfigurerade I/O-kapabiliteten):

Åtgärd	Krävt passkey-svar
_PASSKEY_ACTION_INPUT	Lösenkoden som användaren läser från fjärrenheten.
_PASSKEY_ACTION_DISPLAY	En lokalt genererad slumpmässig sexsiffrig lösenkod som visas för användaren.
_PASSKEY_ACTION_NUMERIC_COMPARISON	1 för att acceptera lösenkoden som visas i händelsen _IRQ_PASSKEY_ACTION, eller 0 för att avbryta parkopplingen.

class UUID

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

Skapar en UUID-instans med det angivna value. Bluetooth använder tre UUID-bredder; UUID accepterar vilken som helst av dem:

UUID-bredd	Accepterade value-typer	Exempel
16-bitars	int eller en 2-byte buffert (little-endian)	UUID(0x2908) eller UUID(b'\x08\x29')
32-bitars	4-byte buffert (little-endian)	UUID(b'\x08\x29\x00\x00')
128-bitars	16-byte buffert eller en strängavgränsad med bindestreck	UUID('6E400001-B5A3-F393-E0A9-E50E24DCCA9E')

16- och 32-bitars UUID:er är vanligtvis SIG-allokerade identifierare (se Bluetooth assigned numbers); 128-bitars UUID:er är normalt leverantörsdefinierade.