DEVELOPERS BLOG

BlackBerry 10 Keeping Precious Things Close: Proximity, Part 1

CASCADES / 12.18.13 / mdwrim

Chickens

It is the year of “Sense, Understand, Adapt” here at BlackBerry. The capabilities of the BlackBerry 10 OS and APIs, together with its hardware, have propelled BlackBerry 10 and app developers into a world of IoT (Internet of Things). Built-in sensors and technologies like Bluetooth Low Energy (AKA Bluetooth Smart) give apps the ability to sense aspects of the physical environment, interpret environmental data and take action – adapting the application’s behavior and UI as things of interest change in that environment.

I teamed up with my BlackBerry Developer Relations colleague John Murray earlier this year to explore some of the BlackBerry 10 capabilities that make “Sense, Understand, Adapt” possible, in particular Bluetooth Low Energy and Near Field Communications (NFC).

In this blog post, we will discuss a specific environmental attribute that makes it possible to program your application to “sense” the world around it. That attribute is called proximity.

About Proximity

Proximity can mean different things in different contexts. Only last year, I was using the term “proximity gaming” to refer to games that leveraged NFC in game play by allowing physical interactions between players and their devices.

To some, “proximity” immediately conjures up the proximity sensor, which uses infrared light to detect objects that are near to the BlackBerry 10 device. It’s often used for face detection for example.

In this blog post however, we will focus on the Bluetooth Low Energy Proximity Profile.

The Bluetooth Low Energy Proximity Profile

The Proximity Profile enables us to monitor objects which we would hate to lose, and specifically to:

  1. Be notified when the object has become too far away from us for comfort
  2. Be notified when we’re so far away from our object that we’ve completely lost “sight” of it
  3. Gain assistance when we have lost our object when we think it is still relatively close by

There are Bluetooth Low Energy devices on the market that use the Bluetooth Proximity Profile concerned with these use cases. For example, John and I obtained and worked with the Philips AEA1000 “smart leash,” a small rectangular device that you can either place inside a bag or attach to something via the rubber band it comes with.

Philips AEA1000 Smart Leash

Figure 1 – The Philips AEA1000 Smart Leash

The Proximity Profile – Roles

The Bluetooth SIG defines two roles with respect to the Proximity Profile.

Proximity Profile

Figure 2 – Proximity Roles

A Proximity Reporter like the Philips AEA1000 is a GATT server. A Proximity Monitor, on the other hand, is a device that works with the Proximity Reporter, keeping an eye on the status of the Proximity Reporter device. In our case, the Proximity Monitor is a BlackBerry 10 application. So we have a partnership here: with a Proximity Reporter device in your bag or attached to your keys, and a Proximity Monitor application running on your BlackBerry 10smartphone, you will never lose your precious things again!

In case you’re new to Bluetooth Low Energy, be aware that a “profile” is essentially a specification that defines things like the services (things a device can do) and characteristics (data) that a device has implemented and available. Read our Bluetooth Low Energy Primer if you want to know more about Bluetooth Low Energy and its key technical components such as “GATT.”

Figure 2 lists the services defined for the Proximity Profile reporter role. The dotted lines indicate an optional service. The only mandatory service in this profile is the Link Loss Service, but let’s briefly examine each of the three services in turn:

Link Loss Service: This service triggers an audible “alert” whenever the Bluetooth link to the monitor device is lost.

Immediate Alert Service: This service will trigger an audible alert whenever it is instructed to do so by the monitor device. In other words, it can respond to “Where are you?” queries with a beep or similar audio signal.

TX Power Service: This service exposes the reporter device’s current transmit power level when it’s in a connection.

The Philips AEA1000 implements all three of these services.

Exploiting the Proximity Profile

A Proximity Reporter like the Philips AEA1000 does the “sensing” for us, but it’s up to your BlackBerry 10 application to implement the “understand” and “adapt” behaviors. John and I set about developing an application that would do just that. The functional requirements were clear enough, but we wanted a UI that would stand out and convey the feeling of safe-guarding precious items. We brainstormed. We did everything possible to get the creative juices flowing like never before. John even stood on his head whilst holding a wet fish at one point [John: Yes, I can confirm that this is true!]. And yet despite all of our efforts and use of leading-edge creativity-enhancing techniques, *this* was the best we could come up with: chickens. Yes, CHICKENS!

A colleague had quite seriously asked if he could attach a proximity reporter to his children. We followed that thought through to its logical conclusion and substituted a brightly colored, cartoon metaphor. The Bluetooth Chicken Guardian was born!

