`ubluepy` — Bluetooth LE-kringutrustning och -central¶

Modulen ubluepy är det äldre Bluetooth LE-API:et som levereras med MicroPythons nRF-port. Det är löst modellerat efter Linux-biblioteket bluepy för Python och ligger direkt ovanpå Nordic SoftDevice — det finns ingen portabel back-end, så modulen är endast tillgänglig på Nordic-mål (Arduino Nano 33 BLE Sense i OpenMV:s sortiment). De nyare API:erna bluetooth / aioble är inte aktiverade i detta bygge, så ubluepy är det enda sättet att driva den inbyggda radion.

Den tillgängliga uppsättningen funktioner beror på vilken SoftDevice som flashats av den fasta programvaran:

s140 (Nano 33 BLE Sense) — både kringutrustnings- och central- (scanner-) roller. Detta är vad OpenMV-firmware levererar.
s132 — både kringutrustning och central.
s110 — endast kringutrustning; scanner-/connect-metoder är bortkompilerade.

Exempel på kringutrustning¶

Annonsera som en Bluetooth LE-kringutrustning med en enda environmental sensing-tjänst och notifiera en temperaturkaraktäristik vid varje skrivning till dess 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])

Exempel på central¶

Sök efter närliggande annonserande enheter i 100 ms och avkoda annonseringsdata för varje 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))

Modulinnehåll¶

Klasser¶

class ubluepy.UUID(value)¶

Konstruera ett 16- eller 128-bitars Bluetooth-UUID.

value

En av:

int — ett 16-bitars numeriskt UUID (UUID(0x180A)).
6-teckens "0xXXXX"-sträng — ett 16-bitars UUID, t.ex. UUID("0x181A").
36-teckens "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"-sträng — ett fullständigt 128-bitars UUID. Den leverantörsspecifika delen registreras hos SoftDevice vid konstruktion.
En annan UUID-instans — utför en kopiering.

Alla andra längder utlöser ValueError("Invalid UUID string length").

binVal() → int¶: Returnerar de låga 16 bitarna av UUID:et som en int. För 128-bitars UUID returneras endast det 16-bitarsfält som är inbäddat i det leverantörsspecifika UUID:et (det fullständiga 128-bitarsvärdet är endast tillgängligt via SoftDevices leverantörsspecifika index).

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

Definiera en GATT-tjänst som registreras hos SoftDevice när den läggs till i en Peripheral.

uuid: En UUID-instans. Att skicka ett objekt som inte är ett UUID utlöser ValueError.
type: Antingen Service.PRIMARY (standard) eller Service.SECONDARY. Andra värden utlöser ValueError.

uuid() → UUID¶: Returnerar tjänstens UUID-instans.

addCharacteristic(characteristic: Characteristic) → None¶: Registrera en Characteristic med tjänsten. Karaktäristikens GATT-handtag tilldelas under detta anrop.

getCharacteristic(uuid: UUID) → Characteristic | None¶: Slå upp en tidigare tillagd Characteristic via UUID. Returnerar karaktäristikinstansen, eller None om ingen matchning hittas.

getCharacteristics() → list¶: Returnerar listan över varje karaktäristik som lagts till i tjänsten.

PRIMARY: int¶: Tjänsttypskonstant för primära tjänster (1).

SECONDARY: int¶: Tjänsttypskonstant för sekundära tjänster (2).

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

Definiera en GATT-karaktäristik. Lägg till den i en Service med Service.addCharacteristic() innan den överordnade Peripheral börjar annonsera.

uuid: En UUID-instans.
props (endast nyckelord): Bitmask med ett eller flera Characteristic.PROP_*-värden som beskriver vilka operationer karaktäristiken stöder.
attrs (endast nyckelord): Bitmask med ytterligare GATT-attribut. Använd Characteristic.ATTR_CCCD för att koppla en Client Characteristic Configuration Descriptor — krävs för att få PROP_NOTIFY- / PROP_INDICATE-karaktäristiker att fungera.

