That said there are…. apparently…. people in this world who have a bit more resolve than I do and take their sporting and fitness activities a bit more seriously. Not only do they manage to get out of the comfy chair, they even like to measure and analyse their performance so they can improve.

Now my colleague Martin (@mdwrim) has normal furniture in his house and seems more than capable of getting out of the comfy chair and down to the climbing wall or out on his bike. He and I (@jcmrim ) talked about the kind of technology available to sporty people, in particular cyclists. Martin had just come back from watching part of the Giro d’Italia and pointed out that all the pro cyclists have sensors on their bikes. BlackBerry 10, Bluetooth Low Energy and cycling! What a perfect combination of great technology, fun and exercise as well as a great opportunity for a new Blog post, video and sample app!

If you haven’t already done so, this is probably a good time to have a read of our previous blog posts and articles on the Internet of Things and Finding Car Keys since they cover the basic concepts needed in this blog post.

As before, the first thing we did was to do a little bit of research to see if the Bluetooth SIG had defined any standards in this area; no point in re-inventing the wheel [no pun intended] 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: Cycling Speed and Cadence (CSC)… this sounded promising, and the description looked like it was just what we needed.

“The Cycling Speed and Cadence Profile is used to enable a data collection device to obtain data from a Cycling Speed and Cadence Sensor (CSC Sensor) that exposes the Cycling Speed and Cadence Service.”

The key element of this profile is the Cycling Speed and Cadence Service (UUID 0×1816) which contains four really useful fields:

• “Cumulative Wheel Revolutions”
• “Cumulative Crank Revolutions”
• “Last Wheel Event Time”
• “Last Crank Event Time”

These are part of the “CSC Measurement” GATT Characteristic (UUID 0x2A5B). They are described in detail here: CSC Characteristics and outlined in Figure 1.

There are some other characteristics that allow configuration and control of the device but we’ll talk about these when we come across them.

Figure 1 Key GATT Characteristics for CSC

So, if you think about these characteristics they allow you to derive a number of key measurements:

1. Total distance travelled – using “Cumulative Wheel Revolutions” – all you need to know is the wheel circumference to calculate this, but if you combine this with a time and a geo-location measurement you can even derive sufficient information to plot your progress on a map.
2. Speed – using “Last Wheel Event Time” – you can figure out how fast the bike is going if you do a simple calculation involving the time between successive Last Wheel Event Time values and the number of wheel revolutions that occurred in that time. But if you combine this with a geo-location measurement you can derive sufficient information to plot your speed on the map as well.
3. Instantaneous effort – using ““Last Crank Event Time”” – this can help identify those times that you’re free-wheeling and not expending energy.

It’s at this point that the engineer in me begins to wonder how to instrument a bicycle to make use of this GATT profile. Martin’s a cyclist, so, after identifying a device that matched the requirements (Wahoo Fitness Blue SC[1] device), he attached it to his cycle as shown in Figure 2.

Figure 2 Attachment of cycle monitor

For those of you who are mechanically minded small magnets on both the crank and the rear wheel spokes activate the sensor strapped to the frame. The sensor maintains the counts and timings and will report them to a suitable Bluetooth LE device such as a BlackBerry 10 smartphone.

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 CSC Service (UUID 0×1816)
   2. Connects to a discovered device selected by the user
   3. Requests the device to notify our application as changes are made to the CSC Measurement characteristic (UUID 0x2A5B) which contains the wheel and crank data that we’re interested in.
   4. Receive, parse and display in numerical (RPM) and historical graphical form the CSC Measurement data as they are received.

Here are some screenshots showing what the application looks like:

Figure 3 The CscMonitor Application

Instantaneous values of the wheel and crank readings in revolutions per minute (RPM) are shown in the upper part of the screen whilst historical RPM data are plotted on the lower half of the display. Wheel and crank historical data displays can be toggled by touching the screen. Mapping RPM values to distance or energy expended would require additional information to be provided, such as the wheel circumference or radius of the crank — we’ll leave this for a possible later iteration of the application and focus on the Bluetooth LE aspects for now.

If we inspect the GATT services the CSC device supports using a tool like BTool we can see (Figure 4) that the CSC Measurement Characteristic (UUID 0x2A5B) is exposed at handle 0×0023. Handles are the references to entries in the GATT that our application will discover and use to access the value associated with a characteristic. We’ve used handles before in both our previous examples.

Figure 4 GATT showing CSC Characteristics

Associated with the CSC Measurement Characteristic is a “Client Characteristic Configuration” characteristic (UUID 0×2902) exposed at handle 0×0024. The value of this field determines whether our application will receive Notifications or Indications for the CSC Measurement Characteristic. We’ve used these before as well in our previous examples. In this case this characteristic will be set to enable Notifications using the BlackBerry 10 Bluetooth LE API.

So, how do we manage the data that is notified to us from the CSC device? The CSC data received is managed by a class called “CscDataContainer” … here’s part of its definition:

class CscDataContainer: public QObject {
       Q_OBJECT
private:
       CscDataContainer();
...
       // notification data
       QQueue<csc_notification_t> _csc_notifications;
       // CSC values
       QQueue<csc_values_t> _csc_values;
       int _min_wheel_rpm;
       int _max_wheel_rpm;
       int _avg_wheel_rpm;
       long _total_wheel_rpm;
...
}

