`ubluepy` --- Bluetooth LE peripheral và central¶

Mô-đun ubluepy là API Bluetooth LE cũ đi kèm với nRF port của MicroPython. Nó được mô hình hóa một cách lỏng lẻo dựa trên thư viện Python bluepy trên Linux và nằm trực tiếp trên Nordic SoftDevice --- không có back-end di động, vì vậy mô-đun này chỉ khả dụng trên các mục tiêu Nordic (Arduino Nano 33 BLE Sense trong dòng sản phẩm của OpenMV). Các API bluetooth / aioble mới hơn không được bật trong bản dựng này, vì vậy ubluepy là cách duy nhất để điều khiển radio tích hợp.

Tập hợp tính năng có sẵn phụ thuộc vào SoftDevice được flash bởi firmware:

s140 (Nano 33 BLE Sense) --- cả hai vai trò peripheral và central (scanner). Đây là phiên bản firmware OpenMV cung cấp.
s132 --- cả peripheral và central.
s110 --- chỉ peripheral; các phương thức scanner / connect được biên dịch ra ngoài.

Ví dụ Peripheral¶

Quảng bá như một Bluetooth LE peripheral với một dịch vụ cảm biến môi trường duy nhất và thông báo một đặc tính nhiệt độ trên mỗi lần ghi vào Client Characteristic Configuration Descriptor (CCCD) của nó:

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

Ví dụ Central¶

Quét các thiết bị quảng bá gần đó trong 100 ms và giải mã dữ liệu quảng bá của mỗi 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))

Nội dung mô-đun¶

Các lớp¶

class ubluepy.UUID(value)¶

Tạo một Bluetooth UUID 16-bit hoặc 128-bit.

value

Một trong số:

int --- một UUID số 16-bit (UUID(0x180A)).
Chuỗi "0xXXXX" 6 ký tự --- một UUID 16-bit, ví dụ UUID("0x181A").
Chuỗi "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" 36 ký tự --- một UUID 128-bit đầy đủ. Phần dành riêng cho nhà cung cấp được đăng ký với SoftDevice khi khởi tạo.
Một thực thể UUID khác --- thực hiện sao chép.

Bất kỳ độ dài nào khác đều gây ra ValueError("Invalid UUID string length").

binVal() → int¶: Trả về 16 bit thấp của UUID dưới dạng int. Đối với UUID 128-bit, chỉ trường 16-bit được nhúng bên trong UUID dành riêng cho nhà cung cấp mới được trả về (giá trị 128-bit đầy đủ chỉ có thể truy cập thông qua chỉ số dành riêng cho nhà cung cấp của SoftDevice).

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

Định nghĩa một dịch vụ GATT sẽ được đăng ký với SoftDevice khi được thêm vào Peripheral.

uuid: Một thực thể UUID. Truyền một đối tượng không phải UUID sẽ gây ra ValueError.
type: Là Service.PRIMARY (mặc định) hoặc Service.SECONDARY. Các giá trị khác gây ra ValueError.

uuid() → UUID¶: Trả về thực thể UUID của dịch vụ.

addCharacteristic(characteristic: Characteristic) → None¶: Đăng ký một Characteristic với dịch vụ. Handle GATT của đặc tính được gán trong lần gọi này.

getCharacteristic(uuid: UUID) → Characteristic | None¶: Tra cứu một Characteristic đã được thêm trước đó theo UUID. Trả về thực thể đặc tính, hoặc None nếu không tìm thấy.

getCharacteristics() → list¶: Trả về danh sách mọi đặc tính đã được thêm vào dịch vụ.

PRIMARY: int¶: Hằng số kiểu dịch vụ cho dịch vụ chính (1).

SECONDARY: int¶: Hằng số kiểu dịch vụ cho dịch vụ phụ (2).

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

Định nghĩa một đặc tính GATT. Thêm nó vào một Service với Service.addCharacteristic() trước khi Peripheral cha bắt đầu quảng bá.

uuid: Một thực thể UUID.
props (keyword-only): Bitmask của một hoặc nhiều giá trị Characteristic.PROP_* mô tả các thao tác mà đặc tính hỗ trợ.
attrs (keyword-only): Bitmask của các thuộc tính GATT bổ sung. Sử dụng Characteristic.ATTR_CCCD để đính kèm Client Characteristic Configuration Descriptor --- cần thiết để làm cho các đặc tính PROP_NOTIFY / PROP_INDICATE hoạt động.

