TheBluetooth.requestDevice() method of theBluetooth interface returns aPromise that fulfills with aBluetoothDevice object matching the specified options.If there is no chooser UI, this method returns the first device matching the criteria.

Syntax

requestDevice()requestDevice(options)

Parameters

optionsOptional

An object that sets options for selecting an appropriate device.The available options are:

filtersOptional

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 specifiedservices,name,namePrefix, and so on.

Each filter consists of an array of objects with the following properties:

servicesOptional

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 theGATT assigned services list, 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 toBluetoothUUID.getService().

nameOptional

A string containing the precise name of the device to match against.

namePrefixOptional

A string containing the name prefix to match against.All devices that have a name starting with this string will be matched.

manufacturerDataOptional

An array of objects matching against manufacturer data in the Bluetooth Low Energy (BLE) advertising packets. Each filter object has the following properties:

companyIdentifier

A mandatory number identifying the manufacturer of the device.Company identifiers are listed in the Bluetooth specificationAssigned numbers, Section 7.For example, to match against devices manufactured by "Digianswer A/S", with assigned hex number0x000C, you would specify12.

dataPrefixOptional

The data prefix.A buffer containing values to match against the values at the start of the advertising manufacturer data.

maskOptional

This allows you to match against bytes within the manufacturer data, by masking some bytes of the service datadataPrefix.

serviceDataOptional

An array of objects matching against service data in the Bluetooth Low Energy (BLE) advertising packets.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 theservices array.

dataPrefixOptional

The data prefix.A buffer containing values to match against the values at the start of the advertising service data.

maskOptional

This allows you to match against bytes within the service data, by masking some bytes of the service datadataPrefix.

exclusionFiltersOptional

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

optionalServicesOptional

An array of optional service identifiers.

The identifiers take the same values as the elements of theservices array (a GATT service name, service UUID, or UUID short 16-bit or 32-bit form).

optionalManufacturerDataOptional

An optional array of integer manufacturer codes.This takes the same values ascompanyIdentifier.

The data is not used for filtering the devices, but advertisements that match the specified set are still delivered inadvertisementreceived 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.

acceptAllDevicesOptional

A boolean value indicating that the requesting script can accept all Bluetooth devices.The default isfalse.

This option is appropriate when devices have not advertised enough information for filtering to be useful.WhenacceptAllDevices is set totrue you should omit allfilters andexclusionFilters, and you must setoptionalServices to be able touse 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 offilters.services or inoptionalServices.It is therefore important to list the required services.In particular, when filtering with justname you must remember to also specify the desired services inoptionalServices.

Return value

APromise to aBluetoothDevice object.

Exceptions

TypeError

Thrown if the providedoptions do not make sense.For example, ifoptions.filters is present andoptions.acceptAllDevices istrue,options.filters is not present andoptions.acceptAllDevices isfalse, oroptions.filters is[].

NotFoundErrorDOMException

Thrown if there is no Bluetooth device that matches the specified options.

SecurityErrorDOMException

Thrown if this operation is not permitted in this context due tosecurity concerns, such as being called from an insecure origin.

Examples

// Discovery options match any devices advertising:// - The standard heart rate service.// - Both 16-bit service IDs 0x1802 and 0x1803.// - A proprietary 128-bit UUID service c48e6067-5295-48d3-8d5c-0395f61792b1.// - Devices with name "ExampleName".// - Devices with name starting with "Prefix".//// And enables access to the battery service if devices// include it, even if devices do not advertise that service.let options = {  filters: [    { services: ["heart_rate"] },    { services: [0x1802, 0x1803] },    { services: ["c48e6067-5295-48d3-8d5c-0395f61792b1"] },    { name: "ExampleName" },    { namePrefix: "Prefix" },  ],  optionalServices: ["battery_service"],};navigator.bluetooth  .requestDevice(options)  .then((device) => {    console.log(`Name: ${device.name}`);    // Do something with the device.  })  .catch((error) => console.error(`Something went wrong. ${error}`));

Detailed examples are in the specification and also inCommunicating with Bluetooth devices over JavaScript ondeveloper.chrome.com.

Specifications

Browser compatibility

See also

• Communicating with Bluetooth devices over JavaScript ondeveloper.chrome.com.