Building and Debugging PJSIP on Symbian S60 3rd Edition Device using Carbide C++ 1.2

Introduction

Note there is an updated guide for Carbide C++ 2.0

Previously PJSIP did not support Carbide C++ as the development tools for Symbian target, since Carbide did not import PJSIP's MMP files properly. But with the release of Carbide C++ version 1.2, Carbide is now able to build PJSIP projects fine. And since it seems that Nokia strongly suggests to use Carbide for the development tools instead of CodeWarrior, it may worth to write some small documentation to help you get started with developing PJSIP applications on Symbian using this tool quickly.

This document covers the following topics:

1. Introduction
2. Requirements
3. Installations
   1. SDK
   2. Carbide
   3. Nokia PC Suite
   4. PJSIP
4. Importing PJSIP Projects
5. Building the Projects
   1. Select the Build Configuration
   2. Build the Project
6. Preparing the .sis/.sisx File
   1. Set the .pkg File to be Used
   2. Edit the PKG File
   3. Build the SISX File
7. Configuring On-Device Debugging
   1. Configuring Device Security
   2. Installing TRK Application on the Phone
   3. Running TRK Application on the Phone
   4. Finding the COM Port Mapping for the Phone Connection
   5. Configure the Debug Settings in Carbide
   6. Debugging Application
8. Common Problems
   1. Problem with Build/Clean?
   2. I/O Error: File in Use (I/O Fault)
   3. TRKProtocolPlugin: Failed to download the specified file to target
   4. TRKProtocolPlugin: Failed to continue thread
   5. TRK Not Running Error
   6. High Audio Latency
   7. Random Crash/Stack? Size Problem
9. Other Resources

---

Requirements

For this tutorial, we will need:

• ​Symbian S60 3rd Edition Maintenance Release (MR). Other SDK versions may work, but I did not test it.
• ​Carbide C++ version 1.2 or higher. You will need the Developer Edition to do on-device debugging (21 days evaluation is available). You can also use the Express Edition, just ignore the instructions on debugging.
• ​Nokia PC Suite for the connectivity between the device and your PC (I use version 6.85)
• Latest PJSIP from SVN trunk
• Nokia S60 3rd Edition device (I use Nokia E70, but any S60 3rd Edition device should do, I think)
• Nokia data cable for on-device debugging (you can also use Bluetooth connection, but this tutorial will not cover it)

---

Installations

SDK

Follow the installation instructions in the SDK documentation (make sure that the SDK requisites, such as Perl version, are satisfied). Please install Symbian SDK on the same drive as PJSIP.

Carbide

Follow the installation instructions in the Carbide C++ documentation. The installation should be straightforward, but don't forget to select the Developer's Edition (instead of Personal Edition) to get the On-Device debugging/TRK Debugging feature.

(There is a 21 days evaluation period for the Developers Edition. If you have installed Carbide before and your evaluation period is over, you may not be able to select the Developers Edition, and you will have to purchase the Developers license)

Nokia PC Suite

Install PC Suite, connect your device with the USB cable, and make sure your PC can access your device.

Connect Data Cable

Connect the USB cable to the phone, and on the phone, select PC Suite:

If this is the first time you connect your phone to the PC, then it may take some time for Windows to install the USB drivers for the phone. Wait for it to complete and the Nokia PC Suite and PC Sync icons on the task bar tray become green:

Leave PC Suite running with the device connected using the USB cable throughout this tutorial session.

PJSIP

Retrieve and configure PJSIP:

1. For this tutorial, I assume pjsip will be checked out to C:\project\pjproject directory.
2. Checkout PJSIP from the usual location (see ​PJSIP Download page for details).
3. Fill in your config_site.h with:

   #include <pj/config_site_sample.h>
   

---

Importing PJSIP Projects

Run Carbide C++. When it asks the workspace location, enter a directory where you would want to put Carbide specific settings for PJSIP (or just accept the default value):

You will now be presented with Carbide Welcome page.

Now we need to import PJSIP's project files (the MMP files) into Carbide's workspace.

Select File --> Import from the menu:

This dialog below will pop up. Select Symbian OS --> Symbian OS Bld.inf file from the list, then press Next button:

On the next dialog, click Browse.. button to select bld.inf file from PJSIP's build.symbian directory, then press Next button:

Then on the SDK selection dialog, select the build configurations that you want to support. For this tutorial, select WINSCW and GCCE from S60 3rd Edition MR SDK, and press Next button (do not select ARMV5 unless you have the commercial ARMV5 compiler):

You will then presented with MMP selection dialog. Leave the default selection (normally it should select all MMPs) and press Next:

The project now is ready to be imported, press the Finish button:

Carbide is now exporting the MMP files into the workspace and this progress window will be displayed:

Wait for the process to complete.

