`ubluepy` — Bluetooth LE çevre birimi (peripheral) ve merkez (central)¶

ubluepy modülü, MicroPython nRF uyarlaması ile birlikte gelen eski Bluetooth LE API’sidir. Linux bluepy Python kütüphanesi temel alınarak gevşek bir şekilde modellenmiştir ve doğrudan Nordic SoftDevice üzerine oturur — taşınabilir bir arka uç yoktur, dolayısıyla modül yalnızca Nordic hedeflerinde (OpenMV ürün yelpazesinde Arduino Nano 33 BLE Sense) kullanılabilir. Daha yeni bluetooth / aioble API’leri bu derlemede etkinleştirilmemiştir, bu nedenle yonga üzerindeki radyoyu sürmenin tek yolu ubluepy modülüdür.

Kullanılabilir özellik kümesi, aygıt yazılımı (firmware) tarafından flash belleğe yazılan SoftDevice’a bağlıdır:

s140 (Nano 33 BLE Sense) — hem çevre birimi (peripheral) hem de merkez (tarayıcı) rolleri. OpenMV aygıt yazılımının (firmware) içerdiği budur.
s132 — hem çevre birimi hem de merkez.
s110 — yalnızca çevre birimi; tarayıcı / bağlanma metotları derleme dışı bırakılır.

Çevre birimi örneği¶

Tek bir çevresel algılama hizmetiyle Bluetooth LE çevre birimi olarak yayın yapın ve Client Characteristic Configuration Descriptor (CCCD) öğesine yapılan her yazma işleminde bir sıcaklık karakteristiğine bildirim gönderin:

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

Merkez örneği¶

100 ms boyunca yakındaki yayın yapan cihazları tarayın ve her ScanEntry öğesinin reklam verisini çözün:

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

Modül içeriği¶

Sınıflar¶

class ubluepy.UUID(value)¶

16 bitlik veya 128 bitlik bir Bluetooth UUID oluşturur.

value

Şunlardan biri:

int — 16 bitlik sayısal bir UUID (UUID(0x180A)).
6 karakterlik "0xXXXX" dizesi — 16 bitlik bir UUID, örn. UUID("0x181A").
36 karakterlik "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" dizesi — tam 128 bitlik bir UUID. Üreticiye özel kısım, oluşturma sırasında SoftDevice’a kaydedilir.
Başka bir UUID örneği — bir kopya gerçekleştirir.

Başka herhangi bir uzunluk ValueError("Invalid UUID string length") hatasını yükseltir.

binVal() → int¶: UUID’nin düşük 16 bitini bir int olarak döndürür. 128 bitlik UUID’ler için yalnızca üreticiye özel UUID içine gömülü 16 bitlik alan döndürülür (tam 128 bitlik değere yalnızca SoftDevice’ın üreticiye özel dizini aracılığıyla erişilebilir).

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

Bir Peripheral öğesine eklendiğinde SoftDevice’a kaydedilecek bir GATT hizmeti tanımlar.

uuid: Bir UUID örneği. UUID olmayan bir nesne geçirmek ValueError hatasını yükseltir.
type: Service.PRIMARY (varsayılan) veya Service.SECONDARY öğelerinden biri. Diğer değerler ValueError hatasını yükseltir.

uuid() → UUID¶: Hizmetin UUID örneğini döndürür.

addCharacteristic(characteristic: Characteristic) → None¶: Hizmete bir Characteristic kaydeder. Karakteristiğin GATT tutamacı (handle) bu çağrı sırasında atanır.

getCharacteristic(uuid: UUID) → Characteristic | None¶: Daha önce eklenmiş bir Characteristic öğesini UUID’ye göre arar. Karakteristik örneğini, eşleşme bulunamazsa None döndürür.

getCharacteristics() → list¶: Hizmete eklenen her karakteristiğin listesini döndürür.

PRIMARY: int¶: Birincil hizmetler için hizmet türü sabiti (1).

SECONDARY: int¶: İkincil hizmetler için hizmet türü sabiti (2).

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

Bir GATT karakteristiği tanımlar. Üst Peripheral öğesi yayına başlamadan önce Service.addCharacteristic() ile bir Service öğesine ekleyin.

uuid: Bir UUID örneği.
props (yalnızca anahtar sözcük): Karakteristiğin hangi işlemleri desteklediğini açıklayan bir veya daha fazla Characteristic.PROP_* değerinden oluşan bit maskesi.
attrs (yalnızca anahtar sözcük): Ek GATT özniteliklerinin bit maskesi. Bir Client Characteristic Configuration Descriptor eklemek için Characteristic.ATTR_CCCD kullanın — PROP_NOTIFY / PROP_INDICATE karakteristiklerinin çalışması için gereklidir.

