Quick guide to making a mobile app for the TI SensorTag using JavaScript

Make an app for the TI SensorTag in 5 minutes! Everyone who knows web technologies can now create mobile applications for the Texas Instruments TI SensorTag. Thanks to a high-level scripting library there is no need to do low-level programming in Objective-C or Java. And you can still do a native build of the final app and publish it on Apple App Store and on Google Play.

The TI SensorTag

In this tutorial we will look at a new and innovative way to develop mobile applications for the Texas Instruments TI SensorTag – using HTML5 and JavaScript. By building on the code examples and the demo app, you will be able to contribute your own SensorTag apps to the app stores, using web technologies and a high-level JavaScript library specially made to communicate with the SensorTag.

The Texas Instruments TI SensorTag is a widely-popular battery powered, Bluetooth Low Energy (BLE) device, with a number of different sensors that can be used for various applications and projects. Available sensors are:

Temperature (IR sensor)
Temperature (ambient)
Air pressure
Hygrometer
Accelerometer (tri-axis)
Gyroscope (tri-axis)
Magnetometer (tri-axis)
Two physical buttons

Photo of the TI SensorTag, stripped from its protective shell:

Demo app

The demo app showcases the TI SensorTag. Coded in HTML5 and JavaScript, the app runs on a mobile phone or tablet (Android or iOS) and the various values from the SensorTag is displayed on-screen in real time. To date, only a few Android-based devices actually carry the required BLE hardware and software (September 2014), so please make sure your devices meets the requirements to avoid frustration. For iOS, iPhone 4S or later with iOS 7 or later will all work with this demo app.

The app connects to the closest SensorTag when started and displays readings for the different sensors. You can modify this example to do something interesting with the sensor values. Here is a photo of the app running on an iPad Mini:

In the code

The demo app consists of the following files:

index.html – the complete application code (HTML and JavaScript)
ti-sensortag.js – high-level TI SensorTag library
easy-ble.js – high-level BLE library

The TI SensorTag uses BLE to communicate with a phone or tablet. When writing an app in Objective-C or Java, the program must scan for and find a SensorTag, connect to it, turn on each sensor used, enable notifications, and so on, using BLE calls. By contrast, the TI SensorTag JavaScript library abstracts the low-level BLE code, UUIDs etc, and provides high-level functions for enabling and reading sensors, so you as a developer don’t have to.

The entire application logic of the demo app is made up by 92 lines of JavaScript code. Here is the complete listing:

// SensorTag object.
var sensorTag = TISensorTag.createInstance()

function initialiseSensortag()
{
    sensorTag
        .statusCallback(statusHandler)
        .errorCallback(errorHandler)
        .keypressCallback(keypressHandler)
        .irTemperatureCallback(irTemperatureHandler)
        .humidityCallback(humidityHandler)
        .barometerCallback(barometerHandler)
        .accelerometerCallback(accelerometerHandler, 100)
        .magnetometerCallback(magnetometerHandler, 100)
        .gyroscopeCallback(gyroscopeHandler, 100)
        .connectToClosestDevice()
}

function statusHandler(status)
{
    displayValue('StatusData', status)
}

function errorHandler(error)
{
    displayValue('StatusData', 'Error: ' + error)
    if ('disconnected' == error)
    {
        // If disconneted attempt to connect again.
        setTimeout(
            function() { sensorTag.connectToClosestDevice() },
            1000)
    }
}

function keypressHandler(data)
{
    displayValue('KeypressData', data[0])
}

function irTemperatureHandler(data)
{
    displayValue(
        'IRTemperatureData',
        data[0] + ',' + data[1] + ',' + data[2] + ',' + data[3])
}

function accelerometerHandler(data)
{
    //console.log('length: ' + data.length)
    //console.log('acceldata: ' + data[0] + ' ' + data[1] + ' ' + data[2])

    displayValue(
        'AccelerometerData',
        data[0] + ',' + data[1] + ',' + data[2])
}