At its core are a couple of queues that maintain the data that is received. The queue has a maximum length that can accommodate one notification per second for an 8 hour period. A future version might persist these data in a database but this is sufficient to demonstrate the principle in this case.

Once again the excellent little JavaScript library called “Flot” is used to plot these data in a WebView component in QML.

As notifications are received by our application the addNotification() method of the CscDataContainer class is called with the CSC Measurement data passed as a (uint8_t *) and a length (uint16_t) — that is an array of bytes.

Parsing this data is the first task and it’s instructive to see how this works – the main points are highlighted in the code fragment below:

void CscDataContainer::addNotification(const uint8_t *val, uint16_t len) {
       // parse value, paying attention to the bit settings in the FLAGS field
       bool wheel_revolution_data_present = false; // bit 0 of Flags field
       bool crank_revolution_data_present = false; // bit 1 of Flags field
       uint32_t cumulative_wheel_revolutions = 0;
       uint16_t cumulative_crank_revolutions = 0;
       uint16_t last_wheel_event_time = 0;
       uint16_t last_crank_event_time = 0;
       int index = 0;
       uint8_t flags = val[index];
       wheel_revolution_data_present = ((
flags & WHEEL_REVOLUTION_DATA_PRESENT) == WHEEL_REVOLUTION_DATA_PRESENT);
       crank_revolution_data_present = ((
flags & CRANK_REVOLUTION_DATA_PRESENT) == CRANK_REVOLUTION_DATA_PRESENT);
       // Fields are in the order of LSO to MSO.
       // Where LSO = Least Significant Octet and MSO = Most Significant Octet.
       index++;
       if (wheel_revolution_data_present) {
              // Cumulative Wheel Revolutions, 4 bytes.
             // Field exists if the key of bit 0 of the Flags field is set to 1.
              cumulative_wheel_revolutions =
(val[index + 3] << 24) | (val[index + 2] << 16) |
(val[index + 1] << 8)  |  val[index];
index += 4;
              // Last Wheel Event Time, 2 bytes. 
              // Field exists if the key of bit 0 of the Flags field is set to 1.
              last_wheel_event_time = (val[index + 1] << 8) | val[index];
              index += 2;
...
}
       if (crank_revolution_data_present) {
// Cumulative Crank Revolutions, 2 bytes. 
// Field exists if the key of bit 1 of the Flags field is set to 1.
              cumulative_crank_revolutions =
(val[index + 1] << 8) | val[index];
              index += 2;
              // Last Crank Event Time, 2 bytes. 
              // Field exists if the key of bit 1 of the Flags field is set to 1.
              last_crank_event_time = (val[index + 1] << 8) | val[index];
              index += 2;
    ...
    }
...
}

The first byte of data contains an 8-bit flag field (see Figure 1 for details). This indicates whether crank or wheel data is present in the following data.  If these are present they are represented in Little-endian form and need to be extracted by shifting them out a byte at a time.

The rest of the application is more focussed on the display of this data using QML so I’ll leave that for you to look at yourself since the main learning points are to do with how to interface to the Bluetooth Low Energy device itself.

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

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

• The complete source code for this application on Git Hub;
  • 
    https://github.com/blackberry/Cascades-Community-Samples
    
• If you’re completely new to Bluetooth LE then we recommend you read our “BlackBerry 10 Bluetooth LE Primer for Developers”  which you’ll find in our knowledge base. This and all other Bluetooth LE related developer resources that we’ve created, are listed in a single resource index page:
  • 
    http://supportforums.blackberry.com/t5/Native-Development/BlackBerry-10-Bluetooth-LE-resource-index/ta-p/2326147
    

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.

JAM36 – NFC development for BlackBerry 10: A whirlwind tour

Here we’ll look at all the tech that is available from you to create solutions. We’ll cover tag reading and writing, P2P and more.  Great to keep in mind that NFC is more than just payment!!!

JAM26 – Demystifying NFC Payment

But – if you’re thinking about getting into payment (or loyalty programs) – this is the session for you.

We’ll cover a few different approaches and talk about everything you need lined up. There are lots of moving pieces involved to make complete secure element / card emulation solution.

Send me an email or tweet @robbieDubya for all of your NFC needs.

Thinking of twitter – Martin @mdwrim and John @jcmrim are people you really should be following if you are into NFC and BlackBerry! #nfcguys

I hope you’ve enjoyed the series and we look forward to seeing you all at BlackBerry Jam Americas in Orlando. Please let us know what you thought of the videos to ensure that we can bring information to you in a way that’s educational, but entertaining as well.

This particular video will give you some information about the current opportunities and upcoming roadmap items that we’re looking at for extending connectivity for developers. In this video we’re joined by Rob Williams who talks about how you can connect BlackBerry 10 to the world around you to incorporate context into your apps.

One of our goals for this year’s BlackBerry Live conference is to integrate mobile technology not just in the discussions, sessions, and resources – but into the actual conference itself to help keep attendees closely plugged into all of the action.

Near Field Communication (NFC)

One of my all-time favorite technologies, Near Field Communication (NFC) will be integrated into BlackBerry Live in a big way. You’ll be able to scan into BlackBerry Live and BlackBerry Jam sessions and interact with aspects of the venue using the BlackBerry Live Conference App, but that’s just the beginning. You’ll also be able to share contact information with sponsors, scoop up links to resources and web sites, and take advantage of all that BlackBerry 10 has to offer when it comes to NFC.

BlackBerry Live Conference App

