emericg / toolblex

A multiplatform Bluetooth Low Energy (and Classic) device scanner and analyzer.

A Bluetooth Low Energy device scanner and analyzer.

Available on Linux, macOS, Windows.

Features

• host adapters info
• RSSI graph / proximity graph (BLE and classic)
• device scanner (BLE and classic)
• device advertisement and services explorer (BLE)
• read/write device services data (BLE)
• export device info: advertisement packets, services and characteristics (with or without values)
• frequency analyzer (ONLY if you have an Ubertooth One)

Download

Screenshots

Frequency analyzer (with an Ubertooth One)

Documentation

Build dependencies

You will need a C++17 compiler and Qt 6.5+ with the following 'additional librairies':

• Qt Connectivity
• Qt Charts

For Windows builds, you'll need the MSVC 2019+ compiler. Bluetooth won't work with MinGW.
For macOS builds, you'll need Xcode 14+ installed.

Building toolBLEx

$ git clone https://github.com/emericg/toolBLEx.git
$ cd toolBLEx/
$ qmake6
$ make

Using toolBLEx

Linux

Double click.

macOS

macOS has various limitations regarding Bluetooth handling:

• MAC addresses are hidden by the OS, and replaced by randomly generated UUIDs, making proper device identification hard
• Apple iBeacons are hidden by the OS and don't appear in scan results
• Bluetooth Classic scanning doesn't seem to work at the moment

Starting with macOS 11, the application will ask you for permission to use Bluetooth. You can learn more on Apple developer website.

Windows

Bluetooth driver support might be a little shaky...

Windows doesn't have good enough support for the Ubertooth One, and thus the frequency analyzer is disabled.

Third party projects used by toolBLEx

• Qt6 (LGPL v3)
• SingleApplication (MIT)
• Graphical resources: assets/COPYING

Get involved!

Developers

You can browse the code on the GitHub page, submit patches and pull requests! Your help would be greatly appreciated ;-)

Users

You can help us find and report bugs, suggest new features, help with translation, documentation and more! Visit the Issues section of the GitHub page to start!

License

toolBLEx is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
Read the LICENSE file or consult the license on the FSF website directly.

Emeric Grange [email protected]

toolblex's Issues

[Feature Request] Pair / Bond ability?

Is your feature request related to a problem? Please describe.
I am not sure. I see a BLE beacon that is advertising and is connectable but I dont see any ability to let toolBLEx connect.

Describe the solution you'd like
I would like the ability to connect to a BLE device and through the services, use the notify function to get updates

toolBLEx flathub flatpak version does not work with Bluetooth out of the box

Describe the bug
I have installed the 0.12 toolBLEx flatpak version from Flathub (IMHO it should be the flatpak version at commit 121003c55b9c52223b4545af5210457aaddc9eca).

Out-of-the-box / without any flatpak security changes, this flatpak version did not work with Bluetooth, i.e. did not list Bluetooth devices (which on the other hand my operating system (Debian 12 bookworm under KDE 5 Plasma, Wayland) can see and interact with):

$ flatpak run io.emeric.toolblex
qt.bluetooth.bluez: Missing CAP_NET_ADMIN permission. Cannot determine whether a found address is of random or public type.
qrc:/qml/PanelDeviceInfos.qml:94:21: QML TextSelectable: Binding loop detected for property "implicitWidth"
qrc:/qml/AdapterWidget.qml:137:13: QML TextSelectable: Binding loop detected for property "implicitWidth"
qrc:/qml/AdapterWidget.qml:83:13: QML TextSelectable: Binding loop detected for property "implicitWidth"
qrc:/qml/PanelDeviceInfos.qml:266: TypeError: Cannot read property 'pairingStatus' of null
qrc:/qml/PanelDeviceInfos.qml:346: TypeError: Cannot read property 'majorClass' of null
qrc:/qml/PanelDeviceInfos.qml:371: TypeError: Cannot read property 'majorClass' of null
qrc:/qml/PanelDeviceInfos.qml:386: TypeError: Cannot read property 'servicesCount' of null
qrc:/qml/PanelDeviceInfos.qml:396: TypeError: Cannot read property 'serviceClass' of null
qrc:/qml/PanelDeviceInfos.qml:629: TypeError: Cannot read property 'mtu' of null
qrc:/qml/PanelDeviceInfos.qml:675: TypeError: Cannot read property 'rssi' of null
qrc:/qml/PanelDeviceInfos.qml:821: TypeError: Cannot read property 'servicesCount' of null

