Using LightBlue on iOS

When you first connect with LightBlue, it will be difficult to interpret the data because the UI displays hex bytes for the temperature, humidity, and pressure value. Select the temperature characteristic and tap on the Hex button on the top-right. Scroll down and select 4 Byte Float Little Endian. The UI will switch back to the characteristic view and display the temperature as a float (Figure 6-6).

Figure 6-6. The temperature displays as a floating-point number

Using nRF Master Control Panel on Android

On Android, we read the data with nRF Master Control Panel (Figure 6-7).

Figure 6-7. Click the icon with the three down arrows to enable temperature notifications

Unfortunately, nRF Master Control Panel doesn’t translate the bytes of data into floating-point numbers. You can use the IEEE 754 Float Converter to convert the hexadecimal characteristic value to a float. Type the value in the Hexadecimal Representation input box (Figure 6-8).

Figure 6-8. Float Converter

Note that you need to reverse the byte order between nRF Master Control Panel and the Float Converter. nRF Master Control Panel displays the data in network byte order (big-endian). The Float Converter expects the most significant byte first (little-endian).

Create the Project

Open a terminal or cmd prompt on your computer. Change to the directory where you’d like to create the project.

cd ~/bluetooth

Use the phonegap command-line tool to create a new project.

phonegap create weather com.makebluetooth.weather Weather --template blank

Since you are using the PhoneGap Developer App, there’s no need to install the Bluetooth Low Energy plugin or any platform-specific code. See “Installing PhoneGap” for more details about using Apache Cordova or PhoneGap to build native applications.

Open the project in your text editor.

HTML

The index.html page builds the user interface for the mobile application. The application has two pages. The first page lists the available devices that are running the 0xBBB0 Bluetooth Weather Service. When you tap on a device in the list, you are connected to the device and taken to the detail page. The detail page shows data from the Bluetooth weather service.

Application pages are created using HTML div elements. The elements get unique ids so it is easy to access them from the JavaScript code. JavaScript functions show and hide divs as the user navigates in the application.

Add a link to the stylesheet in the head section of index.html.

<link rel="stylesheet" type="text/css" href="css/index.css" />

The stylesheet isn’t strictly required, but the application will look better if you add it. Create a new css directory inside the www directory. Create a file named index.css. Copy the contents of index.css into your file. This book already covers a lot of topics. Copying in some premade CSS allows us to skip the explanation and get back to building the application.

Edit the code within the body tag of index.html.

An h2 header element serves as a title bar for the application.

<h2>BLE Weather</h2>

The main page contains a list for devices and a refresh button.

<div id="mainPage">
    <ul id="deviceList">
    </ul>
    <button id="refreshButton">Refresh</button>
</div>

The detail page is slightly more complex. It contains a series of nested div elements to display the data. JavaScript functions will fill in this data as the application runs.

<div id="detailPage">
    <p>Temperature</p>
    <div id="temperatureDiv">
        Unknown
    </div>
    <p>Humidity</p>
    <div id="humidityDiv">
        Unknown
    </div>
    <p>Station Pressure</p>
    <div id="stationPressureDiv">
        Unknown
    </div>
    <p>Sea Level Pressure</p>
    <div id="seaLevelPressureDiv">
        Unknown
    </div>
    <button id="disconnectButton">Disconnect</button>
</div>

Finally, ensure that both cordova.js and index.js are included just before the close body tag.

<script type="text/javascript" src="cordova.js"></script>
<script type="text/javascript" src="js/index.js"></script>

See Example 6-2 for the complete listing of index.html.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="initial-scale=1, maximum-scale=1,
         user-scalable=no, width=device-width">
        <link rel="stylesheet" type="text/css" href="css/index.css" />
        <title>BLE Weather</title>
    </head>
    <body>
        <h2>BLE Weather</h2>
        <div id="mainPage">
            <ul id="deviceList">
            </ul>
            <button id="refreshButton">Refresh</button>
        </div>
        <div id="detailPage">
            <p>Temperature</p>
            <div id="temperatureDiv">
                Unknown
            </div>
            <p>Humidity</p>
            <div id="humidityDiv">
                Unknown
            </div>
            <p>Station Pressure</p>
            <div id="stationPressureDiv">
                Unknown
            </div>
            <p>Sea Level Pressure</p>
            <div id="seaLevelPressureDiv">
                Unknown
            </div>
            <button id="disconnectButton">Disconnect</button>
        </div>
        <script type="text/javascript" src="cordova.js"></script>
        <script type="text/javascript" src="js/index.js"></script>
    </body>
</html>

JavaScript

PhoneGap applications are written in JavaScript. Create a new js directory inside the www directory. Create a new file named index.js. Define four constants for the Bluetooth service and characteristics at the beginning of the file.