uuid() → UUID¶: Returnerar karaktäristikens UUID-instans.

properties() → int¶: Returnerar den props-bitmask som angavs vid konstruktionen.

read() → bytearray¶: Endast centralroll. Läs karaktäristikens värde från den anslutna motparten. Returnerar en bytearray med det senaste värdet. På en kringutrustning är detta en no-op och returnerar None.

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

Skriv till karaktäristiken.

På en kringutrustning, om PROP_NOTIFY är inställt i karaktäristikens egenskaper skickas värdet som en GATT-notifiering till den anslutna centralen; annars uppdateras det lokala attributvärdet.
På en central skrivs värdet till den fjärranslutna motparten. Ange with_response=True för att utfärda en skrivbegäran och vänta på motpartens bekräftelse i stället för ett skrivkommando.

data är vilket objekt som helst med buffertprotokoll (bytes, bytearray, memoryview).

PROP_BROADCAST: int¶: Karaktäristiken kan sända sitt värde (0x01).

PROP_READ: int¶: Karaktäristiken stöder läsningar (0x02).

PROP_WRITE_WO_RESP: int¶: Karaktäristiken stöder skrivningar utan svar (0x04).

PROP_WRITE: int¶: Karaktäristiken stöder skrivningar med svar (0x08).

PROP_NOTIFY: int¶: Karaktäristiken kan skicka notifieringar till en prenumererande central (0x10).

PROP_INDICATE: int¶: Karaktäristiken kan skicka indikationer (bekräftade notifieringar) till en prenumererande central (0x20).

PROP_AUTH_SIGNED_WR: int¶: Karaktäristiken stöder autentiserade signerade skrivningar (0x40).

ATTR_CCCD: int¶: Lägg till en Client Characteristic Configuration Descriptor till karaktäristiken (0x01). Krävs för att klienter ska kunna prenumerera på notifieringar/indikationer.

class ubluepy.Descriptor(uuid: UUID)¶: Stub-klass för att representera GATT-deskriptorer. Den nuvarande implementationen lagrar endast UUID:et och exponerar inga metoder — den tillhandahålls för framåtkompatibilitet med framtida revisioner av modulen.

class ubluepy.Peripheral¶

Den lokala Bluetooth LE-enheten. Samma klass används för både kringutrustnings- och centralroller; rollen väljs utifrån vilka metoder du anropar (advertise() väljer kringutrustning, connect() väljer central).

addService(service: Service) → None¶: Registrera en Service (och alla dess tidigare tillagda karaktäristiker) med den lokala GATT-servern.

getServices() → list¶: Returnerar listan över de tjänster som för närvarande är registrerade med denna Peripheral.

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

Börja annonsera i kringutrustningsroll.

device_name: Fullständigt lokalt namn som annonseras i GAP-nyttolasten.
services: Lista över Service-instanser att annonsera. Varje tjänsts UUID inkluderas i annonseringen.
data: Valfri rå annonseringsnyttolast (bytes / bytearray) som läggs till efter det automatiskt genererade huvudet. Använd detta för leverantörsspecifika nyttolaster eller beacon-nyttolaster såsom Eddystone.
connectable: När True (standard), annonsera som en anslutningsbar enhet och registrera GAP-/GATTS-händelsehanterare så att det konfigurerade setConnectionHandler()-återanropet utlöses vid anslutning, frånkoppling och CCCD-skrivningar. När False, annonsera som en beacon — inga hanterare kopplas och enheten kan inte anslutas till.

advertise_stop() → None¶: Stoppa eventuell pågående annonsering.

setConnectionHandler(func) → None¶: Registrera ett återanrop som anropas vid GAP- och GATTS-händelser. Återanropet anropas som func(event_id, conn_handle, data) där event_id är ett av värdena constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED eller constants.EVT_GATTS_WRITE, conn_handle är SoftDevices anslutningshandtag (eller attributhandtag för GATTS-skrivningar), och data är den råa händelsenyttolasten som en bytearray (eller None vid anslutning/frånkoppling).

