README

---------------
0. Introduction
---------------
  Ikran is an experimental addon for Firefox that turns your browser into a SIP endpoint 
  for both audio and video.  It currently uses WebRTC for audio/video media support.

  The ikran is a bird from the mythical world of Pandora (Avatar).  It is well known for
  its birdcall which travels long distances using widely accepted standards for audio and video.

  Ikran can operate in two modes. (1) Registration mode, where it is a SIP UA and registers with 
  a SIP server. (2) Peer to Peer Mode, where is can communicate directly with other ikran clients
  in the same mode using SIP. 

-------------------
1. Platform Support 
-------------------
Required for all platforms:
  Python (www.python.org) -  known to work with 2.6 & 2.7 
  SCons (www.scons.org) - see section 13
  
Linux:
  Should build on Ubuntu 11.04, 11.10 or Fedora15
  Third-Party Libraries
  +Glib    - sudo apt-get install libdbus-glib-1-dev
  +asound  - sudo apt-get install libasound2-dev
  +libgtk  - sudo apt-get install libgtk2.0-dev     
  +libidn  - sudo apt-get install libidn11-dev

Mac OSX:
  Built on OSX 10.7 with XCode 4.1 and OSX 10.6 with XCode 3.2.6
  Links to Framework 10.6, minimum version 10.5
  Requires libidl installed.  You can use MacPorts ("sudo port install libidl")

Windows:
  Built regularly on Windows XP & Windows 7.
  Python path is in runSconsBuild.py and set to c:\python27
  Requires setting following environment variables
  SCONS_LOCATION pointing to scons installation
	e.g SCONS_LOCATION=c:\Python26\Scripts
  ZIP_LOCATION pointing to 7z zip installation
  MS_WINDOWS_SDK_PATH pointing to Windows SDK path ( v7.1)
  MS_VC_PATH pointing to Visual Studio installation ( VS9.0)
  DXSDK_DIR pointing to Micrsoft DirectX SDK installation
  
-----------
2. Building 
-----------
  - Get and build Mozilla Firefox, we link to some Firefox libraries
      https://developer.mozilla.org/en/Build_Documentation
      Set the MOZSRCPATH env variable to point to it - to the mozilla-central directory.
  - Build WEBRTC for video and audio engine libraries 
      +  Follow the instructions @ http://www.webrtc.org/reference/getting-started
      +  Set WEBRTCPATH to point to it : export WEBRTCPATH=/Users/XTM/HTML5/webrtc/trunk
  
  Set up these two Environment variables
    MOZSRCPATH environment variable pointing to the a built source tree of Firefox (mozilla-central)
    WEBRTCPATH environment variable pointing to a built webrtc source trunk

  To Run the build
    'python runSconsBuild.py debug' or
    'python runSconsBuild.py clean'
    Current command line options are 'debug', 'release', 'clean', 'noaddon' and 'x64'.

-------------------
4. Output from build
-------------------
  The build will create a test application and a Firefox addon for the nightly build.
  Test App binary: TestApp_Softphone
  Addon: ikran-0.2-dev.xpi

----------------------------
5. Testing the Firefox addon
----------------------------
  To test the addon follow these steps

  - The addon executable will be generated under <SOURCE>/ikran
 	 called ikran-0.2-dev.xpi
  - OSX 
	Start Firefox in 32 bit as 
		arch -i386 /Applications/Firefox.app/Contents/MacOS/firefox-bin 
  - Linux (32 bit and 64 bit)
	Connect your camera and make sure it works :)
	Start Firefox normally  
  - Install the addon
  - Test add-on with sample page at
		<SOURCE>/ikran/content/ikran.html		

  NOTES:
  1. ikran.html should be served from a server due to permission issues.
  2. If your cameras are working you should see a 2 way video call, ikran to ikran.
  3. You should be able to call any softphone or hardphone connected to CUCM, Asterisk or Kamailio.

