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:

[bluetooth]#

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#
 /org/bluez/hci0/dev_00_61_61_15_8D_60/service0001
 00001801-0000-1000-8000-00805f9b34fb
 Generic Attribute Profile
 [NEW] Characteristic
 /org/bluez/hci0/dev_00_61_61_15_8D_60/service0001/char0002
 00002a05-0000-1000-8000-00805f9b34fb
 Service Changed
 [NEW] Descriptor
 /org/bluez/hci0/dev_00_61_61_15_8D_60/service0001/char0002/desc0004
 00002902-0000-1000-8000-00805f9b34fb
 Client Characteristic Configuration
 [NEW] Primary Service
 /org/bluez/hci0/dev_00_61_61_15_8D_60/service000a
 0000180a-0000-1000-8000-00805f9b34fb
 Device Information
 [NEW] Characteristic
 /org/bluez/hci0/dev_00_61_61_15_8D_60/service000a/char000b
 00002a29-0000-1000-8000-00805f9b34fb
 Manufacturer Name String
 [NEW] Primary Service
 /org/bluez/hci0/dev_00_61_61_15_8D_60/service000d
 00001809-0000-1000-8000-00805f9b34fb
 Health Thermometer
 [NEW] Characteristic
 /org/bluez/hci0/dev_00_61_61_15_8D_60/service000d/char000e
 00002a1c-0000-1000-8000-00805f9b34fb
 Temperature Measurement
 [NEW] Descriptor
 /org/bluez/hci0/dev_00_61_61_15_8D_60/service000d/char000e/desc0010
 00002902-0000-1000-8000-00805f9b34fb
 Client Characteristic Configuration
 [NEW] Primary Service
 /org/bluez/hci0/dev_00_61_61_15_8D_60/service0011
 1d14d6ee-fd63-4fa1-bfa4-8f47b42119f0
 Vendor specific
 [NEW] Characteristic
 /org/bluez/hci0/dev_00_61_61_15_8D_60/service0011/char0012
 f7bf3564-fb6d-4e53-88a4-5e37e0326063
 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.