qt.bluetooth.bluez: Cannot open HCI socket: "Address family not supported by protocol"
qt.bluetooth.bluez: Cannot determine bluetoothd version and required Bluetooth HCI ioctols
qt.bluetooth.bluez: Disabling Qt Bluetooth LE feature
qt.bluetooth.bluez: Cannot open HCI socket
qrc:/qml/ButtonScanMenu.qml:44: ReferenceError: getDeviceStatusIcon is not defined
qrc:/qml/ButtonScanMenu.qml:44: ReferenceError: getDeviceStatusIcon is not defined
qt.bluetooth.bluez: l2cp socket not initialised
Device::deviceErrored( "XX:XX:XX:XX:XX:XX" ) error: QLowEnergyController::ConnectionError

Using Flatseal, I gave toolBLEx a bunch of additional permissions. The additional permissions are:

share=network
socket=session-bus
socket=system-bus
device=all

With the permissions already set up in the flathub version release, in sum the permissions look like this:

$ flatpak info --show-permissions io.emeric.toolblex
[Context]
shared=network;ipc;
sockets=x11;wayland;session-bus;system-bus;fallback-x11;
devices=dri;all;
features=bluetooth;

[System Bus Policy]
org.bluez=talk

Also, for portals, I allowed "can run in the backgorund" and "can send notifications":

$ flatpak permission-show io.emeric.toolblex
Table         Object       App                Permissions Data
background    background   io.emeric.toolblex yes         0x00
notifications notification io.emeric.toolblex yes         0x00

With these additional permissions, toolBLEx does find Bluetooth devices:

$ flatpak run io.emeric.toolblex
qt.bluetooth.bluez: Missing CAP_NET_ADMIN permission. Cannot determine whether a found address is of random or public type.
qrc:/qml/PanelDeviceInfos.qml:94:21: QML TextSelectable: Binding loop detected for property "implicitWidth"
qrc:/qml/AdapterWidget.qml:137:13: QML TextSelectable: Binding loop detected for property "implicitWidth"
qrc:/qml/AdapterWidget.qml:83:13: QML TextSelectable: Binding loop detected for property "implicitWidth"
qrc:/qml/PanelDeviceInfos.qml:266: TypeError: Cannot read property 'pairingStatus' of null
qrc:/qml/PanelDeviceInfos.qml:346: TypeError: Cannot read property 'majorClass' of null
qrc:/qml/PanelDeviceInfos.qml:371: TypeError: Cannot read property 'majorClass' of null
qrc:/qml/PanelDeviceInfos.qml:386: TypeError: Cannot read property 'servicesCount' of null
qrc:/qml/PanelDeviceInfos.qml:396: TypeError: Cannot read property 'serviceClass' of null
qrc:/qml/PanelDeviceInfos.qml:629: TypeError: Cannot read property 'mtu' of null
qrc:/qml/PanelDeviceInfos.qml:675: TypeError: Cannot read property 'rssi' of null
qrc:/qml/PanelDeviceInfos.qml:821: TypeError: Cannot read property 'servicesCount' of null

That is, the following error messages no longer show up:

qt.bluetooth.bluez: Cannot open HCI socket: "Address family not supported by protocol"
qt.bluetooth.bluez: Cannot determine bluetoothd version and required Bluetooth HCI ioctols
qt.bluetooth.bluez: Disabling Qt Bluetooth LE feature
qt.bluetooth.bluez: Cannot open HCI socket
qrc:/qml/ButtonScanMenu.qml:44: ReferenceError: getDeviceStatusIcon is not defined
qrc:/qml/ButtonScanMenu.qml:44: ReferenceError: getDeviceStatusIcon is not defined
qt.bluetooth.bluez: l2cp socket not initialised
Device::deviceErrored( "XX:XX:XX:XX:XX:XX" ) error: QLowEnergyController::ConnectionError

The error messages qt.bluetooth.bluez: Missing CAP_NET_ADMIN permission. ... and all qrc:/qml/... error messages are probably irrelevant for this issue;

Expected behavior
toolBLEx flatpak version works with Bluetooth out of the box

To Reproduce
Steps to reproduce the behavior:

# DON'T have lingering flatpak toolBLEx configurations from previous installations

flatpak install flathub io.emeric.toolblex
flatpak run io.emeric.toolblex

Screenshots
If applicable, add screenshots to help explain your problem.

(I don't add a screenshot, because I don't want to jinx my working installation)

Your environment
Please describe the environment you are using:

Operating System: Debian GNU/Linux 12
KDE Plasma Version: 5.27.5
KDE Frameworks Version: 5.103.0
Qt Version: 5.15.8
Kernel Version: 6.7.12+bpo-rt-amd64 (64-bit)
Graphics Platform: Wayland
Processors: 12 × AMD Ryzen 5 7640U w/ Radeon 760M Graphics
Memory: 27,2 GiB of RAM
Graphics Processor: AMD Radeon Graphics
Manufacturer: Framework
Product Name: Laptop 13 (AMD Ryzen 7040Series)
System Version: A5

