`bluetooth` — matalan tason Bluetooth¶

Tämä moduuli tarjoaa rajapinnan sisäänrakennettuun Bluetooth-ohjaimeen. Se tukee Bluetooth Low Energy (BLE) -tekniikkaa Central-, Peripheral-, Broadcaster- ja Observer-rooleissa sekä GATT-palvelinta ja -asiakasta ja yhteyspohjaisia L2CAP-kanavia. Laite voi toimia useassa roolissa samanaikaisesti. Myös pariutusta (pairing) ja sidontaa (bonding) tuetaan.

Tämä rajapinta on tarkoitettu vastaamaan matalan tason Bluetooth-protokollaa ja tarjoamaan rakennuspalikoita korkeamman tason abstraktioille, kuten tietyille laitetyypeille.

Vihje

Suosi useimmissa sovelluksissa korkeamman tason aioble-kirjastoa, joka tarjoaa asyncio-pohjaisen kääreen tämän moduulin ympärille. Katso aioble — Asynkroninen BLE.

class BLE¶

class bluetooth.BLE¶

Palauttaa BLE-singleton-olion.

Konfigurointi

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

Vaihtaa valinnaisesti BLE-radion aktiivisen tilan ja palauttaa nykyisen tilan.

Radio on aktivoitava ennen tämän luokan muiden metodien käyttöä.

config(param: str, /) → Any¶

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

Hae tai aseta BLE-rajapinnan konfigurointiarvoja. Arvon hakemiseksi parametrin nimi on annettava lainausmerkeissä merkkijonona, ja vain yksi parametri kysytään kerrallaan. Arvojen asettamiseen käytetään avainsanasyntaksia, ja yksi tai useampi parametri voidaan asettaa kerrallaan.

Tällä hetkellä tuettuja arvoja ovat:

'mac': Tällä hetkellä käytössä oleva osoite, joka riippuu nykyisestä osoitetilasta. Tämä palauttaa monikon (addr_type, addr).

Katso gap_scan saadaksesi lisätietoja osoitetyypistä.

Tätä voidaan kysyä vain, kun rajapinta on parhaillaan aktiivinen.

'addr_mode': Asettaa osoitetilan. Arvot ovat:

Arvo	Nimi	Toiminta
`0x00`	PUBLIC	Käytä ohjaimen julkista osoitetta.
`0x01`	RANDOM	Käytä generoitua staattista osoitetta.
`0x02`	RPA	Käytä ratkaistavissa olevia yksityisiä osoitteita.
`0x03`	NRPA	Käytä ei-ratkaistavissa olevia yksityisiä osoitteita.

Oletuksena rajapinta käyttää PUBLIC-osoitetta, jos sellainen on saatavilla, muutoin se käyttää RANDOM-osoitetta.

'gap_name': Hae/aseta GAP-laitenimi, jota käyttää Generic Access -palvelu (UUID 0x1800), Device Name -ominaisuus (UUID 0x2a00). Tämä voidaan asettaa milloin tahansa ja muuttaa useita kertoja.
'rxbuf': Hae/aseta sisäisen puskurin koko tavuina, jota käytetään saapuvien tapahtumien tallentamiseen. Tämä puskuri on globaali koko BLE-ajurille ja käsittelee siten saapuvan datan kaikille tapahtumille, mukaan lukien kaikki ominaisuudet. Tämän kasvattaminen mahdollistaa purskeisen saapuvan datan (esimerkiksi skannaustulosten) paremman käsittelyn sekä suurempien ominaisuusarvojen vastaanottamisen.
'mtu': Hae/aseta MTU, jota käytetään ATT MTU -vaihdon aikana. Tuloksena oleva MTU on tämän ja etälaitteen MTU:n pienempi arvo. ATT MTU -vaihto ei tapahdu automaattisesti (ellei etälaite käynnistä sitä), ja se on käynnistettävä manuaalisesti metodilla gattc_exchange_mtu. Käytä _IRQ_MTU_EXCHANGED-tapahtumaa saadaksesi tietyn yhteyden MTU:n selville.
'bond': Asettaa, otetaanko sidonta käyttöön pariutuksen aikana. Kun käytössä, pariutuspyynnöt asettavat ”bond”-lipun ja avaimet tallennetaan molempiin laitteisiin.
'mitm': Asettaa, vaaditaanko MITM-suojaus pariutukseen.

'io': Asettaa tämän laitteen I/O-ominaisuudet.

Käytettävissä olevat vaihtoehdot ovat:

Vakio	Arvo	Ominaisuus
`_IO_CAPABILITY_DISPLAY_ONLY`	0	Vain näyttö
`_IO_CAPABILITY_DISPLAY_YESNO`	1	Näyttö kyllä/ei-syötteellä
`_IO_CAPABILITY_KEYBOARD_ONLY`	2	Vain näppäimistö
`_IO_CAPABILITY_NO_INPUT_OUTPUT`	3	Ei syöttöä eikä tulostusta
`_IO_CAPABILITY_KEYBOARD_DISPLAY`	4	Näppäimistö ja näyttö

