Quick Start Guide to IAX Telephone Interface

arserver (and the AudioRack and ARStudio user interfaces) now includes capabilities to interface with a VoIP (Voice Over Internet Protocol) telephone system using the IAX (inter-asterisk exchange) protocol.  IAX was developed as a simplified VoIP protocol for use in the Asterisk open source PBX (Public Branch Exchange) software system which is available for almost all modern computer operating systems and platforms.  In this document, I will explain how to set up both arserver and asterisk to create an "on-air" extension in your telephone system for putting callers on the air. 

With the release of ARSuite (version 2.7.6) a panel has been added to the ARStudio client to enable the telephone functions of arserver, so you do NOT need to set things up manually as outlined here.  You can now use the VoIP tab found in arserver settings in ARStudio preferences to set up VoIP functionality.  I am keeping the low-level set up instructions here for those of you who want to know what is going on "under the hood."

1. What it will do.

After everything is configured and running correctly, you will be able to transfer a phone call through your PBX from what ever extension the call is currently on to an extension assigned to arserver.  When after the call has been transfered, arserver will answer the call, set up a 'iax' player in it's mixer and start sending the default arserver output bus (Monitor Bus) back to the caller.  You can then statrt the player to put the caller on the air, change the output bus that is feed back to the caller or close the player, which will transfer the call out to another pre-specified extension in your PBX and close the player.  You can have multiple callers running through arserver at once.  Each feed to a caller has automatic mix-minus, which removed the incoming audio  from that caller (if any) from the feed being sent back to the caller.

There is also a special secondary extension that you can configure arserver to answer calls to which has special "control" abilities.  If a arserver answers a call to this extension, the callers will additionaly be able to use the telephone DTMF keys (touch tone pad) to cause arserver to execute programable commands such as fade to next, put on air now, stop automation, or any other control function.  It is advisable that you set up asterisk to password protect this extension if this feature is enabled.

2. arserver setup.

When arserver starts up, it will attempt to enable the iax features just after it loads the preferences file.  The preferences file contains all the user changeable settings and is usually found in a file called ars_prefs.conf, either in the users preferences folder, or in /etc/arserver if arserver is being run in server mode.  If arserver has never been run before by a user, there will be no ars_prefs.conf file.  This file is created after arserver is run by the 'saveset' command which save thee current arserver settings into this file for loading next time arserver is run.  Note that chaging a setting through the AudioRack GUI will automatically create/update this file.

All that being said, you have two options for setting up the iax feature - Directly edit the ars_prefs.conf file in a text editor or change the settings through the arserver command line.  The arserver command line is accessed by running arserver and telnet-ing into the arserver control port (port 9550 by default).  You will need to start or re-start arserver for most of the changes to take effect.  Alternatly, if you are using the arserver command line, you can enter the iaxinit command to reload the iax settings as long as no lines are currently in use.  If you are using the arserver command line, don't forget to enter the saveset command to save the settings into the ars_prefs.conf file for next time.

The following is a list of commands that you will need to add to the ars_prefs.conf file or enter into the arserver command line.

set iax_max_lines <integer>

Where integer is the maximum number of lines (callers) you want to allow arserver to have allow at once.  If you set this to 1, only one caller can be on the air at a time.  Set to zero to disable all iax functions.

set iax_port_number <port number>

Where port number is the UDP port arserver should listen to for in coming iax connections.  Set to zero to use the default iax port.

set iax_control_number <extension number>

Where extension number is the extension you want arserver to answer with control ability via the phone touch tone keys.  Set to zero to disable.

set iax_auto_xfr <extension number>

Where extension number is the extension in your PBX system you want arserver to transfer calls to when you unload/close a iax player with a caller still on the line.

set iax_reg_pw <password>

Optional setting for iax registeration. Where password is the password asterisk has associated with the above user id.  See asterisk configuration section for details.

set iax_reg_user <user id>

Optional setting for iax registeration. Where user id is the asterisk user id to register arserver as.  See asterisk configuration section for details.

set iax_reg_host <host ip address>

Optional setting for iax registeration. Where host ip address the ip address for the asterisk PBX computer to register with.

set iax_reg_refresh <seconds>

Optional setting for iax registeration. Where seconds specifies how often arserver should re-register with the asterisk server. 60 seconds is a common registration period.

set iax_reg_retry <seconds>

Optional setting for iax registeration. Where seconds specifies how often arserver  should try to reregister is it was unable to connect the asterisk server or registration failed.  300 would cause arserver to retry every five minutes.

NOTE:  The following settings do not require arserver to restart before taking effect 

