bluetooth --- Bluetooth tingkat rendah

Modul ini menyediakan antarmuka ke kontroler Bluetooth yang terpasang. Modul ini mendukung Bluetooth Low Energy (BLE) dalam peran Central, Peripheral, Broadcaster, dan Observer, serta GATT Server dan Client serta kanal berorientasi koneksi L2CAP. Sebuah perangkat dapat beroperasi dalam beberapa peran secara bersamaan. Pairing dan bonding juga didukung.

API ini dimaksudkan untuk mengikuti protokol Bluetooth tingkat rendah dan menyediakan blok pembangun untuk abstraksi tingkat yang lebih tinggi seperti jenis perangkat tertentu.

Tip

Untuk sebagian besar aplikasi, lebih baik gunakan pustaka tingkat tinggi aioble, yang menyediakan pembungkus berbasis asyncio di sekitar modul ini. Lihat aioble --- Async BLE.

class BLE

class bluetooth.BLE

Mengembalikan objek BLE singleton.

Konfigurasi

active(active: bool | None = None, /) → bool

Secara opsional mengubah status aktif radio BLE, dan mengembalikan status saat ini.

Radio harus diaktifkan sebelum menggunakan metode lain pada kelas ini.

config(param: str, /) → Any

config(*, **kwargs: Any) → None

Mendapatkan atau mengatur nilai konfigurasi antarmuka BLE. Untuk mendapatkan nilai, nama parameter harus dikutip sebagai string, dan hanya satu parameter yang dapat dikueri pada satu waktu. Untuk mengatur nilai, gunakan sintaks kata kunci, dan satu atau lebih parameter dapat diatur sekaligus.

Nilai yang saat ini didukung adalah:

• 'mac': Alamat yang sedang digunakan saat ini, tergantung pada mode alamat yang aktif. Ini mengembalikan tuple berupa (addr_type, addr).

  Lihat gap_scan untuk detail tentang jenis alamat.

  Ini hanya dapat dikueri saat antarmuka sedang aktif.

• 'addr_mode': Mengatur mode alamat. Nilai-nilainya adalah:

  Nilai	Nama	Perilaku
  0x00	PUBLIC	Gunakan alamat publik kontroler.
  0x01	RANDOM	Gunakan alamat statis yang dihasilkan.
  0x02	RPA	Gunakan alamat privat yang dapat di-resolve.
  0x03	NRPA	Gunakan alamat privat yang tidak dapat di-resolve.

  Secara default, antarmuka akan menggunakan alamat PUBLIC jika tersedia, jika tidak akan menggunakan alamat RANDOM.

• 'gap_name': Mendapatkan/mengatur nama perangkat GAP yang digunakan oleh layanan Generic Access (UUID 0x1800), karakteristik Device Name (UUID 0x2a00). Ini dapat diatur kapan saja dan diubah berkali-kali.

• 'rxbuf': Mendapatkan/mengatur ukuran dalam byte dari buffer internal yang digunakan untuk menyimpan event yang masuk. Buffer ini bersifat global untuk seluruh driver BLE sehingga menangani data masuk untuk semua event, termasuk semua karakteristik. Meningkatkan ini memungkinkan penanganan data masuk yang bersifat burst dengan lebih baik (misalnya hasil scan) dan kemampuan untuk menerima nilai karakteristik yang lebih besar.

• 'mtu': Mendapatkan/mengatur MTU yang akan digunakan selama pertukaran ATT MTU. MTU yang dihasilkan akan menjadi nilai minimum antara ini dan MTU perangkat remote. Pertukaran ATT MTU tidak akan terjadi secara otomatis (kecuali perangkat remote yang memulainya), dan harus dimulai secara manual dengan gattc_exchange_mtu. Gunakan event _IRQ_MTU_EXCHANGED untuk mengetahui MTU untuk koneksi tertentu.

• 'bond': Mengatur apakah bonding akan diaktifkan selama pairing. Ketika diaktifkan, permintaan pairing akan mengatur flag "bond" dan kunci akan disimpan oleh kedua perangkat.

• 'mitm': Mengatur apakah perlindungan MITM diperlukan untuk pairing.

• 'io': Mengatur kemampuan I/O perangkat ini.

  Opsi yang tersedia adalah:

  Konstanta	Nilai	Kemampuan
  _IO_CAPABILITY_DISPLAY_ONLY	0	Hanya tampilan
  _IO_CAPABILITY_DISPLAY_YESNO	1	Tampilan dengan input ya/tidak
  _IO_CAPABILITY_KEYBOARD_ONLY	2	Hanya keyboard
  _IO_CAPABILITY_NO_INPUT_OUTPUT	3	Tanpa input atau output
  _IO_CAPABILITY_KEYBOARD_DISPLAY	4	Keyboard dan tampilan