uuid() → UUID¶: Karakteristiğin UUID örneğini döndürür.

properties() → int¶: Oluşturma sırasında ayarlanan props bit maskesini döndürür.

read() → bytearray¶: Yalnızca merkez rolü. Karakteristiğin değerini bağlı eşten okur. En son değeri içeren bir bytearray döndürür. Bir çevre biriminde bu işlemsizdir (no-op) ve None döndürür.

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

Karakteristiğe yazar.

Bir çevre biriminde, karakteristiğin özelliklerinde PROP_NOTIFY ayarlanmışsa değer, bağlı merkeze bir GATT bildirimi olarak gönderilir; aksi takdirde yerel öznitelik değeri güncellenir.
Bir merkezde, değer uzaktaki eşe yazılır. Bir yazma komutu yerine bir yazma isteği göndermek ve eşin onayını beklemek için with_response=True ayarlayın.

data, herhangi bir arabellek protokolü nesnesidir (bytes, bytearray, memoryview).

PROP_BROADCAST: int¶: Karakteristik değerini yayınlayabilir (0x01).

PROP_READ: int¶: Karakteristik okumaları destekler (0x02).

PROP_WRITE_WO_RESP: int¶: Karakteristik yanıtsız yazmaları destekler (0x04).

PROP_WRITE: int¶: Karakteristik yanıtlı yazmaları destekler (0x08).

PROP_NOTIFY: int¶: Karakteristik, abone olan bir merkeze bildirim gönderebilir (0x10).

PROP_INDICATE: int¶: Karakteristik, abone olan bir merkeze gösterimler (onaylanmış bildirimler) gönderebilir (0x20).

PROP_AUTH_SIGNED_WR: int¶: Karakteristik, kimliği doğrulanmış imzalı yazmaları destekler (0x40).

ATTR_CCCD: int¶: Karakteristiğe bir Client Characteristic Configuration Descriptor ekler (0x01). İstemcilerin bildirimlere/gösterimlere abone olabilmesi için gereklidir.

class ubluepy.Descriptor(uuid: UUID)¶: GATT tanımlayıcılarını temsil etmek için iskelet sınıfı. Mevcut uygulama yalnızca UUID’yi saklar ve hiçbir metot sunmaz — modülün gelecekteki sürümleriyle ileriye dönük uyumluluk için sağlanmıştır.

class ubluepy.Peripheral¶

Yerel Bluetooth LE cihazı. Hem çevre birimi hem de merkez rolleri için aynı sınıf kullanılır; rol, çağırdığınız metotlara göre seçilir (advertise() çevre birimini, connect() merkezi seçer).

addService(service: Service) → None¶: Yerel GATT sunucusuna bir Service (ve daha önce eklenmiş tüm karakteristikleri) kaydeder.

getServices() → list¶: Bu Peripheral öğesine şu anda kayıtlı olan hizmetlerin listesini döndürür.

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

Çevre birimi rolünde yayına başlar.

device_name: GAP yükünde yayınlanan tam yerel ad.
services: Yayınlanacak Service örneklerinin listesi. Her hizmetin UUID’si reklama dahil edilir.
data: Otomatik oluşturulan başlığa eklenen isteğe bağlı ham reklam yükü (bytes / bytearray). Bunu Eddystone gibi üreticiye özel veya işaret (beacon) yükleri için kullanın.
connectable: True (varsayılan) olduğunda, bağlanılabilir bir cihaz olarak yayın yapar ve GAP / GATTS olay işleyicilerini kaydeder; böylece yapılandırılmış setConnectionHandler() geri çağırması (callback) bağlantı, bağlantı kesme ve CCCD yazma işlemlerinde tetiklenir. False olduğunda, bir işaret (beacon) olarak yayın yapar — hiçbir işleyici eklenmez ve cihaza bağlanılamaz.

advertise_stop() → None¶: Devam eden tüm reklamları durdurur.

setConnectionHandler(func) → None¶: GAP ve GATTS olaylarında çağrılan bir geri çağırma (callback) kaydeder. Geri çağırma func(event_id, conn_handle, data) olarak çağrılır; burada event_id, constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED veya constants.EVT_GATTS_WRITE değerlerinden biridir, conn_handle, SoftDevice bağlantı tutamacıdır (veya GATTS yazmaları için öznitelik tutamacı) ve data, ham olay yükünün bir bytearray halidir (veya bağlantı / bağlantı kesme için None).

