Troubleshooting Bluetooth in Pybricks Code

[dlech]

Unfortunately Bluetooth issues are somewhat common due to the wide variety of Bluetooth hardware and operating systems available. But the good news is that there are some simple things you can do to really help us out. If you get a Bluetooth error in Pybricks Code, here are some things you can do to help diagnose the issue.

Common problems

Hub turns off while flashing firmware

Don't hold the button too long. The hub status light will turn off for a second while the flash memory is being erased. Then it will start flashing again. This is when you should release the button.

Error when starting to flash firmware

Don't release the button too early, otherwise the hub may turn off before flashing firmware can start. The hub status light will turn off for a second while the flash memory is being erased. Then it will start flashing again. This is when you should release the button.

City hub freezes while flashing firmware

Be sure that all motors and sensors are disconnected from the hub before flashing the firmware.

The firmware still won't flash

There are some known issues with the bootloaders on the hubs (especially the City hub + Windows). Many users have reported success using a different operating to flash the firmware (Mac/Linux/Android/ChromeOS). Once the firmware is flashed, you will likely be able to connect using the original computer to connect. Also making sure no other Bluetooth devices are connected at the same time may help.

Windows Bluetooth stack gets in bad state

We haven't determined why, but sometimes the Windows Bluetooth stack will get in a bad state and will refuse to connect, even after multiple tries. We have found that restarting Windows can sometimes fix problems like this.

Some Bluetooth adapters don't work well on Windows

Help us find out which adapters work and which don't by sharing info on your adapter. Run the following in PowerShell then post it in this issue:

wget https://github.com/Microsoft/busiotools/raw/master/bluetooth/tracing/GetBluetoothRadioInfo.ps1 -UseBasicParsing | iex 

Linux prints output twice

Sometimes we have observed information in the terminal being printed twice after disconnecting and reconnecting a hub on Linux. When this happens, BlueZ needs to be restarted with sudo systemctl restart bluetooth.service.

Errors after upgrading from firmware v3.0 to >= v3.1 on Linux

See #374 (comment) for Pybricks Code Error and #374 (comment) for pybricksdev error examples.

BlueZ keeps a cache of the device's GATT attributes and returns the old values. Clear the cache manually like this:

bluetoothctl remove XX:XX:XX:XX:XX:XX
sudo rm "/var/lib/bluetooth/YY:YY:YY:YY:YY:YY/cache/XX:XX:XX:XX:XX:XX"

where XX:XX:XX:XX:XX:XX is the Bluetooth address of the hub and YY:YY:YY:YY:YY:YY is the Bluetooth address of the Bluetooth adapter on your computer.

Developer Console

This can tell us if there was a problem with the code we wrote.

1. Press F12 or Ctrl+Shift+I (Cmd+Shift+I on macOS) to open the web browser developer tools.
2. Click on the Console tab.
3. Look for any error listed.

Chrome Device Log

This can give us more information if there was an operating-system specific problem.

1. Open a new tab or window in your web browser.
2. Type chrome://device-log in the address bar and press Enter.
3. Click Refresh if needed.
4. Change the log level to Debug.
5. Enable Detailed Timestamps
6. Filter for only Bluetooth messages.
7. Look for any errors or other useful information.

Capturing Bluetooth Packets

For the really tough problems, it is useful to capture the actual Bluetooth packets being exchanged with the Bluetooth chip.

Please refer to https://bleak.readthedocs.io/en/latest/troubleshooting.html#capture-bluetooth-traffic for instructions on how to do this.

[dlech]

Some other bits:

• Chromium-based web browsers do not officially support Web Bluetooth on Linux. You must enable it via chrome://flags/#enable-experimental-web-platform-features. This flag is only need on Linux and not any other OS.
• Not as useful, but another interesting hidden page is chrome://bluetooth-internals.
• Use this to submit bug report to Microsoft: Error: Failed to execute getPrimaryService on BluetoothRemoteGATTServer : GATT Server is disconnected. Cannot retrieve services. (Re)connect first with device.gatt.connect. #918 (comment)