'le_secure': Asettaa, vaaditaanko ”LE Secure” -pariutus. Oletus on epätosi (eli sallii ”Legacy Pairing” -pariutuksen).

Tapahtumien käsittely

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

Rekisteröi takaisinkutsun BLE-pinon tapahtumille. handler ottaa kaksi argumenttia, event (joka on jokin alla olevista koodeista) ja data (joka on tapahtumakohtainen arvojen monikko).

Huomautus: Tarpeettomien varausten estämiseksi optimointina monikoiden addr-, adv_data-, char_data-, notify_data- ja uuid-tietueet ovat vain luettavissa olevia memoryview-ilmentymiä, jotka osoittavat bluetooth-moduulin sisäiseen rengaspuskuriin, ja ne ovat voimassa vain IRQ-käsittelijäfunktion suorituksen aikana. Jos ohjelmasi tarvitsee tallentaa jonkin näistä arvoista käytettäväksi IRQ-käsittelijän palaamisen jälkeen (esim. tallentamalla sen luokan ilmentymään tai globaaliin muuttujaan), sen on otettava kopio datasta joko käyttämällä bytes() tai bluetooth.UUID(), näin:

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

Esimerkiksi skannaustuloksen IRQ-käsittelijä saattaa tarkastaa adv_data-tiedon päättääkseen, onko kyseessä oikea laite, ja vasta sitten kopioida osoitedatan käytettäväksi muualla ohjelmassa. Ja tulostaaksesi dataa IRQ-käsittelijän sisältä tarvitaan print(bytes(addr)).

Käsittelijä yleensä haarautuu tapahtumakoodin perusteella ja purkaa tapahtumakohtaisen hyötykuormamonikon:

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

Jokainen tapahtumakoodi, sen toimittama hyötykuorma ja lyhyt kuvaus on lueteltu alla. Tapahtumissa, joiden status-kenttä mainitaan, status on 0 onnistuessa ja toteutuskohtainen nollasta poikkeava arvo epäonnistuessa.

