Skip to content

How to Use Legacy Bluetooth LE Beacons

Warning

This guide uses the deprecated Kura Bluetooth APIs. Please consider to use the new ones.

Overview

The Bluetooth Beacon example is a simple bundle for Eclipse Kura that allows you to configure a device as a Beacon. A Beacon device is a Bluetooth Low Energy device that broadcasts its identity to nearby devices. It uses a specific BLE packet, called beacon or advertising packet, that contains the following information:

  • Proximity UUID - a 128-bit value that uniquely identifies one or more beacons as a certain type or from a certain organization.

  • Major value - an optional 16-bit unsigned integer that can group related beacons with the same proximity UUID.

  • Minor value - an optional 16-bit unsigned integer that differentiates beacons with the same proximity UUID and major value.

  • Tx Power - a value programmed into the beacon that enables distance from the beacon to be determined based on signal strength.

The advertising packet has a fixed format and is broadcasted periodically. The information contained in the advertising packet can be used by a receiver, typically a smartphone, to identify the beacon and to roughly estimate its distance.

Prerequisites

For this tutorial a Raspberry Pi Type B with a LMTechnologies LM506 Bluetooth 4.0 dongle is used.

Beacon Advertising with hcitool

After the embedded device is properly configured, the advertising may be started using the hcitool command contained in the bluez packet.

Plug in the Bluetooth dongle if needed and verify that the interface is up with the following command:

sudo hciconfig hci0

If the interface is down, enable it with the following command:

sudo hciconfig hci0 up

To configure the advertising packet, enter the following command:

sudo hcitool -i hci0 cmd 0x08 0x0008 1e 02 01 1a 1a ff 4c 00 02 15 aa aa aa aa bb bb cc cc dd dd ee ee ee ee ee ee 01 00 01 00 c5

In this example, the packet will contain the uuid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee, major 1, minor 1 and Tx Power -59 dBm.

For further information about BLE commands and packet formats, refer to the Bluetooth 4.0 Core specifications

To set the advertising interval to 1 second, enter the following command:

sudo hcitool -i hci0 cmd 0x08 0x0006 a0 00 a0 00 03 00 00 00 00 00 00 00 00 07 00

Finally, to start the advertising, enter the following command: 

sudo hcitool -i hci0 cmd 0x08 0x000a 01
To verify that the embedded device is broadcasting its beacon, use a smartphone with a iBeacon scanner app (e.g., iBeacon Finder, iBeacon Scanner, or iBeaconDetector on Android).

To stop the advertising, write 0 to the register 0x000a as shown in the following command:

sudo hcitool -i hci0 cmd 0x08 0x000a 00

Beacon Advertising with Kura

The Beacon bundle is a simple example that allows you to configure the advertising packet, the time interval, and to start/stop the advertising.

Develop the Beacon Bundle

The Beacon bundle code development follows the guidelines presented in the Hello World Application :

  • Create a Plug-in Project named org.eclipse.kura.example.beacon.

  • Create the class BeaconExample.

  • Include the following bundles in the MANIFEST.MF:

  • org.eclipse.kura.bluetooth
  • org.eclipse.kura.configuration
  • org.osgi.service.component
  • org.slf4j

The following files need to be implemented in order to write the source code:

OSGI-INF/metatype/org.eclipse.kura.example.beacon.BeaconExample.xml File

The OSGI-INF/metatype/org.eclipse.kura.example.beacon.beaconExample.xml file describes the parameters for this bundle including the following:

  • enableAdvertising - enables Beacon advertising.

  • minBeaconInterval - sets the minimum time interval between beacons (milliseconds).

  • maxBeaconInterval - sets the maximum time interval between beacons (milliseconds).

  • uuid - defines a 128-bit uuid for beacon advertising expressed as hex string.

  • major - sets the major value.

  • minor - sets the minor value.

  • companyCode - defines a 16-bit company code as hex string.

  • txPower - indicates the transmission power measured at 1m away from the beacon expressed in dBm.

  • LELimited - defines the LE Discoverable Mode. Set false to advertise for 30.72s and then stops. Set true to advertise indefinitely.

  • BR_EDRSupported - indicates whether BR/EDR is supported.

  • LE_BRController - indicates whether LE and BR/EDR Controller operates simultaneously.

  • LE_BRHost - indicates whether LE and BR/EDR Host operates simultaneously.

  • iname - provides the name of bluetooth adapter.

org.eclipse.kura.example.beacon.BeaconExample.java File

The com.eurotech.example.beacon.BeaconExample.java file contains the activate and deactivate methods for this bundle. The activate method gets the BluetoothAdapter, enables the interface if needed, and executes the configureBeacon method that configures the device according to the properties. The following code sample shows part of the activate method:

// Get Bluetooth adapter with Beacon capabilities and ensure it is enabled
this.bluetoothAdapter = this.bluetoothService.getBluetoothAdapter(this.name, this);
if (this.bluetoothAdapter != null) {
    logger.info("Bluetooth adapter interface => {}", this.name);
    logger.info("Bluetooth adapter address => {}", this.bluetoothAdapter.getAddress());
    logger.info("Bluetooth adapter le enabled => {}", this.bluetoothAdapter.isLeReady());

    if (!this.bluetoothAdapter.isEnabled()) {
        logger.info("Enabling bluetooth adapter...");
        this.bluetoothAdapter.enable();
        logger.info("Bluetooth adapter address => {}", this.bluetoothAdapter.getAddress());
    }

    configureBeacon();

} else {
    logger.warn("No Bluetooth adapter found ...");
}

