Changes between Version 10 and Version 11 of Getting-Started/BB10


Ignore:
Timestamp:
Apr 16, 2013 3:23:17 AM (6 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Getting-Started/BB10

    v10 v11  
    1010=== !BlackBerry 10 Native SDK === #ndk 
    1111 
    12 You'll need [https://developer.blackberry.com/native/ BlackBerry 10 Native SDK] for native development. We tested with SDK version 10.1.0.1020, but this should work with later versions too.  
    13  
    14 After you download and install the SDK, set the environment variables by running {{{bbndk-env}}} script provided in the SDK: 
     12You'll need [https://developer.blackberry.com/native/ BlackBerry 10 Native SDK] for native development. After you download and install the SDK, set the environment variables: 
    1513 {{{ 
    1614$ source $BBNDK_DIR/bbndk-env.sh 
     
    1816 
    1917 
    20 Note that it is '''no longer necessary''' to have the [https://github.com/blackberry/Cascades-Community-Samples/tree/master/bb10-pjsipdemo BB10 PJSIP Demo] as PJSIP now contains a PJSUA demo for !BlackBerry. 
    21  
    2218 
    2319[[BR]] 
     
    3733 }}} 
    3834 1. {{{cd}}} to PJSIP source directory. 
    39  1. Run '''{{{configure-bb10}}}''' script with suggested parameters as follows. This will setup PJSIP with debugging info and '''without optimization'''.  
     35 1. (For debug build) Run '''{{{configure-bb10}}}''' script with debugging info and '''without optimization'''.  
    4036 {{{ 
    4137$ CFLAGS="-O -g" ./configure-bb10 --disable-speex-aec 
    4238 }}} 
    43  You can pass additional parameters as both environment variables or command line options to the '''{{{configure-bb10}}}''' script. See further customization options in [wiki:Getting-Started/Autoconf Building with GNU] page or run '''{{{./configure --help}}}''' for more info. 
     39 See Build Customiation section in [wiki:Getting-Started/Autoconf#BuildCustomizations Building with GNU] page or run '''{{{./configure --help}}}''' for more customization info. 
    4440 1. We suggest to fill in your '''{{{config_site.h}}}''' ({{{pjlib/include/pj/config-site.h}}} file) with the following: 
    4541 {{{ 
     
    113109== Configuring the Device and Momentics IDE == 
    114110 
    115 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 [https://developer.blackberry.com/native/documentation/bb10/com.qnx.doc.native_sdk.quickstart/topic/set_up_your_environment.html these instructions].  
    116  
    117 Assorted things to check before debugging an application to the device: 
     111For 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. If not, follow [https://developer.blackberry.com/native/documentation/bb10/com.qnx.doc.native_sdk.quickstart/topic/set_up_your_environment.html these instructions] from !BlackBerry developer site. 
     112 
     113 
     114[[BR]] 
     115 
     116== Building and Running the pjsua Demo Application == 
     117 
     118PJSIP comes with a fully featured pjsua application which runs on all platforms that PJSIP supports including BB10.  
     119 
     120=== Import the PjsuaBB Project === 
     121 
     122In Momentics IDE: 
     123 1. Select '''File''' --> '''Import..''' 
     124 1. Select '''General''' and '''Existing Projects into Workspace''', and press '''Next >''' 
     125 1. In ''Import..'' dialog: 
     126    - Select root directory: '''{{{$PJ_DIR/pjsip-apps/src/pjsua/bb10}}}''' 
     127 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''' 
     128 
     129=== Build PjsuaBB === 
     130 
     131Just build it. 
     132 
     133=== Create Debug Configuration === 
     134 
     135 1. Highlight "PjsuaBB" from the Project Navigator, select '''Run''' --> '''Debug Configurations..''' from the main menu 
     136 1. From the left list, right click '''!BlackBerry C/C++ Application''', and select '''New..''' 
     137 1. New debug settings will appear with default values 
     138 1. Go to '''Debugger''' tab and uncheck '''Stop on startup''' 
     139 1. Press '''Apply''' 
     140 
     141=== Running PjsuaBB === 
     142 
     143Launch 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. 
     144 
     145 
     146[[BR]] 
     147 
     148== Creating a New PJSIP Based Application == #newapp 
     149 
     150=== Creating a !BlackBerry Native Application === #appconfig 
     151 
     152Use Momentics new project wizard to create a new !BlackBerry native application. This should be easy, and we will not explain it here. 
     153 
     154Configure the permissions by double-clicking ''bar-descriptor.xml'' file and select ''Application'' tab from the bottom of the page, and check these permissions: 
     155 - Internet 
     156 - Microphone 
     157 - Run When Backgrounded 
     158 
     159 
     160=== Integrating PJSIP into the App ===  #newappintegrate 
     161 
     162Integrating PJSIP settings into the app is very easy: 
     163 1. Open the app's '''.pro''' file (e.g. {{{PjsipBB.pro}}} for PjsipBB app) 
     164 1. Include '''pjsip.pri''' file in the relevant target section, e.g.: 
     165 {{{ 
     166.. 
     167device { 
     168    CONFIG(debug, debug|release) { 
     169        .. 
     170        include(../../../../pjsip.pri) 
     171        LIBS += -lbb 
     172        .. 
     173    } 
     174} 
     175.. 
     176 }}} 
     177 
     178The '''pjsip.pri''' file is generated by {{{configure-bb10}}} script (as explained [#pjsippri above]) and contains compilation and link flags to integrate PJSIP with your app.  
     179 
     180 
     181[[BR]] 
     182 
     183== Simulator == 
     184 
     185Install 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: 
     186 {{{ 
     187$ ./configure-bb10 --simulator 
     188 }}} 
     189 
     190 
     191[[BR]] 
     192 
     193== Multiple PJSIP Build Configurations == 
     194 
     195If 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. 
     196 
     197 
     198=== Option 1: Build PJSIP in Multiple Directories === 
     199 
     200This 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. 
     201 
     202=== Option 2: Checkout Once, Configure Build and Install Several Times === 
     203 
     204The 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. 
     205 
     206 
     207 
     208[[BR]] 
     209 
     210== Notes == 
     211 
     212=== Missing Separator === 
     213 
     214If you forgot to run '''{{{source bbndk-env.sh}}}''' (as explained [#ndk 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. 
     215 
     216=== GSM Call Interruption Problem === #gsm 
     217 
     218If 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. 
     219 
     220To 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. 
     221 
     222Thank you Bob Cripps of Truphone for the note. 
     223 
     224=== Unable to Get Sound Device Parameters === #snd0 
     225 
     226This error happens because PJSIP is unable to open the audio capture device. Make sure you set the [#appconfig application permissions] correctly. 
     227 
     228=== Troubleshooting !BlackBerry Target Device === #targetprob 
     229 
    118230 1. Development mode is turned ON (''Settings'' --> ''Security and Privacy'' --> ''Development Mode'') 
    119231    - 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 
     
    126238     - you can ping it (make sure Development Mode is ON) 
    127239     - the IP address is correct in Momentics target properties 
    128  
    129  
    130 [[BR]] 
    131  
    132 == Building and Running the pjsua Demo Application == 
    133  
    134 PJSIP comes with a fully featured pjsua application which runs on all platforms that PJSIP supports including BB10.  
    135  
    136 === Import the PjsuaBB Project === 
    137  
    138 In Momentics IDE: 
    139  1. Select '''File''' --> '''Import..''' 
    140  1. Select '''General''' and '''Existing Projects into Workspace''', and press '''Next >''' 
    141  1. In ''Import..'' dialog: 
    142     - Select root directory: '''{{{$PJ_DIR/pjsip-apps/src/pjsua/bb10}}}''' 
    143  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''' 
    144  
    145 === Build PjsuaBB === 
    146  
    147 Just build it. 
    148  
    149 === Create Debug Configuration === 
    150  
    151  1. Highlight "PjsuaBB" from the Project Navigator, select '''Run''' --> '''Debug Configurations..''' from the main menu 
    152  1. From the left list, right click '''!BlackBerry C/C++ Application''', and select '''New..''' 
    153  1. New debug settings will appear with default values 
    154  1. Go to '''Debugger''' tab and uncheck '''Stop on startup''' 
    155  1. Press '''Apply''' 
    156  
    157  
    158 [[BR]] 
    159  
    160 == Creating a New PJSIP Based Application == #newapp 
    161  
    162 === Creating a !BlackBerry Native Application === #appconfig 
    163  
    164 Use Momentics new project wizard to create a new !BlackBerry native application. This should be easy, and we will not explain it here. 
    165  
    166 Configure the permissions by double-clicking ''bar-descriptor.xml'' file and select ''Application'' tab from the bottom of the page, and check these permissions: 
    167   - Internet 
    168   - Microphone 
    169   - Run When Backgrounded 
    170  
    171  
    172 === Integrating PJSIP into the App ===  #newappintegrate 
    173  
    174 Integrating PJSIP settings into the app is very easy: 
    175  1. Open the app's '''.pro''' file (e.g. {{{PjsipBB.pro}}} for PjsipBB app) 
    176  1. Include '''pjsip.pri''' file in the relevant target section, e.g.: 
    177  {{{ 
    178 .. 
    179 device { 
    180     CONFIG(debug, debug|release) { 
    181         .. 
    182         include(../../../../pjsip.pri) 
    183         LIBS += -lbb 
    184         .. 
    185     } 
    186 } 
    187 .. 
    188  }}} 
    189  
    190 The '''pjsip.pri''' file is generated by {{{configure-bb10}}} script (as explained [#pjsippri above]) and contains compilation and link flags to integrate PJSIP with your app.  
    191  
    192  
    193 [[BR]] 
    194  
    195 == Simulator == 
    196  
    197 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: 
    198  {{{ 
    199 $ ./configure-bb10 --simulator 
    200  }}} 
    201  
    202  
    203 [[BR]] 
    204  
    205 == Multiple PJSIP Build Configurations == 
    206  
    207 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. 
    208  
    209  
    210 === Option 1: Build PJSIP in Multiple Directories === 
    211  
    212 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. 
    213  
    214 === Option 2: Checkout Once, Configure Build and Install Several Times === 
    215  
    216 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. 
    217  
    218  
    219  
    220 [[BR]] 
    221  
    222 == Notes == 
    223  
    224 === Missing Separator === 
    225  
    226 If you forgot to run '''{{{source bbndk-env.sh}}}''' (as explained [#ndk 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. 
    227  
    228 === GSM Call Interruption Problem === #gsm 
    229  
    230 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. 
    231  
    232 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. 
    233  
    234 Thank you Bob Cripps of Truphone for the note. 
    235  
    236 === Unable to Get Sound Device Parameters === #snd0 
    237  
    238 This error happens because PJSIP is unable to open the audio capture device. Make sure you set the [#appconfig application permissions] correctly. 
    239