FreeSWITCH/Woomera User Guide

From ProjectDiaStar

The instructions here assume that you have downloaded, built, installed and configured FreeSWITCH and mod_woomera and that you are able to make and receive PSTN (ISDN or SS7) or IP (SIP) calls.

Contents 1 Inbound Calls 2 Outbound Calls 2.1 Technologies 2.2 Dial Parameters 2.3 Profiles 2.4 Call Progress Analysis (CPA) 2.5 Channel Groups 3 Multimedia 3.1 Commands 3.2 Examples 4 Video Conferencing 4.1 Tiles 4.2 Position 4.3 Role 4.4 Captions 4.5 Adhoc Conference 4.6 Controlled Conference 5 Sample Files 5.1 Verification Demo

Inbound Calls

Inbound PSTN or IP/SIP calls through the DiaStar Server delivered to FreeSWITCH via Woomera are handled in the same manner as inbound calls using any other technology. The context to which the call is delivered is set in the /usr/local/freeswitch/conf/autoload_configs/woomera.conf.xml file:

 <param name="context" value="diastar"/>

and is handled in the corresponding context in the FreeSWITCH dialplan e.g./usr/local/freeswitch/conf/dialplan/default.xml:

<include>
  <context name="diastar">
    <extension name="echo">
      <condition field="destination_number" expression="^9996$">
	<action application="answer"/>
	<action application="echo"/>
      </condition>
    </extension>
  </context>
</include>

Outbound Calls

Technologies

The DiaStar server supports the following technologies:

 isdn
 sip
 ss7
 conf

The technology used to make the outbound calls is specified as part of the FreeSWITCH Bridge command.

 <action application="bridge" data="WOOMERA/isdn:12345678"/>
 <action application="bridge" data="WOOMERA/sip:12345678"/>
 <action application="bridge" data="WOOMERA/ss7:12345678"/>
 <action application="bridge" data="WOOMERA/conf:1"/>
 

Dial Parameters

Parameters to the FreeSWITCH bridge command are used to access features of the DiaStar™ Server on a call by call basis.
These values are specified in the format feature=value and multiple Dial parameters can be specified using : as a separator.

Example:

 <action application="bridge" data="WOOMERA/isdn:12345678/cpa=yes:group=default"/>

Profiles

Profiles are not yet supported in mod_woomera.

Call Progress Analysis (CPA)

CPA can be enabled on a call by call basis.

To switch on CPA:

 <action application="bridge" data="WOOMERA/isdn:12345678/cpa=yes"/>

To switch off CPA:

 <action application="bridge" data="WOOMERA/isdn:12345678/cpa=no"/>

CPA is disabled if the "cpa" parameter is not specified. If CPA is used the result is contained in the $CONNECTIONTYPE variable when the Dial command completes.

Valid results are:

• answer-machine
• voice
• fax
• unknown
• operator-intercept
• busy-tone

CPA will also detect special-information-tones and busy-tone, when this occurs the call will be terminated and a hangup event will be sent to the FreeSWITCH server. The reason may be retrieved using the standard $HANGUPCAUSE dial plan variable.

CPA can also detect and report user defined tones. These are defined in dedicated configuration files, see: Project DiaStar™ Server - User's Guide

Channel Groups

While Profiles determine which DiaStar server an outbound call is placed from, a channel group is a way of dividing PSTN lines into outbound call groups within a server.

Note that call groups are used for PSTN calls (ISDN and SS7) only. SIP calls are usually made using a single virtual board and a single physical network interface.

Channel groups for outbound calls can be set in the [groups] section of the DiaStar Server configuration file:

 ; The following section is used to define groups of dti (isdn) devices.
 ; These groups are used when allocating a device for an outbound call.
 ; Each definition consists of the group's name followed by a comma separated 
 ; list of dti device numbers, which may include ranges defined using a hyphen
 ; e.g. pbxlines = 1,2,3,4,31-60
 
 [groups]
 outgroup1 = 1,2,3,4
 outgroup2 = 5-8