• 'le_secure': Mengatur apakah pairing "LE Secure" diperlukan. Defaultnya adalah false (yaitu mengizinkan "Legacy Pairing").

Penanganan Event

irq(handler: Callable[[int, Tuple], Any | None], /) → None

Mendaftarkan callback untuk event dari stack BLE. handler mengambil dua argumen, event (yang akan menjadi salah satu kode di bawah) dan data (yang merupakan tuple nilai spesifik event).

Catatan: Sebagai optimisasi untuk mencegah alokasi yang tidak perlu, entri addr, adv_data, char_data, notify_data, dan uuid dalam tuple adalah instance memoryview hanya-baca yang menunjuk ke ringbuffer internal bluetooth, dan hanya valid selama pemanggilan fungsi handler IRQ. Jika program Anda perlu menyimpan salah satu nilai ini untuk diakses setelah handler IRQ kembali (misalnya dengan menyimpannya dalam instance kelas atau variabel global), maka perlu membuat salinan data, baik dengan menggunakan bytes() atau bluetooth.UUID(), seperti ini:

connected_addr = bytes(addr)  # equivalently: adv_data, char_data, or notify_data
matched_uuid = bluetooth.UUID(uuid)

Misalnya, handler IRQ untuk hasil scan mungkin memeriksa adv_data untuk memutuskan apakah itu perangkat yang tepat, dan baru kemudian menyalin data alamat untuk digunakan di tempat lain dalam program. Dan untuk mencetak data dari dalam handler IRQ, print(bytes(addr)) akan diperlukan.

Handler biasanya men-dispatch pada kode event dan membongkar tuple payload spesifik event:

def bt_irq(event, data):
    if event == _IRQ_CENTRAL_CONNECT:
        conn_handle, addr_type, addr = data
        ...
    elif event == _IRQ_SCAN_RESULT:
        addr_type, addr, adv_type, rssi, adv_data = data
        ...

Setiap kode event, payload yang dikirimkannya, dan deskripsi singkat tercantum di bawah ini. Untuk event yang field status-nya disebutkan, status adalah 0 pada keberhasilan dan nilai non-nol spesifik implementasi pada kegagalan.

