hcitool and gatttool example
This guide will show you how to interact with a peripheral BLE device using BlueZ, a USB dongle, and TI's Sensor Tag. You can read TI's SensorTag User's Guide for an in depth description of how the hardware works. The device has a variety of sensors. In this example, I will be accessing the accelerometer data. My SensorTag has firmware rev 1.5
Check to see if you already have bluez installed with 'dpkg -s bluez'. If you get a message that says "package 'bluez' is not installed", run 'sudo apt-get install bluez'. You may also install bluez from the source code.
After installing bluez, you should have a program called hcitool. Hcitool is a CLI tool capable of detecting and connecting to peripheral devices. HCI stands for Host Controller Interface. Hit ths side button of the SensorTag to make it visible. Then use hcitool to find it
peter:~/Documents$ sudo hcitool lescan
BC:6A:29:AE:D8:12 SensorTag
You can also check to see addtional information a device might be advertising.
peter:~/Documents$ sudo hcitool leinfo BC:6A:29:AE:D8:12
Requesting information ...
Handle: 64 (0x0040)
LMP Version: 4.0 (0x6) LMP Subversion: 0x140
Manufacturer: Texas Instruments Inc. (13)
Features: 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00
You can connect to the SensorTag with hcitool,
peter:~/Documents/blue/bluezDoc.wiki$ sudo hcitool lecc BC:6A:29:AE:D8:12
Connection handle 64
and disconnect.
peter:~/Documents/blue/bluezDoc.wiki$ sudo hcitool ledc 64
We can discover, read, and write characteristics with gatttool. GATT stands for Generic Attribute and defines a data structure for organizing characteristics and attributes. Launch gatttool in interactive mode.
peter:~/Documents$ gatttool -I
[ ][LE]>
Use the MAC address you discovered with hcitool to connect to the SensorTag
[ ][LE]> connect BC:6A:29:AE:D8:12
Attempting to connect to BC:6A:29:AE:D8:12
Connection successful
[BC:6A:29:AE:D8:12][LE]>
Use the command characteristics to see all the available characteristics we can read data from. We are also given the characteristic's properties. These are bit masked values that tell us read/write capabilities and permission requirements. To understand these values and become a BLE guru, you can read the core specification.
Bluetooth characteristics have UUIDs (universal unique identifier) which describe the type of data. The 16-bit UUID of the SensorTag's accelerometer data is 0xAA11, and the bit-masked axis enable UUID is 0xAA12. These 16 bit UUIDs are embedded in TI's base UUID to form a 128 bit UUID. Reading these characteristics shows that nothing is enabled initially
[BC:6A:29:AE:D8:12][LE]> char-read-uuid f000aa11-0451-4000-b000-000000000000
handle: 0x0030 value: 00 00 00
[BC:6A:29:AE:D8:12][LE]> char-read-uuid f000aa12-0451-4000-b000-000000000000
handle: 0x0034 value: 00
Alternatively, we can read characteristics by their handle.
[BC:6A:29:AE:D8:12][LE]> char-read-hnd 30
Characteristic value/descriptor: 00 00 00
[BC:6A:29:AE:D8:12][LE]> char-read-hnd 34
Characteristic value/descriptor: 00
Enable the axis and try reading again
[BC:6A:29:AE:D8:12][LE]> char-write-cmd 34 07
[BC:6A:29:AE:D8:12][LE]> char-read-hnd 30
handle: 0x0030 value: 00 f0 02
The accelerometer characteristic has the "notify" property which means it will notify us whenever the data changes. This is handy for low power applications where we what to know change has occurred without constantly requesting new data wirelessly. The SensorTag is configured to send notifications on a periodic basis. The notification enable will always be the characteristic directly following the data i.e. the data is at handle 30, the enable is at 31. The notification enable is a 2-byte value that can be 1 or 0, and data is transmitted in little endian format. We want to write 0x0001 to characteristic handle 0x31.
[BC:6A:29:AE:D8:12][LE]> char-write-cmd 31 0100
Notification handle = 0x0030 value: 00 f0 02
Notification handle = 0x0030 value: 00 f0 01
Notification handle = 0x0030 value: 00 f0 02
Notification handle = 0x0030 value: 00 f0 02
Advanced Mode
You can get the UUID's of a range of characteristic handles with gatttool.
[BC:6A:29:AE:D8:12][LE]> char-desc 2F 35
handle: 0x002f, uuid: 00002803-0000-1000-8000-00805f9b34fb
handle: 0x0030, uuid: 0000aa11-0000-1000-8000-00805f9b34fb
handle: 0x0031, uuid: 00002902-0000-1000-8000-00805f9b34fb
handle: 0x0032, uuid: 00002901-0000-1000-8000-00805f9b34fb
handle: 0x0033, uuid: 00002803-0000-1000-8000-00805f9b34fb
handle: 0x0034, uuid: 0000aa12-0000-1000-8000-00805f9b34fb
handle: 0x0035, uuid: 00002901-0000-1000-8000-00805f9b34fb
[BC:6A:29:AE:D8:12][LE]> char-read-hnd 32
Characteristic value/descriptor: 41 63 63 65 6c 2e 20 44 61 74 61
0x2901 is the characteristic UUID of a user description of the preceding characteristic data. Reading its data gave us ASCII bytes which translate to "Accel. Data" which describes what that data at handle 0x30 is.