Shortly before BlackBerry Live the Mobile Conference Guide app will be available in BlackBerry World for you to download. This will be your ultimate conference guide, including a wide range of features:

• Find sessions, speaker, sponsor, and event details
• Receive event update messages
• View the conference agenda and floor plan
• Build and edit your conference schedule
• Scan into sessions using Near Field Communication (NFC)
• Complete conference and session surveys
• Share your information with conference sponsors using NFC

It’s not too late to register for BlackBerry Live!

Head over to www.blackberrylive.com to register for this year’s conference, and don’t forget that if you’ve attended a BlackBerry event in the past, you may be eligible for a $150 discount as part of the Alumni Discount!

Stay tuned for availability in BlackBerry World, and get ready for a seriously mobile conference! See you next week in Orlando.

“Bluetooth Low Energy”, I hear you say. ”I know all about Bluetooth since that’s been around for many years. It’s what I use to connect my headset to my BlackBerry device and play music though my sound system. What’s this ‘Low Energy’ thing?”

Well, the Bluetooth specification went through a number of changes a couple of years ago when Bluetooth 4.0 was released. Bluetooth Low Energy (LE) is an addition to the classic specification that allows ultra low power devices to participate in Bluetooth Networks.

What does “Ultra low power” mean? Well, Bluetooth LE is designed to support devices that would typically be powered by battery cells like the one in this picture.

That means that such devices can have incredibly small footprints yet can be full participants in a Bluetooth network alongside larger devices like tablets or smart phones such as BlackBerry 10 smartphones.

It also means that this awesome technology is an enabler for the “Internet of things” where such devices can participate in an Internet populated with all sorts and sizes of devices ranging from large servers to intelligent thermometers; from tablets to intelligent sensors in your running shoes; from mobile phones to intelligent light switches in your home.

Imagine being able to use your BlackBerry 10 smartphone to tailor your environment to your preferences as you move around. It’s already capable of knowing where you are and Bluetooth LE gives it the capability of communicating with smart devices in your home or car. Imagine returning home and having your BlackBerry 10 smartphone communicate with your lighting to set it appropriately; your home entertainment system to play your favourite playlist; and your house’s environmental controls to set just the right temperature!

The diversity of potential applications is quite staggering. Sports, wearable devices, home automation, automotive and healthcare, are just a few of the sectors recognising the potential of Bluetooth LE.

And … BlackBerry 10 is a perfect fit here! So, we got to thinking how we could demonstrate how easy it is to integrate Bluetooth LE technology into your BlackBerry 10 application!

In order to provide some focus for this activity we acquired some Bluetooth LE technology and tools including a Wahoo Blue HR device to see what we could do with it. There are a number of similar devices on the market but this seemed like a good starting point. It’s a small, lightweight electronic device, encased in plastic. It has an adjustable strap to allow you to strap it around your chest and the strap has two conductive pads which need to be in contact with the skin.

The nice thing about Bluetooth LE is that there are standards for devices like this that support what’s called the Heart Rate Profile and we managed to develop a nice, even though I say it myself, self contained BlackBerry 10 application that interacted with the heart rate monitor and displayed it’s data.

Take a look at the images below! The image on the left shows a typical trace for a healthy person like Martin who went on a long, exhausting bike ride to gather this data.

The middle one is probably from a small, hyperactive animal like this hamster; whilst the one on the right probably comes from a hibernating hedgehog I came across in my garden.

Rest assured that no small timid animals were involved in our testing other than in our imaginations!

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

• A much more detailed article describing the theory and practice behind this application
• The complete source code for this application on Git Hub
• A video on YouTube showing an overview of the theory and practice behind this application

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.

Did you know that it’s easy to exchange data between your NFC enabled smartphone and your Arduino? It can be arbitrary data too – it does not need to be formatted as NDEF tags or ISO 7816-4 APDUs!

What does it take to get an Arduino that talks with BlackBerry running? Here’s what I used to make a very basic color mixing application that shares colors between the Arduino and the BlackBerry over NFC.

• Some NFC enabled BlackBerry devices. I’m using my Bold 9900s. <3 the keyboard!
• 1 Arduino. I’m using an Arduino Uno R3 (it’s under the shield)
• 1 Adafruit Industries PN532 NFC/RFID shield. A great shield available here:
  http://adafruit.com/products/789
  
• 1 BlackBerry application.
• 1 Arduino sketch
• A copy of the Adafruit NFCShield library. Note that I have made modifications to get the functionality that I needed;
  https://github.com/blackberry/Adafruit_NFCShield_I2C
  (pull request pending…)
• Imagination. This is the most important ingredient! With these other ingredients you could build… anything! (Hit me up in the comments with your project!)

• Optional: The manual for the PN532.
  http://www.adafruit.com/datasheets/pn532um.pdf
  

Arduino Sketch

Here are the guts of my sketch – stripped to the barest functionality… I need to ‘inList’ a passive target and then ‘inDataExchange’. If you can ‘inList’ a target – then you can send data to it…

