Bluetooth cihazlarla JavaScript üzerinden iletişim kurma

Web Bluetooth API, 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 koruyan bir şekilde iletişim kurabileceğini söylesem ne olurdu? Bu şekilde, nabız monitörleri, şarkı söyleyen ampuller ve hatta kaplumbağalar bile bir web sitesiyle doğrudan etkileşim kurabilir.

Şimdiye kadar Bluetooth cihazlarıyla etkileşim kurma özelliği sadece platforma özel uygulamalar için mümkün olmuştur. Web Bluetooth API, bunu değiştirmeyi ve web tarayıcılarına da sunmayı amaçlar.

Başlamadan önce

Bu belgede, Bluetooth Düşük Enerji (BDE) ve Genel Özellik Profili'nin işleyiş şekliyle ilgili bazı temel bilgilere sahip olduğunuz varsayılmaktadır.

Web Bluetooth API spesifikasyonu henüz kesinleşmemiş olsa da spesifikasyon yazarları, bu API'yi deneyecek coşkulu geliştiriciler arıyor ve özellikler hakkında geri bildirim ve uygulama ile ilgili geri bildirim veriyor.

Web Bluetooth API'nin bir alt kümesi ChromeOS, Android için Chrome, Mac (Chrome 56) ve Windows 10 (Chrome 70) ile kullanılabilir. Diğer bir ifadeyle, yakındaki Bluetooth Düşük Enerji cihazlarını isteyebilir ve bu cihazlara bağlayabilir, Bluetooth özelliklerini okuyabilir/yazma, GATT bildirimlerini alabilir, Bluetooth cihazın bağlantısının kesildiği zamanı öğrenebilir ve hatta Bluetooth açıklayıcılarına okuma ve yazma işlemleri yapabilirsiniz. Daha fazla bilgi için MDN'nin Tarayıcı uyumluluğu tablosuna bakın.

Linux ve Windows'un önceki sürümlerinde about://flags öğesinde #experimental-web-platform-features işaretini etkinleştirin.

Kaynak denemelerinde kullanılabilir

Sahada Web Bluetooth API'yi kullanan geliştiricilerden mümkün olduğunca fazla geri bildirim almak için Chrome, bu özelliği önceden Chrome 53'te ChromeOS, Android ve Mac için kaynak denemesi olarak eklemişti.

Deneme süresi Ocak 2017'de başarıyla sona ermiştir.

Güvenlik gereksinimleri

Güvenlik karşılığında sunulan avantajları anlamak için Chrome ekibinde çalışan ve Web Bluetooth API spesifikasyonu üzerinde çalışan Jeffrey Yasskin'in Web Bluetooth Güvenlik Modeli yayınını tavsiye ediyorum.

Yalnızca HTTPS

Bu deneysel API, web'e eklenen yeni ve güçlü bir özellik olduğundan yalnızca güvenli bağlamlarda kullanıma sunulmuştur. Bu nedenle, TLS'yi göz önünde bulundurmanız gerekir.

Kullanıcı hareketi gerekli

Güvenlik özelliği olarak, navigator.bluetooth.requestDevice özelliğine sahip Bluetooth cihazların bulunması, dokunma veya fare tıklaması gibi bir kullanıcı hareketiyle tetiklenmelidir. pointerup, click ve touchend etkinliklerini dinlemekten bahsediyoruz.

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

Kodu inceleyin

Web Bluetooth API, büyük ölçüde JavaScript Promises'i kullanır. Bunlar hakkında bilginiz yoksa bu harika Promise eğiticisine göz atın. Son olarak, () => {}, ECMAScript 2015 Ok işlevleridir.

Bluetooth cihazları iste

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

Bir web sitesi navigator.bluetooth.requestDevice kullanarak yakındaki cihazlara erişim istediğinde, tarayıcı kullanıcıdan bir cihaz seçmesi veya isteği iptal etmesi için bir cihaz seçici ile iletişime geçmesini ister.

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ını istemek için:

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

Bluetooth GATT hizmetiniz, standartlaştırılmış Bluetooth GATT hizmetleri listesinde değilse tam Bluetooth UUID'yi veya kısa bir 16 ya da 32 bit formu sağlayabilirsiniz.

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

Ad filtresi

Bluetooth cihazlarını, name filtre anahtarıyla tanıtılan cihaz adına göre, hatta namePrefix filtre anahtarıyla bu adın bir ön ekiyle de isteyebilirsiniz. Bu durumda, hizmet filtresine dahil olmayan hizmetlere erişebilmek için optionalServices anahtarını da tanımlamanız gerekeceğini unutmayın. Aksi takdirde, daha sonra bunlara erişmeye çalıştığınızda bir 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

