bluetooth — low-level Bluetooth

Deze module biedt een interface naar de ingebouwde Bluetooth-controller. Het ondersteunt Bluetooth Low Energy (BLE) in de rollen Central, Peripheral, Broadcaster en Observer, evenals GATT Server en Client en L2CAP-verbindingsgerichte kanalen. Een apparaat kan tegelijkertijd in meerdere rollen functioneren. Pairing en bonding worden eveneens ondersteund.

Deze API is bedoeld om aan te sluiten op het Bluetooth-protocol op laag niveau en biedt bouwstenen voor abstracties op hoger niveau, zoals specifieke apparaattypes.

Tip

Geef voor de meeste toepassingen de voorkeur aan de aioble-bibliotheek op hoger niveau, die een op asyncio gebaseerde wrapper rond deze module biedt. Zie aioble — Async BLE.

class BLE

class bluetooth.BLE

Retourneert het singleton BLE-object.

Configuratie

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

Wijzigt optioneel de actieve status van de BLE-radio en retourneert de huidige status.

De radio moet actief worden gemaakt voordat andere methoden van deze klasse gebruikt kunnen worden.

config(param: str, /) → Any

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

Haal configuratiewaarden van de BLE-interface op of stel ze in. Om een waarde op te halen moet de parameternaam tussen aanhalingstekens als string worden opgegeven, en er wordt slechts één parameter tegelijk opgevraagd. Om waarden in te stellen gebruikt u de keyword-syntaxis, en kunnen er één of meer parameters tegelijk worden ingesteld.

Momenteel ondersteunde waarden zijn:

• 'mac': Het huidige adres dat in gebruik is, afhankelijk van de huidige adresmodus. Dit retourneert een tuple van (addr_type, addr).

  Zie gap_scan voor details over het adrestype.

  Dit kan alleen worden opgevraagd terwijl de interface momenteel actief is.

• 'addr_mode': Stelt de adresmodus in. Waarden zijn:

  Waarde	Naam	Gedrag
  0x00	PUBLIC	Gebruik het publieke adres van de controller.
  0x01	RANDOM	Gebruik een gegenereerd statisch adres.
  0x02	RPA	Gebruik resolvable private addresses.
  0x03	NRPA	Gebruik non-resolvable private addresses.

  Standaard gebruikt de interface een PUBLIC-adres indien beschikbaar, anders gebruikt het een RANDOM-adres.

• 'gap_name': Haal de GAP-apparaatnaam op of stel deze in, die wordt gebruikt door de Generic Access service (UUID 0x1800), Device Name-karakteristiek (UUID 0x2a00). Dit kan op elk moment worden ingesteld en meerdere keren worden gewijzigd.

• 'rxbuf': Haal de grootte in bytes op of stel deze in van de interne buffer die wordt gebruikt om inkomende events op te slaan. Deze buffer is globaal voor de gehele BLE-driver en verwerkt dus inkomende data voor alle events, inclusief alle karakteristieken. Het verhogen hiervan zorgt voor betere verwerking van burst-gewijze inkomende data (bijvoorbeeld scanresultaten) en de mogelijkheid om grotere karakteristiekwaarden te ontvangen.

• 'mtu': Haal de MTU op of stel deze in die zal worden gebruikt tijdens een ATT MTU-uitwisseling. De resulterende MTU is het minimum van deze en de MTU van het externe apparaat. ATT MTU-uitwisseling gebeurt niet automatisch (tenzij het externe apparaat deze initieert), en moet handmatig worden geïnitieerd met gattc_exchange_mtu. Gebruik het _IRQ_MTU_EXCHANGED-event om de MTU voor een bepaalde verbinding te achterhalen.

• 'bond': Stelt in of bonding wordt ingeschakeld tijdens pairing. Wanneer ingeschakeld zullen pairingverzoeken de “bond”-vlag instellen en zullen de sleutels door beide apparaten worden opgeslagen.

• 'mitm': Stelt in of MITM-bescherming vereist is voor pairing.

• 'io': Stelt de I/O-mogelijkheden van dit apparaat in.

  Beschikbare opties zijn:

  Constante	Waarde	Mogelijkheid
  _IO_CAPABILITY_DISPLAY_ONLY	0	Alleen weergave
  _IO_CAPABILITY_DISPLAY_YESNO	1	Weergave met ja/nee-invoer
  _IO_CAPABILITY_KEYBOARD_ONLY	2	Alleen toetsenbord
  _IO_CAPABILITY_NO_INPUT_OUTPUT	3	Geen invoer of uitvoer
  _IO_CAPABILITY_KEYBOARD_DISPLAY	4	Toetsenbord en weergave

