Marmalade SDK and Blackberry Playbook – From Setup and Deployment to App World Submission

The latest version of the marvellous Marmalade SDK 5.1.3 has recently hit our development machines. Whats so special about 5.1.3 you ask? Well for starters you can now deploy your smart phone and tablet apps and games to the awesome Blackberry Playbook. If you haven’t had the chance to tinker with one of these beauties then I suggest you go and have a play because they are fantastic tablets. Amazon are selling them right now here for 16GB version and here for 64GB version

Ok you read this far and thought, “hmm, what the hell is the Marmalade SDK fool?”, sounds like something you would spread on toast and not actually use to make ground breaking cross platform games and apps. For those developers that have been asleep for the last couple of years or maybe just missed the name change, the Marmalade SDK is the newly named AirPlay SDK created by the boffins over at IdeaWorks. The marmalade SDK is basically an awesome system that allows developers to develop apps and games using a single unified API for a whole host of platforms including Apple iPhone, iPad, Android phones & tablets, Samsung Bada, Blackberry Playbook, Web OS, Symbian, Windows Mobile, Windows, Mac and others. How do they do that you may ask, well don’t ask me! take a trip over to http://www.madewithmarmalade.com and take a look

Ok, shameless plug for my favourite SDK of all time out of the way, now on with the article

We have recently just ported one of our games “BattleBallz Chaos” to the Blackberry Playbook platform and had it published in record time (for our company at least). Within 24 hours we went from receiving our Blackberry Playbook test tablet and our unified Android, iOS, Bada code base to “on the App World store!” For those interested you can check out BattleBallz Chaos here and more info about our other versions for iPhone, iPad, Android, Bada and Windows Phone 7 is at http://www.battleballz.com

You are probably here because you are pulling your hair out trying to accomplish one of the following:

• Deploy a debug build to an actual Blackberry Playbook tablet
• Having trouble getting your build ready for submission to RIM’s Blackberry App World store
• Need to know the splash screen, icon formats and sizes for a Blackberry Playbook build
• Other random issues with Marmalade or Blackberry Playbook deployment or submissions

Well for whatever reason I hope this article can help you in some small way, now on with the article

Preparing your system

1. Grab a copy of the Blackberry Web Works SDK from http://us.blackberry.com/developers/tablet/webworks.jsp. Note that you will also have some other tools to install which are listed on that same page, just follow the instructions
2. Install the SDK to your development machine as specified

You may be wondering why you would need to install the HTML5 SDK when you are deploying a native application. The reason is that you need the binary tools that are located in this SDK. Note that the native SDK is Beta at the moment and is only available by asking Blackberry directly for access to the beta program at http://03268fe.netsolhost.com/bbbeta/

Set up your PC to allow signing with the Blackberry signing server: (Only has to be done once)

3. Go to Blackberrys online code signing keys request tool at https://www.blackberry.com/SignedKeys/, fill in the information and submit,. You will be emailed 2 registration files that look something like this (DONT FORGET YOUR PIN!):

• client-RDK-195133201.csj – This is for the signing process (RBK)
• client-PBDT-195133201.csj – This is for the debug token creation process (PBDT)

NOTE: It may take a few days to get the registration files so apply for them immediately

4. Now lets actually do the set-up process

* Copy the registration files from step 3 into a folder (lets call it ‘Playbook’)
* Open up a command prompt and change to the ‘Playbook’ folder you just created
* Run the following commands at the command prompt:

"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-keytool" -genkeypair -keystore sigtool.p12 –storepass {your_password} -dname "cn={your_company_name}" -alias author
"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-signer" -csksetup -cskpass {your_password}
"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-signer" -register –csjpin {your_pin} -cskpass {your_password} client-RDK-195133201.csj

{your_password} – Choose a password that you are going to remember
{your_company_name} – Company name as specified when you requested the registration files in step 3
{your_pin} – The pin you created when you requested the registration files in step 3
client-RDK-195133201.csj – Change this to the name of the RDK CSJ file that you received in your registration files email in step 2

NOTE: The location where the blackberry-keytool and blackberry-signer will probably be different depending on which SDK you are using and where you installed it

Set up your PC to enable generation of debug tokens (Only has to be done once)

5. Open up a command prompt and change to the ‘Playbook’ folder created in step 4 then enter the following at the command prompt

"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-debugtokenrequest.bat" -register -cskpass {your_password} -csjpin {your_pin} client-PBDT-195133201.csj

{your_password} – The same password that you chose in step 4
{your_pin} – The pin you created when you requested the registration files in step 3
client-PBDT-195133201.csj – Change this to the name of the PBDT CSJ file that you received in your registration files email in step 2

Generate a debug token to allow deployment of debug builds to the Blackberry Playbook tablet

6. Open up a command prompt and change to the ‘Playbook’ folder created in step 4 then enter the following at the command prompt

"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-debugtokenrequest" -cskpass {your_password} -keystore sigtool.p12 -storepass {your_password} -deviceId 0x{device_id} name_of_your_debug_token.bar

{your_password} – The same password that you chose in step 4
{device_id} – Your Blackberry Playbooks device ID
name_of_your_debug_token.bar – Note that you should not use any funny characters or spaces in this name, best bet is to name it something like companynamedebugtoken.bar

NOTE: To find your Blackberry Playbooks device id do the following:
* Tap the settings icon in the top right hand corner of the playbooks screen to bring up settings
* Select “’About ‘ item on the left hand side menu
* In the drop down box to the right selected “’Hardware’
* The ‘PIN’ number shown is your device ID

Install the debug token to the Blackberry Playbook tablet

7. if you haven’t already done so then ensure that you have connected your Playbook to your local Wi-Fi network. Go to Settings->Wi-Fi and set it up here.
8. Go to settings->About then select ‘Network’ from the drop down list to the right which displays info about your network. Now note down the IP address of the Playbook (something like 192.168.1.2)
9. Enable “Development Mode” on your Blackberry Playbook as follows:

* Go to Settings->Security->Development Mode
* Slide the development mode slider to “On”
* You will be asked to enter a password (for simplicity use the same password as you use for logging into your Playbook)
* Select “Upload debug token” button

And finally to install the debug token to the Playbook, open up a command prompt and change to the ‘Playbook’ folder created in step 4 then enter the following at the command prompt to install the debug token to the Playbook

"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-deploy" -installDebugToken name_of_your_debug_token.bar –device {ip_address} –password {playbook_password}

name_of_your_debug_token.bar is the name of your debug token that you create in step 6
{ip_address} – The IP address that you noted down in step 8
{playbook_password} – This is the security password that you have set for your Blackberry Playbook (The one you type in when you log into your Playbook)

Ok, the hard bit is out of the way, take a breather and go for a coffee, next part is deploying via the Marmalade SDK, which is thankfully a much easier process

Deploying your Marmalade SDK app to the Blackberry Playbook tablet

There are a few things you need to do on the Marmalade side in order to get your build ready for deployment to the Blackberry Playbook:

10. MKB project file modifications

* If you want to appear as the author for your app then you need to add the following to the Playbook deployment section of your MKB:

playbook-author='Your company name'

* So that RIM can identify you as the real author of the app they need to know your author ID. The line in your MKB will look something like this:

playbook-authorid='gBACAgDE-PVmaTowNV2UQzp61q32'

The aiuthor-id is however a little elusive. The easiest way to find it is to rename the “name_of_your_debug_token.bar” file that you generated in step 6 as a zip file “name_of_your_debug_token.zip” for example. Open the zip file and extract the MANIFEST.MF file. open this file in a text editor and fiind the field called “”Package-Author-Id” the value for this field is the authorid you need to supply to the Marmalade build system

* To set the Splash Screen and icon use the following two MKB commands:

splashscreen=PlaybookSplash.png
icon=PlaybookIcon.png

The splash screen and icons will be scaled to the correct sizes, but I recommend choosing a large sized splash screen that matches the 1024 x 600 pixel aspect ratio screen and 86 x 86 pixel icon (rounded corners and transparency are allowed in the icon)

Ok, now you have this in place, compile and run your ARM release build. When the Marmalade deployment tool runs and gets to the final stage of deployment you need to enter the following details:

* Device hostname (or IP address) – Enter the IP address that you noted down in step 8
* Device password – Enter your playbook security password (The one you type in when you log into your Playbook)

If you selected Package and Install in the previous Marmalade deployment step then you should find your apps shiny icon on the Playbooks screen (under games category most likely)

Ok, you can now deploy your build to an actual Blackberry Playbook, but what about preparing your BAR file for submission to Blackberry App World, we shall cover that next

Preparing your app for submission to the Blackberry App World Store

In order to submit your app to Blackberry for App World approval you will need to sign your BAR file:

11. Edit the file located at “\Marmalade\5.1\s3e\deploy\plugins\qnx\MANIFEST.MF” and change the line that reads “Application-Development-Mode: true” to “Application-Development-Mode: false”. Remember to change it back to true when you are deploying development builds
12. Open up a command prompt and change to the folder where you MKB is located (lets say for example ‘e:\Apps\CoolGame’)
13. Copy the file ‘sigtool.p12’ from the ‘Playbook’ folder that you created in step 4 into the folder specified in step 12
14. Run the following commands at the command prompt: (when resigning the same build you only need to perform steps 12 and 14)

"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-signer" -verbose -cskpass {your_password} -keystore sigtool.p12 -storepass {your_password} build_coolgame_vc10\deployments\Blackberry\playbook\release\CoolGame.bar RDK
"E:\Program Files\Research In Motion\BlackBerry WebWorks SDK for TabletOS 2.1.0.6\bbwp\blackberry-tablet-sdk\bin\blackberry-signer" -keystore sigtool.p12 -storepass {your_password} build_coolgame_vc10\deployments\Blackberry\playbook\release\CoolGame.bar author

{your_password} – The same password that you chose in step 4
build_coolgame_vc10\deployments\Blackberry\playbook\release\CoolGame.bar – You need to replace this section with the relative path to your .BAR file for your app

You now have a signed BAR file that you can submit to Blackberry App World for approval! Good luck with your submission and good luck with sales!

A Few Notes

* You can choose a separate CSK password and store password if you like to increase security
* Remember to replace the path to the Blackberry tools with the correct path for your Blackberry SDK install
* Our app only took around 16 hours to get approval but we noticed that the number of new apps appearing around our time of submission were few and far between so it could take longer
* Ensure you have a working internet connection throughout the whole process as the Blackberry tools will need to query various external servers
* If you are having trouble with deploying your debug build then ensure that a) Your Blackberry Playbooks IP address has not changed and b) Your debug token has not expired (they have a very short life span)
* If you would like your app to be classified in a category other than “’games’ you will need to change the application category line “Application-Category: core.games” located in the file “\Marmalade\5.1\s3e\deploy\plugins\qnx\MANIFEST.MF”

Confirming that your app has been signed

To confirm that you app has been signed by both the RIM signing authority and yourself open your BAR file as a zip file and check the META-INF folder. This folder should contain 5 files:

* AUTHOR.EC
* AUTHOR.SF
* MANIFEST.MF
* RDK.EC
* RDK.SF

If any are missing then something went wrong and you need to sign again. Note that if you receive an error saying something along the lines of “already signed” then change your version number, rebuild and re-sign