bluetooth — düşük seviyeli Bluetooth

Bu modül, yerleşik Bluetooth denetleyicisine bir arayüz sağlar. Central, Peripheral, Broadcaster ve Observer rollerinde Bluetooth Low Energy (BLE) ile birlikte GATT Sunucusu ve İstemcisini ve L2CAP bağlantı yönelimli kanalları destekler. Bir cihaz aynı anda birden fazla rolde çalışabilir. Eşleştirme (pairing) ve bağlama (bonding) da desteklenir.

Bu API, düşük seviyeli Bluetooth protokolüyle eşleşecek ve belirli cihaz türleri gibi daha üst seviye soyutlamalar için yapı taşları sağlayacak şekilde tasarlanmıştır.

Tüyo

Çoğu uygulama için, bu modülün etrafında asyncio tabanlı bir sarmalayıcı sağlayan daha üst seviyeli aioble kütüphanesini tercih edin. Bkz. aioble — Asenkron BLE.

class BLE

class bluetooth.BLE

Tekil (singleton) BLE nesnesini döndürür.

Yapılandırma

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

İsteğe bağlı olarak BLE radyosunun etkin durumunu değiştirir ve mevcut durumu döndürür.

Bu sınıftaki diğer herhangi bir metodu kullanmadan önce radyo etkin hale getirilmelidir.

config(param: str, /) → Any

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

BLE arayüzünün yapılandırma değerlerini alır veya ayarlar. Bir değeri almak için parametre adı bir dize olarak tırnak içine alınmalıdır ve bir seferde yalnızca tek bir parametre sorgulanır. Değerleri ayarlamak için anahtar sözcük söz dizimini kullanın; bir seferde bir veya daha fazla parametre ayarlanabilir.

Şu anda desteklenen değerler şunlardır:

• 'mac': Mevcut adres moduna bağlı olarak, kullanımda olan geçerli adres. Bu, (addr_type, addr) biçiminde bir demet döndürür.

  Adres türü hakkında ayrıntılar için bkz. gap_scan.

  Bu, yalnızca arayüz şu anda etkinken sorgulanabilir.

• 'addr_mode': Adres modunu ayarlar. Değerler şunlardır:

  Değer	Ad	Davranış
  0x00	PUBLIC	Denetleyicinin genel (public) adresini kullan.
  0x01	RANDOM	Oluşturulmuş statik bir adres kullan.
  0x02	RPA	Çözümlenebilir özel adresler kullan.
  0x03	NRPA	Çözümlenemeyen özel adresler kullan.

  Varsayılan olarak arayüz, mevcutsa bir PUBLIC adres kullanır; aksi takdirde bir RANDOM adres kullanır.

• 'gap_name': Generic Access hizmeti (UUID 0x1800), Device Name özelliği (UUID 0x2a00) tarafından kullanılan GAP cihaz adını alır/ayarlar. Bu, herhangi bir zamanda ayarlanabilir ve birden çok kez değiştirilebilir.

• 'rxbuf': Gelen olayları depolamak için kullanılan dahili arabelleğin boyutunu bayt cinsinden alır/ayarlar. Bu arabellek tüm BLE sürücüsü için geneldir ve bu nedenle tüm özellikler dahil olmak üzere tüm olaylar için gelen verileri işler. Bunu artırmak, ani (bursty) gelen verilerin (örneğin tarama sonuçları) daha iyi işlenmesine ve daha büyük özellik değerlerinin alınabilmesine olanak tanır.

• 'mtu': Bir ATT MTU değişimi sırasında kullanılacak MTU’yu alır/ayarlar. Sonuçta elde edilen MTU, bunun ve uzak cihazın MTU’sunun en küçüğü olacaktır. ATT MTU değişimi otomatik olarak gerçekleşmez (uzak cihaz bunu başlatmadıkça) ve gattc_exchange_mtu ile manuel olarak başlatılmalıdır. Belirli bir bağlantı için MTU’yu öğrenmek üzere _IRQ_MTU_EXCHANGED olayını kullanın.

• 'bond': Eşleştirme sırasında bağlamanın etkinleştirilip etkinleştirilmeyeceğini ayarlar. Etkinleştirildiğinde, eşleştirme istekleri “bond” bayrağını ayarlar ve anahtarlar her iki cihaz tarafından da depolanır.

• 'mitm': Eşleştirme için MITM koruması gerekip gerekmediğini ayarlar.

