Bluetooth cihazlarla JavaScript üzerinden iletişim kurma

Web Bluetooth API'si, web sitelerinin Bluetooth cihazlarla iletişim kurmasına olanak tanır.

François Beaufort

Web sitelerinin yakındaki Bluetooth cihazlarla güvenli ve gizliliği korumaya yönelik bir şekilde iletişim kurabileceğini söylesem ne dersin? Bu şekilde, nabız monitörleri, ses veren ampuller ve hatta kaplumbağalar doğrudan bir web sitesiyle etkileşim kurabilirler.

Bluetooth cihazlarla etkileşim kurma özelliği şimdiye kadar yalnızca platforma özel uygulamalarda kullanılabiliyordu. Web Bluetooth API'si bu durumu değiştirmeyi ve web tarayıcılarına da getirmeyi amaçlar.

Başlamadan önce

Bu belgede, Bluetooth Düşük Enerji (BLE) ve Genel Özellik Profili'nin işleyiş şekli hakkında temel düzeyde bilgi sahibi olduğunuz varsayılmaktadır.

Web Bluetooth API spesifikasyonu henüz tamamlanmamış olsa da spesifikasyon yazarları, bu API'yi deneyip özellik hakkında geri bildirim ve uygulamaya dair geri bildirim verecek hevesli geliştiriciler arıyor.

Web Bluetooth API'nin bir alt kümesi ChromeOS, Android 6.0 için Chrome, Mac (Chrome 56) ve Windows 10'da (Chrome 70) kullanılabilir. Bu sayede, yakındaki Bluetooth Düşük Enerji cihazlarını isteyebilir ve bağlayabilir, Bluetooth özelliklerini okuyabilir/write, GATT bildirimleri alabilir, Bluetooth cihazının bağlantısının ne zaman kesildiğini öğrenebilir ve hatta Bluetooth tanımlayıcılarını okuyabilir ve bunlara yazabilirsiniz. Daha fazla bilgi için MDN'nin Tarayıcı uyumluluğu tablosuna bakın.

Linux ve Windows'un önceki sürümleri için about://flags uygulamasında #experimental-web-platform-features işaretini etkinleştirin.

Not: RFCOMM hizmeti sunan Bluetooth Classic cihazlar için Web Serial API'yi kullanabilirsiniz. Daha fazla bilgi için Web'de Bluetooth üzerinden seri başlıklı kılavuzumuza bakın.

Kaynak denemelerinde kullanılabilir

Web Bluetooth API'sini sahada kullanan geliştiricilerden mümkün olduğunca fazla geri bildirim almak için Chrome, bu özelliği daha önce ChromeOS, Android ve Mac için orijinal deneme olarak Chrome 53'e eklemişti.

Deneme Ocak 2017'de başarıyla sona erdi.

Güvenlik şartları

Güvenlikle ilgili değiş tokuşları anlamak için Chrome ekibinde yer alan ve Web Bluetooth API spesifikasyonu üzerinde çalışan yazılım mühendisi Jeffrey Yasskin'in Web Bluetooth Güvenlik Modeli başlıklı makalesini okumanızı öneririz.

Yalnızca HTTPS

Bu deneysel API, web'e eklenen güçlü bir yeni özellik olduğundan yalnızca güvenli bağlamlarda kullanılabilir. Bu nedenle, derleme işlemini TLS temelinde yapmanız gerekir.

Kullanıcı hareketi gerekiyor

Güvenlik özelliği olarak, navigator.bluetooth.requestDevice ile Bluetooth cihazların keşfi dokunma veya fare tıklaması gibi bir kullanıcı hareketiyle tetiklenmelidir. pointerup, click ve touchend etkinliklerini dinleme hakkında konuşuyoruz.

button.addEventListener('pointerup', function(event) {
  // Call navigator.bluetooth.requestDevice
});

Kodu inceleme

Web Bluetooth API büyük ölçüde JavaScript Vaatleri'ne dayanır. Sözlere aşina değilseniz bu mükemmel Sözler eğitim videosuna göz atın. () => {}, ECMAScript 2015 ok işlevleridir.

Bluetooth cihazları isteme

