I’ve heard a lot of people claim that the gamepad is dead – doomed to be replaced by touch screens. I disagree with this sentiment.  There’s nothing wrong with mobile games using cool new control schemes that make good use of touch screens – but if I’m playing a game that was designed with gamepads in mind, like Shadowgun, why can’t I just use a real controller?

Well, now I can – and so can you. Check out gamepad support now being added in upcoming Unity 4 for BlackBerry 10:

After years of being frustrated by touch screen gamepads, I’m excited about bringing physical gamepad support to the Native SDK for BlackBerry 10. By making use of the new Gamepad API features developers can make their games work with physical controllers, giving their players the tactile responsiveness they’re used to from consoles and desktop PCs. When this is combined with BlackBerry 10’s built-in HDMI connectivity, you end up with a console experience in your pocket!

Here is another video showcasing gamepad pairing instructions and a racer sample on GamePlay3D that now supports not only desktop gamepad support but also BlackBerry 10:

Before you get started implementing this in your own game, I want to answer a few of the most common questions people ask me about the API.

1. What gamepads are supported right now?
   1. The SteelSeries Free.
   2. The Gametel.
   3. The Wii Remote.  Note that currently only the core buttons on the remote itself are supported – that means no attachments and no motion controls, just the D-Pad and other buttons.
2. If new gamepads come out, do I have to update my game to support them?
   1. No, you don’t!  When new controllers become available, we’ll update the mappings in a system update and your game will start receiving gamepad inputs from the new hardware.  Because the Gamepad API is an abstraction above HID, and because we map each gamepad’s unique HID report format to the Gamepad API, you don’t need to write any code that’s specific to a single controller.
3. Do users need to install anything to set up or configure their gamepads?
   1. No.  The Gamepad API is integrated into the Screen library, the same library you are already using to handle touch, keyboard, and other input events.  All users have to do is pair their device through the Bluetooth settings screen for it to start sending inputs to your game.

We realize there are other gamepads out there and continue to work towards supporting as many devices as possible. If you know of a Bluetooth, HID-compatible game controller that’s not supported yet, please let us know in the comments. Meanwhile, the fact that you won’t have to change your code when we add more devices to the list means you only help yourself (and your users) by starting to use this new feature right away.

Here’s a tutorial that should get you up and running. It includes plenty of code snippets and is based on this open-source sample project, which started as a little app I whipped up to test the new API. It eventually turned into a demo of two-player connectivity and a configuration screen.  I hope you find it useful.

Please, for the sake of everyone who’s ever been frustrated by touch controls, try this new feature and leave your feedback – I’m eager to do what I can to help if you have any trouble.  Most of all, I’m looking forward to playing your games with a real gamepad!

Links:

• Tutorial
• Sample code
• SteelSeries Free
• Gametel

With bbUI v0.9.5, <meme>We Has JavaScript</meme>. The focus in this release has really been another round of bug fixes, optimizations and additional JavaScript interfaces. The previous versions of bbUI have started to improve with the number of JavaScript interfaces, but still haven’t provided full dynamic functionality. This release gets us further towards our goal of creating more dynamic user interfaces via JavaScript. While we’ve made major steps forward in this department with v0.9.5, we’re not finished yet and have much more planned for v0.9.6.

Be sure to check out the full change log for this release to know what kind of adjustments you may need to make to your app in order to run v0.9.5. Also, check out the closed issues for details on bug fixes and new features. Any v0.9.5 compatibility changes are fairly minor and are meant to make your life easier as we continue to move forward.

Notable Improvements

• Updated coloring/styling/sizing to better match Cascades
• New Title Bar styling allows for optional coloring other than the default light or dark
• Minified versions of the JavaScript and CSS files are now provided
• Action Bar back button and “button actions” highlight when touched
• Image Grids now allow for a specified number of columns in a row as well as horizontal carousel scrolling
• Action and tab overflow menus now vertically scroll items when there are too many options to fit on the screen at one time
• Toggle Buttons now support a disabled state
• Ability to refresh all the items in an image list at once
• Many new JavaScript interfaces for controls with updated samples to show how to use them
• Control bug fixes

Compatibility Changes

