本頁面由 Cloud Translation API 翻譯而成。

透過 JavaScript 與藍牙裝置通訊

Web Bluetooth API 可讓網站與藍牙裝置通訊。

François Beaufort

如果我說過網站可以與附近的藍牙裝置通訊，該怎麼辦？能更安全且保護隱私權呢？因此透過這種方式燈泡和海龜都可以直接與網站互動。

在此之前，使用者或許可以與藍牙裝置互動但僅適用於平台專屬應用程式Web Bluetooth API 的目標是並匯入網路瀏覽器

課前說明

本文假設您已具備一些有關藍牙低功耗的基本知識能源 (BLE) 和一般屬性設定檔可正常運作。

雖然 Web Bluetooth API 規格尚未結束，許多作者都積極尋找熱心的開發人員試用這個 API，針對規格提供意見和對導入作業的意見回饋。

ChromeOS、Chrome for Android 都提供部分的 Web Bluetooth API 6.0、Mac (Chrome 56) 和 Windows 10 (Chrome 70)。也就是說，您應該要求並連線至附近的藍牙低功耗裝置。讀取/寫入藍牙特性、接收 GATT 通知、瞭解藍牙裝置連線中斷，甚至讀取和寫入藍牙描述元。詳情請參閱 MDN 的瀏覽器相容性表格可能不準確或不適當

如果是 Linux 和較舊版本的 Windows，請啟用 about://flags 中的 #experimental-web-platform-features 標記。

適用於來源試用

使用網頁版服務，盡可能向開發人員收集意見 Chrome 已在實地運用 Bluetooth API，因此 Chrome 先前已在 Chrome 中新增這項功能 53 是一項適用於 ChromeOS、Android 和 Mac 的來源試用。

試用期已順利結束於 2017 年 1 月。

安全性需求

如要瞭解安全性的取捨，建議您參考「網路藍牙安全性」 Chrome 團隊軟體工程師 Jeffrey Yasskin 的貼文 Web Bluetooth API 規格

僅限 HTTPS

這個實驗性 API 是新增在網路上的強大新功能只提供給安全內容。也就是說，建立應用程式時考量TLS。

使用者必須做出手勢

偵測藍牙裝置是安全功能 navigator.bluetooth.requestDevice 必須經由使用者手勢觸發，例如以輕觸或點擊的方式傳送我們是收聽 pointerup、click 和 touchend 事件。

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

進入程式碼

Web Bluetooth API 依賴 JavaScript Promise。如果不是熟悉這些功能，歡迎參考這個絕佳的 Promise 教學課程。還有一件事 () => {} 是 ECMAScript 2015 年箭頭函式。

要求藍牙裝置

此版本的 Web Bluetooth API 規格允許網站在扮演核心角色，可透過 BLE 連線連至遠端 GATT 伺服器。這項服務支援在實作藍牙 4.0 以上版本的裝置之間進行通訊。

網站要求存取鄰近裝置時： navigator.bluetooth.requestDevice，瀏覽器會透過裝置提示使用者透過選擇器選擇一部裝置或取消要求。

藍牙裝置使用者提示。

navigator.bluetooth.requestDevice() 函式採用必要物件定義篩選器。這些篩選條件只會傳回符合特定條件的裝置宣傳藍牙 GATT 服務和/或裝置名稱。

服務篩選器

例如，要求要求宣傳藍牙 GATT 的藍牙裝置電池服務：

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

如果您的藍牙 GATT 服務未出現在標準化藍牙 GATT 服務但您可以提供完整的藍牙 UUID 或簡短 16 或 32 位元格式。

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

名稱篩選器

您也可以根據要宣傳的裝置名稱來請求藍牙裝置運算子：name 篩選器鍵，或這個名稱的前置字串 (也就是 namePrefix) 篩選器鍵。請注意，在本範例中，您也需要定義 optionalServices 金鑰：可存取服務篩選器否則，當您嘗試存取應用程式時，系統將顯示錯誤訊息具體做法是指示 Kubernetes 建立並維護一或多個代表這些 Pod 的物件

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

製造商資料篩選器