Vakio	Arvo	Tapahtuma	Hyötykuormamonikko
`_IRQ_CENTRAL_CONNECT`	1	Central on yhdistänyt tähän peripheraaliin.	`(conn_handle, addr_type, addr)`
`_IRQ_CENTRAL_DISCONNECT`	2	Central on katkaissut yhteyden tähän peripheraaliin.	`(conn_handle, addr_type, addr)`
`_IRQ_GATTS_WRITE`	3	Yhdistetty asiakas on kirjoittanut paikalliseen ominaisuuteen tai kuvaajaan. Käytä metodia `gatts_read` noutaaksesi uuden arvon.	`(conn_handle, attr_handle)`
`_IRQ_GATTS_READ_REQUEST`	4	Yhdistetty asiakas on antanut lukupyynnön. Palauta nollasta poikkeava virhekoodi alla olevasta taulukosta evätäksesi luvun, tai `0` / `None` hyväksyäksesi sen.	`(conn_handle, attr_handle)`
`_IRQ_SCAN_RESULT`	5	Aktiivisen skannauksen aikana vastaanotettiin yksittäinen mainospaketti.	`(addr_type, addr, adv_type, rssi, adv_data)`
`_IRQ_SCAN_DONE`	6	Nykyinen skannaus on päättynyt joko siksi, että konfiguroitu kesto kului umpeen, tai koska kutsuttiin `gap_scan(None)`.	`()`
`_IRQ_PERIPHERAL_CONNECT`	7	Aiemmin annettu `gap_connect` on onnistunut.	`(conn_handle, addr_type, addr)`
`_IRQ_PERIPHERAL_DISCONNECT`	8	Yhdistetty peripheraali on katkaissut yhteyden.	`(conn_handle, addr_type, addr)`
`_IRQ_GATTC_SERVICE_RESULT`	9	Metodi `gattc_discover_services` löysi yhden palvelun.	`(conn_handle, start_handle, end_handle, uuid)`
`_IRQ_GATTC_SERVICE_DONE`	10	Palveluiden haku on päättynyt.	`(conn_handle, status)`
`_IRQ_GATTC_CHARACTERISTIC_RESULT`	11	Metodi `gattc_discover_characteristics` löysi yhden ominaisuuden.	`(conn_handle, end_handle, value_handle, properties, uuid)`
`_IRQ_GATTC_CHARACTERISTIC_DONE`	12	Ominaisuuksien haku on päättynyt.	`(conn_handle, status)`
`_IRQ_GATTC_DESCRIPTOR_RESULT`	13	Metodi `gattc_discover_descriptors` löysi yhden kuvaajan.	`(conn_handle, dsc_handle, uuid)`
`_IRQ_GATTC_DESCRIPTOR_DONE`	14	Kuvaajien haku on päättynyt.	`(conn_handle, status)`
`_IRQ_GATTC_READ_RESULT`	15	Aiemmin annettu `gattc_read` on palauttanut dataa.	`(conn_handle, value_handle, char_data)`
`_IRQ_GATTC_READ_DONE`	16	Aiemmin annettu `gattc_read` on päättynyt.	`(conn_handle, value_handle, status)`
`_IRQ_GATTC_WRITE_DONE`	17	Aiemmin annettu `gattc_write` on kuitattu.	`(conn_handle, value_handle, status)`
`_IRQ_GATTC_NOTIFY`	18	Etäpalvelin on lähettänyt (kuittaamattoman) ilmoituksen.	`(conn_handle, value_handle, notify_data)`
`_IRQ_GATTC_INDICATE`	19	Etäpalvelin on lähettänyt (kuitatun) ilmaisun.	`(conn_handle, value_handle, notify_data)`
`_IRQ_GATTS_INDICATE_DONE`	20	Aiemmin lähetetty ilmaisu on kuitattu asiakkaan toimesta (tai aikakatkaistu).	`(conn_handle, value_handle, status)`
`_IRQ_MTU_EXCHANGED`	21	ATT MTU -vaihto on valmistunut (kumman tahansa osapuolen käynnistämänä).	`(conn_handle, mtu)`
`_IRQ_L2CAP_ACCEPT`	22	Etälaite on pyytänyt L2CAP-yhteyttä PSM:llä, jota tämä laite kuuntelee. Palauta nollasta poikkeava kokonaisluku hylätäksesi, tai `0` / `None` hyväksyäksesi.	`(conn_handle, cid, psm, our_mtu, peer_mtu)`
`_IRQ_L2CAP_CONNECT`	23	L2CAP-kanava on nyt muodostettu joko hyväksymällä saapuva pyyntö tai saattamalla loppuun lähtevä `l2cap_connect`.	`(conn_handle, cid, psm, our_mtu, peer_mtu)`
`_IRQ_L2CAP_DISCONNECT`	24	L2CAP-kanavan yhteys on katkaistu. `status` on `0` puhtaalle katkaisulle, tai nollasta poikkeava, jos lähtevä yhteysyritys epäonnistui.	`(conn_handle, cid, psm, status)`
`_IRQ_L2CAP_RECV`	25	L2CAP-kanavalle on saapunut dataa. Kutsu metodia `l2cap_recvinto` lukeaksesi sen.	`(conn_handle, cid)`
`_IRQ_L2CAP_SEND_READY`	26	Aiempi `l2cap_send`, joka palautti `False`, on tyhjentynyt ja kanava on jälleen valmis. Nollasta poikkeava `status` tarkoittaa, että lähetyspuskuri ylivuoti ja sovelluksen on lähetettävä data uudelleen.	`(conn_handle, cid, status)`
`_IRQ_CONNECTION_UPDATE`	27	Etälaite on päivittänyt yhteysparametrit (väli, viive, valvonnan aikakatkaisu).	`(conn_handle, conn_interval, conn_latency, supervision_timeout, status)`
`_IRQ_ENCRYPTION_UPDATE`	28	Yhteyden salaustila on muuttunut, tyypillisesti pariutuksen tai sidonnan valmistumisen jälkeen.	`(conn_handle, encrypted, authenticated, bonded, key_size)`
`_IRQ_GET_SECRET`	29	Pino pyytää tallennettua sidontasalaisuutta. Jos `key` on `None`, palauta tyypin `sec_type` `index`:nnen tallennettu arvo; muutoin palauta annettuun `(sec_type, key)` -pariin liittyvä arvo. Palauta `None`, jos mitään ei ole tallennettu.	`(sec_type, index, key)`
`_IRQ_SET_SECRET`	30	Pino pyytää sovellusta tallentamaan sidontasalaisuuden pysyvästi. Palauta `True`, kun se on tallennettu.	`(sec_type, key, value)`
`_IRQ_PASSKEY_ACTION`	31	Salasanatoiminto vaaditaan osana pariutusta. Vastaa käyttämällä metodia `gap_passkey`; katso mahdolliset toiminnot alla olevasta salasanatoimintotaulukosta.	`(conn_handle, action, passkey)`

_IRQ_GATTS_READ_REQUEST-tapahtumalle käytettävissä olevat paluukoodit ovat:

Vakio	Arvo	Merkitys
`_GATTS_NO_ERROR`	`0x00`	Hyväksy luku.
`_GATTS_ERROR_READ_NOT_PERMITTED`	`0x02`	Lukua ei sallittu.
`_GATTS_ERROR_WRITE_NOT_PERMITTED`	`0x03`	Kirjoitusta ei sallittu.
`_GATTS_ERROR_INSUFFICIENT_AUTHENTICATION`	`0x05`	Asiakasta ei ole todennettu.
`_GATTS_ERROR_INSUFFICIENT_AUTHORIZATION`	`0x08`	Asiakkaalla ei ole valtuutusta.
`_GATTS_ERROR_INSUFFICIENT_ENCRYPTION`	`0x0f`	Yhteyttä ei ole salattu.