Konstanta	Nilai	Event	Tuple payload
_IRQ_CENTRAL_CONNECT	1	Sebuah central telah terhubung ke peripheral ini.	(conn_handle, addr_type, addr)
_IRQ_CENTRAL_DISCONNECT	2	Sebuah central telah terputus dari peripheral ini.	(conn_handle, addr_type, addr)
_IRQ_GATTS_WRITE	3	Klien yang terhubung telah menulis ke karakteristik atau deskriptor lokal. Gunakan gatts_read untuk mengambil nilai baru.	(conn_handle, attr_handle)
_IRQ_GATTS_READ_REQUEST	4	Klien yang terhubung telah mengeluarkan permintaan baca. Kembalikan kode error non-nol dari tabel di bawah untuk menolak baca, atau 0 / None untuk menerimanya.	(conn_handle, attr_handle)
_IRQ_SCAN_RESULT	5	Satu paket iklan diterima selama scan aktif.	(addr_type, addr, adv_type, rssi, adv_data)
_IRQ_SCAN_DONE	6	Scan saat ini telah berakhir, baik karena durasi yang dikonfigurasi telah berlalu atau karena gap_scan(None) dipanggil.	()
_IRQ_PERIPHERAL_CONNECT	7	Sebuah gap_connect yang sebelumnya diterbitkan telah berhasil.	(conn_handle, addr_type, addr)
_IRQ_PERIPHERAL_DISCONNECT	8	Sebuah peripheral yang terhubung telah terputus.	(conn_handle, addr_type, addr)
_IRQ_GATTC_SERVICE_RESULT	9	Satu layanan ditemukan oleh gattc_discover_services.	(conn_handle, start_handle, end_handle, uuid)
_IRQ_GATTC_SERVICE_DONE	10	Penemuan layanan telah selesai.	(conn_handle, status)
_IRQ_GATTC_CHARACTERISTIC_RESULT	11	Satu karakteristik ditemukan oleh gattc_discover_characteristics.	(conn_handle, end_handle, value_handle, properties, uuid)
_IRQ_GATTC_CHARACTERISTIC_DONE	12	Penemuan karakteristik telah selesai.	(conn_handle, status)
_IRQ_GATTC_DESCRIPTOR_RESULT	13	Satu deskriptor ditemukan oleh gattc_discover_descriptors.	(conn_handle, dsc_handle, uuid)
_IRQ_GATTC_DESCRIPTOR_DONE	14	Penemuan deskriptor telah selesai.	(conn_handle, status)
_IRQ_GATTC_READ_RESULT	15	Sebuah gattc_read yang sebelumnya diterbitkan telah mengembalikan data.	(conn_handle, value_handle, char_data)
_IRQ_GATTC_READ_DONE	16	Sebuah gattc_read yang sebelumnya diterbitkan telah selesai.	(conn_handle, value_handle, status)
_IRQ_GATTC_WRITE_DONE	17	Sebuah gattc_write yang sebelumnya diterbitkan telah diakui.	(conn_handle, value_handle, status)
_IRQ_GATTC_NOTIFY	18	Server remote telah mengirim notifikasi (tanpa pengakuan).	(conn_handle, value_handle, notify_data)
_IRQ_GATTC_INDICATE	19	Server remote telah mengirim indikasi (dengan pengakuan).	(conn_handle, value_handle, notify_data)
_IRQ_GATTS_INDICATE_DONE	20	Sebuah indikasi yang sebelumnya dikirim telah diakui oleh klien (atau telah habis waktu).	(conn_handle, value_handle, status)
_IRQ_MTU_EXCHANGED	21	Pertukaran ATT MTU telah selesai (dimulai oleh salah satu pihak).	(conn_handle, mtu)
_IRQ_L2CAP_ACCEPT	22	Perangkat remote telah meminta koneksi L2CAP pada PSM yang sedang didengarkan perangkat ini. Kembalikan bilangan bulat non-nol untuk menolak, atau 0 / None untuk menerima.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_CONNECT	23	Kanal L2CAP sekarang telah terbentuk, baik dengan menerima permintaan masuk atau dengan menyelesaikan l2cap_connect keluar.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_DISCONNECT	24	Kanal L2CAP telah terputus. status adalah 0 untuk pemutusan yang bersih, atau non-nol jika upaya koneksi keluar gagal.	(conn_handle, cid, psm, status)
_IRQ_L2CAP_RECV	25	Data telah tiba di kanal L2CAP. Panggil l2cap_recvinto untuk membacanya.	(conn_handle, cid)
_IRQ_L2CAP_SEND_READY	26	Sebuah l2cap_send sebelumnya yang mengembalikan False telah dikuras dan kanal siap kembali. Status non-nol status berarti buffer pengiriman meluap dan aplikasi harus mengirim ulang data.	(conn_handle, cid, status)
_IRQ_CONNECTION_UPDATE	27	Perangkat remote telah memperbarui parameter koneksi (interval, latensi, supervision timeout).	(conn_handle, conn_interval, conn_latency, supervision_timeout, status)
_IRQ_ENCRYPTION_UPDATE	28	Status enkripsi koneksi telah berubah, biasanya setelah pairing atau bonding selesai.	(conn_handle, encrypted, authenticated, bonded, key_size)
_IRQ_GET_SECRET	29	Stack sedang meminta rahasia bonding yang tersimpan. Jika key adalah None, kembalikan nilai tersimpan ke-indexdari sec_type; jika tidak kembalikan nilai yang terkait dengan (sec_type, key) yang diberikan. Kembalikan None jika tidak ada yang tersimpan.	(sec_type, index, key)
_IRQ_SET_SECRET	30	Stack meminta aplikasi untuk menyimpan rahasia bonding. Kembalikan True setelah tersimpan.	(sec_type, key, value)
_IRQ_PASSKEY_ACTION	31	Tindakan passkey diperlukan sebagai bagian dari pairing. Tanggapi menggunakan gap_passkey; lihat tabel passkey-action di bawah untuk tindakan yang mungkin.	(conn_handle, action, passkey)

Untuk event _IRQ_GATTS_READ_REQUEST, kode kembalian yang tersedia adalah:

Konstanta	Nilai	Makna
_GATTS_NO_ERROR	0x00	Terima baca.
_GATTS_ERROR_READ_NOT_PERMITTED	0x02	Baca tidak diizinkan.
_GATTS_ERROR_WRITE_NOT_PERMITTED	0x03	Tulis tidak diizinkan.
_GATTS_ERROR_INSUFFICIENT_AUTHENTICATION	0x05	Klien tidak terautentikasi.
_GATTS_ERROR_INSUFFICIENT_AUTHORIZATION	0x08	Klien tidak terautorisasi.
_GATTS_ERROR_INSUFFICIENT_ENCRYPTION	0x0f	Tautan tidak terenkripsi.

Untuk event _IRQ_PASSKEY_ACTION, tindakan yang tersedia adalah:

Konstanta	Nilai	Makna
_PASSKEY_ACTION_NONE	0	Tidak ada tindakan yang diperlukan.
_PASSKEY_ACTION_INPUT	2	Minta pengguna untuk memasukkan passkey yang ditampilkan di perangkat remote.
_PASSKEY_ACTION_DISPLAY	3	Tampilkan passkey 6 digit untuk dimasukkan oleh perangkat remote.
_PASSKEY_ACTION_NUMERIC_COMPARISON	4	Konfirmasikan bahwa passkey cocok dengan yang ditampilkan di perangkat remote.

