Difference between revisions of "User:IanH"

From eLinux.org
Jump to: navigation, search
(Using Bluetooth LE with Python)
 
(8 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
* [[Serial port programming]]
 
* [[Serial port programming]]
 
* [[RPi_GPIO_Interface_Circuits]]
 
* [[RPi_GPIO_Interface_Circuits]]
 +
* [[RPi_Bluetooth_LE]]
 +
* [[RPi_GPIO_Code_Samples]]
  
Link to [[File:Circuit_Symbols.svg Circuit Symbols]]
+
==Bluetooth LE on the Raspberry Pi==
  
 +
The [https://www.raspberrypi.org/products/raspberry-pi-3-model-b/ Raspberry Pi 3] has built-in support for Bluetooth Low Energy (BLE). BLE is the technology behind many fitness trackers and smartwatches, and allows small, low-power devices to transmit and receive information from a central computer or smartphone.
 +
 +
This tutorial gets you started with Bluetooth Low Energy using a [http://www.ti.com/tool/cc2650stk Texas Instruments SensorTag] - these are small, robust, relatively cheap and do interesting things out of the box. You can buy one [http://www.ti.com/tool/cc2650stk#buy directly from TI], or in the UK they are available from [http://uk.rs-online.com/web/p/radio-frequency-development-kits/8735892/ RS] and [http://uk.farnell.com/texas-instruments/cc2650stk/evaluation-mod-simplelink-sensor/dp/2470181 Farnell].
 +
 +
=== Pre-requisites ===
 +
 +
This page assumes:
 +
* Raspberry Pi 3 Model B (older Pis will probably work with an external Bluetooth 4.0 dongle)
 +
* Raspbian Jessie (April 2017), although later versions will probably work.
 +
* TI CC2650 SensorTag, firmware 1.30 (May 2016) or later
 +
 +
We'll also assume you are familiar with the basics of typing Bash commands using the [https://www.raspberrypi.org/documentation/usage/terminal/ command line].
 +
 +
=== Basic installation checks ===
 +
 +
The Pi 3's built-in Bluetooth adapter is called ''hci0''. You can check it is operating correctly with the command:
 +
hciconfig
 +
 +
This should show something like this:
 +
hci0: Type: BR/EDR  Bus: UART
 +
BD Address: B8:27:EB:23:E2:A4  ACL MTU: 1021:8  SCO MTU: 64:1
 +
UP RUNNING
 +
RX bytes:1987 acl:0 sco:0 events:91 errors:0
 +
TX bytes:1647 acl:0 sco:0 commands:57 errors:0
 +
 
 +
If for some reason it is shown as <tt>DOWN</tt> you can re-enable it with:
 +
sudo hciconfig hci0 up
 +
 +
=== Scanning using <tt>hcitool</tt> ===
 +
 +
[[File:Sensortag-buttons.jpg|frameless|SensorTag with outer case removed]]
 +
 +
If you've not already done so, take a look at TI's [http://www.ti.com/ww/en/wireless_connectivity/sensortag/gettingStarted.html Getting Started Guide] which explains how to set up the SensorTag.
 +
 +
To wake it up, press the button on the left-hand side (see illustration) and the green LED should flash, once per second.
 +
 +
On the Pi, enter the command:
 +
  sudo hcitool lescan
 +
 +
This will start a scan for any Bluetooth LE devices in range which are currently 'advertising'. You should shortly see something like this:
 +
  pi@raspberrypi:~ $ sudo hcitool lescan
 +
  LE Scan ...
 +
  B0:B4:48:ED:44:C3 (unknown)
 +
  B0:B4:48:ED:44:C3 CC2650 SensorTag
 +
 +
Type Control-C to stop <tt>lescan</tt>. The 12 hexadecimal digits (<tt>B0:B4:48:ED:44:C3</tt> in the example) are your tag's MAC address. You will need to know this when making Bluetooth LE connections to it.
 +
 +
=== Connecting with <tt>gatttool</tt> ===
 +
 +
The <tt>gatttool</tt> utility can make connections to Bluetooth LE devices. To try this, make sure the SensorTag's LED is flashing then run:
 +
  gatttool -I -b <i>MAC-address</i>
 +
 +
where ''MAC-address'' is the value reported by <tt>hcitool</tt> (see above). <tt>gatttool</tt> will give you a prompt, ending <tt>[LE]&gt;</tt>. Type <tt>connect</tt> to make a connection to the SensorTag. This is shown below:
 +
 +
  pi@raspberrypi:~ $ gatttool -I -b B0:B4:48:ED:44:C3
 +
  [B0:B4:48:ED:44:C3][LE]> connect
 +
  Attempting to connect to B0:B4:48:ED:44:C3
 +
  Connection successful
 +
  [B0:B4:48:ED:44:C3][LE]>
 +
 +
You can then type a number of commands. The <tt>primary</tt> command lists the available 'Services', which are groups containing 'Characteristics' - these are data items which can be read or written to the device. So, to read the device name you could use the <tt>char-read-uuid</tt> command, giving it the ID of the Bluetooth [https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.characteristic.gap.device_name.xml Device Name characteristic]:
 +
 +
  [B0:B4:48:ED:44:C3][LE]> char-read-uuid 00002a00-0000-1000-8000-00805f9b34fb
 +
  handle: 0x0003 value: 53 65 6e 73 6f 72 54 61 67 20 32 2e 30
 +
 +
(These are the ASCII values for ''SensorTag 2.0''.
 +
 +
The Sensortag User Guide at http://processors.wiki.ti.com/index.php/CC2650_SensorTag_User's_Guide lists all the available services and characteristics. For example, to turn on the optical sensor, we need to discover the 'handle' for the configuration characteristic (with ID ''f000aa72-0451-4000-b000-000000000000''), then write an 0x01 byte to it:
 +
 +
  [B0:B4:48:ED:44:C3][LE]> characteristics 1 ffff f000aa72-0451-4000-b000-000000000000
 +
  handle: 0x0046, char properties: 0x0a, char value handle: 0x0047, uuid: f000aa72-0451-4000-b000-000000000000
 +
  [B0:B4:48:ED:44:C3][LE]> char-write-req 47 01
 +
  Characteristic value was written successfully
 +
 +
In the example above the handle value was 0x47 (it may change with firmware versions). One the sensor is enabled, the light level can then be read from characteristic ''f000aa71-0451-4000-b000-000000000000'':
 +
 +
  [B0:B4:48:BF:C9:83][LE]> char-read-uuid f000aa71-0451-4000-b000-000000000000
 +
  handle: 0x0044 value: bc 0a
 +
 +
In this example the light level bytes are ''bc 0a'', and will change with the amount of light falling on the CC2650 device.
 +
 +
 +
== Using Bluetooth LE with Python ==
 +
 +
=== Installing <tt>bluepy</tt> ===
 +
Using <tt>gatttool</tt> is very laborious for doing any useful work, so it's a good idea to use a programming language. The ''bluepy'' package is one way to use Bluetooth LE commands from Python - it can be installed from https://pypi.python.org/pypi using the <tt>pip</tt> command. If you don't already have <tt>pip</tt>, on the Pi or other Debian systems it is easily installed with:
 +
 +
  sudo apt-get install python-pip
 +
 +
Before installing ''bluepy'' you will also need some support libraries:
 +
 +
  sudo apt-get install libglib2.0-dev
 +
 +
Then you can run:
 +
 +
  sudo pip install bluepy
 +
 +
If successful, it will show a message such as this:
 +
 +
      Installing blescan script to /usr/local/bin
 +
      Installing sensortag script to /usr/local/bin
 +
  Successfully installed bluepy
 +
  Cleaning up... 
 
-----
 
-----
 +
 +
==Old==
 
BlueZ 5.4 build on Raspberry Pi
 
BlueZ 5.4 build on Raspberry Pi
  

Latest revision as of 07:21, 26 June 2017

In Cambridge, UK

Bluetooth LE on the Raspberry Pi

The Raspberry Pi 3 has built-in support for Bluetooth Low Energy (BLE). BLE is the technology behind many fitness trackers and smartwatches, and allows small, low-power devices to transmit and receive information from a central computer or smartphone.

This tutorial gets you started with Bluetooth Low Energy using a Texas Instruments SensorTag - these are small, robust, relatively cheap and do interesting things out of the box. You can buy one directly from TI, or in the UK they are available from RS and Farnell.

Pre-requisites

This page assumes:

  • Raspberry Pi 3 Model B (older Pis will probably work with an external Bluetooth 4.0 dongle)
  • Raspbian Jessie (April 2017), although later versions will probably work.
  • TI CC2650 SensorTag, firmware 1.30 (May 2016) or later

We'll also assume you are familiar with the basics of typing Bash commands using the command line.

Basic installation checks

The Pi 3's built-in Bluetooth adapter is called hci0. You can check it is operating correctly with the command:

hciconfig

This should show something like this:

hci0:	Type: BR/EDR  Bus: UART
	BD Address: B8:27:EB:23:E2:A4  ACL MTU: 1021:8  SCO MTU: 64:1
	UP RUNNING 
	RX bytes:1987 acl:0 sco:0 events:91 errors:0
	TX bytes:1647 acl:0 sco:0 commands:57 errors:0
 

If for some reason it is shown as DOWN you can re-enable it with:

sudo hciconfig hci0 up

Scanning using hcitool

SensorTag with outer case removed

If you've not already done so, take a look at TI's Getting Started Guide which explains how to set up the SensorTag.

To wake it up, press the button on the left-hand side (see illustration) and the green LED should flash, once per second.

On the Pi, enter the command:

 sudo hcitool lescan

This will start a scan for any Bluetooth LE devices in range which are currently 'advertising'. You should shortly see something like this:

 pi@raspberrypi:~ $ sudo hcitool lescan 
 LE Scan ...
 B0:B4:48:ED:44:C3 (unknown)
 B0:B4:48:ED:44:C3 CC2650 SensorTag

Type Control-C to stop lescan. The 12 hexadecimal digits (B0:B4:48:ED:44:C3 in the example) are your tag's MAC address. You will need to know this when making Bluetooth LE connections to it.

Connecting with gatttool

The gatttool utility can make connections to Bluetooth LE devices. To try this, make sure the SensorTag's LED is flashing then run:

 gatttool -I -b MAC-address

where MAC-address is the value reported by hcitool (see above). gatttool will give you a prompt, ending [LE]>. Type connect to make a connection to the SensorTag. This is shown below:

 pi@raspberrypi:~ $ gatttool -I -b B0:B4:48:ED:44:C3
 [B0:B4:48:ED:44:C3][LE]> connect
 Attempting to connect to B0:B4:48:ED:44:C3
 Connection successful
 [B0:B4:48:ED:44:C3][LE]>

You can then type a number of commands. The primary command lists the available 'Services', which are groups containing 'Characteristics' - these are data items which can be read or written to the device. So, to read the device name you could use the char-read-uuid command, giving it the ID of the Bluetooth Device Name characteristic:

 [B0:B4:48:ED:44:C3][LE]> char-read-uuid 00002a00-0000-1000-8000-00805f9b34fb
 handle: 0x0003 	 value: 53 65 6e 73 6f 72 54 61 67 20 32 2e 30 

(These are the ASCII values for SensorTag 2.0.

The Sensortag User Guide at http://processors.wiki.ti.com/index.php/CC2650_SensorTag_User's_Guide lists all the available services and characteristics. For example, to turn on the optical sensor, we need to discover the 'handle' for the configuration characteristic (with ID f000aa72-0451-4000-b000-000000000000), then write an 0x01 byte to it:

 [B0:B4:48:ED:44:C3][LE]> characteristics 1 ffff f000aa72-0451-4000-b000-000000000000
 handle: 0x0046, char properties: 0x0a, char value handle: 0x0047, uuid: f000aa72-0451-4000-b000-000000000000
 [B0:B4:48:ED:44:C3][LE]> char-write-req 47 01
 Characteristic value was written successfully

In the example above the handle value was 0x47 (it may change with firmware versions). One the sensor is enabled, the light level can then be read from characteristic f000aa71-0451-4000-b000-000000000000:

 [B0:B4:48:BF:C9:83][LE]> char-read-uuid f000aa71-0451-4000-b000-000000000000
 handle: 0x0044 	 value: bc 0a 

In this example the light level bytes are bc 0a, and will change with the amount of light falling on the CC2650 device.


Using Bluetooth LE with Python

Installing bluepy

Using gatttool is very laborious for doing any useful work, so it's a good idea to use a programming language. The bluepy package is one way to use Bluetooth LE commands from Python - it can be installed from https://pypi.python.org/pypi using the pip command. If you don't already have pip, on the Pi or other Debian systems it is easily installed with:

 sudo apt-get install python-pip

Before installing bluepy you will also need some support libraries:

 sudo apt-get install libglib2.0-dev

Then you can run:

 sudo pip install bluepy

If successful, it will show a message such as this:

     Installing blescan script to /usr/local/bin
     Installing sensortag script to /usr/local/bin
 Successfully installed bluepy
 Cleaning up...  

Old

BlueZ 5.4 build on Raspberry Pi

Standard Wheezy bluez package is 4.99 and doesn't have LE support.

wget https://www.kernel.org/pub/linux/bluetooth/bluez-5.4.tar.xz
xz -d bluez-5.4.tar.xz
tar xf bluez-5.4.tar
sudo apt-get install libglib2.0-dev
sudo apt-get install libdbus-1-dev libdbus-glib-1-dev
sudo apt-get install libusb-dev
sudo apt-get install libudev-dev
sudo apt-get install libical-dev
sudo apt-get install libreadline-dev
./configure --disable-systemd
make
sudo make install

Notes: Tests use: 2014-01-07-wheezy-raspbian.zip from http://downloads.raspberrypi.org/raspbian_latest