Getting Started: Building for BlackBerry 10 (BB10)

1. Requirements
   1. BlackBerry 10 Native SDK
2. Configure and Build PJSIP
   1. Get PJSIP Source Code
   2. Configure PJSIP
   3. The pjsip.pri QMake Project File
   4. Import and Build PJSIP to/in Momentics IDE
3. Configuring the Device and Momentics IDE
4. Building and Running the pjsua Demo Application
   1. Import the PjsuaBB Project
   2. Build PjsuaBB
   3. Create Debug Configuration
5. Creating a New PJSIP Based Application
   1. Creating a BlackBerry Native Application
   2. Integrating PJSIP into the App
6. Simulator
7. Multiple PJSIP Build Configurations
   1. Option 1: Build PJSIP in Multiple Directories
   2. Option 2: Checkout Once, Configure Build and Install Several Times
8. Notes
   1. Missing Separator
   2. GSM Call Interruption Problem
   3. Unable to Get Sound Device Parameters

Requirements

BlackBerry 10 Native SDK

You'll need ​BlackBerry 10 Native SDK for native development. We tested with SDK version 10.1.0.1020, but this should work with later versions too.

After you download and install the SDK, set the environment variables by running bbndk-env script provided in the SDK:

$ source $BBNDK_DIR/bbndk-env.sh

Note that it is no longer necessary to have the ​BB10 PJSIP Demo as PJSIP now contains a PJSUA demo for BlackBerry.

Configure and Build PJSIP

Get PJSIP Source Code

Get the source code, if you haven't already. This tutorial applies to PJSIP version 2.2 and above (or the 2.1 from SVN trunk dated 2013/04/16 or later).

Configure PJSIP

1. Run this in your BB10 NDK directory, otherwise the configure command will fail:

   $ source $BBNDK_DIR/bbndk-env.sh
   

2. cd to PJSIP source directory.
3. Run configure-bb10 script with suggested parameters as follows. This will setup PJSIP with debugging info and without optimization.

   $ CFLAGS="-O -g" ./configure-bb10 --disable-speex-aec
   

   You can pass additional parameters as both environment variables or command line options to the configure-bb10 script. See further customization options in Building with GNU page or run ./configure --help for more info.
4. We suggest to fill in your config_site.h (pjlib/include/pj/config-site.h file) with the following:

   #include <pj/config_site_sample.h>
   

5. Run make dep to build the dependencies:

   $ make dep
   

At this point, you may build PJSIP simply by executing make, but we'll show you how to import PJSIP into Momentics IDE and build it from there.

The pjsip.pri QMake Project File

The configure-bb10 script above also creates pjsip.pri at the root of PJSIP directory. This file contains PJSIP build settings in QMake project (.pro) file format, which can be included in application's .pro file to build with PJSIP.

See creating new app section for more info.

Import and Build PJSIP to/in Momentics IDE

This is optional, as you can just run make in PJSIP directory to build PJSIP. But nevertheless this is a lot more convenient especially if you are developing PJSIP.

Import PJSIP as New Project

In Momentics IDE:

1. Select File --> Import..
2. From the list, open BlackBerry, select Existing Code as BlackBerry C/C++ Makefile Project, and click Next >
3. In the "Import.." wizard, set
   • Project name: pjproject (or other name. But in this tutorial we will refer the PJSIP project as pjproject)
   • Code location: the directory where you extract PJSIP to
   • Language: C and click Next >
4. Accept the default "Use workspace SDK selection", and click Finish.

Create Build Configuration

1. Right click pjproject from the Project Explorer view (tab), then select Build Configurations --> Manage from the pop-up menu.
2. In the dialog, click New.. to create new build configuration
   • In "Create New Configuration Dialog":
     • set Name: PJSIP-Default
     • press OK to close the dialog
3. Set PJSIP-Default as the active build configuration by selecting it from the list and pressing the Set Active button
4. Press OK to close the "Manage Configurations" dialog

Configure Build Configuration