您也可根據製造商要求使用藍牙裝置來宣傳特定資料。manufacturerData這組金鑰是物件的陣列，其中包含必要的藍牙公司 ID 金鑰， companyIdentifier。您也能提供資料前置字串製造商所提供的資料。請注意，您也需要定義 optionalServices 鍵，才能存取任何服務未納入服務篩選器否則在之後嘗試存取這些檔案

// 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); });

遮罩也可以與資料前置字串搭配使用，藉此比對製造商資料詳情請參閱藍牙資料篩選器說明內容。

注意：撰寫本文時，manufacturerData 篩選器鍵適用於 Chrome 92。如果希望與舊版瀏覽器回溯相容，必須提供備用選項，因為系統會將製造商資料篩選器納入考量並將空無一物。請見 [example]。

排除篩選器

navigator.bluetooth.requestDevice() 中的 exclusionFilters 選項可讓您您從瀏覽器選擇器排除部分裝置。可用來排除符合範圍較廣但不受支援的裝置

// 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); });

敬上

注意：exclusionFilters 選項適用於 Chrome 114。

不要使用濾鏡

最後，您可以不使用 filters，而是使用 acceptAllDevices 鍵顯示所有附近的藍牙裝置。您也需要定義 optionalServices 並使用部分服務。否則，您將收到錯誤訊息並能有效存取

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

敬上

連線至藍牙裝置

那麼，既然您已取得 BluetoothDevice，要做什麼呢？接著連線到支援藍牙遠端 GATT 伺服器的服務與特性定義。

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); });

讀取藍牙特性

我們在此連線至遠端藍牙裝置的 GATT 伺服器。現在我們並想取得主要 GATT 服務這項服務。舉例來說，我們可以試著讀取裝置的電力

在上方範例中，battery_level 是標準化電池電量特性：

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); });

如果您使用自訂的藍牙 GATT 特徵，可提供完整的藍牙 UUID，或是 16 或 32 位元的簡短格式 service.getCharacteristic。

請注意，您也可以將 characteristicvaluechanged 事件監聽器新增至處理讀取其值的特性。請參閱閱讀特性值已變更範例，瞭解如何視需要處理即將發布的 GATT 收到通知

…
.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);
}

寫入藍牙特性

寫入藍牙 GATT 特性和閱讀一樣簡單。這次讓我們使用心率控制點將能量消耗的能量值心率監測器裝置的電量為 0。

我保證這裡完全沒有魔法。一切就在心率控制點特性頁面。

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 通知

現在，來看看如何在心率測量裝置的特性變化：

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
}

通知樣本說明如何停止接收通知， stopNotifications()並妥善移除加入的 characteristicvaluechanged 事件接聽程式。

中斷與藍牙裝置的連線