_IRQ_PASSKEY_ACTION-tapahtumalle käytettävissä olevat toiminnot ovat:

Vakio	Arvo	Merkitys
`_PASSKEY_ACTION_NONE`	0	Toimintoa ei vaadita.
`_PASSKEY_ACTION_INPUT`	2	Kehota käyttäjää syöttämään etälaitteessa näytetty salasana.
`_PASSKEY_ACTION_DISPLAY`	3	Näytä 6-numeroinen salasana, jonka etälaite syöttää.
`_PASSKEY_ACTION_NUMERIC_COMPARISON`	4	Vahvista, että salasana vastaa etälaitteessa näytettyä.

Tilan säästämiseksi laiteohjelmistossa näitä vakioita ei ole sisällytetty bluetooth-moduuliin. Lisää ohjelmaasi yllä olevista luetteloista ne, joita tarvitset.

Broadcaster-rooli (mainostaja)

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

Aloittaa mainostamisen määritetyllä välillä (mikrosekunteina). Tämä väli pyöristetään alaspäin lähimpään 625 us:iin. Lopettaaksesi mainostamisen aseta interval_us arvoon None.

adv_data ja resp_data voivat olla mitä tahansa puskuriprotokollan toteuttavaa tyyppiä (esim. bytes, bytearray, str). adv_data sisältyy kaikkiin lähetyksiin, ja resp_data lähetetään vastauksena aktiiviseen skannaukseen.

Huomautus: jos adv_data (tai resp_data) on None, niin edelliseen gap_advertise-kutsuun annettua dataa käytetään uudelleen. Tämä mahdollistaa mainostajan jatkavan mainostamista pelkällä gap_advertise(interval_us)-kutsulla. Tyhjentääksesi mainoshyötykuorman anna tyhjä bytes, eli b''.

Observer-rooli (skanneri)

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

Suorittaa skannausoperaation, joka kestää määritetyn ajan (millisekunteina).

Skannataksesi loputtomasti aseta duration_ms arvoon 0.

Lopettaaksesi skannauksen aseta duration_ms arvoon None.

Käytä interval_us- ja window_us-arvoja konfiguroidaksesi valinnaisesti pulssisuhteen. Skanneri toimii window_us mikrosekuntia jokaista interval_us mikrosekuntia kohti yhteensä duration_ms millisekunnin ajan. Oletusväli ja -ikkuna ovat vastaavasti 1,28 sekuntia ja 11,25 millisekuntia (taustaskannaus).

Jokaiselle skannaustulokselle nostetaan _IRQ_SCAN_RESULT-tapahtuma, jonka tapahtumadata on (addr_type, addr, adv_type, rssi, adv_data).

addr_type-arvot ilmaisevat julkiset tai satunnaiset osoitteet:

Arvo	Nimi	Merkitys
`0x00`	PUBLIC	Julkinen laiteosoite.
`0x01`	RANDOM	Satunnainen osoite (joko staattinen, RPA tai NRPA; tyyppi on koodattu itse osoitteeseen).

adv_type-arvot vastaavat Bluetooth-spesifikaatiota:

Arvo	Nimi	Merkitys
`0x00`	ADV_IND	Yhdistettävä ja skannattava suuntaamaton mainostus.
`0x01`	ADV_DIRECT_IND	Yhdistettävä suunnattu mainostus.
`0x02`	ADV_SCAN_IND	Skannattava suuntaamaton mainostus.
`0x03`	ADV_NONCONN_IND	Ei-yhdistettävä suuntaamaton mainostus.
`0x04`	SCAN_RSP	Skannausvastaus.

active voidaan asettaa arvoon True, jos haluat vastaanottaa skannausvastauksia tuloksissa.

Kun skannaus pysäytetään (joko keston päättymisen vuoksi tai kun se pysäytetään nimenomaisesti), nostetaan _IRQ_SCAN_DONE-tapahtuma.

Central-rooli

Central-laite voi yhdistää peripheraaleihin, jotka se on löytänyt observer-roolin avulla (katso gap_scan) tai tunnetulla osoitteella.

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¶

Yhdistä peripheraaliin.

Katso gap_scan saadaksesi lisätietoja osoitetyypeistä.

Peruuttaaksesi käynnissä olevan yhteysyrityksen ajoissa kutsu gap_connect(None).

Onnistuessa nostetaan _IRQ_PERIPHERAL_CONNECT-tapahtuma. Jos yhteysyritys peruutetaan, nostetaan _IRQ_PERIPHERAL_DISCONNECT-tapahtuma.

Laite odottaa enintään scan_duration_ms ajan vastaanottaakseen mainoshyötykuorman laitteelta.