set iax_def_bus <bus bits>

Where bus bits is an integer number representing the arserver output buses you want the player to play through: 1=Monitor, 2=Cue, 4=Main, 8=Alternate.  Sum the number of all the buses you want for the final number.  For example, to have the player play through Monitor and Main, set bus bits to 5, which is 1 + 4.

set iax_def_feed <output bus number>

Where output bus number is the arserver output bus number to send back to the caller. 0=Monitor, 1=Cue, 2=Main, 3=Alternate.

set iax_def_vol <volume factor>

Where volume factor is an floating point scalar number for the playback gain of the player.  For example, 1.0 is unity gain, 2.0 is +6 dB, 0.33 is -10 dB, etc.

set iax_dtmf_macro_<key> <command>

Where key is the single digit touch tone key and command is an arserver command to associate with that key.  Touch tone control from the caller will only work if the caller called in to the control extension number.  Note that the command can include [self] which will be converted into the callers player number when arserver goes to execute the command. Commands that except a UID will take -1 to mean the UID of the callers player.  You can use the config command to have arserver execute a complex series of commands from a file.  See arserver documentation for details.

examples:
set iax_dtmf_macro_1 play [self]
set iax_dtmf_macro_2 add -2 [self]
set iax_dtmf_macro_3 stop [self]
set iax_dtmf_macro_4 autoon
set iax_dtmf_macro_7 autolive
set iax_dtmf_macro_5 segnow
set iax_dtmf_macro_6 run
set iax_dtmf_macro_9 halt
set iax_dtmf_macro_0 config complex_dtmf.conf

If you are doing all your audio source mixing with arserver (all microphones, CD, and other external inputs are routed through arserver inputs), then you can ignore the following section.   It is likely that you will have an external mixer if you are using microphones and you do not have a computer audio interface that supports direct monitoring, other wise the 50 to 100 mS delay between the microphone and your headphones will drive you crazy!  If you are using an external mixer, then you will need a way to get the additional microphone audio back into arserver to eb included in the feed to callers.  Note that arserver can send audio back to a caller from any of it's output mixes, and will automatically min-minus the call from that audio.  However, this will not include audio that you mix after or external to  arserver.  To make the phone feed include external audio, you will need to send the audio from your external mixer back into arserver, making sure that this audio does NOT include the original audio material from the arserver output you are sending to the external mixer.  That can be done through a AUX-SEND on most mixers, or by creating a sub-mix for mixers that have more than one mix bus.  After you have this worked out, feed the sub-mix into a free audio input on the arserver computer, create a new arserver input definition with a bus assignment set to the bus arserver output bus you will be using as a phone feed -- the Monitor bus is the deafult.  Give the input definition a name like "ExtFeed" .
 
When run, arserver looks for a start up file in the Preferences folder of the user who is running it.  If it isn't found, it then goes to the default startup file in /usr/local/arserver.  It is best to leave the default startup file alone, making any changes to a copy of the file specific to a user account.  That being said, make a copy of the ars_startup.conf file, moving it to the Preferences folder of the user account you will be running arserver in if the files don'e already exist there.  For example /Users/SomeUsers/Library/Preferences/.  If you are running arserver in server mode, you can skip this step and just directly edit the file in the /etc/arserver/ directory.  To finish, edit the new ars_startup.conf file adding the following  three lines and save.

; set up external telephone feed
load 9 input:///ExtFeed
start 9

This will cause arserver to automatically load and start playing the ExtFeed input into the specified output bus, including it in the feed to callers, when arserver is started up.  It is loaded into player 9 so it will not show up in the AudioRack user interface since AudioRack only displayed the first eight players.  Also note that you can exclude this player from any defined outputs (such as your monitor speakers) by enabling the ExtFeed mix-minus from the list of inputs on the output settings for that particular output.

3. asterisk setup.

setting up asterisk to use arserver involves editing two asterisk configuration files: 

iax.conf		- Tells asterisk how to connect to an iax client and names it.
extensions.conf 	- Tells asterisk how to include a named client in a dial plan.

Check you particular asterisk installation for the locations of these files.

If f you know the ip address of the computer running arserver (as seen by the computer running astersik) and it does not change, you can use direct addressing in iax.conf file.  If asterisk and arserver are running on the same computer, this will always be true: the address 127.0.0.1, also called 'localhost' is a local loopback address for all ip traffic between processes with in the same computer.  In direct addressing mode, asterisk will connect to the iax client by ip address as directed by it's iax.conf file.  

Here are example lines to be added to the end of your iax.conf to make use of direct address mode:

[audiorack]
context=default
type=friend   
auth=md5
secret=<password here>
host=<ip address of arserver computer (i.e. 192.168.0.7)>
disallow=all  
allow=ulaw
allow=alaw
allow=linear
callerid="audiorack"

In this case, a client named audiorack is set up with host is set to ip address of the client arserver computer, secret should be the same as the arserver iax password property iax_reg_pw, and the arserver iax property  iax_reg_user should be set to match the client name "audiorack"  and the context is set to "default" here, but should be set to what ever asterisk dialing context contains the extension which arserver will transfer unloaded calls to (arserver iax property  iax_auto_xfr).  Leave the context set to "default" if you do not set the arserver iax_auto_xfr property.  Note that arserver currently supports the following audio formats: ulaw, alaw and 16 bit linear.

If the ip address of the computer running arserver could change, then you need to use iax registration in both the iax.conf file AND make sure you set the arserver iax  registration properties mentioned in section 2.  In this mode, the iax client (arserver) will periodically send a message to the asterisk server, notifying it of it's current address, that way asterisk can connect to it using the most recent address when a call needs to be routed it's way.

Here are example lines to be added to the end of your iax.conf to make use of registration mode:

[audiorack]
context= default
type=friend   
auth=md5
secret=<password here>
host=dynamic
disallow=all  
allow=ulaw
allow=alaw
allow=linear
callerid="audiorack"
qualify=600

In this case, host is set to dynamic and qualify is set to 600 seconds, meaning if registration is not received from the client in at least 600 seconds, assume the client is not on line.  As in the pervious example, context is set to "default" here, but should be set to what ever asterisk dialing context contains the extension which arserver will transfer unloaded calls to (arserver iax property  iax_auto_xfr).  the secret should be the same as the arserver iax password property iax_reg_pw, and the arserver iax property  iax_reg_user should be set to match the client name: "audiorack"   The arserver iax properties for iax_reg_host  should be set to the ip address of the computer that is running the asterisk server as seen from the arserver computer. Also set iax_reg_refresh to 60 seconds for the refresh period and iax_reg_retry something like 300 seconds.

Finally, to set up the dial plan to include arserver, you will need to edit the asterisk extensions.conf file.

Find the dial plan context you would like to add arserver dialing ability to.  For example, in my system I have two contexts: inside and outside.  The inside dial plan handles routing all calls that come from inside my asterisk system - calls that start from dialing other extensions in the system.  The outside dial plan handles all calls that come from my VoIP DID provider - calls that come from dialing one of my public phone numbers from an outside phone line.  I do not want outside callers to be able to reach arserver directly.  Instead, I want outside callers to call into my main telephone, where I will transfer them over to arserver.  So I put the arserver entry for extensions.conf in the [inside] dial plan area, so only inside extensions can call or transfer callers into arserver.

Here is an example entry added to extensions.conf some place after the [inside] line but before any other contexts are defined:

exten => 30,1,Dial(IAX2/audiorack/30,20,t)         ; Ring the interface, 20 seconds maximum, allow transfer
exten => 31,1,Dial(IAX2/audiorack/31,20,t)         ; Ring the interface, 20 seconds maximum, allow transfer

These lines will cause an inside phone to call audiorack when extension 30 is dialed.  And it will cause arserver's control extension to to be dialed when extension 31 is dialed.  Note the /31 in the above example tells asterisk pass along to the arserver that extension 31 was dialed.  I assume that arserver is set up such that the control extension is 31 in this example.  Also note that exten => 60,1,Dial(IAX2/audiorack/31,20,t)  would also work for making 60 dial the control extension.  If you put a dial entry in for arserver from an outside extension, I HIGHLY RECOMMEND you add a password, so outside callers can't hijack control of arserver!

And here is an example of a dial plan entry for extension 31 to first ask for a password (1234) then dial the arserver control extension.  This example could be placed in an dial context accessible from the outside since it has password protection. 

exten => 31,1,Authenticate(1234)
exten => 31,2,Dial(IAX2/audiorack/31,20,t)         ; Ring the interface, 20 seconds maximum, allow transfer

Finally, a note last note about security.  arserver will answer any iax call it receives, with out any authentication, and will allow any call received who dialed the control extension to have dtmf control ability over arserver.  Keeping this in mind, it would be a VERY GOOD IDEA to use a fire wall either on the arserver computer or on your network as a whole, to make sure that ONLY the computer running asterisk can connect to the arserver computer using the iax port number/protocol.  iax uses port number 5036, UDP protocol.

© 2006 Ethan Funk