BLE Examples

Bluetooth Low Energy Examples

Many Technologic Systems' products off on-board support of WiFi and Bluetooth via a soldered down module. In applications without on-board support, Bluetooth connectivity can still be achieved with a USB dongle.

This document will focus only on products that use the on-board modules. While these examples should work just the same, external USB modules may require additional configuration and support that is not covered here. Additionally, these examples will only cover Bluetooth Low Energy and not Bluetooth Classic modes.

The primary provider of Bluetooth support in Linux is the BlueZ project. Additionally, many distributions provide their own releases of BlueZ packages so they do not need to be built from source.

Installing BlueZ

Note:

The following sections have been tested on products booting at least a 4.9 Linux kernel and Debian Stretch. Other systems may require additional steps.

Below we provide instructions for installing a binary version of BlueZ or building it from sources. Note that only one of the two should be performed. Doing both may result in an unstable system with conflicting binary versions.

Installing BlueZ from apt

At the time of writing this, Debian Stretch supplies BlueZ 5.43 which should be a new enough version for most applications. Additionally, BlueZ supplies a number of demo scripts that we will be using later to test functionality and demonstrate BLE connectivity.

The full compliment of binaries and utilities can be installed with:

apt-get update && apt-get install -y bluez bluez-test-tools bluez-test-scripts

This will install the example tools to /usr/share/doc/bluez-test-scripts/examples/ which we will use later.

Installing BlueZ from Source

At the time of writing this, version 5.54 is the latest BlueZ release. The following examples will download, build, and install BlueZ directly on the target device. Compilation directly on the device will be far slower but does not have the prerequisite of a properly set up cross build system. Cross compilation of BlueZ is possible, but is beyond the scope of this document.

First, since most of our products ship with BlueZ pre-installed from the distribution package manager, this will need to be removed:

apt-get purge "bluez"

Ensure all build requirements are met:

apt-get update && apt-get install -y git libglib2.0-dev libglib2.0-0 libdbus-1-dev libdbus-1-3 libudev-dev libudev1 libical-dev libical2 libreadline-dev libreadline7

Next, download the sources for BlueZ 5.54:

wget https://www.kernel.org/pub/linux/bluetooth/bluez-5.54.tar.xz
tar xvf bluez-5.54.tar.xz

Configure, build, and install BlueZ:

cd bluez-5.54
./configure --enable-library --enable-test --enable-deprecated && make install

From here, the example tools will be installed to /usr/local/lib/bluez/test/. We will be using this later.

Running the Examples

With BlueZ and the examples built and installed, it's now possible to start running some of the examples and using them for further development. Below, we highlight a few different examples.

However, before running any of the examples, the Bluetooth device must be up and enabled. See the specific device's manual's Bluetooth section for information and steps on how to bring up and enable the on-board Bluetooth device.

Additionally, most of the examples will require

Example GATT Server

The BlueZ example GATT server emulates a dummy device with a dummy battery. It demonstrates being able to do active reads of a BLE device as well as subscribing to push notifications from a device.