the Chromium logo

The Chromium Projects
For Developers > How-Tos >

How to file Web Bluetooth bugs

Stack Overflow #web-bluetooth is a great community for diagnosing issues. It is helpful to form well-asked questions. The tools on this page can help you diagnose issues.

If you find an implementation bug, please file a Web Bluetooth bug, and attach Bluetooth logs (both Chrome and platform logs) to help debug the issue.

Specification bugs are on GitHub.

General Bluetooth Inspection Tools

These general tools will help you explore bluetooth devices that you are attempting to communicate with:

  1. chrome://bluetooth-internals
    • Displays Bluetooth information Chrome is able to access, allowing you to experiment without going through the device chooser dialog, blocklist, or other web platform security aspects of Web Bluetooth.
  2. nRF Connect for Android or nRF Connect for iOS
    • Generic tool that allows you to scan, advertise and explore your Bluetooth low energy (BLE) devices and communicate with them.

Manual Bluetooth Tests

https://github.com/WebBluetoothCG/manual-tests contains a suite of tests that use the Web Bluetooth API. These tests differ from those already utilized by browsers in that they rely on actual Bluetooth hardware, and are manually driven.

Reproducing an error by forking and modifying one of these tests will enable other developers to reproduce the same error more rapidly because they will not need to acquire another specific or possibly proprietary device.

Bluetooth Devices to Test With

These devices are some that can be used to act as peripheral devices.

  1. BLE Peripheral Simulator Android app
    • Simulates a devices with Battery, Heart Rate, Health Thermometer services. Developers can connect to the app to Read and Write Characteristics, Subscribe to Notifications for when the Characteristics change, and Read and Write Descriptors.
    • Code at: https://github.com/WebBluetoothCG/ble-test-peripheral-android
  2. nRF Connect Can also simulate a GATT server.
  3. Espruino devices (Puck JS etc)
    • Programable in JavaScript with a WebIDE.

chrome://device-log

chrome://device-log displays a filtered view of logs on multiple platforms.

However, more detailed platform logs may be necessary to diagnose issues, see below:

Mac

Chrome logs

  1. Quit any running instance of Chrome.
  2. Launch /Applications/Utilities/Terminal.app
  3. At the command prompt enter: /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --enable-logging=stderr --vmodule=*bluetooth*=2

Platform logs

  1. Install Apple's Additional Tools for XCode if you have XCode 8+, otherwise install Apple's Hardware IO Tools for Xcode.
  2. Use Bluetooth Explorer in that package to try to discover and connect to your device.
    • Devices | Low Energy Devices will let you scan for and connect to BLE devices. If you can't find or use your device with Bluetooth Explorer, there's likely a bug in MacOS rather than Chrome. Please file a bug in Apple's bug tracker.
    • "Tools" and select "Device Cache Explorer", from there you can click "Delete All" button to clear device cache if needed to help reproduce errors.
  3. Use PacketLogger to capture a log of Bluetooth packets while you're reproducing your bug. Remember to clear the packet log before you start so you send us mostly relevant packets.

Linux

Chrome logs

  1. Quit any running instance of chrome.
  2. Execute in a console: google-chrome --enable-logging=stderr --vmodule=*bluetooth*=9 --enable-experimental-web-platform-features

Platform logs

  1. Get BlueZ version with dpkg -l bluez
  2. Get Linux kernel version with uname -r
  3. Start monitoring bluetooth via sudo btmon or record traces in btsnoop format via sudo btmon -w ~/Downloads/btmon.btsnoop

Chrome OS

Chrome logs

  1. Put the device into Developer Mode so you can get a Root Shell
  2. Open Chrome OS Shell with [Ctrl] + [Alt] + T
  3. Enter shell and run these shell commands: sudo su cp /etc/chrome_dev.conf /usr/local/ mount --bind /usr/local/chrome_dev.conf /etc/chrome_dev.conf echo "--vmodule=*bluetooth*=9" >> /etc/chrome_dev.conf
  4. Restart the UI via: restart ui
  5. Check out messages logged by Chrome at file:///home/chronos/user/log/chrome

Platform logs

Check out System Logs:

  1. Go to file:///var/log/messages
  2. Look for "bluetooth"

Enter a Bluetooth debugging console:

  1. Open Chrome OS Shell with [Ctrl] + [Alt] + T
  2. Enter bt_console and type help to get to know commands

Monitor Bluetooth traffic:

  1. Put the device into Developer Mode so you can get a Root Shell
  2. Open Chrome OS Shell with [Ctrl] + [Alt] + T
  3. Enter shell
  4. Start monitoring bluetooth via sudo btmon or record traces in btsnoop format via sudo btmon -w ~/Downloads/btmon.btsnoop

Monitor BlueZ messages going through a D-Bus message bus:

  1. Put the device into Developer Mode so you can get a Root Shell
  2. Open Chrome OS Shell with [Ctrl] + [Alt] + T
  3. Enter shell
  4. Start monitoring with dbus-monitor --system "interface=org.freedesktop.DBus.Properties" "interface=org.freedesktop.DBus.ObjectManager"

Getting the BlueZ package version:

  1. Put the device into Developer Mode so you can get a Root Shell
  2. Open Chrome OS Shell with [Ctrl] + [Alt] + T
  3. Enter shell
  4. Get the version with more /etc/portage/make.profile/package.provided/chromeos-base.packages | grep bluez

And if you're enthusiastic, you can also build BlueZ from source on your Chromebook in Developer Mode, with crouton and run it by following these instructions.

Android

ADB logs

Windows

Packet capture

  1. Install the Windows Driver Kit for Windows 10.
  2. Open an administrator command prompt.
  3. Run the command: logman create trace "bth_hci" -ow -o C:\bth_hci.etl -p {8a1f9517-3a8c-4a9e-a018-4f17a200f277} 0xffffffffffffffff 0xff -nb 16 16 -bs 1024 -mode Circular -f bincirc -max 4096 -ets
  4. Reproduce your issue.
  5. Run the command: logman stop "bth_hci" -ets
  6. Find BtEtlParse.exe in the WDK and run the command: btetlparse C:\bth_hci.etl
  7. The resulting file can be opened using Wireshark.