uuid() → UUID¶: Trả về thực thể UUID của đặc tính.

properties() → int¶: Trả về bitmask props được đặt tại thời điểm khởi tạo.

read() → bytearray¶: Chỉ vai trò central. Đọc giá trị của đặc tính từ peer đã kết nối. Trả về bytearray với giá trị mới nhất. Trên peripheral, đây là no-op và trả về None.

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

Ghi vào đặc tính.

Trên peripheral, nếu PROP_NOTIFY được đặt trong thuộc tính của đặc tính, giá trị được gửi dưới dạng thông báo GATT đến central đã kết nối; nếu không, giá trị thuộc tính cục bộ được cập nhật.
Trên central, giá trị được ghi vào peer từ xa. Đặt with_response=True để gửi yêu cầu ghi và chờ xác nhận từ peer thay vì lệnh ghi.

data là bất kỳ đối tượng nào hỗ trợ giao thức buffer (bytes, bytearray, memoryview).

PROP_BROADCAST: int¶: Đặc tính có thể phát sóng giá trị của nó (0x01).

PROP_READ: int¶: Đặc tính hỗ trợ đọc (0x02).

PROP_WRITE_WO_RESP: int¶: Đặc tính hỗ trợ ghi không có phản hồi (0x04).

PROP_WRITE: int¶: Đặc tính hỗ trợ ghi có phản hồi (0x08).

PROP_NOTIFY: int¶: Đặc tính có thể đẩy thông báo đến central đã đăng ký (0x10).

PROP_INDICATE: int¶: Đặc tính có thể đẩy chỉ định (thông báo đã xác nhận) đến central đã đăng ký (0x20).

PROP_AUTH_SIGNED_WR: int¶: Đặc tính hỗ trợ ghi đã ký xác thực (0x40).

ATTR_CCCD: int¶: Thêm Client Characteristic Configuration Descriptor vào đặc tính (0x01). Cần thiết để các client có thể đăng ký nhận thông báo/chỉ định.

class ubluepy.Descriptor(uuid: UUID)¶: Lớp stub để biểu diễn các GATT descriptor. Cài đặt hiện tại chỉ lưu trữ UUID và không hiển thị các phương thức --- nó được cung cấp để tương thích với các phiên bản mô-đun trong tương lai.

class ubluepy.Peripheral¶

Thiết bị Bluetooth LE cục bộ. Cùng một lớp được sử dụng cho cả vai trò peripheral và central; vai trò được chọn bởi các phương thức bạn gọi (advertise() chọn peripheral, connect() chọn central).

addService(service: Service) → None¶: Đăng ký một Service (và tất cả các đặc tính đã được thêm trước đó) với máy chủ GATT cục bộ.

getServices() → list¶: Trả về danh sách các dịch vụ hiện đang được đăng ký với Peripheral này.

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

Bắt đầu quảng bá ở vai trò peripheral.

device_name: Tên cục bộ đầy đủ được quảng bá trong tải trọng GAP.
services: Danh sách các thực thể Service để quảng bá. UUID của mỗi dịch vụ được bao gồm trong quảng cáo.
data: Tải trọng quảng cáo thô tùy chọn (bytes / bytearray) được thêm vào tiêu đề được tạo tự động. Sử dụng tham số này cho tải trọng dành riêng cho nhà cung cấp hoặc beacon như Eddystone.
connectable: Khi True (mặc định), quảng bá như một thiết bị có thể kết nối và đăng ký bộ xử lý sự kiện GAP / GATTS để hàm gọi lại setConnectionHandler() đã cấu hình kích hoạt khi kết nối, ngắt kết nối và ghi CCCD. Khi False, quảng bá như một beacon --- không có bộ xử lý nào được đính kèm và thiết bị không thể được kết nối.

advertise_stop() → None¶: Dừng bất kỳ quảng cáo đang diễn ra nào.

setConnectionHandler(func) → None¶: Đăng ký một hàm gọi lại được gọi trên các sự kiện GAP và GATTS. Hàm gọi lại được gọi là func(event_id, conn_handle, data) trong đó event_id là một trong các giá trị constants.EVT_GAP_CONNECTED, constants.EVT_GAP_DISCONNECTED, hoặc constants.EVT_GATTS_WRITE, conn_handle là handle kết nối SoftDevice (hoặc handle thuộc tính cho ghi GATTS), và data là tải trọng sự kiện thô dưới dạng bytearray (hoặc None cho kết nối / ngắt kết nối).

