RPi Bluetooth LE

= Bluetooth LE on the Raspberry Pi =

At the time of writing Bluetooth Low Energy (BLE) is not well supported by the standard Raspberry Pi distributions. Some work is required to get it working, as described below.

Software
This page has been tested using the Raspbian Wheezy distribution, in particular the image at: http://downloads.raspberrypi.org/raspbian/images/raspbian-2014-01-09/2014-01-07-wheezy-raspbian.zip

For reference, uname -a on the test system returned: Linux raspberrypi 3.10.25+ #622 PREEMPT Fri Jan 3 18:41:00 GMT 2014 armv6l GNU/Linux

Hardware
You will need a Bluetooth 4.0 compatible USB adapter to use with the Pi. The following devices have been tested:
 * Plugable USB-BT4LE adapter: http://plugable.com/products/usb-bt4le (uses BCM20702 chipset)
 * CSR chipset adapter http://www.amazon.co.uk/Version-Bluetooth-Adapter-Compatible-Windows/dp/B00A0CBOTE

BlueZ installation
By default, the Wheezy distribution comes without a Bluetooth stack. The bluez package is version 4.99, which has patchy support for Low Energy. You can build and install a more modern version as follows:

BlueZ 5.4 build instructions
Firstly, you'll need a download and install a number of development libraries. From a command prompt run: sudo apt-get install libdbus-1-dev libdbus-glib-1-dev libglib2.0-dev libical-dev libreadline-dev libudev-dev libusb-dev make

Then, download the source: mkdir -p work/bluepy cd work/bluepy wget https://www.kernel.org/pub/linux/bluetooth/bluez-5.4.tar.xz xz -d bluez-5.4.tar.xz tar xvf bluez-5.4.tar

If successful, you'll now have a bluez-5.4 source code directory on disk. To build it, do: cd bluez-5.4 ./configure --disable-systemd make

This will take half an hour or so. When this is done, do: sudo make install

USB Checks
To ensure the USB Bluetooth device is being seen, run lsusb

With the Plugable adapter shown above, the result will be similar to this: Bus 001 Device 002: ID 0424:9512 Standard Microsystems Corp. Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp. Bus 001 Device 004: ID 0a5c:21e8 Broadcom Corp.

The adapter is the one on Bus 001 Device 004. To show more information about the 'Broadcom' device, do: sudo lsusb -v -d 0a5c:

Using hcitool
If this is working, run the hciconfig tool: pi@raspberrypi ~ $ hciconfig hci0:	Type: BR/EDR Bus: USB BD Address: 00:02:72:14:27:0E ACL MTU: 1021:8  SCO MTU: 64:1 DOWN RX bytes:2715 acl:1 sco:0 events:146 errors:0 TX bytes:2500 acl:0 sco:0 commands:133 errors:0

If the bluetooth adapter (hci0 in the above example) is down as DOWN, you will need to enable it with: sudo hciconfig hci0 up

Scanning for LE devices
If you have any Bluetooth LE devices, you can start scanning for them with: sudo hcitool lescan

For the TI SensorTag, pressing the button on the side will ensure the device is awake and broadcasting advertising packets. Other LE devices may need a similar action - please consult the relevant user manual.

Testing connections
The lescan command above should have displayed the MAC address (six hex digits, like 00:1e:3f:22:4b:a7) of any Bluetooth LE devices in range and available for connection. You can check a particular device by attempting to make (and then drop) a connection to it, using a command like: sudo hcitool lecc 00:1e:3f:22:4b:a7

(Obviously, replace 00:1e ... with a MAC address from your lescan</tt> output).

Using Bluetooth LE from Python
You can communicate with Bluetooth LE devices from Python using the bluepy package. This is currently source code you need to build yourself; there isn't an official installer for it yet.

Fetch the source by changing directory to a suitable work area and running: git clone https://github.com/IanHarvey/bluepy.git

This should create a directory bluepy/</tt>. If you have already fetched all the packages needed in ''BlueZ 5.4 Build Instructions' above, you can build the source with just:

cd bluepy/bluepy make

If successful you will have built an executable bluepy-helper</tt>.

To test this, first ensure that hcitool lecc</tt> works (see above) so you can manually create a connection, then run btle.py</tt> giving it your peripheral's MAC address, e.g.

python btle.py 00:1e:3f:22:4b:a7

This will attempt to enumerate the services and characteristics presented by the device.

There is currently no official documentation for the bluepy module; you will need to use the Python source as example code.

Using Bluetooth LE with Go (Golang)
Gatt is a Go package, which provides developers to create BLE applications for Linux and OS X.

Developers install Go language on the host machine, and cross-compile the applications for RPi.

The package accesses HCI devices directly via HCI sockets provided by BlueZ core (kernel space), so it doesn't require the BlueZ userland package.

To test the example programs (sample GATT server and clients):
Cross-compile the server example for an ARMv6 target device. GOARCH=arm GOARM=6 GOOS=linux go build examples/server.go cp server

Start the server on the target device sudo ./server

Cross-compile the client example (discoverer) for an ARMv6 target device. GOARCH=arm GOARM=6 GOOS=linux go build examples/discoverer.go cp discoverer

Run the discoverer to scan surrounding peripheral devices. sudo ./discoverer

Links: other Bluetooth Low Energy resources

 * http://www.bluez.org/ - BlueZ stack announcements and downloads
 * https://www.bluetooth.org/en-us/specification/adopted-specifications - Bluetooth official specifications
 * -> Index of assigned numbers