Would you like to contribute to the Titanium docs? To get started, sign up for an account on the Appcelerator Wiki and sign our CLA.

Skip to end of metadata
Go to start of metadata


Overview

This guide walks through the steps to download and setup the QNX Momentics IDE and BlackBerry native SDK as well as how to configure the Titanium environment to support BlackBerry development.

Compatibility and Download

Titanium requires the BlackBerry 10 NDK to develop BlackBerry applications as well as the BlackBerry Device Simulator to test applications.

BlackBerry Native SDK and QNX Momentics IDE

To install the BlackBerry NDK, you need to first download and install the QNX Momentics IDE. When you launch the QNX Momentics IDE for the first time, you will be prompted to install the BlackBerry NDK.

The QNX Momentics IDE requires Java SE 6, which is included as part of the Oracle JDK. The Oracle JDK should already be installed since this is also a prerequisite for the Titanium SDK.

Each Titanium SDK supports a specific version range of the BlackBerry NDK.

Titanium SDK VersionMin BB NDK VersionMax BB NDK Version
3.1.3 - latest10.0.x10.2.x
3.1.210.0.x10.1.x

BlackBerry Device Simulator

The BlackBerry 10 Device Simulator runs on a virtual machine and requires one of the following:

BlackBerry Developer Certificates

To deploy to a device or package your application for distribution, you need to obtain signing keys from BlackBerry to create developer certificates. See BlackBerry Developer: Signing apps for more information.

 

 

Download both the Momentics IDE and BlackBerry 10 Device Simulator from http://developer.blackberry.com/native/download/.

Installation

Download and install the QNX Momentics IDE.  After installing the QNX Momentics IDE, launch the the program.  If this is the first application launch, a dialog appears asking you to select a workspace directory and then you will be prompted to install the BlackBerry NDK.  Follow the dialog's instructions.

Download and setup VMware and the BlackBerry Device Simulator.  Launch the installation program and follow the instructions.  Launch the simulator.  The simulator needs a few minutes to boot and acquire an IP address.  Make a note of the IP address, located in the bottom-left of the simulator.  This is a configuration setting for Studio.

Updating the BlackBerry NDK

To update the BlackBerry NDK, launch the Momentics application.  From the menu, select HelpUpdate API levels....  A dialog appears with a list of possible NDKs to install.  You can choose between Gold and Beta versions. Click Install next to the NDK(s) you want to install.  The installation starts in a background process and you can click OK to dismiss the dialog.

Developer Certificates and Debug Tokens

To launch an application on device or to package your application for distribution, you need developer certificates to create debug tokens or sign your application package.  The following steps outline what you need to do:

Register for a Developer Certificate

Before starting, you can optionally connect a BlackBerry device to your computer to expedite the device setup process and install debug tokens to your device. Make sure Development Mode is enabled.  In Settings, select Security and Privacy > Development Mode and make sure Use Development Mode is on.

  1. Start the QNX Momentics IDE.
  2. Open the Preferences dialog:
    1. For Mac OS X systems, from the menu, select Momentics Preferences or Momentics > Preferences.
    2. For Linux and Windows systems, from the menu, select Windows >Preferences.
  3. Select BlackBerry and click BlackBerry Deployment Setup Wizard.
  4. Click Next. Momentics tries to discover your connected device or simulator.
  5. If you have a device connected, enter your device password and click NextA dialog appears.
  6. Click Next. Momentics sets up your device.
  7. Select Complete the Registration process by downloading your BlackBerry ID token... and click Next. You are prompted to register for signing keys.
  8. Enter your company name and the password you want to use with the token. Make a note of the password since it is the keystore password for Studio.  Click Get token. A dialog appears for you to sign in to BlackBerry. You may also be prompted to create a master password.
  9. Enter your BlackBerry ID credentials and click Sign In.  If you do not have BlackBerry ID credentials, you need to create them. 
  10. Click Next. Momentics downloads a token file and creates a developer certificate.
  11. Select a location to backup your token file and developer certificate or choose not to back them up.  Click Next.
  12. If you have a device connected, choose to Create a debug token... and click Next. Momentics installs a debug token to your device.
  13. Click Finish, then OK.

For up-to-date instructions, see BlackBerry Developer: Signing apps.

Create and Install a Debug Token to a Device

To create and install debug tokens to a device, you need to have registered a developer certificate.  Simply rerun the BlackBerry Deployment Setup Wizard by following the instructions from the previous section except you must connect your device to the computer via USB.  If this is a new device, you may need to update the IP address.  Since you have already registered a developer certificate, steps 7 - 11 do not apply.

You can also manually create a debug token using Momentics:

  1. Open the Preferences dialog. 
  2. Navigate to BlackBerry  > Signing
  3. Click Create... to create a debug token and provide it your device's PIN number either by manually entering the information or using the auto-discovery option.
  4. Click Import... to load the debug token to your connected device.

