Freitag, 25. April 2008

Using the Asterisk Voip PBX as SIP Mediaserver

Here I show how the open source Voip PBX Asterisk can be used as a simple mediaserver for Sip applications.

Prerequisites

  • I use the AsteriskNOW software appliance which is prepackaged ready-to-run version of Asterisk. It can be downloaded from http://www.asterisknow.org/downloads . There is a very good documentation avaliable as PDF download from Asterisk Book Download .
  • Asterisk is running on Linux only, so in order to run it on Windows or other OS you need a virtual machine environment e.g. VMware. The download from AsteriskNOW is an ISO image, to run it on VMWare you need VMWare Server which you can get for free from http://www.vmware.com/download/server/ . Alternatively you can use VMware Player and run an Asterisk Virtual Appliance which you can get from the VMware virtual appliance directory at http://www.vmware.com/appliances/ .
  • I prefer to run it from VMware Server. To install it create a new virtual machine, insert a CD made from the ISO image or mount the image directly and follow the instructions of the graphic installer. There is quickstart guide available at http://www.asterisknow.org/support/install .
  • Asterisk provides a Web based administration, but for our usecases it is required to have direct access to the Asterisk console. Use an ssh client (e.g. Putty from http://www.chiark.greenend.org.uk/~sgtatham/putty/ ) to connect to the Asterisk server.

Configuration

  • Connect to Asterisk using the ssh client and login (default user is admin and password is password). Configuration of Asterisk is done by editing various configuration files. When you edit the configuration files you must give yourself the access rights with sudo, e.g sudo vi sip.conf.
  • The sip configuration file is sip.conf in /etc/asterisk. Rename the file from the installation (it is very complicated and contains lots of examples) and create a new sip.conf as follows:

    [general]
    context=default
    allowoverlap=no
    bindport=5060
    bindaddr=0.0.0.0
    srvlookup=yes
    [sailfin]
    type=peer
    context=from-fwd
    host=192.168.0.12
    insecure=port

    The configuration is done by declaring contexts, in our case the sailfin context, type=peer means that this context can only receive calls.The host address has to be replaced with the ip address of the sailfin server (yes the sailfin server since it is the peer, not the Asterisk server). Detailed explanation about contents can be found in the Asterisk book.
  • The next configuration file is extensions.conf, which contains the dialplan. Rename the file and create a new one like for sip.conf. A dialplan tells Asterisk what to do when a call is received. In our example we are using a very simple dialplan which tells Asterisk to play an announcement when a callis received on a certain extension.

    [from-fwd]
    exten => 1234,1,Answer()
    exten => 1234,2,Playback(to-reach-operator)
    exten => 1234,3,Hangup()


    When a call is received for the context from-fwd with the extension 1234 the call is answered, then an announcement is played and the call is finished. Announcement are defined as .wav files with a full path, if no path is specified the default directory /var/lib/asterisk/sounds is used.
  • To activate the context type sip reload from the console (the console can be reached from the Asterisk main menu with ALT-F9). There are many other sip related console commands, they are explained in detail in the Asterisk book in appendix E.
  • The log files for sip can be found in /var/log/asterisk in file full, errors are in file messages.
  • When you now make a sip call to Asterisk (sip:1234@192.168.0.12 in our example) Asterisk answers the call with 200 OK, then receives an ACK, plays the announcement and ends the call with BYE when the announcement is finished.

Next Steps

The usecase described here is an extremely simple one, Asterisk can do much more than that, e.g. it can act as

  • IVR with voice menus reacting on keypresses and event database access.
  • Voice mail server
  • Call recording server

I will try to explore these possibilities and explain in a future post.

Donnerstag, 24. April 2008

Hunting Sample App using ECharts

In this example I show how to build a more complex sample using the ECharts state machine language. Details about ECharts can be found in http://echarts.org/ and also in one my previous posts in screening sample app with ECharts . The sources for the sample are available in cvs using cvs -d:pserver:[your java.net account]@cvs.dev.java.net:/cvs co sailfin/sailfin-tests and then can be found then in community/samples/hunting, or send an email to me to get them.

It provides the functionality to define a list of alternative Sip URI's in a database which are tried in sequence to connect when a call is received until a successful connection is established.

  • The application is triggered only in terminating case via the ECharts application router if the To address matches the specfied pattern in the app router.
  • It then connects the call to a mediaserver (MRF) which plays a dialtone or other announcement to the caller.
  • When the dialtone is established it sends a INVITE to the original called party of the call.
  • When the called party answers with 200 OK it disconnects from the mediaserver and reconnects via REINVITE to the caller. How to setup a mediaserver I will show in a future blog entry.
  • If the called party returns a 486 BUSY or 487 NOT REACHABLE it retrieves the next alternative Sip URI from the database and sends INVITE again.
  • If no alternative called party is available it stops the dialtone and signals a failure to the caller.

Sip Callflow for Redirect on Busy

The following callflow shows a scenario where the B Party is busy and the call is forwarded to C-Party.

A-Party......Sailfin......B-Party......MRF......C-Party

-INVITE SDPa->.....................................
.............-INVITE-------------------->..........
.............<-200 OK SDPm---------------..........
<-200 OK SDPm-.....................................
-ACK--------->.....................................
.............-ACK----------------------->..........
.............-INVITE SDPa--->......................
.............<-486 BUSY------......................
.............-ACK----------->......................
.............-INVITE SDPa------------------------->
.............<-200 OK SDPc-------------------------
.............-BYE----------------------->..........
<-200 OK SDPc-.....................................
.............<-200 OK--------------------..........
-ACK--------->.....................................
.............-ACK--------------------------------->
..................t a l k i n g....................
-BYE--------->.....................................
.............-BYE--------------------------------->
.............<-200 OK------------------------------
<-200 OK------.....................................


State Machines

A graphical description of the state machines can be found in the downloaded sources in hunting/src/echarts/hunting/ech/doc-files

  • The MainFSM machine connects to the MRF to play the dialtone using the ConnectFSM machine. When the dialtone is established it transitions to the HuntingFSM which performs the search and connect for the called party. Finally when the call is successfully established it transitions to the TransparentFSM which handles the talking state of the call and also the turndown at the end.
  • The HuntingFSM runs three paralles states.
    The PLAY_DIALTONE state uses the TransparentFSM and monitors the connection to the MRF.
    The CALL state uses the CallFSM to make a connection the called party until it has a successful connection.
    The REINVITE state uses the ReinviteFSM to handle the reinvite to the caller after a successful connection to the B-Party has been established.
  • The ConnectFSM machine handles the conenction to the MRF.
  • The CallFSM handles connect attempts to the B-Party.
  • The SendReinviteFSM handles the reinvite to the caller.
  • The TransparentFSM handles the talking state and turndown together with the TransparentHandleRequestFSM.