How to Inspect and Debug Web Bluetooth Devices in Google Chrome Using Bluetooth Internals

The Web Bluetooth API allows progressive web apps and web pages to communicate directly with nearby Bluetooth Low Energy (BLE) peripheral devices—such as fitness monitors, IoT sensors, heart rate trackers, and industrial automation controllers—using browser JavaScript. However, because Bluetooth communication involves multiple abstraction layers (physical radios, pairing bonds, Generic Access Profiles (GAP), and Generic Attribute Profiles (GATT)), diagnosing missing characteristics or connection dropouts using standard DevTools console logs is insufficient. Google Chrome includes a dedicated internal diagnostic console located at chrome://bluetooth-internals.

In this guide, you will learn how to inspect local Bluetooth adapters, scan for nearby BLE peripherals, discover GATT services and characteristics, and debug Web Bluetooth connections in Google Chrome.

Understanding Web Bluetooth and the GATT Hierarchy

Web Bluetooth communication is structured around the Generic Attribute Profile (GATT) client-server model:

• Peripheral / Server: The remote BLE hardware device (e.g., a smart thermometer).
• Central / Client: The Chrome browser running on your computer or Android device.
• Services: Logical collections of data (e.g., Heart Rate Service 0x180D) identified by 16-bit or 128-bit UUIDs.
• Characteristics: Individual data values stored within a service (e.g., Heart Rate Measurement 0x2A37) containing permissions (Read, Write, Notify, Indicate) and byte arrays.
• Descriptors: Metadata describing characteristic configurations (such as Client Characteristic Configuration Descriptor 0x2902 used to enable notifications).

The chrome://bluetooth-internals page exposes this complete hierarchical structure directly within Chrome.

Opening Chrome Bluetooth Internals

To access Chrome’s Bluetooth diagnostic console:

1. Launch Google Chrome on your desktop (Windows, macOS, Linux, or ChromeOS).
2. In the Omnibox address bar, type:

   chrome://bluetooth-internals

3. Press Enter.

The interface presents three primary tabs: Adapter, Devices, and Sidebar Logs.

Auditing Local Bluetooth Hardware Adapters

Click on the Adapter tab to evaluate the capabilities of your host machine’s Bluetooth controller:

Property	Description
Present	Indicates whether a physical Bluetooth radio is detected and recognized by the OS.
Powered	Reports whether the Bluetooth radio is switched ON in operating system settings.
Discoverable	Shows whether the local host is broadcasting pairing beacons.
Discovering	Indicates whether active BLE scanning is currently running.

If Present or Powered reports false, resolve operating system driver or hardware issues before attempting Web Bluetooth connections in your web app.

Scanning for Devices and Exploring GATT Services

To inspect nearby advertising BLE hardware:

1. Navigate to the Devices tab in chrome://bluetooth-internals.
2. Click the Start Scan button in the upper toolbar. Chrome begins listening for advertising packets.
3. Look for your target device in the table. The grid displays:
   • Device Name: The advertised peripheral name.
   • Address: The MAC address or randomized Bluetooth address.
   • RSSI: Received Signal Strength Indication (e.g., -65 dBm). Closer devices display higher values.
   • Connection Status: Whether the device is currently paired or connected.
4. Click the Inspect link next to your device. A dedicated tab opens displaying the peripheral’s GATT attributes.

Inspecting Characteristics and Testing Reads and Writes

Inside the device inspection tab, click Connect to establish a GATT connection:

1. Once connected, click Expand All to view all discovered Primary Services.
2. Under each service UUID, expand the Characteristics tree.
3. To read a value from the physical device:
   • Locate a characteristic with Read permissions.
   • Click Read Value.
   • Chrome queries the BLE peripheral and displays the returned hexadecimal bytes along with the decoded UTF-8 string representation.
4. To write a value to the device:
   • Locate a characteristic with Write permissions.
   • Enter the byte sequence or ASCII payload in the text box.
   • Click Write Value. Confirm that the peripheral responds appropriately.
5. To test continuous sensor streaming:
   • Click Start Notifications on a notification-capable characteristic.
   • Watch real-time value updates appear dynamically in the console.

Debugging Web Bluetooth Permission Prompts and Issues

When developing a Web Bluetooth application (using navigator.bluetooth.requestDevice()):

• Filter Mismatches: If your web app fails to find the device, check the advertising UUIDs in chrome://bluetooth-internals against the filters: [{ services: [...] }] array passed in JavaScript. If the peripheral advertises 128-bit vendor UUIDs while your script requests 16-bit IDs, Chrome suppresses the device from the user pairing prompt.
• Optional Services: In JavaScript, you can only access GATT services explicitly declared in the optionalServices: [...] parameter. If you attempt server.getPrimaryService('battery_service') without listing it, Chrome throws a SecurityError.
• Origin Trial and HTTPS Requirement: Web Bluetooth is strictly limited to secure HTTPS origins. Local testing works across http://localhost, but remote domains must serve valid TLS certificates.