`ubluepy` — Bluetooth LE peripheral en central#

De ubluepy-module is de oudere Bluetooth LE-API die met de MicroPython nRF-port wordt meegeleverd. Ze is losjes gemodelleerd naar de Linux bluepy Python-bibliotheek en bevindt zich rechtstreeks bovenop de Nordic SoftDevice — er is geen draagbare back-end, dus de module is alleen beschikbaar op Nordic-targets (de Arduino Nano 33 BLE Sense in het assortiment van OpenMV). De nieuwere bluetooth- / aioble-API’s zijn in deze build niet ingeschakeld, dus ubluepy is de enige manier om de geïntegreerde radio aan te sturen.

De beschikbare functieset hangt af van de SoftDevice die door de firmware is geflasht:

s140 (Nano 33 BLE Sense) — zowel de peripheral- als central-rol (scanner). Dit is wat de OpenMV-firmware meelevert.
s132 — zowel peripheral als central.
s110 — alleen peripheral; scanner- / connect-methoden worden weggecompileerd.

Peripheral-voorbeeld#

Adverteer als een Bluetooth LE-peripheral met een enkele environmental sensing-service en notificeer een temperatuurkarakteristiek bij elke schrijfactie naar de bijbehorende Client Characteristic Configuration Descriptor (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])

Central-voorbeeld#

Scan gedurende 100 ms naar nabije adverterende apparaten en decodeer de advertentiegegevens van elke ScanEntry

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

Module-inhoud#

Klassen#

class ubluepy.UUID(value)#

Construeer een 16- of 128-bits Bluetooth UUID.

value

Een van:

int — een 16-bits numerieke UUID (UUID(0x180A)).
Een 6-tekenstring "0xXXXX" — een 16-bits UUID, bijv. UUID("0x181A").
Een 36-tekenstring "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" — een volledige 128-bits UUID. Het leverancierspecifieke deel wordt bij constructie bij de SoftDevice geregistreerd.
Een andere UUID-instantie — maakt een kopie.

Elke andere lengte veroorzaakt ValueError("Invalid UUID string length").

binVal() → int#: Geeft de onderste 16 bits van de UUID terug als een int. Voor 128-bits UUID’s wordt alleen het 16-bits veld teruggegeven dat in de leverancierspecifieke UUID is ingebed (de volledige 128-bits waarde is alleen toegankelijk via de leverancierspecifieke index van de SoftDevice).

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

Definieer een GATT-service die bij de SoftDevice wordt geregistreerd wanneer deze aan een Peripheral wordt toegevoegd.

uuid: Een UUID-instantie. Het doorgeven van een niet-UUID-object veroorzaakt ValueError.
type: Ofwel Service.PRIMARY (standaard) ofwel Service.SECONDARY. Andere waarden veroorzaken ValueError.

uuid() → UUID#: Geeft de UUID-instantie van de service terug.

addCharacteristic(characteristic: Characteristic) → None#: Registreer een Characteristic bij de service. Tijdens deze aanroep wordt de GATT-handle van de karakteristiek toegewezen.

getCharacteristic(uuid: UUID) → Characteristic | None#: Zoek een eerder toegevoegde Characteristic op via UUID. Geeft de karakteristiekinstantie terug, of None als er geen overeenkomst wordt gevonden.

getCharacteristics() → list#: Geeft de lijst van elke aan de service toegevoegde karakteristiek terug.

PRIMARY: int#: Servicetype-constante voor primaire services (1).

SECONDARY: int#: Servicetype-constante voor secundaire services (2).

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

Definieer een GATT-karakteristiek. Voeg deze met Service.addCharacteristic() toe aan een Service voordat de bovenliggende Peripheral begint te adverteren.

uuid: Een UUID-instantie.
props (alleen sleutelwoord): Bitmasker van een of meer Characteristic.PROP_*-waarden die beschrijven welke bewerkingen de karakteristiek ondersteunt.
attrs (alleen sleutelwoord): Bitmasker van aanvullende GATT-attributen. Gebruik Characteristic.ATTR_CCCD om een Client Characteristic Configuration Descriptor toe te voegen — vereist om PROP_NOTIFY- / PROP_INDICATE-karakteristieken te laten werken.