• 'io': Bu cihazın G/Ç yeteneklerini ayarlar.

  Kullanılabilir seçenekler şunlardır:

  Sabit	Değer	Yetenek
  _IO_CAPABILITY_DISPLAY_ONLY	0	Yalnızca ekran
  _IO_CAPABILITY_DISPLAY_YESNO	1	Evet/hayır girişiyle ekran
  _IO_CAPABILITY_KEYBOARD_ONLY	2	Yalnızca klavye
  _IO_CAPABILITY_NO_INPUT_OUTPUT	3	Giriş veya çıkış yok
  _IO_CAPABILITY_KEYBOARD_DISPLAY	4	Klavye ve ekran

• 'le_secure': “LE Secure” eşleştirmesinin gerekip gerekmediğini ayarlar. Varsayılan değer false’tur (yani “Legacy Pairing”e izin verir).

Olay İşleme

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

BLE yığınından gelen olaylar için bir geri çağırma kaydeder. handler iki argüman alır: event (aşağıdaki kodlardan biri olacaktır) ve data (olaya özgü bir değer demetidir).

Not: Gereksiz ayırmaları önlemek için bir optimizasyon olarak, demetlerdeki addr, adv_data, char_data, notify_data ve uuid girdileri, bluetooth modülünün dahili halka arabelleğine işaret eden salt okunur memoryview örnekleridir ve yalnızca IRQ işleyici işlevinin çağrılması sırasında geçerlidir. Programınızın bu değerlerden birini IRQ işleyici döndükten sonra erişmek üzere kaydetmesi gerekiyorsa (örneğin bir sınıf örneğine veya genel değişkene kaydederek), o zaman verinin bir kopyasını alması gerekir; bunu bytes() veya bluetooth.UUID() kullanarak şu şekilde yapabilir:

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

Örneğin, bir tarama sonucu için IRQ işleyici, doğru cihaz olup olmadığına karar vermek için adv_data öğesini inceleyebilir ve yalnızca o zaman adres verisini programın başka bir yerinde kullanılmak üzere kopyalayabilir. IRQ işleyicinin içinden veri yazdırmak için print(bytes(addr)) gerekecektir.

Bir işleyici tipik olarak olay kodu üzerinden yönlendirme yapar ve olaya özgü yük demetini açar:

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

Her olay kodu, ilettiği yük ve kısa bir açıklama aşağıda listelenmiştir. status alanından bahsedilen olaylarda, status başarıda 0 olur ve başarısızlıkta uygulamaya özgü sıfır olmayan bir değer olur.