I mentioned that there were a few changes that were made that will affect your applications, so let’s talk about those:

• Image Lists:
• List items now only highlight if they have an associated onclick for the item or have a context menu assigned to the list.
• Images for image lists are now 109 x 109 for BlackBerry 10 devices to match the new list item height adjustment.
• You now simply include bbUI.js and bbUI.css in your application. There are no longer any version numbers as part of the source file names. Version numbers are now contained inside the files as code comments.
• The samples now show how to use your initialization code in the “webworksready” event for all BlackBerry OS versions.

More to Come

We’ve created an additional v0.9.6 milestone for bbUI that contains additional BlackBerry 10 styling improvements, and also includes more JavaScript interfaces for dynamic screen creation and manipulation. If you’re interested in following the bbUI.js changes as they go, feel free to follow me on Twitter.

If you have ever implemented Push across multiple platforms, then you have no doubt heard of Urban Airship, which offers a service to centralize and manage pushes to all devices. This greatly simplifies the process of managing and maintaining data delivery to a single application across a wide array of mobile environments.

Urban Airship officially supports iOS, Android, Helium for Windows, Windows 8, Windows Phone 8 and BlackBerry OS 7.1 and earlier. Every platform offers “push” in their own unique way, so traditionally you would need to tailor your server-side development uniquely for each platform being targeted. This can be a huge pain, especially when you need to do things like add new functionality, track currently-registered devices, determine the format for all the various push types and queries, and so on. With Urban Airship, you can have all devices from any of the supported platforms register against your online account; after that, all you need to do is interface with the Urban Airship server using relatively simple JSON-formatted commands to send data to any device that has your application installed. As if that wasn’t easy enough, there are also server libraries in a variety of flavors to speed up and simplify the process.

As you may have read in my previous blog post, from the server-side of things nothing has changed with respect to BlackBerry Push Services — if you have a server-side application that pushes to BlackBerry devices running OS 7.1 and earlier, the same application is fully capable of pushing to a BlackBerry 10 application. With that in mind, you may already realize that this means that the server portion of Urban Airship is already fully capable of pushing to BlackBerry 10; the only portion that is missing is the client-side. Today I am happy to announce that we have just published a BlackBerry 10 sample application using the Cascades framework to GitHub which demonstrates registering the device with an Urban Airship account so that it can begin receiving data pushes.

This sample handles the registration of the device with the device Push Notification Service, BlackBerry Push Services, and then finally with your specified Urban Airship account. Once completed, you can then log in to your Urban Airship control panel and begin sending test push messages to your newly registered BlackBerry 10 Dev Alpha testing device.

All account information is housed in one class to make modifying for your application as easy as possible — simply open UrbanAirshipAPI.cpp and modify the static string values here with those assigned for your application. After this is done, it should be as easy as compiling and running the application on a live device to begin testing out Urban Airship push notifications on BlackBerry 10.

Note: You will need to ensure your code signing keys have push permissions applied.

The UrbanAirshipAPI cpp and hpp files can also be added to your own application to easily add Urban Airship registration support.

If you have an Urban Airship account already and would like to start targeting BlackBerry 10 applications with your existing services, you can request access to an evaluation BlackBerry Push Services account here. On the flip side, should you already have a BlackBerry Push Services account and would like to explore the offerings of Urban Airship to either expand or consolidate your push offerings, you can request an account here.

For more information, please refer to the following resources:

GitHub Cascades-Community-Samples
BlackBerry Push Services overview
BlackBerry Push Services Documentation
Urban Airship home page

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

Guest post from Nukul – Ed.

We’ve received a lot of requests from developers to be able to build BlackBerry® 10 WebWorks™ directly from GitHub. Before I talk about how to take advantage of this, I would like to explain why it took us so long to get here and what it means for you.

The main issue was that the latest BlackBerry 10 WebWorks SDK features were dependent on features in the BlackBerry 10 OS. Therefore, if you built BlackBerry 10 WebWorks in open source, it potentially would not work with latest BlackBerry 10 OS beta.