• 'le_secure': Stelt in of “LE Secure”-pairing vereist is. Standaard is dit false (d.w.z. “Legacy Pairing” toestaan).

Eventafhandeling

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

Registreert een callback voor events van de BLE-stack. De handler neemt twee argumenten, event (dat een van de onderstaande codes is) en data (dat een event-specifieke tuple van waarden is).

Opmerking: Als optimalisatie om onnodige allocaties te voorkomen, zijn de items addr, adv_data, char_data, notify_data en uuid in de tuples alleen-lezen memoryview-instanties die wijzen naar de interne ringbuffer van bluetooth, en zijn ze alleen geldig tijdens de uitvoering van de IRQ-handlerfunctie. Als uw programma een van deze waarden moet opslaan om er na het terugkeren van de IRQ-handler toegang toe te hebben (bijv. door het op te slaan in een klasse-instantie of globale variabele), dan moet het een kopie van de data maken, ofwel met bytes() of bluetooth.UUID(), zoals zo:

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

De IRQ-handler voor een scanresultaat zou bijvoorbeeld de adv_data kunnen inspecteren om te bepalen of het het juiste apparaat is, en pas dan de adresdata kopiëren om elders in het programma te gebruiken. En om data binnen de IRQ-handler af te drukken is print(bytes(addr)) nodig.

Een handler dispatcht doorgaans op basis van de eventcode en pakt de event-specifieke payload-tuple uit:

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

Elke eventcode, de payload die deze levert en een korte beschrijving worden hieronder vermeld. Voor events waarvan het status-veld wordt genoemd, is status 0 bij succes en een implementatiespecifieke waarde verschillend van nul bij mislukking.