Sabit	Değer	Olay	Yük demeti
_IRQ_CENTRAL_CONNECT	1	Bir central, bu peripheral’a bağlandı.	(conn_handle, addr_type, addr)
_IRQ_CENTRAL_DISCONNECT	2	Bir central, bu peripheral’dan bağlantısını kesti.	(conn_handle, addr_type, addr)
_IRQ_GATTS_WRITE	3	Bağlı bir istemci, yerel bir özelliğe veya tanımlayıcıya yazdı. Yeni değeri almak için gatts_read kullanın.	(conn_handle, attr_handle)
_IRQ_GATTS_READ_REQUEST	4	Bağlı bir istemci bir okuma gerçekleştirdi. Okumayı reddetmek için aşağıdaki tablodan sıfır olmayan bir hata kodu döndürün veya kabul etmek için 0 / None döndürün.	(conn_handle, attr_handle)
_IRQ_SCAN_RESULT	5	Etkin bir tarama sırasında tek bir reklam (advertising) paketi alındı.	(addr_type, addr, adv_type, rssi, adv_data)
_IRQ_SCAN_DONE	6	Mevcut tarama, ya yapılandırılan süre dolduğu için ya da gap_scan(None) çağrıldığı için sona erdi.	()
_IRQ_PERIPHERAL_CONNECT	7	Daha önce verilen bir gap_connect başarılı oldu.	(conn_handle, addr_type, addr)
_IRQ_PERIPHERAL_DISCONNECT	8	Bağlı bir peripheral bağlantısını kesti.	(conn_handle, addr_type, addr)
_IRQ_GATTC_SERVICE_RESULT	9	gattc_discover_services tarafından bir hizmet bulundu.	(conn_handle, start_handle, end_handle, uuid)
_IRQ_GATTC_SERVICE_DONE	10	Hizmet keşfi tamamlandı.	(conn_handle, status)
_IRQ_GATTC_CHARACTERISTIC_RESULT	11	gattc_discover_characteristics tarafından bir özellik bulundu.	(conn_handle, end_handle, value_handle, properties, uuid)
_IRQ_GATTC_CHARACTERISTIC_DONE	12	Özellik keşfi tamamlandı.	(conn_handle, status)
_IRQ_GATTC_DESCRIPTOR_RESULT	13	gattc_discover_descriptors tarafından bir tanımlayıcı bulundu.	(conn_handle, dsc_handle, uuid)
_IRQ_GATTC_DESCRIPTOR_DONE	14	Tanımlayıcı keşfi tamamlandı.	(conn_handle, status)
_IRQ_GATTC_READ_RESULT	15	Daha önce verilen bir gattc_read veri döndürdü.	(conn_handle, value_handle, char_data)
_IRQ_GATTC_READ_DONE	16	Daha önce verilen bir gattc_read tamamlandı.	(conn_handle, value_handle, status)
_IRQ_GATTC_WRITE_DONE	17	Daha önce verilen bir gattc_write onaylandı.	(conn_handle, value_handle, status)
_IRQ_GATTC_NOTIFY	18	Uzak bir sunucu bir (onaysız) bildirim gönderdi.	(conn_handle, value_handle, notify_data)
_IRQ_GATTC_INDICATE	19	Uzak bir sunucu bir (onaylı) gösterge (indication) gönderdi.	(conn_handle, value_handle, notify_data)
_IRQ_GATTS_INDICATE_DONE	20	Daha önce gönderilen bir gösterge, istemci tarafından onaylandı (veya zaman aşımına uğradı).	(conn_handle, value_handle, status)
_IRQ_MTU_EXCHANGED	21	Bir ATT MTU değişimi tamamlandı (her iki taraftan biri tarafından başlatılmış olabilir).	(conn_handle, mtu)
_IRQ_L2CAP_ACCEPT	22	Uzak bir cihaz, bu cihazın dinlediği bir PSM üzerinde bir L2CAP bağlantısı istedi. Reddetmek için sıfır olmayan bir tamsayı döndürün veya kabul etmek için 0 / None döndürün.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_CONNECT	23	Bir L2CAP kanalı artık kuruldu; bu, ya gelen bir isteğin kabul edilmesiyle ya da giden bir l2cap_connect işleminin tamamlanmasıyla gerçekleşti.	(conn_handle, cid, psm, our_mtu, peer_mtu)
_IRQ_L2CAP_DISCONNECT	24	Bir L2CAP kanalının bağlantısı kesildi. Temiz bir bağlantı kesintisi için status 0 olur veya giden bir bağlantı girişimi başarısız olduysa sıfır olmayan bir değer olur.	(conn_handle, cid, psm, status)
_IRQ_L2CAP_RECV	25	Bir L2CAP kanalına veri geldi. Bunu okumak için l2cap_recvinto çağırın.	(conn_handle, cid)
_IRQ_L2CAP_SEND_READY	26	False döndüren önceki bir l2cap_send boşaldı ve kanal yeniden hazır. Sıfır olmayan bir status, iletim arabelleğinin taştığı ve uygulamanın veriyi yeniden göndermesi gerektiği anlamına gelir.	(conn_handle, cid, status)
_IRQ_CONNECTION_UPDATE	27	Uzak cihaz, bağlantı parametrelerini (aralık, gecikme, denetim zaman aşımı) güncelledi.	(conn_handle, conn_interval, conn_latency, supervision_timeout, status)
_IRQ_ENCRYPTION_UPDATE	28	Bir bağlantının şifreleme durumu değişti; bu tipik olarak eşleştirme veya bağlama tamamlandıktan sonra gerçekleşir.	(conn_handle, encrypted, authenticated, bonded, key_size)
_IRQ_GET_SECRET	29	Yığın, depolanmış bir bağlama gizli değerini (secret) istiyor. key None ise, sec_type türünün index. depolanmış değerini döndürün; aksi takdirde verilen (sec_type, key) ile ilişkili değeri döndürün. Hiçbir şey depolanmamışsa None döndürün.	(sec_type, index, key)
_IRQ_SET_SECRET	30	Yığın, uygulamadan bir bağlama gizli değerini kalıcı olarak saklamasını istiyor. Depolandığında True döndürün.	(sec_type, key, value)
_IRQ_PASSKEY_ACTION	31	Eşleştirmenin bir parçası olarak bir parola anahtarı (passkey) eylemi gerekiyor. gap_passkey kullanarak yanıt verin; olası eylemler için aşağıdaki parola anahtarı eylem tablosuna bakın.	(conn_handle, action, passkey)

_IRQ_GATTS_READ_REQUEST olayı için kullanılabilir dönüş kodları şunlardır:

Sabit	Değer	Anlam
_GATTS_NO_ERROR	0x00	Okumayı kabul et.
_GATTS_ERROR_READ_NOT_PERMITTED	0x02	Okumaya izin verilmiyor.
_GATTS_ERROR_WRITE_NOT_PERMITTED	0x03	Yazmaya izin verilmiyor.
_GATTS_ERROR_INSUFFICIENT_AUTHENTICATION	0x05	İstemci kimliği doğrulanmamış.
_GATTS_ERROR_INSUFFICIENT_AUTHORIZATION	0x08	İstemci yetkilendirilmemiş.
_GATTS_ERROR_INSUFFICIENT_ENCRYPTION	0x0f	Bağlantı şifrelenmemiş.