This has changed as we get closer and closer to launch. We are now starting to work on features that are not dependent on the latest BlackBerry 10 OS beta. Imagine this: You hear about an awesome new feature or extension we are working on. You can now go to our GitHub repositories, look at pull requests, pull down the branch, and a few minutes later you have a BlackBerry 10 WebWorks build with the new extension or feature.

Build time can be less than two to three minutes from a clean build. From the time you see someone’s tweet about an awesome new feature, it could take you less than five minutes to get a build of BlackBerry 10 WebWorks that has that feature.

The advantages to a BlackBerry 10 WebWorks app developer are infinite here. You should never need to wait for new features. You can even build with Linux! It’s all there. There will still be some features that you will need the next OS release for, but that will happen less frequently as we get closer to launch of BlackBerry 10.

Here are the two repos you need to build to get ready to take advantage of this:

https://github.com/blackberry/BB10-WebWorks-Framework

https://github.com/blackberry/BB10-Webworks-Packager

The framework repo contains the Framework that is packaged with your app when you build a BlackBerry 10 WebWorks app. The Packager repo contains all the code for the packaging tool.

There are two main branches in each BlackBerry 10 WebWorks repo: master and next. The master branch will contain all the features that you can currently use with the current publicly-released OS — think of it as the features we wish we had time to get into the previous release. When a feature is completed, it’s merged into master if does not have any OS dependencies. The next branch will contain the new features that have OS dependencies.

To allow developers to easily build stable versions, each release is tagged using the version number of the release. This allows you to easily check out the source of a particular release. You can simply use the tags to check out the code from that release. For example, you can use “git checkout v1.0.2.9” to pull down the code for the last release. So, any pull request you see going into the master branch, you can grab and use right away. You will see none open today, but over the next couple of weeks you should start seeing many.

The README.md has been updated with all the updated instructions.
Run the unit tests, automated tests, all the developer tools we use are all available to you.

We are doing everything we can to enable developers to take advantage of our latest and greatest work. Just open an issue on our repo when you find an issue with our BlackBerry 10 WebWorks SDK. If you fix a bug or build an awesome extension, contribute it back and help us make BlackBerry 10 WebWorks SDK even better. For details on how to contribute, check out http://blackberry.github.com/howToContribute.html

We recently had Mark Robinson contribute changes to make SDK work on Linux — contributions like that go a long way. Be sure to see our growing list of contributors!

You can reach me any time on Twitter® @nukulb or send me a message through GitHub.

After a bunch of hard work, bbUI version 0.9.4 is finally here. The focus in this release has really been around bug fixes, optimizations and additional JavaScript® interfaces. The previous versions of bbUI have been VERY declarative and haven’t allowed for much manipulation after the fact via JavaScript. This release takes a step in the right direction to allow you to create more dynamic user interfaces via JavaScript. While there are some improvements in this department with v0.9.4, we’re not finished yet and have much more planned for v0.9.5.

One of the best things I’ve seen lately is the number of people participating in the project. It’s absolutely fantastic to see members of the community grab items from the roadmap, implement them and send them back as pull requests. These pull requests are full on feature creation as well as bug fixes. A gigantic THANK YOU goes out to all those who are helping to improve bbUI!

Be sure to check out the full change log for this release to know what kind of adjustments you may need to make to your JavaScript in order to run v0.9.4, and check out the closed issues for details on bugs that have been fixed and features that have been added. The v0.9.4 JavaScript changes are fairly minor and are meant to make your life easier as we continue to move forward.

Notable Improvements

• Updated coloring/styling to better match Cascades™
• New Title Bar styling which now allows images in the Title Bar
• New BlackBerry® PlayBook™ tablet 2.x styling for Activity Indicators, Text Input, Image Lists and Buttons
• Many new JavaScript interfaces to manipulate controls on-the-fly
• Native scrolling speed increases
• Screen stack bug fixes
• Control bug fixes

Changes to your code

I mentioned that there were a few changes that were made that will affect your applications JavaScript so let’s talk about those.

• bb.init()
  • bb10ActionBarDark renamed to actionBarDark
  • bb10ControlsDark renamed to controlsDark
  • bb10ListsDark renamed to listsDark
  • bb10HighlightColor renamed to highlightColor