1. Right click pjproject from the Project Explorer view (tab) and select Properties from the pop-up menu.
2. In the Properties for pjproject dialog:
   • Select C/C++ Build from the left tree pane
   • Make sure "PJSIP-Default [Active]" Configuration is selected from the combo box in the top center of the dialog.
     • if it's not marked as active, make it active
   • Go to Behaviour tab
   • Set Make build target in the textbox right to Build on resource save (Auto build) to: all
   • I personally uncheck the Build on resource save (Auto build) (I'd rather build manually)
   • Also set the build target in the textbox right to Build (Incremental build) to: "all"
   • Click Apply
   • Click OK to close the dialog

Build PJSIP

Now you can build the pjproject PJSIP project.

Configuring the Device and Momentics IDE

For the rest of this tutorial, we will assume that you already have the IDE and target device (or simulator) configured for debugging BB10 application. If not, follow ​these instructions.

Assorted things to check before debugging an application to the device:

1. Development mode is turned ON (Settings --> Security and Privacy --> Development Mode)
   • Otherwise when you connect the USB you'll have a random IP address and you are not able to connect to target device in Momentics
2. You can connect to BlackBerry target device in Momentics IDE. A BlackBerry target device will be named something like usb or usb1 if you're connecting via USB
   • right click the target device in Project Explorer, select BlackBerry Tools --> Connect
     If you can't connect, make sure that:
     • the device is really connected
     • it has the right IP address
     • you can ping it (make sure Development Mode is ON)
     • the IP address is correct in Momentics target properties

Building and Running the pjsua Demo Application

PJSIP comes with a fully featured pjsua application which runs on all platforms that PJSIP supports including BB10.

Import the PjsuaBB Project

In Momentics IDE:

1. Select File --> Import..
2. Select General and Existing Projects into Workspace, and press Next >
3. In Import.. dialog:
   • Select root directory: $PJ_DIR/pjsip-apps/src/pjsua/bb10

Once you select the directory, PjsuaBB will appear under Projects list in the dialog. Make sure it is selected (by default it is). Click Finish

Build PjsuaBB

Just build it.

Create Debug Configuration

1. Highlight "PjsuaBB" from the Project Navigator, select Run --> Debug Configurations.. from the main menu
2. From the left list, right click BlackBerry C/C++ Application, and select New..
3. New debug settings will appear with default values
4. Go to Debugger tab and uncheck Stop on startup
5. Press Apply

Creating a New PJSIP Based Application

Creating a BlackBerry Native Application

Use Momentics new project wizard to create a new BlackBerry native application. This should be easy, and we will not explain it here.

Configure the permissions by double-clicking bar-descriptor.xml file and select Application tab from the bottom of the page, and check these permissions:

• Internet
• Microphone
• Run When Backgrounded

Integrating PJSIP into the App

Integrating PJSIP settings into the app is very easy:

1. Open the app's .pro file (e.g. PjsipBB.pro for PjsipBB app)
2. Include pjsip.pri file in the relevant target section, e.g.:

   ..
   device {
       CONFIG(debug, debug|release) {
           ..
           include(../../../../pjsip.pri)
           LIBS += -lbb
           ..
       }
   }
   ..
   

The pjsip.pri file is generated by configure-bb10 script (as explained above) and contains compilation and link flags to integrate PJSIP with your app.

Simulator

Install and configure the BB10 simulator, you will need to install a virtual machine player in order to use the simulator. To build for BB10 simulator, just run configure-bb10 script with --simulator option:

$ ./configure-bb10 --simulator

Multiple PJSIP Build Configurations

If you want to have multiple PJSIP build configurations for your app (for example, Device-Debug, Device-Release, and/or Simulator), you can use the following approach when building PJSIP.

Option 1: Build PJSIP in Multiple Directories

This is of course the easiest, just extract or checkout PJSIP in multiple locations, configure it differently, build, and include the right pjsip.pri file in the relevant section of you application's QMake .pro file.

Option 2: Checkout Once, Configure Build and Install Several Times

The second option is to checkout PJSIP in one directory, but configure, build, and install it several times, each with separate build settings and to different install --prefix. Once the build completes, run make install to install PJSIP development headers and libraries to the installation prefix. You also need to edit the contents of pjsip.pri file, point the path to the right prefix, and rename the pjsip.pri to something more appropriate (e.g. pjsip-device-debug.pri). You then include this .pri file in the relevant section of your application's QMake .pro file.

Notes

Missing Separator

If you forgot to run source bbndk-env.sh (as explained above) before running make dep, the dependency files will get corrupted with the "** missing separator" error and you'll have to delete each of those dependency files manually.

GSM Call Interruption Problem

If a VoIP call is in progress when an incoming GSM call arrives, and if the user accepts the GSM call, the audio routing of the phone is flawed producing the following result: The VoIP call goes to speaker and the GSM call does not “grab” the audio channels so you get a “null” GSM call and the VoIP call carries on with speaker.

To prevent this from happening, application must implement GSM call detection using BB10 native API, and when it detects a GSM call, it should close PJSIP sound device by using either pjsua_set_null_snd_dev() or pjsua_set_no_snd_dev() and put the VoIP call on hold before accepting the GSM call.

Thank you Bob Cripps of Truphone for the note.

Unable to Get Sound Device Parameters

This error happens because PJSIP is unable to open the audio capture device. Make sure you set the application permissions correctly.