How to develop beacon apps in JavaScript with Evothings Studio and Estimote (unsupported content)

This article refers to features no longer supported

We no longer maintain the Cordova plugin for Estimote Beacons. We recommend using the generic iBeacon plugin instead, which works nicely with Estimote Beacons. Please see the iBeacon Starter Guide for further details.

Cross post of article posted at the Estimote blog. Update 2015-03-10: Code snippets now use the recent plugin API.

Tens of thousands of mobile developers are working with Estimote Beacons to build native micro-location apps. Leveraging local context on mobile devices is one of the hottest trends in tech right now, but what about people working with JavaScript and HTML? Now they also can develop mobile applications on top of the Estimote platform. Evothings Studio is an open-source development tool, specifically designed to create mobile applications for the Internet of Things using JavaScript and HTML. Estimote Beacons are supported out-of-the-box. Read on and get your hands dirty writing your first beacon-enabled app.

Prototype ideas in real time

Evothings Studio was created to allow you to quickly develop new ideas and designs. You can now build apps in a highly iterative and interactive style. Make changes to the code incrementally and instantly see the result on multiple mobile phones and tablets. Time from coding to testing is just a few seconds, making for a creative flow where you can turn your concept into a prototype in an instant.

Here is how it works: on your computer you run Evothings Workbench, a server that connects to mobile devices running the Evothings Client app. When pressing save in your code editor, changes are detected and the running app is updated on the connected devices.

When the project is ready to ship, you can build a native app to be published on the Apple App Store and Google Play.

Write code in your favorite editor

Evothings Studio comes with two main components:

Evothings Client – mobile application that runs JavaScript apps
Evothings Workbench – web server with a visual drag-and-drop user interface, which includes a launchpad to organize apps and JavaScript logging and code evaluation tools

The third component is your favorite text editor or IDE.

With Evothings Studio you have the freedom to use any code editor or IDE. As soon as you save a file, changes will be picked up by Evothings Workbench and connected mobile devices will be notified to update the running app.

The live reload mechanism works with all files and formats. For example, if you save an image in Photoshop, the app will update and display the new image.

Hands-on getting started guide

Included with Evothings Studio is the “Estimote Beacons” example app. This app displays beacon data when ranging for beacons.

Here is how to get up and running with the example app:

Get a set of Estimote Beacons
Download Evothings Studio (this download contains Evothings Workbench, examples and documentation)
Install the Evothings Client app on your mobile phone or tablet (get it from Apple App Store or Google Play)
Start Evothings Workbench on your computer
Make sure your mobile device is on the same WiFi as your computer and that the network allows connections
Launch Evothings Client and connect to the Workbench
Go to the Workbench and click RUN on the “Estimote Beacons” example app
The app should now run on the mobile device and start detecting your Estimote Beacons
To view/edit the code, click the CODE button which will open a window with the application files
Open file index.html, make some changes to the code and save the file, the app now automatically reloads on the connected mobile device

To build a native stand-alone app, see the step-by-step guide below.

Cordova/PhoneGap plugin for Estimote Beacons

Evothings Client comes with a Cordova/PhoneGap plugin for Estimote Beacons. It’s open-source so you’re free to use it in any project.

The same plugin is used both when using Evothings Client and when building an app using the Cordova build system. The difference is that the edit-build-test cycle can be slow and tedious when using the Cordova build tools. What Evothings Studio does is taking the development cycle to warp speed.

The Estimote Beacons plugin currently supports:

Ranging for beacons (iOS and Android)
Monitoring beacons (iOS and Android)
Scanning for beacons using CoreBluetooth (iOS only)

The following is a taste of what the API looks like. Here is how to range for Estimote Beacons:

var region = { identifier: 'MyRegion' }

estimote.beacons.startRangingBeaconsInRegion(
   region,
   onBeaconsRanged,
   onError)

function onBeaconsRanged(beaconInfo)
{
   console.log('Number of Estimote Beacons ranged: ' +
       beaconInfo.beacons.length)
}

function onError(error)
{
   console.log('Start ranging error: ' + error)
}