Untuk menghemat ruang dalam firmware, konstanta-konstanta ini tidak disertakan dalam modul bluetooth. Tambahkan yang Anda butuhkan dari daftar di atas ke program Anda.

Peran Broadcaster (Pengiklan)

gap_advertise(interval_us: int | None, adv_data: bytes | None = None, *, resp_data: bytes | None = None, connectable: bool = True) → None

Memulai pengiklanan pada interval yang ditentukan (dalam mikrodetik). Interval ini akan dibulatkan ke bawah ke kelipatan 625us terdekat. Untuk menghentikan pengiklanan, atur interval_us ke None.

adv_data dan resp_data dapat berupa jenis apa pun yang mengimplementasikan protokol buffer (misalnya bytes, bytearray, str). adv_data disertakan dalam semua siaran, dan resp_data dikirim sebagai balasan terhadap scan aktif.

Catatan: jika adv_data (atau resp_data) adalah None, maka data yang diteruskan ke panggilan sebelumnya ke gap_advertise akan digunakan kembali. Hal ini memungkinkan broadcaster untuk melanjutkan pengiklanan hanya dengan gap_advertise(interval_us). Untuk menghapus payload pengiklanan, berikan bytes kosong, yaitu b''.

Peran Observer (Scanner)

gap_scan(duration_ms: int | None, interval_us: int = 1280000, window_us: int = 11250, active: bool = False, /) → None

Jalankan operasi scan yang berlangsung selama durasi yang ditentukan (dalam milidetik).

Untuk scan tanpa batas, atur duration_ms ke 0.

Untuk menghentikan scanning, atur duration_ms ke None.

Gunakan interval_us dan window_us untuk mengonfigurasi siklus kerja secara opsional. Scanner akan berjalan selama window_us mikrodetik setiap interval_us mikrodetik selama total duration_ms milidetik. Interval dan jendela default masing-masing adalah 1,28 detik dan 11,25 milidetik (scanning latar belakang).

Untuk setiap hasil scan, event _IRQ_SCAN_RESULT akan dimunculkan, dengan data event (addr_type, addr, adv_type, rssi, adv_data).

Nilai addr_type menunjukkan alamat publik atau acak:

Nilai	Nama	Makna
0x00	PUBLIC	Alamat perangkat publik.
0x01	RANDOM	Alamat acak (baik statis, RPA, atau NRPA; jenisnya dikodekan dalam alamat itu sendiri).

Nilai adv_type sesuai dengan Spesifikasi Bluetooth:

Nilai	Nama	Makna
0x00	ADV_IND	Pengiklanan undirected yang dapat dihubungkan dan dapat di-scan.
0x01	ADV_DIRECT_IND	Pengiklanan directed yang dapat dihubungkan.
0x02	ADV_SCAN_IND	Pengiklanan undirected yang dapat di-scan.
0x03	ADV_NONCONN_IND	Pengiklanan undirected yang tidak dapat dihubungkan.
0x04	SCAN_RSP	Respons scan.

active dapat diatur ke True jika Anda ingin menerima respons scan dalam hasil.

Ketika scanning dihentikan (baik karena durasi selesai atau ketika dihentikan secara eksplisit), event _IRQ_SCAN_DONE akan dimunculkan.

Peran Central

Perangkat central dapat terhubung ke peripheral yang telah ditemukannya menggunakan peran observer (lihat gap_scan) atau dengan alamat yang diketahui.

gap_connect(addr_type: int | None, addr: bytes | None = None, scan_duration_ms: int = 2000, min_conn_interval_us: int | None = None, max_conn_interval_us: int | None = None, /) → None

Terhubung ke peripheral.

Lihat gap_scan untuk detail tentang jenis alamat.

Untuk membatalkan upaya koneksi yang sedang berjalan lebih awal, panggil gap_connect(None).

Pada keberhasilan, event _IRQ_PERIPHERAL_CONNECT akan dimunculkan. Jika membatalkan upaya koneksi, event _IRQ_PERIPHERAL_DISCONNECT akan dimunculkan.

Perangkat akan menunggu hingga scan_duration_ms untuk menerima payload pengiklanan dari perangkat.

Interval koneksi dapat dikonfigurasi dalam mikrodetik menggunakan salah satu atau keduanya dari min_conn_interval_us dan max_conn_interval_us. Jika tidak, interval default akan dipilih, biasanya antara 30000 dan 50000 mikrodetik. Interval yang lebih pendek akan meningkatkan throughput, dengan mengorbankan penggunaan daya.

Peran Peripheral

Perangkat peripheral diharapkan mengirim iklan yang dapat dihubungkan (lihat gap_advertise). Biasanya akan bertindak sebagai server GATT, setelah terlebih dahulu mendaftarkan layanan dan karakteristik menggunakan gatts_register_services.

