What Data Does an iBeacon Advertise?

The iBeacon standard uses the optional manufacturer data (Extended Inquiry Response data type 0xFF) section of the GAP advertising specification to broadcast 25 bytes of data. More information on the manufacturer data section and GAP can be found in the Bluetooth Core Specification.

Here is an example of the data advertised followed by a description of each part:

4C00 02 15 B9407F30F5F8466EAFF925556B57FE6D ED4E 8931 B6

• The first two bytes are the Apple Company Identifier (little-endian) 0x004C.

• The third byte has a value of 2, which specifies that the data type is iBeacon.

• The fourth byte, 0x15, specifies the remaining data length, which is 21 (0x15) bytes.

• The next 16 bytes contain the iBeacon UUID, B9407F30-F5F8-466E-AFF9-25556B57FE6D.

• The two bytes after the iBeacon UUID are the iBeacon Major (big-endian); i.e., 0xED4E, 60750.

• The two bytes after the iBeacon Major are the iBeacon Minor (big-endian); i.e., 0x8931, 35121.

• The final byte is the measured received signal strength indication (RSSI) at 1 meter away; i.e., 0xB6, -74. You need to take its 2’s complement to convert the byte value into a signed number.

Three of the properties create the beacon’s identity. These are:

UUID

This is a property that is unique to each company; in most use cases, the same UUID would be given to all beacons deployed by a company (or group).

Major

The property you use to specify a related set of beacons (e.g., all the beacons in one store would share the same Major value).

Minor

The property that you use to specify a particular beacon in a location.

The measured RSSI at 1 meter away is used by the central to estimate proximity to the beacon. This value is used with the RSSI measured by the central when it detects the iBeacon’s advertisement. A beacon with a lower (more negative) value further away than a beacon with a larger (less negative) RSSI value.

Building and Detecting a Beacon

Let’s create an iBeacon with Node.js and use a smartphone to detect it.

We’ll use the node-bleacon module using Node.js. It uses bleno for the BLE layer.

The source code and documentation for node-bleacon can be found on GitHub.

First, make a new directory for the project, and change the current directory to it:

$ mkdir make-bluetooth-ibeacons
$ cd make-bluetooth-ibeacons

Next, install the bleacon module from npm:

$ npm install bleacon

This command will create a node_modules folder in the current directory and pull the bleacon module, along with its dependencies including bleno, down from npm.

Now create a new file called advertise.js and open it using your favorite text editor.

At the start of the file, require the bleacon module:

var Bleacon = require('bleacon');

Next, set up some variables to store the iBeacon’s UUID, major, minor, and measure-powered values:

var uuid = 'E2C56DB5-DFFB-48D2-B060-D0F5A71096E0';
var major = 1;
var minor = 2;
var measuredPower = -59;

Now we can use the startAdvertising provided by Bleacon to start advertising:

console.log('starting advertising ...');
Bleacon.startAdvertising(uuid, major, minor, measuredPower);

We are all set to run the advertise.js script now.

On a Mac:

$ node advertise.js

On Linux, sudo is needed:

$ sudo advertise.js

To detect the beacon, we need an application on our BLE-equipped smartphone. Go ahead and install the Locate Beacon app by Radius Networks on your smartphone:

• iOS

• Android

Once you open the app on iOS, you will be prompted for permission to access your location (as shown in Figure 10-1, left); make sure to select Allow. This prompt will not be present when using an Android device.

Now a prompt for sharing iBeacon data will appear (Figure 10-1, right). Select NO.

Figure 10-1. Left: Location permissions screen of the Locate Beacon app; Right: Share iBeacon data screen of the Locate Beacon app

The Main screen for the app is shown (Figure 10-2, left). Press the Locate iBeacons button to start the beacon-scanning process.

A screen showing that no beacons are in range will appear next (Figure 10-2, right), followed by a beacon being detected (Figure 10-3).

Figure 10-2. Left: Main screen of the Locate Beacon app; Right: A screen showing that no beacons were found

Figure 10-3. Main screen of the Locate Beacon app

Tap the row for a beacon to select it. You will see the iBeacon’s RSSI and proximity (Figure 10-4, left). The proximity field can have one of the following values: immediate, near, and far. Walk further and closer to your iBeacon to see the proximity value change.

The measure-powered value for our beacon was arbitrarily selected. We can use the calibration feature of the Locate Beacon app to get a more accurate reading. Press the Calibrate button (Figure 10-4, right).

Figure 10-4. Left: The iBeacon details screen of the Locate Beacon app; Right: The iBeacon Calibration screen of the Locate Beacon app

Once you are about one meter away from your iBeacon, press the Calibrate button again to start the calibration progress, as shown in Figure 10-5 (left).

