Debugging Bluetooth LE Device Using bluetoothctl Tool Under Linux

First of all don’t bother with hcitool and hciconfig tools. They are deprecated. Use bluetoothctl to connect and test your Bluetooth LE devices. It’s an interactive command line utility that provides a convenient interface for testing and probing your devices. Here is a short introduction on how to connect to a LE device that implements “Health Thermometer Service” over GATT profile.

First, start the bluetoothctl tool. It starts as an interactive session, so rest of the commands will be entered into its prompt which appears like this:


You can enter “help” command to see a list of usable commands.

Enter “scan on” command to start the device discovery. This should print something like this if it finds your device:

[CHG] Controller E8:2A:EA:29:3E:6F Discovering: yes
 [NEW] Device 00:61:61:15:8D:60 Thermometer Example

To connect to the device use the “connect” command like this:

connect 00:61:61:15:8D:60

By the way, you can use TAB completion to quickly enter IDs, addresses etc.

This should print a success message and list the device characteristics right after that. In my case I had this response, but it will change depending on your device. By the way I’m using an example project that came with my Silabs bluetooth development kit.

Attempting to connect to 00:61:61:15:8D:60
 [CHG] Device 00:61:61:15:8D:60 Connected: yes
 Connection successful
 [NEW] Primary Service#
 Generic Attribute Profile
 [NEW] Characteristic
 Service Changed
 [NEW] Descriptor
 Client Characteristic Configuration
 [NEW] Primary Service
 Device Information
 [NEW] Characteristic
 Manufacturer Name String
 [NEW] Primary Service
 Health Thermometer
 [NEW] Characteristic
 Temperature Measurement
 [NEW] Descriptor
 Client Characteristic Configuration
 [NEW] Primary Service
 Vendor specific
 [NEW] Characteristic
 Vendor specific
 [CHG] Device 00:61:61:15:8D:60 UUIDs: 00001800-0000-1000-8000-00805f9b34fb
 [CHG] Device 00:61:61:15:8D:60 UUIDs: 00001801-0000-1000-8000-00805f9b34fb
 [CHG] Device 00:61:61:15:8D:60 UUIDs: 00001809-0000-1000-8000-00805f9b34fb
 [CHG] Device 00:61:61:15:8D:60 UUIDs: 0000180a-0000-1000-8000-00805f9b34fb
 [CHG] Device 00:61:61:15:8D:60 UUIDs: 1d14d6ee-fd63-4fa1-bfa4-8f47b42119f0
 [CHG] Device 00:61:61:15:8D:60 ServicesResolved: yes
 [CHG] Device 00:61:61:15:8D:60 Appearance: 0x0300

To get the list of characteristics you can use the “list-attributes” command, which should print the same list as above:

list-attributes 00:61:61:15:8D:60

To read an attribute you first select it, with the -you guessed it- “select-attribute” command:

select-attribute /org/bluez/hci0/dev_00_61_61_15_8D_60/service000a/char000b

After that you can issue the “read” command, without any parameters.

To read a characteristic continuously (if characteristic supports it) , use the “notify” command:

notify on

This should periodically print the characteristic value sent from the device. To stop run:

notify off

And disconnect with the “disconnect” command. So easy.


Leave a Reply

Your email address will not be published. Required fields are marked *