Ketika central terhubung, event _IRQ_CENTRAL_CONNECT akan dimunculkan.

Peran Central & Peripheral

gap_disconnect(conn_handle: int, /) → bool

Putuskan handle koneksi yang ditentukan. Ini bisa berupa central yang telah terhubung ke perangkat ini (jika bertindak sebagai peripheral) atau peripheral yang sebelumnya terhubung ke perangkat ini (jika bertindak sebagai central).

Pada keberhasilan, event _IRQ_PERIPHERAL_DISCONNECT atau _IRQ_CENTRAL_DISCONNECT akan dimunculkan.

Mengembalikan False jika handle koneksi tidak terhubung, dan True jika sebaliknya.

GATT Server

Server GATT memiliki sekumpulan layanan yang terdaftar. Setiap layanan dapat berisi karakteristik, yang masing-masing memiliki nilai. Karakteristik juga dapat berisi deskriptor, yang sendirinya memiliki nilai.

Nilai-nilai ini disimpan secara lokal, dan diakses melalui "value handle" yang dihasilkan selama pendaftaran layanan. Mereka juga dapat dibaca dari atau ditulis oleh perangkat klien remote. Selain itu, server dapat "memberitahu" karakteristik ke klien yang terhubung melalui handle koneksi.

Perangkat dalam peran central atau peripheral dapat berfungsi sebagai server GATT, namun dalam kebanyakan kasus lebih umum bagi perangkat peripheral untuk bertindak sebagai server.

Karakteristik dan deskriptor memiliki ukuran maksimum default 20 byte (ATT MTU default 23 byte dikurangi header ATT 3 byte; MTU yang dinegosiasikan lebih besar tidak dengan sendirinya meningkatkan batas ini). Apa pun yang ditulis ke mereka oleh klien akan dipotong hingga panjang ini. Namun, penulisan lokal apa pun akan meningkatkan ukuran maksimum, jadi jika Anda ingin mengizinkan penulisan yang lebih besar dari klien ke karakteristik tertentu, gunakan gatts_write setelah pendaftaran. misalnya gatts_write(char_handle, bytes(100)).

gatts_register_services(services_definition: Sequence[Sequence], /) → Sequence[Sequence[int]]

Mengonfigurasi server dengan layanan yang ditentukan, menggantikan layanan yang ada.

services_definition adalah daftar layanan, di mana setiap layanan adalah tuple dua elemen yang berisi UUID dan daftar karakteristik.

Setiap karakteristik adalah tuple dua atau tiga elemen yang berisi UUID, nilai flags, dan secara opsional daftar deskriptor.

Setiap deskriptor adalah tuple dua elemen yang berisi UUID dan nilai flags.

flags adalah kombinasi bitwise-OR dari flag yang didefinisikan di bawah ini. Ini mengatur perilaku karakteristik (atau deskriptor) serta persyaratan keamanan dan privasi.

Nilai kembalian adalah daftar (satu elemen per layanan) dari tuple (setiap elemen adalah value handle). Handle karakteristik dan deskriptor diratakan ke dalam tuple yang sama, dalam urutan yang didefinisikan.

Contoh berikut mendaftarkan dua layanan (Heart Rate, dan Nordic UART):

bt = bluetooth.BLE()
bt.active(True)

# Heart Rate service: one Heart Rate Measurement characteristic.
HR_SERVICE = (
    bluetooth.UUID(0x180D),
    (
        (bluetooth.UUID(0x2A37),
         bluetooth.FLAG_READ | bluetooth.FLAG_NOTIFY),
    ),
)

# Nordic UART service: a TX characteristic the client subscribes
# to for notifications, and an RX characteristic it writes to.
UART_SERVICE = (
    bluetooth.UUID('6E400001-B5A3-F393-E0A9-E50E24DCCA9E'),
    (
        (bluetooth.UUID('6E400003-B5A3-F393-E0A9-E50E24DCCA9E'),
         bluetooth.FLAG_READ | bluetooth.FLAG_NOTIFY),
        (bluetooth.UUID('6E400002-B5A3-F393-E0A9-E50E24DCCA9E'),
         bluetooth.FLAG_WRITE),
    ),
)

((hr,), (tx, rx)) = bt.gatts_register_services(
    (HR_SERVICE, UART_SERVICE),
)

Tiga value handle (hr, tx, rx) dapat digunakan dengan gatts_read, gatts_write, gatts_notify, dan gatts_indicate.

Catatan: Pengiklanan harus dihentikan sebelum mendaftarkan layanan.

Flag yang tersedia untuk karakteristik dan deskriptor adalah:

Konstanta	Nilai	Makna
_FLAG_BROADCAST	0x0001	Karakteristik dapat di-broadcast.
_FLAG_READ	0x0002	Klien dapat membaca nilai.
_FLAG_WRITE_NO_RESPONSE	0x0004	Klien dapat menulis tanpa mengharapkan respons.
_FLAG_WRITE	0x0008	Klien dapat menulis dengan respons yang diakui.
_FLAG_NOTIFY	0x0010	Server dapat mengirim notifikasi (tanpa pengakuan).
_FLAG_INDICATE	0x0020	Server dapat mengirim indikasi (dengan pengakuan).
_FLAG_AUTHENTICATED_SIGNED_WRITE	0x0040	Klien dapat mengeluarkan penulisan bertanda tangan.
_FLAG_AUX_WRITE	0x0100	Properti tambahan: penulisan antrian/andal diizinkan.
_FLAG_READ_ENCRYPTED	0x0200	Baca memerlukan tautan terenkripsi.
_FLAG_READ_AUTHENTICATED	0x0400	Baca memerlukan tautan yang terautentikasi (dilindungi MITM).
_FLAG_READ_AUTHORIZED	0x0800	Baca memerlukan otorisasi tingkat aplikasi.
_FLAG_WRITE_ENCRYPTED	0x1000	Tulis memerlukan tautan terenkripsi.
_FLAG_WRITE_AUTHENTICATED	0x2000	Tulis memerlukan tautan yang terautentikasi (dilindungi MITM).
_FLAG_WRITE_AUTHORIZED	0x4000	Tulis memerlukan otorisasi tingkat aplikasi.

Seperti konstanta event di atas, flag ini tidak disediakan oleh modul bluetooth; salin yang Anda butuhkan ke dalam program Anda.

gatts_read(value_handle: int, /) → bytes

Membaca nilai lokal untuk handle ini (yang telah ditulis oleh gatts_write atau oleh klien remote).

gatts_write(value_handle: int, data: bytes, send_update: bool = False, /) → None

Menulis nilai lokal untuk handle ini, yang dapat dibaca oleh klien.

Jika send_update adalah True, maka klien yang berlangganan akan diberitahu (atau diindikasikan, tergantung pada apa yang mereka langgani dan operasi mana yang didukung karakteristik) tentang penulisan ini.

gatts_notify(conn_handle: int, value_handle: int, data: bytes | None = None, /) → None

Mengirim permintaan notifikasi ke klien yang terhubung.

Jika data adalah None (default), maka nilai lokal saat ini (sebagaimana diatur dengan gatts_write) akan dikirim.

Jika tidak, jika data bukan None, maka nilai tersebut dikirim ke klien sebagai bagian dari notifikasi. Nilai lokal tidak akan dimodifikasi.

Catatan: Notifikasi akan dikirim terlepas dari status langganan klien terhadap karakteristik ini.

gatts_indicate(conn_handle: int, value_handle: int, data: bytes | None = None, /) → None

Mengirim permintaan indikasi ke klien yang terhubung.

Jika data adalah None (default), maka nilai lokal saat ini (sebagaimana diatur dengan gatts_write) akan dikirim.

Jika tidak, jika data bukan None, maka nilai tersebut dikirim ke klien sebagai bagian dari indikasi. Nilai lokal tidak akan dimodifikasi.

Saat pengakuan (atau kegagalan, misalnya timeout), event _IRQ_GATTS_INDICATE_DONE akan dimunculkan.

Catatan: Indikasi akan dikirim terlepas dari status langganan klien terhadap karakteristik ini.

gatts_set_buffer(value_handle: int, len: int, append: bool = False, /) → None

Mengatur ukuran buffer internal untuk nilai dalam byte. Ini akan membatasi kemungkinan penulisan terbesar yang dapat diterima. Defaultnya adalah 20 byte (ATT MTU default 23 dikurangi header ATT 3 byte).

Mengatur append ke True akan membuat semua penulisan remote ditambahkan ke, bukan menggantikan, nilai saat ini. Paling banyak len byte dapat di-buffer dengan cara ini. Ketika Anda menggunakan gatts_read, nilai akan dihapus setelah dibaca. Fitur ini berguna saat mengimplementasikan sesuatu seperti Nordic UART Service.

GATT Client

Klien GATT dapat menemukan dan membaca/menulis karakteristik di server GATT remote.

Lebih umum bagi perangkat peran central untuk bertindak sebagai klien GATT, namun peripheral juga dapat bertindak sebagai klien untuk menemukan informasi tentang central yang telah terhubung ke sana (misalnya untuk membaca nama perangkat dari layanan informasi perangkat).

gattc_discover_services(conn_handle: int, uuid: UUID | None = None, /) → None

Kueri server yang terhubung untuk layanannya.

Secara opsional tentukan uuid layanan untuk hanya mengkueri layanan tersebut.