Once it completes, you will see the PJSIP project tree on the bottom left part of the Carbide main window:

On the Problems pane (bottom center of the main window) you can see there is one Warning about duplicate path, but we can ignore this for now.

The projects should now be ready to be build.

---

Building the Projects

Lets try to build the project first to make sure that the source is okay.

Select the Build Configuration

First select the build target by selecting Project --> Active Build Configuration from main menu (or right clicking the Bld.inf or pjproject item from Symbian Project Navigator pane from the bottom left part of the main window).

Select Phone Debug (GCCE) [S60_3rd_MR] from the menu:

Build the Project

Then right click Bld.inf or pjproject item from Symbian Project Navigator pane from the bottom left part of the main window, and select Build Target Only:

Wait for the build process to complete. You may take a peek on what Carbide is doing by clicking on Console pane/tab in the bottom part of main window.

Once it completes, watch out for any errors in the Problems pane (at the bottom center). There shouldn't be any errors, although there may be few warnings which I think can be ignored, for now:

We are now ready to build the .sis/.sisx file to be deployed to the phone.

---

Preparing the .sis/.sisx File

The .sis file is the packaging for the executable to be deployed in the device. The .sisx file is a signed .sis. Both the .sis and .sisx file can be created very easily with Carbide C++.

Set the .pkg File to be Used

First we'll need to configure the .pkg file to be used to generate the .sisx file. PJSIP provides some sample .pkg files which can be used, however there may be few editing needed before you can use them (this is because the .pkg file contains absolute directory path for your Symbian SDK, which may be different on your installation).

Assign the .pkg file to be used by the project by selecting Project Properties:

Then Project Properties dialog will appear. On this dialog:

1. Select Carbide Build Configuration from the tree (left part of the dialog).
2. Make sure that the Active Configuration is set to Phone Debug (GCCE) [S60_3rd_MR] (the SDK name will be different, if you use different SDK version)
3. Set the PKG File by clicking Browse... button, and choose symbian_ua_udeb.pkg from PJSIP's build.symbian directory.

We can leave the "SIS creation and Signing" settings empty to use the default settings.

The dialog window now should look like this:

Press OK button to save the project configuration.

Now right click bld.inf (or pjproject) and click Refresh:

Wait for few seconds (30 seconds on my computer) for Carbide to do its job, once it's done, you will see the .pkg file in the Project Navigator pane:

Note:

The picture above displays symbian_ua.pkg in the tree, while actually it should display symbian_ua_udeb.pkg instead.

Edit the PKG File

As said earlier, the PKG file contains absolute directory path for the SDK, so you may need to edit it if your SDK location is different than the one specified in the PKG.

Edit the PKG by double clicking it in the Symbian Project Navigator pane. Check out these lines in the PKG file:

; Target
"C:\Symbian\9.1\S60_3rd_MR\epoc32\release\gcce\UDEB\symbian_ua.exe"-"!:\sys\bin\symbian_ua.exe"

Check that the SDK path is correct.

Once you are done with the modification, save the file. We can close the PKG file editor window now.

Build the SISX File

Once PKG has been setup on the project, a SISX file will be created everytime we build the project. So lets build the project now.

Right click bld.inf or pjproject from the Symbian Project Navigator pane, and select Build Target Only:

The build process will start. You can take a peek on the Console tab to see what's being done. Once the build process completes, you should see something like this on the Console tab:

Signing

***SIS Creation Complete

Total Time: 12 sec

