Building and Deploying Samples for AIR

The Samples-for-AIR project is publicly available online at github and can be downloaded using  git version control.

Using git, perform the following in a command prompt:

git clone https://github.com/blackberry/Samples-for-AIR.git

The above command will copy Samples-for-Air source to Samples-for-AIR directory.

GitHub also provides git-less access to a repo’s sources via a zip-ball.  In this case, point your browser or curl to https://github.com/blackberry/Samples-for-AIR/zipball/master and unzip.

Importing project into Flash Builder 4.5

Adobe Flash Builder 4.5 and Blackberry Tablet OS SDK for Adobe AIR are both required to build the Samples for AIR project. See http://us.blackberry.com/developers/tablet/adobe.jsp

Once you’ve checked out the Samples-for-Air project, launch Flash Builder 4.5 and click File\Import\Flash Builder\Flash Builder Project

Select Project Folder Samples-For-Air\SampleLibrary and click Finish.

Repeat the above steps and import Samples-For-Air\SampleApplication and click Finish.

You should now have two projects SampleAirApplication and SampleAirLibrary. You’re now ready to begin exploring the sample application and library.

When creating this project Adobe AIR SDK version 3.1 was used with the BlackBerry tablet OS SDK. Therefore, if you’re using a different Adobe AIR SDK version, SampleAirApplication/src/SampleApplication-app.xml may require a change.  If you experience the following error:  Namespace x.x.x in the application descriptor file should be equal or higher than the minimum version x.x.x required by Flex SDK

The above example shows changing the xmlns version to 3.1 in the line

<application xmlns=”http://ns.adobe.com/air/application/3.1″&gt;

in SampleAirApplication/src/SampleApplication-app.xml to match the version of the Adobe AIR SDK version 3.1 installed.

Deploying Sample AIR project to the BlackBerry Playbook

NOTE, some included APIs will not execute within Desktop Application Flash builder debug profiles.

Select SampleAirApplication and choose Run As Mobile Application (or Debug As)

Set the following properties in the Debug Configurations window:

• Project: SampleAirApplication
• Application File: src/SampleApplication
• Target Platform: BlackBerry Tablet OS
• Launch Method: On device

NOTE: When configuring BlackBerry Tablet test device profile USB is preferred as WiFi reception can cause the connection to fail, depending on your WiFi signal strength. The USB port starts with 169.254.*.* If you are using Tablet OS version 1.0.7 and above the IP address will be 169.254.0.1 and set the debug host to 169.254.0.2.

Edit BlackBerry Tablet OS Test Device. These settings must match those in the Playbook OptionsSecurityDevelopment Mode see Enabling debug mode on the BlackBerry Playbook.

Enabling debug mode on the BlackBerry Playbook

Enable development mode on your BlackBerry Playbook by visiting Playbook Options\Security\Development Mode and set Use development mode set to on.

Need help installing a Debug Token in your Playbook?

Customizing the Sample Library package path and directory structure

Open Samples-for-AIR\SampleLibrary\build.xml with your favourite editor and locate the line:

<property name=”generated.package.root” value=”com.playbook.samples”/>

To change the package path of the sample library change value=”com.playbook.samples” to your preferred package path. e .g.

<property name=”generated.package.root” value=”net.foo“/>

Then, from a command prompt, execute ant in Samples-for-AIR\SampleLibrary

$ ant

Buildfile: c:\temp\Samples-for-AIR\SampleLibrary\build.xml

generatesource:
[echo] Generated source will copied to: generated/net/foo
[echo] Target package: net.foo.*
<snip>
[echo] Generated source copied to: generated/net/foo
[echo]
[echo]

BUILD SUCCESSFUL
Total time: 1 second

The newly generated source files will be found in Samples-for-AIR\SampleLibrary\generated

After running the above example, the package path in each source file starts with net.foo. e.g Samples-for-AIR\SampleLibrary\generated\net\foo\ui\menu\Menu.as contains package net.foo.ui.menu

 

See related post Samples for AIR: An open source project for the BlackBerry Playbook.

 

