Getting Started: Building for BlackBerry 10 (BB10)

1. Getting Started: Building for BlackBerry 10 (BB10)
   1. Requirements
      1. BlackBerry 10 Native SDK
   2. (For Linux and Mac OS X Hosts:) Configure and Build PJSIP
      1. Get PJSIP Source Code
      2. Configure PJSIP
      3. The pjsip.pri QMake Project File
      4. (Optional) Import and Build PJSIP to/in Momentics IDE
   3. (For Windows Hosts:) Configure and Build PJSIP
   4. Building and Running the pjsua Demo Application
      1. Configuring the Device and Momentics IDE
      2. Import the PjsuaBB Project
      3. Build PjsuaBB
      4. Create Debug Configuration
      5. Running PjsuaBB
      6. Customizing SIP Settings
2. Next Steps
   1. Creating a New PJSIP Based Application
      1. Creating a BlackBerry Native Application
      2. Integrating PJSIP to Your Application
   2. Multiple PJSIP Build Configurations
      1. Option 1: Build PJSIP in Multiple Directories
      2. Option 2: Install PJSIP in Multiple Directories
3. Problems
   1. Missing Separator
   2. GSM Call Interruption Problem
   3. Unable to Get Sound Device Parameters
   4. Troubleshooting BlackBerry Target Device

Requirements

BlackBerry 10 Native SDK

You'll need ​BlackBerry 10 Native SDK for native development. After you download and install the SDK, set the environment variables:

$ source $BBNDK_DIR/bbndk-env.sh

(For Linux and Mac OS X Hosts:) 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. (For debug build) Run configure-bb10 script with debugging info and without optimization.

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

   See Build Customization section in Building with GNU page or run ./configure --help for more customization info.
4. Or for simulator target, run configure-bb10 with --simulator option"

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

5. 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>
   

6. Run make dep to build the dependencies:

   $ make dep
   

At this point, you can 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.

(Optional) 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:

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

Now build the pjproject PJSIP project.

(For Windows Hosts:) Configure and Build PJSIP

TODO

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.

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 native applications (any native applications, not just PJSIP). If not, follow ​these instructions from BlackBerry developer site.

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 checked (the default). Click Finish

Build PjsuaBB

Just build it. You need to build the app before creating a Debug Configuration below (so that Eclipse can find the app's binary).

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

Running PjsuaBB

Launch debugging session for PjsuaBB. Wait until the app is loaded on the device. You will see telnet instructions on the device's screen. Telnet to this address to operate the application.

Customizing SIP Settings

Currently this can only be done by modifying the argv variable in applicationui.cpp:

    char *argv[] = { (char*)"pjsuabb",
		     (char*)"--use-cli",
		     (char*)"--no-cli-console",
		     (char*)"--cli-telnet-port=2323",
		     // Add your settings here
		     NULL };

Next Steps

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 to Your Application

Integrating PJSIP settings into the app is very easy:

1. Open the app's .pro QMake project file
2. Include pjsip.pri file in the relevant target section, e.g.:

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

As explained above, the pjsip.pri file is generated by configure-bb10 script and contains compilation and link flags to integrate PJSIP with your app.

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 one of the following approaches when building PJSIP.

Option 1: Build PJSIP in Multiple Directories

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

Option 2: Install PJSIP in Multiple Directories

You can use this option if you don't want to checkout PJSIP to multiple directories (for example, to simplify development):

1. Checkout PJSIP to a directory
2. Configure with the right settings for the target
3. Set a specific directory as --prefix argument to ./configure-bb10. This is where PJSIP will be installed to
4. Build
5. Run make install to install PJSIP header and lib files to the installation directory as specified by "--prefix" option.
6. Edit pjsip.pri file, change the paths to point to the installation directory.
7. Rename pjsip.pri to something more appropriate, e.g. pjsip-device-debug.pri
8. Include pjsip-device-debug.pri in the relevant section of your .pro file.
9. Repeat from step 2 for each target

Problems

Missing Separator

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

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 have Audio Capture application permissions set correctly.

Troubleshooting BlackBerry Target Device

If you're having problems with target device, make sure that:

1. Development mode is turned ON on the device (Settings --> Security and Privacy --> Development Mode)
   • Otherwise when you connect the USB you'll have a random IP address and you will not be able to connect to it 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