Yhteysväli voidaan konfiguroida mikrosekunteina käyttämällä joko yhtä tai molempia arvoista min_conn_interval_us ja max_conn_interval_us. Muutoin valitaan oletusväli, tyypillisesti 30000:n ja 50000:n mikrosekunnin väliltä. Lyhyempi väli kasvattaa läpäisykykyä virrankulutuksen kustannuksella.

Peripheral-rooli

Peripheraalilaitteen odotetaan lähettävän yhdistettäviä mainoksia (katso gap_advertise). Se toimii yleensä GATT-palvelimena rekisteröityään ensin palvelut ja ominaisuudet metodilla gatts_register_services.

Kun central yhdistää, nostetaan _IRQ_CENTRAL_CONNECT-tapahtuma.

Central- ja Peripheral-roolit

gap_disconnect(conn_handle: int, /) → bool¶

Katkaise määritetty yhteyskahva. Tämä voi olla joko central, joka on yhdistänyt tähän laitteeseen (jos toimii peripheraalina), tai peripheraali, johon tämä laite oli aiemmin yhdistänyt (jos toimii centralina).

Onnistuessa nostetaan _IRQ_PERIPHERAL_DISCONNECT- tai _IRQ_CENTRAL_DISCONNECT-tapahtuma.

Palauttaa False, jos yhteyskahva ei ollut yhdistettynä, ja muutoin True.

GATT-palvelin

GATT-palvelimella on joukko rekisteröityjä palveluja. Kukin palvelu voi sisältää ominaisuuksia, joilla kullakin on arvo. Ominaisuudet voivat myös sisältää kuvaajia, joilla itsellään on arvoja.

Nämä arvot tallennetaan paikallisesti, ja niitä käytetään niiden ”arvokahvalla”, joka generoidaan palvelun rekisteröinnin aikana. Etäasiakaslaite voi myös lukea niitä tai kirjoittaa niihin. Lisäksi palvelin voi ”ilmoittaa” ominaisuuden yhdistetylle asiakkaalle yhteyskahvan kautta.

Joko central- tai peripheral-roolissa oleva laite voi toimia GATT-palvelimena, mutta useimmissa tapauksissa on yleisempää, että peripheraalilaite toimii palvelimena.

Ominaisuuksilla ja kuvaajilla on oletusarvoinen enimmäiskoko 20 tavua (oletusarvoinen 23 tavun ATT MTU vähennettynä 3 tavun ATT-otsakkeella; suurempi neuvoteltu MTU ei itsessään nosta tätä rajaa). Mikä tahansa asiakkaan niihin kirjoittama katkaistaan tähän pituuteen. Mikä tahansa paikallinen kirjoitus kuitenkin kasvattaa enimmäiskokoa, joten jos haluat sallia suurempia kirjoituksia asiakkaalta tiettyyn ominaisuuteen, käytä metodia gatts_write rekisteröinnin jälkeen. Esim. gatts_write(char_handle, bytes(100)).

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

Konfiguroi palvelimen määritetyillä palveluilla korvaten kaikki olemassa olevat palvelut.

services_definition on lista palveluista, jossa kukin palvelu on kaksialkioinen monikko, joka sisältää UUID:n ja listan ominaisuuksista.

Kukin ominaisuus on kaksi- tai kolmialkioinen monikko, joka sisältää UUID:n, flags-arvon ja valinnaisesti listan kuvaajista.

Kukin kuvaaja on kaksialkioinen monikko, joka sisältää UUID:n ja flags-arvon.

flags on alla määriteltyjen lippujen bitti-OR-yhdistelmä. Nämä asettavat sekä ominaisuuden (tai kuvaajan) toiminnan että turvallisuus- ja yksityisyysvaatimukset.

Paluuarvo on lista (yksi alkio palvelua kohti) monikoista (kukin alkio on arvokahva). Ominaisuus- ja kuvaajakahvat litistetään samaan monikkoon siinä järjestyksessä, jossa ne on määritelty.

Seuraava esimerkki rekisteröi kaksi palvelua (Heart Rate ja 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),
)

Kolmea arvokahvaa (hr, tx, rx) voidaan käyttää metodien gatts_read, gatts_write, gatts_notify ja gatts_indicate kanssa.

Huomautus: Mainostaminen on lopetettava ennen palvelujen rekisteröintiä.

Ominaisuuksille ja kuvaajille käytettävissä olevat liput ovat:

Vakio	Arvo	Merkitys
`_FLAG_BROADCAST`	`0x0001`	Ominaisuus voidaan lähettää (broadcast).
`_FLAG_READ`	`0x0002`	Asiakas voi lukea arvon.
`_FLAG_WRITE_NO_RESPONSE`	`0x0004`	Asiakas voi kirjoittaa odottamatta vastausta.
`_FLAG_WRITE`	`0x0008`	Asiakas voi kirjoittaa kuitatulla vastauksella.
`_FLAG_NOTIFY`	`0x0010`	Palvelin voi lähettää ilmoituksia (kuittaamattomia).
`_FLAG_INDICATE`	`0x0020`	Palvelin voi lähettää ilmaisuja (kuitattuja).
`_FLAG_AUTHENTICATED_SIGNED_WRITE`	`0x0040`	Asiakas voi tehdä allekirjoitettuja kirjoituksia.
`_FLAG_AUX_WRITE`	`0x0100`	Laajennetut ominaisuudet: jonotetut/luotettavat kirjoitukset ovat sallittuja.
`_FLAG_READ_ENCRYPTED`	`0x0200`	Luku vaatii salatun yhteyden.
`_FLAG_READ_AUTHENTICATED`	`0x0400`	Luku vaatii todennetun (MITM-suojatun) yhteyden.
`_FLAG_READ_AUTHORIZED`	`0x0800`	Luku vaatii sovellustason valtuutuksen.
`_FLAG_WRITE_ENCRYPTED`	`0x1000`	Kirjoitus vaatii salatun yhteyden.
`_FLAG_WRITE_AUTHENTICATED`	`0x2000`	Kirjoitus vaatii todennetun (MITM-suojatun) yhteyden.
`_FLAG_WRITE_AUTHORIZED`	`0x4000`	Kirjoitus vaatii sovellustason valtuutuksen.

Kuten yllä olevien tapahtumavakioiden kohdalla, näitä lippuja ei tarjoa bluetooth-moduuli; kopioi tarvitsemasi ohjelmaasi.

gatts_read(value_handle: int, /) → bytes¶: Lukee tämän kahvan paikallisen arvon (jonka on joko kirjoittanut gatts_write tai etäasiakas).

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

Kirjoittaa tämän kahvan paikallisen arvon, jonka asiakas voi lukea.

Jos send_update on True, niin kaikille tilanneille asiakkaille ilmoitetaan (tai ilmaistaan, riippuen siitä, mihin he ovat tilanneet ja mitä operaatioita ominaisuus tukee) tästä kirjoituksesta.

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

Lähettää ilmoituspyynnön yhdistetylle asiakkaalle.

Jos data on None (oletus), niin lähetetään nykyinen paikallinen arvo (kuten asetettu metodilla gatts_write).

Muutoin, jos data ei ole None, niin kyseinen arvo lähetetään asiakkaalle osana ilmoitusta. Paikallista arvoa ei muuteta.

Huomautus: Ilmoitus lähetetään riippumatta asiakkaan tilaustilasta tähän ominaisuuteen.

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

Lähettää ilmaisupyynnön yhdistetylle asiakkaalle.

Jos data on None (oletus), niin lähetetään nykyinen paikallinen arvo (kuten asetettu metodilla gatts_write).

Muutoin, jos data ei ole None, niin kyseinen arvo lähetetään asiakkaalle osana ilmaisua. Paikallista arvoa ei muuteta.

Kuittauksen (tai epäonnistumisen, esim. aikakatkaisun) yhteydessä nostetaan _IRQ_GATTS_INDICATE_DONE-tapahtuma.

Huomautus: Ilmaisu lähetetään riippumatta asiakkaan tilaustilasta tähän ominaisuuteen.

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

Asettaa arvon sisäisen puskurin koon tavuina. Tämä rajoittaa suurinta mahdollista vastaanotettavaa kirjoitusta. Oletus on 20 tavua (oletusarvoinen 23 tavun ATT MTU vähennettynä 3 tavun ATT-otsakkeella).

append-arvon asettaminen arvoon True saa kaikki etäkirjoitukset lisäämään nykyiseen arvoon sen korvaamisen sijaan. Tällä tavoin voidaan puskuroida enintään len tavua. Kun käytät metodia gatts_read, arvo tyhjennetään lukemisen jälkeen. Tämä ominaisuus on hyödyllinen toteutettaessa esimerkiksi Nordic UART Service -palvelua.

GATT-asiakas

GATT-asiakas voi löytää ja lukea/kirjoittaa ominaisuuksia etä-GATT-palvelimella.

On yleisempää, että central-roolissa oleva laite toimii GATT-asiakkaana, mutta on myös mahdollista, että peripheraali toimii asiakkaana selvittääkseen tietoja siihen yhdistäneestä centralista (esim. lukeakseen laitenimen laitetietopalvelusta).

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

Kysele yhdistetyltä palvelimelta sen palveluja.

Määritä valinnaisesti palvelun uuid kysellaksesi vain kyseistä palvelua.

Jokaiselle löydetylle palvelulle nostetaan _IRQ_GATTC_SERVICE_RESULT-tapahtuma, jota seuraa _IRQ_GATTC_SERVICE_DONE valmistuessa.

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

Kysele yhdistetyltä palvelimelta ominaisuuksia määritetyltä väliltä.