Web Bluetooth API spesifikasyonunun bu sürümü, Merkezi rolde çalışan web sitelerinin BLE bağlantısı üzerinden uzak GATT sunucularına bağlanmasına olanak tanır. Bluetooth 4.0 veya sonraki sürümleri kullanan cihazlar arasında iletişimi destekler.

Bir web sitesi navigator.bluetooth.requestDevice kullanarak yakındaki cihazlara erişim istediğinde tarayıcı, kullanıcıya bir cihaz seçici gösterir. Kullanıcı buradan bir cihaz seçebilir veya isteği iptal edebilir.

Bluetooth cihaz kullanıcı istemi.

navigator.bluetooth.requestDevice() işlevi, filtreleri tanımlayan zorunlu bir nesne alır. Bu filtreler, yalnızca reklamı yapılan bazı Bluetooth GATT hizmetleriyle ve/veya cihaz adıyla eşleşen cihazları döndürmek için kullanılır.

Hizmetler filtresi

Örneğin, Bluetooth GATT Pil Hizmeti'nin reklamını yapan Bluetooth cihazları istemek için:

navigator.bluetooth.requestDevice({ filters: [{ services: ['battery_service'] }] })
.then(device => { /* … */ })
.catch(error => { console.error(error); });

Ancak Bluetooth GATT Hizmetiniz standartlaştırılmış Bluetooth GATT hizmetleri listesinde yoksa Bluetooth UUID'sinin tamamını veya kısa bir 16 ya da 32 bitlik biçimini sağlayabilirsiniz.

navigator.bluetooth.requestDevice({
  filters: [{
    services: [0x1234, 0x12345678, '99999999-0000-1000-8000-00805f9b34fb']
  }]
})
.then(device => { /* … */ })
.catch(error => { console.error(error); });

Ad filtresi

name filtre anahtarını kullanarak reklamı yapılan cihaz adına göre veya namePrefix filtre anahtarını kullanarak bu adın önekine göre Bluetooth cihazları da isteyebilirsiniz. Bu durumda, hizmet filtresine dahil edilmeyen hizmetlere erişebilmek için optionalServices anahtarını da tanımlamanız gerektiğini unutmayın. Aksi takdirde, daha sonra bu öğelere erişmeye çalışırken hata alırsınız.

navigator.bluetooth.requestDevice({
  filters: [{
    name: 'Francois robot'
  }],
  optionalServices: ['battery_service'] // Required to access service later.
})
.then(device => { /* … */ })
.catch(error => { console.error(error); });

Üretici veri filtresi

Ayrıca, manufacturerData filtre anahtarıyla reklamı yapılan üreticiye özel verilere dayalı olarak Bluetooth cihazları isteyebilirsiniz. Bu anahtar, companyIdentifier adlı zorunlu bir Bluetooth şirket tanımlayıcısı anahtarına sahip nesne dizisidir. Ayrıca, kendisiyle başlayan Bluetooth cihazlarındaki üretici verilerini filtreleyen bir veri ön eki de sağlayabilirsiniz. Bir hizmet filtresine dahil edilmeyen hizmetlere erişebilmek için optionalServices anahtarını da tanımlamanız gerektiğini unutmayın. Aksi takdirde, daha sonra bu dosyalara erişmeye çalışırken hata alırsınız.

// Filter Bluetooth devices from Google company with manufacturer data bytes
// that start with [0x01, 0x02].
navigator.bluetooth.requestDevice({
  filters: [{
    manufacturerData: [{
      companyIdentifier: 0x00e0,
      dataPrefix: new Uint8Array([0x01, 0x02])
    }]
  }],
  optionalServices: ['battery_service'] // Required to access service later.
})
.then(device => { /* … */ })
.catch(error => { console.error(error); });

Maske, üretici verilerindeki bazı kalıpları eşleştirmek için veri önekiyle de kullanılabilir. Daha fazla bilgi için Bluetooth veri filtreleri açıklamalı başlıklı makaleyi inceleyin.

Not: Bu yazının yazıldığı sırada manufacturerData filtre anahtarı Chrome 92'de kullanılabilmektedir. Eski tarayıcılarla geriye dönük uyumluluk istenirse üretici veri filtresi boş olarak kabul edildiği için bir yedek seçeneği sağlamanız gerekir. [Örneğe] göz atın.

Hariç tutma filtreleri