A call can be placed on a specified channel group:

 <action application="bridge" data="WOOMERA/isdn:12345678/group=outgroup2"/>

The highest channel number available in the group is chosen for an outbound call. Calls are placed on the highest available channel number if the "group" parameter is not specified.

Multimedia

Using the following multimedia commands allows applications like Interactive Voice and Video Response systems (IVVR) to be built using an FreeSWITCH dialplan.
The following multimedia commands are only supported on the DiaStar SIP interface.

Commands

• WoomeraPlayback - multimedia play from the audio/video file pair specified. Does not allow interruption from DTMF tones. (This is analogous to the FreeSWITCH audio Playback() command)

• WoomeraBackground - multimedia play from the audio/video file pair specified. Play is done in the background and control flow continues to the next dialplan command. This command is usually followed by the WoomeraWaitForTone command to allow interruption from and collection of a DTMF tone.

• WoomeraRecord - multimedia record into the audio/video file pair specified. A DTMF # tone will terminate the recording. (This is analogous to the FreeSWITCH audio Record() command)

• WoomeraRingback(audio_file_name, video_file_name) - pre-answer, multimedia ring-back, plays from the audio/video file pair specified. Play is done in the background and control flow continues to the next dialplan command. The play terminates automatically when the call is answered.

• WoomeraStop - stop an active WoomeraBackground or WoomeraRingback.

Files used for audio and video playback must be in a proprietary Dialogic multimedia format. Files recorded via DiaStar are are produced in the same format. See [1] for instructions on converting to/from this format.

Examples

 <action application="WoomeraPlayback" data="audio_file_name, video_file_name"/>
 <action application="WoomeraBackground" data="audio_file_name, video_file_name"/>
 <action application="WoomeraRecord" data="audio_file_name, video_file_name"/>
 <action application="WoomeraRingback" data="audio_file_name, video_file_name"/>
 <action application="WoomeraWaitForTone" data="100000"/>

Video Conferencing

DiaStar V2.1 supports multimedia conferencing with SIP calls. A list of features can be found here.

Conference management is handled by the FreeSWITCH Dialplan, while DiaStar Server simply provides the primitive conferencing functions.

Any call in FreeSWITCH may participate in a DiaStar conference, irrespective of its channel technology.
Calls enter a DiaStar conference using a new Woomera sub-protocol "conf". Once a call is active within a dialplan, it may dial into a conference:

This diagram shows 3 calls in a single conference. One call originates on the same DiaStar server as the conference. A second comes in through a second DiaStar server. Finally, the third call arrives via a non-DiaStar technology though FreeSWITCH.

To Join a video conference the FreeSWITCH dialplan application "bridge" is used. The Woomera technology name used must be 'conf'. The number of the conference to join must be given, followed by 0 or more optional parameters. Finally, a timeout (in seconds) should be give for returning if joining the conference fails.

E.g.

<action application="bridge" data="Woomera/conf:confnum,timeout"/>
<action application="bridge" data="Woomera/conf:confnum/param=value:param=value,timeout"/>

The following optional parameters can be used

• tiles
• position
• role

Tiles

Video output may be laid out as either 1,4,6 or 9 tiles.
If the 'tiles' parameter is not specified then the default layout specified in the DiaStar server configuration file is used.
Specifying a tile count of zero causes the number of tiles to grow and shrink depending on the number of visible parties.

<action application="bridge" data="WOOMERA/conf:1/tiles=0,30"/>

Position

When joining a conference a party may optionally specify which tile their video should appear on using the 'position' parameter.
If the tile is already occupied the new party will not be shown. If the 'position' parameter is not specified then the next available position is used.
Valid positions for each tile type are shown below.

<action application="bridge" data="WOOMERA/conf:1/position=2,30"/>

Role

The role is used to set the behaviour of the conference participant.
If the 'role' parameter is not specified the participant will be entered into the conference as a presenter.

