Asterisk Client (chan woomera) - User's Guide

From ProjectDiaStar

The instructions here assume that you have downloaded, built, installed and configured Asterisk, chan_woomera (see Asterisk Client (chan woomera) - Download, Build and Install) and the DiaStar™ Server (see Project DiaStar™ Server - Download, Build and Install) and that you are able to make and receive calls to and from the PSTN.

Contents 1 Inbound Calls 2 Outbound Calls 2.1 Dial Parameters 2.2 Profiles 2.3 Call Progress Analysis (CPA) 2.4 Channel Groups 3 Sample Files

Inbound Calls

Calls inbound from the PSTN, through the DiaStar™ Server to Asterisk 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=dialogic

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

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

Outbound Calls

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/default/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/isdn: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

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

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.

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

Finally, 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()