Bluetooth cihazları, manufacturerData filtre anahtarıyla reklamı yapılan üreticiye özel verilere dayalı olarak da istenebilir. Bu anahtar, companyIdentifier adlı zorunlu Bluetooth şirket tanımlayıcı anahtarına sahip bir nesne dizisidir. Üretici verilerini, bu kodla başlayan Bluetooth cihazlarından filtreleyen bir veri öneki de sağlayabilirsiniz. Hizmet filtresine dahil olmayan hizmetlere erişebilmek için optionalServices anahtarını tanımlamanız gerektiğini de unutmayın. Aksi takdirde, daha sonra bunlara 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 edinmek için Bluetooth veri filtreleri açıklamasına göz atın.

Not: Bu yazının yazıldığı sırada manufacturerData filtre anahtarı Chrome 92'de kullanılabilir. Eski tarayıcılarla geriye dönük uyumluluk isteniyorsa, üretici veri filtresi boş kabul edildiğinden bir yedek seçeneği sağlamanız gerekir. Bir [örneğe] bakın.

Hariç tutma filtreleri

navigator.bluetooth.requestDevice() içindeki exclusionFilters seçeneği, bazı cihazları tarayıcı seçiciden 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 kullanmayın

Son olarak, yakındaki tüm Bluetooth cihazları göstermek için filters yerine acceptAllDevices tuşunu kullanabilirsiniz. Bazı hizmetlere erişebilmek için optionalServices anahtarını da tanımlamanız gerekir. Aksi takdirde daha sonra bunlara 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 durum, seçicide bir dizi alakasız cihazın gösterilmesine ve filtre olmadığı için enerjinin harcanmasına yol açabilir. Dikkatli kullanın.

Bluetooth cihaza bağlanma

BluetoothDevice sahibi olduğunuza göre şimdi ne yapıyorsunuz? Hizmeti ve özellik tanımlarını barındıran Bluetooth uzak 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ği Okuma

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

Yukarıdaki örnekte battery_level, standart Pil Düzeyi Özelliğidir.

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 adresine tam Bluetooth UUID veya kısa 16 ya da 32 bit bir form sağlayabilirsiniz.

Değerini okumak için bir özelliğe characteristicvaluechanged etkinlik işleyici de ekleyebileceğinizi unutmayın. Yaklaşan GATT bildirimlerinin de nasıl ele alınacağını isteğe bağlı olarak nasıl ele alacağınızı görmek için Özellik Değişikliği Örneği Okuma'ya 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 yaz

Bluetooth GATT özelliğine yazmak, bu özelliği okumak kadar kolaydır. Bu kez, nabız monitöründe Nabız Kontrol Noktası'nı kullanarak Harcanan Enerji alanının değerini 0'a sıfırlayalım.

Yeterince sihirli bir yer yok. Bu işlemlerin tümü Nabız Kontrol Noktası Ö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 de cihazda Nabız Ölçümü özelliği değiştiğinde nasıl bildirim alacağına bakalım:

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 bildirimleri nasıl durduracağınızı ve eklenen characteristicvaluechanged etkinlik işleyiciyi nasıl uygun şekilde kaldıracağınızı gösterir.

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

Daha iyi bir kullanıcı deneyimi sağlamak için bağlantı kaldırma etkinliklerini dinlemek ve kullanıcıyı yeniden bağlantı kurmaya davet etmek isteyebilirsiniz:

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 olan bağlantısını kesmek için de device.gatt.disconnect() numaralı telefonu arayabilirsiniz. Bu işlem, mevcut gattserverdisconnected etkinlik dinleyicilerini tetikler. Bluetooth cihazla iletişim kuran başka bir uygulama varsa cihazın Bluetooth cihaz iletişimini durdurmayacağını unutmayın. Daha ayrıntılı bilgi edinmek için Cihaz Bağlantı Kesme Örneği ve Otomatik Yeniden Bağlama Örneği'ne göz atın.

Dikkat: Bir cihazın bağlantısı kesildiğinde Bluetooth GATT özellikleri, hizmetleri, özellikleri vb. geçersiz hale gelir. Diğer bir deyişle, kodunuz yeniden bağlandıktan sonra bu özellikleri her zaman (getPrimaryService(s), getCharacteristic(s) vb. aracılığıyla) almalıdır.

Bluetooth açıklayıcılarını okuma ve bunlara yazma

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

Örneğin, cihazın sağlık termometresinin ölçüm aralığının kullanıcı açıklamasının nasıl okunacağını 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 Özellik 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ığına ilişkin kullanıcı açıklamasını okuduğumuza göre, şimdi bunu nasıl güncelleyeceğimize ve nasıl özel bir değer yazacağımıza bakalım.

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 Web Bluetooth örneklerinin tümü başarıyla test edilmiştir. Bu örneklerden tam anlamıyla yararlanmak için Pil Hizmeti, Nabız Hizmeti veya Sağlık Termometre Hizmeti ile BLE çevre birimini simüle eden [BLE Çevre Birimi Simülatörü Android Uygulaması]'nı yüklemenizi öneririz.

Başlangıç seviyesi

