Back in 2007 I wrote a BlackBerry OS application to perform a simple e-mail routing health check procedure. It turned out to be a hellish process, and not just for the fact that I’m not much of a Java developer (I don’t include Java in my list of skills on my resume). That was a minor problem compared to the overly involved process that had to be undertaken in order to simply compile the damn app and deploy it to a handheld for testing. On top of all that, Research In Motion at that time required that any developer who wished to use certain parts of their API, even just to test on their own device, to register at the cost of $200 USD. My employer paid this fee on my behalf, but it capped off an unpleasant process.

Times have changed and RIM has learned a few lessons. Developers no longer have to pay RIM merely for the pleasure of developing an app, but they do still face an unclear process for deploying to a test device. For both my own sake and for other developers, I’ve attempted to do a comprehensive write up of the process of deploying a BlackBerry WebWorks app to a PlayBook tablet. It consists of ten rather involved steps, but after the first time you do it once the process shrinks down to just the two last steps.

All right – let’s both take a deep breath and get started.

Before you attempt to deploy a WebWorks app, fill out the BlackBerry Code Signing Keys Order Form. While this costs you nothing, there is a 24 to 48 hour delay to recieving your key, so try to do this as soon as possible. You will eventually receive two *.CSJ files by e-mail that will allow you to complete the rest of this process: A ‘PDBT’ token used during your debugging, and an ‘RDK’ token used to sign your completed app when you submit it to the App World. Make note of your Registration PIN as you’ll need this in a step listed below.

Step One

Download Adobe AIR SDK 2.7 and the BlackBerry WebWorks SDK for Tablet OS for Windows. (For the WebWorks SDK download, you’ll need to register before you can download the EXE installation file.)

Step Two

Unzip the Adobe AIR SDK to C:\Program Files (x86)\AdobeAIRSDK . Install the WebWorks SDK to the default location (on my Windows 7 PC, that was to C:\Program Files (x86)\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6 ).

Step Three

Now that we’ve got all of the utilities of the SDK set up, we’ll set up our Windows PC and get rid of the Windows error message to be able to sign applications to be deployed to a tablet in development mode. Open a Command Prompt and input the following:

cd ".\bbwp\blackberry-tablet-sdk\bin"
blackberry-keytool -genkeypair -keystore sigtool.p12 -storepass myp12password -dname "cn=My Company Name" -alias author
blackberry-signer -csksetup -cskpass mycskpassword
blackberry-debugtokenrequest -register -cskpass mycskpassword -csjpin myregistrationpin mycsjfile.csj

To explain each of these lines step by step:

• Line #1 changes the directory to the \bin folder of the BlackBerry Tablet SDK.
• Line #2 creates the file sigtool.p12 using the password value of myp12password and the author My Company Name. I’m told that commas in the author name cause issues, so avoid that.
• Line #3 sets up long term keys for communication with the signing authority server under the password mycskpassword, and generates the file mycsjfile.csj.
• Line #4 registers your machine with the signing authority server, referencing your CSK password of mycskpassword, the Registration PIN you entered in the BlackBerry Code Signing Keys Order Form (myregistrationpin) and the ‘PDBT’ *.CSJ file you received via e-mail.

Step Four

To move forward, we need an app to deploy. For the purposes of this guide, let’s deploy a sample application we know works. Download Marco van Hylckama Vlieg’s Unit Converter application from GitHub (click the Downloads button on the right side, select the *.ZIP file). Unzip that application into a local directory (for our example, C:\Development\UnitConverter\ ).

Step Five

Create a zipfile out of the contents of C:\Development\UnitConverter\ (the root directory should have config.xml in it, not a directory containing that file and others) and place it at C:\Development\UnitConverter.zip. Then run the following command which will create the file C:\Development\UnitConverter.bar:

".\bbwp\bbwp.exe" "C:\Development\UnitConverter.zip" -o "C:\Development"

Step Six