navigator.bluetooth.requestDevice() içindeki exclusionFilters seçeneği, tarayıcı seçiciden bazı cihazları hariç tutmanıza olanak tanır. Daha geniş bir filtreyle eşleşen ancak desteklenmeyen cihazları hariç tutmak için kullanılabilir.

// Request access to a bluetooth device whose name starts with "Created by".
// The device named "Created by Francois" has been reported as unsupported.
navigator.bluetooth.requestDevice({
  filters: [{
    namePrefix: "Created by"
  }],
  exclusionFilters: [{
    name: "Created by Francois"
  }],
  optionalServices: ['battery_service'] // Required to access service later.
})
.then(device => { /* … */ })
.catch(error => { console.error(error); });

Not: exclusionFilters seçeneği Chrome 114'te kullanılabilir.

Filtre yok

Son olarak, yakındaki tüm Bluetooth cihazlarını göstermek için filters yerine acceptAllDevices tuşunu kullanabilirsiniz. Bazı hizmetlere erişebilmek için optionalServicesanahtarını da tanımlamanız gerekir. Aksi takdirde, daha sonra bu öğelere erişmeye çalışırken hata alırsınız.

navigator.bluetooth.requestDevice({
  acceptAllDevices: true,
  optionalServices: ['battery_service'] // Required to access service later.
})
.then(device => { /* … */ })
.catch(error => { console.error(error); });

Dikkat: Bu işlem, seçicide bir sürü alakasız cihazın gösterilmesine ve filtre olmadığı için enerjinin boşa harcanmasına neden olabilir. Dikkatli kullanın.

Bluetooth cihaza bağlanma

BluetoothDevice sahibi olduğunuza göre şimdi ne yapacaksınız? Hizmet ve özellik tanımlarını içeren Bluetooth uzaktan GATT sunucusuna bağlanalım.

navigator.bluetooth.requestDevice({ filters: [{ services: ['battery_service'] }] })
.then(device => {
  // Human-readable name of the device.
  console.log(device.name);

  // Attempts to connect to remote GATT Server.
  return device.gatt.connect();
})
.then(server => { /* … */ })
.catch(error => { console.error(error); });

Bluetooth özelliğini okuma

Burada, uzak Bluetooth cihazının GATT sunucusuna bağlanırız. Şimdi Birincil GATT Hizmeti alıp bu hizmete ait bir özelliği okumak istiyoruz. Örneğin, cihazın pilinin mevcut şarj seviyesini okumayı deneyelim.

Aşağıdaki örnekte battery_level, standartlaştırılmış Pil Seviyesi Özelliği'dir.

navigator.bluetooth.requestDevice({ filters: [{ services: ['battery_service'] }] })
.then(device => device.gatt.connect())
.then(server => {
  // Getting Battery Service…
  return server.getPrimaryService('battery_service');
})
.then(service => {
  // Getting Battery Level Characteristic…
  return service.getCharacteristic('battery_level');
})
.then(characteristic => {
  // Reading Battery Level…
  return characteristic.readValue();
})
.then(value => {
  console.log(`Battery percentage is ${value.getUint8(0)}`);
})
.catch(error => { console.error(error); });

Özel bir Bluetooth GATT özelliği kullanıyorsanız service.getCharacteristic için tam Bluetooth UUID'sini veya kısa bir 16 ya da 32 bit biçimi sağlayabilirsiniz.

Bir özelliğe, değerini okumak için characteristicvaluechanged etkinlik dinleyicisi de ekleyebileceğinizi unutmayın. Yaklaşan GATT bildirimlerini isteğe bağlı olarak nasıl işleyeceğinizi görmek için Özellik Değeri Değiştiğinde Okuma Örneği'ne göz atın.

…
.then(characteristic => {
  // Set up event listener for when characteristic value changes.
  characteristic.addEventListener('characteristicvaluechanged',
                                  handleBatteryLevelChanged);
  // Reading Battery Level…
  return characteristic.readValue();
})
.catch(error => { console.error(error); });

function handleBatteryLevelChanged(event) {
  const batteryLevel = event.target.value.getUint8(0);
  console.log('Battery percentage is ' + batteryLevel);
}

Bluetooth özelliğine yazma