• Cihaz Bilgileri - Bir BDE Cihazından temel cihaz bilgilerini alın.
• Pil Düzeyi - Bir BLE cihazından Pil bilgilerini tanıtan pil bilgilerini alın.
• Enerjiyi Sıfırla - Nabzı gösteren bir BDE cihazından harcanan enerjiyi sıfırlar.
• Özellik Özellikleri: Bir BDE Cihazındaki belirli bir özelliğin tüm özelliklerini görüntüleyin.
• Bildirimler: Bir BDE cihazından gelen karakteristik bildirimleri başlatma ve durdurma.
• Cihazın Bağlantısını Kes: Bağlandıktan sonra BLE Cihazının bağlantısını kesin ve cihaz bağlantısı kesilirse bildirim alın.
• Özellikleri Edin: Bir BDE Cihazından reklamı yapılan hizmetin tüm özelliklerini öğrenin.
• Tanımlayıcılar Al: Bir BDE Cihazından reklamı yapılan hizmetin tüm özelliklerini alın.
• Üretici Veri Filtresi: Üretici verileriyle eşleşen bir BDE cihazından temel cihaz bilgilerini alın.
• Hariç Tutma Filtreleri - Temel hariç tutma filtrelerini içeren bir BLE Cihazından temel cihaz bilgilerini alın.

Birden fazla işlemi birleştirme

• GAP Özellikleri - Bir BDE Cihazının tüm GAP özelliklerini öğrenin.
• Cihaz Bilgileri Özellikleri: Bir BDE Cihazının tüm Cihaz Bilgileri özelliklerini öğrenin.
• Bağlantı Kaybı: BDE Cihazının Uyarı Düzeyi özelliğini (okuma Değeri ve yazma Değeri) belirleyin.
• Hizmetleri ve Özellikleri Keşfedin: Erişilebilir tüm birincil hizmetleri ve bunların özelliklerini bir BDE Cihazından keşfedin.
• Otomatik Yeniden Bağlanma - Bağlantısı kesilen bir BDE cihazına, üstel geri çekilme algoritması kullanarak yeniden bağlanın.
• Değişen Karakter Değerini Okuma - Pil düzeyini okuyun ve bir BDE Cihazındaki değişikliklerle ilgili bildirim alın.
• Tanımlayıcıları Okuma: Bir BDE Cihazından bir hizmetin tüm özelliklerini okuyabilme.
• Açıklayıcı Yazma: BDE cihazında "Özellikle ilgili kullanıcı açıklaması"na yazın.

Seçilmiş Web Bluetooth Demolarımıza ve resmi Web Bluetooth Codelab'lerimize 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.
• Web Bluetooth API dolgusu, en popüler Node.js BLE merkezi modülü olan noble'da bulunur. Bu, WebSocket sunucusuna veya başka eklentilere gerek kalmadan webpack/browserify noble'ınızı kullanmanıza olanak tanır.
• angle-web-bluetooth, Web Bluetooth API'yi yapılandırmak için gereken tüm ortak metinleri soyutlayan bir Angular modülüdür.

Araçlar

• Web Bluetooth'u Kullanmaya Başlama, bir Bluetooth cihazıyla etkileşime başlamak için tüm JavaScript standart kodunu oluşturan basit bir Web Uygulamasıdır. Bir cihaz adı, hizmet ve özellik girin, özelliklerini tanımlayın ve kullanıma hazır olun.
• Zaten bir Bluetooth geliştiricisiyseniz, Web Bluetooth Developer Studio Eklentisi, ayrıca Bluetooth cihazınız için Web Bluetooth JavaScript kodunu oluşturur.

İpuçları

Yakındaki Bluetooth cihazlarla ilgili durum, hizmetler, özellikler ve tanımlayıcılar gibi her şeyi inceleyebilmeniz için Chrome'da about://bluetooth-internals adresindeki Bluetooth Dahili Bilgileri sayfası mevcuttur.

Chrome'da Bluetooth cihazlarda hata ayıklamak için kullanılan dahili sayfa.

Bluetooth'ta hata ayıklaması bazen zor olabildiğinden, resmi Web Bluetooth hatalarını bildirme sayfasına da göz atmanızı öneririz.

Dikkat: Bluetooth özelliklerini paralel olarak okuyup yazmak, platforma bağlı olarak hatalara yol açabilir. Uygun olduğunda GATT işlemi isteklerini manuel olarak sıraya sokmanızı önemle tavsiye ederiz. "GATT işlemi devam ediyor - nasıl ele alınacak?" bölümünü inceleyin.

Sırada ne var?

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

Henüz tam olarak tamamlanmamış olsa da, yakın gelecekte neler olacağına dair kısa bir bakışı burada bulabilirsiniz:

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

API'ye desteği gösterin

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ı satıcılarına onları desteklemenin ne kadar kritik olduğunu gösterir.

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

Kaynaklar

• Yığın Taşması
• Chrome Özelliğinin Durumu
• Chrome Uygulama hataları
• Web Bluetooth özellikleri
• GitHub'daki Teknik Özellikler Sorunları
• BLE Çevre Birimi Simülatörü Uygulaması

Teşekkür

Bu makaleyi incelediğiniz için Kayce Basques'a teşekkür ederiz. Boulder, ABD'den SparkFun Electronics'in lokomotif resmi.