uuid() → UUID#: Geeft de UUID-instantie van de karakteristiek terug.

properties() → int#: Geeft het props-bitmasker terug dat bij constructie is ingesteld.

read() → bytearray#: Alleen central-rol. Lees de waarde van de karakteristiek van de verbonden peer. Geeft een bytearray met de laatste waarde terug. Op een peripheral is dit een no-op en geeft het None terug.

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

Schrijf naar de karakteristiek.

Op een peripheral wordt de waarde, als PROP_NOTIFY is ingesteld in de eigenschappen van de karakteristiek, als een GATT-notificatie naar de verbonden central verzonden; anders wordt de lokale attribuutwaarde bijgewerkt.
Op een central wordt de waarde naar de externe peer geschreven. Stel with_response=True in om een schrijfverzoek te versturen en op de bevestiging van de peer te wachten in plaats van een schrijfopdracht.

data is elk object dat het bufferprotocol ondersteunt (bytes, bytearray, memoryview).

PROP_BROADCAST: int#: De karakteristiek kan haar waarde uitzenden (0x01).

PROP_READ: int#: De karakteristiek ondersteunt leesbewerkingen (0x02).

PROP_WRITE_WO_RESP: int#: De karakteristiek ondersteunt schrijfbewerkingen zonder respons (0x04).

PROP_WRITE: int#: De karakteristiek ondersteunt schrijfbewerkingen met respons (0x08).

PROP_NOTIFY: int#: De karakteristiek kan notificaties naar een geabonneerde central pushen (0x10).

PROP_INDICATE: int#: De karakteristiek kan indicaties (bevestigde notificaties) naar een geabonneerde central pushen (0x20).

PROP_AUTH_SIGNED_WR: int#: De karakteristiek ondersteunt geverifieerde ondertekende schrijfbewerkingen (0x40).

ATTR_CCCD: int#: Voeg een Client Characteristic Configuration Descriptor toe aan de karakteristiek (0x01). Vereist om clients in staat te stellen zich op notificaties/indicaties te abonneren.

class ubluepy.Descriptor(uuid: UUID)#: Stub-klasse voor het representeren van GATT-descriptors. De huidige implementatie slaat alleen de UUID op en biedt geen methoden — ze wordt aangeboden voor voorwaartse compatibiliteit met toekomstige revisies van de module.

class ubluepy.Peripheral#

Het lokale Bluetooth LE-apparaat. Dezelfde klasse wordt gebruikt voor zowel de peripheral- als central-rol; de rol wordt geselecteerd door welke methoden je aanroept (advertise() selecteert peripheral, connect() selecteert central).

addService(service: Service) → None#: Registreer een Service (en alle eerder toegevoegde karakteristieken) bij de lokale GATT-server.

getServices() → list#: Geeft de lijst van services terug die momenteel bij deze Peripheral zijn geregistreerd.

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

Begin met adverteren in de peripheral-rol.

device_name: Volledige lokale naam die in de GAP-payload wordt geadverteerd.
services: Lijst van Service-instanties om te adverteren. De UUID van elke service wordt in de advertentie opgenomen.
data: Optionele ruwe advertentiepayload (bytes / bytearray) die aan de automatisch gegenereerde header wordt toegevoegd. Gebruik dit voor leverancierspecifieke of beacon-payloads zoals Eddystone.
connectable: Wanneer True (standaard) wordt geadverteerd als een verbindbaar apparaat en worden GAP- / GATTS-eventhandlers geregistreerd, zodat de geconfigureerde setConnectionHandler()-callback bij verbinden, verbreken en CCCD-schrijfbewerkingen wordt geactiveerd. Wanneer False wordt geadverteerd als een beacon — er worden geen handlers gekoppeld en er kan geen verbinding met het apparaat worden gemaakt.

advertise_stop() → None#: Stop elke lopende advertentie.

setConnectionHandler(func) → None#: Registreer een callback die bij GAP- en GATTS-events wordt aangeroepen. De callback wordt aangeroepen als func(event_id, conn_handle, data), waarbij event_id een van de waarden constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED of constants.EVT_GATTS_WRITE is, conn_handle de SoftDevice-verbindingshandle is (of de attribuuthandle voor GATTS-schrijfbewerkingen), en data de ruwe event-payload is als een bytearray (of None voor verbinden / verbreken).