Bluetooth GATT özelliğine yazmak, okumak kadar kolaydır. Bu kez, bir nabız monitörü cihazında Harcanan Enerji alanının değerini 0'a sıfırlamak için Nabız Kontrol Noktası'nı kullanalım.

Burada sihir yok. Tüm bunlar Kalp Atışı Kontrol Puanı Özellikleri sayfasında açıklanmıştır.

navigator.bluetooth.requestDevice({ filters: [{ services: ['heart_rate'] }] })
.then(device => device.gatt.connect())
.then(server => server.getPrimaryService('heart_rate'))
.then(service => service.getCharacteristic('heart_rate_control_point'))
.then(characteristic => {
  // Writing 1 is the signal to reset energy expended.
  const resetEnergyExpended = Uint8Array.of(1);
  return characteristic.writeValue(resetEnergyExpended);
})
.then(_ => {
  console.log('Energy expended has been reset.');
})
.catch(error => { console.error(error); });

GATT bildirimleri alma

Şimdi, cihazda Nabız Ölçümü özelliği değiştiğinde nasıl bildirim alacağınızı görelim:

navigator.bluetooth.requestDevice({ filters: [{ services: ['heart_rate'] }] })
.then(device => device.gatt.connect())
.then(server => server.getPrimaryService('heart_rate'))
.then(service => service.getCharacteristic('heart_rate_measurement'))
.then(characteristic => characteristic.startNotifications())
.then(characteristic => {
  characteristic.addEventListener('characteristicvaluechanged',
                                  handleCharacteristicValueChanged);
  console.log('Notifications have been started.');
})
.catch(error => { console.error(error); });

function handleCharacteristicValueChanged(event) {
  const value = event.target.value;
  console.log('Received ' + value);
  // TODO: Parse Heart Rate Measurement value.
  // See https://github.com/WebBluetoothCG/demos/blob/gh-pages/heart-rate-sensor/heartRateSensor.js
}

Bildirim Örneği, stopNotifications() ile bildirimlerin nasıl durdurulacağını ve eklenen characteristicvaluechanged etkinlik işleyicinin nasıl doğru şekilde kaldırılacağını gösterir.

Bluetooth cihazının bağlantısını kesme

Daha iyi bir kullanıcı deneyimi sunmak için bağlantı kesme etkinliklerini dinleyebilir ve kullanıcıyı yeniden bağlanmaya davet edebilirsiniz:

navigator.bluetooth.requestDevice({ filters: [{ name: 'Francois robot' }] })
.then(device => {
  // Set up event listener for when device gets disconnected.
  device.addEventListener('gattserverdisconnected', onDisconnected);

  // Attempts to connect to remote GATT Server.
  return device.gatt.connect();
})
.then(server => { /* … */ })
.catch(error => { console.error(error); });

function onDisconnected(event) {
  const device = event.target;
  console.log(`Device ${device.name} is disconnected.`);
}

Web uygulamanızın Bluetooth cihazla bağlantısını kesmek için device.gatt.disconnect() numaralı telefonu da arayabilirsiniz. Bu işlem, mevcut gattserverdisconnected etkinlik dinleyicilerini tetikler. Bluetooth cihazıyla zaten iletişim kuran başka bir uygulama varsa Bluetooth cihaz iletişimini durduramayacağını unutmayın. Daha ayrıntılı bilgi için Cihaz Bağlantısı Kesme Örneği ve Otomatik Yeniden Bağlantı Örneği'ne göz atın.

Dikkat: Bir cihazın bağlantısı kesildiğinde Bluetooth GATT özellikleri, hizmetleri, özellikleri vb. geçersiz kılınır. Yani, yeniden bağlandıktan sonra kodunuzun bu özellikleri her zaman (getPrimaryService(s), getCharacteristic(s) vb. aracılığıyla) alması gerekir.

Bluetooth tanımlayıcılarını okuma ve yazma

Bluetooth GATT tanımlayıcıları, bir özellik değerini tanımlayan özelliklerdir. Bunları, Bluetooth GATT özelliklerine benzer bir şekilde okuyup yazabilirsiniz.

Örneğin, cihazın sağlık termometresinin ölçüm aralığıyla ilgili kullanıcı açıklamasını nasıl okuyacağınızı görelim.

