`ubluepy` — Bluetooth LE -oheislaite ja -keskuslaite¶

ubluepy-moduuli on vanha Bluetooth LE -rajapinta, joka toimitetaan MicroPythonin nRF-sovituksen mukana. Se on löyhästi mallinnettu Linuxin bluepy-Python-kirjaston pohjalta ja sijaitsee suoraan Nordic SoftDevicen päällä — siirrettävää taustaosaa ei ole, joten moduuli on saatavilla vain Nordic-kohteilla (OpenMV:n valikoimassa Arduino Nano 33 BLE Sense). Uudemmat bluetooth- / aioble-rajapinnat eivät ole käytössä tässä koonnoksessa, joten ubluepy on ainoa tapa ohjata sirulla olevaa radiota.

Käytettävissä oleva ominaisuusjoukko riippuu laiteohjelmiston flash-muistiin ohjelmoimasta SoftDevicestä:

s140 (Nano 33 BLE Sense) — sekä oheislaite- että keskuslaiteroolit (skannaaja). Tämän OpenMV-laiteohjelmisto toimittaa.
s132 — sekä oheislaite että keskuslaite.
s110 — vain oheislaite; skannaus- ja yhteysmetodit on käännetty pois.

Oheislaite-esimerkki¶

Mainosta laitetta Bluetooth LE -oheislaitteena yhdellä ympäristönmittauspalvelulla ja ilmoita lämpötilaominaisuus jokaisella kirjoituksella sen Client Characteristic Configuration Descriptoriin (CCCD):

from ubluepy import Service, Characteristic, UUID, Peripheral, constants
from machine import LED

notif_enabled = False

def event_handler(event_id, handle, data):
    global notif_enabled
    if event_id == constants.EVT_GAP_CONNECTED:
        LED("LED_GREEN").on()
    elif event_id == constants.EVT_GAP_DISCONNECTED:
        LED("LED_GREEN").off()
        periph.advertise(device_name="Nano 33", services=[svc])
    elif event_id == constants.EVT_GATTS_WRITE:
        notif_enabled = bool(data[0])

svc = Service(UUID("181A"))            # Environmental Sensing
char = Characteristic(UUID("2A6E"),
                      props=Characteristic.PROP_NOTIFY | Characteristic.PROP_READ,
                      attrs=Characteristic.ATTR_CCCD)
svc.addCharacteristic(char)

periph = Peripheral()
periph.addService(svc)
periph.setConnectionHandler(event_handler)
periph.advertise(device_name="Nano 33", services=[svc])

Keskuslaite-esimerkki¶

Skannaa lähellä olevia mainostavia laitteita 100 ms:n ajan ja pura kunkin ScanEntry-kohteen mainostiedot:

from ubluepy import Scanner, constants

s = Scanner()
for entry in s.scan(100):
    print(entry.addr(), entry.rssi(), "dBm")
    for ad_type, name, value in entry.getScanData():
        print(" ", ad_type, name, bytes(value))

Moduulin sisältö¶

Luokat¶

class ubluepy.UUID(value)¶

Rakenna 16- tai 128-bittinen Bluetooth-UUID.

value

Yksi seuraavista:

int — 16-bittinen numeerinen UUID (UUID(0x180A)).
6-merkkinen "0xXXXX"-merkkijono — 16-bittinen UUID, esim. UUID("0x181A").
36-merkkinen "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"-merkkijono — täysi 128-bittinen UUID. Toimittajakohtainen osa rekisteröidään SoftDeviceen rakennuksen yhteydessä.
Toinen UUID-instanssi — tekee kopion.

Mikä tahansa muu pituus aiheuttaa ValueError("Invalid UUID string length").

binVal() → int¶: Palauttaa UUID:n alimmat 16 bittiä int-arvona. 128-bittisillä UUID:illa palautetaan vain toimittajakohtaiseen UUID:hen upotettu 16-bittinen kenttä (täysi 128-bittinen arvo on saatavilla vain SoftDevicen toimittajakohtaisen indeksin kautta).

class ubluepy.Service(uuid: UUID, type: int = Service.PRIMARY)¶

Määritä GATT-palvelu, joka rekisteröidään SoftDeviceen, kun se lisätään Peripheral-laitteeseen.

uuid: UUID-instanssi. Muun kuin UUID-objektin välittäminen aiheuttaa ValueError-virheen.
type: Joko Service.PRIMARY (oletus) tai Service.SECONDARY. Muut arvot aiheuttavat ValueError-virheen.

uuid() → UUID¶: Palauttaa palvelun UUID-instanssin.

addCharacteristic(characteristic: Characteristic) → None¶: Rekisteröi Characteristic palveluun. Ominaisuuden GATT-kahva määritetään tämän kutsun aikana.