_IRQ_PASSKEY_ACTION olayı için kullanılabilir eylemler şunlardır:

Sabit	Değer	Anlam
_PASSKEY_ACTION_NONE	0	Eylem gerekmiyor.
_PASSKEY_ACTION_INPUT	2	Kullanıcıdan uzak cihazda gösterilen parola anahtarını girmesini iste.
_PASSKEY_ACTION_DISPLAY	3	Uzak cihazın girmesi için 6 haneli bir parola anahtarı göster.
_PASSKEY_ACTION_NUMERIC_COMPARISON	4	Parola anahtarının uzak cihazda gösterilenle eşleştiğini doğrula.

Aygıt yazılımında yer kazanmak için, bu sabitler bluetooth modülüne dahil edilmemiştir. İhtiyaç duyduklarınızı yukarıdaki listelerden programınıza ekleyin.

Broadcaster Rolü (Reklam Veren)

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

Belirtilen aralıkta (mikrosaniye cinsinden) reklam vermeye başlar. Bu aralık en yakın 625 us değerine aşağı yuvarlanır. Reklam vermeyi durdurmak için interval_us değerini None olarak ayarlayın.

adv_data ve resp_data, arabellek protokolünü uygulayan herhangi bir tür olabilir (örneğin bytes, bytearray, str). adv_data tüm yayınlara dahil edilir ve resp_data, etkin bir taramaya yanıt olarak gönderilir.

Not: adv_data (veya resp_data) None ise, gap_advertise öğesine yapılan önceki çağrıya iletilen veriler yeniden kullanılır. Bu, bir yayıncının yalnızca gap_advertise(interval_us) ile reklam vermeye devam etmesine olanak tanır. Reklam yükünü temizlemek için boş bir bytes geçirin, yani b''.

Observer Rolü (Tarayıcı)

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

Belirtilen süre boyunca (milisaniye cinsinden) süren bir tarama işlemi çalıştırır.

Süresiz tarama yapmak için duration_ms değerini 0 olarak ayarlayın.

Taramayı durdurmak için duration_ms değerini None olarak ayarlayın.

Görev döngüsünü (duty cycle) isteğe bağlı olarak yapılandırmak için interval_us ve window_us değerlerini kullanın. Tarayıcı, toplam duration_ms milisaniye boyunca her interval_us mikrosaniyede bir window_us mikrosaniye çalışır. Varsayılan aralık ve pencere sırasıyla 1,28 saniye ve 11,25 milisaniyedir (arka planda tarama).

Her tarama sonucu için, (addr_type, addr, adv_type, rssi, adv_data) olay verisiyle _IRQ_SCAN_RESULT olayı tetiklenir.

addr_type değerleri genel veya rastgele adresleri belirtir:

Değer	Ad	Anlam
0x00	PUBLIC	Genel (public) cihaz adresi.
0x01	RANDOM	Rastgele adres (statik, RPA veya NRPA; tür, adresin kendisinde kodlanmıştır).

adv_type değerleri Bluetooth Spesifikasyonuna karşılık gelir:

Değer	Ad	Anlam
0x00	ADV_IND	Bağlanabilir ve taranabilir yönsüz reklam.
0x01	ADV_DIRECT_IND	Bağlanabilir yönlendirilmiş reklam.
0x02	ADV_SCAN_IND	Taranabilir yönsüz reklam.
0x03	ADV_NONCONN_IND	Bağlanamayan yönsüz reklam.
0x04	SCAN_RSP	Tarama yanıtı.

Sonuçlarda tarama yanıtlarını almak istiyorsanız active değeri True olarak ayarlanabilir.

Tarama durdurulduğunda (ya sürenin bitmesi nedeniyle ya da açıkça durdurulduğunda), _IRQ_SCAN_DONE olayı tetiklenir.

Central Rolü

Bir central cihaz, observer rolünü kullanarak keşfettiği (bkz. gap_scan) veya bilinen bir adrese sahip peripheral’lara bağlanabilir.

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

Bir peripheral’a bağlanın.

Adres türleri hakkında ayrıntılar için bkz. gap_scan.

Bekleyen bir bağlantı girişimini erkenden iptal etmek için gap_connect(None) çağırın.

Başarı durumunda, _IRQ_PERIPHERAL_CONNECT olayı tetiklenir. Bir bağlantı girişimi iptal ediliyorsa, _IRQ_PERIPHERAL_DISCONNECT olayı tetiklenir.

