`ubluepy` --- periferal dan central Bluetooth LE#

Modul ubluepy adalah API Bluetooth LE lama yang dikirimkan dengan port nRF MicroPython. Modul ini dirancang secara longgar berdasarkan perpustakaan Python bluepy Linux dan berada langsung di atas Nordic SoftDevice --- tidak ada backend portabel, sehingga modul hanya tersedia pada target Nordic (Arduino Nano 33 BLE Sense dalam jajaran OpenMV). API bluetooth / aioble yang lebih baru tidak diaktifkan dalam build ini, sehingga ubluepy adalah satu-satunya cara untuk mengendalikan radio on-die.

Set fitur yang tersedia bergantung pada SoftDevice yang di-flash oleh firmware:

s140 (Nano 33 BLE Sense) --- peran peripheral dan central (scanner). Inilah yang dikirimkan oleh firmware OpenMV.
s132 --- periferal dan central.
s110 --- hanya peripheral; metode scanner / connect dikompilasi keluar.

Contoh Peripheral#

Iklankan sebagai peripheral Bluetooth LE dengan satu layanan penginderaan lingkungan dan notifikasi karakteristik suhu pada setiap penulisan ke Client Characteristic Configuration Descriptor (CCCD)-nya:

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

Contoh Central#

Pindai perangkat iklan terdekat selama 100 ms dan dekode data iklan setiap 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))

Isi modul#

Kelas#

class ubluepy.UUID(value)#

Buat UUID Bluetooth 16- atau 128-bit.

value

Salah satu dari:

int --- UUID numerik 16-bit (UUID(0x180A)).
String "0xXXXX" 6-karakter --- UUID 16-bit, misalnya UUID("0x181A").
String "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" 36-karakter --- UUID 128-bit penuh. Bagian vendor-spesifik didaftarkan ke SoftDevice saat konstruksi.
Instance UUID lain --- melakukan salinan.

Panjang lain apa pun akan memunculkan ValueError("Invalid UUID string length").

binVal() → int#: Kembalikan 16 bit rendah UUID sebagai int. Untuk UUID 128-bit, hanya field 16-bit yang tertanam di dalam UUID vendor-spesifik yang dikembalikan (nilai 128-bit penuh hanya dapat diakses melalui indeks vendor-spesifik SoftDevice).

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

Definisikan layanan GATT yang akan didaftarkan ke SoftDevice saat ditambahkan ke Peripheral.

uuid: Instance UUID. Meneruskan objek non-UUID akan memunculkan ValueError.
type: Salah satu Service.PRIMARY (default) atau Service.SECONDARY. Nilai lain memunculkan ValueError.

uuid() → UUID#: Kembalikan instance UUID layanan.

addCharacteristic(characteristic: Characteristic) → None#: Daftarkan Characteristic ke layanan. Handle GATT karakteristik ditetapkan selama pemanggilan ini.

getCharacteristic(uuid: UUID) → Characteristic | None#: Cari Characteristic yang sebelumnya ditambahkan berdasarkan UUID. Mengembalikan instance karakteristik, atau None jika tidak ditemukan.

getCharacteristics() → list#: Kembalikan daftar semua karakteristik yang ditambahkan ke layanan.

PRIMARY: int#: Konstanta tipe layanan untuk layanan primer (1).

SECONDARY: int#: Konstanta tipe layanan untuk layanan sekunder (2).

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

Definisikan karakteristik GATT. Tambahkan ke Service dengan Service.addCharacteristic() sebelum Peripheral induk mulai beriklan.

uuid: Instance UUID.
props (hanya kata kunci): Bitmask dari satu atau lebih nilai Characteristic.PROP_* yang mendeskripsikan operasi apa yang didukung oleh karakteristik.
attrs (hanya kata kunci): Bitmask dari atribut GATT tambahan. Gunakan Characteristic.ATTR_CCCD untuk melampirkan Client Characteristic Configuration Descriptor --- diperlukan agar karakteristik PROP_NOTIFY / PROP_INDICATE berfungsi.

uuid() → UUID#: Kembalikan instance UUID karakteristik.