DosBox on PlayBook – The Engadget Appearance

Our port of DosBox (wikipedia, web site) made it to Engadget last week.  The journey from our GitHub repo is interesting:

At CrackBerry, jamesjmunro started a CrackBerry thread on October 24th, pointing out the new repo.  The next day several other members of the forum started working on compiling the sources, tracking some missing instructions and configurations.   You can see the results of this being incorporated into the GitHub repo in the commit history (Oct 25th, 26th, and 29th).  And on Nov 4th, a7tomic reports success: dosbox is now running.  That was post #8; the CrackBerry thread picks up from there and soon started moving into how to run specific games.

Next seems to have been an appearance by BBIn.  They created a video showing  how the PlayBook running DosBox running MS-DOS  (5.0?),  They also showed how to mount the disk and how to run some classic games (Prince of Persia, Wolf-3D, The Lion King).

The games did it – DosBox is an abstract concept, but a popular game is very concrete.  From BBIn the news went to n4bb, and from there to Engadget.  And I see The Verge also did a piece.  All this on Nov 17th.

At some point the OSBB folks did a news piece that includes a screen shot of Windows 95.  The piece is dated Nov 18th, but the screenshot shows in the Engadget post from Nov 17th.  Maybe different Time-Zones, I didn’t check.

And this is how Open Source works!

Stay tuned for a future post that shows how to build the DosBox sources, in a way similar to how we showed how to build TunnelTilt.

Samples for AIR

The Samples for AIR open source project, available at github,  offers sample APIs written using Blackberry Tablet OS SDK for Adobe AIR. APIs include common utilities and UI elements such as animated screen transitions, navigation menu, media component, search field, and download manager. A fully functional example application that demonstrates how to use the provided APIs is also provided.

Added Also check out the detailed note on How to Build and Install the Sample Application.

Sample Library

Navigation menu
A customizable navigation bar offers optional elements, such as tabbed browsing and search input field. Buttons that launch user options, help and return to home are also available. Clicking the help icon launches the browser to supplied URL.

Search field
A customizable search field allows users to type search text that filters words that match characters as they type.

Download Manager
The download manager is a utility that maintains a queue of tasks consisting of the source URL, destination file path and relevant meta-data. Tasks can be added, paused, resumed and removed from the persisted download manager queue. The UI must implement the controls to display pause/resume, stop, remove management controls and show status of downloads.

Clients are notified of the following state changes: pending, initializing, complete and failed. Active download progress is provided so clients may update the UI with the number of kb/MB downloaded.

The download manager will pause or resume downloads if events of the following nature are detected:

• WIFI reception loss and regain,
• File system space  full and available, or
• HTTP and FILE IO errors.

Media Playbar

A music player example shows how to invoke stop, play/pause and use volume media controls.

Screen animations

A screen transition utility takes source and destination screens and horizontally slides screens in and out of view.

Cache

Written for applications that download large quantities of images and keep them for extended periods of time, the file system assisted image cache API takes a URL and returns an image from the cache or remote server.

Scrolling Marquee field

A scrolling marquee field scrolls text from left to right. This is useful to fit long text strings in small spaces.

Back button

The UI back button has a customized skin.

Sample Application

The included sample is a fully functioning BlackBerry Playbook mobile application that can be deployed directly onto the Playbook. It demonstrates the use of various tablet APIs and components provided by Sample Library for Blackberry Tablet OS SDK for Adobe AIR, including the following:

• Navigation menu
• Screen animations
• Swipe down menu with options, help and browsing history
• Search field (entering text launches search results screen)
• Scrolling marquee field
• Media playback
• Download Manager
• An Options screen that demonstrates how to save, retrieve and display user options
• Help button that launches browser directed to URL
• Browsing history (see swipe down menu)
• Back button (see sample search results screen)

The sample application has several screens, accessible using navigation buttons. Each screen demonstrates a particular component, e. g marquee field, playing media and downloading files APIs.

Sample application with navigation bar and search input field