Määritä valinnaisesti ominaisuuden uuid kysellaksesi vain kyseistä ominaisuutta.

Argumenttien start_handle=1 ja end_handle=0xffff antaminen kattaa koko GATT-attribuuttikahvavälin, joten tämä yhdistelmä käytännössä etsii etälaitteen jokaisen palvelun.

Jokaiselle löydetylle ominaisuudelle nostetaan _IRQ_GATTC_CHARACTERISTIC_RESULT-tapahtuma, jota seuraa _IRQ_GATTC_CHARACTERISTIC_DONE valmistuessa.

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

Kysele yhdistetyltä palvelimelta kuvaajia määritetyltä väliltä.

Jokaiselle löydetylle kuvaajalle nostetaan _IRQ_GATTC_DESCRIPTOR_RESULT-tapahtuma, jota seuraa _IRQ_GATTC_DESCRIPTOR_DONE valmistuessa.

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

Anna etäluku yhdistetylle palvelimelle määritetylle ominaisuus- tai kuvaajakahvalle.

Kun arvo on saatavilla, nostetaan _IRQ_GATTC_READ_RESULT-tapahtuma, jota seuraa _IRQ_GATTC_READ_DONE valmistuessa.

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

Anna etäkirjoitus yhdistetylle palvelimelle määritetylle ominaisuus- tai kuvaajakahvalle.

Argumentti mode määrittää kirjoitustoiminnan, ja tällä hetkellä tuetut arvot ovat:

mode=0 (oletus) on kirjoitus ilman vastausta: kirjoitus lähetetään etäpalvelimelle, mutta vahvistusta ei palauteta eikä tapahtumaa nosteta.

mode=1 on kirjoitus vastauksella: etäpalvelinta pyydetään lähettämään vastaus/kuittaus siitä, että se vastaanotti datan.

Jos etäpalvelimelta vastaanotetaan vastaus, nostetaan _IRQ_GATTC_WRITE_DONE-tapahtuma.

gattc_exchange_mtu(conn_handle: int, /) → None¶

Käynnistä MTU-vaihto yhdistetyn palvelimen kanssa käyttäen BLE.config(mtu=value)-asetuksella määritettyä ensisijaista MTU:ta.

_IRQ_MTU_EXCHANGED-tapahtuma nostetaan, kun MTU-vaihto valmistuu.

MTU-vaihdon käynnistää tyypillisesti central; NimBLE tukee molempia rooleja.

L2CAP-yhteyspohjaiset kanavat

Tämä ominaisuus mahdollistaa socketin kaltaisen datanvaihdon kahden BLE-laitteen välillä. Kun laitteet on yhdistetty GAP:n kautta, kumpi tahansa laite voi kuunnella toisen yhdistämistä numeerisella PSM:llä (Protocol/Service Multiplexer).

Vain yksi L2CAP-kanava voi olla aktiivinen kerrallaan (eli et voi yhdistää kuunnellessasi).

Aktiiviset L2CAP-kanavat tunnistetaan yhteyskahvasta, jolla ne muodostettiin, ja CID:stä (kanavan tunniste).

Yhteyspohjaisissa kanavissa on sisäänrakennettu luottoperusteinen vuonohjaus. Toisin kuin ATT:ssä, jossa laitteet neuvottelevat jaetun MTU:n, sekä kuunteleva että yhdistävä laite asettavat kumpikin itsenäisen MTU:n, joka rajoittaa enimmäismäärää käsittelemätöntä dataa, jonka etälaite voi lähettää ennen kuin se on täysin kulutettu metodissa l2cap_recvinto.

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

Aloita saapuvien L2CAP-kanavapyyntöjen kuuntelu määritetyllä psm:llä paikallisen MTU:n ollessa asetettuna arvoon mtu.

Kun etälaite käynnistää yhteyden, nostetaan _IRQ_L2CAP_ACCEPT-tapahtuma, joka antaa kuuntelevalle palvelimelle mahdollisuuden hylätä saapuva yhteys (palauttamalla nollasta poikkeavan kokonaisluvun).

Kun yhteys on hyväksytty, nostetaan _IRQ_L2CAP_CONNECT-tapahtuma, jonka avulla palvelin voi saada kanavan tunnisteen (CID) sekä paikallisen ja etäisen MTU:n.

Huomautus: Tällä hetkellä kuuntelua ei ole mahdollista lopettaa.

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

Yhdistä kuuntelevaan vertaiseen määritetyllä psm:llä paikallisen MTU:n ollessa asetettuna arvoon mtu.

Onnistuneen yhteyden yhteydessä nostetaan _IRQ_L2CAP_CONNECT-tapahtuma, jonka avulla asiakas voi saada CID:n sekä paikallisen ja etäisen (vertaisen) MTU:n.

Epäonnistunut yhteys nostaa _IRQ_L2CAP_DISCONNECT-tapahtuman, jolla on nollasta poikkeava status.