The above region will match all Estimote Beacons that have the default UUID (B9407F30-F5F8-466E-AFF9-25556B57FE6D). The function onBeaconsRanged will be called continuously when there are matching beacons within range, until ranging is stopped. It prints the number of beacons ranged to the debug console.

Monitoring and ranging

Two basic actions apps can perform defined in the iBeacon standard are region monitoring and ranging. Monitoring, which is enabled by startMonitoringForRegion, tracks entering and exiting regions. Monitoring works in the background or even when the app is killed. Thanks to that, it’s a powerful tool for delivering contextual notifications when the user comes in range of a beacon, even though monitoring itself does not contain any information about proximity.

Ranging, enabled by startRangingBeaconsInRegion, works only in the foreground. It has a fast update rate, and includes proximity and distance information, allowing for for granular insight into users’ behavior and therefore tailoring content more suited to their needs.

Read more about monitoring and ranging on the Estimote Community Portal.

On iOS a third method for detecting beacons is supported, which is called scanning. Scanning is similar to ranging but uses a different underlying implementation than ranging does.

Beacon regions

Regions define which beacons to monitor and range. A region consists of the following:

Identifier – a string set by the developer to name the region
UUID (Universally Unique Identifier) – a string that identifies the UUID for the beacons in the region (many beacons can share a UUID)
Major – the major value is a number that can be used to identify specific beacons (several beacons in a region can have the same major value)
Minor – the minor value is a number can be used to identify a specific beacon (the minor value should be unique to one beacon within a region)

Estimote Beacons come predefined with a default UUID and randomly generated major and minor values. Each value can be used by an application to identify beacons or to create ‘regions’: beacon-based geofences. When specifying a beacon region, you can leave out major and minor values to find all beacons with the specified UUID. You can also specify the UUID and major value (when using minor, major must also be given). If you define all three: UUID, major and minor, you will be monitoring for a single beacon with the particular ID.

Understanding how regions works is critical to building iBeacon apps. To learn more about it, read the article on Estimote Community Portal.

When a region is defined in JavaScript, certain default values apply if a field is left out.

Default values are as follows:

Region identifier defaults to ‘EstimoteSampleRegion’
UUID defaults to ‘B9407F30-F5F8-466E-AFF9-25556B57FE6D’ (Estimote Beacon factory UUID)
Major value defaults to null
Minor value defaults to null

Here is an example of a simple beacon region that will match all factory configured Estimote Beacons:

var region =
{
    identifier: 'MyRegion'
}

Note that if you set a minor value you must also set a major value. You cannot use minor without major.

Here is an example of a region that defines all fields:

var region =
{
    identifier: 'MyRegion',
    uuid: 'B9407F30-F5F8-466E-AFF9-25556B57FE6D',
    major: 1,
    minor: 2
}

Overview of Estimote plugin and JavaScript API

Start and stop ranging:

estimote.beacons.startRangingBeaconsInRegion(
    region,
    successCallback,
    errorCallback)

estimote.beacons.stopRangingBeaconsInRegion(
    region,
    successCallback,
    errorCallback)

Start and stop scanning (iOS only):

estimote.beacons.startEstimoteBeaconsDiscoveryForRegion(
    region,
    successCallback,
    errorCallback)

estimote.beacons.stopEstimoteBeaconDiscovery(
    region,
    successCallback,
    errorCallback)

On iOS 8 it is also required for your app to ask for permission to use location services (on iOS 7 and Android this call does nothing):

estimote.beacons.requestAlwaysAuthorization(
    successCallback,
    errorCallback)

To learn more look into the documentation in the JavaScript API file, available on GitHub.

How to access beacon data