Sample application scrolling marquee screen

Media example with play, pause, stop and volume controls.

Sample application media screen.

Download manager

Sample application download manager screen. Add, pause and remove download tasks.

Search field

Search field with customizable image and background text.

Search results view with back button

Options screen shows how to store and retrieve user options from database.

Sample options screen

Swipe down menu with browse history, home, options and help buttons.

Swipe down to reveal the hidden menu and browsing history example.

Coming Monday, help downloading, building the Samples for AIR project and deploying to the BlackBerry Playbook.  Added post is now available

Unbox Your PlayBook with a 2.0 Twist

Some new PlayBook functionality, like some WebWorks 2 and WebGL support (required by the TunnelTilt game), the BlackBerry® Runtime for Android, and Adobe AIR 3.0, require a build of PlayBook OS  2.0. This note explains how to install the PlayBook OS 2.0 Developer Beta that RIM announced at DevCon America 2011 so you can try these features today.

This note provides additional hand-holding and screenshots to the information in BlackBerry PlayBook OS 2.0 Developer Beta and in Developer Beta Update Now Available.  As usual, the official blog sites are the authoritative versions.

Unbox

Get yourself a PlayBook, from the RIM site, or one of our partners – or luck out and get it as a conference gift.  Unbox the device, notice that the bezel is active, and follow the instructions: make sure you are in a site with WiFi and internet access, and power up the tablet.

The device will come loaded with some build and the setup sequence will configure the WiFi network, the locale, the time zone, your BlackBerry ID and everything else that’s needed.  The setup will also do an automatic Over-The-Air (WiFi in this case) upgrade to the latest publicly available build using the standard PlayBook software upgrade machinery.  Let’s assume you got the device with a 1.0.* build; as of writing this note, the latest build is 1.0.7.3312.

Register your PlayBook

The Developer Beta is also installed using the PlayBook upgrade machinery; the only difference is that you will need to request the upgrade for your specific PlayBook.  You can do via a form linked at the bottom of the android and html5 microsites, or just go directly to the registration page and provide the PIN for your tablet and your email.

You will get an acknowledgement of the submission right away.   This is a good time to consider backing up your current configuration using the BlackBerry Desktop Manager, so you can later downgrade following these instructions if you want to (note – I’ve not tried this part).

At some time after, your PlayBook should show a notification (top-left) indicating the availability of the upgrade – or you can manually go request a software update check via the options panel.  Then you can download, install and reboot and you will find yourself on 2.0.0.3894, ready to have fun with 2.0.

One final note that the Developer Beta is just that, for developers.  In particular it does not contain end user features such as: email, calendar, contacts, video store, etc.

Installing a Debug Token in your PlayBook

This note describes how to configure a PlayBook with a Debug Token so it can be used to install applications like TunnelTilt.

Steps Required

• Request a Code Signing Key
• Register the signer with the RIM servers
• Create a (Debug) Token
• Put the PlayBook in Development Mode
• Install the Debug Token in the PlayBook

Let’s go through these in sequence

Request a Code Signing Key
Point your browser to blackberry.com/SignedKeys.  Provide the following information:

• First Name and Last Name for requester
• Company
• Email address
• Country
• A CSJPIN (to be used when using the Code Signing Keys)

You will get a quick response mail acknowledging the request ()

Some time after that (around 2 hours) you will get one or two emails (depending on whether you asked for BB, for PB, or for both) each with one CSJ attached ()

The CSJ files have a name of the form: client-PBDT-CLIENTNUMBER.csj (client-RDK-CLIENTNUMBER.csj for the BB) where CLIENTNUMBER identifies “you”, the author that requested the Code Signing Keys.

Next save the CSJ files somewhere:

bash-3.2$ pushd ~/Software/Keys/
~/Software/Keys /Developer/SDKs/Research In Motion/BlackBerry WebWorks SDK for TabletOS 2.2.0.5/bbwp ~/tmp

bash-3.2$ ls
client-PBDT-CLIENTNUMBER.csj client-RDK-CLIENTNUMBER.csj

