BLE Examples

Bluetooth Low Energy Examples

Many Technologic Systems' products offer 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.

Below, we have a set of instructions for both installing and using BlueZ with some of our products. Additionally, BlueZ provides a set of example scripts for testing functionality and for use as a starting point for development. The instructions below are split in to two main categories, installing BlueZ from Debian's APT repository, and installing it from source with the current latest available release. The process and locations of these two methods do differ, but ultimately they offer the same usability examples.

Note that only one of the two instruction sets should be followed, i.e. installing from APT or installing from source. Doing both may result in an unstable system with conflicting binary versions.

Note that all of the examples assume the unit is running at least Debian Stretch with at least a 4.9 kernel. Using older distributions or kernels may result in compatibility or functionality issues.

BlueZ from Debian APT

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.

BlueZ From Source

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
systemctl enable bluetooth
systemctl start bluetooth

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

Running the Examples (BlueZ From Source)

With BlueZ and its 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.

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.

However! If the instructions use the hciconfig command, do not run this command! The reason is that recent versions of BlueZ have moved to a more centralized control scheme using bluetoothd, running the hciconfig command in any way can cause the Bluetooth service to enter an invalid state. If needed, the use of hciattach is safe.

Additionally, most of the examples will require a compatible external device, e.g. a smartphone or other peripheral that is able to connect to other BLE nodes.

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.

Prerequisites

The example was tested against a smartphone with BLE capabilities, using a simple BLE monitor tool. The example requires the use of python and dbus, if not already installed, they can be installed with:

apt-get update && apt-get install -y python3-dbus

It is likely necessary to enable discovery of the local BLE device, this can be done with the following command:

hciconfig hci0 leadv 0

Running

Will have output similar to the following. Can read directly, supported peripherals can also "subscribe" to the battery service. Read requests will show up on the command line, subscription push actions will not.