l2cap_disconnect(conn_handle: int, cid: int, /) → None¶: Katkaise aktiivinen L2CAP-kanava, jolla on määritetty conn_handle ja cid.

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

Lähetä määritetty buf (jonka on tuettava puskuriprotokollaa) L2CAP-kanavalla, joka tunnistetaan conn_handle- ja cid-arvoista.

Puskurin on täytettävä molemmat rajat: se ei saa ylittää etäistä (vertaisen) MTU:ta eikä paikallisen MTU:n kaksinkertaista määrää.

Tämä palauttaa False, jos kanava on nyt ”jumissa”, mikä tarkoittaa, että metodia l2cap_send ei saa kutsua uudelleen ennen kuin _IRQ_L2CAP_SEND_READY-tapahtuma on vastaanotettu (mikä tapahtuu, kun etälaite myöntää lisää luottoja, tyypillisesti sen jälkeen kun se on vastaanottanut ja käsitellyt datan).

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

Vastaanota dataa määritetystä conn_handle- ja cid-arvosta annettuun buf-puskuriin (jonka on tuettava puskuriprotokollaa, esim. bytearray tai memoryview).

Palauttaa kanavalta luettujen tavujen määrän.

Jos buf on None, palauttaa saatavilla olevien tavujen määrän.

Huomautus: _IRQ_L2CAP_RECV-tapahtuman vastaanottamisen jälkeen sovelluksen tulisi jatkaa metodin l2cap_recvinto kutsumista, kunnes vastaanottopuskurissa ei ole enempää tavuja saatavilla (tyypillisesti etäisen (vertaisen) MTU:n kokoon asti).

Kunnes vastaanottopuskuri on tyhjä, etälaitteelle ei myönnetä lisää kanavaluottoja eikä se voi lähettää enempää dataa.

Pariutus ja sidonta

Pariutus mahdollistaa yhteyden salaamisen ja todentamisen salaisuuksien vaihdon kautta (valinnaisella MITM-suojauksella salasanatodennuksen avulla).

Sidonta on prosessi, jossa nuo salaisuudet tallennetaan haihtumattomaan muistiin. Sidottuna laite kykenee ratkaisemaan ratkaistavissa olevan yksityisen osoitteen (RPA) toiselta laitteelta tallennetun identiteetin ratkaisuavaimen (IRK) perusteella. Tukeakseen sidontaa sovelluksen on toteutettava _IRQ_GET_SECRET- ja _IRQ_SET_SECRET-tapahtumat.

gap_pair(conn_handle: int, /) → None¶

Käynnistä pariutus etälaitteen kanssa.

Ennen tämän kutsumista varmista, että konfigurointivaihtoehdot io, mitm, le_secure ja bond on asetettu (metodin config kautta).

Onnistuneen pariutuksen yhteydessä nostetaan _IRQ_ENCRYPTION_UPDATE-tapahtuma.

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

Vastaa _IRQ_PASSKEY_ACTION-tapahtumaan määritetylle conn_handle- ja action-arvolle. passkey-arvon merkitys riippuu action-arvosta (joka puolestaan riippuu konfiguroidusta I/O-ominaisuudesta):

Toiminto	Vaadittu passkey-vastaus
`_PASSKEY_ACTION_INPUT`	Salasana, jonka käyttäjä lukee etälaitteesta.
`_PASSKEY_ACTION_DISPLAY`	Paikallisesti generoitu satunnainen 6-numeroinen salasana, joka näytetään käyttäjälle.
`_PASSKEY_ACTION_NUMERIC_COMPARISON`	`1` hyväksyäksesi `_IRQ_PASSKEY_ACTION`-tapahtumassa näytetyn salasanan, tai `0` peruuttaaksesi pariutuksen.

class UUID¶

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

Luo UUID-ilmentymän määritetyllä value-arvolla. Bluetooth käyttää kolmea UUID-leveyttä; UUID hyväksyy minkä tahansa niistä:

UUID-leveys	Hyväksytyt `value`-tyypit	Esimerkki
16-bittinen	`int` tai 2-tavuinen puskuri (little-endian)	`UUID(0x2908)` tai `UUID(b'\x08\x29')`
32-bittinen	4-tavuinen puskuri (little-endian)	`UUID(b'\x08\x29\x00\x00')`
128-bittinen	16-tavuinen puskuri tai yhdysviivoin eroteltu merkkijono	`UUID('6E400001-B5A3-F393-E0A9-E50E24DCCA9E')`

16- ja 32-bittiset UUID:t ovat tyypillisesti SIG:n myöntämiä tunnisteita (katso Bluetoothin myönnetyt numerot); 128-bittiset UUID:t ovat normaalisti valmistajan määrittelemiä.

bluetooth — matalan tason Bluetooth¶

class BLE¶

class UUID¶

`bluetooth` — matalan tason Bluetooth¶