Skip to content

QtBlueTooth not functional on Linux

I’m developing an embedded application with bluetooth LE function enabled using Qt 5.7. The device I’m developing are meant to act as peripheral role, it can broadcast advertising packets and let smartphones to connect to.

The target board are running with Ubuntu Linux 14.04, with bluez version 5.43 (the latest) Since Qt documentation says “In Qt 5.7, additional API supporting the peripheral role was added as a Technology Preview, with the backend only implemented for Linux/BlueZ.” So, I think the Qt bluetooth API are exactly what I need.

But when I build and run the Qt bluetooth examples (BlueTooth Low Energy Heart Rate Server Example and Bluetooth Scanner Example), none of them are working. I can only get console output: “qt.bluetooth: Dummy backend running. Qt Bluetooth module is non-functional.”

I googled that error message, it seems many developers get that error message because they are using Qt bluetooth API on windows platform, and qt bluetooth api does not support Windows. But I’m using Ubuntu Linux, so clearly something wrong but I don’t know what exactly cause the issue.

What I’m trying:

  1. Enable QtBluetooth logging. But nothing more interesting message to show.
  2. Don’t use any Qt bluetooth API, just use command line tool hciconfig and hcitool to manually set up an advertising action. And it actually works ! My iPhone can “see” the device, and I can connect to it !

Based on what I’m trying, I think my hardware are OK, the bluetooth chip can work, but I really need the QtBluetooth API to work correctly. Maybe I miss something important ? The bluez need some configuration ? Please help.



OK, finally I’ve managed to solve the issue. Qt has some feature test functions when you build it by source. If you don’t have some development packages installed on the host, the test will fail and the function won’t work properly. In this case qt will use dummy backend instead, so the example apps can still compile OK and run, but without any practical usage.

Speaking of the qt bluetooth, the required dev-packages are libbluetooth-dev bluetooth blueman bluez libusb-dev libdbus-1-dev bluez-hcidump bluez-tools (I’ve list more installs than needed, just in case), make sure install all these on the host BEFORE make.

After I’ve done all the prepare work, I run the configure script to generate the Makefile for Qt. This is the configure script I use:

-prefix /opt/qt-5.7.0 
-xplatform linux-arm-gnueabi-g++     # yes, I need to cross-compile
-nomake examples 
-nomake tests 

After running the configure script, you’ll get a qmake executable under yourQtSourcePath/qtbase/bin/, then you can test your qtbluetooth function by execute:

qtSourcePath/qtbase/bin/qmake qtSourcePath/qtconnectivity/   

If you see something like:

Checking for bluez... yes
Checking for bluez_le... yes
Checking for linux_crypto_api... yes

then you are good to go, just make && make install for the whole Qt source, qt bluetooth can work properly now.


If by any means you can’t pass the bluetooth test (It’s very possible when you need to cross-compile, like my case), I’ve figured out a workaround. You still have to install all the required dev-packages before make, this time in order to pass the bluetooth function test, you can use your system built-in qmake (apt-get install qt5-qmake, NOT the qmake you generated by running configure script) to work with This way, you can pass the bluetooth function test and generate a Makefile for qtconnectivity module.

Modify the Makefile, change the QMAKE parameter. In my case, this is the result:

- QMAKE = /usr/lib/x86_64-linux-gnu/qt5/bin/qmake
+ QMAKE = /opt/qt-everywhere-opensource-src-5.7.0/qtbase/bin/qmake 

Then, you can cross-compile the whole Qt source by make && make install.

I’ve test the workaround, the example app (heartRate server) can work properly now. The annoying message “qt.bluetooth: Dummy backend running. Qt Bluetooth module is non-functional” is gone 🙂

User contributions licensed under: CC BY-SA
3 People found this is helpful