Constante	Waarde	Event	Payload-tuple
_IRQ_CENTRAL_CONNECT	1	Een central heeft verbinding gemaakt met dit peripheral.	(conn_handle, addr_type, addr)
_IRQ_CENTRAL_DISCONNECT	2	Een central heeft de verbinding met dit peripheral verbroken.	(conn_handle, addr_type, addr)
_IRQ_GATTS_WRITE	3	Een verbonden client heeft naar een lokale karakteristiek of descriptor geschreven. Gebruik gatts_read om de nieuwe waarde op te halen.	(conn_handle, attr_handle)
_IRQ_GATTS_READ_REQUEST	4	Een verbonden client heeft een leesverzoek uitgevoerd. Retourneer een foutcode verschillend van nul uit de onderstaande tabel om het lezen te weigeren, of 0 / None om het te accepteren.	(conn_handle, attr_handle)
_IRQ_SCAN_RESULT	5	Er is een enkel advertentiepakket ontvangen tijdens een actieve scan.	(addr_type, addr, adv_type, rssi, adv_data)
_IRQ_SCAN_DONE	6	De huidige scan is beëindigd, ofwel omdat de geconfigureerde duur is verstreken of omdat gap_scan(None) is aangeroepen.	()
_IRQ_PERIPHERAL_CONNECT	7	Een eerder uitgevoerde gap_connect is geslaagd.	(conn_handle, addr_type, addr)
_IRQ_PERIPHERAL_DISCONNECT	8	Een verbonden peripheral heeft de verbinding verbroken.	(conn_handle, addr_type, addr)
_IRQ_GATTC_SERVICE_RESULT	9	Eén service is gevonden door gattc_discover_services.	(conn_handle, start_handle, end_handle, uuid)
_IRQ_GATTC_SERVICE_DONE	10	Het ontdekken van services is voltooid.	(conn_handle, status)
_IRQ_GATTC_CHARACTERISTIC_RESULT	11	Eén karakteristiek is gevonden door gattc_discover_characteristics.	(conn_handle, end_handle, value_handle, properties, uuid)
_IRQ_GATTC_CHARACTERISTIC_DONE	12	Het ontdekken van karakteristieken is voltooid.	(conn_handle, status)
_IRQ_GATTC_DESCRIPTOR_RESULT	13	Eén descriptor is gevonden door gattc_discover_descriptors.	(conn_handle, dsc_handle, uuid)
_IRQ_GATTC_DESCRIPTOR_DONE	14	Het ontdekken van descriptors is voltooid.	(conn_handle, status)
_IRQ_GATTC_READ_RESULT	15	Een eerder uitgevoerde gattc_read heeft data geretourneerd.	(conn_handle, value_handle, char_data)
_IRQ_GATTC_READ_DONE	16	Een eerder uitgevoerde gattc_read is voltooid.	(conn_handle, value_handle, status)
_IRQ_GATTC_WRITE_DONE	17	Een eerder uitgevoerde gattc_write is bevestigd.	(conn_handle, value_handle, status)
_IRQ_GATTC_NOTIFY	18	Een externe server heeft een (onbevestigde) notificatie verzonden.	(conn_handle, value_handle, notify_data)
_IRQ_GATTC_INDICATE	19	Een externe server heeft een (bevestigde) indicatie verzonden.	(conn_handle, value_handle, notify_data)
_IRQ_GATTS_INDICATE_DONE	20	Een eerder verzonden indicatie is bevestigd door de client (of er is een time-out opgetreden).	(conn_handle, value_handle, status)
_IRQ_MTU_EXCHANGED	21	Een ATT MTU-uitwisseling is voltooid (geïnitieerd door een van beide kanten).	(conn_handle, mtu)
_IRQ_L2CAP_ACCEPT	22	Een extern apparaat heeft een L2CAP-verbinding aangevraagd op een PSM waarop dit apparaat luistert. Retourneer een geheel getal verschillend van nul om te weigeren, of 0 / None om te accepteren.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_CONNECT	23	Er is nu een L2CAP-kanaal tot stand gebracht, ofwel door een inkomend verzoek te accepteren of door een uitgaande l2cap_connect te voltooien.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_DISCONNECT	24	Een L2CAP-kanaal is verbroken. status is 0 bij een schone verbreking, of verschillend van nul als een uitgaande verbindingspoging is mislukt.	(conn_handle, cid, psm, status)
_IRQ_L2CAP_RECV	25	Er is data binnengekomen op een L2CAP-kanaal. Roep l2cap_recvinto aan om het te lezen.	(conn_handle, cid)
_IRQ_L2CAP_SEND_READY	26	Een eerdere l2cap_send die False retourneerde is afgevoerd en het kanaal is weer gereed. Een status verschillend van nul betekent dat de verzendbuffer is overgelopen en dat de applicatie de data opnieuw moet verzenden.	(conn_handle, cid, status)
_IRQ_CONNECTION_UPDATE	27	Het externe apparaat heeft de verbindingsparameters bijgewerkt (interval, latentie, supervision-time-out).	(conn_handle, conn_interval, conn_latency, supervision_timeout, status)
_IRQ_ENCRYPTION_UPDATE	28	De encryptiestatus van een verbinding is gewijzigd, doorgaans nadat pairing of bonding is voltooid.	(conn_handle, encrypted, authenticated, bonded, key_size)
_IRQ_GET_SECRET	29	De stack vraagt om een opgeslagen bonding-secret. Als key None is, retourneer dan de indexde opgeslagen waarde van sec_type; retourneer anders de waarde die hoort bij de opgegeven (sec_type, key). Retourneer None als er niets is opgeslagen.	(sec_type, index, key)
_IRQ_SET_SECRET	30	De stack vraagt de applicatie om een bonding-secret op te slaan. Retourneer True zodra dit is opgeslagen.	(sec_type, key, value)
_IRQ_PASSKEY_ACTION	31	Een passkey-actie is vereist als onderdeel van de pairing. Reageer met gap_passkey; zie de onderstaande passkey-actietabel voor de mogelijke acties.	(conn_handle, action, passkey)

Voor het _IRQ_GATTS_READ_REQUEST-event zijn de beschikbare retourcodes:

Constante	Waarde	Betekenis
_GATTS_NO_ERROR	0x00	Accepteer het leesverzoek.
_GATTS_ERROR_READ_NOT_PERMITTED	0x02	Lezen niet toegestaan.
_GATTS_ERROR_WRITE_NOT_PERMITTED	0x03	Schrijven niet toegestaan.
_GATTS_ERROR_INSUFFICIENT_AUTHENTICATION	0x05	Client is niet geauthenticeerd.
_GATTS_ERROR_INSUFFICIENT_AUTHORIZATION	0x08	Client is niet geautoriseerd.
_GATTS_ERROR_INSUFFICIENT_ENCRYPTION	0x0f	Verbinding is niet versleuteld.