After 30 to 60 seconds, the app will recommend a measured-power value to use. In this particular session (Figure 10-5, right), -49 was recommended. Go ahead and update your advertise.js file with the recommended value. Then exit and rerun the script.

Figure 10-5. Left: Screen showing that the iBeacon is calibrating; Right: Screen showing that the iBeacon was calibrated

Creating a Mobile App that Uses iBeacons

Let’s create a mobile app that detects the specific iBeacon we created earlier. We will use PhoneGap with an iBeacon plugin named cordova-plugin-ibeacon.

Source code and documentation for the cordova-plugin-ibeacon can be found on GitHub.

There are two modes to detect iBeacons:

Ranging

Used to detect iBeacons in range and periodically get their proximity (immediate, near, far). Ranging can only be used when the app is running in the foreground.

Region monitoring

Used to detect if you are inside or outside an iBeacon region. Region monitoring can be used when the app is running in the foreground, as well as in background mode.

On iOS, both modes require the user to grant your app access to your location. Android apps only require permissions to access Bluetooth hardware.

The cordova-plugin-ibeacon plugin maps the modes to the following APIs for starting and stopping:

• cordova.plugins.locationManager.startMonitoringForRegion(beaconRegion)

• cordova.plugins.locationManager.stopMonitoringForRegion(beaconRegion)

• cordova.plugins.locationManager.startRangingBeaconsInRegion(beaconRegion)

• cordova.plugins.locationManager.stopRangingBeaconsInRegion(beaconRegion)

Both APIs require a beaconRegion parameter, which can be constructed from a UUID, identifier, optional major value, and optional minor value. If the major and/or minor is not provided, they are set to wildcard values so that any iBeacon with the UUID or UUID and major in range is reported.

var uuid = 'E2C56DB5-DFFB-48D2-B060-D0F5A71096E0';
var identifier = 'region';
var major = 1;
var minor = 2;

var beaconRegion = new cordova.plugins.locationManager.BeaconRegion(identifier, uuid, major, minor);

You also need to set up and assign a delegate to receive updates from the location manager. You have the option of overriding any of the default delegate methods.

A new location manager delegate can be created by using new cordova.plugins.locationManager.Delegate(). Then the default delegate methods for ranging and region monitoring can be over-ridden by setting the didRangeBeaconsInRegion and didDetermineStateForRegion properties. The setDelegate method of the location manager is then used to assign the delegate to the location manager.

var delegate = new cordova.plugins.locationManager.Delegate();

delegate.didRangeBeaconsInRegion = function(pluginResult) {
    // ...
};

delegate.didDetermineStateForRegion = function(pluginResult) {
    // ...
};

cordova.plugins.locationManager.setDelegate(delegate);

Let’s create a region timer app to track how long we are in a beacon region. This could be used as a desk timer, for example. We only need to use the region-monitoring APIs for this app.

Start off by creating a new PhoneGap app, which we’ll call Region Timer:

phonegap create regiontimer "com.makebluetooth.regiontimer" "Region Timer"

Then change directories to a newly created folder:

cd regiontimer

If you have an iOS device, add iOS as a platform using the following command:

phonegap platform add ios

To use with an Android device, use the following command:

phonegap platform add android

For Android, you will also need to update the config.xml file to update the android-minSdkVersion from 7 to 10 by changing the following line from:

    <preference name="android-minSdkVersion" value="7" />

to:

    <preference name="android-minSdkVersion" value="10" />

Now add the plug in to the PhoneGap app:

phonegap plugin add phonegap plugin add https://github.com/petermetz/cordova-plugin-ibeacon.git#3.3.0

Open up www/index.html in a text editor and change the contents for the <div class="app"> tag to:

<div id="totalTimeInRegion"></div>

We will use this div to display the total time spent in the region.

We are done with editing index.html for now. Now, to work on the JavaScript side, open www/js/index.js in a text editor.

Let’s remove some of the code that we don’t need anymore. Delete the app.receivedEvent(deviceready); line in the onDeviceReady function, as well as the entire receivedEvent function.

We need to create and set up a location manager as we did earlier. Create a new function named setupLocationManager:

setupLocationManager: function() {
}

The first thing we need to do is create a beacon region to monitor for the iBeacon UUID, major, and minor we created. We will use region as the identifier.

var uuid = 'E2C56DB5-DFFB-48D2-B060-D0F5A71096E0';
var identifier = 'region';
var major = 1;
var minor = 2;

var beaconRegion = new cordova.plugins.locationManager.BeaconRegion(identifier, uuid, major, minor);

Now create and assign a delegate to the Location Manager:

var delegate = new cordova.plugins.locationManager.Delegate();

cordova.plugins.locationManager.setDelegate(delegate);

On iOS 8 and above, we need to request authorization, including for background mode:

cordova.plugins.locationManager.requestAlwaysAuthorization();

Now we can start region monitoring:

cordova.plugins.locationManager.startMonitoringForRegion(beaconRegion);

The onDeviceReady also needs to be updated to call app.setupLocationManager to set up the location manager:

// ...
onDeviceReady: function() {
    app.setupLocationManager();
},
// ...

We don’t have anything to handle iBeacon region events, so we’ll create a new function called didDetermineStateForRegion. We can assign it to the delegate in the setupLocationManager function:

setupLocationManager: function() {
    // ...
    var delegate = new cordova.plugins.locationManager.Delegate();
    delegate.didDetermineStateForRegion = app.didDetermineStateForRegion;


    // ...
}

Let’s create the didDetermineStateForRegion function now. It will have one argument, pluginResult, which is a state property that contains the state of the region. When it is set to 'CLRegionStateInside', the device is in the beacon region; otherwise, the device is outside the region. We’ll update the app.insideRegion value accordingly.

didDetermineStateForRegion: function(pluginResult) {
    var regionState = pluginResult.state;

    if (regionState === 'CLRegionStateInside') {
        app.insideRegion = true;
    } else {
        app.insideRegion = false;
    }
}

Now the app.insideRegion property reflects whether we are inside the iBeacon region. Let’s create another function named updateTotalTimeInRegion that uses this property. It will first get the current time, and check if the user is in the region. When the user is in the region, it will update the total time in the region since the last update. The last update date will also be set to the current time.

updateTotalTimeInRegion: function() {
    var now = new Date();

    if (app.insideRegion) {
        var secondsSinceLastUpdate = (now.getTime() - app.lastUpdateDate.getTime()) / 1000.0;

        app.totalTimeInRegion += secondsSinceLastUpdate;
    }

    app.lastUpdateDate = now;
}

We also need to initialize the app properties in the initialize function:

// ...

initialize: function() {
    this.bindEvents();

    this.insideRegion = false;
    this.lastUpdateDate = null;
    this.totalTimeInRegion = 0;
},

// ...

Then we need to update onDeviceReady to set up a timer to call the new app.updateTotalTimeInRegion function every second (1,000 milliseconds). We can use setInterval for this.

// ...
onDeviceReady: function() {
    app.setupLocationManager();

    setInterval(app.updateTotalTimeInRegion, 1000);
},
// ...

This will ensure the total time in the region is updated every second, based on the value of app.insideRegion. If the user is not in the region, the app.totalTimeInRegion will remain the same. However, when the user is in the region, the value of app.totalTimeInRegion will be updated based on the time that has passed since the last update (usually one second).

We also need to update both onDeviceReady and didDetermineStateForRegion to call the app.updateTotalTimeInRegion when the app starts.

// ...
onDeviceReady: function() {
    // ...

    app.updateTotalTimeInRegion();
},
// ...
didDetermineStateForRegion: function(pluginResult) {
    // ...
    app.updateTotalTimeInRegion();
},
// ...

This will initialize things on app start and immediately update the time whenever the beacon region is entered or exited. Without this change, it would take about a second for the value to be updated.

Now app.totalTimeInRegion will be updated every time we enter and exit the beacon region. We need to display the total time in the app, so create a new function named displayTotalTimeInRegion.

The displayTotalTimeInRegion function will first split up totalTimeInRegion from seconds to hours, minutes, and seconds. Then create a string to display in the app, in the totalTimeInRegion element.

displayTotalTimeInRegion: function() {
    var hours = Math.floor(app.totalTimeInRegion / 3600);
    var minutes = Math.floor((app.totalTimeInRegion % 3600) / 60);
    var seconds = Math.floor(app.totalTimeInRegion % 60);

    var totalTimeInRegionText = 'Hours: ' + hours + ' ' +
                                'Minutes: ' + minutes + ' ' +
                                'Seconds: ' + seconds;

    document.getElementById('totalTimeInRegion').textContent = totalTimeInRegionText;
}

We are all set to run the initial version of our region timer app. Plug your iOS or Android device into your computer using a USB cable, and run the following command:

phonegap run --device

On iOS when the app launches, you will be prompted to allow location access (Figure 10-6). Press Allow to grant access; pressing Don’t Allow will cause our app to not work.

Figure 10-6. Location permissions screen of the Region Timer app

The app will then go the the main screen, showing 0 time in the region (Figure 10-7).

Figure 10-7. The Region Timer app showing that our device is idle

Once you start the Node.js iBeacon advertise.js script, the mobile app will start updating the time spent in the region (Figure 10-8).

