Bluetooth.requestDevice() update the options (#32638)

* Bluetooth.requestDevice() update the options * Add events known to work * Add bit of info on optional manufacturer data * Apply suggestions from code review Co-authored-by: Chris Mills <[email protected]> --------- Co-authored-by: Chris Mills <[email protected]>
mdn · Mar 14, 2024 · b74d3ed · b74d3ed
1 parent 78005ac
commit b74d3ed
Show file tree

Hide file tree

Showing 3 changed files with 96 additions and 13 deletions.
diff --git a/files/en-us/web/api/bluetooth/requestdevice/index.md b/files/en-us/web/api/bluetooth/requestdevice/index.md
@@ -23,17 +23,89 @@ requestDevice(options)
 ### Parameters
 
 - `options` {{optional_inline}}
-  - : An object that sets options for the device request.
+
+  - : An object that sets options for selecting an appropriate device.
     The available options are:
-    - `filters`
-      - : An array of filter objects.
-        Each filter consists of an array of `BluetoothServiceUUID`s, a `name` parameter, and a `namePrefix` parameter.
-    - `optionalServices`
-      - : An array of `BluetoothServiceUUID`s.
-    - `acceptAllDevices`
+
+    - `filters` {{optional_inline}}
+
+      - : An array of filter objects indicating the properties of devices that will be matched.
+        To match a filter object, a device must match all the values of the filter: all its specified `services`, `name`, `namePrefix`, and so on.
+
+        Each filter consists of an array of objects with the following properties:
+
+        - `services` {{optional_inline}}
+
+          - : An array of values indicating the Bluetooth GATT (Generic Attribute Profile) services that a Bluetooth device must support.
+            Each value can be a valid name from the [GATT assigned services list](https://github.com/WebBluetoothCG/registries/blob/master/gatt_assigned_services.txt), such as `'battery_service'` or `'blood_pressure'`.
+            You can also pass a full service UUID such as `'0000180F-0000-1000-8000-00805f9b34fb'` or the short 16-bit (`0x180F`) or 32-bit alias.
+            Note that these are the same values that can be passed to {{domxref("BluetoothUUID/getService_static","BluetoothUUID.getService()")}}.
+
+        - `name` {{optional_inline}}
+          - : A string containing the precise name of the device to match against.
+        - `namePrefix` {{optional_inline}}
+          - : A string containing the name prefix to match against.
+            All devices that have a name starting with this string will be matched.
+        - `manufacturerData` {{optional_inline}}
+
+          - : An array of objects matching against manufacturer data in the Bluetooth Low Energy (BLE) advertising packets. <!-- BluetoothManufacturerDataFilterInit -->
+            Each filter object has the following properties:
+
+            - `companyIdentifier`
+              - : A mandatory number identifying the manufacturer of the device.
+                Company identifiers are listed in the Bluetooth specification [Assigned numbers](https://www.bluetooth.com/specifications/assigned-numbers/), Section 7.
+                For example, to match against devices manufacturered by "Digianswer A/S", with assigned hex number `0x000C`, you would specify `12`.
+            - `dataPrefix` {{optional_inline}}
+              - : The data prefix.
+                A buffer containing values to match against the values at the start of the advertising manufacturer data.
+            - `mask` {{optional_inline}}
+              - : This allows you to match against bytes within the manufacturer data, by masking some bytes of the service data `dataPrefix`.
+
+        - `serviceData` {{optional_inline}} <!-- BluetoothServiceDataFilterInit -->
+
+          - : An array of objects matching against service data in the Bluetooth Low Energy (BLE) advertising packets.<!-- BluetoothServiceDataFilterInit -->
+            Each filter object has the following properties:
+
+            - `service`
+              - : The GATT service name, the service UUID, or the UUID 16-bit or 32-bit form.
+                This takes the same values as the elements of the [`services`](#services) array.
+            - `dataPrefix` {{optional_inline}}
+              - : The data prefix.
+                A buffer containing values to match against the values at the start of the advertising service data.
+            - `mask` {{optional_inline}}
+              - : This allows you to match against bytes within the service data, by masking some bytes of the service data `dataPrefix`.
+
+    - `exclusionFilters` {{optional_inline}}
+      - : An array of filter objects indicating the characteristics of devices that will be excluded from matching.
+        The properties of the array elements are the same as for [`filters`](#filters).
+    - `optionalServices` {{optional_inline}}
+
+      - : An array of optional service identifiers.
+
+        The identifiers take the same values as the elements of the [`services`](#services) array (a GATT service name, service UUID, or UUID short 16-bit or 32-bit form).
+
+    - `optionalManufacturerData` {{optional_inline}}
+
+      - : An optional array of integer manufacturer codes.
+        This takes the same values as [`companyIdentifier`](#companyidentifier).
+
+        The data is not used for filtering the devices, but advertisements that match the specified set are still delivered in `advertisementreceived` events.
+        This is useful because it allows code to specify an interest in data received from Bluetooth devices without constraining the filter controlling which devices are presented to the user in the permission prompt.
+
+    - `acceptAllDevices` {{optional_inline}}
+
       - : A boolean value indicating that the requesting script can accept all Bluetooth devices.
         The default is `false`.
 
+        This option is appropriate when devices have not advertised enough information for filtering to be useful.
+        When `acceptAllDevices` is set to `true` you should omit all [`filters`](#filters) and [`exclusionFilters`](#exclusionfilters), and you must set [`optionalServices`](#optionalservices) to be able to _use_ the returned device.
+
+After the user selects a device to pair in the current origin, it is only allowed to access services whose UUID was listed in the services list in any element of [`filters.services`](#services) or in [`optionalServices`](#optionalservices).
+It is therefore important to list the required services.
+In particular, when filtering with just [`name`](#name) you must remember to also specify the desired services in [`optionalServices`](#optionalservices).
+
+> **Note:** Even though the `options` argument is technically optional, in order to return any results you must either set a value for `filters` or set `acceptAllDevices` to `true`.
+
 ### Return value
 
 A {{jsxref("Promise")}} to a {{domxref("BluetoothDevice")}} object.
@@ -80,7 +152,7 @@ navigator.bluetooth
   .catch((error) => console.error(`Something went wrong. ${error}`));
 ```
 
-[Detailed examples](https://webbluetoothcg.github.io/web-bluetooth/#example-filter-by-services) are in the specification.
+[Detailed examples](https://webbluetoothcg.github.io/web-bluetooth/#example-filter-by-services) are in the specification and also in [Communicating with Bluetooth devices over JavaScript](https://developer.chrome.com/docs/capabilities/bluetooth) on _developer.chrome.com_.
 
 ## Specifications
 
@@ -89,3 +161,7 @@ navigator.bluetooth
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [Communicating with Bluetooth devices over JavaScript](https://developer.chrome.com/docs/capabilities/bluetooth) on _developer.chrome.com_.
diff --git a/files/en-us/web/api/bluetoothdevice/index.md b/files/en-us/web/api/bluetoothdevice/index.md
@@ -31,6 +31,13 @@ environment.
 - {{DOMxRef("BluetoothDevice.forget()")}} {{Experimental_Inline}}
   - : Provides a way for the page to revoke access to a device the user has granted access to.
 
+## Events
+
+Listen to these events using {{domxref("EventTarget.addEventListener", "addEventListener()")}} or by assigning an event listener to the `oneventname` property of this interface.
+
+- {{DOMxRef("BluetoothDevice/gattserverdisconnected_event", "gattserverdisconnected")}}
+  - : Fired on a device when an active GATT connection is lost.
+
 ## Specifications
 
 {{Specifications}}

diff --git a/files/en-us/web/api/bluetoothremotegattcharacteristic/index.md b/files/en-us/web/api/bluetoothremotegattcharacteristic/index.md
@@ -24,11 +24,6 @@ The `BluetoothRemoteGattCharacteristic` interface of the [Web Bluetooth API](/en
 - {{DOMxRef("BluetoothRemoteGATTCharacteristic.value")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : The currently cached characteristic value. This value gets updated when the value of the characteristic is read or updated via a notification or indication.
 
-### Events
-
-- `oncharacteristicvaluechanged` {{Experimental_Inline}}
-  - : Event handler for the `characteristicvaluechanged` event.
-
 ## Instance methods
 
 - {{DOMxRef("BluetoothRemoteGATTCharacteristic.getDescriptor()")}} {{Experimental_Inline}}
@@ -48,6 +43,11 @@ The `BluetoothRemoteGattCharacteristic` interface of the [Web Bluetooth API](/en
 - {{DOMxRef("BluetoothRemoteGATTCharacteristic.stopNotifications()")}} {{Experimental_Inline}}
   - : Returns a {{JSxRef("Promise")}} that resolves when `navigator.bluetooth` is removed from the active notification context.
 
+## Events
+
+- {{DOMxRef("BluetoothRemoteGATTCharacteristic/characteristicvaluechanged_event", "characteristicvaluechanged")}} {{Experimental_Inline}}
+  - : Fired on a {{domxref("BluetoothRemoteGATTCharacteristic")}} when its value changes.
+
 ## Specifications
 
 {{Specifications}}