Register the Signer
Now register the signer with RIM using the blackberry-signer application.  You need the CSJPIN to use the keys, and you will create a local STOREPASSWORD for later.

bash-3.2$ blackberry-tablet-sdk/bin/blackberry-signer -register \
 -csjpin CSJPIN -storepass STOREPASSWORD \
~/Software/Keys/client-RDK-CLIENTNUMBER.csj  \
~/Software/Keys/client-PBDT-CLIENTNUMBER.csj
Info: CSK file created.
Info: Developer certificate created in /Users/epelegri/Library/Research In Motion/author.p12
Info: Successfully registered with server.
Info: Successfully registered with server.

Next you will get Emails indicating the CLIENTNUMBER was successfully registered with Signing Servers (ID RDK and/or ID PBDT) ()

We can now use this store to do multiple operations, including:

Create the Debug Token
The Debug Token is created specifically for a given PlayBook; you can get its DEVPIN from the Options panel, under About/Hardware.  We use the blackberry-debugtokenrequest application

bash-3.2$ blackberry-tablet-sdk/bin/blackberry-debugtokenrequest \
-storepass STOREPASSWORD -devicepin DEVPIN \
~/Software/Keys/MyDebugToken.bar
Info: Debug token created.

Put the PlayBook in Development Mode
Before actually installing the debug token, you need to set the PlayBook in Development Mode. That is under Options/Security. That will show the IP for your device and will also give you an opportunity to set the password. Note that your device may have more than one IP address, e.g. one for WiFi and one for USB, if connected physically that way.

• Get the device IP (DEVICEIP)
• Set and record the password for the device (DEVICEPASS)

Install the Debug Token
And finally we are ready to install the debug token. The PlayBook should (still) be in Development Mode, and connected with the same IP as above, now use the blackberry-deploy application as follows:

bash-3.2$ blackberry-tablet-sdk/bin/blackberry-deploy \
-installDebugToken ~/Software/Keys/MyDebugToken.bar \
-device DEVICEIP -password DEVICEPASS
Info: Sending request: Install Debug Token
Info: Action: Install Debug Token
Info: File size: 2252
result::success

More links

• Code Signing Keys
• Configure signing for tablet applications

TunnelTilt – From GitHub to Your PlayBook

Last month, during MikeL‘s keynote at DevCon America, George showed a WebGL game running on the PlayBook (check at 24:18 in the screencast).  Last week we posted the sources at GitHub, in a new WebGL-Samples repository, and this post will show you how to download, compile and install the game on your PlayBook.

Note – the details in the post are from my Mac laptop, but the instructions for a Windows box are not very different.

Added – TunnelTilt is now Available on the BlackBerry App World

Prep Work
Start by getting yourself a PlayBook and then Install the Developers Beta of PlayBook OS 2.0 and Install a Debug Token.  The PlayBook will need to (still) be in Development Mode, and you will need to write down the DEVICEIP and the DEVICEPASS.

TunnelTilt and WebGL
WebGL (Web-Based Graphics Library, wikipedia, spec page) is a web standard for a low-level 3D graphics API based on  OpenGL ES 2.0, using GLSL, exposed through the HTML5 Canvas element as Document Object Model interfaces.  WebGL allows JavaScript applications to leverage the power of modern hardware platforms, specifically its Graphics processing pipelines.

TunnelTilt is a WebGL-based game that leverages the sensors in the PlayBook to race a ball inside a tunnel avoiding obstacles.  The application runs inside a WebWorks container, so what we are going to do is just create a WebWorks application that has the extensions needed by WebGL, then package everything together and install it into our PlayBook.

Install the WebWorks SDK
The Download area in the HTML5 micro-site has links to all the tools you need; some are used in this post, others are not.

• WebWorks SDK – To package your WebWork App (needed)
• Ripple – Usually used for testing your WebWork App (not needed)
• Simulators – Virtual Images of the Devices (not needed)

As indicated in the WebWorks instructions for PlayBook, you will also need

• Adobe AIR SDK