The configureBeacon (shown below) is a private method:

private void configureBeacon() {

    if (this.enable) {

        if (this.minInterval != null && this.maxInterval != null) {
            this.bluetoothAdapter.setBeaconAdvertisingInterval(this.minInterval, this.maxInterval);
        }
        this.bluetoothAdapter.startBeaconAdvertising();
        if (this.uuid != null && this.major != null && this.minor != null && this.companyCode != null
                && this.txPower != null) {
            this.bluetoothAdapter.setBeaconAdvertisingData(this.uuid, this.major, this.minor, this.companyCode,
                    this.txPower, this.leLimited, this.leLimited ? false : true, this.brSupported,
                    this.brController, this.brHost);
        }
    } else {
        this.bluetoothAdapter.stopBeaconAdvertising();
    }
}

Deploy and Validate the Bundle

In order to proceed, you need to know the IP address of your embedded gateway that is on the remote target unit. With this information, follow the mToolkit instructions for installing a single bundle to the remote target device located here. When the installation is complete, the bundle starts automatically.

In the Kura Gateway Administration Console, the BeaconExample tab appears on the left and enables the beacon to be configured for advertising.

You should see a message similar to the one below from /var/log/kura.log indicating that the bundle was successfully installed and configured.

2015-07-09 10:46:06,522 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.e.b.BeaconExample - Activating Bluetooth Beacon example...
2015-07-09 10:46:06,639 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.e.b.BeaconExample - Bluetooth adapter interface => hci0
2015-07-09 10:46:06,643 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.e.b.BeaconExample - Bluetooth adapter address => null
2015-07-09 10:46:06,645 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.e.b.BeaconExample - Bluetooth adapter le enabled => false
2015-07-09 10:46:06,664 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.e.b.BeaconExample - Enabling bluetooth adapter...
2015-07-09 10:46:06,745 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.e.b.BeaconExample - Bluetooth adapter address => 5C:F3:70:60:63:9E
2015-07-09 10:46:06,770 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.l.b.BluetoothAdapterImpl - Set Advertising Parameters on interface hci0
2015-07-09 10:46:06,842 [BluetoothProcess Input Stream Gobbler] INFO  o.e.k.l.b.l.b.BluetoothBeaconListener - Command ogf 0x08, ocf 0x0006 Succeeded.
2015-07-09 10:46:06,852 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.l.b.BluetoothAdapterImpl - Set Advertising Data on interface hci0
2015-07-09 10:46:06,859 [BluetoothProcess Input Stream Gobbler] INFO  o.e.k.e.b.BeaconExample - Command results :   01 06 20 00
2015-07-09 10:46:06,872 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.l.b.BluetoothAdapterImpl - Start Advertising on interface hci0
2015-07-09 10:46:06,906 [BluetoothProcess Input Stream Gobbler] INFO  o.e.k.l.b.l.b.BluetoothBeaconListener - Command ogf 0x08, ocf 0x0008 Succeeded.
2015-07-09 10:46:06,908 [BluetoothProcess Input Stream Gobbler] INFO  o.e.k.e.b.BeaconExample - Command results :   01 08 20 00
2015-07-09 10:46:06,921 [BluetoothProcess Input Stream Gobbler] INFO  o.e.k.l.b.l.b.BluetoothBeaconListener - Command ogf 0x08, ocf 0x000a Succeeded.
2015-07-09 10:46:06,923 [BluetoothProcess Input Stream Gobbler] INFO  o.e.k.e.b.BeaconExample - Command results :   01 0A 20 00
2015-07-09 10:46:06,947 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.c.c.ConfigurableComponentTracker - Adding ConfigurableComponent org.eclipse.kura.example.beacon.BeaconExample
2015-07-09 10:46:06,950 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.c.c.ConfigurationServiceImpl - Registration of ConfigurableComponent org.eclipse.kura.example.beacon.BeaconExample by org.eclipse.kura.core.configuration.ConfigurationServiceImpl@11120b6...
2015-07-09 10:46:06,996 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.c.c.ConfigurationServiceImpl - Registering org.eclipse.kura.example.beacon.BeaconExample with ocd: org.eclipse.kura.core.configuration.metatype.Tocd@8af8b3 ...
2015-07-09 10:46:06,999 [Component Resolve Thread (Bundle 6)] INFO  o.e.k.c.c.ConfigurationServiceImpl - Registration Completed for Component org.eclipse.kura.example.beacon.BeaconExample.

Note that the bundle writes the string returned by the configuration commands to the log:

2015-07-09 10:46:06,859 [BluetoothProcess Input Stream Gobbler] INFO  o.e.k.e.b.BeaconExample - Command results :   01 06 20 00

The last number of the string is the error code. A value of "00" indicates a successful command. Refer to the Bluetooth 4.0 Core specifications for a complete list of the error codes.

Once the bundle is deployed, you can use a iBeacon scanner app to detect the bundle. Also, you can modify the bundle properties and verify the results in the scanner.