• You no longer specify a viewport meta tag in your main index.htm. This is now supplied by the toolkit at runtime based on the OS version.
• BlackBerry® 10 title bars now take on the control coloring.
• You no longer need to specify a unique id for your script tags used with screens.
• Scroll Panel JavaScript interfaces have been modified.
• If you were calling bb.scroller.refresh() you will want to change your code to “if (bb.scroller) bb.scroller.refresh();”

More to Come

We’ve now created an additional v0.9.5 milestone for bbUI that contains additional BlackBerry 10 styling improvements, but also includes more JavaScript interfaces for dynamic screen creation and manipulation. If you’re interested in following the bbUI.js changes as they go, feel free to follow me on Twitter®.

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?

So how do you actually go about integrating features from these services into your application?  First the needs to allow your application access to their profile, and this bring us to Open Authorization – better known as OAuth.

OAuth you say?!

OAuth is an open standard for authorization used by tons of popular services, foursquare, Twitter, and Tumblr, to name a few.  It allows applications to connect their users to these services without having to handle their username and password.

There are a couple versions of OAuth which we have created sample apps for.

OAuth 1

Let’s be honest, OAuth 1 can be darn right nasty to work with out-of-the-box.  OAuth 1 and I are not really good friends, we’ve had many fights over the past year, and often I’ve been on the losing side.  In a nutshell, the way OAuth 1 works is by having an application perform a series of requests to a service, exchanging “tokens”, and ultimately granting the application access to the service on behalf of the user.  It requires several things to go just right, and if something doesn’t, access is denied.

Luckily there is a really awesome open-source JavaScript library written by Rob Griffiths (@bytespider) called jsOAuth. JsOAuth takes the pain and extensive process of OAuth 1 away, and allows you to focus on connecting your app with a service such as Twitter rather than spend a ton of time working with the OAuth 1 protocol.

OAuth 2

While OAuth 1 is my adversary; OAuth 2 is my best friend.  This is the next evolution of the OAuth protocol and is used by services like foursquare, and Facebook.  OAuth 2 is much friendlier for developers to integrate into their apps, and provides much easier, and straight forward authorization “flows” to work with.  Though the standard is still evolving, it’s solid, and in contrast to OAuth 1, is amazingly easy to work with.

The Sample Apps

Getting started with OAuth can be pretty intimidating to say the least.  As a former 3^rd party developer, I’ve been there.  I’ve screamed at my console log, cried like a baby, and even begged the OAuth gods for it to “just work”.  Since joining the BlackBerry® Developer Relations team here at RIM®, I vowed to help make this process easier for fellow developers and I’m glad to finally say that we’ve released two sample apps on GitHub today to help guide you on your OAuth journey.

The first sample app shows how to integrate Twitter into your application by using the OAuth 1 protocol.  You’ll learn how to quickly and painlessly authenticate with Twitter, and post a Tweet to a user’s timeline by taking advantage of the jsOAuth library.

The second sample shows integration with foursquare, and uses OAuth 2.  It’ll show you how your application can authenticate a user with the service, search for near-by venues, and then check-in to a venue.

The third sample shows how to integrate Facebook and OAuth 2 into your application.  You’ll learn how to authenticate a user with Facebook, and interact with their feed by posting, and reading content.

Each of these samples are completely Open Source, and available on GitHub.  If you find them useful, have any feedback, or need an extra helping hand along your way find me on the BlackBerry Developer Support Forums or Twitter @chadtatro.

We found many examples of things we’re doing right (e.g. automatic updates in Ripple). However, as we hoped to find, we also discovered examples of sub-optimal experiences where new developers could possibly be road blocked in their ability to complete their BlackBerry application. It is these latter examples that proved why we ran this exercise, and we are committed to continuing this review and will re-evaluate the platform again on a regular schedule.

Our group first started by identifying who our development community was. How did they think? What was important to them? How would their potential backgrounds influence how they flow through the “getting started with BlackBerry” experience? Our focus was on the following 5 personalities:

• “The coder” – Lives in a text editor and can modify their own path variable. Comfortable troubleshooting advanced issues without assistance. Likely have built a mobile app already.
• “The beginner” – Just getting started with mobile development or are evaluating BlackBerry Web dev. May have strong development skills in another language or none at all.
• “The desktop web developer” – Have a very strong understanding of client-server web development. Have successfully built web sites and may have used frameworks like jQuery, Sencha or Dojo.
• “The enterprise developer” – Cross platform is a primary goal. Prefers to use IDEs and typically works under an IT enforced environment.
• “The PhoneGap developer” – Someone who has come to the BlackBerry developer site to learn how to port their PhoneGap application

So what did we find? Lots! In fact, I’m still going through all the feedback. Everything from “would be nice” changes to “this is a gating bug and must be fixed” is being documented, and our intent is to file issues so the public can track them in the developer issue tracker . Here are just some of the results from the group:

• Discovery process: Search engine optimization should be improved. Keywords that each developer persona would expect to search for did not always generate correct search results.
  [Michelle] Search term: “enterprise development for BlackBerry 10” on Google. First result is to register for an outdated/unrelated course; next search results are for BlackBerry® Enterprise Server development.
• Sample applications: A number of BlackBerry WebWorks sample applications are published in Github. We need to refine the flow of navigating a user between blackberry.com and github.com. Also, for new developers, Github is unfamiliar. Some preparation of what to expect and how to use it will be helpful:
  [Kevin]: Sample apps… I am not super familiar with Github. Didn’t like getting dumped into git for samples. I’d prefer to get a zip to download. Managed to figure it out then.
  [Brent] – Click the link for samples on Getting Started – Taken to Github – what is Github? And what are these samples for – what do they do?
• HelloWorld sample: More developers will successfully complete the “Creating HelloWorld for BlackBerry 10” tutorial if we provide a direct link to a ZIP file that contains the sample application assets.
  [Brent] HelloWorld sample – copying and Pasting seems like a waste. Possible to download the helloworld package? – Creating config.xml in notepad and pasting the copied xml text puts it all on one lovely line. #NotImpressed
• Ripple: The Ripple Mobile emulator is currently designed to build and sign a BlackBerry WebWorks application. It also provides an option to deploy to a target device, but only when the app is unsigned. For simulators this is ideal; however, not for live devices where a debug token would be required. Not all developers want / know how to use a debug token.
  [Ed] The build choices are confusing and missing the one option I want. I want “package and sign, or package sign and deploy” to a real device. Package and launch is confusing because I don’t want to package and launch to a simulator, but when I do want to for a real device, I want it to do so signed, not with debug tokens I don’t use. I suggest: “Package”, “Package & Sign”, “Package & Sign & deploy” (to a real device” and “Package and launch” to simulator. the last one, the least likely to use.

Here’s how you can send us feedback -

1. Join the discussion in the BlackBerry Web and BlackBerry WebWorks community forum.
2. Log into the developer issue tracker and file a bug report. Remember to provide as much detail as possible about how to reproduce the problem and what are the expected / actual results.
3. Let’s have a chat via @BlackBerryDev on Twitter® or the BlackBerryDevCommunity on Facebook®.

Calling all Java® developers: We have some news regarding the BlackBerry® Java® Plug-in for Eclipse™!

We are pleased to announce a new Open Source project for the BlackBerry development platform. While we have stopped SDK work on BlackBerry® 7 OS, we’ve decided to make the source code open for all those developers using the Java Plug-in for Eclipse. The BlackBerry Java Plug-in for Eclipse is now available as a repository provided under the Eclipse Public Licenses 1.0. The BlackBerry Java Plug-in for Eclipse lets you develop, test, and debug BlackBerry Java applications using the Eclipse IDE, in combination with the BlackBerry SDK appropriate for the BlackBerry OS your application is targeting.

The readme file on the project page details all the information you will need to build the source code for Windows or Mac, build your own update site for the plug-in or even build your own full installer. For all the details, jump to the project page.

Additionally, the BlackBerry Java Plug-in for Eclipse 2.0 is now available for download as a complete install for Windows and Mac, or as an update via our Eclipse update sites. For more BlackBerry Java related information, tool downloads, sample apps and documentations, please visit our Java development page — and make sure to fork us on Github!