getCharacteristic(uuid: UUID) → Characteristic | None¶: Hae aiemmin lisätty Characteristic UUID:n perusteella. Palauttaa ominaisuusinstanssin, tai None, jos vastaavuutta ei löydy.

getCharacteristics() → list¶: Palauttaa luettelon kaikista palveluun lisätyistä ominaisuuksista.

PRIMARY: int¶: Palvelutyypin vakio ensisijaisille palveluille (1).

SECONDARY: int¶: Palvelutyypin vakio toissijaisille palveluille (2).

class ubluepy.Characteristic(uuid: UUID, *, props: int = PROP_READ | PROP_WRITE, attrs: int = 0)¶

Määritä GATT-ominaisuus. Lisää se Service-palveluun metodilla Service.addCharacteristic() ennen kuin emo-Peripheral alkaa mainostaa.

uuid: UUID-instanssi.
props (vain avainsanana): Bittimaski yhdestä tai useammasta Characteristic.PROP_*-arvosta, joka kuvaa, mitä toimintoja ominaisuus tukee.
attrs (vain avainsanana): Bittimaski lisä-GATT-attribuuteista. Käytä Characteristic.ATTR_CCCD-arvoa liittääksesi Client Characteristic Configuration Descriptorin — vaaditaan, jotta PROP_NOTIFY- / PROP_INDICATE-ominaisuudet toimivat.

uuid() → UUID¶: Palauttaa ominaisuuden UUID-instanssin.

properties() → int¶: Palauttaa rakennusvaiheessa asetetun props-bittimaskin.

read() → bytearray¶: Vain keskuslaiteroolissa. Lue ominaisuuden arvo yhdistetyltä vertaislaitteelta. Palauttaa bytearray-objektin, jossa on uusin arvo. Oheislaitteessa tämä ei tee mitään ja palauttaa None.

write(data, *, with_response: bool = False) → None¶

Kirjoita ominaisuuteen.

Oheislaitteessa, jos PROP_NOTIFY on asetettu ominaisuuden ominaisuuksiin, arvo lähetetään GATT-ilmoituksena yhdistetylle keskuslaitteelle; muutoin paikallisen attribuutin arvo päivitetään.
Keskuslaitteessa arvo kirjoitetaan etävertaislaitteelle. Aseta with_response=True lähettääksesi kirjoituspyynnön ja odottaaksesi vertaislaitteen kuittausta kirjoituskomennon sijaan.

data on mikä tahansa puskuriprotokollaa noudattava objekti (bytes, bytearray, memoryview).

PROP_BROADCAST: int¶: Ominaisuus voi lähettää arvonsa yleislähetyksenä (0x01).

PROP_READ: int¶: Ominaisuus tukee lukuja (0x02).

PROP_WRITE_WO_RESP: int¶: Ominaisuus tukee kirjoituksia ilman vastausta (0x04).

PROP_WRITE: int¶: Ominaisuus tukee kirjoituksia vastauksella (0x08).

PROP_NOTIFY: int¶: Ominaisuus voi lähettää ilmoituksia tilaavalle keskuslaitteelle (0x10).

PROP_INDICATE: int¶: Ominaisuus voi lähettää osoituksia (kuitattuja ilmoituksia) tilaavalle keskuslaitteelle (0x20).

PROP_AUTH_SIGNED_WR: int¶: Ominaisuus tukee todennettuja allekirjoitettuja kirjoituksia (0x40).

ATTR_CCCD: int¶: Lisää ominaisuuteen Client Characteristic Configuration Descriptor (0x01). Vaaditaan, jotta asiakkaat voivat tilata ilmoituksia/osoituksia.

class ubluepy.Descriptor(uuid: UUID)¶: Tynkäluokka GATT-kuvaajien esittämiseen. Nykyinen toteutus tallentaa vain UUID:n eikä tarjoa metodeja — se on tarjolla yhteensopivuuden vuoksi moduulin tulevien versioiden kanssa.

class ubluepy.Peripheral¶

Paikallinen Bluetooth LE -laite. Samaa luokkaa käytetään sekä oheislaite- että keskuslaiterooleihin; rooli valitaan sillä, mitä metodeja kutsut (advertise() valitsee oheislaitteen, connect() valitsee keskuslaitteen).

addService(service: Service) → None¶: Rekisteröi Service (ja kaikki sen aiemmin lisätyt ominaisuudet) paikalliseen GATT-palvelimeen.

getServices() → list¶: Palauttaa luettelon palveluista, jotka on tällä hetkellä rekisteröity tähän Peripheral-laitteeseen.

advertise(*, device_name: str | None = None, services: list | None = None, data: bytes | None = None, connectable: bool = True) → None¶