To follow along this note, you need to install the WebWorks SDK but you do not need to install the simulators or BlackBerry Ripple.

The rest of this note assumes that the WebWorks SDK has been installed under a directory $root/bbwp.

Get TunnelTilt from GitHub
The sources for TunnelTilt are in GitHub, in one of the repositories of the BlackBerry organization – the GitHub.com/BlackBerry/WebGL-Samples repository.

You can download the sources in several ways – the following does not require you to have a (free!) GitHub account:

bash-3.2$ cd $root

bash-3.2$ git clone http://github.com/blackberry/WebGL-Samples.git
Cloning into WebGL-Samples...
remote: Counting objects: 113, done.
remote: Compressing objects: 100% (77/77), done.
remote: Total 113 (delta 30), reused 102 (delta 19)
Receiving objects: 100% (113/113), 5.78 MiB | 303 KiB/s, done.
Resolving deltas: 100% (30/30), done.

bash-3.2$ ls
WebGL-Samples/

bash-3.2$ ls WebGL-Samples/tunneltilt/
LICENSE                                 config.xml                              gl-utils.js
NOTICE                                  data/                                   index.html
README.md                               events.js                               loader.js
blackberry.custom.accelerometer/        geometry.js                             shaders.html
blackberry.custom.audio/                gl-matrix/                              sound.js

We have now two subdirectories under $root: WebGL and bbwp.

Added: GitHub also provides git-less access to a repo’s sources via a zip-ball.  In this case, point your browser or curl to http://github.com/blackberry/WebGL-Samples/zipball/master and unzip.

Install the WebWorks Extensions
The blackberry.custom.* files need to be “installed” into $root/bbwp/ext. This will do it:

bash-3.2$ cd $root/WebGL-Samples/tunneltilt

bash-3.2$ mv blackberry.custom.accelerometer/ $root/bbwp/ext
bash-3.2$ mv blackberry.custom.audio/ $root/bbwp/ext

bash-3.2$ ls $root/bbwp/ext
blackberry.app/                         blackberry.io.dir/                      blackberry.system.event/
blackberry.app.event/                   blackberry.io.file/                     blackberry.ui.dialog/
blackberry.custom.accelerometer/        blackberry.media.camera/                blackberry.utils/
blackberry.custom.audio/                blackberry.media.microphone/            js/
blackberry.identity/                    blackberry.payment/                     library.xml
blackberry.invoke/                      blackberry.system/                      src/

Create a ZIP with the WebWorks/TunnelTilt Sources
Since the tunneltilt directory no longer has the extensions we can just zip the rest:

bash-3.2$ cd $root/WebGL-Samples/tunneltilt

bash-3.2$ zip -r ../tunneltilt.zip *
  adding: LICENSE (deflated 66%)
  adding: NOTICE (deflated 33%)
  adding: README.md (deflated 66%)
  adding: config.xml (deflated 46%)
  adding: data/ (stored 0%)
  adding: data/images/ (stored 0%)
  adding: data/images/ball_backglow_256.png (deflated 1%)
  adding: data/images/ball_center_256.png (deflated 3%)
  adding: data/images/bg1.png (deflated 78%)
  adding: data/images/bg2.png (deflated 75%)
  adding: data/images/bg3.png (deflated 77%)
  adding: data/images/bg4.png (deflated 78%)
  adding: data/images/bg5.png (deflated 75%)
  adding: data/images/progress_bar.gif (deflated 25%)
  adding: data/images/splash.png (deflated 0%)
  adding: data/images/tap_to_restart.png (deflated 21%)
  adding: data/images/tap_to_start.png (stored 0%)
  adding: data/images/tunnelTiltIcon.png (stored 0%)
  adding: data/images/wall1.png (stored 0%)
  adding: data/images/wall2.png (deflated 0%)
  adding: data/images/wall3.png (deflated 0%)
  adding: data/images/wall4.png (deflated 0%)
  adding: data/images/wall5.png (deflated 0%)
  adding: data/images/win.png (deflated 13%)
  adding: data/levels/ (stored 0%)
  adding: data/levels/level1.json (deflated 87%)
  adding: data/levels/level2.json (deflated 88%)
  adding: data/levels/level3.json (deflated 88%)
  adding: data/levels/level4.json (deflated 85%)
  adding: data/levels/level5.json (deflated 83%)
  adding: data/sound/ (stored 0%)
  adding: data/sound/crash.mp3 (deflated 1%)
  adding: data/sound/rocket.mp3 (deflated 9%)
  adding: events.js (deflated 64%)
  adding: geometry.js (deflated 72%)
  adding: gl-matrix/ (stored 0%)
  adding: gl-matrix/gl-matrix-min.js (deflated 67%)
  adding: gl-matrix/LICENSE.md (deflated 47%)
  adding: gl-matrix/README.md (deflated 58%)
  adding: gl-utils.js (deflated 65%)
  adding: index.html (deflated 69%)
  adding: loader.js (deflated 65%)
  adding: shaders.html (deflated 70%)
  adding: sound.js (deflated 42%)