When you use ranging or scanning, you have access to a variety of beacon properties. Different properties are available depending on whether ranging or scanning is used. (Note that during monitoring you don’t get data for individual beacons, rather you get data about regions entered and exited.

Properties available on iOS

Properties available both during ranging and scanning:

major – major value of the beacon
minor – minor value of the beacon
color – color value
rssi – number representing the Received Signal Strength Indication

Properties available only when ranging:

proximityUUID – UUID of the beacon
distance – estimated distance from the beacon in meters
proximity – proximity value

Properties available only when scanning:

macAddress
measuredPower

The full set of properties available on iOS are documented in the Estimote iOS SDK.

Properties available on Android

Properties available when ranging:

proximityUUID – UUID of the beacon
major – major value of the beacon
minor – minor value of the beacon
distance – estimated distance from the beacon in meters
proximity – proximity value
rssi – number representing the Received Signal Strength Indication
name – the name advertised by the beacon
macAddress
measuredPower

The properties available on Android are documented in the Estimote Android SDK.

Beacon data code example

Using the above data you can do all sorts of things based on proximity: identify which beacons are close, how far they are, and so on. Here is an example of how to access the beacon distance property:

var region = { identifier: 'MyRegion' }

estimote.beacons.startRangingBeaconsInRegion(
    region,
    onBeaconsRanged,
    onError)

function onBeaconsRanged(beaconInfo)
{
    // Sort beacons by distance.
    beaconInfo.beacons.sort(function(beacon1, beacon2) {
        return beacon1.distance > beacon2.distance })

    // Display distance for the closest beacon.
    var beacon = beaconInfo.beacons[0]
    console.log('Closest beacon is ' + beacon.distance + 'm away')
}

function onError(error)
{
    console.log('Start ranging error: ' + error)
}

Creating a native Estimote app

Using the Cordova or PhoneGap build system, you can build a native app that can be published on the app stores.

Here is a step-by-step guide for how to build the example app “Estimote Beacons” using Cordova.

1. Install the Cordova build system.

2. Create a new Cordova project with the name of your choice, using a command line window.

The following command will create a template Cordova app in the directory “beacondemo”, set the app id to “com.mydomain.beacondemo”, and set the name to “BeaconDemo”:

cordova create beacondemo com.mydomain.beacondemo BeaconDemo

3. Go to the app directory using the command:

cd beacondemo

4. Copy your HTML and JavaScript files to the newly created Cordova project.

In the “beacondemo” folder there is a subfolder called “www”. This is where you put the application’s HTML and JavaScript files. Delete all the files already inside the “www” folder and put your own app’s files in there. If you’re just trying out the build process, you can use the “Estimote Beacons” example’s files instead: you’ll find them in the “examples” folder of the Evothings Studio directory.

Copy files in:

examples/estimote-beacons

To the directory:

beacondemo/www

The result should look like this:

beacondemo
   www
       app.js
       index.html
       libs
       ui

5. Add the Estimote plugin using the following command; this just needs to be done once:

cordova plugin add https://github.com/evothings/phonegap-estimotebeacons.git

(If you want to use other plugins, you also have to add them to the project.)

6. Add the target platforms you wish to build for (Android and/or iOS); this also only needs to be done once:

cordova platform add android
cordova platform add ios

7. Build the app.

To build and install the app on Android, use these commands:

cordova build android
adb install -r platforms/android/ant-build/BeaconDemo-debug.apk

To build and install the app on iOS, first build an Xcode project:

cordova build ios

Then open and run the generated project using Xcode: platforms/ios/BeaconDemo.xcodeproj

That’s it! You have now built a native stand-alone app.

A nice thing is that you can continue to develop the code using Evothings Workbench and Evothings Client. Just drag and drop this file into the Workbench project list:

beacondemo/www/index.html

Now you can edit and develop your project using the fast Evothings Workbench based workflow, and when you’re ready to build a native version of the app, just execute the cordova build… command as described above.

It may be that you want to use Cordova plugins that are not included with Evothings Client (list of supported plugins). However, you can still use your Cordova app with Evothings Workbench, to take advantage of the fast workflow. Learn a few simple steps to achieve this in the Evothings Cordova Guide.

The Estimote PhoneGap/Cordova plugin also contains an example app you can use as an inspiration for your own apps, along with build instructions.

It’s easy to get started with Estimote Beacons in JavaScript

It is fun and easy to get going. Just order an Estimote Developer Kit, then download Evothings Studio and dive straight into building your beacon projects with JavaScript and HTML. We’d love to hear your thoughts, so don’t hesitate to ask about anything on the Evothings Forum or Twitter, or email info@evothings.com.

Mikael Kindborg, Lead Architect at Evothings