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