Voor het _IRQ_PASSKEY_ACTION-event zijn de beschikbare acties:

Constante	Waarde	Betekenis
_PASSKEY_ACTION_NONE	0	Geen actie vereist.
_PASSKEY_ACTION_INPUT	2	Vraag de gebruiker om de passkey in te voeren die op het externe apparaat wordt weergegeven.
_PASSKEY_ACTION_DISPLAY	3	Geef een passkey van 6 cijfers weer die het externe apparaat moet invoeren.
_PASSKEY_ACTION_NUMERIC_COMPARISON	4	Bevestig dat de passkey overeenkomt met die op het externe apparaat wordt weergegeven.

Om ruimte te besparen in de firmware zijn deze constanten niet opgenomen in de bluetooth-module. Voeg de constanten die u nodig hebt uit de bovenstaande lijsten toe aan uw programma.

Broadcaster-rol (Advertiser)

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

Begint met adverteren op het opgegeven interval (in microseconden). Dit interval wordt naar beneden afgerond op de dichtstbijzijnde 625us. Om te stoppen met adverteren, stelt u interval_us in op None.

adv_data en resp_data kunnen elk type zijn dat het bufferprotocol implementeert (bijv. bytes, bytearray, str). adv_data wordt opgenomen in alle uitzendingen, en resp_data wordt verzonden als antwoord op een actieve scan.

Opmerking: als adv_data (of resp_data) None is, dan wordt de data die aan de vorige aanroep van gap_advertise is doorgegeven hergebruikt. Hiermee kan een broadcaster het adverteren hervatten met enkel gap_advertise(interval_us). Om de advertentiepayload te wissen geeft u een lege bytes door, d.w.z. b''.

Observer-rol (Scanner)

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

Voer een scanbewerking uit die de opgegeven duur duurt (in milliseconden).

Om onbeperkt te scannen, stelt u duration_ms in op 0.

Om te stoppen met scannen, stelt u duration_ms in op None.

Gebruik interval_us en window_us om optioneel de duty cycle te configureren. De scanner zal window_us microseconden lopen elke interval_us microseconden, gedurende een totaal van duration_ms milliseconden. Het standaardinterval en -venster zijn respectievelijk 1,28 seconden en 11,25 milliseconden (achtergrondscannen).

Voor elk scanresultaat wordt het _IRQ_SCAN_RESULT-event opgeroepen, met eventdata (addr_type, addr, adv_type, rssi, adv_data).

addr_type-waarden geven publieke of willekeurige adressen aan:

Waarde	Naam	Betekenis
0x00	PUBLIC	Publiek apparaatadres.
0x01	RANDOM	Willekeurig adres (statisch, RPA of NRPA; het type is gecodeerd in het adres zelf).

adv_type-waarden komen overeen met de Bluetooth-specificatie:

Waarde	Naam	Betekenis
0x00	ADV_IND	Verbindbare en scanbare niet-gerichte advertentie.
0x01	ADV_DIRECT_IND	Verbindbare gerichte advertentie.
0x02	ADV_SCAN_IND	Scanbare niet-gerichte advertentie.
0x03	ADV_NONCONN_IND	Niet-verbindbare niet-gerichte advertentie.
0x04	SCAN_RSP	Scanantwoord.

active kan op True worden gezet als u scanantwoorden in de resultaten wilt ontvangen.

Wanneer het scannen wordt gestopt (ofwel omdat de duur is verstreken of wanneer het expliciet wordt gestopt), wordt het _IRQ_SCAN_DONE-event opgeroepen.

Central-rol

Een central-apparaat kan verbinding maken met peripherals die het heeft ontdekt via de observer-rol (zie gap_scan) of met een bekend adres.

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

Maak verbinding met een peripheral.

Zie gap_scan voor details over adrestypes.

Om een lopende verbindingspoging vroegtijdig te annuleren, roept u gap_connect(None) aan.

Bij succes wordt het _IRQ_PERIPHERAL_CONNECT-event opgeroepen. Bij het annuleren van een verbindingspoging wordt het _IRQ_PERIPHERAL_DISCONNECT-event opgeroepen.