Aşağıdaki örnekte health_thermometer; Sağlık Termometresi hizmeti, measurement_interval Ölçüm Aralığı özelliği ve gatt.characteristic_user_description Karakteristik Kullanıcı Açıklaması tanımlayıcısıdır.

navigator.bluetooth.requestDevice({ filters: [{ services: ['health_thermometer'] }] })
.then(device => device.gatt.connect())
.then(server => server.getPrimaryService('health_thermometer'))
.then(service => service.getCharacteristic('measurement_interval'))
.then(characteristic => characteristic.getDescriptor('gatt.characteristic_user_description'))
.then(descriptor => descriptor.readValue())
.then(value => {
  const decoder = new TextDecoder('utf-8');
  console.log(`User Description: ${decoder.decode(value)}`);
})
.catch(error => { console.error(error); });

Cihazın sağlık termometresinin ölçüm aralığının kullanıcı açıklamasını okuduk. Şimdi bu açıklamayı nasıl güncelleyeceğimizi ve özel bir değer yazacağımızı öğrenelim.

navigator.bluetooth.requestDevice({ filters: [{ services: ['health_thermometer'] }] })
.then(device => device.gatt.connect())
.then(server => server.getPrimaryService('health_thermometer'))
.then(service => service.getCharacteristic('measurement_interval'))
.then(characteristic => characteristic.getDescriptor('gatt.characteristic_user_description'))
.then(descriptor => {
  const encoder = new TextEncoder('utf-8');
  const userDescription = encoder.encode('Defines the time between measurements.');
  return descriptor.writeValue(userDescription);
})
.catch(error => { console.error(error); });

Örnekler, demolar ve codelab'ler

Aşağıdaki tüm Web Bluetooth örnekleri başarıyla test edilmiştir. Bu örneklerden en iyi şekilde yararlanmak için pil hizmeti, kalp atış hızı hizmeti veya sağlık termometresi hizmeti içeren bir BLE çevre birimini simüle eden [BLE Çevresel Cihaz Simülasyon Aracı Android Uygulaması]'nı yüklemenizi öneririz.

Başlangıç düzeyi

• Cihaz Bilgileri: BLE cihazdan temel cihaz bilgilerini alır.
• Pil Seviyesi - Pil bilgilerini tanıtan bir BDE cihazından pil bilgilerini alın.
• Enerjiyi Sıfırla: Kalp atış hızı reklamı yapan bir BLE cihazdan harcanan enerjiyi sıfırlayın.
• Karakter Özellikleri: Bir BDE Cihazındaki belirli bir özelliğin tüm özelliklerini gösterir.
• Bildirimler: BLE cihazdan özellik bildirimlerini başlatma ve durdurma.
• Cihaz bağlantısı kesme: BLE cihazına bağlandıktan sonra cihazın bağlantısını kesebilir ve bağlantı kesildiğinde bildirim alabilirsiniz.
• Özellikleri Al: Reklamı yapılan bir hizmetin tüm özelliklerini BLE cihazdan alır.
• Tanımlayıcıları Al: Bir BLE cihazdan reklamı yapılan bir hizmetin tüm özelliklerinin tanımlayıcılarını alın.
• Üretici Veri Filtresi: BLE cihazından üretici verileriyle eşleşen temel cihaz bilgilerini alır.
• Hariç tutma filtreleri: Temel hariç tutma filtreleri içeren bir BLE cihazdan temel cihaz bilgilerini alır.

Birden çok işlemi birleştirme