setNotificationHandler(func) → None¶: Merkez rolünde alınan bildirim olayları için bir geri çağırma (callback) kaydeder.

withDelegate(delegate: DefaultDelegate) → None¶: Çözülmüş GATT olaylarını almak için bir DefaultDelegate örneği ekler.

disconnect() → None¶: Etkin bağlantıyı keser (bu derlemede şu anda işlemsiz bir iskelettir).

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

Yalnızca merkez rolü. Verilen adrese sahip eşe bağlanır ve birincil hizmetlerini ve karakteristiklerini eşzamanlı olarak keşfeder. Bağlantı kurulana ve keşif tamamlanana kadar bloke eder; keşfedilen hizmetler daha sonra getServices() aracılığıyla kullanılabilir.

addr: 17 karakterlik "xx:xx:xx:xx:xx:xx" dizesi olarak eş adresi (örn. ScanEntry.addr() öğesinden alınan).
addr_type (yalnızca anahtar sözcük): constants.ADDR_TYPE_PUBLIC (varsayılan) veya constants.ADDR_TYPE_RANDOM_STATIC öğelerinden biri.

class ubluepy.Scanner¶

Yakındaki yayın yapan cihazları keşfetmek için GAP gözlemcisi. Yalnızca aygıt yazılımı (firmware) merkez desteği olan bir SoftDevice’a (s132 / s140) karşı derlendiğinde kullanılabilir.

scan(timeout: int) → list¶: timeout milisaniye boyunca pasif bir tarama çalıştırır ve bir ScanEntry örnekleri listesi döndürür — pencere boyunca alınan her reklam raporu için bir tane.

class ubluepy.ScanEntry¶

Scanner.scan() tarafından yakalanan tek bir reklam raporu. Örnekler tarayıcıdan döndürülür — genel bir oluşturucu (constructor) yoktur.

addr() → str¶: Eş adresini 17 karakterlik "xx:xx:xx:xx:xx:xx" dizesi olarak döndürür.

addr_type() → int¶: Eş adresi türünü döndürür (constants.ADDR_TYPE_PUBLIC veya constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int¶: dBm cinsinden sinyal gücü göstergesini döndürür.

getScanData() → list¶: Reklam yükünü bir (ad_type, description, value) demetleri listesine çözer. ad_type, sayısal AD türü baytıdır (bkz. constants.ad_types), description, eşleşen sabitin adını bir dize olarak verir (veya tür bilinmiyorsa None) ve value, AD kaydının gövdesini bir bytearray olarak verir.

class ubluepy.DefaultDelegate¶

Peripheral.withDelegate() öğesine geçirilen nesneler için temel sınıf. GATT olaylarına tepki vermek için bu sınıftan türetin ve handleConnection() / handleNotification() metotlarını geçersiz kılın.

handleConnection() → None¶: GAP bağlantı / bağlantı kesme olaylarında çağrılır. Varsayılan uygulama boştur.

handleNotification() → None¶: Gelen GATT bildirimlerinde çağrılır. Varsayılan uygulama boştur.

Sabitler¶

Modülün constants özniteliği, GAP/GATT olay tanımlayıcıları, adres türü değerleri ve iç içe geçmiş ad_types ad alanını içeren bir ad alanıdır.

ubluepy.constants: type¶: Aşağıdaki sabitleri sunan kapsayıcı.

constants.EVT_GAP_CONNECTED: int¶: GAP bağlantısı için Peripheral bağlantı işleyicisi event_id değeri (16).

constants.EVT_GAP_DISCONNECTED: int¶: GAP bağlantı kesilmesi için Peripheral bağlantı işleyicisi event_id değeri (17).

constants.EVT_GATTS_WRITE: int¶: Bildirimleri etkinleştiren/devre dışı bırakan bir CCCD’ye yapılan yazmalar dahil olmak üzere, yerel bir GATT özniteliğine yapılan bir yazma için Peripheral bağlantı işleyicisi event_id değeri (80).

constants.UUID_CCCD: int¶: Client Characteristic Configuration Descriptor için standart Bluetooth UUID’si (0x2902).

constants.ADDR_TYPE_PUBLIC: int¶: Genel (Public) Bluetooth Cihaz Adresi (0).

constants.ADDR_TYPE_RANDOM_STATIC: int¶: Statik rastgele Bluetooth Cihaz Adresi (1).

constants.ad_types: type¶

Bluetooth Core Specification Supplement kaynağından gelen reklam verisi AD türü sabitlerinin ad alanı. Her ad, karşılık gelen 1 baytlık AD türüyle eşleşir:

Ad	Değer
`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 çevre birimi (peripheral) ve merkez (central)¶