Cihaz, cihazdan bir reklam yükü almak için scan_duration_ms kadar bekler.

Bağlantı aralığı, min_conn_interval_us ve max_conn_interval_us değerlerinden biri veya her ikisi kullanılarak mikrosaniye cinsinden yapılandırılabilir. Aksi takdirde, tipik olarak 30000 ile 50000 mikrosaniye arasında varsayılan bir aralık seçilir. Daha kısa bir aralık, güç tüketimi pahasına iş hacmini artırır.

Peripheral Rolü

Bir peripheral cihazın bağlanabilir reklamlar göndermesi beklenir (bkz. gap_advertise). Genellikle, önce gatts_register_services kullanarak hizmetleri ve özellikleri kaydederek bir GATT sunucusu olarak görev yapar.

Bir central bağlandığında, _IRQ_CENTRAL_CONNECT olayı tetiklenir.

Central ve Peripheral Rolleri

gap_disconnect(conn_handle: int, /) → bool

Belirtilen bağlantı tanıtıcısının (handle) bağlantısını keser. Bu, ya bu cihaza bağlanmış bir central (peripheral olarak görev yapıyorsa) ya da bu cihazın daha önce bağlandığı bir peripheral (central olarak görev yapıyorsa) olabilir.

Başarı durumunda, _IRQ_PERIPHERAL_DISCONNECT veya _IRQ_CENTRAL_DISCONNECT olayı tetiklenir.

Bağlantı tanıtıcısı bağlı değilse False, aksi takdirde True döndürür.

GATT Sunucusu

Bir GATT sunucusunun bir dizi kayıtlı hizmeti vardır. Her hizmet, her birinin bir değeri olan özellikler içerebilir. Özellikler ayrıca, kendileri de değerlere sahip olan tanımlayıcılar içerebilir.

Bu değerler yerel olarak depolanır ve hizmet kaydı sırasında oluşturulan “değer tanıtıcıları” (value handle) aracılığıyla erişilir. Ayrıca uzak bir istemci cihaz tarafından okunabilir veya yazılabilirler. Buna ek olarak, bir sunucu bir bağlantı tanıtıcısı aracılığıyla bağlı bir istemciye bir özelliği “bildirebilir” (notify).

Central veya peripheral rolündeki bir cihaz GATT sunucusu olarak işlev görebilir, ancak çoğu durumda bir peripheral cihazın sunucu olarak görev yapması daha yaygındır.

Özelliklerin ve tanımlayıcıların varsayılan maksimum boyutu 20 bayttır (23 baytlık varsayılan ATT MTU eksi 3 baytlık bir ATT başlığı; daha büyük bir müzakere edilmiş MTU tek başına bu sınırı yükseltmez). Bir istemci tarafından bunlara yazılan her şey bu uzunluğa kısaltılır. Ancak, herhangi bir yerel yazma maksimum boyutu artırır; bu nedenle, bir istemcinin belirli bir özelliğe daha büyük yazmalar yapmasına izin vermek istiyorsanız, kayıttan sonra gatts_write kullanın. Örneğin gatts_write(char_handle, bytes(100)).

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

Sunucuyu belirtilen hizmetlerle yapılandırır ve mevcut tüm hizmetleri değiştirir.

services_definition, services öğelerinden oluşan bir listedir; burada her service, bir UUID ve bir characteristics listesi içeren iki öğeli bir demettir.

Her characteristic, bir UUID, bir flags değeri ve isteğe bağlı olarak bir descriptors listesi içeren iki veya üç öğeli bir demettir.

Her descriptor, bir UUID ve bir flags değeri içeren iki öğeli bir demettir.

flags, aşağıda tanımlanan bayrakların bit düzeyinde VEYA (bitwise-OR) birleşimidir. Bunlar hem özelliğin (veya tanımlayıcının) davranışını hem de güvenlik ve gizlilik gereksinimlerini ayarlar.

Dönüş değeri, demetlerden oluşan bir listedir (hizmet başına bir öğe) (her öğe bir değer tanıtıcısıdır). Özellik ve tanımlayıcı tanıtıcıları, tanımlandıkları sırayla aynı demet içinde düzleştirilir.

Aşağıdaki örnek iki hizmeti kaydeder (Heart Rate ve 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),
)

Üç değer tanıtıcısı (hr, tx, rx), gatts_read, gatts_write, gatts_notify ve gatts_indicate ile kullanılabilir.

Not: Hizmetler kaydedilmeden önce reklam verme durdurulmalıdır.

Özellikler ve tanımlayıcılar için kullanılabilir bayraklar şunlardır:

Sabit	Değer	Anlam
_FLAG_BROADCAST	0x0001	Özellik yayınlanabilir.
_FLAG_READ	0x0002	İstemci değeri okuyabilir.
_FLAG_WRITE_NO_RESPONSE	0x0004	İstemci bir yanıt beklemeden yazabilir.
_FLAG_WRITE	0x0008	İstemci onaylı bir yanıtla yazabilir.
_FLAG_NOTIFY	0x0010	Sunucu bildirim gönderebilir (onaysız).
_FLAG_INDICATE	0x0020	Sunucu gösterge gönderebilir (onaylı).
_FLAG_AUTHENTICATED_SIGNED_WRITE	0x0040	İstemci imzalı yazmalar gerçekleştirebilir.
_FLAG_AUX_WRITE	0x0100	Genişletilmiş özellikler: kuyruğa alınmış/güvenilir yazmalara izin verilir.
_FLAG_READ_ENCRYPTED	0x0200	Okuma şifreli bir bağlantı gerektirir.
_FLAG_READ_AUTHENTICATED	0x0400	Okuma, kimliği doğrulanmış (MITM korumalı) bir bağlantı gerektirir.
_FLAG_READ_AUTHORIZED	0x0800	Okuma uygulama düzeyinde yetkilendirme gerektirir.
_FLAG_WRITE_ENCRYPTED	0x1000	Yazma şifreli bir bağlantı gerektirir.
_FLAG_WRITE_AUTHENTICATED	0x2000	Yazma, kimliği doğrulanmış (MITM korumalı) bir bağlantı gerektirir.
_FLAG_WRITE_AUTHORIZED	0x4000	Yazma uygulama düzeyinde yetkilendirme gerektirir.

Yukarıdaki olay sabitlerinde olduğu gibi, bu bayraklar bluetooth modülü tarafından sağlanmaz; ihtiyaç duyduklarınızı programınıza kopyalayın.

gatts_read(value_handle: int, /) → bytes

Bu tanıtıcı için yerel değeri okur (bu değer ya gatts_write ile ya da uzak bir istemci tarafından yazılmıştır).

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

Bu tanıtıcı için yerel değeri yazar; bu değer bir istemci tarafından okunabilir.

send_update True ise, abone olan tüm istemciler bu yazma hakkında bilgilendirilir (neye abone olduklarına ve özelliğin hangi işlemleri desteklediğine bağlı olarak ya bildirim ya da gösterge yoluyla).

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

Bağlı bir istemciye bir bildirim isteği gönderir.

data None ise (varsayılan), mevcut yerel değer (gatts_write ile ayarlanan) gönderilir.

Aksi takdirde, data None değilse, bu değer bildirimin bir parçası olarak istemciye gönderilir. Yerel değer değiştirilmez.

Not: Bildirim, istemcinin bu özelliğe abonelik durumuna bakılmaksızın gönderilir.

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

Bağlı bir istemciye bir gösterge isteği gönderir.

data None ise (varsayılan), mevcut yerel değer (gatts_write ile ayarlanan) gönderilir.

Aksi takdirde, data None değilse, bu değer göstergenin bir parçası olarak istemciye gönderilir. Yerel değer değiştirilmez.

Onay (veya başarısızlık, örneğin zaman aşımı) durumunda, _IRQ_GATTS_INDICATE_DONE olayı tetiklenir.

Not: Gösterge, istemcinin bu özelliğe abonelik durumuna bakılmaksızın gönderilir.

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

Bir değer için dahili arabellek boyutunu bayt cinsinden ayarlar. Bu, alınabilecek en büyük yazmayı sınırlar. Varsayılan değer 20 bayttır (23 baytlık varsayılan ATT MTU eksi 3 baytlık ATT başlığı).

append değerini True olarak ayarlamak, tüm uzak yazmaların mevcut değeri değiştirmek yerine sonuna eklenmesini sağlar. Bu şekilde en fazla len bayt arabelleğe alınabilir. gatts_read kullandığınızda, değer okunduktan sonra temizlenir. Bu özellik, Nordic UART Service gibi bir şey uygularken kullanışlıdır.

GATT İstemcisi

Bir GATT istemcisi, uzak bir GATT sunucusundaki özellikleri keşfedebilir ve okuyabilir/yazabilir.

Bir central rolündeki cihazın GATT istemcisi olarak görev yapması daha yaygındır, ancak bir peripheral’ın da kendisine bağlanan central hakkında bilgi keşfetmek için (örneğin cihaz bilgisi hizmetinden cihaz adını okumak için) istemci olarak görev yapması mümkündür.

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

Bağlı bir sunucuyu hizmetleri için sorgular.

Yalnızca o hizmeti sorgulamak için isteğe bağlı olarak bir hizmet uuid belirtin.