• GAP Özellikleri: Bir BDE cihazının tüm GAP özelliklerini öğrenme.
• Cihaz Bilgisi Özellikleri: Bir BDE cihazının tüm Cihaz Bilgisi özelliklerini öğrenin.
• Bağlantı kaybı: BLE cihazının Uyarı Seviyesi özelliğini ayarlayın (readValue ve writeValue).
• Hizmetleri ve Özellikleri Keşfet: BLE cihazdan erişilebilen tüm birincil hizmetleri ve özelliklerini keşfedin.
• Otomatik Yeniden Bağlanma: Eksponansiyel geri yükleme algoritması kullanarak bağlantısı kesilen bir BDE cihazına yeniden bağlanın.
• Read Characteristic Value Changed (Özellik Değeri Değişti'ni Oku): Pil seviyesini okuyun ve BLE cihazdaki değişikliklerden haberdar olun.
• Tanımlayıcıları Oku: BLE cihazdan bir hizmetin tüm özelliklerinin tanımlayıcılarını okuyun.
• Tanımlayıcı Yazma: BLE cihazındaki "Özellik Kullanıcı Açıklaması" tanımlayıcısına yazma.

Düzenlediğimiz Web Bluetooth Demoları ve resmi Web Bluetooth Codelabs'e de göz atın.

Kütüphaneler

• web-bluetooth-utils, API'ye bazı kolaylık işlevleri ekleyen bir npm modülüdür.
• En popüler Node.js BLE merkezi modülü olan noble'da Web Bluetooth API şim mevcuttur. Bu sayede, WebSocket sunucusu veya başka eklentiler kullanmadan noble'u webpack/browserify yapabilirsiniz.
• angular-web-bluetooth, Web Bluetooth API'yi yapılandırmak için gereken tüm şablonları soyutlayan bir Angular modülüdür.

Araçlar

• Web Bluetooth'u kullanmaya başlama, bir Bluetooth cihazla etkileşime geçmeye başlamak için tüm JavaScript şablon kodunu oluşturan basit bir web uygulamasıdır. Bir cihaz adı, hizmet ve özellik girip özelliklerini tanımlayın.
• Bluetooth geliştiricisiyseniz Web Bluetooth Developer Studio eklentisi, Bluetooth cihazınız için Web Bluetooth JavaScript kodunu da oluşturur.

İpuçları

Chrome'un about://bluetooth-internals adresindeki Bluetooth Internals sayfasını kullanarak yakındaki Bluetooth cihazlarla ilgili her şeyi (ör. durum, hizmetler, özellikler ve tanımlayıcılar) inceleyebilirsiniz.

Bluetooth cihazlarda hata ayıklama için Chrome'daki dahili sayfa.

Bluetooth'da hata ayıklama bazen zor olabileceğinden resmi Web Bluetooth hatalarını bildirme sayfasına da göz atmanızı öneririz.

Dikkat: Bluetooth özelliklerini paralel olarak okumak ve yazmak, platforma bağlı olarak hatalara neden olabilir. Uygun olduğunda GATT işlem isteklerini manuel olarak sıraya almanızı önemle tavsiye ederiz. "GATT işlemi devam ediyor - bu sorunu nasıl çözebilirim?" başlıklı makaleyi inceleyin.

Sırada ne var?

Web Bluetooth API'nin hangi bölümlerinin şu anda uygulanmakta olduğunu öğrenmek için önce tarayıcı ve platform uygulama durumunu kontrol edin.

Henüz tamamlanmamış olsa da yakın gelecekte sizi nelerin beklediğine dair bir ön bakış sunmak isteriz:

• navigator.bluetooth.requestLEScan() ile yakındaki BLE reklamları taranacaktır.
• Yeni bir serviceadded etkinliği, yeni keşfedilen Bluetooth GATT Hizmetleri'ni izler. serviceremoved etkinliği ise kaldırılanları izler. Bir Bluetooth GATT Hizmeti'ne herhangi bir özellik ve/veya tanımlayıcı eklendiğinde veya hizmetten kaldırıldığında yeni bir servicechanged etkinliği tetiklenir.

API'yi destekleme

Web Bluetooth API'yi kullanmayı planlıyor musunuz? Herkese açık desteğiniz, Chrome ekibinin özelliklere öncelik vermesine yardımcı olur ve diğer tarayıcı tedarikçi firmalarına bu özellikleri desteklemenin ne kadar önemli olduğunu gösterir.

#WebBluetooth hashtag'ini kullanarak @ChromiumDev hesabına tweet gönderin ve bu özelliği nerede ve nasıl kullandığınızı bize bildirin.

Kaynaklar

• Stack Overflow
• Chrome Özelliği Durumu
• Chrome uygulama hataları
• Web Bluetooth spesifikasyonu
• GitHub'daki Spesifikasyon Sorunları
• BLE Çevre Birimi Simülatörü Uygulaması

Teşekkür ederiz

Bu makaleyi inceleyen Kayce Basques'e teşekkürler. Boulder, ABD'deki SparkFun Electronics tarafından oluşturulan hero resim.