Aloita mainostaminen oheislaiteroolissa.

device_name: Täydellinen paikallinen nimi, joka mainostetaan GAP-hyötykuormassa.
services: Luettelo mainostettavista Service-instansseista. Kunkin palvelun UUID sisällytetään mainokseen.
data: Valinnainen raaka mainoshyötykuorma (bytes / bytearray), joka liitetään automaattisesti luodun otsikon perään. Käytä tätä toimittajakohtaisiin tai majakkahyötykuormiin, kuten Eddystoneen.
connectable: Kun True (oletus), mainostaa yhdistettävänä laitteena ja rekisteröi GAP- / GATTS-tapahtumankäsittelijät, jotta määritetty setConnectionHandler()-takaisinkutsu laukeaa yhdistettäessä, yhteyttä katkaistaessa ja CCCD-kirjoituksissa. Kun False, mainostaa majakkana — käsittelijöitä ei liitetä eikä laitteeseen voi muodostaa yhteyttä.

advertise_stop() → None¶: Pysäytä mahdollinen käynnissä oleva mainostus.

setConnectionHandler(func) → None¶: Rekisteröi takaisinkutsu, joka kutsutaan GAP- ja GATTS-tapahtumissa. Takaisinkutsua kutsutaan muodossa func(event_id, conn_handle, data), jossa event_id on yksi arvoista constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED tai constants.EVT_GATTS_WRITE, conn_handle on SoftDevicen yhteyskahva (tai attribuuttikahva GATTS-kirjoituksissa), ja data on raaka tapahtumahyötykuorma bytearray-objektina (tai None yhdistettäessä / yhteyttä katkaistaessa).

setNotificationHandler(func) → None¶: Rekisteröi takaisinkutsu keskuslaiteroolissa vastaanotetuille ilmoitustapahtumille.

withDelegate(delegate: DefaultDelegate) → None¶: Liitä DefaultDelegate-instanssi vastaanottamaan puretut GATT-tapahtumat.

disconnect() → None¶: Katkaise aktiivinen yhteys (tässä koonnoksessa tällä hetkellä toimimaton tynkä).

connect(addr, *, addr_type: int = constants.ADDR_TYPE_PUBLIC) → None¶

Vain keskuslaiteroolissa. Muodosta yhteys annetulla osoitteella varustettuun vertaislaitteeseen ja löydä synkronisesti sen ensisijaiset palvelut ja ominaisuudet. Estää suorituksen, kunnes yhteys on muodostettu ja löytäminen on valmis; löydetyt palvelut ovat sen jälkeen saatavilla getServices()-metodin kautta.

addr: Vertaislaitteen osoite 17-merkkisenä "xx:xx:xx:xx:xx:xx"-merkkijonona (esim. ScanEntry.addr()-metodista otettuna).
addr_type (vain avainsanana): Joko constants.ADDR_TYPE_PUBLIC (oletus) tai constants.ADDR_TYPE_RANDOM_STATIC.

class ubluepy.Scanner¶

GAP-tarkkailija lähellä olevien mainostavien laitteiden löytämiseen. Saatavilla vain, kun laiteohjelmisto on koottu keskuslaitetukea sisältävää SoftDeviceä vasten (s132 / s140).

scan(timeout: int) → list¶: Suorita passiivinen skannaus timeout millisekunnin ajan ja palauta luettelo ScanEntry-instansseista — yksi kustakin ikkunan aikana vastaanotetusta mainosraportista.

class ubluepy.ScanEntry¶

Yksittäinen mainosraportti, jonka Scanner.scan() on tallentanut. Instanssit palautetaan skannaajalta — julkista konstruktoria ei ole.

addr() → str¶: Palauttaa vertaislaitteen osoitteen 17-merkkisenä "xx:xx:xx:xx:xx:xx"-merkkijonona.