-----------------------------
6. Using the Test Application
-----------------------------
  Use the command line test application to exercise the SIP stack.
  The test application can be used against Cisco Call Manager, Asterisk and Kamailio (OpenSER).
  The test application requires the nspr4 library in your dynamic library path.  It is 
  easiest just to copy libnspr4.dylib/.so/.dll into the testapp directory from mozilla-central.

  Run the Test Application from the command line with no parameters
   ./tests/testapp_softphone/TestApp_SoftPhone

   ********************************
   Please Choose One :
         0. Quit
         1. Register User
         2. Place Call
         3. Answer Call
         4. End Call
	 5. Start P2P mode
	 6. Place P2P Call
   What Action do you want to perform Monsieur ??

   Select 1 to register, enter the following details, inside square brackets are defaults.

      Enter SIP Server IP Address [ 10.53.47.140 ]:
      Enter SIP Server username (phone DN for CUCM) [ 9995 ]:
      Enter Password (not required for CUCM [ Enter ]:
      Enter device name (only required for CUCM) [ emannionsip01 ]:

   Select 5 to start ikran in Peer to Peer mode.  This requires only the SIP username to start.

      Enter local peer username (usually a phone DN) [ 9995 ]:

   To make a P2P call select option 6, this will require remote SIP username and remote IP Address.

 When running the Test Application in Linux it operates slightly differently. To see the available
 list of commangs use the '?' key.
 
------------
7. Addon API
------------
The JS API offers support for 
    SIP Registration, Place Call, HangUp Call, Answer Call, Send DTMF
    HoldCall, ResumeCall, Mute, UnMute,
    P2P Mode, Place P2P Call
    SetProperty, GetProperty

window.navigator.service.call obtains handle to session-control object.

<session-control>.registerUser(user_device, user, credential, sip-proxy, sessObserver);
registers user to the sip-proxy. 

'sessObserver' is a JS function that will be called whenever there is 
a change in the session state such as "no-registrar","registering",
"registered", "incoming-call" & "registration-failed".

On successful registration, one can place call with the below API
<session-control>.placeCall(dial-number, canvas, mediaObserver);
where dial-number is number to dial and mediaObserver reports 
significant media state changes such as "call-connected",
"call-terminated" as of today.

JS APIs unRegisterUser() and hangupCall() allows de-registration
& end-call functionalities.

SendDigits API
To Send DTMF digits use sendDigits, a call must be active to send DTMF digits.
sendDigits('123#');

SetProperty API
Available properties are
localvoipport -- used in P2P mode
remotevoipport -- used in P2P mode
e.g.  Me.setProperty({"localvoipport": 5061, "remotevoipport": 5061});

GetProperty API
e.g.  var version = Me.getProperty("version");

Few Points to Note
1. One user is suported as registered by instance
 
Please see content/ikran.html for sample usage of the API.

----------------------------------
8. Configuring Asterisk SIP Server
----------------------------------

1. Create a SIP user in /etc/asterisk/sip.conf

  [bob]
  type=friend
  defaultuser=bob
  secret=1234
  host=dynamic
  context=ikran

2. Create a phone extension in /etc/asterisk/extensions.conf

  [ikran]
  extn => 1234,1,Dial(SIP/bob)
  
3. From the Asterisk CLI> sip reload  

---------------------------------
9. Configuring Kamailo SIP Server
---------------------------------
Here is a good reference: http://www.oldskoolphreak.com/tfiles/voip/beginners_openser.txt

1. Create two users

  kamctl add userbob bobpassword bob@localhost
  kamctl add useralice alicepassword alice@localhost

2. Start kamailio

  /usr/local/sbin$ ./kamailio

-----------------------------------
10. Using Ikran with the ROAP Proxy
-----------------------------------

1. The ROAP proxy should be run on a machine with apache and php

2. In /tests/roap you'll find roap.php which should be put on your apache server

3. roap.php forwards the ROAP requests to localhost by default, so on the same
machine run ./test/roap/RoapProxy

4. To follow the logs export these two environment variables:
export NSPR_LOG_FILE=/home/wherever/yourlogfile.log
export NSPR_LOG_MODULES=ikran:5
You can then tail -f the log file to watch the RoapProxy.  It should give a couple
'bind succeeded' messages on startup.

5. Put roap_client.html on your apache server and point your Nightly build with Ikran to it.

6. On page load you should see the RoapProxy register and then it will do the SIP conversation
on behalf of your browser.  It currently only works for 1 call and needs to be reset between
each call.

----------------------------------------
11. Using SoftphoneTestCases Application
----------------------------------------
Use the command line test application to verify the SIP stack and softphone APIs.
The test application can be used against Cisco Call Manager and Kamailio (OpenSER).
The test application requires the nspr4 library in your dynamic library path. It is easiest 
just to copy libnspr4.dylib/.so/.dll into the testapp directory from mozilla-central.

Below is the step-by-step for automatic test with the test application.

(1) Prepare server configure file "server.txt" and client configure file "client.txt", "valid.txt" 
and "invalid.txt". You may find examples in ./tests/SoftphoneTestCases/.

In these configure files:
IP_ADDRESS is IP address of SIP server.

DEVICENAME, SIPUSER and CREDENTIALS are user settings provided by SIP server. 
In invalid.txt, please set wrong DEVICENAME, SIPUSER and CREDENTIALS.

LOCALIP is IP address of the test machine on which the test application runs.

TESTSERVER is IP address of the server.

(2) Place server.txt into the same directory with the test application. Run the test 
application from the command line as below to start it as a server. 
    ./SoftphoneTestCases -s server.txt

(3) Enter "r" and press "enter" to register to SIP server.

(4) Place client.txt, valid.txt and invalid.txt into the same directory with the test 
application. Run the test application from the command line as below to start is as a client.
    ./SoftphoneTestCases -c client.txt

Notes:
(1) Server and client on the same machine may have some problems.

--------------------
12. Installing Scons
--------------------

Make sure pyhton is installed

Linux
'sudo apt-get install scons' or 'sudo yum install scons'

Mac
From http://www.scons.org/  download the tarball, untar and do this
python setup.py install

Windows
From http://www.scons.org/ download and install the scons windows installer 
 
 ---------------------------------------------------
13. Using Ikran with websocket-based ROAP Proxy
---------------------------------------------------

1. Start the roap proxy firstly.

2. Start firefox with ikran add-on. Enter IP:7681 in address bar to load page. the IP is roap proxy ip.

3. On page load you should see the RoapProxy register and then it will do the SIP conversation
on behalf of your browser.  It currently only works for 1 call and needs to be reset between
each call.