`ubluepy` — Bluetooth-LE-Peripheriegerät und Central¶

Das ubluepy-Modul ist die veraltete Bluetooth-LE-API, die mit dem MicroPython-nRF-Port ausgeliefert wird. Es ist lose an die Linux-Python-Bibliothek bluepy angelehnt und setzt direkt auf dem Nordic SoftDevice auf — es gibt kein portierbares Back-End, sodass das Modul nur auf Nordic-Zielen verfügbar ist (in OpenMVs Produktpalette dem Arduino Nano 33 BLE Sense). Die neueren APIs bluetooth / aioble sind in diesem Build nicht aktiviert, sodass ubluepy die einzige Möglichkeit ist, das integrierte Funkmodul anzusteuern.

Der verfügbare Funktionsumfang hängt vom durch die Firmware geflashten SoftDevice ab:

s140 (Nano 33 BLE Sense) — sowohl die Peripheriegerät- als auch die Central-Rolle (Scanner). Genau dies liefert die OpenMV-Firmware aus.
s132 — sowohl Peripheriegerät als auch Central.
s110 — nur Peripheriegerät; Scanner-/Verbindungsmethoden sind herauskompiliert.

Peripheriegerät-Beispiel¶

Als Bluetooth-LE-Peripheriegerät mit einem einzelnen Umgebungssensor-Dienst (Environmental Sensing) werben und bei jedem Schreibzugriff auf den zugehörigen Client Characteristic Configuration Descriptor (CCCD) eine Temperatur-Charakteristik notifizieren:

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-Beispiel¶

100 ms lang nach umliegenden werbenden Geräten scannen und die Werbedaten jedes ScanEntry dekodieren:

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

Modulinhalt¶

Klassen¶

class ubluepy.UUID(value)¶

Konstruiert eine 16- oder 128-Bit-Bluetooth-UUID.

value

Eines von:

int — eine 16-Bit-Zahl-UUID (UUID(0x180A)).
6-stellige "0xXXXX"-Zeichenkette — eine 16-Bit-UUID, z. B. UUID("0x181A").
36-stellige "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"-Zeichenkette — eine vollständige 128-Bit-UUID. Der herstellerspezifische Anteil wird bei der Konstruktion beim SoftDevice registriert.
Eine weitere UUID-Instanz — erstellt eine Kopie.

Jede andere Länge löst ValueError("Invalid UUID string length") aus.

binVal() → int¶: Gibt die unteren 16 Bit der UUID als int zurück. Bei 128-Bit-UUIDs wird nur das in der herstellerspezifischen UUID eingebettete 16-Bit-Feld zurückgegeben (der vollständige 128-Bit-Wert ist nur über den herstellerspezifischen Index des SoftDevice zugänglich).

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

Definiert einen GATT-Dienst, der beim SoftDevice registriert wird, sobald er einem Peripheral hinzugefügt wird.

uuid: Eine UUID-Instanz. Die Übergabe eines Nicht-UUID-Objekts löst ValueError aus.
type: Entweder Service.PRIMARY (Standard) oder Service.SECONDARY. Andere Werte lösen ValueError aus.

uuid() → UUID¶: Gibt die UUID-Instanz des Dienstes zurück.

addCharacteristic(characteristic: Characteristic) → None¶: Registriert eine Characteristic beim Dienst. Das GATT-Handle der Charakteristik wird während dieses Aufrufs zugewiesen.

getCharacteristic(uuid: UUID) → Characteristic | None¶: Sucht eine zuvor hinzugefügte Characteristic anhand der UUID. Gibt die Charakteristik-Instanz zurück oder None, falls keine Übereinstimmung gefunden wird.

getCharacteristics() → list¶: Gibt die Liste aller dem Dienst hinzugefügten Charakteristiken zurück.

PRIMARY: int¶: Dienst-Typ-Konstante für primäre Dienste (1).

SECONDARY: int¶: Dienst-Typ-Konstante für sekundäre Dienste (2).

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

Definiert eine GATT-Charakteristik. Fügen Sie sie mit Service.addCharacteristic() einem Service hinzu, bevor das übergeordnete Peripheral mit dem Werben beginnt.

uuid: Eine UUID-Instanz.
props (nur als Schlüsselwort): Bitmaske aus einem oder mehreren Characteristic.PROP_*-Werten, die beschreiben, welche Operationen die Charakteristik unterstützt.
attrs (nur als Schlüsselwort): Bitmaske zusätzlicher GATT-Attribute. Verwenden Sie Characteristic.ATTR_CCCD, um einen Client Characteristic Configuration Descriptor anzuhängen — erforderlich, damit PROP_NOTIFY- / PROP_INDICATE-Charakteristiken funktionieren.