Het apparaat wacht maximaal scan_duration_ms om een advertentiepayload van het apparaat te ontvangen.

Het verbindingsinterval kan in microseconden worden geconfigureerd met behulp van min_conn_interval_us en/of max_conn_interval_us. Anders wordt een standaardinterval gekozen, doorgaans tussen 30000 en 50000 microseconden. Een korter interval verhoogt de doorvoer, ten koste van het stroomverbruik.

Peripheral-rol

Een peripheral-apparaat wordt verondersteld verbindbare advertenties te verzenden (zie gap_advertise). Het zal gewoonlijk fungeren als een GATT-server, nadat het eerst services en karakteristieken heeft geregistreerd met gatts_register_services.

Wanneer een central verbinding maakt, wordt het _IRQ_CENTRAL_CONNECT-event opgeroepen.

Central- en Peripheral-rollen

gap_disconnect(conn_handle: int, /) → bool

Verbreek de opgegeven verbindingshandle. Dit kan ofwel een central zijn die verbinding heeft gemaakt met dit apparaat (als het als peripheral fungeert) of een peripheral waarmee dit apparaat eerder verbinding heeft gemaakt (als het als central fungeert).

Bij succes wordt het _IRQ_PERIPHERAL_DISCONNECT- of _IRQ_CENTRAL_DISCONNECT-event opgeroepen.

Retourneert False als de verbindingshandle niet verbonden was, en anders True.

GATT-server

Een GATT-server heeft een set geregistreerde services. Elke service kan karakteristieken bevatten, die elk een waarde hebben. Karakteristieken kunnen ook descriptors bevatten, die zelf waarden hebben.

Deze waarden worden lokaal opgeslagen en zijn toegankelijk via hun “value handle” die wordt gegenereerd tijdens de serviceregistratie. Ze kunnen ook worden gelezen van of geschreven naar een extern client-apparaat. Daarnaast kan een server een karakteristiek “notificeren” naar een verbonden client via een verbindingshandle.

Een apparaat in de central- of peripheral-rol kan fungeren als GATT-server, hoewel het in de meeste gevallen gebruikelijker is dat een peripheral-apparaat als server fungeert.

Karakteristieken en descriptors hebben een standaard maximale grootte van 20 bytes (de standaard ATT MTU van 23 bytes minus een ATT-header van 3 bytes; een grotere onderhandelde MTU verhoogt deze limiet op zichzelf niet). Alles wat een client ernaar schrijft wordt tot deze lengte afgekapt. Elke lokale schrijfactie verhoogt echter de maximale grootte, dus als u grotere schrijfacties van een client naar een bepaalde karakteristiek wilt toestaan, gebruik dan gatts_write na registratie, bijv. gatts_write(char_handle, bytes(100)).

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

Configureert de server met de opgegeven services, waarbij eventuele bestaande services worden vervangen.

services_definition is een lijst van services, waarbij elke service een tuple van twee elementen is die een UUID en een lijst van characteristics bevat.

Elke characteristic is een tuple van twee of drie elementen die een UUID, een flags-waarde en optioneel een lijst van descriptors bevat.

Elke descriptor is een tuple van twee elementen die een UUID en een flags-waarde bevat.

De flags zijn een bitsgewijze OR-combinatie van de hieronder gedefinieerde flags. Deze stellen zowel het gedrag van de karakteristiek (of descriptor) in als de beveiligings- en privacyvereisten.

De retourwaarde is een lijst (één element per service) van tuples (elk element is een value handle). Karakteristiek- en descriptorhandles worden in dezelfde tuple afgevlakt, in de volgorde waarin ze zijn gedefinieerd.