• controller - Used in "Controlled" conferences only. Activates the conference and transmits/receives audio and video until the first presenter joins. While a presenter is in the conference the controller's video is not shown.
• presenter - A full participant whose media are included in the conference output.
• attendee - A watch & listen only participant. They receive the conference output but do not have their media included in it.

Captions

A caption for each conference participant can be shown based on the DiaStar server configuration.
The caption shown by default will be based on the 'SIP INVITE From:' field taken from the inbound call leg.

In the case below the caption displayed will be antony

From: Antony Martin <sip:antony@projectdiastar.org>

Adhoc Conference

An adhoc conference may be entered and exited at any time, by any participant.
The 'controller' role is not supported in an adhoc conference.

Example
A presenter and attendee joining conference #1, with a variable number of tiles and a dial timeout of 30 seconds.

<action application="bridge" data="WOOMERA/conf:1/role=presenter:tiles=0,30"/>
<action application="bridge" data="WOOMERA/conf:1/role=attendee,30"/>

Controlled Conference

Controlled conference behaviour:

• Only one controller per conference is allowed
• A controlled conference must have a controller call active before other callers will be admitted
• A non-controller participant take one of two other roles: presenter or attendee
• A controller party must be established in order for presenters and attendees to be admitted to the conference
• The controllers video is shown only when no presenters are present. This allows the controller to play a image/video to the attendees while they wait for the presenters to arrive. The controller's audio is always included in the mix and should be muted locally as necessary.
• When the controller call ends the conference itself ends and all other parties are automatically hung up

In the following example, the controller plays a static JPEG image to all 'participants' until a 'presenter' joins the conference.

<!--
; Controlled conference demo.
; Assumes that conference id 1 is configured with "mode = controlled" on DiaStar.
;
; The controller's connection in managed by the dialplan. Control is passed to 
; the script controller.js. This has been done to allow an image to be
; played to conference attendees at times when no presenters are connected. The
; controllers audio remains connected at all times and should be muted locally
; if necessary.
;-------------------------------------------------------------------------------
-->

<!--
; The conference controller dials into here.
-->
    <extension name="woomera-controlled-conf-controller">
      <condition field="destination_number" expression="^611$">
        <action application="javascript" data="controlled.js 1 controller" />
      </condition>
    </extension>
<!--
; Presenters dial into here. These are full members of the conference whose
; media are included in the output.
-->
    <extension name="woomera-controlled-conf-presenter">
      <condition field="destination_number" expression="^612$">
        <action application="javascript" data="controlled.js 1 presenter" />
      </condition>
    </extension>

<!--
; Attendees dial into here. These are passive observers of the conference whose
; own media are not included in the output.
-->
    <extension name="woomera-controlled-conf-attendee">
      <condition field="destination_number" expression="^613">
        <action application="javascript" data="controlled.js 1 attendee" />
      </condition>
    </extension>

The controller.js file used in the dialplan above should be located FreeSWITCH scripts folder '/usr/local/freeswitch/scripts'.

var room = argv[0];
var role = argv[1];

session.answer();

new_session = new Session('woomera/conf:' + room + '/role=' + role + ':tiles=0', session);
new_session.waitForAnswer(10000);

if (new_session.ready()) {
  new_session.sleep(1000);
  if (role == "controller")
  {
    new_session.execute("WoomeraBackground", ",conference_demo/diastar-video-conf");
  }
  bridge(session, new_session);
}

Sample Files

Here are some dialplan examples for FreeSWITCH.

Verification Demo

    <extension name="woomera-verification">
      <condition field="destination_number" expression="^8005551222$">
      </condition>

      <!-- ###### First Time in ###### -->
      <condition field="${ivrlevel}" expression="^$" break="never">
        <action application="set" data="file_loc=verification"/>
        <action application="set" data="domain_name=$${domain}"/>
        <action application="WoomeraPlayback" data="${file_loc}/greeting,${file_loc}/greeting"/>
        <action application="WoomeraBackground" data="${file_loc}/main_menu,${file_loc}/main_menu"/>
        <action application="WoomeraWaitForTone" data="100000"/>
        <action application="set" data="ivrlevel=2"/>
        <action application="set" data="ivrsel=${WOOMERATONESTATUS}"/>
        <action application="transfer" data="${destination_number}"/>
      </condition>

      <!-- ###### LEVEL 1 ###### -->
      <condition field="${ivrlevel}" expression="^1$" break="never">
        <action application="log" data="Level 1"/>
        <action application="WoomeraBackground" data="${file_loc}/main_menu,${file_loc}/main_menu"/>
        <action application="WoomeraWaitForTone" data="100000"/>
        <action application="set" data="ivrlevel=2"/>
        <action application="set" data="ivrsel=${WOOMERATONESTATUS}"/>
        <action application="transfer" data="${destination_number}"/>
      </condition>

      <!-- ###### LEVEL 2 ###### -->
      <!-- Option 1 Play Menu -->
      <condition field="${ivrlevel}-${ivrsel}" expression="^2-1$" break="never">
        <action application="WoomeraBackground" data="${file_loc}/play_menu,${file_loc}/play_menu"/>
        <action application="WoomeraWaitForTone" data="100000"/>
        <action application="set" data="ivrlevel=3"/>
        <action application="set" data="ivrsel=${WOOMERATONESTATUS}"/>
        <action application="transfer" data="${destination_number}"/>
      </condition>

      <!-- Option 2 Record Menu -->
      <condition field="${ivrlevel}-${ivrsel}" expression="^2-2$" break="never">
        <action application="WoomeraBackground" data="${file_loc}/record_intro,${file_loc}/record_intro"/>
        <action application="WoomeraWaitForTone" data="100000"/>
        <action application="set" data="ivrlevel=4"/>
        <action application="set" data="ivrsel=${WOOMERATONESTATUS}"/>
        <action application="transfer" data="${destination_number}"/>
      </condition>

      <!-- Option 3 Hangup -->
      <condition field="${ivrlevel}-${ivrsel}" expression="^2-3$" break="never">
        <action application="Hangup"/>
      </condition>

      <!-- ###### LEVEL 3 ###### -->
      <!-- Play Options -->
      <condition field="${ivrlevel}-${ivrsel}" expression="^3-1$" break="never">
        <action application="WoomeraPlayback" data="${file_loc}/video_clip_callcenter,${file_loc}/video_clip_callcenter"/>
        <action application="set" data="ivrlevel=1"/>
        <action application="transfer" data="${destination_number}"/>
      </condition>

      <condition field="${ivrlevel}-${ivrsel}" expression="^3-2$" break="never">
        <action application="WoomeraPlayback" data="${file_loc}/video_clip_nascar,${file_loc}/video_clip_nascar"/>
        <action application="set" data="ivrlevel=1"/>
        <action application="transfer" data="${destination_number}"/>
      </condition>

      <!-- ###### LEVEL 4 ###### -->
      <!-- Record Options -->
      <condition field="${ivrlevel}-${ivrsel}" expression="^4-1$" break="never">
        <action application="WoomeraRecord" data="${file_loc}/video_record,${file_loc}/video_record"/>
        <action application="WoomeraPlayback" data="${file_loc}/video_record,${file_loc}/video_record"/>
        <action application="set" data="ivrlevel=2"/>
        <action application="set" data="ivrsel=2"/>
        <action application="transfer" data="${destination_number}"/>
      </condition>

      <!-- ###### Catch All ###### -->
      <!-- * - Go back to main menu -->
      <condition field="${ivrsel}" expression="^\*$" break="never">
        <action application="set" data="ivrlevel=1"/>
        <action application="transfer" data="${destination_number}"/>
      </condition>

      <!-- Invalid digit -->
      <condition field="${ivrsel}" expression="^([0-9]|#)$" break="never">
        <action application="Hangup"/>
      </condition>

    </extension>