var WEATHER_SERVICE = 'BBB0';
var TEMPERATURE_CHARACTERISTIC = 'BBB1';
var HUMIDITY_CHARACTERISTIC = 'BBB2';
var PRESSURE_CHARACTERISTIC = 'BBB3';

Create an object literal named app. The application logic is built by adding functions to the app object.

var app = {
};

The first three functions you add are common bootstrapping for most PhoneGap apps. The initialize function calls bindEvents and ensures the main page is visible. The bindEvents function adds JavaScript event listeners to the list and buttons. The onDeviceReady function is called when the deviceready event fires. PhoneGap applications must wait for the framework to initialize and fire deviceready before making any API calls.

initialize: function() {
    this.bindEvents();
    this.showMainPage();
},
bindEvents: function() {
    document.addEventListener('deviceready', this.onDeviceReady, false);
    deviceList.addEventListener('click', this.connect, false);
    refreshButton.addEventListener('click', this.refreshDeviceList, false);
    disconnectButton.addEventListener('click', this.disconnect, false);
},
onDeviceReady: function() {
    app.refreshDeviceList();
},

Once the device is ready, the application can scan for Bluetooth devices and display the results in the user interface. Bluetooth scan results are filtered to contain only devices that are advertising the 0xBBB0 Weather Service.

refreshDeviceList: function() {
    deviceList.innerHTML = ''; // empty the list
    ble.scan([WEATHER_SERVICE], 5, app.onDiscoverDevice, app.onError);
},

The onDiscoverDevice callback will be called for each Bluetooth device that is found. Add a li element to the unordered list that will display the device name and id. The device id is stored in the list item’s dataset so that it can be retrieved later.

onDiscoverDevice: function(device) {
   var listItem = document.createElement('li');
   listItem.innerHTML = device.name + ' ' + device.id;
   listItem.dataset.deviceId = device.id;
   deviceList.appendChild(listItem);
},

When a user taps an item in the list, the connect function is called. The device id is retrieved from the dataset and passed to the connect function of the ble API.

connect: function(e) {
    var deviceId = e.target.dataset.deviceId;
    ble.connect(deviceId, app.onConnect, app.onError);
},

When the application connects to the Bluetooth peripheral, the success callback app.onConnect is called. After a successful connection, a few things need to happen. First, save a reference to the connected peripheral in app.peripheral. You’ll need the reference to the peripheral later in the disconnect method. Next, display the detail page to the user using app.showDetailPage (you’ll write this function later.) Use ble.startNotification to subscribe to notifications when the temperature, humidity, or pressure changes. It’s also important to call ble.read for each characteristic. If the values are not changing, ble.read ensures there is data to show the user. The read and notify for each property can share the same success callback.

onConnect: function(peripheral) {
    app.peripheral = peripheral;
    app.showDetailPage();

    var failure = function(reason) {
       navigator.notification.alert(reason, null, "Temperature Error");
    };

    // subscribe to be notified when the temperature changes
    ble.startNotification(
        peripheral.id,
        WEATHER_SERVICE,
        TEMPERATURE_CHARACTERISTIC,
        app.onTemperatureChange,
        failure
    );

    // subscribe to be notified when the humidity changes
    ble.startNotification(
        peripheral.id,
        WEATHER_SERVICE,
        HUMIDITY_CHARACTERISTIC,
        app.onHumidityChange,
        failure
    );

    // subscribe to be notified when the pressure changes
    ble.startNotification(
        peripheral.id,
        WEATHER_SERVICE,
        PRESSURE_CHARACTERISTIC,
        app.onPressureChange,
        failure
    );

    // read the initial values
    ble.read(
        peripheral.id,
        WEATHER_SERVICE,
        TEMPERATURE_CHARACTERISTIC,
        app.onTemperatureChange,
        failure
    );

    ble.read(
        peripheral.id,
        WEATHER_SERVICE,
        HUMIDITY_CHARACTERISTIC,
        app.onHumidityChange,
        failure
    );

    ble.read(
        peripheral.id,
        WEATHER_SERVICE,
        PRESSURE_CHARACTERISTIC,
        app.onPressureChange,
        failure
    );

},

Now, implement the callback for the ble.read and ble.startNotification calls. All three characteristics are floating-point numbers. Each callback receives an ArrayBuffer of data. This buffer of raw data needs to be converted into a typed Float32Array so it can be read. Although the ArrayBuffer is converted into an array of floating-point values, the service only sends one value, so it is an array of one element.

Convert temperature into a floating-point value. Temperature is sent in Celsius. Convert this to Fahrenheit and display both values in the application. Use toFixed to truncate the number to one decimal place.