addr_type() → int¶: Palauttaa vertaislaitteen osoitetyypin (constants.ADDR_TYPE_PUBLIC tai constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int¶: Palauttaa signaalin voimakkuuden ilmaisimen yksikössä dBm.

getScanData() → list¶: Pura mainoshyötykuorma luetteloksi (ad_type, description, value)-monikoita. ad_type on numeerinen AD-tyyppitavu (katso constants.ad_types), description on vastaavan vakion nimi merkkijonona (tai None, jos tyyppi on tuntematon), ja value on AD-tietueen runko bytearray-objektina.

class ubluepy.DefaultDelegate¶

Kantaluokka objekteille, jotka välitetään Peripheral.withDelegate()-metodille. Periytä siitä ja korvaa handleConnection() / handleNotification() reagoidaksesi GATT-tapahtumiin.

handleConnection() → None¶: Kutsutaan GAP-yhdistämis- / -katkaisutapahtumissa. Oletustoteutus on tyhjä.

handleNotification() → None¶: Kutsutaan saapuvien GATT-ilmoitusten yhteydessä. Oletustoteutus on tyhjä.

Vakiot¶

Moduulin constants-attribuutti on nimiavaruus, joka sisältää GAP/GATT-tapahtumatunnisteet, osoitetyyppiarvot ja sisäkkäisen ad_types-nimiavaruuden.

ubluepy.constants: type¶: Säiliö, joka tarjoaa alla olevat vakiot.

constants.EVT_GAP_CONNECTED: int¶: Peripheral-yhteyskäsittelijän event_id-arvo GAP-yhdistämiselle (16).

constants.EVT_GAP_DISCONNECTED: int¶: Peripheral-yhteyskäsittelijän event_id-arvo GAP-katkaisulle (17).

constants.EVT_GATTS_WRITE: int¶: Peripheral-yhteyskäsittelijän event_id-arvo kirjoitukselle paikalliseen GATT-attribuuttiin, mukaan lukien kirjoitukset CCCD:hen, jotka ottavat ilmoitukset käyttöön / pois käytöstä (80).

constants.UUID_CCCD: int¶: Bluetooth-standardin UUID Client Characteristic Configuration Descriptorille (0x2902).

constants.ADDR_TYPE_PUBLIC: int¶: Julkinen Bluetooth-laiteosoite (0).

constants.ADDR_TYPE_RANDOM_STATIC: int¶: Staattinen satunnainen Bluetooth-laiteosoite (1).

constants.ad_types: type¶

Mainostietojen AD-tyyppivakioiden nimiavaruus Bluetooth Core Specification Supplement -määrityksestä. Kukin nimi vastaa kyseistä 1-tavuista AD-tyyppiä:

Nimi	Arvo
`AD_TYPE_FLAGS`	`0x01`
`AD_TYPE_16BIT_SERVICE_UUID_MORE_AVAILABLE`	`0x02`
`AD_TYPE_16BIT_SERVICE_UUID_COMPLETE`	`0x03`
`AD_TYPE_32BIT_SERVICE_UUID_MORE_AVAILABLE`	`0x04`
`AD_TYPE_32BIT_SERVICE_UUID_COMPLETE`	`0x05`
`AD_TYPE_128BIT_SERVICE_UUID_MORE_AVAILABLE`	`0x06`
`AD_TYPE_128BIT_SERVICE_UUID_COMPLETE`	`0x07`
`AD_TYPE_SHORT_LOCAL_NAME`	`0x08`
`AD_TYPE_COMPLETE_LOCAL_NAME`	`0x09`
`AD_TYPE_TX_POWER_LEVEL`	`0x0A`
`AD_TYPE_CLASS_OF_DEVICE`	`0x0D`
`AD_TYPE_SIMPLE_PAIRING_HASH_C`	`0x0E`
`AD_TYPE_SIMPLE_PAIRING_RANDOMIZER_R`	`0x0F`
`AD_TYPE_SECURITY_MANAGER_TK_VALUE`	`0x10`
`AD_TYPE_SECURITY_MANAGER_OOB_FLAGS`	`0x11`
`AD_TYPE_SLAVE_CONNECTION_INTERVAL_RANGE`	`0x12`
`AD_TYPE_SOLICITED_SERVICE_UUIDS_16BIT`	`0x14`
`AD_TYPE_SOLICITED_SERVICE_UUIDS_128BIT`	`0x15`
`AD_TYPE_SERVICE_DATA`	`0x16`
`AD_TYPE_PUBLIC_TARGET_ADDRESS`	`0x17`
`AD_TYPE_RANDOM_TARGET_ADDRESS`	`0x18`
`AD_TYPE_APPEARANCE`	`0x19`
`AD_TYPE_ADVERTISING_INTERVAL`	`0x1A`
`AD_TYPE_LE_BLUETOOTH_DEVICE_ADDRESS`	`0x1B`
`AD_TYPE_LE_ROLE`	`0x1C`
`AD_TYPE_SIMPLE_PAIRING_HASH_C256`	`0x1D`
`AD_TYPE_SIMPLE_PAIRING_RANDOMIZER_R256`	`0x1E`
`AD_TYPE_SERVICE_DATA_32BIT_UUID`	`0x20`
`AD_TYPE_SERVICE_DATA_128BIT_UUID`	`0x21`
`AD_TYPE_URI`	`0x24`
`AD_TYPE_3D_INFORMATION_DATA`	`0x3D`
`AD_TYPE_MANUFACTURER_SPECIFIC_DATA`	`0xFF`

ubluepy — Bluetooth LE -oheislaite ja -keskuslaite¶