Bluetooth Web API Guide Based on Our Experience With BLE Device Connection

Benefits of the BLE

The BLE integration brings numerous benefits to both businesses and end-users. These advantages highlight why BLE is a preferred choice for a wide range of applications, from consumer electronics to industrial devices.

Since you know the benefits and capabilities of BLE technology, you may be interested in how to build a BLE app:

Bluetooth and BLE Difference

Bluetooth Classic and BLE, though part of the same family, serve different purposes. Traditional Bluetooth is designed for continuous, streaming data transfer, making it ideal for applications like audio streaming or file transfers.

In contrast, BLE is optimized for low-power, intermittent data transfer, making it ideal for devices such as health monitors and smart home devices. Additionally, modern interactions with BLE devices are facilitated by the Web Bluetooth API.

According to the Bluetooth Special Interest Group (SIG) 2024 Market Report, Bluetooth and BLE will continue to have a significant impact on technological advancement. Let’s take a look at the numbers:

• By 2028, annual shipments of Bluetooth-enabled devices are forecasted to reach 7.5 billion, with an 8% compound annual growth rate (CAGR).
• In 2024, 1.8 billion Bluetooth LE single-mode devices are expected to ship, with annual shipments projected to double in the next five years.
• Nearly all new smartphones, tablets, and laptops support dual-mode (Bluetooth Classic + BLE).
• 3.5 billion Bluetooth peripheral devices are expected to ship in 2024, growing to 5.5 billion by 2028 with a CAGR of 12%.

For a detailed comparison, use cases, and statistical insights, you can have a quick look at our Bluetooth vs BLE article. There you will find comprehensive information on how BLE differentiates itself from traditional Bluetooth in terms of technology, application, and performance metrics.

Today, the Web Bluetooth API provides a means for web developers to discover and communicate with Bluetooth devices. This API is particularly beneficial in fields such as health and fitness, home automation, and industrial IoT. By leveraging the Web Bluetooth API, web applications can connect to heart rate monitors, smart home devices, industrial sensors, and more, allowing for real-time data exchange and control.

You can also refer to Google's official documentation for more details on the capabilities and use cases of the Web Bluetooth API.

Browser Compatibility

One of the significant advantages of Web Bluetooth is its cross-browser compatibility, ensuring that a broad range of users can access BLE-enabled web apps regardless of their preferred platform. Additionally, the Web Bluetooth API enables experimental web platform features, allowing developers to explore new possibilities and enhance user experiences. The API is supported by major browsers, making it accessible to a wide audience:

• Google Chrome. Web Bluetooth is fully supported on both Desktop and Android versions of Chrome, making it a versatile choice for developers targeting a broad user base. Chrome's widespread usage and consistent update cycle ensure that users have access to the latest BLE Web API features and improvements.
• Microsoft Edge. The support for Web Bluetooth on both Desktop and Android versions of Microsoft Edge provides another robust option for developers. Edge's compatibility ensures that users on Windows and other platforms can leverage BLE functionalities in their web applications.
• Opera. Like Chrome and Edge, Opera supports Web Bluetooth on both Desktop and Android. This adds another layer of cross-platform accessibility, especially for users who prefer this browser.
• Mozilla Firefox. There is ongoing discussion and interest within the Mozilla community about the benefits of Web Bluetooth API. As for now, Firefox partially supports Web Bluetooth.

Despite its growing adoption, Web Bluetooth isn’t universally supported across all browsers. Notable browsers that don’t currently support the Web Bluetooth API include:

• Apple Safari. Both the desktop and mobile versions of Safari don’t support Web Bluetooth. This is primarily due to Apple's strict security and privacy guidelines.
• Internet Explorer. Given its deprecated status and lack of support for many modern web standards, Internet Explorer doesn’t support Web Bluetooth.

While most of the browsers offer solid support for Web Bluetooth, it's important to remember that the technology is still developing. This means that some features may vary slightly or be in different stages of implementation across browsers. Developers should keep an eye on browser updates and community feedback to ensure compatibility and take advantage of new Web Bluetooth demo features as they become available.

Advantages and Disadvantages of Web Bluetooth for Businesses

While Web Bluetooth implementation presents numerous advantages, it also has some notable weaknesses that developers and businesses should consider.