setNotificationHandler(func) → None¶: Registrera ett återanrop för notifieringshändelser som tas emot i centralroll.

withDelegate(delegate: DefaultDelegate) → None¶: Koppla en DefaultDelegate-instans för att ta emot avkodade GATT-händelser.

disconnect() → None¶: Avbryt den aktiva anslutningen (för närvarande en no-op-stub i detta bygge).

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

Endast centralroll. Anslut till motparten med den angivna adressen och upptäck synkront dess primära tjänster och karaktäristiker. Blockerar tills anslutningen är upprättad och upptäckten slutförts; de upptäckta tjänsterna är därefter tillgängliga via getServices().

addr: Motpartsadress som en 17-teckens "xx:xx:xx:xx:xx:xx"-sträng (t.ex. hämtad från ScanEntry.addr()).
addr_type (endast nyckelord): Antingen constants.ADDR_TYPE_PUBLIC (standard) eller constants.ADDR_TYPE_RANDOM_STATIC.

class ubluepy.Scanner¶

GAP-observatör för att upptäcka närliggande annonserande enheter. Tillgänglig endast när den fasta programvaran är byggd mot en SoftDevice med centralstöd (s132 / s140).

scan(timeout: int) → list¶: Kör en passiv sökning i timeout millisekunder och returnera en lista över ScanEntry-instanser — en per annonseringsrapport som mottas under fönstret.

class ubluepy.ScanEntry¶

En enskild annonseringsrapport som fångats av Scanner.scan(). Instanser returneras från scannern — det finns ingen publik konstruktor.

addr() → str¶: Returnerar motpartsadressen som en 17-teckens "xx:xx:xx:xx:xx:xx"-sträng.

addr_type() → int¶: Returnerar motpartens adresstyp (constants.ADDR_TYPE_PUBLIC eller constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int¶: Returnerar signalstyrkeindikatorn i dBm.

getScanData() → list¶: Avkoda annonseringsnyttolasten till en lista över (ad_type, description, value)-tupplar. ad_type är den numeriska AD-typbyten (se constants.ad_types), description är den matchande konstantens namn som en sträng (eller None om typen är okänd), och value är AD-postens kropp som en bytearray.

class ubluepy.DefaultDelegate¶

Basklass för objekt som skickas till Peripheral.withDelegate(). Subklassa den och åsidosätt handleConnection() / handleNotification() för att reagera på GATT-händelser.

handleConnection() → None¶: Anropas vid GAP-anslutnings-/frånkopplingshändelser. Standardimplementationen är tom.

handleNotification() → None¶: Anropas vid inkommande GATT-notifieringar. Standardimplementationen är tom.

Konstanter¶

Modulens constants-attribut är en namnrymd som innehåller GAP-/GATT-händelseidentifierare, adresstypvärden och den nästlade ad_types-namnrymden.

ubluepy.constants: type¶: Container som exponerar konstanterna nedan.

constants.EVT_GAP_CONNECTED: int¶: event_id-värde för Peripheral-anslutningshanteraren vid GAP-anslutning (16).

constants.EVT_GAP_DISCONNECTED: int¶: event_id-värde för Peripheral-anslutningshanteraren vid GAP-frånkoppling (17).

constants.EVT_GATTS_WRITE: int¶: event_id-värde för Peripheral-anslutningshanteraren vid en skrivning till ett lokalt GATT-attribut, inklusive skrivningar till en CCCD som aktiverar/inaktiverar notifieringar (80).

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

constants.ADDR_TYPE_PUBLIC: int¶: Publik Bluetooth-enhetsadress (0).

constants.ADDR_TYPE_RANDOM_STATIC: int¶: Statisk slumpmässig Bluetooth-enhetsadress (1).

constants.ad_types: type¶

Namnrymd med AD-typkonstanter för annonseringsdata från Bluetooth Core Specification Supplement. Varje namn mappar till motsvarande 1-byte AD-typ:

Namn	Värde
`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-kringutrustning och -central¶