Check the Problems tab again to see if we have any errors (there shouldn't be any).

---

Configuring On-Device Debugging

Make sure the phone is connected to the PC using the data cable.

Configuring Device Security

By default, your phone does not allow self-signed certificate to be installed on the phone, I think. To change this setting:

1. Go to Menu --> Tools --> App. Mgr
2. On App. manager, select menu Options --> Settings
3. Set Software installation to All

Installing TRK Application on the Phone

Install TRK support on the phone. The TRK application can be found in C:\Program Files\Nokia\Carbide.c++ v1.2\plugins\com.nokia.carbide.trk.support_1.2.0.29\trk\s60 directory. For my phone, the one that works is s60_3_0_app_trk_2_7.sisx. Right click this .sisx file and select Install with Nokia Application Installer:

When asked if we want to install, click Yes:

On the PC, this window should be displayed.

Leave it this way, the installation will start on the phone now. Your phone should display something like this:

Click Yes.

Now the phone will display Details information:

Click Continue.

Your phone may now display the target memory location:

Select the memory and press Select menu.

Now the phone will display license agreement:

Click OK (if you agree, of course). The phone should display installation progress window for couple of seconds now:

Once it's done, Installation Complete window will appear briefly:

TRK is now installed on the phone. Next step is to run it.

Running TRK Application on the Phone

1. Run it from Menu --> Installations --> TRK (it may be different on your phone).
2. When it asks to switch on Blueetooth, click No. We use USB cable for this session.
3. The TRK window will appear. We can ignore the error message for now:

1. Select Options --> Settings menu.
2. Change the Connection to USB, and leave all settings unchanged:

1. Click Back to get back to TRK main window.
2. Now select Options --> Connect from the menu.
3. TRK main window should display Status: Connected now:

Leave TRK running on the phone for the duration of this tutorial.

Finding the COM Port Mapping for the Phone Connection

Find out which COM port is the phone connection mapped to, in Device Manager:

In this case, the COM port is COM3. Note this COM port number, as we will need to specify it in Carbide.

Configure the Debug Settings in Carbide

Back to Carbide.

Next we will need to create a new on-device debugging configuration.

Select Run --> Debug... from the main menu:

Debug dialog will appear like below:

Create a new Debug configuration for on-device debugging

Right-click Symbian OS App TRK, and click New.

New configuration will appear on the dialog. We need to edit few things:

1. Rename the configuration name from pjproject Phone Debug... to symbian_ua Phone Debug..., as seen in the picture below. (Hints: when we have different executable to debug, we will create different configuration).
2. Set the Executable
3. Set the Remote process to launch

You should see something similar to the image below.

Now click on Apply button. The configuration name on the left tree now will get updated.

Configure TRK Connection

Now select Connection tab. Choose the Serial Port to the COM port where your phone connection is mapped to, which you have found out from the step above (look at the Device Manager). In my case, it was COM3:

The Baud Rate setting should match the setting on the TRK application running on the phone. Since we have not changed this setting, just accept the default value (115200).

Now click on Apply button.

Configure SIS File

Now select the Installation tab. Browse the .sisx file from PJSIP's build.symbian directory:

Now click Apply button

We are now ready to perform on-device debugging! Get yourself some tea, you deserve some break.

Debugging Application

Still in the Debug dialog, press the Debug button. Hold your breath!

Carbide now may rebuild the project (you may take a peek on what it's doing by looking at Console tab). Once it's done, Carbide will switch to Debug Perspective and the SIS file will be downloaded to the phone and this window will appear briefly:

When this window dissappear, you should see the application runs on the phone:

You may make calls, receive calls, do presence stuffs, etc. Full debugging should also be possible; you may set breakpoints, step into functions, etc.

---

Common Problems

Problem with Build/Clean?

Sometimes Carbide does not build the project properly after we make some changes to the source. This will cause the old code to be built instead of the new changes.

My standard work flow is to always clean the library/application project containing the modified source before building the whole project, to make sure that the modified libraries/application gets rebuilt properly.

I/O Error: File in Use (I/O Fault)

Sometimes .SIS creation fails with I/O error message in the Problems pane similar to this message:

file I/O fault
makesis.exe returned with exit value == 1
The process cannot access the file because it is being used by another process.

This sounds like a generic error from the build system, and it may be caused by several problems. You can try these and see which one solves it:

1. First check that the build process has completed without errors (a build error will cause the executable not to get built, and this will cause .sis creation to fail).
2. Rather than selecting "Build Target Only", try with "Build Project" from the menu. Sometimes build directories are not created when "Build Target Only" is used.
3. Try cleaning and re-building the project.
4. Sometimes restarting Carbide C++ also fixes it.

TRKProtocolPlugin: Failed to download the specified file to target

I had experienced this few times. The file seems to be downloaded to the phone fine (the download progress bar shows progress), but once debugging starts Carbide displays "Carbide Alert": "Load Failed", "TRKProtocolPlugin: Failed to download the specified file to target" (as shown in the picture below).

I'm not sure what's causing this, but closing TRK on the phone, then reconnecting the USB cable and restarting TRK seems to have fixed this.

TRKProtocolPlugin: Failed to continue thread

The solution is similar to above.

TRK Not Running Error

Sometimes I get Carbide complaining about TRK not running:

Launching

Target request failed: TRKProtocolPlugin: Can't connect to TRK
(TRK may not be running on the phone or mismatch between selected and
connected com port.).

Like this dialog:

If you see TRK is running on the phone, it means that your phone is hung now. Restart the phone by disconnecting the USB cable, taking of the battery, put it back on, start the phone, connect the USB cable, and re-run TRK again.

High Audio Latency

We're working on this issue.

Random Crash/Stack? Size Problem

When you have random crash (sometimes in ICE/pjnath or in DNS SRV resolver) or KERN-EXEC 3 when running without debugger, check if increasing stack size in the MMP fixes the problem. The default stack size (8KB) is not sufficient, hence in symbian_ua.mmp the EPOCSTACKSIZE setting is set to 12KB.

---

Other Resources

Checkout:

• ​Carbide.c++: Setting up On Target Debugging | NewLC - this article describes how to set up on-device debugging using Bluetooth connection.