Linux Blackberry OS 10 Cordova plugin development setup

This semester I’m contributing towards HTML5 on BB10 with thanks to UCOSP and my team’s mentor Tim Windsor from Blackberry. We’re implementing and porting cordova (phonegap) plugins.

Setting up my development environment under linux (Ubuntu 13.04) took the full first day of our face-to-face sprint. I am thankful Tim was sitting across the table and was willing to  answer my many questions.

For this tutorial I am going to assume you are on Ubuntu 13.04 but other linux distros should be the a similar process.

For Ubuntu 13.10 you’ll need to take one extra step.

0. Install dependencies and linux tools

The non-BB10 specific tools we need can all be downlaoded through apt-get. Bring up a command line interface by pressing Ctrl + Alt + t.

In the command line run the following:

sudo apt-get install git ia32-libs openjdk-6-jre

That installs the BB10 IDE’s dependencies, java, and Git. Git being a version control tool we’ll use later to get the example Cordova plugin. Java is needed for the signing tools. If you are on 32bit linux you should not need ia32-libs

We also need a current vesrion of node.js for which we can use a ppa. Run the following commands:

sudo apt-get update
sudo apt-get install python-software-properties python g++ make
sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs

Now install cordova through node.js’s package manager with the following commands:

sudo npm install -g cordova

1. Download the BB10 IDE, BB10 specific Cordova, and signing tools

We need to download the following:

  1. “QNX Momentics IDE for Linux”, which is the Blackberry OS 10 Native Development Kit: http://developer.blackberry.com/native/downloads/
  2. Community ported old BB10 Webworks SDK: https://github.com/badtoyz/BB10-WebWorks-SDK-Linux-Gold/archive/master.zip

We have many files to download so get those downloads started now and start reading ahead.

2. Install the IDE, which includes some Cordova tools

The IDE install file we downloaded is an installer binary which we must mark as executable and then execute, run the following in the command line:

chmod +x Downloads/bbndk-BB10_*
./Downloads/bbndk-BB10_2_0X-1155-106-201308081646.bin

The IDE installer will ask where to install the IDE into. For the purpose of the tutorial we’ll install in a folder called “bbndk”, the default suggested folder. If you feel comfortable with linux then we can install it elsewhere provided you know how to edit the below commands to use your desired install path.

installing_bbndk

Installing the IDE (QDE) into bbndk folder

3. Extract the signing tools

The signing tools we need can only be found in the community ported version of the old WebWorks tools. We downloaded them earlier and now we should extract them to the folder “bbndk-signing”. You can use the default Ubuntu unzipper or run the following on the command line:

unzip Downloads/BB10-WebWorks-SDK-Linux-Gold-master.zip -d bbndk-signing

4. Add the tools into our PATH

When you run things from the command line the shell looks for the program in the list of directories in your PATH. We need to add the directory with the IDE, the signing tools, and the BB10 specific Cordova tools.

Open the hidden file ‘.bashrc’ by running:

gedit ~/.bashrc

We must add the following lines at the bottom of .bashrc:

export PATH="${HOME}/bbndk:${PATH}" # The IDE 'qde'
export PATH="${HOME}/bbndk-signing/BB10-WebWorks-SDK-Linux-Gold-master/dependencies/tools/bin:${PATH}" # signing tools
export PATH="${HOME}/bbndk/host_10_2_0_15/linux/x86/usr/bin:${PATH}" # BB10 Cordova

Now you must close your terminal window and re-open it so that the new PATH setting will take effect.

bbndk_in_PATH

Once the additional directories to the PATH have been added the bottom of .bashrc should look like the above

 

5. Download an SDK through the IDE

Now that your PATH variable is set correct you may launch the IDE by running the following command:

qde

The IDE will open a window asking you to connect a device and download an SDK. For our purposes you do not yet need to setup your device for the SDK. As such select the “No Device” option and uncheck the “Download Simulator”, then click next until the download starts.

qde_download_sdk_no_device_or_simulator

We shall be using the Cordova tools to package and push the complete application but we’ll still add the device later on for different reasons.

The SDK download may take a while, I have found the Blackberry servers to be slower than one might expect. It is safe to perform step 6 & 7 SDK is downloading but we shall need the SDK for steps 8 and onwards.

6. Request a signed development key

Before we can sign and push our applications we need a special signed key from Blackberry. We can request such a key through https://www.blackberry.com/SignedKeys/codesigning.html

Select the second option as we’ll be signing with the Blackberry WebWorks tools. Request the key now as it takes upto 2 hours for it to arrive. The two files we’ll need shall be emailed to you.

7. Find your phone’s IP address

Since BB10 simulator requires a paid license to proprietary software I will only be able to cover how to use a real BB10 device. Blackberry was gracious enough to provide my team members each with a “Dev Alpha C”, a cooler looking model of the Q10.

The IP address we need is the one associated with your WiFi network, not the usb connection, nor your mobile data connection. The exact path through the menus is non-obvious so we’ll go over board on the photo guide for this section.