• Central and Peripheral Roles. In BLE, devices can operate in two primary roles: central and peripheral. The central device, often a smartphone or computer, initiates and manages the connection. The peripheral device, such as a fitness tracker or sensor, broadcasts data and responds to the central device’s requests.
• GAP and GATT. GAP manages the device discovery and connection process. It defines how BLE devices advertise themselves and connect, ensuring smooth and secure interactions. GATT server defines how data is structured and transferred between BLE devices. It uses a hierarchy of services and characteristics, identified by unique UUIDs to facilitate organized and efficient data exchange.
• Services. They organize data into blocks, known as Characteristics, that are essential for delivering a specific service. For instance, the Fitness Tracking Server features two primary services: the Heart Rate Service and the Activity Monitoring Service.
• Characteristics. They serve as containers for data points and their values. In the Heart Rate Service, characteristics include Current Heart Rate, Average Heart Rate, and Maximum Heart Rate. In the Activity Monitoring Service, characteristics encompass Total Steps, Distance Traveled, and Calories Burned.
• Descriptors. They provide additional details about characteristics and their values.
• UUID. UUIDs are critical in BLE design, serving as unique identifiers for services and characteristics within the GATT structure. They ensure that data is accurately categorized and accessed across different devices and applications.

Implementing BLE in Devices

Integrating BLE into devices involves both hardware and software components. This integration must be carefully planned and executed to ensure optimal performance and reliability.

• Hardware Integration. This includes the selection and placement of BLE modules and antennas. The physical design must minimize interference and maximize signal strength to ensure stable connectivity.
• Software Development. Developing firmware and software to manage BLE communication involves configuring GATT services and characteristics, handling connection events, and ensuring efficient power management. Implementing power-saving features, such as sleep modes, is crucial for extending battery life in BLE devices.

If you want to know how to integrate BLE devices into your React Native, you can read our article on this topic:

BLE's Operational Bandwidth (OBW) Explained

OBW refers to the range of frequencies within which a BLE device operates effectively. BLE operates in the 2.4 GHz ISM band, divided into 40 channels of 2 MHz each.

OBW impacts several performance aspects of BLE devices:

• Data Throughput. A wider OBW can enhance data transfer rates by accommodating more simultaneous connections and larger data packets.
• Interference Management. Efficient use of OBW helps in reducing interference from other wireless devices, ensuring stable and reliable connections.
• Energy Consumption. Optimizing OBW usage can lead to significant energy savings, extending the battery life of BLE devices.

Understanding and optimizing OBW is essential for achieving the desired balance between performance and power efficiency in BLE devices.

Request Bluetooth Devices

The first step in using Web BLE API is to request Bluetooth devices. In JavaScript, we can achieve this by using the navigator.bluetooth.requestDevice function. This function allows your website to communicate with Bluetooth devices.

In the script below, we’re requesting heart rate monitor devices available around. The 'services' filter specifies the GATT services we're interested in, and we’re using the 'heart_rate' service which is a standard for heart rate monitors.

The requestDevice function is wrapped in a promise and it returns a promise. When the promise resolves, it carries a BluetoothDevice object that has metadata we’re interested in. For instance, device.name will give you the name of the device, while device.id will provide you with the UUID of that device.

As for error handling, it’s important to catch the errors that may occur during the requestDevice call. This can be done by chaining a .catch function to the promise. The catch block will handle any potential errors.

Connecting to BLE Device and Search Services and Characteristics

One of the key points in working with BLE devices is connecting to the device and dealing with its services and characteristics. Here we extend the previous code to include a Web Bluetooth server example.

So you've requested a device and got a BluetoothDevice object. Then, you should connect to the device's GATT server through the device.gatt.connect() call. This returns a promise with a BluetoothRemoteGATTServer object.

Next, you request the specific service you're interested in, which in our case is 'heart_rate'. You do this by calling getPrimaryService() on the connection to our BLE device, for example Web BLE server.

After that, you call getCharacteristic('heart_rate_measurement') on the service. This method returns a characteristic object which represents a piece of data provided by the BLE device. The 'heart_rate_measurement' is a standard characteristic in BLE heart rate monitors; it provides heart rate measurement.

We use the readValue() method to read the current value of the characteristic. This returns a promise that resolves with a DataView. In our case, the second byte in the DataView is the heart rate measurement we're interested in.

Handle Characteristic Change

Once a connection to a characteristic (in our case, the heart rate measurement characteristic) is established, we can set up an event listener to handle the characteristicvaluechanged event. This event occurs whenever the characteristic's value changes, which in our example is when a new heart rate measurement is received.

To receive these changes, it's vital to call startNotifications() method on the characteristic.

In the event handler handleHeartRateMeasurement(), we simply print the new heart rate measurement. In a full-fledged application, you could do more with this information — for example, displaying it in a user interface, or saving it for later analysis.

Write on Characteristics

Writing on a characteristic involves finding the appropriate characteristic and then writing a value to it. In many BLE devices on the Web, certain functions can be controlled by writing to their associated characteristic. Here, we're demonstrating how to reset the heart rate measurement by writing to the Heart Rate Control Point Characteristic.

The writing is done via the writeValue method of the BluetoothRemoteGATTCharacteristic object. Values being written must be of type ArrayBuffer or TypedArray; in this scenario, we used Uint8Array.

