The parameter <span class="text-color-code">filters</span> receives an object of <span class="text-color-code">BluetoothLEScanFilter</span>, with the parameter <span class="text-color-code">services</span> containing <span class="text-color-code">BluetoothServiceUUID</span>.
In our case, <span class="text-color-code">BluetoothServiceUUID</span> is <span class="text-color-code">battery_service</span>, which is one of the standardized Bluetooth GATT services.
You may provide either the full Bluetooth UUID or a short 16- or 32-bit form.
Bluetooth devices can also be requested on the basis of the device name being advertised with the <span class="text-color-code">name</span> filters key, or even a prefix of this name with the <span class="text-color-code">namePrefix</span> filters key.
Important:
Whenever you add other filter as primary filter, do not forget to add the services you might be interested in after connecting to the device, to communicate or read data.It is mandatory to tell system in advance about the scope of access required.
navigator.bluetooth.requestDevice({
filters: [{ name: 'RORO BLE Device' }],
optionalServices: ['battery_service'] // Required to access service later.
Manufacturer data filter
Request Bluetooth devices based on the manufacturer data.
The manufacturer-specific data is being advertised with the <span class="text-color-code">manufacturerData</span> filters key. This key is an array of objects with a mandatory key named <span class="text-color-code">companyIdentifier</span>. A data prefix can also be provided that filters manufacturer data from Bluetooth devices that start with it.
There are some cases where you want to exclude BLE devices with certain properties, like name or services. The <span class="text-color-code">exclusionFilters</span> option in <span class="text-color-code">navigator.bluetooth.requestDevice()</span> allows you to exclude devices from the browser picker.
Let's say, you want to query all the available devices, in such case <span class="text-color-code">filters</span> can be replaced with <span class="text-color-code">acceptAllDevices</span>.
Note: The browser might need permission to access the Bluetooth services of the device if the OS of that device has such restrictions. However, the flow to ask permission from the user is handled by the browser itself, therefore is no need to handle or check any such thing here.
The browser will present a pop-up to the user, where devices on the basis of the filters applied, will appear, Your website/code will not have access to any BLE device information unless the user selects and pairs the device, the user can also simply cancel the pop-up.
Now we know that how can we query the BLE devices of our interest, lets start interacting with the BLE device. First thing first, connect to the device.
Connect to a Bluetooth device
After we request a device with specified filters, it will return a promise, with the reference to the Bluetooth device, if the user selects the device from the picker.
Then call <span class="text-color-code">.gatt.connect()</span> on the device reference.
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 => { /* … */ })
Here it further returns the GATT Server, from which we can get the services we added to the filter. Now we want to get a Primary GATT Service and read a characteristic that belongs to this service. Try the following method to read the current charge level of the device's battery.
A service has many characteristics, and those can be different types: read, write, read/write.
For example, <span class="text-color-code">battery_service</span> is the service where we can find the characteristics related to the battery, and <span class="text-color-code">battery_level</span> is a characteristic where we can read the value.
Write to Bluetooth characteristics
We know how to read the value that is being advertised at a service. But communication is two-way, so to send the data to the BLE device, we need to write the value to the characteristics of the service.
Let’s say the <span class="text-color-code">display</span> is a service in a BLE device, which has <span class="text-color-code">display_message</span> characteristics to which we can send data and update the display message or perform certain actions.
.then(server => server.getPrimaryService('display'))
.then(service => service.getCharacteristic('display_message'))
.then(characteristic => {
let textEncoder = new TextEncoder();
let value = textEncoder.encode("Hello World!");
return characteristic.writeValueWithoutResponse(value);
.then(_ => {
console.log('Message has been sent.');
.catch(error => { console.error(error); });
We can also write command/characters to it, and the BLE device will perform certain actions if it is programmed for it.
Here our device is programmed to clear the display of Bluetooth device, when <span class="text-color-code">clr</span> is sent to the characteristics. Replacing “Hello World!” with “clr” will do the same.
Receive GATT notifications
The device in question displays the heart rate of the user, so we want to get notified whenever the heart rate changes. So, let's see how to be notified when the Heart Rate Measurement characteristic changes on the device:
.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);
What else? Disconnect
It is best practice to free the resources, you no longer need. It will also save energy.
Simply call <span class="text-color-code">device.gatt.disconnect()</span> to disconnect the device. Here <span class="text-color-code">device</span> s the reference of a Bluetooth device.
Bonus
There is an inbuilt tool in chrome(chrome://bluetooth-internals/#devices), where you can get full details of the device.
You can expand and navigate to further characteristics, and other details of the selected device.
This is it?
Of course not, this was just an introduction, and hands-on implementation which will be useful in many cases. but there is more to it how to read descriptors, and write descriptors.
.png)
.png)