Let’s prep our physical PlayBook tablet to accept apps in development mode. Swipe down from the menu screen to reveal the configuration menu. Select Security, Development Mode, and set Use Development Mode to On. You’ll be required to set a password, which for this example will be devicepassword.

When this is complete, swipe the configuration menu back upwards and take notice of the new icon of a person with a gear in the top-right corner of the PlayBook’s display. Tap this icon to reveal the Development Mode menu. Take note of the IP Address value, as we’ll need it for the next step (for this example, we’ll use the value of 192.168.1.101).

Step Seven

Our next step is to create a debug token that allows us to place test versions of applications on our PlayBook tablet. Open a Command Prompt and input the following:

cd ".\bbwp\blackberry-tablet-sdk\bin"
blackberry-debugtokenrequest -cskpass mycskpassword -keystore sigtool.p12 -storepass myp12password -deviceId 0x12345678 "C:\Development\DebugToken.bar"
blackberry-deploy -installDebugToken "C:\Development\DebugToken.bar" -device 192.168.1.101 -password devicepassword

To explain each of these lines step by step:

• Line #1 changes the directory to the \bin folder of the BlackBerry Tablet SDK.
• Line #2 creates a debug token as a *.BAR file, requiring your mycskpassword, your keystore file sigtool.p12, the password to your keystore myp12password, your PlayBook’s PIN (About > Hardware > PIN) with the characters 0x placed in front (0x12345678), and the path and filename of the new debug token file, C:\Development\DebugToken.bar.
• Line #3 transmits the debug token to your PlayBook, requiring you to input the tablet’s IP address 192.168.1.101 and the password you set in development mode, devicepassword.

Step Eight

We need to add a blackberry-tablet.xml file to your application, and will need to retrieve two values from our packager first. Run the following:

blackberry-airpackager -listManifest "C:\Development\DebugToken.bar"

Scroll back up through the output and make note of the following values:

Package-Author: My Company Name
Package-Author-Id: gYg7vhn3Q-5hjwnvbn67ckm3uvn

Create a new file called blackberry-tablet.xml in the same folder of your app as config.xml with the following contents:

<qnx>
	<author>My Company Name</author>
	<authorId>gYg7vhn3Q-5hjwnvbn67ckm3uvn</authorId>
	<category>core.all</category>
	<action>play_audio</action>
	<buildId>1</buildId>
	<platformVersion>0.1.0.0</platformVersion>
	<icon>
		<image>icon.png</image>
	</icon>
</qnx>

Step Nine

Re-do Step Five (create a zipfile, output a *.BAR file) to repackage your app with the blackberry-tablet.xml inside it.

Step Ten

Would you believe this is the last step? It’s straightforward, too – it simply deploys your *.BAR file to your PlayBook:

".\bbwp\blackberry-tablet-sdk\bin\blackberry-deploy.bat" -installApp -password pass -device 192.168.1.138 -package "C:\Development\UnitConverter.bar"

You’re Done!

Assuming the result of your last step contained the message “result::success”, you’re done! Take a look at your PlayBook’s menus and select your application. It should start without issue and allow you to explore your app’s performance on a real-world PlayBook device.

As mentioned earlier, after this first deployment you’ll only ever have to re-run Step Nine and Step Ten to load updated copies of your app onto the device (plus the occasional upload of a new debug token, as each last 10 days).

References

• BlackBerry Code Signing Keys Order Form
• BlackBerry WebWorks SDK for Tablet OS
• BlackBerry Support Forums: Where can I find Adobe AIR SDK 2.5?
• GitHub: Unit Converter
• Development Guide: Configure signing for tablet applications
• Development Guide: Create a debug token from the command line
• BlackBerry Developer’s Blog: Getting Started Tips for BlackBerry WebWorks SDK for Tablet OS
• MELLISdesigns Official Blog: Install Blackberry Playbook Debug Token Guide
• BlackBerry Support Forums: blackberry-template.xml category choices
• BlackBerry Support Forums: Backup and Restore BlackBerry Code Signing Keys