Keşfedilen her hizmet için _IRQ_GATTC_SERVICE_RESULT olayı tetiklenir ve tamamlandığında _IRQ_GATTC_SERVICE_DONE olayı bunu izler.

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

Bağlı bir sunucuyu belirtilen aralıktaki özellikler için sorgular.

Yalnızca o özelliği sorgulamak için isteğe bağlı olarak bir özellik uuid belirtin.

start_handle=1 ve end_handle=0xffff geçirmek, tam GATT öznitelik tanıtıcı aralığını kapsar; bu nedenle bu birleşim, uzak cihazdaki her hizmeti etkili bir şekilde arar.

Keşfedilen her özellik için _IRQ_GATTC_CHARACTERISTIC_RESULT olayı tetiklenir ve tamamlandığında _IRQ_GATTC_CHARACTERISTIC_DONE olayı bunu izler.

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

Bağlı bir sunucuyu belirtilen aralıktaki tanımlayıcılar için sorgular.

Keşfedilen her tanımlayıcı için _IRQ_GATTC_DESCRIPTOR_RESULT olayı tetiklenir ve tamamlandığında _IRQ_GATTC_DESCRIPTOR_DONE olayı bunu izler.

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

Belirtilen özellik veya tanımlayıcı tanıtıcısı için bağlı bir sunucuya uzak bir okuma gerçekleştirir.

Bir değer kullanılabilir olduğunda _IRQ_GATTC_READ_RESULT olayı tetiklenir ve tamamlandığında _IRQ_GATTC_READ_DONE olayı bunu izler.

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

Belirtilen özellik veya tanımlayıcı tanıtıcısı için bağlı bir sunucuya uzak bir yazma gerçekleştirir.

mode argümanı, şu anda desteklenen değerlerle birlikte yazma davranışını belirtir:

• mode=0 (varsayılan) yanıtsız bir yazmadır: yazma uzak sunucuya gönderilir, ancak hiçbir onay döndürülmez ve hiçbir olay tetiklenmez.

• mode=1 yanıtlı bir yazmadır: uzak sunucudan, veriyi aldığına dair bir yanıt/onay göndermesi istenir.

Uzak sunucudan bir yanıt alınırsa _IRQ_GATTC_WRITE_DONE olayı tetiklenir.

gattc_exchange_mtu(conn_handle: int, /) → None

BLE.config(mtu=value) kullanılarak ayarlanan tercih edilen MTU’yu kullanarak bağlı bir sunucuyla MTU değişimini başlatır.

MTU değişimi tamamlandığında _IRQ_MTU_EXCHANGED olayı tetiklenir.

MTU değişimi tipik olarak central tarafından başlatılır; NimBLE her iki rolü de destekler.

L2CAP Bağlantı Yönelimli Kanallar

Bu özellik, iki BLE cihazı arasında soket benzeri veri alışverişine olanak tanır. Cihazlar GAP aracılığıyla bağlandıktan sonra, her iki cihaz da diğerinin sayısal bir PSM (Protocol/Service Multiplexer) üzerinde bağlanmasını dinleyebilir.

Belirli bir zamanda yalnızca bir L2CAP kanalı etkin olabilir (yani dinlerken bağlanamazsınız).

Etkin L2CAP kanalları, kuruldukları bağlantı tanıtıcısı ve bir CID (kanal kimliği) ile tanımlanır.

Bağlantı yönelimli kanalların yerleşik kredi tabanlı akış denetimi vardır. Cihazların ortak bir MTU müzakere ettiği ATT’nin aksine, hem dinleyen hem de bağlanan cihazlar, uzak cihazın l2cap_recvinto içinde tamamen tüketilmeden önce gönderebileceği maksimum bekleyen veri miktarını sınırlayan bağımsız birer MTU ayarlar.

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

Yerel MTU mtu olarak ayarlanmış halde, belirtilen psm üzerinde gelen L2CAP kanal isteklerini dinlemeye başlar.

Uzak bir cihaz bir bağlantı başlattığında, dinleyen sunucuya gelen bağlantıyı reddetme şansı veren (sıfır olmayan bir tamsayı döndürerek) _IRQ_L2CAP_ACCEPT olayı tetiklenir.

Bağlantı kabul edildiğinde, sunucunun kanal kimliğini (CID) ve yerel ve uzak MTU’yu almasına olanak tanıyan _IRQ_L2CAP_CONNECT olayı tetiklenir.

Not: Dinlemeyi durdurmak şu anda mümkün değildir.

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

Yerel MTU mtu olarak ayarlanmış halde, belirtilen psm üzerinde dinleyen bir eşe (peer) bağlanın.