function humidityHandler(data)
{
    displayValue(
        'HumidityData',
        data[0] + ',' + data[1] + ',' + data[2] + ',' + data[3])
}

function magnetometerHandler(data)
{
    displayValue(
        'MagnetometerData',
        data[0] + ',' + data[1] + ',' + data[2])
}

function barometerHandler(data)
{
    displayValue(
        'BarometerData',
        data[0] + ',' + data[1] + ',' + data[2] + ',' + data[3])
}

function gyroscopeHandler(data)
{
    displayValue(
        'GyroscopeData',
        data[0] + ',' + data[1] + ',' + data[2] + ','
        + data[3] + ',' + data[4] + ',' + data[5])
}

function displayValue(elementId, value)
{
    document.getElementById(elementId).innerHTML = value
}

document.addEventListener('deviceready', initialiseSensortag, false)

When the app starts, the initialiseSensortag function is called. This function creates a SensorTag object that we use to enable sensors. The API for defining sensors uses a “fluent” style, where you chain together function calls.

For each sensor used in the app, a callback function is given. This function will be called when sensor values are updated. Some sensors have a setting for the update interval, which given in milliseconds.

As the final initialisation step, the function connectToClosestDevice is called. This makes the app scan for and connect to the SensorTag with the strongest RSSI (signal strength) value.

The callback functions take a data parameter, that contains an array of sensor values (byte values). The number of data values differ depending on the sensor. For the full documentation of sensors and sensor values, see SensorTag_User_Guide and BLE_SensorTag_GATT_Server.pdf.

Running the app using Evothings Studio

The TI SensorTag app has been developed using Evothings Studio.

When developing apps with Evothings Studio, you run the Evothings Client app on your mobile device to execute the application, and you use Evothings Workbench on your laptop/desktop machine, running a live-reload server.

Start by installing the Evothings Client app on your iOS or Android device (available in the AppStore and on Google Play). If you use an Android device, make sure it has full support for BLE and runs Android 4.3 or later. Then download Evothings Studio and run the Evothings Workbench live server on your computer.

To run the TI SensorTag demo app, do as follows:

Get the source code for the TI SensorTag demo app from GitHub.
Launch Evothings Workbench on your computer (on OS X do right-click Open on first launch).
Drag and drop index.html from the “TISensorTag” project folder into the project list window of the Workbench. It will show up right on the top of the project list.
Connect from Evothings Client to the Workbench (make sure your phone and computer are on the same network).
Press Run in the Workbench.
Put the SensorTag into announcement mode (press the button on the side of the Tag until the small front led visible under the cover starts blinking).

That’s it – live sensor data from the TI SensorTag should now be displayed on your phone/tablet!

Fun things to do

You can modify the app in various ways. Play around with the source code, find out how to use Evothings Studio to quickly see your changes on the mobile device.

You can for example play around with chaining the colours of the UI, make different things happen when pressing the buttons on the SensorTag, move an absolutely positioned div-tag using accelerometer data, and so on.

Using BLE from JavaScript

It can be quite a challenge to develop mobile applications for the Internet of Things (IoT) using Bluetooth Low Energy (BLE). By using high-level JavaScript libraries, IoT app development can be made easier and quicker.

To access BLE from JavaScript, the Evothings BLE plugin for Apache Cordova is used.

Files of interest:

ble.js is the API for the BLE plugin. This file built into the Evothings Client app (which is built with Cordova), and is not included in the source code for the app.
easy-ble.js is a high-level abstraction of the API in ble.js. The EasyBLE library is generally useful to communicate with BLE devices, such as an Arduino equipped with the BLE Shield.
ti-sensortag.js is a high-level library for the TI SensorTag.

Building a native app

Any app you create using Evothings Studio can be packaged as a native Apache Cordova app, that can be published on the app stores. The Evothings Client app itself is a Cordova app, it was even developed using Evothings Workbench!

How to build a native app with Cordova is described in the Evothings Build Documentation.