properties() → int#: Kembalikan bitmask props yang ditetapkan pada saat konstruksi.

read() → bytearray#: Hanya peran central. Baca nilai karakteristik dari peer yang terhubung. Mengembalikan bytearray dengan nilai terbaru. Pada peripheral ini adalah no-op dan mengembalikan None.

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

Tulis ke karakteristik.

Pada peripheral, jika PROP_NOTIFY diatur dalam properti karakteristik, nilai dikirimkan sebagai notifikasi GATT ke central yang terhubung; jika tidak, nilai atribut lokal diperbarui.
Pada central, nilai ditulis ke peer jarak jauh. Atur with_response=True untuk mengeluarkan permintaan tulis dan menunggu pengakuan dari peer alih-alih perintah tulis.

data adalah objek protokol buffer apa pun (bytes, bytearray, memoryview).

PROP_BROADCAST: int#: Karakteristik dapat menyiarkan nilainya (0x01).

PROP_READ: int#: Karakteristik mendukung pembacaan (0x02).

PROP_WRITE_WO_RESP: int#: Karakteristik mendukung penulisan tanpa respons (0x04).

PROP_WRITE: int#: Karakteristik mendukung penulisan dengan respons (0x08).

PROP_NOTIFY: int#: Karakteristik dapat mendorong notifikasi ke central yang berlangganan (0x10).

PROP_INDICATE: int#: Karakteristik dapat mendorong indikasi (notifikasi yang diakui) ke central yang berlangganan (0x20).

PROP_AUTH_SIGNED_WR: int#: Karakteristik mendukung penulisan bertanda tangan yang diautentikasi (0x40).

ATTR_CCCD: int#: Tambahkan Client Characteristic Configuration Descriptor ke karakteristik (0x01). Diperlukan agar klien dapat berlangganan notifikasi/indikasi.

class ubluepy.Descriptor(uuid: UUID)#: Kelas stub untuk merepresentasikan deskriptor GATT. Implementasi saat ini hanya menyimpan UUID dan tidak mengekspos metode --- disediakan untuk kompatibilitas ke depan dengan revisi modul di masa mendatang.

class ubluepy.Peripheral#

Perangkat Bluetooth LE lokal. Kelas yang sama digunakan untuk peran peripheral dan central; peran dipilih berdasarkan metode yang Anda panggil (advertise() memilih peripheral, connect() memilih central).

addService(service: Service) → None#: Daftarkan Service (dan semua karakteristiknya yang sebelumnya ditambahkan) ke server GATT lokal.

getServices() → list#: Kembalikan daftar layanan yang saat ini terdaftar pada Peripheral ini.

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

Mulai beriklan dalam peran peripheral.

device_name: Nama lokal lengkap yang diiklankan dalam payload GAP.
services: Daftar instance Service untuk diiklankan. UUID setiap layanan disertakan dalam iklan.
data: Payload iklan mentah opsional (bytes / bytearray) yang ditambahkan ke header yang dibuat secara otomatis. Gunakan ini untuk payload vendor-spesifik atau beacon seperti Eddystone.
connectable: Saat True (default), iklankan sebagai perangkat yang dapat dihubungkan dan daftarkan handler event GAP / GATTS sehingga callback setConnectionHandler() yang dikonfigurasi aktif saat connect, disconnect, dan penulisan CCCD. Saat False, iklankan sebagai beacon --- tidak ada handler yang dilampirkan dan perangkat tidak dapat dihubungkan.

advertise_stop() → None#: Hentikan iklan yang sedang berlangsung.

setConnectionHandler(func) → None#: Daftarkan callback yang dipanggil pada event GAP dan GATTS. Callback dipanggil sebagai func(event_id, conn_handle, data) di mana event_id adalah salah satu nilai constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED, atau constants.EVT_GATTS_WRITE, conn_handle adalah handle koneksi SoftDevice (atau handle atribut untuk penulisan GATTS), dan data adalah payload event mentah sebagai bytearray (atau None untuk connect / disconnect).

setNotificationHandler(func) → None#: Daftarkan callback untuk event notifikasi yang diterima dalam peran central.