bash-3.2$ ls $root/WebGL-Samples
README.md       tunneltilt/     tunneltilt.zip

Compile the WebWorks Application
Remember to compile “-d” for the debug token

bash-3.2$ cd $root/WebGL-Samples;

bash-3.2$ $root/bbwp tunneltilt.zip -d -o .
[INFO]                  Parsing command line options
[INFO]                  Parsing bbwp.properties
[INFO]                  Validating WebWorks archive
[INFO]                  Parsing config.xml
[INFO]                  Populating application source
[INFO]                  Compiling WebWorks application
[INFO]                  Packaging the bar file
[INFO]                  Bar packaging complete
[INFO]                  WebWorks application packaging complete

Install TunnelTilt
We are now all ready, just

bash-3.2$ cd $root/WebGL-Samples

bash-3.2$ $root/bbwp/blackberry-tablet-sdk/bin/blackberry-deploy \
-installApp -password DEVICEPASS \
-device DEVICEIP -package tunneltilt.bar
Info: Sending request: Install
Info: Action: Install
Info: File size: 6320643
Info: Installing ...
Info: Processing 6320643 bytes
Info: Progress 3%...
Info: Progress 13%...
Info: Progress 99%...
Info: Progress 100%...
actual_dname::tunneltilt11d42dee67902b699aef126ff4456cb.testDev_126ff4456cb2eeff07a
actual_id::testDev_126ff4456cb2eeff07a
actual_version::1.0.3.0
result::success

Enjoy!
And we can now just enjoy your game!

And…

Open Source Components at DevCon America 2011

This is a back-dated post intended to capture a significant event in RIM’s Open Source engagements that occurred prior to the start of Open BB News in November 2011.

RIM launched a significant initiative to leverage Open Source in our new BlackBerry PlayBook OS during DevCon America 2011.  The initiative was described in a post at our official DevBlog blog; the post is Open Source and the BlackBerry PlayBook OS Platform, dated October 18, 2011.

The initiative was also described in more detail in a page we created for the event at our Community website at GitHub.

Looking Back on One Year of RIM Open Source Repositories

This is a back-dated post intended to capture a significant event in RIM’s Open Source engagements that occurred prior to the start of Open BB News in November 2011.

In the days leading towards DevCon America 2011, I wrote a summary of RIM’s Open Source activities at our official DevBlog blog.   The post is Looking Back on One Year of RIM Open Source Repositories, dated October 18, 2011.

BlackBerry WebWorks – Open Sourced at DevCon America 2010

This is a back-dated post intended to capture a significant event in RIM’s Open Source engagements that occurred prior to the start of Open BB News in November 2011.

RIM open sourced BlackBerry WebWorks during DevCon America 2010.  The first repository, using the ASL2 license, is WebWorks, at GitHub, and provides the runtime for BlackBerry Smartphones.

The official post is at DevBlog: BlackBerry WebWorks and the Open Source Community, dated, 29 September, 2010.