= Getting Started: Building and Debugging PJSIP on Symbian S60 3rd Edition Device using Carbide C++ = [[TracNav(Getting-Started/TOC)]] Deploying PJSIP on Symbian S60 is recommended only on real devices as the emulator has audio and networking problems. This document applies to PJSIP version 2.2 or above, for version 2.1 or below (including 1.x), check [wiki:Symbian-1x here]. This document covers the following topics: [[PageOutline(2-3,,inline)]] ---- == Requirements == - Symbian SDK, known supported platforms are S60 3rd ed (plain, MR, FP1, FP2), S60 5th ed, and Nokia N97. The SDKs can be downloaded from: - [http://www.developer.nokia.com/info/sw.nokia.com/id/ec866fab-4b76-49f6-b5a5-af0631419e9c/S60_All_in_One_SDKs.html All in one package] for S60 5th ed, S60 3rd ed FP2, and Nokia N97 SDKs. - [http://www.developer.nokia.com/info/sw.nokia.com/id/4a7149a5-95a5-4726-913a-3c6f21eb65a5/S60-SDK-0616-3.0-mr.html Platform SDK for C++] for S60 3rd ed FP1 and S60 3rd ed (MR). - [http://www.developer.nokia.com/info/sw.nokia.com/id/dbb8841d-832c-43a6-be13-f78119a2b4cb.html Carbide C++ IDE]. - [http://www.nokia.com/global/support/nokia-pc-suite/ Nokia PC Suite] for the connectivity between the device and your PC. - [wiki:Getting-Started/Download-Source pjsip source code] - [wiki:S60-Phones-Supported Nokia S60 3rd/5th edition device]. Note that the date and time of this device need to be the same as development PC otherwise you may get certificate errors. - Nokia data cable for on-device debugging (you can also use Bluetooth connection) ---- == Installations == === SDK === Follow the installation instructions in the SDK documentation (make sure that the SDK requisites, such as [http://downloads.activestate.com/ActivePerl/Windows/5.6/ 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, Note that for older version of Carbide, e.g: Carbide 2.0, you will need to '''choose Developer Edition''' during installation to enable on-device debugging/TRK feature. === 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, a dialog of USB mode operations will be shown, 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. === PJSIP === [http://trac.pjsip.org/repos/wiki/Getting-Started/Download-Source Get the source code], if you haven't already. ---- == Importing PJSIP Projects == 1. Select '''File''' --> '''Import''' from the menu. 1. On the 'Import' dialog, select '''Symbian OS''' --> '''Symbian OS Bld.inf file''' from the tree. 1. On the next dialog, click '''Browse..''' button, select '''bld.inf''' file from PJSIP's {{{build.symbian}}} directory. 1. On the SDK selection dialog, check the target SDKs and build configurations. 1. Next you will be presented with MMP selection dialog. Just select all MMPs. 1. Once the importing process completes, you will see the PJSIP project tree on the bottom left part of the Carbide main window. - Note: on the '''Problems''' pane (bottom center of the main window) you may see one ''Warning'' about duplicate path, but we can ignore this for now. ---- == Building the Projects == #build 1. Select active build configuration: 1. Select the (just imported) PJSIP project in the Carbide's ''Project Explorer'' or ''Symbian Project Navigator'' pane. 1. On the main menu, select '''Project''' --> '''Build Configuration''' --> '''Set Active''' --> select the SDK used for the build. - alternatively, this can be set via right clicking the PJSIP project --> '''Build Configuration''' --> '''Set Active''' --> select the SDK used for the build. 1. Build the Project: 1. Setup PJSIP config on {{{pjlib/include/pj/config_site.h}}} file. As starting point, we would suggest to just fill it with the following: {{{ #include }}} 1. Select the (just imported) PJSIP project in the Carbide's ''Project Explorer'' or ''Symbian Project Navigator'' pane. 1. On the main menu, select '''Project''' --> '''Build Project'''. - Alternatively, this can be done via right clicking the PJSIP project --> '''Build Project'''. 1. 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. ---- == Preparing the .sis/.sisx Installer 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++. 1. Configure the {{{.pkg}}} configuration file to be used 1. Open ''Project Properties'' dialog from main menu or right click on the PJSIP project. 1. Select '''Carbide.c++''' --> '''Build Configuration''' from the tree (left part of the dialog). 1. Check if the Active Configuration is set correctly to the targeted SDK. 1. On ''SIS Builder'' tab, click ''Add'' button - Set ''PKG File'' to {{{pjsip-apps/src/pjsua/symbian/sis/pjsua.pkg}}} from the drop down. - Optional, set ''Signing Options'' appropriately, for now, just leave its setting to ''Self sign sis file''. Note that, to be able to distribute the application properly, you will need to sign it with a valid certificate from Symbian. - Just leave the other setting fields empty for now. 1. Done with ''Project Properties'' dialog, click the ''OK'' button. 1. You may need to refresh the project by right clicking on the project and '''Refresh'''. 1. [#build Build the Project] to generate the {{{.sisx}}} file. Note that once PKG has been setup on the project, a SISX file will be created everytime we build the project. After the build process completes, you should see something like this on the '''Console''' tab: {{{ Signing ***SIS Creation Complete Total Time: 12 sec }}} In case such line is not shown, check the ''Problems'' tab to see if we have any errors (there shouldn't be any). 1. The {{{pjsua.sisx}}} file should be located in {{{pjsip-apps/src/pjsua/symbian/sis/}}} directory. It can be deployed to the device using Nokia Application Installer (included with PC Suite). Things to note on the deployment: - Application Manager has been set to [#device-sec allow all]. - Date and time of phone matches development PC. ---- == Configuring On-Device Debugging == Make sure the phone is connected to the PC using the data cable. === Configuring Device Security === #device-sec 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''' 1. On ''App. manager'', select menu '''Options''' --> '''Settings''' 1. Set '''Software installation''' to '''All''' === Installing TRK Application on the Phone === TRK provides the debugging service from the device side. 1. On the menu, select '''Help''' --> '''On-device connection''' to open ''Connection Setting'' dialog. 1. On the ''Setup Connection'' tab, configure the connection type to ''USB'' and select the ''Serial Port'' to the target device (when the phone device is properly connected, the name should be shown in the drop down menu). 1. On the ''Install Remote Agent'' tab, there will be list/tree of TRK version for each Symbian OS version, select the TRK version appropriately according to the SDK/OS version used by the target phone/device and click ''Install'' button, and follow the installation instruction on the device. Just for reference, here is a map of SDK name and its OS version target: ||=SDK=||=OS target=|| ||S60 3rd Plain/MR||3.0.0|| ||S60 3rd FP1||3.1.0|| ||S60 3rd FP2||3.2.0|| ||S60 5th||5.0.0|| === Running TRK Application on the Device/Phone === 1. Run it from '''Menu''' --> '''Installations'''/'''Applications''' --> '''TRK'''. 1. When it asks to switch on Bluetooth, click '''No'''. Note, you can re-configure it later to use Bluetooth if you want from the ''Option'' --> ''Settings'' menu in the TRK application. 1. The TRK window will appear and there should be line as: {{{ Status: Connected }}} === Setting and Testing Connection Settings === 1. On the menu, select '''Help''' --> '''On-device connection''' to open ''Connection Setting'' dialog. 1. On the ''Setup Connection'' tab, configure the connection type to ''USB'' and select the ''Serial Port'' to the target device (when the phone device is properly connected, the name should be shown in the drop down menu). 1. Make sure the TRK application on the device is running, and on the ''Test Connection'' tab, select ''TRK'' as the service to test, and click '''Initiate service testing''' button. 1. If everything is okay, you will get the TRK version info printed on the area in the status textbox, e.g: {{{ Installed TRK is latest available version: version = 3.1.2 }}} === Start Debugging === 1. Setup a debug configuration by selecting '''Run''' --> '''Debug Configurations..''' from the Carbide's main menu. 1. Select ''Symbian OS Application TRK'' from the left pane list and click ''New launch configuration'' icon on the top left. 1. The new debug configuration is created and appears on the left pane list, now we need adjust the setting: - '''Remote process to launch''' should be set to {{{pjsua.exe}}}, e.g: on Windows it should be {{{C:\sys\bin\pjsua.exe}}} - Setup the connection properly and optionally run connection test again by clicking '''Edit''' button and activate ''Test Connection'' tab. - On the ''Installation'' tab, verify that the installer file ({{{.sisx}}}) is set to {{{pjsua.sisx}}} which we already generated beforehand. 1. Click '''Debug''' button to start the debugging right away. - 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 {{{.sisx}}} file will be downloaded to the phone. - It may take some time to see the {{{pjsua}}} application started on the device. The '''pjsua''' application is ready when 'PJSUA' logo+text and 'Telnet to IP:port' appears on the screen. - Note that the network connection (usually via WiFi) should have been setup properly on the device. 1. Start a telnet client and connect to the IP address and port as shown in the ''pjsua'' application screen. You may make calls, receive calls, do presence stuffs, etc from the telnet Command Line Interface session. Full debugging should also be possible; you may set breakpoints, step into functions, etc. You can now move on to bigger and better things: [wiki:APS APS & VAS] ---- == 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). 1. 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. 1. Try cleaning and re-building the project. 1. 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". 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.). }}} 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. === Load Failed: TRKProtocolPlugin: Failed to launch the application === If you get this error while trying to debug the application: {{{ Load Failed: TRKProtocolPlugin: Failed to launch the application (Installing the application may have failed or dependent libraries may be missing) }}} Solution: - the application may genuinely be missing some dependent libraries - try to install the app manually from Windows Explorer, then run it in the phone (not from Carbide). If it won't run (it may or may not display any error messages, in the later case, the application just won't start when you click it on the phone), then it may be missing the dependent libraries. - think about the libraries that the application needs (for example: APSServer, SSL and PIPS if for the TLS, and so on), and install them to the phone. - make sure the .sisx specified in Debug - Installation matches the .sisx specified in the Project Build properties: - check the .sisx in Debug - Installation: - open Debug Configurations dialog (from Run menu), - select the debug configuration item from the left tree panel (e.g. select "pjproject phone Debug ((GCCE) [S60_3rd_FP1])") - go to "Installation" tab - check the .sisx name - check the .sisx in Project Build properties: - right click the project from "Symbian Project Navigator" panel, select "Properties" - in the "Properties" dialog, from the left tree panel, select "Carbide C++" then "Build Configurations" - in the "SIS Builder" tab, make sure build for pjsua.sisx is checked, and optionally, "Partial Upgrade" is also checked - if you don't see the pjsua.sisx entry in the list: - press "Add" - set "PKG File:" to pjsua.pkg - leave "Signing Options" to "Self sign sis file" - press "OK" - If everything above has been set correctly and you still get the error, this is what I did that fixed it: - install the pjsua.sisx manually from Windows Explorer, located in {{{pjsip-apps/src/pjsua/symbian/sis}}} directory (right click pjsua.sisx and select Install with Nokia Application Installer) - the installation was successful - uninstall the app from the phone - delete both the .sis and .sisx in the Windows computer - build the project again in Carbide - and launch debug === Load Failed: TRKProtocolPlugin: Unable to install the application === If you get this error when trying to launch debug: {{{ Load Failed: TRKProtocolPlugin: Unable to install the application. If self signing, certificate could be invalid if your PC clock is ahead of your phone clock. If not, your developer certificate may be invalid or UID of your application may be invalid or already in use. }}} The solution is hinted in the message. Common causes are: - your PC clock is ahead of the phone clock - there may be other application installed in the phone which uses the same UID. - we may inadvertenly use the same UID for other PJSIP applications such as pjlib-test. In this case uninstall all of these other apps. === High Audio Latency === This is a known limitation of Symbian sound device with MDA backend, some says that internally Symbian uses high buffer (4096 bytes). Alternatively, use [wiki:APS APS] or [wiki:VAS VAS] for low latency audio device. === 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 {{{pjsua.mmp}}} the EPOCSTACKSIZE setting is set to 20KB (0x5000B). ---- == Other Resources == Checkout: - Tutorial for using PJSIP version 2.1 or below (including 1.x) on Symbian, please check [wiki:Symbian-1x here]. - [http://newlc.com/Carbide-c-Setting-up-On-Target.html Carbide.c++: Setting up On Target Debugging | NewLC] - this article describes how to set up on-device debugging using Bluetooth connection.