Bt Chicken Guardian

Figure 3 – The BtChickenGuardian application

We’d successfully utilized chickens before; you may remember NFC Chicken. If not, check out this video (specifically around 20:05) and then come back and read on!

BtChickenGuardian implements all three use cases described above. It monitors your distance from the Proximity Reporter device with which it has been paired and gives a visual representation of distance falling into three bands: Near, Middle Distance and Far. In this case, “Far” is deemed “too far,” so the application indicates this with a distinct visual appearance and suitable sound effect. Now what noise would you expect a momma chicken to make when alarmed that one of her chicks has strayed too far away? Yes, the app makes that very noise. This is the very essence of “Understand” and “Adapt” in action!

Bt Chicken Guardian_2

Figure 4 – The BtChickenGuardian application

The Panic button exploits the Immediate Alert Service. When selected, we send a command over Bluetooth Low Energy which causes the Philips Proximity Reported to emit a loud tone which we can hear and thereby locate the lost item, be it a baby chick or otherwise. We’ve talked about the Immediate Alert Service in this blog post and this video in the past.

So how do we monitor distance? When we first connect to the Proximity Reporter, we query the TX Power Service. This returns a value which indicates, as a digital quantity, the power with which the Reporter device asserts that it is transmitting. We can then use this as a baseline to compare with the locally “experienced” signal strength that we receive.

However, we found that the TX Power Service didn’t work properly on the Philips device, no matter what third party tools we used to test it. So instead we gave our application a Settings page where the user can define signal strength thresholds, which are linked to our three distance bands of near, middle distance and far. It’s a simple approach which works in practice and which can be tuned by the user as they see fit.

So what does the code look like? Much of what we do in this application you’ve seen before, and of course the full BtChickenGuardian app has been released as open source in our GitHub repository. But one aspect of this application that is new is the monitoring of signal strength. Technically this is called the RSSI (Received Signal Strength Indicator) and monitoring its value is very easy as shown here.

void BluetoothHandler::startRssiPolling()
{

    // we'll poll the RSSI in a background thread

    DataContainer* dc = DataContainer::getInstance();

    rssi_polling_required = true;

    _future = new QFuture<void>;
    _watcher = new QFutureWatcher<void>;
    *_future = QtConcurrent::run(_handler, &BluetoothHandler::pollRssi);
    _watcher->setFuture(*_future);
    QObject::connect(_watcher, SIGNAL(finished()), this, SLOT(finishedRssiPolling()));
}

void BluetoothHandler::pollRssi()
{
    DataContainer* dc = DataContainer::getInstance();

    int *rssi;
    rssi = (int*) malloc(sizeof(int));

    while (rssi_polling_required) {
        delay(1000);

        errno= 0;

        int result = bt_rdev_get_current_rssi(dc->getCurrentDevice(), rssi);
        if (result < 0) {
            qDebug() << "XXXX bt_rdev_get_current_rssi - errno=(" << errno<< ") :" << strerror(errno);
        }

        dc->setRssi(*rssi);

        int proximity_indicator = calculateProximityIndicator(rssi);

        emit signalRssi(QVariant(proximity_indicator), QVariant(*rssi));

        if (proximity_indicator != dc->getProximityIndicator()) {
            dc->setProximityIndicator(proximity_indicator);
            emit signalProximityChange(proximity_indicator);
        }
    }

    free(rssi);

}

As you can see, all we do is to kick off a background thread, and in that thread we periodically (once per second) read the RSSI value using API function bt_rdev_get_current_rssi. We communicate the current value to the UI by emitting a Qt signal, and if the signal indicates the distance has changed significantly, say from “middle distance” to “far,” we emit another signal so that the UI can change its appearance accordingly.

One last word on the technique used here. RSSI as a means of estimating distance is not particularly accurate because all sorts of environmental factors can affect RSSI. It’s good enough as a guide, and therefore fine for this type of application, but we wouldn’t recommend using it when pinpoint accuracy is needed.

Bluetooth Low Energy and BlackBerry 10: Sense. Understand. Adapt.

Bluetooth Low Energy and BlackBerry 10 partner well together. Your applications can exhibit smart behaviors by sensing what’s going on in the outside world, interpreting and understanding that data and adapting to it. All in all, your applications can significantly enhance the user’s experience and add real value by breaking out of the confines of the device they run on and connecting to the outside world.

Resources

About mdwrim