onTemperatureChange: function(buffer) {
    var data = new Float32Array(buffer);
    var temperature = data[0];
    var temperatureF = temperature * 1.8 + 32;
    var message = temperature.toFixed(1) + "&deg;C<br/>" +
      temperatureF.toFixed(1) + "&deg;F<br/>";
    temperatureDiv.innerHTML = message;
},

Humidity is a floating-point value like temperature. Use toFixed to display one decimal place.

onHumidityChange: function(buffer) {
    var data = new Float32Array(buffer);
    var humidity = data[0];
    var message = humidity.toFixed(1) + "%";
    humidityDiv.innerHTML = message;
},

The handler for pressure is slightly more complex. The pressure value is just a floating-point number like temperature and humidity, but there are a few more conversions that need to be done.

Data is sent in pascals, but hectoPascals (or millbars) is a better way to display pressure information. Divide by 100 to get hPa. Displaying pressure in hPa works fine for most of the world. Unfortunately, the United States still uses the antiquated unit inches of mercury to measure pressure. Use app.toInchesOfMercury helper function to do the conversion.

The pressure measured by the sensor is known as station pressure. This measured value probably does not match the value you look up on a weather website such as NOAA, GoC Weather, or BBC Weather.

Atmospheric pressure decreases as elevation increases. Barometric pressure is reported at sea-level pressure as a way to normalize pressure measurements, removing the effect of the station’s elevation. Once you know the elevation of your weather station, you can convert the pressure to theoretical pressure at sea level.

There are formulas for calculating sea-level pressure from station pressure using temperature and elevation. As a rough estimate, assume that pressure will decrease 1 hPa for every 8 meters of elevation. If you are at higher elevation or need a more accurate value, you may need to substitute a better conversion formula.

onPressureChange: function(buffer) {
    var data = new Float32Array(buffer);
    var pressure = data[0]; // pascals

    // hectoPascals (or millibar) is a better unit of measure
    pressure = pressure / 100.0;

    // station pressure is what we measure
    var message = pressure.toFixed(2) + " hPa<br/>" +
          app.toInchesOfMercury(pressure) + " inHg<br/>";

    stationPressureDiv.innerHTML = message;

    // Pressure needs to be converted to sea-level pressure to match
    // the barometric pressure in weather reports.

    // Fort Washington, PA - adjust this for your location
    var elevationInMeters = 50.438;

    // pressure drops approx 1 millibar for every 8 meters above sea level
    var delta = elevationInMeters / 8.0;
    var seaLevelPressure = pressure + delta;

    message = seaLevelPressure.toFixed(2) + " hPa<br/>" +
      app.toInchesOfMercury(seaLevelPressure) + " inHg";

    seaLevelPressureDiv.innerHTML = message;
},

Create a helper function to covert between hectoPascals and inches of mercury. This can be estimated by using the conversion factor of 0.0295300 inHg per hPa.

toInchesOfMercury: function(hPa) {
  // http://www.srh.noaa.gov/images/epz/wxcalc/pressureConversion.pdf
  return (hPa * 0.0295300).toFixed(2);
},

Create a function for the disconnect button.

disconnect: function(e) {
    if (app.peripheral && app.peripheral.id) {
        ble.disconnect(app.peripheral.id, app.showMainPage, app.onError);
    }
},

Create two functions for page navigation. Navigation simply shows and hides divs.

showMainPage: function() {
    mainPage.hidden = false;
    detailPage.hidden = true;
},
showDetailPage: function() {
    mainPage.hidden = true;
    detailPage.hidden = false;
},

The last function in the app object is the generic error handler referenced from many of the API calls. If an error occurs, a dialog box is shown to the user.

onError: function(reason) {
   navigator.notification.alert(reason, app.showMainPage, "Error");
}

The last line of the JavaScript file should initialize the application.

app.initialize();

See Example 6-3 for the complete listing of index.js.

var WEATHER_SERVICE = 'BBB0';
var TEMPERATURE_CHARACTERISTIC = 'BBB1';
var HUMIDITY_CHARACTERISTIC = 'BBB2';
var PRESSURE_CHARACTERISTIC = 'BBB3';

