#1 – Experimenting with Web Bluetooth API and Bluetooth Low Energy Programming

This is the first post among the series of posts I am planning to write regarding the concepts and technologies I learned or “going to learn” in my GSOC 2017 journey. May 5 to 29 is the community bonding period and in this period I am supposed to procure the necessary skills, technologies and knowledge so that I can start coding from 30th May. In this post, I describe my first encounter with Google’s Web Bluetooth API and how to access services in a Bluetooth Low Energy device using Web Bluetooth API.

The Web Bluetooth API

Th Web Bluetooth API allows websites to communicate with nearby Bluetooth devices and access various services and data available in the device. Web Bluetooth is still in its infancy and it is available in latest Chrome browsers (v 56+) in Linux, Android 6+ and Mac. Also note that, Web Bluetooth can only access devices operating in Bluetooth Low Energy (BLE) mode. BLE is available from Bluetooth v4.0 onwards and it is fundamentally different from the old Classic Bluetooth which most of us are familiar with. BLE is widely used in device to device and device to gateway communication in IoT (Internet of Things) because of it’s “Low Energy” requirements.

More information about Web Bluetooth can be found here and here.

Setting up Chromium Browser

I use Linux Mint as my primary Operating System in my Laptop. In Android and Mac the Web Bluetooth is enabled by default, and if you have a BLE capable device and latest chrome browser, you are good to go. But in Linux, you have to perform a little bit of manual tinkering before you can fiddle with Web Bluetooth.

Update Bluez to Latest Version

The Chromium browser in Linux uses the Bluez stack, or specifically the “Bluez D-Bus API” to interact with Bluetooth devices. Bluez is the official Bluetooth stack of Linux and it comes pre-installed in most of the Linux distributions. But if you are using an older version of Linux, chances are there that you are using an older version of Bluez in which Bluetooth Low Energy specification is not fully implemented.

To check the version of Bluez run the command:

bluetoothctl --version

I was having the version 5.37 of Bluez which had a buggy implementation of BLE.

So, I updated it to the latest version available (5.45 as of now). You can download the latest source code from their web site: http://www.bluez.org/

Bluez has some dependency, so those packages must be installed first:

– GCC compiler
– GLib library
– D-Bus library
– udev library (optional)
– readline

Some of these were already installed in my system and I end up installing the following additional packages:

sudo apt-get install build-essential libglib2.0-dev\ 
libreadline-dev libdbus-1-dev libudev-dev libical-dev

Now, extract and install Bluez:

tar -xf bluez-X.XX.tar.xz
cd bluez-X.XX
./configure
make
sudo make install

Now you verify the installation by checking the version number again.

Enable experimental mode in Bluez

Some of the BLE features which are still in development are not enabled by default in Bluez. To enable them, open the file bluetooth.service in a text editor.

sudo gedit /lib/systemd/system/bluetooth.service

The contents of the file will be something similar to below:

[Unit]
Description=Bluetooth service
Documentation=man:bluetoothd(8)
ConditionPathIsDirectory=/sys/class/bluetooth

[Service]
Type=dbus
BusName=org.bluez
ExecStart=/usr/local/libexec/bluetooth/bluetoothd
NotifyAccess=main
#WatchdogSec=10
#Restart=on-failure
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
LimitNPROC=1
ProtectHome=true
ProtectSystem=full

[Install]
WantedBy=bluetooth.target
Alias=dbus-org.bluez.service

All we have to do is to add an –experimental flag to the line 9:

[Unit]
Description=Bluetooth service
Documentation=man:bluetoothd(8)
ConditionPathIsDirectory=/sys/class/bluetooth

[Service]
Type=dbus
BusName=org.bluez
ExecStart=/usr/local/libexec/bluetooth/bluetoothd --experimental
NotifyAccess=main
#WatchdogSec=10
#Restart=on-failure
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
LimitNPROC=1
ProtectHome=true
ProtectSystem=full

[Install]
WantedBy=bluetooth.target
Alias=dbus-org.bluez.service

Now, save the file and restart the Bluetooth service:

sudo systemctl daemon-reload
sudo systemctl restart bluetooth

Enable Experimental Web Platform features in Chromium Browser

As I mentioned earlier, in Linux, to get Web Bluetooth features we have to enable the Experimental Web Platform Features flag.

To do so, go this URL in Chromium:

chrome://flags/#enable-experimental-web-platform-features

And press the Enable button.

Some Hello world Web Bluetooth Programs

Now that we have the chromium browser ready for testing Web Bluetooth, assuming you have a Bluetooth 4.0+ adapter attached to your machine, it is time to try out some sample codes.

navigator.bluetooth.requestDevice({ filters: [{ services: ['battery_service'] }] })
.then(device => device.gatt.connect())
.then(server => {
  // Getting Battery Service...
  return server.getPrimaryService('battery_service');
})
.then(service => {
  // Getting Battery Level Characteristic...
  return service.getCharacteristic('battery_level');
})
.then(characteristic => {
  // Reading Battery Level...
  return characteristic.readValue();
})
.then(value => {
  console.log('Battery percentage is ' + value.getUint8(0));
})
.catch(error => { console.log(error); });

This code is taken from the Google Developers website and using it you can read the battery level of your BLE device. Your device need to have a battery service implemented in order for this code to work properly.

Some more example programs are available here: https://googlechrome.github.io/samples/web-bluetooth/

Building Simulated BLE Peripheral with a Custom Location Service

My GSOC – 2017 project is about building an indoor navigation system using BLE beacons and Web Bluetooth API. As I don’t have any real beacons with me I decided to create a simulated BLE beacon (peripheral) in my laptop, effectively turning my laptop’s BLE adapter to a beacon.

I have used the Bleno library by Sandeep Mistry to build the peripheral device.

The code is available here: https://github.com/vipinraj/pw-hospital-routing/tree/master/Learning/location-beacon

Also, a sample web application which, using the Web Bluetooth API, read the location data from the peripheral and display the corresponding map is created.

Code: https://github.com/vipinraj/pw-hospital-routing/tree/master/Learning/physical-web-sample-web-app

The web application requires MongoDB to be installed. Before login, simply register a user.

Note that, you have to have two BLE adapters to run these programs, one for the peripheral and one for the Web App.

So, thats it for now. In the coming days I have to do the following:

1. Figure out how to create custom Indoor Maps, possibly using Open Layers and Geo Server.
2. Create some UI Prototypes for the Web application I am supposed to build during the next three months.