about // doc

Use Bluetooth on Linux

Created: Mar, 2015;

Last modified: Mar, 2016

Bluez is a popular Bluetooth toolbox for Linux. At the time of writing, I am using Linux Mint 17 and Raspberry Pi.


Not surprisingly, the BlueZ source in Ubuntu and Debian is old. To get the latest features (e.g., those in Bluetooth V4.2), one can compile the whole thing from the latest source code.

First install the dependencies

sudo apt-get install libdbus-1-dev libdbus-glib-1-dev libglib2.0-dev libical-dev libreadline-dev libudev-dev libusb-dev make

Note that Bluez uses systemd which is not the default service manager in Ubuntu (it’s upstart). So I just skip installing systemd packages on Linux Mint to avoid potential headaches. Raspberry Pi Debian Linux uses systemd, so it should be okay. Download the latest Bluez source from Linux kernel’s website or Bluez download page. At the time of writing, the latest version is 5.29.

Next, install dependencies. For Ubuntu/Linux Mint

./configure --disable-systemd --enable-library

The first flag “–disable-systemd” disable compiling with systemd libraries since we will not use systemd anyway, otherwise you can get error like “configure: error: systemd system unit directory is required”. The second flag “–enable-library” installs Bluetooth library so that it is possible to develop your own BT applications in the future.

Finally, compile and install:

sudo make install 
sudo cp attrib/gatttool /usr/local/bin/

The last command installs gatttool system-wide since it is not automatically done in “make install”.

Play with Bluetooth Low Energy

I am mostly interested in Bluetooth Low Energy (BLE) applications which becomes part of the Bluetooth stack since V4.0. Since my computer does not have BLE capability, I get a CSR4.0 BLE USB adapter from Amazon (here) which works pretty well. Note that this device only implements BT V4.0 stack, thus not having new features in BT V4.1 and V4.2.

Insert the CSR4.0 BLE USB dongle, and make sure you see something similar to the following after “lsusb”:

Bus 002 Device 005: ID 0a12:0001 Cambridge Silicon Radio, Ltd Bluetooth Dongle (HCI mode)

View all BT devices on the computer by


I see the following:

hci1:	Type: BR/EDR  Bus: USB
	BD Address: 00:1A:7D:DA:71:13  ACL MTU: 310:10  SCO MTU: 64:8
	RX bytes:3447 acl:0 sco:0 events:153 errors:0
	TX bytes:730 acl:0 sco:0 commands:59 errors:0

hci0:	Type: BR/EDR  Bus: USB
	BD Address: CC:52:AF:E1:F6:06  ACL MTU: 1021:8  SCO MTU: 64:1
	RX bytes:1056 acl:0 sco:0 events:53 errors:0
	TX bytes:1433 acl:0 sco:0 commands:53 errors:0

It turns out hci0 is the native built-in BT module on my computer, and hci1 is the CSR4.0 BLE USB dongle. Right now hci1 is still in “down” mode while hci0 is running. Now bring hci1 up by

sudo hciconfig hci1 up

After another “hciconfig hci1”, you will see hci1 becomes:

hci1:	Type: BR/EDR  Bus: USB
	BD Address: 00:1A:7D:DA:71:13  ACL MTU: 310:10  SCO MTU: 64:8
	RX bytes:4005 acl:0 sco:0 events:181 errors:0
	TX bytes:1085 acl:0 sco:0 commands:87 errors:0

You can also list the active BT devices by

hcitool dev

which will return the MAC addresses of active BT devices attached to the computer, like

	hci1	00:1A:7D:DA:71:13
	hci0	CC:52:AF:E1:F6:06

Now we can do various things with hci1. For example, I have a SensorTag. I can scan the BLE devices by

sudo hcitool lescan

It will continuously output information about BLE peripheral devices to the console like:

BC:6A:29:AB:7B:1A SensorTag
BC:6A:29:AB:7B:1A SensorTag
BC:6A:29:AB:7B:1A SensorTag

Now I can test a BLE connection to my SensorTag by starting and dropping a connection like

sudo hcitool lecc BC:6A:29:AB:7B:1A

and it will return something like

Connection handle 72

meaning a connection was successful. Now close the connection:

sudo hcitool ledc 72

Configure Udev

By default the BLE dongle is inactive after being connected to the computer. Udev can help enable the device upon connection by adding this udev rule:

ACTION=="add", KERNEL=="hci1", RUN+="/usr/local/bin/hciconfig hci1 up"

Note that the path for “hciconfig” may be different on different systems. Be sure to check the path with “which”.


The real fun part is to connect to a BLE peripheral like SensorTag and interact with “gatttool”. Jared Wolff’s post covers some basic usage.

The CSR4.0 BLE USB dongle can also be used to capture the advertizing packet data from other BLE devices. See discussion in this thread.

There is also a Python package for interfacing BLE on the shoulder of Bluez here. The package seems still a little preliminary, but does provide the most needed basic features.

One can make an iBeacon device with this little BLE USB dongle. For example, piBeacon does exactly such thing.

[Update: Mar 2016]

I recommend a NodeJS package called Noble for BLE scripting. I find it much easier to use than existing alternatives.


comments powered by Disqus