var app = {
    initialize: function() {
        this.bindEvents();
        this.showMainPage();
    },
    bindEvents: function() {
        document.addEventListener('deviceready', this.onDeviceReady, false);
        deviceList.addEventListener('click', this.connect, false);
        refreshButton.addEventListener('click', this.refreshDeviceList, false);
        disconnectButton.addEventListener('click', this.disconnect, false);
    },
    onDeviceReady: function() {
        app.refreshDeviceList();
    },
    refreshDeviceList: function() {
        deviceList.innerHTML = ''; // empty the list
        ble.scan([WEATHER_SERVICE], 5, app.onDiscoverDevice, app.onError);
    },
    onDiscoverDevice: function(device) {
       var listItem = document.createElement('li');
       listItem.innerHTML = device.name + ' ' + device.id;
       listItem.dataset.deviceId = device.id;
       deviceList.appendChild(listItem);
    },
    connect: function(e) {
        var deviceId = e.target.dataset.deviceId;
        ble.connect(deviceId, app.onConnect, app.onError);
    },
    onConnect: function(peripheral) {
        app.peripheral = peripheral;
        app.showDetailPage();

        var failure = function(reason) {
           navigator.notification.alert(reason, null, "Temperature Error");
        };

        // subscribe to be notified when the temperature changes
        ble.startNotification(
            peripheral.id,
            WEATHER_SERVICE,
            TEMPERATURE_CHARACTERISTIC,
            app.onTemperatureChange,
            failure
        );

        // subscribe to be notified when the humidity changes
        ble.startNotification(
            peripheral.id,
            WEATHER_SERVICE,
            HUMIDITY_CHARACTERISTIC,
            app.onHumidityChange,
            failure
        );

        // subscribe to be notified when pressure changes
        ble.startNotification(
            peripheral.id,
            WEATHER_SERVICE,
            PRESSURE_CHARACTERISTIC,
            app.onPressureChange,
            failure
        );

        // read the initial values
        ble.read(
            peripheral.id,
            WEATHER_SERVICE,
            TEMPERATURE_CHARACTERISTIC,
            app.onTemperatureChange,
            failure
        );

        ble.read(
            peripheral.id,
            WEATHER_SERVICE,
            HUMIDITY_CHARACTERISTIC,
            app.onHumidityChange,
            failure
        );

        ble.read(
            peripheral.id,
            WEATHER_SERVICE,
            PRESSURE_CHARACTERISTIC,
            app.onPressureChange,
            failure
        );

    },
    onTemperatureChange: function(buffer) {
        var data = new Float32Array(buffer);
        var temperature = data[0];
        var temperatureF = temperature * 1.8 + 32;
        var message = temperature.toFixed(1) + "&deg;C<br/>" +
          temperatureF.toFixed(1) + "&deg;F<br/>";
        temperatureDiv.innerHTML = message;
    },
    onHumidityChange: function(buffer) {
        var data = new Float32Array(buffer);
        var humidity = data[0];
        var message = humidity.toFixed(1) + "%";
        humidityDiv.innerHTML = message;
    },
    onPressureChange: function(buffer) {
        var data = new Float32Array(buffer);
        var pressure = data[0]; // pascals

        // hectoPascals (or millibar) is a better unit of measure
        pressure = pressure / 100.0;

        // station pressure is what we measure
        var message = pressure.toFixed(2) + " hPa<br/>" +
              app.toInchesOfMercury(pressure) + " inHg<br/>";

        stationPressureDiv.innerHTML = message;

        // Pressure needs to be converted to sea-level pressure to match
        // the barometric pressure in weather reports.

        // Fort Washington, PA - adjust this for your location
        var elevationInMeters = 50.438;

        // pressure drops approx 1 millibar for every 8 meters above sea level
        var delta = elevationInMeters / 8.0;
        var seaLevelPressure = pressure + delta;

        message = seaLevelPressure.toFixed(2) + " hPa<br/>" +
          app.toInchesOfMercury(seaLevelPressure) + " inHg";

        seaLevelPressureDiv.innerHTML = message;
    },
    toInchesOfMercury: function(hPa) {
      // http://www.srh.noaa.gov/images/epz/wxcalc/pressureConversion.pdf
      return (hPa * 0.0295300).toFixed(2);
    },
    disconnect: function(e) {
        if (app.peripheral && app.peripheral.id) {
            ble.disconnect(app.peripheral.id, app.showMainPage, app.onError);
        }
    },
    showMainPage: function() {
        mainPage.hidden = false;
        detailPage.hidden = true;
    },
    showDetailPage: function() {
        mainPage.hidden = true;
        detailPage.hidden = false;
    },
    onError: function(reason) {
       navigator.notification.alert(reason, app.showMainPage, "Error");
    }
};

app.initialize();

Run the App

Save index.html and index.js and you’re ready to run the application. Go back to your terminal or command prompt and start the server by typing phonegap serve.

xvi:weather don(master)$ phonegap serve
[phonegap] starting app server...
[phonegap] listening on 10.0.1.16:3000
[phonegap]
[phonegap] ctrl-c to stop the server
[phonegap]

On your phone or tablet, start the PhoneGap Developer App. Verify that the server address listed in the app matches the address from the phonegap serve command. Press Connect. You should see a list of devices offering the Weather Service. Click on your device. You should see the weather details reported on the detail screen (Figure 6-9). Click the disconnect button to go back to the device list.

Figure 6-9. Left: PhoneGap Developer App. Center: Weather main page. Right: Weather detail page

The source code for this chapter is available on GitHub.