Configuring Studio

These steps outline the Studio Preferences settings that need to be changed to support BlackBerry development.

  1. Start Studio.
  2. Open Preferences:
    1. For Mac OS X systems, from the menu, select Titanium Studio Preferences or Appcelerator Studio > Preferences.
    2. For Linux and Windows systems, from the menu, select Windows > Preferences.
  3. In Preferences, navigate to Studio > Platforms > BlackBerry.
  4. Under the BlackBerry section:
    1. Enter the path to the BlackBerry 10 Native SDK in the BlackBerry NDK Home textbox.  The following are the default locations for the NDK:
      1. Linux: /home/<user>/bbndk/
      2. Mac OS X: /Applications/Momentics.app/
      3. Windows: C:\bbndk
    2. For running on device, specify the location of the debug token bar file in the BlackBerry Debug Token textbox.  The following are the default locations:
      1. Linux:  ~/.rim
      2. Mac OS X:  ~/Library/Research In Motion
      3. Windows: %HOMEPATH%\AppData\Local\Research In Motion
    3. For running on device, enter the IP address of the BlackBerry 10 Device in the Device IP textbox.
    4. For testing on the simulator, enter the IP address of the BlackBerry 10 Device Simulator in the Simulator IP textbox.
    5. For running on device, enter the device password in the Device Password textbox.
    6. For package distribution, enter the key store password used to setup your developer certificate in the KeyStore Password textbox.
  5. Click the OK button.

Studio is now setup to use the BlackBerry 10 Native SDK.

Using Studio

Launch an Application on the Emulator

Start the BlackBerry Device Simulator before launching the application.  See directions below.

Click on the Run icon and select BlackBerry Simulator. Titanium builds and installs the application to the simulator. After installation, the application automatically launches on the simulator.

Launch an Application on Device

On the device, make sure Development Mode is enabled.  Under system settings of the device, click Security and Privacy, then Development Mode.  Click the Use Development Mode switch to on.  Make a note of the Development IP Address.  The same debug token that you are building your application against should also be installed to the device.

Make sure that the Device IP in Studio Preferences matches the Development IP Address you got when you turn on Development Mode on the device (usually 169.254.0.1) and that you specified the location of your BlackBerry Debug Token and your Device Password.

Make sure the application you want to launch is selected in the Project Explorer view, then select Run from the Launch Mode drop-down and select BlackBerry Device from the Target drop-down.

Distribute an Application

Make sure that the KeyStore Password in Studio Preferences is set.

Make sure the application you want to launch is selected in the Project Explorer view, then select Package from the Launch Mode drop-down and select BlackBerry from the Target drop-down.

Using the CLI

  • To create a project: 

  • Run the application on the BlackBerry 10 simulator (start the simulator beforehand): 

  • Run on a development device (make sure development mode is enabled and the debug token is installed on the device): 

  • Build a release bar file and sign it so it can be published to 'BlackBerry World' or deployed to device: 

Using the BlackBerry Device Simulator

This section demonstrates how to perform a few operations with the simulator for development.  For a complete list of simulator features and directions, see the BlackBerry 10 Device Simulator guide.

Launch the Simulator

  • For Mac OS X systems, locate and double-click the BlackBerry10Simulator-BB10_n_nn file. Default location is ~/Documents/Virtual Machines/BlackBerry10Simulator-BB10_<version>.
  • For Windows systems, select the Start menu, All ProgramsBlackBerry 10 Simulator folder, BlackBerry 10 Simulator - BB10_ n_nn folder, and finally the BlackBerry 10 Simulator application.
  • For Linux systems, run the following command, which may need to be adapted for your installation or version:

For Windows systems that do not support the graphics requirements, select the 'BB10DevAlphaSafe' option during boot up.  The simulator needs a few minutes to boot.

Return to the Main Screen

After launching an application, to return to the main screen, use the cursor to swipe from the bottom of the simulator upward to go to the Application Switcher.  In the Application Switcher, click on the 'x' in the lower-right corner of the application to close it and return to the main screen.

Uninstall an Application

To remove an installed application from the simulator, select and hold the cursor over the application icon.  A trashcan icon appears in the top-right corner of the application icon. Click on the trashcan icon to remove the application. A dialog appears to confirm the removal.  Click on the Delete button to remove the application.

Access Simulator Log Messages

You can use a telnet client to access the simulator.  Use the IP address located at the bottom-left of the simulator.  Once connected, the username and password are both devuser.  The log messages are located in the /accounts/1000/appdata/<app_id>/log directory for your application. Use the cat or tail command to output the log file.

The simulator log message are displayed in Studio's Console View.

References