uuid() → UUID¶: Gibt die UUID-Instanz der Charakteristik zurück.

properties() → int¶: Gibt die zur Konstruktionszeit gesetzte props-Bitmaske zurück.

read() → bytearray¶: Nur Central-Rolle. Liest den Wert der Charakteristik vom verbundenen Peer. Gibt ein bytearray mit dem aktuellsten Wert zurück. Auf einem Peripheriegerät ist dies ein No-Op und gibt None zurück.

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

Schreibt in die Charakteristik.

Auf einem Peripheriegerät wird der Wert, falls PROP_NOTIFY in den Eigenschaften der Charakteristik gesetzt ist, als GATT-Notification an das verbundene Central gesendet; andernfalls wird der lokale Attributwert aktualisiert.
Auf einem Central wird der Wert auf den entfernten Peer geschrieben. Setzen Sie with_response=True, um anstelle eines Schreibbefehls eine Schreibanforderung auszugeben und auf die Bestätigung des Peers zu warten.

data ist ein beliebiges Objekt nach dem Buffer-Protokoll (bytes, bytearray, memoryview).

PROP_BROADCAST: int¶: Charakteristik kann ihren Wert broadcasten (0x01).

PROP_READ: int¶: Charakteristik unterstützt Lesezugriffe (0x02).

PROP_WRITE_WO_RESP: int¶: Charakteristik unterstützt Schreibzugriffe ohne Antwort (0x04).

PROP_WRITE: int¶: Charakteristik unterstützt Schreibzugriffe mit Antwort (0x08).

PROP_NOTIFY: int¶: Charakteristik kann Notifications an ein abonniertes Central senden (0x10).

PROP_INDICATE: int¶: Charakteristik kann Indications (bestätigte Notifications) an ein abonniertes Central senden (0x20).

PROP_AUTH_SIGNED_WR: int¶: Charakteristik unterstützt authentifizierte signierte Schreibzugriffe (0x40).

ATTR_CCCD: int¶: Fügt der Charakteristik einen Client Characteristic Configuration Descriptor hinzu (0x01). Erforderlich, damit Clients Notifications/Indications abonnieren können.

class ubluepy.Descriptor(uuid: UUID)¶: Stub-Klasse zur Repräsentation von GATT-Deskriptoren. Die aktuelle Implementierung speichert nur die UUID und stellt keine Methoden bereit — sie ist für die Vorwärtskompatibilität mit künftigen Überarbeitungen des Moduls vorgesehen.

class ubluepy.Peripheral¶

Das lokale Bluetooth-LE-Gerät. Dieselbe Klasse wird sowohl für die Peripheriegerät- als auch für die Central-Rolle verwendet; die Rolle wird dadurch ausgewählt, welche Methoden Sie aufrufen (advertise() wählt das Peripheriegerät, connect() wählt das Central).

addService(service: Service) → None¶: Registriert einen Service (und alle zuvor hinzugefügten Charakteristiken) beim lokalen GATT-Server.

getServices() → list¶: Gibt die Liste der aktuell bei diesem Peripheral registrierten Dienste zurück.

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

Beginnt mit dem Werben in der Peripheriegerät-Rolle.

device_name: Vollständiger lokaler Name, der im GAP-Payload beworben wird.
services: Liste von Service-Instanzen, für die geworben werden soll. Die UUID jedes Dienstes wird in die Werbung aufgenommen.
data: Optionaler roher Werbe-Payload (bytes / bytearray), der an den automatisch generierten Header angehängt wird. Verwenden Sie dies für herstellerspezifische oder Beacon-Payloads wie Eddystone.
connectable: Bei True (Standard) wird als verbindbares Gerät geworben und es werden GAP-/GATTS-Event-Handler registriert, sodass der konfigurierte setConnectionHandler()-Callback bei Verbindung, Trennung und CCCD-Schreibzugriffen ausgelöst wird. Bei False wird als Beacon geworben — es werden keine Handler angehängt und das Gerät kann nicht verbunden werden.

advertise_stop() → None¶: Stoppt eine laufende Werbung.

setConnectionHandler(func) → None¶: Registriert einen Callback, der bei GAP- und GATTS-Events aufgerufen wird. Der Callback wird als func(event_id, conn_handle, data) aufgerufen, wobei event_id einer der Werte constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED oder constants.EVT_GATTS_WRITE ist, conn_handle das SoftDevice-Verbindungshandle (oder das Attribut-Handle bei GATTS-Schreibzugriffen) ist und data der rohe Event-Payload als bytearray ist (oder None bei Verbindung / Trennung).