Untuk setiap layanan yang ditemukan, event _IRQ_GATTC_SERVICE_RESULT akan dimunculkan, diikuti oleh _IRQ_GATTC_SERVICE_DONE saat selesai.

gattc_discover_characteristics(conn_handle: int, start_handle: int, end_handle: int, uuid: UUID | None = None, /) → None

Kueri server yang terhubung untuk karakteristik dalam rentang yang ditentukan.

Secara opsional tentukan uuid karakteristik untuk hanya mengkueri karakteristik tersebut.

Meneruskan start_handle=1 dan end_handle=0xffff mencakup rentang handle atribut GATT penuh, sehingga kombinasi ini secara efektif mencari setiap layanan di perangkat remote.

Untuk setiap karakteristik yang ditemukan, event _IRQ_GATTC_CHARACTERISTIC_RESULT akan dimunculkan, diikuti oleh _IRQ_GATTC_CHARACTERISTIC_DONE saat selesai.

gattc_discover_descriptors(conn_handle: int, start_handle: int, end_handle: int, /) → None

Kueri server yang terhubung untuk deskriptor dalam rentang yang ditentukan.

Untuk setiap deskriptor yang ditemukan, event _IRQ_GATTC_DESCRIPTOR_RESULT akan dimunculkan, diikuti oleh _IRQ_GATTC_DESCRIPTOR_DONE saat selesai.

gattc_read(conn_handle: int, value_handle: int, /) → None

Keluarkan baca remote ke server yang terhubung untuk handle karakteristik atau deskriptor yang ditentukan.

Ketika nilai tersedia, event _IRQ_GATTC_READ_RESULT akan dimunculkan, diikuti oleh _IRQ_GATTC_READ_DONE saat selesai.

gattc_write(conn_handle: int, value_handle: int, data: bytes, mode: int = 0, /) → None

Keluarkan penulisan remote ke server yang terhubung untuk handle karakteristik atau deskriptor yang ditentukan.

Argumen mode menentukan perilaku penulisan, dengan nilai yang saat ini didukung adalah:

• mode=0 (default) adalah write-without-response: penulisan akan dikirim ke server remote tetapi tidak ada konfirmasi yang akan dikembalikan, dan tidak ada event yang akan dimunculkan.

• mode=1 adalah write-with-response: server remote diminta untuk mengirim respons/pengakuan bahwa ia menerima data.

Jika respons diterima dari server remote, event _IRQ_GATTC_WRITE_DONE akan dimunculkan.

gattc_exchange_mtu(conn_handle: int, /) → None

Inisiasi pertukaran MTU dengan server yang terhubung, menggunakan MTU yang disukai yang diatur menggunakan BLE.config(mtu=value).

Event _IRQ_MTU_EXCHANGED akan dimunculkan ketika pertukaran MTU selesai.

Pertukaran MTU biasanya dimulai oleh central; NimBLE mendukung kedua peran.

Kanal Berorientasi Koneksi L2CAP

Fitur ini memungkinkan pertukaran data seperti socket antara dua perangkat BLE. Setelah perangkat terhubung melalui GAP, salah satu perangkat dapat mendengarkan perangkat lain untuk terhubung pada PSM (Protocol/Service Multiplexer) numerik.

Hanya satu kanal L2CAP yang dapat aktif pada waktu tertentu (yaitu Anda tidak dapat terhubung saat mendengarkan).

Kanal L2CAP aktif diidentifikasi oleh handle koneksi tempat mereka dibentuk dan CID (channel ID).

Kanal berorientasi koneksi memiliki kontrol aliran berbasis kredit bawaan. Tidak seperti ATT, di mana perangkat menegosiasikan MTU bersama, perangkat yang mendengarkan dan terhubung masing-masing mengatur MTU independen yang membatasi jumlah maksimum data yang belum diproses yang dapat dikirim oleh perangkat remote sebelum sepenuhnya dikonsumsi dalam l2cap_recvinto.

l2cap_listen(psm: int, mtu: int, /) → None

Mulai mendengarkan permintaan kanal L2CAP yang masuk pada psm yang ditentukan dengan MTU lokal diatur ke mtu.

Ketika perangkat remote memulai koneksi, event _IRQ_L2CAP_ACCEPT akan dimunculkan, yang memberi server yang mendengarkan kesempatan untuk menolak koneksi yang masuk (dengan mengembalikan bilangan bulat non-nol).

Setelah koneksi diterima, event _IRQ_L2CAP_CONNECT akan dimunculkan, memungkinkan server untuk mendapatkan ID kanal (CID) serta MTU lokal dan remote.

Catatan: Saat ini tidak memungkinkan untuk menghentikan pendengar.

l2cap_connect(conn_handle: int, psm: int, mtu: int, /) → None