if (nfc.inListPassiveTarget()) {
    while(true) {
      message[0] = 1; message[1] = r; message[2] = g; message[3] = b;
      uint8_t responseLength = sizeof(message);
      if (nfc.inDataExchange(message,sizeof(message),message,&responseLength)) {
        uint8_t command = message[0];
        switch(command) {
        case 1:
          if (responseLength==4) {
            r = message[1];
            g = message[2];
            b = message[3];
            showColor();
          }
          else {
            //Serial.println("Doesn't seem to be a color...");
          }
          break;
        default:
          ;
        }

The Adafruit samples show you everything you need to know about initializing the class.

The active NFC peer (the Arduino) is responsible for sending data first. You may have to keep on polling your passive peer.

Java

Again – just the basics. You need to create a VirtualISO14443Part4TypeATarget. You have to be aware that the target is only active when your app is in the foreground. The number below is not used by the API. this is an instance of VirtualISO14443Part4TargetCallback.

    emulated = new VirtualISO14443Part4TypeATarget(this, "10451045", null);
    emulated.startEmulation();

Then, in the callback I send the color that has been mixed on the screen (unless the user hasn’t chosen a color recently). The byte array returned from this method is transmitted over NFC.

private byte[] processCommand(byte[] command) {

        if (command == null) {
            return new byte[0];
        }
        int messageType = command[0] & 0xff;
        switch (messageType) {
        case 1:
            if (command.length == 4) {
                int colorIn = (command[1] & 0xff) << 16;
                colorIn |= (command[2] & 0xff) << 8;
                colorIn |= (command[3] & 0xff);

                if (colorIn != color) {
                    if (colorQueued) {

                        byte[] toReturn = new byte[4];
                        toReturn[0] = 1;
                        toReturn[1] = (byte) (color >> 16);
                        toReturn[2] = (byte) (color >> 8);
                        toReturn[3] = (byte) color;

                        return toReturn;

Existing BlackBerry samples and tutorials explain the listener really well.

The Result

Here’s a very short video showing several BlackBerrys sharing colors with the Arduino. I built a paper cube around my LED to try and make it easier to capture on video.

My NFC Slogan

You’re already there! No need to PAIR!

What I’m trying to say in my slogan is this: there are times when you want to be physically at a device and make it do something. To me – NFC feels a little like the crystals that power starship computers in SCI-FI shows. The hero moves them into the right spot; completing the system and saving the day, galaxy and timeline.

There are times that you don’t want to be there either… And there are lots of higher powered RF systems for that…

What Can You Make?

Who will make the first bridge for NFC to XBee that has a cradle form factor?

I’m looking forward to hearing in the comments what you are going to Make!

#BBGotGame Port-A-Thon Update

http://devblog.blackberry.com/2012/11/got-game-port-a-thon-update/

Using the Invocation Framework with BlackBerry Messenger

http://devblog.blackberry.com/2012/11/bbm-invocation-framework/

Be Bold and Vote: What’s Your Reason to Believe in BlackBerry 10?

http://blogs.blackberry.com/2012/11/blackberry-10-believe-poll/

Near Field Communication: Just a Payment Tool? Debunking a Common NFC Myth

http://bizblog.blackberry.com/2012/11/nfc-myths/

Did you miss or would like to re-watch any of our past developer webcasts? Below is a summary of where to find all the recordings posted to date, along with a couple that are coming soon.

NFC-related webcasts, specific webcast titles listed below:

• NFC overview (Native)
• NFC Tags BlackBerry® 10
• NFC Tags BlackBerry® 7

Cascades™-related webcasts, specific webcast titles listed below:

• Astonishing UIs using the new BlackBerry 10 framework
• Astonishing UIs using the new BlackBerry 10 framework continued
• Cascades – everything you’ve always wanted to ask about retrieving, storing and displaying your Data – but were afraid to ask
• Building Compelling 3D Apps using Cascades and OpenGL ES

Native-related webcasts, specific webcast titles listed below:

• BlackBerry Native Game Development

HTML5/BlackBerry® WebWorks™-related webcasts, specific webcast titles listed below:

• Using the Dojo Toolkit in a BlackBerry WebWorks app Full Webcast
• BlackBerry 10 WebWorks Applications with the Enyo.js framework Full Webcast
• Exploring the use of bbUI.js for building a BlackBerry UI with HTML5

Coming soon!

• HTML5 Gaming (WebGL (3D), Audio, Social Integration (BBM™), Web Workers, Web Sockets)
• Building BlackBerry 10 apps with jQuery Mobile & backbone.js

Built for BlackBerry-related webcasts, specific webcast titles listed below:

• 10k Developer Commitment
• Built For BlackBerry Part 1: User Benefit, User Experience, and System Integration
• Built For BlackBerry Part 2: Performance

Android-related webcasts, specific webcast titles listed below:

• Running Android Applications on BlackBerry® PlayBook™ and BlackBerry 10

Alpha-related webcasts, specific webcast titles listed below:

• Beta 3: Beta 3: BlackBerry 10 WebWorks SDK Update
• Beta 3: The Power of the Integrated Platform Emerges

Enterprise-related webcasts, specific webcast titles listed below:

• Enterprise App Developers: BlackBerry® Balance™ technology

The Marmalade webcast is hosted on the Marmalade site:

• BlackBerry game development with Marmalade SDK

You know, working in the Developer Relations team at Research In Motion® (RIM®), you get to get to play around with some fun stuff. Recently, Near Field Communication (NFC) has been exercising my brain cells. Some of you may be familiar with the NFC-related articles and code samples that I’ve co-authored with my co-conspirator, Martin Woolley (@mdwrim), which you can find listed in our NFC Article and Code index.

Now, whenever you mention NFC in a conversation, people invariably think of payments. Using NFC to make secure payments is perhaps the most obvious use case. However, when I think of NFC I tend to think of workflows as well. “Workflows,” you say? What do you mean?

OK, let’s think about it anecdotally. How many times have you had the challenge of transcribing some data from an external source to your handset whilst holding a bag and trying to hold a conversation at the same time? How many times have you tried to share information on your handset with someone else and had to struggle with inputting email addresses whilst doing three other things at the same time? These use cases are examples of Workflows, or Business Processes, that stumble on the point of having to accommodate more “human” interaction than is really necessary. NFC can be used to help streamline simple workflows that involve human interactions on mobile devices and ultimately help achieve efficiencies.

So, having thought about this and how to demonstrate a simple but realistic use case (whilst also having some fun), we came up with the concept of the “Fun Run”.

Suppose you’re taking part in a charity “Fun Run” – not quite a marathon but something shorter for fun. The race organizers have developed a simple mobile application to allow you to register for the event and have placed NFC Tags in the starting and finishing areas. As you start you tap on one of the tags, your race timer is started as well as notifying the organizers that you have begun. When you pass the finish line, simply tap on one of the tags in the Finish area to stop your timer and notify the organizers of your finishing time!

In between the start and finish, there may be Way Points with NFC Reader devices that can be used to register intermediate times as the runner passes these points. Tap the handset to the NFC Reader and receive confirmation that the timing data has been transferred successfully.

OK, maybe it’s not 100% realistic, but as an example it is sufficient to demonstrate how a workflow process that involves having to record start and finish times and tracking progress can be made more efficient using NFC. The key learning point is to understand how integrating NFC technology into your application can be used to achieve efficiencies in similar processes.

The Applications

Let’s take a look at how we implemented this simple example using BlackBerry® 10 and BlackBerry® 7 NFC capable devices. There are really three use cases:

1. Tap your handset against an NFC tag at the start of the race to start your race timer.
2. Tap your handset against NFC readers at intermediate waypoints during the race to transfer your current race timer data to an application that manages the reader.
3. Tap your handset against an NFC tag at the end of the race to stop your race timer.

Acting on External Tag Events

To implement the first and last use case, we decided to provide two NFC tags that had specific NDEF messages as their content. There would be one tag that would start the timer at the start of the race and one tag that would stop the timer at the end of the race.

Specifically the data in the two tags is:

1. Tag used to start the timer:

NDEF TNF = External ( integer value 4 )
Type = “my.rim.com:myrecordtype”
Payload = “start”

2. Tag used to stop the timer:

NDEF TNF = External ( integer value 4 )
Type = “my.rim.com:myrecordtype”
Payload = “stop”

Why use this data? Well, firstly we choose an NDEF TNF (Type Name Format) for the NDEF Message because it allows us to define custom tag content that won’t clash with standard tag message types such as Smart Poster (“Sp”) or URL (“U”) or Text (“T”). We want to make sure that when one of these tags is presented, our application, and our application alone, is launched to process the tag.

Secondly, we choose a “Type” of “my.rim.com:myrecordtype“. Within the context of an External TNF record the Type can be arbitrary, but in order to prevent clashes with other organizations’ custom tag formats, we use the DNS naming scheme to set the namespace of the tag as “my.rim.com” to establish it as a RIM NDEF message. We further qualify it with a specific sub-type of “myrecordtype” since an organization may define a whole family of custom tag formats for its own use.

So, these settings ensure that these tags will only make sense to our application and not overlap with tags form elsewhere. The “Payload” of the two tags differs in that one has the string “start” and the other has the string “stop” to mark them as ones to be used to start and stop the timers respectively.

In the case of BlackBerry 10, our application registered with the Invocation Framework through the stanza in its “bar-descriptor.xml” file as shown in Figure 1. The “uris” attribute of the “<property … />” tag has been set to the value “ndef://4/my.rim.com/myrecordtype” which a URI format specification of the two tags just described above.

...
<invoke-target id="com.example.NfcRaceTimeWay">
    <type>APPLICATION</type>
    <filter>
        <action>bb.action.OPEN</action>
        <mime-type>application/vnd.rim.nfc.ndef</mime-type>
        <property var="uris" value="ndef://4/my.rim.com/myrecordtype"/>
    </filter>
</invoke-target>
...

Figure 1 Registering for tag types in BlackBerry 10

When a “start” or “stop” tag is presented to the handset, then our application is launched if it’s not already running, and the tag contents are handled as shown in Figure 2 — where the payload of “start” or “stop” is extracted once we’ve verified that it’s of the correct type.

...
void NfcListener::receivedInvokeRequest(const bb::system::InvokeRequest& request) {

    QByteArray data = request.data();
    QtMobilitySubset::QNdefMessage ndefMessage = QtMobilitySubset::QNdefMessage::fromByteArray(data);

    handleNdefRequest(ndefMessage);
}

void NfcListener::handleNdefRequest(const QtMobilitySubset::QNdefMessage ndefMessage) {

    QList::const_iterator ndefRecord;

    for ( ndefRecord = ndefMessage.begin(); ndefRecord != ndefMessage.end(); ndefRecord++) {
        if (ndefRecord->typeNameFormat() == QtMobilitySubset::QNdefRecord::ExternalRtd) {
            if (QString(ndefRecord->type()).compare("my.rim.com:myrecordtype") == 0 ) {
                emit raceTagDetected(QString(ndefRecord->payload()));
            }
        }
    }
}
...

Figure 2 Handling a Start or Stop tag in BlackBerry 10

In the case of BlackBerry 7, registration is achieved in Java® by registering a listener for the specific NDEF message type as shown in Figure 3.

...
    nfcManager = ReaderWriterManager.getInstance();
    nfcManager.addNDEFMessageListener(listener, NDEFRecord.TNF_EXTERNAL, "my.rim.com:myrecordtype", true);
...

Figure 3 Registering for tag types in BlackBerry 7

A similar behaviour is achieved for BlackBerry 7 through the implementation of the “onNDEFMessageDetected()” method of the “NDEFMessageListener” interface as shown in Figure 4.

...
    public void onNDEFMessageDetected(NDEFMessage msg) {
        NDEFRecord[] records = msg.getRecords();
        int numRecords = records.length;
        if(numRecords > 0) {
            byte[] payloadBytes = records[0].getPayload();
            try {
                String ascii_payload = new String(payloadBytes,"US-ASCII");
                Utilities.log("XXXX payload="+ascii_payload);
                if (ascii_payload.equals("start")) {
                    startTimer();
                }
                if (ascii_payload.equals("stop")) {
                    stopTimer();
                }
            } catch(UnsupportedEncodingException e) {
                Utilities.log("XXXX "+e.getClass().getName()+":"+e.getMessage());
            }
        }

    }

...

Figure 4 Handling a Start or Stop tag in BlackBerry 7

So, what we’ve achieved here is the ability to use an external NFC tag to trigger a process in our application. In this case it’s simply the starting and stopping of a timer, but it could be extended quite easily to, say, call a web service and integrate the event into a larger workflow process.

What does this look like in practice? Well, here’s a short video of the BlackBerry 10 application in action:

[ YouTube link for mobile viewing ]

Virtual Tag Emulation

Let’s get back to the original use cases. To implement the second one, we decided to have the BlackBerry handset emulate a virtual tag and allow the contents of the virtual tag to be read by an external NFC reader.
What format of tag should be emulated by the handset? This is what we chose:

1. Virtual tag emulated by the application

NDEF TNF = External ( integer value 4 )
Type = “my.rim.com:myrecordtype”
Payload = “hh:mm:ss”

a. That is the time displayed on the handset in:
Hours (hh)
Minutes (mm)
Seconds (ss)

The type of the virtual tag is exactly the same as for the “start” and “stop” physical tags for the very same reasons, except that the payload is a representation of the current race timer value (“hh:mm:ss”) as displayed by the application.

...
void NfcListener::startTagEmulation(const QString &tagData) {
    nfc_ndef_record_t *ndefRecord = makeCustomRecord(QString("my.rim.com"), QString("myrecordtype"), tagData);
    if (_emulateNdefMessage) {
        CHECK(nfc_delete_ndef_message(_emulateNdefMessage, true));
        _emulateNdefMessage = 0;
    }
    CHECK(nfc_create_ndef_message(&_emulateNdefMessage));
    CHECK(nfc_add_ndef_record(_emulateNdefMessage, ndefRecord));
    CHECK(nfc_start_ndef_tag_emulation(_emulateNdefMessage));
...

Figure 5 BlackBerry 10 – starting virtual tag emulation

As shown in Figure 5, starting tag emulation in BlackBerry 10 is quite simple. It just involves calling “nfc_start_ndef_tag_emulation()”. In addition we can use BPS (BlackBerry Platform Services) to determine when a read on the virtual tag has been successful, as shown here in Figure 6:

...
void NfcListener::handleNfcEvent(bps_event_t *event) {
    uint16_t code = bps_event_get_code(event);
    if (NFC_VIRTUAL_TAG_SELECTION_EVENT == code) {
        emit tagEmulationSelectEvent();
    } else if (NFC_VIRTUAL_TAG_LEFT_EVENT == code) {
        emit tagEmulationLeftEvent();
    } else if (NFC_VIRTUAL_TAG_READ_EVENT == code) {
        emit tagEmulationReadEvent();
    }
}
...

Figure 6 BlackBerry 10 – stopping virtual tag emulation

So, what we’ve achieved here is the ability to transmit live information from an application in the BlackBerry handset in real time to an external application via an NFC reader. The external application simply displays the time displayed by the BlackBerry application, but it could easily be extended to integrate with some larger workflow process.

Take a look at the video here for a demonstration of this on BlackBerry 10:

[ YouTube link for mobile viewing ]

If you’re interested, the virtual tag emulation functionality was tested using an NFC Reader attached to a PC controlled by a Python application using the “PyScard” (Python for Smart Cards) library available from SourceForge.net. (Python and Ruby are my favorite programming languages!)

The two versions of our NFC-enabled “Fun Run” applications are available with full source code from our GitHub repositories here:

https://github.com/blackberry/Cascades-Community-Samples/tree/master/NfcRaceTimeWay


https://github.com/blackberry/Samples-for-Java/tree/master/NFC/NfcRaceTime7

Just in closing, it’s worth making one or two comments about the relative ease of developing applications to the same set of end user specifications in BlackBerry 10 Cascades™ versus BlackBerry 7 Java. I’ve been developing code in C/C++ for more years than I care to remember and for a shorter time in Java (but still since the language first saw the light of day), so I feel I’m qualified to make comparisons. I’ll be honest: I’ve found it much easier to develop applications using C/C++ and Cascades. The user interface elements are particularly easy to use, and I’ve found it possible to get a user interface up and running in Cascades much faster than I would have done in Java. It’s much easier to modify and extend since Cascades elements map directly to Qt/Cascades C++ classes and the SIGNAL() / SLOT() model makes it so easy to connect events to handlers.

I’m definitely sold on Cascades, Qt and C/C++!

Now it has to be said that it wasn’t the best summer here in the UK (though fortunately the weather gave us a break just in time for the Olympics!) and so I occasionally found myself at the weekend with “fine weather-dependent plans” cancelled and time on my hands. One such weekend, I was thinking about NFC and my thoughts turned to discussions I’d had with John about whether NFC could enrich games and the gaming experience in some way.

The world of computer games has changed somewhat in the 30-something years I’ve been playing them! It’s gone from text-based adventure games (“go north!”) played on a PDP-11 with a teletype and no screen, through the block graphics of Lunar Lander on a Commodore Pet, and onwards through Space Quest, Civilisation I, the Monkey Island series and (many) more favourites.

In the beginning and for many years, games were single-player — or at least they were single machine games. More than one player could play, but you’d have to share the keyboard or take turns. Then came LAN games, and this evolved into Internet-based gaming with huge online gaming communities (without whom, I have no doubt, the world would now be over-run with zombies). The truly great thing about online gaming is that you need never know that “goreslayer765” who just destroyed you in your favourite game is actually a 9-year-old with far more knowledge of automatic weapons than can possibly be healthy. I mean, whose fragile ego could handle knowing that?

So, both extreme ends of the single player vs. multiplayer spectrum are well catered to these days. But in what way might NFC enrich the gaming experience, and in what kind of games? I had a quick brainstorm with John on IM and we came up with a few use cases:

But why would you want to do this? After all, there are plenty of other ways to trigger “new game” or “it’s your turn now” and to share data across a network. Well, the appeal of using NFC is simply this: it adds a physical, tactile element to the game. You’re sitting right next to the person you’re playing with, and having to touch devices at intervals in the game could add a novel and fun element to the experience.

We then realized our most important task. We needed a name for the phenomenon of NFC-enabled games that we were now thinking about. In a flash, I had it! Please welcome “Proximity Gaming” to the world!

Armed with a few ideas, we decided to develop a game as a proof of concept and set about thinking about what the first game would be and how it would work. We decided we’d develop an NFC-enabled version of “tic tac toe” or “noughts and crosses” as it’s known in the UK.

We decided to use NFC in two places. Firstly, players would have to touch devices to start a game, and secondly, they’d touch devices to indicate “it’s your turn now”.

We had to consider a few issues regarding the implementation. It was immediately apparent that we’d have to pass some kind of message from device A to device B and that we’d probably need several message types. In other words, we’d need a simple protocol.

We could also see several technical ways of sending a message from one device to another. We could use virtual target emulation in theory, or maybe we could use one of the two NFC peer-to-peer APIs, SNEP (Simple NDEF Exchange Protocol) or LLCP (Logical Link Control Protocol).

We dismissed target emulation and focused on the peer-to-peer options, since this was clearly a peer-to-peer scenario. We concluded that either SNEP or LLCP could be used, but that SNEP would be a little easier to work with — LLCP being a lower-level connection-oriented protocol whereas SNEP is a higher-level message-oriented protocol. We’d worked with both in the past, so we had a pretty good feel for what the coding would be like.

In conclusion, we decided to invent a simple message-oriented protocol and use SNEP as the NFC protocol, which would transport game messages between devices. The UI design was to be basic: an initial screen that prompted players to touch devices to start a new game; a screen for “player 1” to choose either noughts or crosses; and the main game screen upon which to place noughts and crosses.

We also decided to implement the game for both BlackBerry® 7 OS using Java®, and our BlackBerry® 10 Dev Alpha devices using C++/Qt/Cascades. Being able to play the game between a BlackBerry 7 device and a BlackBerry 10 device would be a nice proof of the interoperability of NFC between generations of BlackBerry technology.

Here are some screen shots from the proof of concept game, first from the BlackBerry 7 version of the game:

Figure 1 – New game screen

Figure 2 – Player 1, choose nought or cross

Figure 3 – Main game screen

And here are some screen shots from the proof of concept game, from the BlackBerry 10 version of the game:

  
Figure 4 – New game screen; Figure 5 – In game; Figure 6 – Game over

Thoughts on the “game protocol” crystalized properly as we worked through prototyping the game and we found we needed the following message types in the simple protocol:

We’d like to tell you how we went about coding the game.

If you want to know how to use SNEP in general terms, we’ve written articles on the subject for both BlackBerry 7 and BlackBerry 10 and sample code too. You’ll find details here:

BlackBerry 7 – Peer to Peer Communication with SNEP
BlackBerry 10 – Peer to Peer Communication with SNEP

There’s a key point here: you could implement your Proximity Gaming ideas for either BlackBerry 7 or BlackBerry 10 because both have the specific types of NFC peer-to-peer capabilities that you will need.
Harnessing NFC SNEP in the way we wanted for our game was easy. The APIs themselves are very straightforward to use. For BlackBerry 7 we designed some Java classes, which represent the various message types in the game protocol. This was standard stuff if you’re accustomed to working with protocols, and we ended up with an abstract class called ProtocolMessage and a series of concrete sub-classes, one for each message type. Each of these classes implemented a marshall and demarshall method so that we could easily swap between byte array representations, which would be exchanged over NFC SNEP and Java objects for internal use in the application.

Here’s an example of one of the protocol message classes:

public class ProtocolMessageMasterBid extends ProtocolMessage {

    private int bid;

    public ProtocolMessageMasterBid() {
        message_id = Constants.PROTOCOL_MASTER_BID;
        Random rand = new Random(System.currentTimeMillis());
        bid = rand.nextInt(1000000);
    }

    public byte[] marshall() {
        byte [] bid_bytes = Utilities.toBytes(bid);
        byte [] bytes = new byte[1+bid_bytes.length];
        bytes [0] = message_id;
        System.arraycopy(bid_bytes, 0, bytes, 1, bid_bytes.length);
        return bytes;
    }

    public void demarshall(byte[] bytes) {
        if (bytes.length != 5) {
            Utilities.log("XXXX invalid parameter length passed to ProtocolMessageMasterBid demarshall:"+ bytes.length);
            return;
        }
        message_id = bytes[0];
        bid = Utilities.toInt(bytes,1);
    }

    public int getBid() {
        return bid;
    }

    public void setBid(int bid) {
        this.bid = bid;
    }

    public String toString() {
        String string = super.toString() + ",ProtocolMessageMasterBid" + ",bid="+bid;
        return string;
     }
}

We also implemented classes called NfcReceiver and NfcSender, which implemented NDEFMessageListener and NDEFMessageBuilder respectively and provided the basic mechanism for sending and receiving my protocol messages.

For BlackBerry 10, life was actually simpler and we just needed to create message using the Qt QbyteArray class and then utilize the BlackBerry 10 native APIs for NFC, as shown below:

void NfcWorker::sendTurnData(bps_event_t *bps_event) {
	nfc_event_t *nfc_event;
	nfc_target_t* target;
	nfc_ndef_record_t* myNdefRecord;
	nfc_ndef_message_t* myNdefMessage;
	// Obtain NFC target object from our BPS NFC event object
	//------------------------------------------------------------------------------
	CHECK(nfc_get_nfc_event(bps_event, &nfc_event));
	CHECK(nfc_get_target(nfc_event, &target));
	//------------------------------------------------------------------------------

	QByteArray ba;
	ba.resize(9);
	ba[0] = 2; // turn over message ID
	// tile changed
	ba[1] = 0;
	ba[2] = 0;
	ba[3] = 0;
	ba[4] = _state->lastSelection();
	int ls = _state->lastSelection();
	// symbol changed
	ba[5] = 0;
	ba[6] = 0;
	ba[7] = 0;
	ba[8] = _state->mySymbol();
	int ms = _state->mySymbol();
	_state->mySymbol();
	myNdefRecord = makeTurnOverRecord(ba.constData());
	//------------------------------------------------------------------------------
	CHECK(nfc_create_ndef_message(&myNdefMessage));
	//------------------------------------------------------------------------------
	CHECK(nfc_add_ndef_record(myNdefMessage, myNdefRecord));
	qDebug() << "XXXX Pushing NDEF message over SNEP";
	//------------------------------------------------------------------------------
	CHECK(nfc_push_ndef_message(target, myNdefMessage));
	//------------------------------------------------------------------------------
	CHECK(nfc_delete_ndef_message(myNdefMessage, true));
	CHECK(nfc_destroy_target(target));
}

So, having designed and implemented a message-oriented protocol and coded classes which used NFC SNEP to transport those messages between devices, the rest of the effort that rainy weekend was spent on standard game development issues like creating the UI. The UI was really easy to create for the BlackBerry 10 version using Cascades™, and took a fraction of the time and effort we spent on the BlackBerry 7 Java version of the game. In both cases, the NFC part was also quite easy and took relatively little effort as a portion of the whole application.

The next step was to find some guinea pigs to test the application out. (Not real guinea pigs, of course — their paws are too small and they have claws that make working with a touch screen problematic. So instead, we decided to use humans — our respective friends and family to be precise. )

Testing was informal. In my case, I explained I’d developed a two-player game that allowed you to take certain actions just by touching the two devices back to back. My guinea pigs generally looked a bit blank or even cynical at this point. “Just touch them together? Really?!” But with a little coaxing I got them started and watched them carefully.

At the very start of the game, the two players are instructed to touch devices to start the game. Looking a little unsure at first, the players touched devices and held them together for a second. The devices responded, vibrating to indicate an NFC message had been received, and the game moved on to the next screen to allow the selected Player 1 to choose noughts or crosses. At this point, the expressions on the players’ faces changed — from expressions that suggested they were being asked to participate in a black magic ritual to sheer delight with big smiles all around! And from that point, there was no stopping them. They were each playing on devices with touch screens – the BlackBerry® Bold™ 9900 and 9790 smartphones, to be precise – so selecting a place to put their mark on the game “board” was simply a case of touching the screen. And passing turns to the other player? They just touched the devices together, of course!

Here’s a video showing the game in use:

[ YouTube link for mobile viewing ]

The verdict was very positive. Players liked the idea in general and enjoyed the tactile element of the game play. It seemed that Proximity Gaming was a big hit!

The two versions of our NFC-enabled tic tac toe games are available with full source code from our github repositories here:

https://github.com/blackberry/Samples-for-Java/tree/master/NFC/TouchTicTacToe


https://github.com/blackberry/Cascades-Community-Samples/tree/master/TouchTicTacTen

So over to you, BlackBerry developers! How could you use NFC in your BlackBerry smartphone game?