setNotificationHandler(func) → None¶: Registriert einen Callback für Notification-Events, die in der Central-Rolle empfangen werden.

withDelegate(delegate: DefaultDelegate) → None¶: Hängt eine DefaultDelegate-Instanz an, um dekodierte GATT-Events zu empfangen.

disconnect() → None¶: Trennt die aktive Verbindung (in diesem Build derzeit ein No-Op-Stub).

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

Nur Central-Rolle. Verbindet sich mit dem Peer unter der angegebenen Adresse und ermittelt synchron dessen primäre Dienste und Charakteristiken. Blockiert, bis die Verbindung hergestellt ist und die Ermittlung abgeschlossen ist; die ermittelten Dienste sind anschließend über getServices() verfügbar.

addr: Peer-Adresse als 17-stellige "xx:xx:xx:xx:xx:xx"-Zeichenkette (z. B. von ScanEntry.addr() übernommen).
addr_type (nur als Schlüsselwort): Entweder constants.ADDR_TYPE_PUBLIC (Standard) oder constants.ADDR_TYPE_RANDOM_STATIC.

class ubluepy.Scanner¶

GAP-Observer zum Auffinden umliegender werbender Geräte. Nur verfügbar, wenn die Firmware gegen ein SoftDevice mit Central-Unterstützung (s132 / s140) gebaut wurde.

scan(timeout: int) → list¶: Führt für timeout Millisekunden einen passiven Scan aus und gibt eine Liste von ScanEntry-Instanzen zurück — eine pro während des Fensters empfangenem Werbe-Report.

class ubluepy.ScanEntry¶

Ein einzelner Werbe-Report, der von Scanner.scan() erfasst wurde. Instanzen werden vom Scanner zurückgegeben — es gibt keinen öffentlichen Konstruktor.

addr() → str¶: Gibt die Peer-Adresse als 17-stellige "xx:xx:xx:xx:xx:xx"-Zeichenkette zurück.

addr_type() → int¶: Gibt den Peer-Adresstyp zurück (constants.ADDR_TYPE_PUBLIC oder constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int¶: Gibt den Signalstärke-Indikator in dBm zurück.

getScanData() → list¶: Dekodiert den Werbe-Payload in eine Liste von (ad_type, description, value)-Tupeln. ad_type ist das numerische AD-Typ-Byte (siehe constants.ad_types), description ist der Name der passenden Konstante als Zeichenkette (oder None, falls der Typ unbekannt ist), und value ist der Inhalt des AD-Records als bytearray.

class ubluepy.DefaultDelegate¶

Basisklasse für Objekte, die an Peripheral.withDelegate() übergeben werden. Leiten Sie sie ab und überschreiben Sie handleConnection() / handleNotification(), um auf GATT-Events zu reagieren.

handleConnection() → None¶: Wird bei GAP-Verbindungs-/Trennungs-Events aufgerufen. Die Standardimplementierung ist leer.

handleNotification() → None¶: Wird bei eingehenden GATT-Notifications aufgerufen. Die Standardimplementierung ist leer.

Konstanten¶

Das constants-Attribut des Moduls ist ein Namespace, der GAP-/GATT-Event-Bezeichner, Adresstyp-Werte und den verschachtelten ad_types-Namespace enthält.

ubluepy.constants: type¶: Container, der die unten aufgeführten Konstanten bereitstellt.

constants.EVT_GAP_CONNECTED: int¶: event_id-Wert des Peripheral-Verbindungs-Handlers für GAP-Verbindung (16).

constants.EVT_GAP_DISCONNECTED: int¶: event_id-Wert des Peripheral-Verbindungs-Handlers für GAP-Trennung (17).

constants.EVT_GATTS_WRITE: int¶: event_id-Wert des Peripheral-Verbindungs-Handlers für einen Schreibzugriff auf ein lokales GATT-Attribut, einschließlich Schreibzugriffen auf einen CCCD, die Notifications aktivieren/deaktivieren (80).

constants.UUID_CCCD: int¶: Standard-Bluetooth-UUID für den Client Characteristic Configuration Descriptor (0x2902).

constants.ADDR_TYPE_PUBLIC: int¶: Öffentliche Bluetooth-Geräteadresse (0).

constants.ADDR_TYPE_RANDOM_STATIC: int¶: Statische zufällige Bluetooth-Geräteadresse (1).

constants.ad_types: type¶

Namespace der AD-Typ-Konstanten für Werbedaten aus dem Bluetooth Core Specification Supplement. Jeder Name wird auf den entsprechenden 1-Byte-AD-Typ abgebildet:

Name	Wert
`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-Peripheriegerät und Central¶