Changes between Version 1 and Version 2 of Getting-Started/Symbian


Ignore:
Timestamp:
May 6, 2009 8:55:12 AM (10 years ago)
Author:
ismangil
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Getting-Started/Symbian

    v1 v2  
     1= Getting Started: Building and Debugging PJSIP on Symbian S60 3rd Edition Device using Carbide C++ = 
    12[[TracNav(Getting-Started/TOC)]] 
     3 
     4[[Image(symbian_ua.JPG)]] 
     5 
     6This document covers the following topics: 
     7 
    28[[PageOutline(2-3,,inline)]] 
     9 
     10 
     11---- 
     12 
     13== Requirements == 
     14 
     15For this tutorial, we will need: 
     16 - [http://www.forum.nokia.com/info/sw.nokia.com/id/4a7149a5-95a5-4726-913a-3c6f21eb65a5/S60-SDK-0616-3.0-mr.html Symbian S60 3rd Edition Maintenance Release (MR)]. We also have tried this on FP1. Other SDK versions may work, but I did not test it. 
     17 - Carbide C++ version 2.0. You will need choose Developer Edition during install to do on-device debugging. 
     18 - [http://europe.nokia.com/A4144903 Nokia PC Suite] for the connectivity between the device and your PC (I use version 6.85) 
     19 - Latest PJSIP from SVN trunk 
     20 - Nokia S60 3rd Edition device (I use Nokia E70, but any S60 3rd Edition device should do, I think) 
     21 - Nokia data cable for on-device debugging (you can also use Bluetooth connection, but this tutorial will not cover it) 
     22 
     23---- 
     24 
     25== Installations == 
     26 
     27=== SDK === 
     28 
     29Follow 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. 
     30 
     31=== Carbide === 
     32 
     33Follow the installation instructions in the Carbide C++ documentation. The installation should be straightforward, but don't forget to '''select the Developer's Edition''' to get the On-Device debugging/TRK Debugging feature. 
     34 
     35=== Nokia PC Suite === 
     36 
     37Install PC Suite, connect your device with the USB cable, and make sure your PC can access your device.  
     38 
     39==== Connect Data Cable ==== 
     40 
     41Connect the USB cable to the phone, and on the phone, select '''PC Suite''': 
     42 
     43[[Image(phone_usb.JPG)]] 
     44 
     45If 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: 
     46 
     47[[Image(pc_suite.JPG)]] 
     48 
     49Leave PC Suite running with the device connected using the USB cable throughout this tutorial session. 
     50 
     51=== PJSIP === 
     52 
     53Retrieve and configure PJSIP: 
     54 1. For this tutorial, I assume pjsip will be checked out to '''{{{C:\project\pjproject}}}''' directory. 
     55 1. Checkout PJSIP from the usual location (see [http://www.pjsip.org/download.htm PJSIP Download page] for details).  
     56 1. Fill in your '''{{{config_site.h}}}''' with: 
     57{{{ 
     58#include <pj/config_site_sample.h> 
     59}}} 
     60 
     61---- 
     62 
     63== Importing PJSIP Projects == 
     64 
     65 
     66Run 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): 
     67 
     68[[Image(carbide-workspace.JPG)]] 
     69 
     70You will now be presented with Carbide Welcome page. 
     71 
     72 
     73Now we need to import PJSIP's project files (the MMP files) into Carbide's workspace.  
     74 
     75Select '''File''' --> '''Import''' from the menu: 
     76 
     77[[Image(file_import.JPG)]] 
     78 
     79This dialog below will pop up. Select '''Symbian OS''' --> '''Symbian OS Bld.inf file''' from the list, then press '''Next''' button: 
     80 
     81[[Image(import.JPG)]] 
     82 
     83On the next dialog, click '''Browse..''' button to select '''bld.inf''' file from PJSIP's {{{build.symbian}}} directory, then press '''Next''' button: 
     84 
     85[[Image(import_bld.JPG)]] 
     86 
     87Then 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'''): 
     88 
     89[[Image(import_sdk.JPG)]] 
     90 
     91You will then presented with MMP selection dialog. Leave the default selection (normally it should select all MMPs) and press '''Next''': 
     92 
     93[[Image(import_mmp.JPG)]] 
     94 
     95The project now is ready to be imported, press the '''Finish''' button: 
     96 
     97[[Image(import_finished.JPG)]] 
     98 
     99Carbide is now exporting the MMP files into the workspace and this progress window will be displayed: 
     100 
     101[[Image(import_creating.JPG)]] 
     102 
     103Wait for the process to complete. 
     104 
     105Once it completes, you will see the PJSIP project tree on the bottom left part of the Carbide main window: 
     106 
     107[[Image(carbide_main.JPG)]] 
     108 
     109On 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. 
     110 
     111The projects should now be ready to be build. 
     112 
     113---- 
     114 
     115== Building the Projects == 
     116 
     117Lets try to build the project first to make sure that the source is okay. 
     118 
     119=== Select the Build Configuration === 
     120 
     121First 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).  
     122 
     123Select '''Phone Debug (GCCE) [S60_3rd_MR]''' from the menu: 
     124 
     125[[Image(build_config.JPG)]] 
     126 
     127=== Build the Project === 
     128 
     129Then 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''': 
     130 
     131[[Image(build.JPG)]] 
     132 
     133Wait 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. 
     134 
     135Once 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: 
     136 
     137[[Image(build_problems.JPG)]] 
     138 
     139We are now ready to build the .sis/.sisx file to be deployed to the phone. 
     140 
     141 
     142---- 
     143 
     144 
     145== Preparing the .sis/.sisx File == 
     146 
     147The .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++. 
     148 
     149 
     150=== Set the .pkg File to be Used === 
     151 
     152First 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). 
     153 
     154Assign the .pkg file to be used by the project by selecting Project Properties: 
     155 
     156[[Image(project_properties_menu.JPG)]] 
     157 
     158Then Project Properties dialog will appear. On this dialog: 
     159 
     160 1. Select ''Carbide Build Configuration'' from the tree (left part of the dialog). 
     161 1. 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) 
     162 1. Set the ''PKG File'' by clicking ''Browse...'' button, and choose {{{symbian_ua_udeb.pkg}}} from PJSIP's {{{build.symbian}}} directory. 
     163 
     164We can leave the "SIS creation and Signing" settings empty to use the default settings. 
     165 
     166The dialog window now should look like this: 
     167 
     168[[Image(project_properties.JPG)]] 
     169 
     170Press ''OK'' button to save the project configuration. 
     171 
     172Now right click '''bld.inf''' (or '''pjproject''') and click '''Refresh''': 
     173 
     174[[Image(project_refresh.JPG)]] 
     175 
     176Wait 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: 
     177 
     178[[Image(project_pkg.JPG)]] 
     179 
     180Note: 
     181 The picture above displays ''symbian_ua.pkg'' in the tree, while actually it should display ''symbian_ua_udeb.pkg'' instead. 
     182 
     183=== Edit the PKG File === 
     184 
     185As 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. 
     186 
     187Edit the PKG by ''double clicking'' it in the ''Symbian Project Navigator'' pane. Check out these lines in the PKG file: 
     188 
     189{{{ 
     190; Target 
     191"C:\Symbian\9.1\S60_3rd_MR\epoc32\release\gcce\UDEB\symbian_ua.exe"-"!:\sys\bin\symbian_ua.exe" 
     192}}} 
     193 
     194Check that the SDK path is correct. 
     195 
     196Once you are done with the modification, save the file. We can close the PKG file editor window now. 
     197 
     198 
     199=== Build the SISX File === 
     200 
     201Once PKG has been setup on the project, a SISX file will be created everytime we build the project. So lets build the project now. 
     202 
     203Right click '''bld.inf''' or '''pjproject''' from the ''Symbian Project Navigator'' pane, and select '''Build Target Only''': 
     204 
     205[[Image(build.JPG)]] 
     206 
     207The 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: 
     208 
     209{{{ 
     210Signing 
     211 
     212***SIS Creation Complete 
     213 
     214Total Time: 12 sec 
     215}}} 
     216 
     217 
     218Check the '''Problems''' tab again to see if we have any errors (there shouldn't be any). 
     219 
     220 
     221---- 
     222 
     223 
     224== Configuring On-Device Debugging == 
     225 
     226Make sure the phone is connected to the PC using the data cable. 
     227 
     228=== Configuring Device Security === 
     229 
     230By default, your phone does not allow self-signed certificate to be installed on the phone, I think. To change this setting: 
     231 1. Go to '''Menu''' --> '''Tools''' --> '''App. Mgr''' 
     232 1. On ''App. manager'', select menu '''Options''' --> '''Settings''' 
     233 1. Set '''Software installation''' to '''All''' 
     234 
     235=== Installing TRK Application on the Phone === 
     236 
     237Install 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''': 
     238 
     239[[Image(trk_path.JPG)]] 
     240 
     241When asked if we want to install, click '''Yes''': 
     242 
     243[[Image(trk_install.JPG)]] 
     244 
     245On the PC, this window should be displayed.  
     246 
     247[[Image(trk_wait.JPG)]] 
     248 
     249Leave it this way, the installation will start on the phone now. Your phone should display something like this: 
     250 
     251[[Image(trk_p_install.JPG)]] 
     252 
     253Click Yes. 
     254 
     255Now the phone will display '''Details''' information: 
     256 
     257[[Image(trk_p_details.JPG)]] 
     258 
     259Click Continue. 
     260 
     261Your phone may now display the target memory location: 
     262 
     263[[Image(trk_p_mem.JPG)]] 
     264 
     265Select the memory and press '''Select''' menu. 
     266 
     267Now the phone will display license agreement: 
     268 
     269[[Image(trk_p_lic.JPG)]] 
     270 
     271Click '''OK''' (if you agree, of course). The phone should display installation progress window for couple of seconds now: 
     272 
     273[[Image(trk_p_progress.JPG)]] 
     274 
     275Once it's done, '''Installation Complete''' window will appear briefly: 
     276 
     277[[Image(trk_p_complete.JPG)]] 
     278 
     279TRK is now installed on the phone. Next step is to run it. 
     280 
     281 
     282=== Running TRK Application on the Phone === 
     283 
     284 1. Run it from '''Menu''' --> '''Installations''' --> TRK (it may be different on your phone). 
     285 1. When it asks to switch on Blueetooth, click '''No'''. We use USB cable for this session. 
     286 1. The TRK window will appear. We can ignore the error message for now: 
     287 
     288[[Image(trk_r_welcome.JPG)]] 
     289 
     290 1. Select '''Options''' --> '''Settings''' menu. 
     291 1. Change the '''Connection''' to USB, and leave all settings unchanged: 
     292 
     293[[Image(trk_p_usb.JPG)]] 
     294 
     295 1. Click '''Back''' to get back to TRK main window. 
     296 1. Now select '''Options''' --> '''Connect''' from the menu. 
     297 1. TRK main window should display '''Status: Connected''' now: 
     298 
     299[[Image(trk_p_connected.JPG)]] 
     300 
     301Leave TRK running on the phone for the duration of this tutorial. 
     302 
     303 
     304=== Finding the COM Port Mapping for the Phone Connection === 
     305 
     306Find out which COM port is the phone connection mapped to, in Device Manager: 
     307 
     308[[Image(dev_mgr_com.JPG)]] 
     309 
     310In this case, the COM port is COM3. Note this COM port number, as we will need to specify it in Carbide. 
     311 
     312 
     313=== Configure the Debug Settings in Carbide === 
     314 
     315Back to Carbide. 
     316 
     317Next we will need to create a new on-device debugging configuration. 
     318 
     319Select '''Run''' --> '''Debug...''' from the main menu: 
     320 
     321[[Image(run_debug.JPG)]] 
     322 
     323'''Debug''' dialog will appear like below: 
     324 
     325[[Image(debug.JPG)]] 
     326 
     327==== Create a new Debug configuration for on-device debugging ==== 
     328 
     329Right-click '''Symbian OS App TRK''', and click '''New'''. 
     330 
     331New configuration will appear on the dialog. We need to edit few things: 
     332 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). 
     333 1. Set the ''Executable'' 
     334 1. Set the ''Remote process to launch'' 
     335 
     336You should see something similar to the image below. 
     337 
     338[[Image(debug_main.JPG)]] 
     339 
     340Now click on '''Apply''' button. The configuration name on the left tree now will get updated. 
     341 
     342==== Configure TRK Connection ==== 
     343 
     344Now 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: 
     345 
     346[[Image(debug_connection.JPG)]] 
     347 
     348The ''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). 
     349 
     350Now click on '''Apply''' button.  
     351 
     352==== Configure SIS File ==== 
     353 
     354Now select the '''Installation''' tab. Browse the .sisx file from PJSIP's {{{build.symbian}}} directory: 
     355 
     356[[Image(debug_installation.JPG)]] 
     357 
     358Now click '''Apply''' button 
     359 
     360We are now ready to perform on-device debugging! Get yourself some tea, you deserve some break. 
     361 
     362 
     363=== Debugging Application === 
     364 
     365Still in the '''Debug''' dialog, press the '''Debug''' button. Hold your breath! 
     366 
     367Carbide 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: 
     368 
     369[[Image(debug_download.JPG)]] 
     370 
     371When this window dissappear, you should see the application runs on the phone: 
     372 
     373[[Image(symbian_ua.JPG)]] 
     374 
     375You may make calls, receive calls, do presence stuffs, etc. Full debugging should also be possible; you may set breakpoints, step into functions, etc. 
     376 
     377 
     378---- 
     379 
     380== Common Problems == 
     381 
     382=== Problem with Build/Clean === 
     383 
     384Sometimes 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. 
     385 
     386My 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. 
     387 
     388 
     389=== I/O Error: File in Use (I/O Fault) === 
     390 
     391Sometimes .SIS creation fails with I/O error message in the ''Problems'' pane similar to this message: 
     392 
     393{{{ 
     394file I/O fault 
     395makesis.exe returned with exit value == 1 
     396The process cannot access the file because it is being used by another process. 
     397}}} 
     398 
     399This 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: 
     400 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).  
     401 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. 
     402 1. Try cleaning and re-building the project. 
     403 1. Sometimes restarting Carbide C++ also fixes it. 
     404 
     405 
     406=== TRKProtocolPlugin: Failed to download the specified file to target === 
     407 
     408I 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). 
     409 
     410[[Image(trk_fail.JPG)]] 
     411 
     412I'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. 
     413 
     414=== TRKProtocolPlugin: Failed to continue thread === 
     415 
     416[[Image(trk_fail2.JPG)]] 
     417 
     418The solution is similar to above. 
     419 
     420=== TRK Not Running Error === 
     421 
     422Sometimes I get Carbide complaining about TRK not running: 
     423 
     424{{{ 
     425Launching 
     426 
     427Target request failed: TRKProtocolPlugin: Can't connect to TRK 
     428(TRK may not be running on the phone or mismatch between selected and 
     429connected com port.). 
     430}}} 
     431 
     432Like this dialog: 
     433 
     434[[Image(trk_not_running.JPG)]] 
     435 
     436If 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. 
     437 
     438 
     439=== High Audio Latency === 
     440 
     441We're working on this issue. 
     442 
     443=== Random Crash/Stack Size Problem === 
     444 
     445When 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. 
     446 
     447---- 
     448 
     449== Other Resources == 
     450 
     451Checkout: 
     452 - [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. 
     453 
     454 
     455 
     456 
     457 
     458 
     459 
     460