bb10_1_network_connections

Open the Settings app and select “Network Connections”

bb10_2_wifi_network

Select your WiFi network

bb10_3_wifi_network_settings

Now find the settings tab in the bottom right

bb10_4_dropdown

We need to switch the type of details shown by using the dropdown list

bb10_5_internet_connection

From the dropdown select “Internet Connection”

bb10_6_ip_address

Now the IP address should be the first detail shown

In my case the IP address of my development phone is 192.168.1.199

Make note of your phones address as we shall use it later on.

8. Clone the community plugin repository

Now we must get the example cordova plugin. We can find said plugin in the community plugin git repository hosted on github: https://github.com/blackberry/WebWorks-Community-APIs

The exact commands we must run are:

git clone https://github.com/blackberry/WebWorks-Community-APIs.git

That will clone the git repository. From now on we should issue all commands from the example plugin which is called “Template”. Navigate to “Template” plugin with the following command:

cd ~/WebWorks-Community-APIs/BB10-Cordova/Template/sample

With the “Template” plugin the “sample” folder contains the cordova app which acts as an example for the plugin’s usage. We’ll use this sample as our hello world.

9. Enable development mode on your device

bb10_9_1_privacy_and_security

From the main settings screen select “Security & Privacy”

bb10_9_2_navigate_to_dev_settings

Scroll to the bottom and select “Development Mode”

 

bb10_9_3_turnon_dev_mode

Now turn on “Devlopment Mode”. The phone will set Development Mode to off after every restart so you’ll have to redo these steps if you restart the phone.

Your phone should now be in development mode. It might also be flashing a red light, the flashing will go away in time. Notice that the IP address listed does not match the one we wrote down earlier. That is because this IP address is for the usb connection.

 

10. Generate an author .csk

Now let us register our signing key. This will generate a author .csk key store which we’ll later use to generate the debug token which gets push to the device. You must edit the following command with your own password and the pin you selected when registering for the signing key:

blackberry-debugtokenrequest -register -storepass PASSWORD -csjpin PIN Downloads/client-PBDT-*-.csj Downloads/client-RDK-*-.csj

Notice that this command assumes you downloaded the two signing key files into your Downloads folder. Edit the paths if this is not the case.

register_signing_key

What it looks like when after registering the signing key. Notice when I registered for my key I used a very weak password, please use a stronger password.

11. Generate a debug token

Now we must use the IDE to generate the debug token. Then we must move a copy of this debug token to where the cordova tools expect. To do this we must add the device to the IDE.

add_device_step1

From the “No Device Selected” dropdown select “Manage Devices”

add_device_step2

Click the “Set up new bb10 device” button

add_device_step3

Use the IP address we wrote down earlier and the password you have set on your phone.

Now click next until it asks if you would like to generate a new debug token or import one. Please do generate a new token and follow the on screen instructions. Once the debug token has been pushed to the device the IDE will ask you if you would like to download debug symbols. We do not need them but there is no harm in downloading the symbols anyway.

Now run the following command to move the debug token to where cordova can use it:

cp .rim/debugtoken1.bar .cordova/blackberry10debugtoken.bar

The filenames are important so please do not change them.

12. Add device to cordova

Since it is cordova which does the heavy lifting we must tell cordova how to connect to your device. Since cordova remembers devices on a project by project basis you must navigate to Template’s sample cordova app.

cd WebWorks-Community-APIs/BB10-Cordova/Template/sample

Now edit the following command with our device’s IP address and password:

./platforms/blackberry10/cordova/target add dev_phone 192.168.1.199 --password PASSWORD

13. Build the native binaries

We must use the IDE for compiling the native binaries. We must add the plugin to QDE and then use a non-obvious build command so please follow the screenshot guide:

import_template_step1

Select Import from the main dropdown menu

import_template_step2

Select import from existing project

import_template_step3

Select the root directory of the plugin’s project.

import_template_step4

The plugin’s project directory is the one which contains the hidden .project file. It is the following folder: ~/WebWorks-Community-APIs/Template/plugin/src/blackberry10/native

import_template_step5

Now click finish and you’ll have the plugin project in the IDE

import_template_step6

Now before we build we must set the active target profile to build. We want to build for the regular “device” profile.

import_template_step7

Once the active build configuration has been set to “device” we can build by selecting the “Build Selected” option.

import_template_step8

14. Use cordova to build and run the plugin sample

Now the fun!

Run the following commands to copy the plugin’s native binaries into the plugin sample and then build and run the sample on our device!

cd ~/WebWorks-Community-APIs/BB10-Cordova/Template/sample
cordova plugin rm community.template
cordova plugin add ../plugin/
cordova run

15. You’re done!

You should see the sample app runing on your device. It should look something like thus:

sample_app_running

When developing your plugin whenever you make changes to the native files you must use the IDE to build new binaries as we did in ste 13 and then use step 14 to test them.

Congratulations!

One thought on “Linux Blackberry OS 10 Cordova plugin development setup

Leave a Reply

Your email address will not be published. Required fields are marked *