Başarılı bağlantı durumunda, istemcinin CID’yi ve yerel ve uzak (peer) MTU’yu almasına olanak tanıyan _IRQ_L2CAP_CONNECT olayı tetiklenir.

Başarısız bir bağlantı, sıfır olmayan bir durumla _IRQ_L2CAP_DISCONNECT olayını tetikler.

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

Belirtilen conn_handle ve cid ile etkin bir L2CAP kanalının bağlantısını keser.

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

conn_handle ve cid ile tanımlanan L2CAP kanalında belirtilen buf öğesini (arabellek protokolünü desteklemelidir) gönderir.

Arabellek her iki sınırı da karşılamalıdır: uzak (peer) MTU’yu aşmamalı ve yerel MTU’nun iki katını aşmamalıdır.

Kanal artık “durmuş” (stalled) ise bu False döndürür; bu, _IRQ_L2CAP_SEND_READY olayı alınana kadar l2cap_send öğesinin tekrar çağrılmaması gerektiği anlamına gelir (bu olay, uzak cihaz daha fazla kredi verdiğinde, tipik olarak veriyi alıp işledikten sonra gerçekleşir).

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

Belirtilen conn_handle ve cid öğesinden, sağlanan buf öğesine (arabellek protokolünü desteklemelidir, örneğin bytearray veya memoryview) veri alır.

Kanaldan okunan bayt sayısını döndürür.

buf None ise, kullanılabilir bayt sayısını döndürür.

Not: _IRQ_L2CAP_RECV olayı alındıktan sonra, uygulama, alma arabelleğinde daha fazla bayt kalmayana kadar (tipik olarak uzak (peer) MTU boyutuna kadar) l2cap_recvinto çağırmaya devam etmelidir.

Alma arabelleği boşalana kadar, uzak cihaza daha fazla kanal kredisi verilmez ve daha fazla veri gönderemez.

Eşleştirme ve Bağlama

Eşleştirme, bir bağlantının gizli değerlerin değişimi yoluyla şifrelenmesine ve kimliğinin doğrulanmasına olanak tanır (parola anahtarı kimlik doğrulaması yoluyla isteğe bağlı MITM koruması ile).

Bağlama, bu gizli değerlerin kalıcı belleğe (non-volatile storage) depolanması işlemidir. Bağlandığında, bir cihaz, depolanan kimlik çözümleme anahtarına (IRK) dayanarak başka bir cihazdan gelen çözümlenebilir özel adresi (RPA) çözümleyebilir. Bağlamayı desteklemek için, bir uygulamanın _IRQ_GET_SECRET ve _IRQ_SET_SECRET olaylarını uygulaması gerekir.

gap_pair(conn_handle: int, /) → None

Uzak cihazla eşleştirmeyi başlatır.

Bunu çağırmadan önce, io, mitm, le_secure ve bond yapılandırma seçeneklerinin (config aracılığıyla) ayarlandığından emin olun.

Başarılı eşleştirme durumunda, _IRQ_ENCRYPTION_UPDATE olayı tetiklenir.

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

Belirtilen conn_handle ve action için bir _IRQ_PASSKEY_ACTION olayına yanıt verir. passkey anlamı action öğesine bağlıdır (bu da yapılandırılmış G/Ç yeteneğine bağlıdır):

Eylem	Gerekli passkey yanıtı
_PASSKEY_ACTION_INPUT	Kullanıcının uzak cihazdan okuduğu parola anahtarı.
_PASSKEY_ACTION_DISPLAY	Kullanıcıya gösterilen, yerel olarak oluşturulmuş rastgele 6 haneli bir parola anahtarı.
_PASSKEY_ACTION_NUMERIC_COMPARISON	_IRQ_PASSKEY_ACTION olayında gösterilen parola anahtarını kabul etmek için 1 veya eşleştirmeyi iptal etmek için 0.

class UUID

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

Belirtilen value ile bir UUID örneği oluşturur. Bluetooth üç UUID genişliği kullanır; UUID bunların herhangi birini kabul eder:

UUID genişliği	Kabul edilen value türleri	Örnek
16 bit	int veya 2 baytlık bir arabellek (little-endian)	UUID(0x2908) veya UUID(b'\x08\x29')
32 bit	4 baytlık arabellek (little-endian)	UUID(b'\x08\x29\x00\x00')
128 bit	16 baytlık arabellek veya kısa çizgili bir dize	UUID('6E400001-B5A3-F393-E0A9-E50E24DCCA9E')

16 ve 32 bitlik UUID’ler tipik olarak SIG tarafından ayrılmış tanımlayıcılardır (bkz. Bluetooth atanmış numaralar); 128 bitlik UUID’ler normalde satıcı tarafından tanımlanır.