Figure 10-8. The Region Timer app showing that our device is running

After you stop advertise.js, it will take about 30 seconds for the location manager to report that you are no longer in the region. This is because of the built-in debounce logic.

You can restart advertise.js and experiment with the distance limits by walking further away from your beacon to get a better idea of the area that the iBeacon region covers. When you’re far enough away, the timer will stop.

The app will also continue to work when it’s running in the background. Go to the homescreen after launching the app, and walk in and out of the region. When you foreground the app, the time value will be updated accordingly. Keep in mind that it is only an estimate.

Let’s add one final feature to the app, a reset button, to reset the time to zero.

Update the <div class="app"> in www/index.html so it looks like the following:

<div class="app">
    <div id="totalTimeInRegion"></div>
    <button id="reset">Reset</button> 
</div>

New reset button

Then update the onDeviceReady function in www/js/index.js and add a click event listener for the reset button. We’ll make a new function named onResetClick to handle the event. The onResetClick will reset app.totalTimeInRegion to 0, and then call app.updateTotalTimeInRegion.

// ...
onDeviceReady: function() {
    // ...
    document.getElementById('reset').addEventListener('click', app.onResetClick, false);
},
// ...
onResetClick: function() {
    app.totalTimeInRegion = 0;

    app.updateTotalTimeInRegion();
}

When you run the updated app, a reset button will be displayed under the timer value (Figure 10-9).

Figure 10-9. The main screen of the Region Timer app with a reset button

The time in the region will be reset back to 0 when the button is tapped.

What Data Does an Eddystone Beacon Advertise?

Unlike iBeacon, Eddystone beacons use the service data type to broadcast information during advertisement.

The specification requires the following to be broadcasted:

• GAP flags with a value of 0x06

• A service UUID of 0xFEAA

• Service data for the 0xFEAA UUID

The service data has a different format for each sub-beacon type.

00 EC 01020304050607080910 AABBCCDDEEFF 0000

10 EE 0061626307

Building and Detecting Your Own Beacon

We’ll be focusing on Eddystone-URL beacons for the remainder of the chapter.

Let’s create an Eddystone-URL beacon using Node.js and use a smartphone to detect it.

We’ll use the node-eddystone-beacon module using Node.js. It uses bleno for the BLE layer.

The source code for node-eddystone-beacon can be found on the following GitHub repo.

First, make a new directory for the project, and change the current directory to it:

$ mkdir make-bluetooth-physical-web
$ cd make-bluetooth-physical-web

Next, install the eddystone-beacon module from npm:

$ npm install eddystone-beacon

This command will create a node_modules folder in the current directory and pull the eddystone-beacon module along with its dependencies, including bleno, down from npm.

Now create a new file called advertise.js and open it using your favorite text editor.

At the start of the file, we need to require the eddystone-beacon module:

var EddystoneBeacon = require('eddystone-beacon');

Next, let’s create a variable for the URL we wish to broadcast using the Eddystone-URL format:

var url = 'http://example.com';

Now we can use the advertiseUrl API provided by EddystoneBeacon to start advertising the URL:

EddystoneBeacon.advertiseUrl(url);

We are all set to run the advertise.js script now.

On a Mac:

$ node advertise.js

On Linux, sudo is needed:

$ sudo node advertise.js

To detect the beacon, we need an application on our BLE-equipped smartphone. Go ahead and install the Physical Web app on your smartphone:

• Physical Web for iOS

• Physical Web for Android

When you first open the Physical Web application, a brief welcome screen is shown (Figure 10-10, left). Tap the Proceed button to continue.

When no Eddystone-URL beacons are in range, Figure 10-10 (right) is displayed.

Figure 10-10. Left: Welcome screen for Physical Web app; Right: Physical Web app screen showing no beacons in range

Since we are running advertise.js, at least one beacon will be in range. If multiple beacons are in range, they will all be displayed in the list and sorted by signal strength (Figure 10-11, left).

Go ahead and tap the Example Domain beacon item. This will open a web browser to http://example.com (Figure 10-11, right), the URL that our Eddystone-URL beacon is configured to advertise.

Unlike iBeacon, which we tried out before, you do not need a specific app to utilize Eddystone-URL beacons; the Physical Web app scans for all Eddystone-URL beacons in range. Then it uses a mobile web browser to provide the UI to interact with the device, once you select a URL you are interested in. Our simple example doesn’t provide any interaction as the example.com website is very static. However, we were able to create a beacon that advertises the URL physically, allowing anyone with an app like Physical Web to detect the beacon when they are in range.

Figure 10-11. Left: Physical Web app showing beacon in range; Right: Physical Web app displaying http://example.com