setNotificationHandler(func) → None¶: Đăng ký một hàm gọi lại cho các sự kiện thông báo nhận được ở vai trò central.

withDelegate(delegate: DefaultDelegate) → None¶: Đính kèm một thực thể DefaultDelegate để nhận các sự kiện GATT đã giải mã.

disconnect() → None¶: Ngắt kết nối hiện tại (hiện tại là no-op stub trong bản dựng này).

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

Chỉ vai trò central. Kết nối với peer tại địa chỉ đã cho và đồng bộ khám phá các dịch vụ và đặc tính chính của nó. Chặn cho đến khi kết nối được thiết lập và khám phá hoàn tất; các dịch vụ đã khám phá sau đó có thể truy cập qua getServices().

addr: Địa chỉ peer dưới dạng chuỗi 17 ký tự "xx:xx:xx:xx:xx:xx" (ví dụ lấy từ ScanEntry.addr()).
addr_type (keyword-only): Là constants.ADDR_TYPE_PUBLIC (mặc định) hoặc constants.ADDR_TYPE_RANDOM_STATIC.

class ubluepy.Scanner¶

GAP observer để khám phá các thiết bị quảng bá gần đó. Chỉ khả dụng khi firmware được xây dựng với SoftDevice hỗ trợ central (s132 / s140).

scan(timeout: int) → list¶: Chạy quét thụ động trong timeout mili giây và trả về danh sách các thực thể ScanEntry --- một thực thể cho mỗi báo cáo quảng cáo nhận được trong cửa sổ.

class ubluepy.ScanEntry¶

Một báo cáo quảng cáo đơn lẻ được chụp bởi Scanner.scan(). Các thực thể được trả về từ scanner --- không có constructor công khai.

addr() → str¶: Trả về địa chỉ peer dưới dạng chuỗi 17 ký tự "xx:xx:xx:xx:xx:xx".

addr_type() → int¶: Trả về loại địa chỉ peer (constants.ADDR_TYPE_PUBLIC hoặc constants.ADDR_TYPE_RANDOM_STATIC).

rssi() → int¶: Trả về chỉ số cường độ tín hiệu tính bằng dBm.

getScanData() → list¶: Giải mã tải trọng quảng cáo thành danh sách các tuple (ad_type, description, value). ad_type là byte loại AD số (xem constants.ad_types), description là tên hằng số khớp dưới dạng chuỗi (hoặc None nếu loại không xác định), và value là nội dung bản ghi AD dưới dạng bytearray.

class ubluepy.DefaultDelegate¶

Lớp cơ sở cho các đối tượng được truyền vào Peripheral.withDelegate(). Tạo lớp con và ghi đè handleConnection() / handleNotification() để phản ứng với các sự kiện GATT.

handleConnection() → None¶: Được gọi trên các sự kiện GAP connect / disconnect. Cài đặt mặc định là rỗng.

handleNotification() → None¶: Được gọi trên các thông báo GATT đến. Cài đặt mặc định là rỗng.

Hằng số¶

Thuộc tính constants của mô-đun là một không gian tên chứa các định danh sự kiện GAP/GATT, giá trị loại địa chỉ, và không gian tên ad_types lồng nhau.

ubluepy.constants: type¶: Container hiển thị các hằng số bên dưới.

constants.EVT_GAP_CONNECTED: int¶: Giá trị event_id của bộ xử lý kết nối Peripheral cho GAP connect (16).

constants.EVT_GAP_DISCONNECTED: int¶: Giá trị event_id của bộ xử lý kết nối Peripheral cho GAP disconnect (17).

constants.EVT_GATTS_WRITE: int¶: Giá trị event_id của bộ xử lý kết nối Peripheral cho lần ghi vào thuộc tính GATT cục bộ, bao gồm ghi vào CCCD để bật/tắt thông báo (80).

constants.UUID_CCCD: int¶: UUID Bluetooth chuẩn cho Client Characteristic Configuration Descriptor (0x2902).

constants.ADDR_TYPE_PUBLIC: int¶: Địa chỉ Thiết bị Bluetooth Công khai (0).

constants.ADDR_TYPE_RANDOM_STATIC: int¶: Địa chỉ Thiết bị Bluetooth ngẫu nhiên tĩnh (1).

constants.ad_types: type¶

Không gian tên của các hằng số loại AD quảng bá từ Bluetooth Core Specification Supplement. Mỗi tên ánh xạ đến loại AD 1 byte tương ứng:

Tên	Giá trị
`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 peripheral và central¶