One thing to point out is that writeValue also returns a promise. When it resolves, it means the write operation is successful, but if it doesn't, that means the operation failed, and an error will be logged to the console. As always, remember to handle errors correctly in your app.

Read and Write to Bluetooth Descriptors

Reading the Measurement Interval descriptor provides us with the current interval at which the Health Thermometer is taking temperature measurements, expressed in seconds. We're using readValue again to get the current value of this descriptor.

Setting a new interval is done via the writeValue function on the BluetoothDescriptor object. It’s important to note that the value is an array of 16-bit integers (Uint16Array). This value variable is an array that only contains the new interval value to be written.

Assigning Events to Buttons

Now, we have two buttons for the Web browser Bluetooth API: one to connect to the heart rate monitor and another to reset it. We use the addEventListener method to attach 'click' event listeners to these buttons.

As a security feature, discovering Bluetooth devices with navigator.bluetooth.requestDevice must be triggered by a user gesture such as a touch or a mouse click. We're talking about listening to pointerup, click, and touchend events.

The ’Connect to HeartRate Monitor' button initiates the Bluetooth device request and subsequent connection when clicked. It also enables the 'Reset HeartRate Monitor' button after a successful connection since we can only reset the heart rate monitor after establishing a connection.

The 'Reset HeartRate Monitor' button invokes the resetHeartRateMeasurement function to send a reset command to the heart rate monitor. Note that at the beginning, this button is disabled. It only becomes enabled after a successful connection.

Automatic Reconnection

During this step, we should define a connect function, which is the previous code used to connect to the device. This function can be called multiple times to reconnect to the BLE devices on the Web when needed.

We add an event listener for the 'gattserverdisconnected' event. The event listener function, onDisconnected, will be called whenever the device disconnects. Inside this function, we check a global flag, autoReconnect, and if it's set to true, initiate a reconnection by calling our connect function.

The autoReconnect variable provides an option to control whether to retry the connection on disconnect. It's set to true initially, allowing for automatic reconnection. But in some circumstances, you may wish to stop attempting to reconnect, and in such cases, this variable can be set to false.

It's essential to handle disconnections as they are quite common in real-world scenarios. This could be due to the device going out-of-range, being powered off, or low battery levels. With an automatic reconnection mechanism in place, your Web application Bluetooth will be more robust and provide a better user experience.

Manual Disconnection from the Device

Here we add an event listener to a button with id 'disconnect-btn'. When this button is clicked, we check if the device is not null and is connected, using the device.gatt.connected property.

If the device is connected, the BLE Web API provides a BluetoothRemoteGATTServer.disconnect method, which can be called to manually disconnect from the device. This can be particularly useful when the connection is no longer needed.

In scenarios where user-triggered disconnections are probable, like ending a monitoring session, it's a good practice to allow manual disconnections to save on resources and battery usage for both the BLE device and the website's host device.

style.css

In the CSS, we need to define a few basic styles. The body has been given some padding and a neutral background color. The 'action-btn' class is styled for the buttons, which is similar to Bootstrap's primary button style. And finally, the device information paragraph is given some top margin for better visuals.

favicon

To use your favicon for your Web BLE examples and samples, simply save it as 'favicon.ico' in the same directory as your HTML and CSS files. You can download the 'favicon.ico.zip' folder here.

Using the React Native framework, we developed a BLE module for smooth Bluetooth connectivity. Rigorous testing and optimized communication protocols allow the system to detect and alert users of potential issues before they become critical, minimizing battery failure risks and ensuring safe maritime adventures. Now, the app ensures users can monitor battery performance effectively and enjoy safer trips on the water.

Egret, a leading e-scooter manufacturer, faced challenges with transitioning their app from Native to React Native. They sought a solution to optimize OTA update processes and ensure consistent communication across all scooter models via BLE.

We developed a custom native module for direct interaction with the scooter's hardware, enhancing communication speed and reliability. By reverse engineering the original protocol handler, we addressed underlying issues and created a generic protocol handler for seamless communication with all e-scooter BLE models. Our solution dramatically improved the OTA update process, reducing delays and enhancing user experience.

If you need to build a companion app for your IoT BLE device, the SportPlus case will be interesting for you. The key challenge was implementing a stable protocol for BLE communication, complicated by the discovery that their equipment used four different BLE protocols, leading to inconsistency in operation.

To solve this problem, we developed a generic protocol handler to address the challenge of multiple protocols, ensuring consistent communication across all devices. Additionally, we implemented a custom workout functionality with a CMS system, allowing SportPlus to manage and update workout content independently. As a result, we developed a mobile app that seamlessly integrates with SportPlus’s workout equipment, providing personalized exercise routines.