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++!

Did you know that your NFC-enabled BlackBerry® smartphone may be able to process NFC transactions, such as payments, even when it has a completely dead battery? Smartphones which support NFC will continue to be able to provide NFC card emulation functionality when in “low battery mode” or, in some circumstances, even when the battery is completely dead.

Let’s explore what the difference between “low battery” versus “dead battery” is before we move on.

Low battery mode starts when the smartphone OS turns off the user interface due to the battery being deemed “low”. The smartphone appears to be off to the user, but internally, the Power Management Integrated Circuit (PMIC) is still on. Dead battery mode, by way of contrast, starts when there is no longer enough power in the battery to keep even the PMIC powered on.

How long low battery mode will last before moving into the dead battery state varies from smartphone to smartphone, but is typically at least four or five hours.

In low battery mode, all BlackBerry smartphones will continue to be able to provide NFC card emulation functionality. But when it comes to dead battery mode, whether NFC card emulation will continue to work or not depends on the smartphone model; for instance, the BlackBerry® Curve™ 9380 smartphone and BlackBerry® Bold™ 9790 smartphone do support dead battery mode. This mode is not supported on the BlackBerry® Bold™ 9900 smartphone and BlackBerry® Curve™ 9360 smartphone.

The user has no way of knowing just from looking at their smartphone if they are in low battery mode or have a completely dead battery. Because of this, they have no way of knowing whether or not NFC transactions in card emulation mode will work or not in a given instance.

Developers have an API function called
SecureElementManager.setCardEmulationWhenPoweredOff(true|false) which they can call to control whether or not card emulation will work or not when the battery is dead or has been removed.

You may also have noticed that the Near Field Communication options screen has a setting in the section entitled “Allow NFC Card Transactions” labelled “When Powered Off”. This setting will also affect the behaviour of a device when in low battery or dead battery mode.

To learn more about NFC, check out our online developer documentation.

Our first task was to establish whether or not we could read the content of the tags any way at all and if so, to determine just what that content was.

Now, an NFC tag is a smart card and it responds to ISO 7816-4 APDUs, so it’s possible to work with it at a lower level than would be the case when using the BlackBerry NDEFMessageListener Java® interface – which is how we’d normally seek to read an NFC tag from a BlackBerry® smartphone application. As such, armed with the NFC Forum specifications for NDEF tags types 1-4 in one hand, the ISO 7816-4 specs in the other, and a contactless card reader in errrrr…the other, we set to work.

Our investigation proceeded on two fronts: John had been looking at a Python API for smart card developers called “pyscard” for a while and thought we could do something with that. We also contacted our own NFC product development team for advice, and they provided a BlackBerry smartphone app that they use to dump the content of tags to the device screen.

While sitting in the hotel bar drinking coffee and huddled around my laptop, it wasn’t long before John and I had a Python script running which was able to dump and decode the content of the tag. Through trial and error, we determined that we were dealing with a Type 2, tag and the decoded data produced by our script agreed with the data produced by the app our development team had provided. On examining the details carefully, we could see the problem with the tags as plain as day. Here’s part of what our script produced. Can you see the issue?

NDEF data:

TNF : 3 RFC 3986 ABSOLUTE URI
Type Length : 1
MB (Message Begin) : 1
ME (Message End) : 1
CF (Chunk Flag) : 0
SR (Short Record) : 1
IL (ID Length) : 0
Payload Length (SR): 34
Type : U
Payload (hex) : 68 74 74 70 3A 2F 2F 6F 6E 2D 74 61 70 2E 6E 65 74 3F 74 3D 30 69 38
34 76 69 65 71 38 7A 65 73 31 6E

The problem is that there’s a mismatch between the value provided for TNF (Type Name Format) and the data in the Type field.

TNF=0×03 means the tag contains an “absolute URI” as defined in RFC 3986. When this value is specified, then the Type field should contain a valid URI and the payload should be empty. As we can see, however, the Type field contains “U” in this case.

Of the other values which TNF could take, a value of 0×01 means the tag contains an “NFC Well Known Type”. Well known types are pre-defined record types and formats which the NFC Forum devised to support common use cases. When TNF=0×01, the Type field contains a short code which indicates which of those well known types the payload represents. Values include “Sp” for smart poster, “T” for Text and “U” for URI. So as you can see, there are two ways of encoding a URI; either with TNF=0×03 and an empty Type field or with TNF=0×01 and Type=”U”. Clearly whatever tool was used to write the tags on the flyers has a bug, since these two distinct cases seem to have been mixed up so that we have the invalid combination of TNF=0×03 and Type=’U’.

So, the mystery of the unreadable tag was solved! Hopefully this account provides some insight into a real-world issue and the activities involved in investigating such a problem.

Have fun with NFC!

BlackBerry DevCon Europe in Amsterdam was my first BlackBerry conference and I have to say, I thoroughly enjoyed the experience. It was a great pleasure to meet developers who I’ve been working with by email but have never actually met in person.

Judging by the feedback received from attendees, the presentation I gave with John Murray, “DEV311 – How to develop an NFC enabled app,” was extremely popular. NFC is really a very large topic, especially when you start to move away from the simple use cases such as tag reading and into more technically-involved use cases, such as payment. It was a shame we were limited to a mere one hour. We could have talked about NFC all day!

However, there was an “incident” in the first of two NFC sessions which we presented, and it’s that incident that I want to write about here.

The event organizers had placed flyers on the chairs in the room, advertising another event that John and I would be at. The event is a NFC Hackathon to be held in London the weekend of March 24th and which our carrier partner O2 is sponsoring. (We’d love to see you there. You can find details at the following web site: http://www.isobar.com/en/news/2012/2/3/create-london)

The flyers had NFC tags fixed to the back of them and John and I knew nothing about this, so we were somewhat surprised when a member of the audience – as the very first question in our first session – said, “So why can’t my BlackBerry® Bold™ 9900 smartphone read this tag?!”
As anyone who has ever presented or done live demos of anything will know, things do go wrong from time to time and that’s all part of the fun. But this one came out of nowhere and we were, to put it mildly, a little stumped by this question initially!

Problems tend to indicate opportunities though, so given that I was presenting on the topic of tag reading when the question was asked, whilst I couldn’t say anything definite at the time (issues like this need technical investigation, as you’ll see), it did give me the opportunity to talk about standards and degrees of compliance. It’s a fact that of the many makes and types of NFC tags that are out there in the world, some comply 100% with the relevant NFC Forum and ISO standards whilst some do not. We’ve worked hard at RIM to ensure our products comply with those standards since for a technology like NFC to gain wide spread adoption, inter-operability between tags and devices and between devices themselves is absolutely crucial. That said, even if a tag complies fully with the technical standards, it’s still possible to write non-standard content to it, so we all have a responsibility to comply with those standards, not just the device vendors.

Having made my small speech about standards, we moved on and completed the presentation. But the story didn’t end there because neither myself nor John are the kind of people to be satisfied with anything less than a complete and technically accurate answer to issues of this sort! So we collected samples of the flyers with their tags and took them back to the hotel where we proceeded to analyse their content. We call this “NFC Forensics!”

The second part of this story will be posted tomorrow; until then send us your thoughts about what you think happened!