為了提供更優質的使用者體驗，建議您監聽連線中斷事件並邀請使用者重新連線：

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.`);
}

你也可以呼叫 device.gatt.disconnect() 將網頁應用程式與藍牙裝置。這會觸發現有的gattserverdisconnected事件接聽程式。請注意，如果藍牙裝置的通訊內容應用程式已經與藍牙裝置通訊。查看 Device 取消連結範例和自動重新連線範例，進一步瞭解詳情。

注意：藍牙 GATT 屬性、服務、特性等項目會在會中斷裝置的連線這表示您的程式碼應一律從 getPrimaryService(s)、getCharacteristic(s) 等) 這些屬性之後重新連線。

讀取及寫入藍牙描述元

藍牙 GATT 描述元是一種描述特徵值的屬性。讀取及寫入這類通訊埠的方式與藍牙 GATT 類似

讓我們看看如何解讀使用者描述的測量結果裝置健康溫度計的間隔時間。

在下例中，health_thermometer 是健康溫度計服務。 measurement_interval評估間隔特徵，以及 gatt.characteristic_user_description「特性使用者說明」描述元。

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); });

我們完成使用者描述了讓我們看看如何更新裝置健康溫度計，並編寫自訂值。

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); });

範例、示範和程式碼研究室

下列所有網路藍牙範例皆已通過測試。享受這些樂趣建議您安裝 [BLE Peripheral 模擬器 Android 應用程式] 模擬 BLE 週邊裝置，搭配電池服務，一種心率服務或健康溫度計服務

新手

裝置資訊 - 從 BLE 裝置擷取基本裝置資訊。
電池電量 - 從 BLE 裝置廣告資訊擷取電池資訊。
重設能源：重設因 BLE 裝置廣告心率而消耗的能源。
特性屬性 - 顯示 BLE 裝置中特定特性的所有屬性。
通知 - 開始和停止來自 BLE 裝置的特性通知。
中斷連線：中斷與 BLE 裝置連線後連線中斷的通知。
取得特性 - 透過 BLE 裝置取得廣告宣傳服務的所有特性。
取得描述元 - 取得所有特性BLE 裝置所宣傳服務的描述元。
製造商資料篩選器 - 從符合製造商資料的 BLE 裝置中擷取基本裝置資訊。
排除篩選器 - 從提供基本排除篩選器的 BLE 裝置中擷取基本裝置資訊。

結合多項作業

GAP 特性 - 取得 BLE 裝置的所有 GAP 特性。
裝置資訊特性：取得 BLE 裝置的所有「裝置資訊」特性。
連結遺失：設定 BLE 裝置的快訊層級特性 (readValue &writeValue)。
探索服務與特性：從 BLE 裝置探索所有無障礙主要服務及其特性。
自動重新連線：使用指數輪詢演算法重新連線至已中斷連線的 BLE 裝置。
讀取特性值已變更：讀取電池電量，並在 BLE 裝置發生變化時接收通知。
讀取描述元 - 從 BLE 裝置上讀取服務的所有特性描述元。
寫入描述元：寫入描述元「特性使用者說明」安裝在 BLE 裝置上

您也可以參考我們精選的網路藍牙示範模式，以及官方網路藍牙程式碼研究室。

程式庫

web-bluetooth-utils 是 npm 模組，可新增一些便利函式到並嚴謹測試及提升 API 的公平性後我們才能放心地推出 API
Web Bluetooth API 輔助程式適用於 noble，這是最熱門的 Node.js BLE 中央模組。如此一來你就可以使用 webpack/browserify 輕鬆瀏覽網路適用於 WebSocket 伺服器或其他外掛程式
angular-web-bluetooth 是 Angular 的模組，設定 Web Bluetooth API 所需的樣板。

工具

開始使用網路藍牙是一款簡單的網頁應用程式，可 JavaScript 樣板程式碼，以便開始與藍牙裝置互動。輸入裝置名稱、服務、特性及定義屬性，並沒問題。
如果您已是藍牙開發人員，請使用網頁藍牙開發人員工作室外掛程式也會為您的藍牙裝置。

提示

您可以透過 Chrome 存取藍牙內部資源頁面，網址為： about://bluetooth-internals，方便使用者查看附近所有相關資訊藍牙裝置：狀態、服務、特性和描述元。

在 Chrome 中對藍牙進行偵錯的內部頁面螢幕截圖 — Chrome 的內部頁面，用於對藍牙裝置進行偵錯。

我們也建議您參閱官方如何回報網路藍牙錯誤一文處理藍牙偵錯作業有時並不容易

後續步驟

請先查看瀏覽器和平台導入狀態，瞭解有哪些部分目前正在實作 Web Bluetooth API。

目前尚未提供完整資訊，但可以先睹為快未來：

掃描附近的 BLE 廣告變更作業將發生於 navigator.bluetooth.requestLEScan()。
新的 serviceadded 事件會追蹤新發現的藍牙 GATT 服務 serviceremoved事件則會追蹤已移除的事件新的 servicechanged 事件就會觸發並從藍牙 GATT 服務中移除。

顯示對 API 的支援

您是否打算使用 Web Bluetooth API？你的公開支援能協助 Chrome 團隊優先開發功能，並向其他瀏覽器廠商說明支援這些功能的重要性。

使用主題標記將推文傳送至 @ChromiumDev #WebBluetooth敬上，並說明你使用這項服務的位置和方式。

資源

特別銘謝

感謝 Kayce Basques 審閱這篇文章。主頁橫幅來源：美國博爾德市的 SparkFun Electronics (美國博爾德)。