setNotificationHandler(func) → None#: Registreer een callback voor notificatie-events die in de central-rol worden ontvangen.

withDelegate(delegate: DefaultDelegate) → None#: Koppel een DefaultDelegate-instantie om gedecodeerde GATT-events te ontvangen.

disconnect() → None#: Verbreek de actieve verbinding (momenteel een no-op-stub in deze build).

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

Alleen central-rol. Maak verbinding met de peer met het opgegeven adres en ontdek synchroon de primaire services en karakteristieken ervan. Blokkeert totdat de verbinding tot stand is gebracht en de ontdekking is voltooid; de ontdekte services zijn vervolgens beschikbaar via getServices().

addr: Peer-adres als een 17-tekenstring "xx:xx:xx:xx:xx:xx" (bijv. afkomstig van ScanEntry.addr()).
addr_type (alleen sleutelwoord): Ofwel constants.ADDR_TYPE_PUBLIC (standaard) ofwel constants.ADDR_TYPE_RANDOM_STATIC.

class ubluepy.Scanner#

GAP-observer voor het ontdekken van nabije adverterende apparaten. Alleen beschikbaar wanneer de firmware is gebouwd tegen een SoftDevice met central-ondersteuning (s132 / s140).

scan(timeout: int) → list#: Voer een passieve scan uit gedurende timeout milliseconden en geef een lijst van ScanEntry-instanties terug — één per advertentierapport dat tijdens het venster is ontvangen.

class ubluepy.ScanEntry#

Een enkel advertentierapport vastgelegd door Scanner.scan(). Instanties worden teruggegeven door de scanner — er is geen publieke constructor.

addr() → str#: Geeft het peer-adres terug als een 17-tekenstring "xx:xx:xx:xx:xx:xx".

addr_type() → int#: Geeft het type van het peer-adres terug (constants.ADDR_TYPE_PUBLIC of constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int#: Geeft de signaalsterkte-indicator in dBm terug.

getScanData() → list#: Decodeer de advertentiepayload tot een lijst van (ad_type, description, value)-tuples. ad_type is de numerieke AD-typebyte (zie constants.ad_types), description is de naam van de bijbehorende constante als een string (of None als het type onbekend is), en value is de body van het AD-record als een bytearray.

class ubluepy.DefaultDelegate#

Basisklasse voor objecten die aan Peripheral.withDelegate() worden doorgegeven. Maak er een subklasse van en overschrijf handleConnection() / handleNotification() om op GATT-events te reageren.

handleConnection() → None#: Aangeroepen bij GAP-verbind- / -verbreekevents. De standaardimplementatie is leeg.

handleNotification() → None#: Aangeroepen bij binnenkomende GATT-notificaties. De standaardimplementatie is leeg.

Constanten#

Het constants-attribuut van de module is een naamruimte die GAP/GATT-event-identificatoren, adrestype-waarden en de geneste ad_types-naamruimte bevat.

ubluepy.constants: type#: Container die de onderstaande constanten blootstelt.

constants.EVT_GAP_CONNECTED: int#: event_id-waarde van de Peripheral-verbindingshandler voor GAP-verbinden (16).

constants.EVT_GAP_DISCONNECTED: int#: event_id-waarde van de Peripheral-verbindingshandler voor GAP-verbreken (17).

constants.EVT_GATTS_WRITE: int#: event_id-waarde van de Peripheral-verbindingshandler voor een schrijfactie naar een lokaal GATT-attribuut, inclusief schrijfacties naar een CCCD die notificaties in-/uitschakelen (80).

constants.UUID_CCCD: int#: Standaard Bluetooth UUID voor de Client Characteristic Configuration Descriptor (0x2902).

constants.ADDR_TYPE_PUBLIC: int#: Public Bluetooth Device Address (0).

constants.ADDR_TYPE_RANDOM_STATIC: int#: Static random Bluetooth Device Address (1).

constants.ad_types: type#

Naamruimte van AD-typeconstanten voor advertentiegegevens uit het Bluetooth Core Specification Supplement. Elke naam wijst naar het bijbehorende 1-byte AD-type:

Naam	Waarde
`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 peripheral en central#