Overview

The Bluetooth Beacon example is a simple bundle for Eclipse Kura that allow 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 that have 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 : Value programmed into the beacon to facilitate determining distance from the beacon based on signal strength

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

Prerequisites

  • The development environment for ESF must be installed in order to develop the bundle. Follow the instructions here : Development Environment Setup.

  • Hardware
    • Use an embedded device running ESF with Bluetooth 4.0 (LE) capabilities.
  • bluez packet must be installed on the embedded device. Follow the installation instructions in How to Use Bluetooth LE.

For this tutorial a Raspberry Pi Type B with a LMTechnologies LM506 Bluetooth 4.0 http://lm-technologies.com/wireless-adapters/lm506-class-1-bluetooth-4-0-usb-adapter/ dongle is used.

Beacon advertising with hcitool

After the embedded device is properly configured, it is possible to start the advertising using the hcitool command contained in to the bluez packet. Plug in the Bluetooth dongle if needed and verify that the interface is up:

sudo hciconfig hci0

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

sudo hciconfig hci0 up

To configure the advertising packet, type 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 way, the packet will contain the uuid aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee, major 1, minor 1 and Tx Power -59 dBm.
For further informations about BLE commands and packet formats, refer to the Bluetooth 4.0 Core specifications

To set the advertising interval to 1 second, use 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, type the 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, write 0 to the register 0x000a:

sudo hcitool -i hci0 cmd 0x08 0x000a 00

Beacon advertising with ESF

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

Develop the Beacon Bundle

The develop of the code follows the guidelines presented in to the Hello World Example located here :

  • 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 - Enable Beacon advertising.

  • minBeaconInterval - Minimum time interval between beacons (milliseconds).

  • maxBeaconInterval - Maximum time interval between beacons (milliseconds).

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

  • major - Major value.

  • minor - Minor value.

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

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

  • LELimited - 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 - 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, enable the interface if needed and execute the configureBeacon method that configure the device according on the properties. The following code sample shows part of the activate method:

try {
	// Get Bluetooth adapter with Beacon capabilities and ensure it is enabled
	m_bluetoothAdapter = m_bluetoothService.getBluetoothAdapter(m_iname, this);
	if (m_bluetoothAdapter != null) {
		s_logger.info("Bluetooth adapter interface => " + m_iname);
		s_logger.info("Bluetooth adapter address => " + m_bluetoothAdapter.getAddress());
		s_logger.info("Bluetooth adapter le enabled => " + m_bluetoothAdapter.isLeReady());

		if (!m_bluetoothAdapter.isEnabled()) {
			s_logger.info("Enabling bluetooth adapter...");
			m_bluetoothAdapter.enable();
			s_logger.info("Bluetooth adapter address => " + m_bluetoothAdapter.getAddress());
		}

		configureBeacon();

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

The configureBeacon is a private method and it is shown below:

private void configureBeacon() {

	if (m_enable) {

		if (m_minInterval != null && m_maxInterval != null) {
			m_bluetoothAdapter.setBeaconAdvertisingInterval(m_minInterval, m_maxInterval);
		}

		if (m_uuid != null && m_major != null && m_minor != null && m_companyCode != null && m_txPower != null) {
			m_bluetoothAdapter.setBeaconAdvertisingData(m_uuid, m_major, m_minor, m_companyCode, m_txPower, m_LELimited, (m_LELimited) ? false : true,
					m_BRSupported, m_BRController, m_BRHost);
		}

		m_bluetoothAdapter.startBeaconAdvertising();
	}
	else
		m_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. Once you do, follow the mToolkit instructions for installing a single bundle to the remote target unit. When this installation completes, the bundle starts automatically. In the ESF web UI, the BeaconExample tab would be visible on the left. From here it is possible to configure the beacon advertising.
You should see a message similar to the one below from /var/log/esf.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 to the log the string returned by the configuration commands:

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: if it is “00” the command succedeed. See the Bluetooth 4.0 Core specifications for a complete list of the error codes.
Once the bundle is deployed, use a iBeacon scanner app to detect the bundle. Moreover, try to modify the bundle properties and see the result in the scanner.