Terhubung ke peer yang mendengarkan pada psm yang ditentukan dengan MTU lokal diatur ke mtu.

Saat koneksi berhasil, event _IRQ_L2CAP_CONNECT akan dimunculkan, memungkinkan klien mendapatkan CID serta MTU lokal dan remote (peer).

Koneksi yang tidak berhasil akan memunculkan event _IRQ_L2CAP_DISCONNECT dengan status non-nol.

l2cap_disconnect(conn_handle: int, cid: int, /) → None

Putuskan kanal L2CAP aktif dengan conn_handle dan cid yang ditentukan.

l2cap_send(conn_handle: int, cid: int, buf: bytes, /) → bool

Kirim buf yang ditentukan (yang harus mendukung protokol buffer) pada kanal L2CAP yang diidentifikasi oleh conn_handle dan cid.

Buffer harus memenuhi kedua batas: tidak boleh melebihi MTU remote (peer), dan tidak boleh melebihi dua kali MTU lokal.

Ini akan mengembalikan False jika kanal sekarang "terhenti", yang berarti l2cap_send tidak boleh dipanggil lagi sampai event _IRQ_L2CAP_SEND_READY diterima (yang akan terjadi ketika perangkat remote memberikan lebih banyak kredit, biasanya setelah menerima dan memproses data).

l2cap_recvinto(conn_handle: int, cid: int, buf: Any | None, /) → int

Terima data dari conn_handle dan cid yang ditentukan ke dalam buf yang disediakan (yang harus mendukung protokol buffer, misalnya bytearray atau memoryview).

Mengembalikan jumlah byte yang dibaca dari kanal.

Jika buf adalah None, maka mengembalikan jumlah byte yang tersedia.

Catatan: Setelah menerima event _IRQ_L2CAP_RECV, aplikasi harus terus memanggil l2cap_recvinto sampai tidak ada lagi byte yang tersedia dalam buffer penerimaan (biasanya hingga ukuran MTU remote (peer)).

Sampai buffer penerimaan kosong, perangkat remote tidak akan diberikan lebih banyak kredit kanal dan tidak akan dapat mengirim data lebih lanjut.

Pairing dan Bonding

Pairing memungkinkan koneksi dienkripsi dan diautentikasi melalui pertukaran rahasia (dengan perlindungan MITM opsional melalui autentikasi passkey).

Bonding adalah proses menyimpan rahasia-rahasia tersebut ke penyimpanan non-volatil. Ketika melakukan bonding, perangkat mampu me-resolve alamat privat yang dapat di-resolve (RPA) dari perangkat lain berdasarkan kunci resolving identitas (IRK) yang tersimpan. Untuk mendukung bonding, aplikasi harus mengimplementasikan event _IRQ_GET_SECRET dan _IRQ_SET_SECRET.

gap_pair(conn_handle: int, /) → None

Inisiasi pairing dengan perangkat remote.

Sebelum memanggil ini, pastikan bahwa opsi konfigurasi io, mitm, le_secure, dan bond telah diatur (melalui config).

Saat pairing berhasil, event _IRQ_ENCRYPTION_UPDATE akan dimunculkan.

gap_passkey(conn_handle: int, action: int, passkey: int, /) → None

Tanggapi event _IRQ_PASSKEY_ACTION untuk conn_handle dan action yang ditentukan. Makna dari passkey tergantung pada action (yang pada gilirannya tergantung pada kemampuan I/O yang dikonfigurasi):

Tindakan	Respons passkey yang diperlukan
_PASSKEY_ACTION_INPUT	Passkey yang dibaca pengguna dari perangkat remote.
_PASSKEY_ACTION_DISPLAY	Passkey 6 digit acak yang dihasilkan secara lokal ditampilkan kepada pengguna.
_PASSKEY_ACTION_NUMERIC_COMPARISON	1 untuk menerima passkey yang ditampilkan dalam event _IRQ_PASSKEY_ACTION, atau 0 untuk membatalkan pairing.

class UUID

class bluetooth.UUID(value: int | bytes | str, /)

Membuat instance UUID dengan value yang ditentukan. Bluetooth menggunakan tiga lebar UUID; UUID menerima ketiganya:

Lebar UUID	Jenis value yang diterima	Contoh
16-bit	int atau buffer 2-byte (little-endian)	UUID(0x2908) atau UUID(b'\x08\x29')
32-bit	Buffer 4-byte (little-endian)	UUID(b'\x08\x29\x00\x00')
128-bit	Buffer 16-byte atau string dengan tanda hubung	UUID('6E400001-B5A3-F393-E0A9-E50E24DCCA9E')

UUID 16- dan 32-bit biasanya merupakan identifkator yang dialokasikan SIG (lihat nomor yang ditetapkan Bluetooth); UUID 128-bit biasanya didefinisikan oleh vendor.