2. Where did you download/bought the application
   from flathub ( https://flathub.org/apps/io.emeric.toolblex ) via flatpak install flathub io.emeric.toolblex

3. The version of the application you are running

$ flatpak info io.emeric.toolblex

toolBLEx - Bluetooth device scanner and analyzer

          ID: io.emeric.toolblex
         Ref: app/io.emeric.toolblex/x86_64/stable
        Arch: x86_64
      Branch: stable
     Version: 0.12
     License: GPL-3.0+
      Origin: flathub
  Collection: org.flathub.Stable
Installation: system
   Installed: 136.2 MB
     Runtime: org.freedesktop.Platform/x86_64/23.08
         Sdk: org.freedesktop.Sdk/x86_64/23.08

      Commit: 3bbe0b9bd4b84b93b456f6926f15c5968424daa2245eb354e20dd19d2213e3c0
      Parent: b1acbc3de4fc93cc3191e1ef7be22d625ecbfd2090255435d1c4a84aa0e90aa6
     Subject: Add back shadertools (121003c5)
        Date: 2024-06-20 11:24:11 +0000

Additional context
Add any other context about the problem here.

AirTags found when run on Mac, but not when run on Linux

Describe the bug
I own some Apple AirTags. When I run toolBLEx on macOS, they are discovered. When I run toolBLEx on Linux, they are not.

Expected behavior
I would expect to see the same devices appear on Linux as on macOS.

To Reproduce
Run toolBLEx GUI on macOS and on Linux in the presence of Apple AirTags.

p.s. I would note that I never have seen the AirTag names listed before when scanning on Linux with "bluetoothctl scan on". So it's possible Apple does something non-standard on macOS (or that BlueZ does something wrong on Linux) that leads to this discrepancy naturally, and it's not a toolBLEx-specific issue. Nevertheless, it'd be good to know if this is actually a toolBLEx issue or not, and if not, why it's occurring.

[Feature Request] Add link to flathub on README

Is your feature request related to a problem? Please describe.
I want to install this app

Describe the solution you'd like
This badge

Describe alternatives you've considered
Set the repo's homepage to the flathub link

0.12 not running after first launch when using Qt6 8.0

Describe the bug

After running and closing 0.12, subsequent launches fail without any messaging. Clearing data file for toolBLEx has no effect.

Possibly related to testing Qt6 8.0

Strace log
strace.txt

Expected behavior

Program to relaunch

To Reproduce
Steps to reproduce the behavior:

1. Run 0.12 (Compiled with Qt6)
2. Close the program
3. Attempt to relaunch

Your environment
Please describe the environment you are using:

1. Arch Linux
2. Compiled fro source
3. cd2976c

Additional context

qt6-base 6.8.0beta1-2

[parker@rogally bin]$ rm -rf ~/.cache/toolBLEx/
[parker@rogally bin]$ rm -rf ~/.config/toolBLEx/
[parker@rogally bin]$ rm -rf ~/.local/share/toolBLEx/
[parker@rogally bin]$ ./toolblex 
[parker@rogally bin]$

Very slow service discovery

Describe the bug

Connected to a Bluetooth tracker that supports Immediate Alert to beep. Clicking the expand on the service shows nothing.

Expected behavior

According to the example screenshots, should be drop down to read/write.

To Reproduce
Steps to reproduce the behavior:

1. Connect to device
2. Click Services
3. Click drop down next to service
4. Nothing appears

Screenshots

Your environment
Please describe the environment you are using:

1. Steam OS 3.5 (Valve modified Arch Linux)
2. Releases tar.gz
3. 0.10

[Feature Request] Selectable data export location

Is your feature request related to a problem? Please describe.
I can't find where the data is exported to

Describe the solution you'd like
I would like to select where it's exported to

Describe alternatives you've considered
You could print where the data is exported to

Doesn't start

When I launch the program it doesn't start. The program freezes and doesn't respond on the bluetooth logo page. I tried it on two different computers. One of them has Windows 10 and the other has Windows 11. Same results.

[Feature Request]

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

[Feature Request] Custom characteristic names/tags

Is your feature request related to a problem? Please describe.
For devices with known characteristics (not defined in the spec) it would be great to have custom names/tags to be able to easily distinguish them in the list

Describe the solution you'd like
A way to rename a characteristic away from "Unknown" or maybe a tag field in the empty area to the right.

Describe alternatives you've considered
Pen and paper? :D

Additional context

I was thinking the next logical step from here is setting a data type for the known characteristic so you can display converted data when the read is performed.

Write to characteristic (data) seems to write as string instead

Describe the bug
A Write to characteristic (data) seems to write as string instead

Expected behavior
A clear and concise description of what you expected to happen.

Input a hex string to send to device, window shows hex values I want written.

After hitting "Write value", characteristic shows write as a string.

Your environment
Please describe the environment you are using:

1. What is your operating system
   Windows 10
2. Where did you download/bought the application
   From github
3. The version of the application you are running
   Latest release

Additional context
Add any other context about the problem here.

Scanning any Bluetooth Low Energy (BLE) device unexpectedly disconnects and unpairs my Bluetooth (Classic) mouse

Describe the bug
Using toolBLEx version 0.12 from flathub (i.e., flatpak version of toolBLEx).

With toolBLEx, at the moment I select "scan device" / "scan services & data" / "scan services only" for a "Bluetooth: Low Energy" device, my connected Bluetooth ("Classic") mouse disconnects and unpairs. To have the Bluetooth mouse connect again, I have to go through an pairing phase again (press-and-hold button on Bluetooth mouse, pair mouse in my Debian 12 KDE Plasma wayland BlueZ GUI).

My Bluetooth mouse does not disconnect when scanning (and writing to) services and characteristics of BLE devices with gatttool and bluetoothctl.

Expected behavior
Scanning for services and characteristics of a BLE device, as well as interacting with them (e.g. writing data to a characteristic) shall not break / tamper existing Bluetooth pairings.

To Reproduce
Steps to reproduce the behavior:

1. In toolBLEx, select BLE device
2. With a BLE device selected/highlight, on the left, press the yellow-orange "scan device" button.
3. paired/connected Microsoft BluetoothMouse3600 disconnects (but e.g. paired/connected JBL Charge 2 speaker does not disconnect).

Screenshots
If applicable, add screenshots to help explain your problem.

Your environment
Please describe the environment you are using:

Operating System: Debian GNU/Linux 12
KDE Plasma Version: 5.27.5
KDE Frameworks Version: 5.103.0
Qt Version: 5.15.8
Kernel Version: 6.7.12+bpo-rt-amd64 (64-bit)
Graphics Platform: Wayland
Processors: 12 × AMD Ryzen 5 7640U w/ Radeon 760M Graphics
Memory: 27,2 GiB of RAM
Graphics Processor: AMD Radeon Graphics
Manufacturer: Framework
Product Name: Laptop 13 (AMD Ryzen 7040Series)
System Version: A5

2. Where did you download/bought the application
   from flathub ( https://flathub.org/apps/io.emeric.toolblex ) via flatpak install flathub io.emeric.toolblex

3. The version of the application you are running

$ flatpak info io.emeric.toolblex

toolBLEx - Bluetooth device scanner and analyzer

          ID: io.emeric.toolblex
         Ref: app/io.emeric.toolblex/x86_64/stable
        Arch: x86_64
      Branch: stable
     Version: 0.12
     License: GPL-3.0+
      Origin: flathub
  Collection: org.flathub.Stable
Installation: system
   Installed: 136.2 MB
     Runtime: org.freedesktop.Platform/x86_64/23.08
         Sdk: org.freedesktop.Sdk/x86_64/23.08

      Commit: 3bbe0b9bd4b84b93b456f6926f15c5968424daa2245eb354e20dd19d2213e3c0
      Parent: b1acbc3de4fc93cc3191e1ef7be22d625ecbfd2090255435d1c4a84aa0e90aa6
     Subject: Add back shadertools (121003c5)
        Date: 2024-06-20 11:24:11 +0000

Additional context
Add any other context about the problem here.

Advertisement frame with bad parsing ?

Hi !

This time I think I've found bug : I'm testing with a Xiaomi LYWSD03MMC (this time with an "atc1441 modified version").

Lots of Advertisement frames are missing and often, no one arrive after the first one, which is not the good one (bytes missing in the end).

I've done screenshots of your soft with in the same time WireShark in background.
At the same second : 19:08:01, Wireshark trace 2 Advertisement frames, and your soft only one, I think a truncated one :
Wireshark end frame (show next screenshot) => A4 C1 38 90 EA 05 00 D6 40 44 0B 0D C3 CE
ToolBLEx end frame (show next screenshot) => A4 C1 38 90 EA 05 (8 bytes missing)

Sometimes, ToolBLEx shows the good frame, but if the truncated frame appears, no more Advertisement frames occurs after (but Advertisement frames continue with WireShark).

I think it's a kind of parsing problem, which also block the next treatment (Maybe there is a link with my last Screenshot : another Advertisement frame arriving very close in time ?)