withDelegate(delegate: DefaultDelegate) → None#: Lampirkan instance DefaultDelegate untuk menerima event GATT yang sudah didekode.

disconnect() → None#: Putuskan koneksi aktif (saat ini berupa stub no-op dalam build ini).

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

Hanya peran central. Hubungkan ke peer dengan alamat yang diberikan dan temukan layanan primer serta karakteristiknya secara sinkron. Memblokir hingga koneksi terbentuk dan penemuan selesai; layanan yang ditemukan kemudian tersedia melalui getServices().

addr: Alamat peer sebagai string "xx:xx:xx:xx:xx:xx" 17-karakter (misalnya diambil dari ScanEntry.addr()).
addr_type (hanya kata kunci): Salah satu constants.ADDR_TYPE_PUBLIC (default) atau constants.ADDR_TYPE_RANDOM_STATIC.

class ubluepy.Scanner#

Observer GAP untuk menemukan perangkat iklan terdekat. Hanya tersedia saat firmware dibangun dengan SoftDevice yang memiliki dukungan central (s132 / s140).

scan(timeout: int) → list#: Jalankan pemindaian pasif selama timeout milidetik dan kembalikan daftar instance ScanEntry --- satu per laporan iklan yang diterima selama jendela waktu.

class ubluepy.ScanEntry#

Satu laporan iklan yang ditangkap oleh Scanner.scan(). Instance dikembalikan dari scanner --- tidak ada konstruktor publik.

addr() → str#: Kembalikan alamat peer sebagai string "xx:xx:xx:xx:xx:xx" 17-karakter.

addr_type() → int#: Kembalikan tipe alamat peer (constants.ADDR_TYPE_PUBLIC atau constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int#: Kembalikan indikator kekuatan sinyal dalam dBm.

getScanData() → list#: Dekode payload iklan menjadi daftar tuple (ad_type, description, value). ad_type adalah byte tipe AD numerik (lihat constants.ad_types), description adalah nama konstanta yang cocok sebagai string (atau None jika tipe tidak dikenal), dan value adalah badan rekaman AD sebagai bytearray.

class ubluepy.DefaultDelegate#

Kelas dasar untuk objek yang diteruskan ke Peripheral.withDelegate(). Turunkan dan timpa handleConnection() / handleNotification() untuk bereaksi terhadap event GATT.

handleConnection() → None#: Dipanggil pada event GAP connect / disconnect. Implementasi default tidak melakukan apa-apa.

handleNotification() → None#: Dipanggil pada notifikasi GATT yang masuk. Implementasi default tidak melakukan apa-apa.

Konstanta#

Atribut constants dari modul adalah namespace yang berisi pengidentifikasi event GAP/GATT, nilai tipe alamat, dan namespace ad_types yang bersarang.

ubluepy.constants: type#: Kontainer yang mengekspos konstanta-konstanta di bawah ini.

constants.EVT_GAP_CONNECTED: int#: Nilai event_id handler koneksi Peripheral untuk GAP connect (16).

constants.EVT_GAP_DISCONNECTED: int#: Nilai event_id handler koneksi Peripheral untuk GAP disconnect (17).

constants.EVT_GATTS_WRITE: int#: Nilai event_id handler koneksi Peripheral untuk penulisan ke atribut GATT lokal, termasuk penulisan ke CCCD yang mengaktifkan/menonaktifkan notifikasi (80).

constants.UUID_CCCD: int#: UUID Bluetooth standar untuk Client Characteristic Configuration Descriptor (0x2902).

constants.ADDR_TYPE_PUBLIC: int#: Alamat Perangkat Bluetooth Publik (0).

constants.ADDR_TYPE_RANDOM_STATIC: int#: Alamat Perangkat Bluetooth acak statis (1).

constants.ad_types: type#

Namespace konstanta tipe AD data-iklan dari Bluetooth Core Specification Supplement. Setiap nama memetakan ke tipe AD 1-byte yang sesuai:

Nama	Nilai
`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 --- periferal dan central Bluetooth LE#