Dude, where’s my car…keys? Bluetooth LE and BlackBerry 10 How-To

How-to

You know, I (@jcmrim) am the world’s-worst for misplacing things: car keys, house keys, and particularly spectacles, the list is endless. You name it and I can lose it. Martin (@mdwrim) isn’t much better either!

So, we thought we’d try a little bit of BlackBerry 10 Bluetooth Low Energy (LE) magic to help us. This  follows on nicely from my previous Blog post on the Internet of Things and the model is more widely applicable than just finding lost keys. In fact, if you haven’t already done so, this is probably a good time to have a read of that blog post and article since it covers the basic concepts needed in this blog post.

Go on … I’ll wait and have a cup of tea.

Ah, ok, you’re back … right, let’s continue.

The first thing we did was to do a little bit of research to see if the Bluetooth SIG had set any standards in this area; no point in re-inventing the wheel and the existence of a standard would mean that a vendor may have already implemented the technology in a product.

Whenever you have a requirement that may be solvable using Bluetooth LE the first place to look is here: http://developer.bluetooth.org/gatt/Pages/default.aspx.

Browsing through the GATT Profiles we came upon this one: Find Me … this sounded promising!

To quote the Abstract for the Find Me profile, “The Find Me profile defines the behavior when a button is pressed on one device to cause an alerting signal on a peer device”. An image formed in our minds immediately!

dude

A closer look shows that this profile implemented a GATT Service called Immediate Alert which used a GATT Characteristic called Alert Level … this looked a perfect match.

Here’s the description of the Alert Level Characteristic.

TITLE_IMAGE

Alert Level Characteristic

It’s an 8-bit unsigned integer that can take on three values signifying:

  • No Alert
  • Mild Alert
  • High Alert

The interpretation of these Alert Levels is the responsibility of the device that implements this characteristic.

Having found the Bluetooth LE Profile that matched our requirements the next step was to find a simple device that implemented it.

We found this one (see Figure 2) from Texas Instruments[1].  As well as supporting the Find Me profile it also allows re-programming with other Bluetooth services.

dude3

Texas Instruments CC2540/41 Mini Development Kit

Out of interest, I used one of the tools ( BTool ) that came with the key-fob to examine the GATT services that this device supported. Here’s a screen shot:

dude4

GATT Services present on the key-fob

So, you can see the highlighted red box clearly shows the Immediate Alert Service which has UUID 0×1802 (integers are represented in little-endian order so 0×1802 is represented as 02:18) and the Alert Level Characteristic which has UUID 0x2A06. Notice that the value field of the Alert Level characteristic has been assigned a handle of 0×0028 – handles are discovered by and used by applications to access fields in the GATT Service list and they’ve been covered in a previous blog post and article.

The application that we developed based on this is actually very similar in structure to the Heart Rate Monitor application that was described in a previous blog and article. The basic logic is the same:

  1. Pair the Bluetooth LE device with the BlackBerry 10 handset before using the application.
  2. Launch the application which:
    1. Discovers devices that support the Immediate Alert Service
    2. Connects to a discovered device selected by the user
    3. Offers the user the choice of Alert Levels ( Off, Mild and High) to be sent to the device

Here are some screenshots showing what the application looks like:

dude5

Screens from the application

You can see that the buttons at the top of the screen become enabled only once the application has connected to the Immediate Alert Service on the key-fob. If you select the “High” option this device will emit a loud buzzing sound and flash a green LED.

Application Sending an Alert to key-fob

Application Sending an Alert to key-fob

This is the application in action. If you use your imagination you can hear the buzzing and I can find my keys!

The key part of the application is where the Alert Level is sent to the device. Here’s the section of code that does this:

void FindMeService::sendAlertRequest() {

       uint8_t level[] = {0};

      switch (_alertLevel) {
            case FindMeService::Off:
                  level[0] = 0;
                  break;
            case FindMeService::Mild:
                  level[0] = 1;
                  break;
            case FindMeService::High:
                  level[0] = 2;
                  break;
            default:
                  level[0] = 0;
                  break;
      }

      errno = 0;

      if (bt_gatt_write_value_noresp(
                    _serviceInstance,
                    _alertLevelValueHandle, 0, 
                    level,
                    sizeof(level)
          ) != EOK) {

             qDebug() << "errno=(" << errno << ") :" << strerror(errno);
      }
}

You can see that we’ve already connected to the Immediate Alert Service and have a reference to this in the variable _serviceInstance; we also have a handle to the Alert Level characteristic value _alertLevelValueHandle. The API used is bt_gatt_write_value_noresp()which means that the Alert Level (level) is written to the device and no acknowledgement is expected in return.

Wait, I hear you say! How did you know that you had to use a Write without Response to write the Alert Level value to the device? Well, it’s part of the definition of the Immediate Alert Service. Here (Figure 6) is the definition of the Alert Level characteristic from the definition of the Immediate Alert Service. It says that this characteristic can be accessed only though the Write without Response request.

dude7

Immediate Alert Service Alert Level Characteristic Properties

And, just to confirm that the device understands and enforces this as well, Figure 7 shows this value in the GATT‘s entry for the Alert Level characteristic – the value 0×04 in the green box is the encoding of this property.

Characteristic Properties of the Alert Level

Characteristic Properties of the Alert Level

We made a video which has Martin (@mdwrim) showing the application in action and explaining the code. Here it is:

http://youtu.be/UXEt5tfUEdc

If you want to know more then check out the following resources:

I hope you’ve enjoyed this short note and hope it has piqued your interest to find out more about Bluetooth Low Energy and how it can be integrated into your BlackBerry 10 applications.


[1] This should not be regarded as an endorsement by BlackBerry, explicit or implied.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus