Asterisk Client - User's Guide V2.2

From ProjectDiaStar

The instructions here assume that you have downloaded, built, installed and configured Asterisk, chan_woomera (see Asterisk Client - Download, Build and Install) and the DiaStar™ Server (see Project DiaStar Server - Download, Build and Install V2.0) 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 Applications 3.1 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

Inbound Calls

Inbound PSTN or IP/SIP calls through the DiaStar Server delivered to Asterisk 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 diastar.conf file:

 context=diastar

and is handled in the corresponding context in the Asterisk dialplan in /etc/asterisk/extensions.conf:

 [diastar]
 ; Context for inbound Woomera server calls
 exten => _X.,1,Answer
 exten => _X.,n,Verbose(File being played - name is demo-echotest)
 exten => _X.,n,Playback(demo-echotest) 
 exten => _X.,n,Hangup()

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 Asterisk Dial command.

 Dial(WOOMERA/isdn:12345678)
 Dial(WOOMERA/sip:12345678)
 Dial(WOOMERA/ss7:12345678)
 Dial(WOOMERA/conf:1)

Dial Parameters

Parameters to the Asterisk Dial 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:

 Dial(WOOMERA/isdn:12345678/cpa=yes:group=default)

A second example shows an Asterisk .call script, used to invoke an outbound call when created and moved into /var/spool/asterisk/outgoing:

 Channel: WOOMERA/ss7:8005550201/group=outgroup1
 MaxRetries: 0
 Context: outdialandplay
 Extension: 1
 Priority: 1

And an example using the Asterisk "originate" command from the CLI:

CLI> originate WOOMERA/isdn:8005550008/cpa=yes:group=outgroup1 extension 1@cpacontext

Profiles

In deployments where Asterisk has access to multiple DiaStar™ Servers, the profile is used to specify which DiaStar™ Server the call will be placed on. The profiles are configured in the file /etc/asterisk/woomera.conf and as standard there is a single 'default' profile. More information on configuring profiles can be found here.

An example that uses the 'server1' profile:

 Dial(WOOMERA/server1/isdn:12345678)

And the 'default' profile:

 Dial(WOOMERA/default/isdn:12345678)

If no profile is specified then the 'default' profile is used:

 Dial(WOOMERA/isdn:12345678)

Call Progress Analysis (CPA)

CPA can be enabled on a call by call basis.

To switch on CPA:

 Dial(WOOMERA/isdn:12345678/cpa=yes)

To switch off CPA:

 Dial(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. In addition an AMI event is generated, e.g.

Event: CPA-Result
Privilege: system,all
ChannelDriver: WOOMERA
Channel: WOOMERA/sip:300@192.168.195.204/cpa=yes-6e30
CallerIDName: tone-test-with-cpa
Uniqueid: 1258371694.10
Result: busy-tone

Valid results are:

• answer-machine
• voice
• fax
• unknown
• operator-intercept
• busy-tone
• or the name of a custom tone

A macro may be used to retrieve the connection type when the call connects:

 exten => 1000,n,Dial(WOOMERA/default/isdn:8005551212/cpa=yes|60|M(dialcomplete))

 [macro-dialcomplete]
 exten => s,1,Verbose(${CONNECTIONTYPE})

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 Asterisk 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:

 Dial(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.

Applications

The Woomera channel driver adds new applications to Asterisk, which enable the dial-plan developer to access the extra functionality provided by DiaStar.

The following applications are available for SIP and conference calls.

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

• WoomeraBackground(audio_file_name, video_file_name[, overlay_info]) - multimedia play from the audio and video files specified and optional overlay generation information. Play is done in the background and control flow continues to the next dialplan command. This command is usually followed by the WaitExten() command to allow interruption from and collection of a DTMF tone. (This is analogous to the Asterisk audio Background() command)

• WoomeraRecord(audio_file_name, video_file_name [,max_time]) - multimedia record into the audio/video file pair specified. A DTMF # tone will terminate the recording. (This is analogous to the Asterisk audio Record() command)

• WoomeraStop - stop an active WoomeraBackground or WoomeraRingback.

The following applications are available for the SIP calls only.

• 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.

The following applications are available for use with ISDN/SS7 and SIP calls.

• WoomeraWaitForTone(timeout_in_seconds) - Wait for a custom tone or a DTMF digit to be detected. The result is returned in the channel variable WOOMERATONESTATUS, this will be set to one of the following: the name of the tone, the DTMF digit or the text value 'timeout' (without the quotes). If a time out of 0 is specified, tone detection will run in background and the application will return immediately, in this case the standard Asterisk WaitExten() application may be used to wait for both digits and tones, with tone events causing a jump to the 'u' extension of the current context.

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

Here is a simple non-interruptible multimedia playback example, specifying both audio and video files. Note that the file names do not include the file extension, this is because DiaStar will choose the best format that is available for the call's media.

[globals]
; Location of media files relative to the DiaStar server's media directory.
MEDIA_DIR = testservice

[start_service]
exten => s,1,Answer
exten => s,n,WoomeraPlayback(${MEDIA_DIR}/service_intro,${MEDIA_DIR}/service_intro)

Here is an example of a video menu. In this case the multimedia play is done in the background, and the dial plan falls through to the WaitExten() command for a choice to be entered via DTMF. Menu choices are: "1" - go to the next video, "2" - repeat the same one, and timeout/invalid choice - repeat the same one:

[main_menu]
exten => s,n,WoomeraBackground(${MEDIA_DIR}/repeatwaitnext,${MEDIA_DIR}/repeatwaitnext)
exten => s,n,WaitExten(300)
exten => 1,1,Goto(next_video,s,1)
exten => 2,1,Goto(previous_video,s,1)
exten => 3,1,WaitExten(300)
exten => t,1,Goto(main_menu,s,1)
exten => i,1,Goto(main_menu,s,1)

This example shows how to record a video clip:

[record_voicemail]
exten => s,n,WoomeraRecord(${MEDIA_DIR}/vmail_recordings/${USERNAME},
                           ${MEDIA_DIR}/vmail_recordings/${USERNAME})

Example showing WoomeraWaitForTone:

; Entry point for test calls via Woomera.
;
[woomera-inbound]

; Calling into this extension creates a new outbound SIP call with CPA which 
; routes back, via Asterisk's native SIP channel, into the dummy answer machine 
; extension shown below. Once the outbound call connects, the Dial() application
; jumps to the connected context.
;
exten => 100,1,Set(CALLERID(name)=wait-for-tone-test)
exten => 100,n,Set(_PARENT=${CHANNEL})
exten => 100,n,Dial(WOOMERA/sip:101@127.0.0.1/cpa=yes,30,G(connected,s,1))

[connected]
exten => s,1,Goto(caller,s,1)
exten => s,2,Goto(callee,s,1)

; Answer the original inbound (stimulus) call.
;
[caller]
exten => s,1,Answer
exten => t,1,NoOp
exten => h,1,Hangup

; Wait for a tone then connect the inbound and outbound call legs together.
; A real app would act upon the values of the CONNECTIONTYPE and WOOMERATONESTATUS
; channel variables.
;
[callee]
exten => s,1,NoOp(${CONNECTIONTYPE})
exten => s,n,WoomeraWaitForTone(10)
exten => s,n,NoOp(${WOOMERATONESTATUS})
exten => s,n,Bridge(${PARENT})
exten => s,n,Hangup
exten => t,1,NoOp
exten => h,1,Hangup


[sip-inbound]
; Test target dummy answer machine with end of message beep.
;
exten => 101,1,Answer
exten => 101,n,Playback(test/hello)
exten => 101,n,Wait(3)
exten => 101,n,Playback(test/1kHz)

Video Conferencing

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

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

Any call in Asterisk 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 Asterisk.

To Join a video conference the Asterisk dialplan Dial() command 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.

Dial(Woomera/conf:confnum,timeout)
Dial(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.

exten=>s,n,Dial(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.

exten=>s,n,Dial(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>

This can be overridden in the Asterisk dialplan by setting the following channel variables

${CALLERID(name)}
${CALLERID(num)}

If both variables are set the name takes preference.

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.

exten=>s,n,Dial(WOOMERA/conf:1/role=presenter:tiles=0,30)
exten=>s,n,Dial(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 dialplan, 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 by passing the 'G'
; option to the Dial() application. 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.
;
; Entry points:
;
;    Controller    controlled_conf,1,1
;    Presenter(s)  controlled_conf,2,1
;    Attendee(s)   controlled_conf,3,1
;
;-------------------------------------------------------------------------------
;

exten => _60[123],1,Goto(controlled_conf,${EXTEN:2},1)

[controlled_conf]
;
; The conference controller dials into here.
; Setting the number of tiles to 0, overrides the configuration and allows for
; the number of tiles shown to grow and shrink dynamically along with the number 
; of presenters.
;
exten => 1,1,Answer
exten => 1,n,Set(_PARENT=${CHANNEL})
exten => 1,n,Dial(WOOMERA/${WOOMERA_PROFILE}/conf:1/role=controller:tiles=9,30,G(cc_connected,s,1))
exten => 1,n,Hangup

; Presenters dial into here. These are full members of the conference whose
; media are included in the output.
;
exten => 2,1,Answer
exten => 2,n,Dial(WOOMERA/${WOOMERA_PROFILE}/conf:1/role=presenter,30)
exten => 2,n,Hangup

; Attendees dial into here. These are passive observers of the conference whose
; own media are not included in the output.
;
exten => 3,1,Answer
exten => 3,n,Dial(WOOMERA/${WOOMERA_PROFILE}/conf:1/role=attendee,30)
exten => 3,n,Hangup

; Invalid number.
exten => i,1,Hangup

; When the conference controller call connects to the conference, the Dial()
; application jumps to the context.
;
[cc_connected]
exten => s,1,Goto(cc_caller,s,1)
exten => s,2,Goto(cc_callee,s,1)

; Answer the original inbound call.
;
[cc_caller]
exten => s,1,Answer
exten => t,1,NoOp
exten => h,1,Hangup

; The controllers own video stream can be shown instead of the image file by
; removing the WoomeraBackround() application.
;
[cc_callee]
exten => s,1,Set(CHANNEL(language)=en_US)
exten => s,n,WoomeraBackground(,conference_demo/diastar-video-conf)
exten => s,n,Bridge(${PARENT})
exten => s,n,Hangup
exten => t,1,NoOp
exten => h,1,Hangup

;-------------------------------------------------------------------------------

Sample Files

Here are some sample configuration files for use with Asterisk.

First, several Asterisk ".call" scripts. When created and moved into /var/spool/asterisk/outgoing, the outbound call specified in the script is triggered. This script uses the outbound call group "outgroup1". The group is described in the DiaStar™ configuration file given in the --conf option. On answer, the context "basicgwfuncplay" is executed:

Channel: WOOMERA/isdn:8005550003/group=outgroup1
MaxRetries: 0
Context: basicgwfuncplay
Extension: 1
Priority: 1

Here, Call Progress Analysis is enabled and ANI is set in the CallerID field of the script. On answer, the context "basicgwfuncrecord" is executed:

Channel: WOOMERA/isdn:8005550009/cpa=yes
CallerID: 0123456789
MaxRetries: 0
Context: basicgwfuncrecord
Extension: 1
Priority: 1

Useful for testing, this shell script that will automatically create and move .call files to the outgoing directory to produce a steady stream of outbound calls:

#!/bin/sh
# vim:ts=4:set nu:
#
# 15-JUN-2009 John Tarlton
#
# Generate dot call files with sequential numbers based a template file test.call
# The sequence number is appended to the dialed number and is used as the base 
# file name.
# The resulting file is moved to the Asterisk spool directory.
#
# Usage: callgen [-r CALLS-PER-SECOND] [-t TOTAL-CALLS]
#

#
# Call template file and the string which will be replaced with the sequence number.
#
TEMPLATE=test.call
REPLACE=1212

#
# Where to put the files.
#
SPOOL=/var/spool/asterisk/outgoing

#
# Total number of call to generate
#
MAXCALLS=240

#
# Base of sequence
#
BEGIN=1000

#
# Calls per second
#
RATE=1

#
# Command line options
#
while [ $# -gt 0 ]
do
	case $1
	in
	-r)
		RATE=$2
		shift 2
	;;


	-t)
		MAXCALLS=$2
		shift 2
	;;

	-h)
		echo "Options:"
		echo "  -r  Call rate. number of call files generated each second ($RATE)"
		echo "  -t  The total number of call files to generate ($MAXCALLS)"
		exit 0
	;;
    
	*)
		echo "Unknown option: $1. Use -h for help"
      		exit 1
	;;
	esac
done


echo "Generating $MAXCALLS calls at $RATE cps"

#
# Create the files and move to the spool directory
#
total=0

while [ $total -lt $MAXCALLS ] 
do
	second=`date +%s`

	first=$(($BEGIN + $total))
	last=$(($first + $RATE - 1))

	for n in `seq $first $last` 
	do 
		cat $TEMPLATE | sed "s/$REPLACE/$n/" > "$n.call"
		mv "$n.call" $SPOOL
		total=$(($total + 1))
		echo -ne "\r$total"
	done
	
	while [ $second -eq `date +%s` ]
	do
		usleep 100000
	done
	
done

echo -e "\rDone!\n"

# END

Here is an Asterisk dialplan file that exercises many of the features supported by the DiaStar™ Server:

;
; This is a sample Asterisk dialplan that uses many or the
; features supported by the Woomera server.
;
; The are organized into separate contexts.  For inbound calls,
; the DNIS is used to branch to a given context.

[basicgwanidnis]
; Make sure ANI/DNIS are received
exten => s,1,Verbose(ANI is ${CALLERID(ani)})
exten => s,n,Verbose(DNIS/DNID is ${CALLERID(dnid)})

[basicgwdtmfrec]
; DTMF recognition test
exten => s,1,Set(TIMEOUT(digit)=3)
exten => s,n,WaitExten
exten => 1,1,Verbose(DTMF 1 detected)
exten => 1,n,Hangup()
exten => 2,1,Verbose(DTMF 2 detected)
exten => 2,n,Hangup()
exten => 3,1,Verbose(DTMF 3 detected)
exten => 3,n,Hangup()
exten => 4,1,Verbose(DTMF 4 detected)
exten => 4,n,Hangup()
exten => 5,1,Verbose(DTMF 5 detected)
exten => 5,n,Hangup()
exten => 6,1,Verbose(DTMF 6 detected)
exten => 6,n,Hangup()
exten => 7,1,Verbose(DTMF 7 detected)
exten => 7,n,Hangup()
exten => 8,1,Verbose(DTMF 8 detected)
exten => 8,n,Hangup()
exten => 9,1,Verbose(DTMF 9 detected)
exten => 9,n,Hangup()
exten => 0,1,Verbose(DTMF 0 detected)
exten => 0,n,Hangup()
exten => *,1,Verbose(DTMF * detected)
exten => *,n,Hangup()
exten => #,1,Verbose(DTMF # detected)
exten => #,n,Hangup()

exten => t,1,Verbose(DTMF digit NOT detected before timeout expired)
exten => t,n,Hangup()

[basicgwfuncrecord]
; Record a uniquely name file.  Note that without the "k" option, (Asterisk 1.6) the recording 
; will be deleted when the call is dropped
exten => s,1,Verbose(File being recorded - name is astrec_${UNIQUEID:11})
exten => s,n,Record(/etc/asterisk/recordings/astrec_${UNIQUEID:11}:vox,0,0) ; open-ended record
exten => s,n,Hangup()

[basicgwfuncplay]
; Play a file.  Other side records, to a set number of seconds.  If the record
; duration is less than the length of the file played on this side, it
; may appear truncated
exten => s,1,Verbose(File being played - name is demo-echotest)
exten => s,n,Playback(demo-echotest) 
exten => s,n,Hangup()

[basicgwfuncdtmfgen]
; Generate a DTMF tone. Other side detects the tone
exten => s,1,Verbose(Generating DTMF tones 0-9,#,*)
exten => s,n,Wait(1)
exten => s,n,SendDTMF(1)
exten => s,n,SendDTMF(2)
exten => s,n,SendDTMF(3)
exten => s,n,SendDTMF(4)
exten => s,n,SendDTMF(5)
exten => s,n,SendDTMF(6)
exten => s,n,SendDTMF(7)
exten => s,n,SendDTMF(8)
exten => s,n,SendDTMF(9)
exten => s,n,SendDTMF(0)
exten => s,n,SendDTMF(#)
exten => s,n,SendDTMF(*)
exten => s,n,Wait(1)
exten => s,n,Hangup()

[basicgwfunclatency]
exten => s,1,Echo
exten => s,n,Hangup()

[basicgwfunccpa]
exten => s,1,Verbose(Call Progress Analysis test - result is ${CONNECTIONTYPE})
exten => s,n,Wait(4)
exten => s,n,Hangup()

[cpatestout]
exten => s,1,Verbose(Entering CPA test on outbound call)
exten => s,n,Verbose(Call Progress Analysis test - result is ${CONNECTIONTYPE})
exten => s,n,Wait(5)
exten => s,n,Hangup()

[cpatestin]
exten => s,1,Playback(demo-echotest) 
exten => s,n,Wait(5)
exten => s,n,Hangup()

[donothing]
exten => s,1,Verbose(Just waiting a little and hanging up...)
exten => s,n,Wait(3)
exten => s,n,Hangup()


[dialogic]
; Context for inbound Woomera HMP server calls.  This is set
; in wooomera.conf
;
; Answer for all test extensions, then branch to test acc'd
; to DNIS
exten => _800555XXXX,1,Answer

; Functional gateway tests first
exten => 8005550001,2,Goto(basicgwanidnis,s,1)
exten => 8005550002,2,Goto(basicgwdtmfrec,s,1)
exten => 8005550003,2,Goto(basicgwfuncrecord,s,1)
exten => 8005550004,2,Goto(basicgwfuncplay,s,1)
exten => 8005550005,2,Goto(basicgwfunclatency,s,1)
exten => 8005550006,2,Goto(basicgwfuncdtmfgen,s,1)
exten => 8005550007,2,Goto(basicgwfunccpa,s,1)
exten => 8005550008,2,Goto(cpatestin,s,1)
exten => 8005550009,2,Goto(donothing,s,1)

; Load tests - use functional test dialplan entries
exten => 8005550200,2,Goto(basicgwfuncrecord,s,1)
exten => 8005550201,2,Goto(basicgwfuncplay,s,1)

exten => _800555XXXX,n,Hangup()

Finally, there are several multimedia demos that contain dialplans in DiaStar's SVN server.