Het volgende voorbeeld registreert twee services (Heart Rate en 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 drie value handles (hr, tx, rx) kunnen worden gebruikt met gatts_read, gatts_write, gatts_notify en gatts_indicate.

Opmerking: Het adverteren moet worden gestopt voordat services worden geregistreerd.

Beschikbare flags voor karakteristieken en descriptors zijn:

Constante	Waarde	Betekenis
_FLAG_BROADCAST	0x0001	Karakteristiek mag worden uitgezonden.
_FLAG_READ	0x0002	Client mag de waarde lezen.
_FLAG_WRITE_NO_RESPONSE	0x0004	Client mag schrijven zonder een antwoord te verwachten.
_FLAG_WRITE	0x0008	Client mag schrijven met een bevestigd antwoord.
_FLAG_NOTIFY	0x0010	Server mag notificaties verzenden (onbevestigd).
_FLAG_INDICATE	0x0020	Server mag indicaties verzenden (bevestigd).
_FLAG_AUTHENTICATED_SIGNED_WRITE	0x0040	Client mag ondertekende schrijfacties uitvoeren.
_FLAG_AUX_WRITE	0x0100	Uitgebreide eigenschappen: queued/reliable writes zijn toegestaan.
_FLAG_READ_ENCRYPTED	0x0200	Lezen vereist een versleutelde verbinding.
_FLAG_READ_AUTHENTICATED	0x0400	Lezen vereist een geauthenticeerde (MITM-beschermde) verbinding.
_FLAG_READ_AUTHORIZED	0x0800	Lezen vereist autorisatie op applicatieniveau.
_FLAG_WRITE_ENCRYPTED	0x1000	Schrijven vereist een versleutelde verbinding.
_FLAG_WRITE_AUTHENTICATED	0x2000	Schrijven vereist een geauthenticeerde (MITM-beschermde) verbinding.
_FLAG_WRITE_AUTHORIZED	0x4000	Schrijven vereist autorisatie op applicatieniveau.

Net als bij de bovenstaande eventconstanten worden deze flags niet geleverd door de bluetooth-module; kopieer de flags die u nodig hebt naar uw programma.

gatts_read(value_handle: int, /) → bytes

Leest de lokale waarde voor deze handle (die ofwel is geschreven door gatts_write of door een externe client).

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

Schrijft de lokale waarde voor deze handle, die door een client kan worden gelezen.

Als send_update True is, dan worden alle geabonneerde clients geïnformeerd (via notificatie of indicatie, afhankelijk van waarop ze zijn geabonneerd en welke bewerkingen de karakteristiek ondersteunt) over deze schrijfactie.

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

Verzendt een notificatieverzoek naar een verbonden client.

Als data None is (de standaard), dan wordt de huidige lokale waarde (zoals ingesteld met gatts_write) verzonden.

Anders, als data niet None is, dan wordt die waarde naar de client verzonden als onderdeel van de notificatie. De lokale waarde wordt niet gewijzigd.

Opmerking: De notificatie wordt verzonden ongeacht de abonnementsstatus van de client op deze karakteristiek.

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

Verzendt een indicatieverzoek naar een verbonden client.

Als data None is (de standaard), dan wordt de huidige lokale waarde (zoals ingesteld met gatts_write) verzonden.

Anders, als data niet None is, dan wordt die waarde naar de client verzonden als onderdeel van de indicatie. De lokale waarde wordt niet gewijzigd.

Bij bevestiging (of mislukking, bijv. time-out) wordt het _IRQ_GATTS_INDICATE_DONE-event opgeroepen.

Opmerking: De indicatie wordt verzonden ongeacht de abonnementsstatus van de client op deze karakteristiek.

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

Stelt de interne buffergrootte voor een waarde in bytes in. Dit beperkt de grootst mogelijke schrijfactie die kan worden ontvangen. De standaard is 20 bytes (standaard ATT MTU van 23 minus de ATT-header van 3 bytes).

Het instellen van append op True zorgt ervoor dat alle externe schrijfacties aan de huidige waarde worden toegevoegd in plaats van deze te vervangen. Maximaal len bytes kunnen op deze manier worden gebufferd. Wanneer u gatts_read gebruikt, wordt de waarde na het lezen gewist. Deze functie is nuttig bij het implementeren van iets als de Nordic UART Service.

GATT-client

Een GATT-client kan karakteristieken op een externe GATT-server ontdekken en lezen/schrijven.

Het is gebruikelijker dat een apparaat in de central-rol als GATT-client fungeert, maar het is ook mogelijk dat een peripheral als client fungeert om informatie te ontdekken over de central die er verbinding mee heeft gemaakt (bijv. om de apparaatnaam te lezen uit de device information service).

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

Vraag een verbonden server op om zijn services.

Geef optioneel een service-uuid op om alleen die service op te vragen.

Voor elke ontdekte service wordt het _IRQ_GATTC_SERVICE_RESULT-event opgeroepen, gevolgd door _IRQ_GATTC_SERVICE_DONE bij voltooiing.

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

Vraag een verbonden server op om karakteristieken in het opgegeven bereik.

Geef optioneel een karakteristiek-uuid op om alleen die karakteristiek op te vragen.

Het doorgeven van start_handle=1 en end_handle=0xffff dekt het volledige bereik van GATT-attribuuthandles, dus deze combinatie doorzoekt in feite elke service op het externe apparaat.

Voor elke ontdekte karakteristiek wordt het _IRQ_GATTC_CHARACTERISTIC_RESULT-event opgeroepen, gevolgd door _IRQ_GATTC_CHARACTERISTIC_DONE bij voltooiing.

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

Vraag een verbonden server op om descriptors in het opgegeven bereik.

Voor elke ontdekte descriptor wordt het _IRQ_GATTC_DESCRIPTOR_RESULT-event opgeroepen, gevolgd door _IRQ_GATTC_DESCRIPTOR_DONE bij voltooiing.

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

Voer een extern leesverzoek uit naar een verbonden server voor de opgegeven karakteristiek- of descriptorhandle.

Wanneer een waarde beschikbaar is, wordt het _IRQ_GATTC_READ_RESULT-event opgeroepen, gevolgd door _IRQ_GATTC_READ_DONE bij voltooiing.

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

Voer een externe schrijfactie uit naar een verbonden server voor de opgegeven karakteristiek- of descriptorhandle.

Het argument mode specificeert het schrijfgedrag, waarbij de momenteel ondersteunde waarden zijn:

• mode=0 (standaard) is een write-without-response: de schrijfactie wordt naar de externe server verzonden maar er wordt geen bevestiging geretourneerd, en er wordt geen event opgeroepen.

• mode=1 is een write-with-response: de externe server wordt verzocht een antwoord/bevestiging te verzenden dat het de data heeft ontvangen.

Als er een antwoord van de externe server wordt ontvangen, wordt het _IRQ_GATTC_WRITE_DONE-event opgeroepen.

gattc_exchange_mtu(conn_handle: int, /) → None

Initieer MTU-uitwisseling met een verbonden server, met behulp van de voorkeurs-MTU die is ingesteld met BLE.config(mtu=value).

Het _IRQ_MTU_EXCHANGED-event wordt opgeroepen wanneer de MTU-uitwisseling is voltooid.

MTU-uitwisseling wordt doorgaans geïnitieerd door de central; NimBLE ondersteunt beide rollen.

L2CAP-verbindingsgerichte kanalen

Deze functie maakt socket-achtige data-uitwisseling tussen twee BLE-apparaten mogelijk. Zodra de apparaten via GAP zijn verbonden, kan een van beide apparaten luisteren tot het andere verbinding maakt op een numerieke PSM (Protocol/Service Multiplexer).

Er kan slechts één L2CAP-kanaal tegelijk actief zijn (d.w.z. u kunt niet verbinden terwijl u luistert).

Actieve L2CAP-kanalen worden geïdentificeerd door de verbindingshandle waarop ze tot stand zijn gebracht en een CID (channel ID).

Verbindingsgerichte kanalen hebben ingebouwde credit-gebaseerde flow control. In tegenstelling tot ATT, waar apparaten een gedeelde MTU onderhandelen, stellen zowel het luisterende als het verbindende apparaat elk een onafhankelijke MTU in die de maximale hoeveelheid uitstaande data beperkt die het externe apparaat kan verzenden voordat deze volledig is verwerkt in l2cap_recvinto.

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

Begin met luisteren naar inkomende L2CAP-kanaalverzoeken op de opgegeven psm met de lokale MTU ingesteld op mtu.

Wanneer een extern apparaat een verbinding initieert, wordt het _IRQ_L2CAP_ACCEPT-event opgeroepen, wat de luisterende server de kans geeft om de inkomende verbinding te weigeren (door een geheel getal verschillend van nul te retourneren).

Zodra de verbinding is geaccepteerd, wordt het _IRQ_L2CAP_CONNECT-event opgeroepen, waardoor de server de channel ID (CID) en de lokale en externe MTU kan verkrijgen.

Opmerking: Het is momenteel niet mogelijk om te stoppen met luisteren.

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

Maak verbinding met een luisterende peer op de opgegeven psm met de lokale MTU ingesteld op mtu.

Bij een succesvolle verbinding wordt het _IRQ_L2CAP_CONNECT-event opgeroepen, waardoor de client de CID en de lokale en externe (peer) MTU kan verkrijgen.

Een onsuccesvolle verbinding roept het _IRQ_L2CAP_DISCONNECT-event op met een status verschillend van nul.

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

Verbreek een actief L2CAP-kanaal met de opgegeven conn_handle en cid.

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

Verzend de opgegeven buf (die het bufferprotocol moet ondersteunen) op het L2CAP-kanaal dat wordt geïdentificeerd door conn_handle en cid.

De buffer moet aan beide limieten voldoen: deze mag de externe (peer) MTU niet overschrijden, en deze mag niet meer dan tweemaal de lokale MTU bedragen.

Dit retourneert False als het kanaal nu “stalled” is, wat betekent dat l2cap_send niet opnieuw mag worden aangeroepen totdat het _IRQ_L2CAP_SEND_READY-event is ontvangen (wat gebeurt wanneer het externe apparaat meer credits verleent, doorgaans nadat het de data heeft ontvangen en verwerkt).

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

Ontvang data van de opgegeven conn_handle en cid in de meegegeven buf (die het bufferprotocol moet ondersteunen, bijv. bytearray of memoryview).

Retourneert het aantal bytes dat van het kanaal is gelezen.

Als buf None is, dan retourneert het het aantal beschikbare bytes.

Opmerking: Na ontvangst van het _IRQ_L2CAP_RECV-event moet de applicatie l2cap_recvinto blijven aanroepen totdat er geen bytes meer beschikbaar zijn in de ontvangstbuffer (doorgaans tot de grootte van de externe (peer) MTU).

Totdat de ontvangstbuffer leeg is, krijgt het externe apparaat geen extra kanaalcredits toegekend en kan het geen data meer verzenden.

Pairing en bonding

Pairing maakt het mogelijk om een verbinding te versleutelen en te authenticeren via uitwisseling van secrets (met optionele MITM-bescherming via passkey-authenticatie).

Bonding is het proces van het opslaan van die secrets in niet-vluchtige opslag. Wanneer een apparaat is gebonden, kan het een resolvable private address (RPA) van een ander apparaat oplossen op basis van de opgeslagen identity resolving key (IRK). Om bonding te ondersteunen moet een applicatie de events _IRQ_GET_SECRET en _IRQ_SET_SECRET implementeren.

gap_pair(conn_handle: int, /) → None

Initieer pairing met het externe apparaat.

Zorg er voordat u dit aanroept voor dat de configuratieopties io, mitm, le_secure en bond zijn ingesteld (via config).

Bij een succesvolle pairing wordt het _IRQ_ENCRYPTION_UPDATE-event opgeroepen.

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

Reageer op een _IRQ_PASSKEY_ACTION-event voor de opgegeven conn_handle en action. De betekenis van passkey hangt af van action (die op zijn beurt afhangt van de geconfigureerde I/O-mogelijkheid):

Actie	Vereist passkey-antwoord
_PASSKEY_ACTION_INPUT	De passkey die de gebruiker afleest van het externe apparaat.
_PASSKEY_ACTION_DISPLAY	Een lokaal gegenereerde willekeurige passkey van 6 cijfers die aan de gebruiker wordt getoond.
_PASSKEY_ACTION_NUMERIC_COMPARISON	1 om de passkey te accepteren die wordt weergegeven in het _IRQ_PASSKEY_ACTION-event, of 0 om de pairing te annuleren.

class UUID

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

Maakt een UUID-instantie met de opgegeven value. Bluetooth gebruikt drie UUID-breedtes; UUID accepteert elk daarvan:

UUID-breedte	Geaccepteerde value-types	Voorbeeld
16-bit	int of een buffer van 2 bytes (little-endian)	UUID(0x2908) of UUID(b'\x08\x29')
32-bit	buffer van 4 bytes (little-endian)	UUID(b'\x08\x29\x00\x00')
128-bit	buffer van 16 bytes of een string met koppeltekens	UUID('6E400001-B5A3-F393-E0A9-E50E24DCCA9E')

16- en 32-bit UUIDs zijn doorgaans door SIG toegewezen identifiers (zie de Bluetooth assigned numbers); 128-bit UUIDs zijn normaal gesproken vendor-gedefinieerd.