Basic Test Configuration

From SpiceCSM

Contents 1 Document Goal 2 Existing infrastructure 2.1 Installing the TDM422 card 2.2 zaptel.conf 3 Installing FreeSWITCH 4 FreeSWITCH Configuration 4.1 openzap.conf 4.2 openzap.conf.xml 4.3 erlang_event.conf.xml 4.4 123456_erlang.xml 4.5 02_hard_phones.com.xml 4.6 modules.conf.xml 4.7 Running FreeSWITCH 5 Installing Erlang 5.1 From Source 5.2 From EPEL Repository 6 Installing Spice-Telephony 7 Base configuration 8 Test Cases 9 Debugging 10 Softphones

Document Goal

The idea of this document is to provide step by step instructions on how to install and use spice-telephony (s-t) and FreeSWITCH to handle inbound and outbound campaigns in a test environment.
Thank Andrew and Micah for your patience ;)

Rcpacheco 10:05, 26 April 2009 (UTC)

Todo 

• Installing Erlang 13RB
• Oubound campaigns
• Test Cases

Existing infrastructure

• A server named myserver.mydomain with Centos 5.3
• A TDM422 Digium Card properly installed. That card has 2 FXO and 2 FXS.
  That mean that we can connect two telephone lines and two regular phones.
  In our examples, those telephone lines will have the following fake DID number associated :
  • DID Customer1: (123) 456.7890
  • DID Customer2: (123) 456.7891
• SIP soft-phone(s). You can find some good candidates here.

Installing the TDM422 card

Follow this instructions on FreeSWITCH wiki, they are very complete.

Nevertheless, here are some important tips:

• Make sure that you have no static electricity; the cards are VERY delicate.
• Remember to connect the card properly to the power.

zaptel.conf

Path 

/etc/zaptel.conf

In my case this is the correct zaptel configuration:

# Autogenerated by /usr/sbin/genzaptelconf -- do not hand edit
# Zaptel Configuration File
#
# This file is parsed by the Zaptel Configurator, ztcfg
#

# It must be in the module loading order


# Span 1: WCTDM/0 "Wildcard TDM400P REV E/F Board 1" (MASTER) fxsks=1
fxsks=2
fxoks=3
fxoks=4

# Global data

loadzone        = us
defaultzone     = us

Installing FreeSWITCH

As expected, the FreeSWITCH Wiki is the best source for information, specially the Installation Guide.

Nevertheless, a simple set of instructions is this, running as root:

cd /usr/local/src
svn co http://svn.freeswitch.org:/svn/freeswitch/trunk freeswitch.trunk
cd freeswitch.trunk

edit the file /usr/local/src/freeswitch.trunk/modules.conf and uncomment the lines:

../../libs/openzap/mod_openzap
event_handlers/mod_erlang_event

Then continue running the following commands:

sh bootstrap.sh
./configure --prefix=/opt/freeswitch
make
make install
make hd-sounds-install
make hd-moh-install
make samples

Since the machine I use is for tests and development, I like to use the trunk version to make sure that I have the last correction for any known bugs.

So, to keep my system up to date I run the following commands:

cd /usr/local/src/freeswitch.trunk
make current

FreeSWITCH Configuration

openzap.conf

Path 

$PREFIX/conf/openzap.conf

In the case of the TDM422 card that I have, the port 1&2 are used to connect the incoming lines. This is a bit different than the Openzap.conf Example at FreeSWITCH wiki. Instead of number 1&2 for the fxo channels, I use the DID number. That makes routing incoming calls much more easy.

[span zt]
name => OpenZAP-FXO1
number => 1234567890
fxo-channel => 1

[span zt]
name => OpenZAP-FXO2
number => 1234567891
fxo-channel => 2

[span zt]
name => OpenZAP-FXS1
number => 3
fxs-channel => 3

[span zt]
name => OpenZAP-FXS2
number => 4
fxs-channel => 4

openzap.conf.xml

Path 

$PREFIX/conf/autoload_configs/openzap.conf.xml

<configuration name="openzap.conf" description="OpenZAP Configuration">
  <settings>
    <param name="debug" value="0"/>
    <param name="hold-music" value="$${moh_uri}"/>    
  </settings>
  <analog_spans>
    <span id="1">
      <param name="tonegroup" value="us"/>
      <param name="digit-timeout" value="2000"/>
      <param name="max-digits" value="11"/>
      <param name="dialplan" value="XML"/>
      <param name="context" value="default"/>
    </span>
    <span id="2">
      <param name="tonegroup" value="us"/>
      <param name="digit-timeout" value="2000"/>
      <param name="max-digits" value="11"/>
      <param name="dialplan" value="XML"/>
      <param name="context" value="default"/>
    </span>
    <span id="3">
      <param name="tonegroup" value="us"/>
      <param name="digit-timeout" value="2000"/>
      <param name="max-digits" value="11"/>
      <param name="dialplan" value="XML"/>
      <param name="context" value="default"/>
    </span>
    <span id="4">
      <param name="tonegroup" value="us"/>
      <param name="digit-timeout" value="2000"/>
      <param name="max-digits" value="11"/>
      <param name="dialplan" value="XML"/>
      <param name="context" value="default"/>
    </span>
  </analog_spans>

erlang_event.conf.xml

Path 

$PREFIX/conf/autoload_configs/erlang_event.conf.xml

This file is not created during the FreeSWITCH installation by the make samples command, so you will have to create it.
The param shortname will allow us to use only node@myserver instead of node@myserver.mydomain.

<configuration name="erlang_event.conf" description="Erlang Socket Client">
  <settings>
    <param name="listen-ip" value="0.0.0.0"/>
    <param name="listen-port" value="8031"/>
    <param name="nodename" value="freeswitch"/>
    <param name="cookie" value="ClueCon"/>
    <param name="shortname" value="true"/>
    <param name="encoding" value="string"/>
  </settings>
</configuration>

123456_erlang.xml

Path 

$PREFIX/conf/dialplan/default/123456_erlang.xml

The extension to_erlang is useful to create fake incoming calls for spice-telephony.
To test the Customer queues replace the default_queue value with the corresponding customer queue name. We will only use this extension in the tests.

<include>
  <extension name="to_erlang">
    <condition field="destination_number" expression="^123456$"> 
      <action application="set" data="queue=default_queue"/>
      <action application="erlang" data="freeswitch_media_manager:! testme@myserver"/>
    </condition>
  </extension>
</include>

You can know more about the way FreeSWITCH handles the Ourbound Connections to Erlang here.

02_hard_phones.com.xml

Path 

$PREFIX/conf/dialplan/default/02_hard_phones.com.xml

It is always a good idea to assign an extension number to the hard-phones so that you can test them

<include>
  <extension name="hardphone1_extension">
    <condition field="destination_number" expression="^(507)$">
      <action application="bridge" data="openzap/3/1"/>
    </condition>
  </extension>
  <extension name="hardphone2_extension">
    <condition field="destination_number" expression="^(508)$">
      <action application="bridge" data="openzap/4/1"/>
    </condition>
  </extension>
</include>

You can see some more examples regarding the Dialplan Configuration of the openzap channels here.

modules.conf.xml

Path 

$PREFIX/conf/autoload_configs/modules.conf.xml

Make sure that entries for mod_erlang_event and mod_openzap exist and are not commented out.

<configuration name="modules.conf" description="Modules">
  <modules>
    
    <!-- Loggers (I'd load these first) -->
    <load module="mod_console"/>
    <load module="mod_logfile"/>
    <!-- <load module="mod_syslog"/> -->

    <!--<load module="mod_yaml"/>-->

    <!-- Multi-Faceted -->
    <!-- mod_enum is a dialplan interface, an application interface and an api command interface -->
    <load module="mod_enum"/>

    <!-- XML Interfaces -->
    <!-- <load module="mod_xml_rpc"/> -->
    <!-- <load module="mod_xml_curl"/> -->
    <!-- <load module="mod_xml_cdr"/> -->

    <!-- Event Handlers -->
    <load module="mod_cdr_csv"/>
    <!-- <load module="mod_event_multicast"/> -->
    <load module="mod_event_socket"/>
    <!-- <load module="mod_zeroconf"/> -->
    <load module="mod_erlang_event"/>

    <!-- Directory Interfaces -->
    <!-- <load module="mod_ldap"/> -->

    <!-- Endpoints -->
    <!-- <load module="mod_dingaling"/> -->
    <load module="mod_iax"/>
    <!-- <load module="mod_portaudio"/> -->
    <!-- <load module="mod_alsa"/> -->
    <load module="mod_sofia"/>
    <load module="mod_loopback"/>
    <!-- <load module="mod_woomera"/> -->
    <load module="mod_openzap"/>
    <!-- <load module="mod_unicall"/> -->

    <!-- Applications -->
    <load module="mod_commands"/>
    <load module="mod_conference"/>
    <load module="mod_dptools"/>
    <load module="mod_expr"/>
    <load module="mod_fifo"/>
    <load module="mod_voicemail"/>
    <!--<load module="mod_fax"/>-->
    <!--<load module="mod_lcr"/>-->
    <load module="mod_limit"/>
    <load module="mod_esf"/>
    <load module="mod_fsv"/>
    <load module="mod_cluechoo"/>
    <!--<load module="mod_spy"/>-->

    <!-- SNOM Module -->
    <!--<load module="mod_snom"/>-->

    <!-- Dialplan Interfaces -->
    <!-- <load module="mod_dialplan_directory"/> -->
    <load module="mod_dialplan_xml"/>
    <load module="mod_dialplan_asterisk"/>

    <!-- Codec Interfaces -->
    <load module="mod_voipcodecs"/>
    <load module="mod_g723_1"/>
    <load module="mod_g729"/>
    <load module="mod_amr"/>
    <load module="mod_ilbc"/>
    <load module="mod_speex"/>
    <load module="mod_h26x"/>
    <!--<load module="mod_siren"/>-->
    <!--<load module="mod_celt"/>-->

    <!-- File Format Interfaces -->
    <load module="mod_sndfile"/>
    <load module="mod_native_file"/>
    <!--For icecast/mp3 streams/files-->
    <!--<load module="mod_shout"/>-->
    <!--For local streams (play all the files in a directory)-->
    <load module="mod_local_stream"/>
    <load module="mod_tone_stream"/>

    <!-- Timers -->

    <!-- Languages -->
    <load module="mod_spidermonkey"/>
    <!-- <load module="mod_perl"/> -->
    <!-- <load module="mod_python"/> -->
    <!-- <load module="mod_java"/> -->
    <load module="mod_lua"/>

    <!-- ASR /TTS -->
    <!-- <load module="mod_flite"/> -->
    <!-- <load module="mod_pocketsphinx"/> -->
    <!-- <load module="mod_cepstral"/> -->
    <!-- <load module="mod_rss"/> -->
    
    <!-- Say -->
    <load module="mod_say_en"/>
    <!-- <load module="mod_say_zh"/> -->
  </modules>

Running FreeSWITCH

It is always a good idea to run FreeSWITCH in a screen session. You can find a good screen tutorial here

screen 
cd /opt/freeswitch/bin
./freeswitch

So, if you want, you can detach from the screen session using <Ctrl-a d>.
To reattach use the following bash command:

screen -r

While in screen, use <Ctrl-a ?> to access the help and know other key bindings.

If you require FreeSWITCH to generate some debugging info, the easiest is to modify the corresponding commands in the vars.xml file:

...
  <X-PRE-PROCESS cmd="set" data="call_debug=true"/> <!-- default: false -->
  <X-PRE-PROCESS cmd="set" data="console_loglevel=debug"/> <!-- default: info -->
...

Installing Erlang

From Source

Now that Erlang R13B is out, we recommend to use it.

cd /usr/local/src
wget http://www.erlang.org/download/otp_src_R13B.tar.gz
tar xvzf otp_src_R13B.tar.g
cd otp_src_R13B
export ERL_TOP=/usr/local/src/otp_src_R13B
sh otp_build setup -a --without-ssl
make
make install

Note: This commands will install erlang without support to wxErlang and ssl. I had to do so because I could not get rid of a ssl related error. If you know how to get rid of it on Centos 5.3, please document it here.

From EPEL Repository

Unfortunately, Erlang is not part of the standard distribution. Nevertheless, the "Extra Packages for Enterprise Linux" repository, also known as EPEL, does include it.

To access th package offered by that repository run the following commands as root:

rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-3.noarch.rpm
yum install erlang erlang-doc

Unfortunately, the EPEL's Erlang version is kind of old, but will be enough for our purpose. Another disadvantage is that EUnit dos not comes installed by default, so you will have to install it if you want to run the tests:

svn co http://svn.process-one.net/contribs/trunk/eunit eunit-2.0
cd eunit-2.0
make
cd ..
mv eunit-2.0 /usr/lib/erlang/lib

Tip 

Usefull commands to be run within the erl console:

code:lib_dir().  %% tells you where the erlang libs are installed.
code:root_dir(). %% tells you what the erlang root is.
application:loaded_applications().
application:loaded(library_or_application).

Installing Spice-Telephony

First you need to select a location to install Spice-Telephony.
We will assume that you use $HOME/src in this document.

mkdir ~/src
cd ~/src
git clone http://git.opencsm.org/index.cgi/spice-telephony/
cd spice-telephony
rake clean
rake

Running spice-telephony the easy way:

ruby boot.rb

Tips 

Remember to keep up with the new versions, updating your system regularly with:

git pull
rake clean
rake

Is also a good idea to generate the html documentation

cd ~/src/spice-telephony
rake doc

You will find the index file of the documentation in the doc directory:

firefox $HOME/src/spice-telephony/doc/index.html

Base configuration

We will define a common basic configuration that will be used throughout the test cases. In some of the cases we will require to complement this configuration. In that case we will provide the required additional configuration instructions. It is recommended to use some of the functions presented below, like add_config/5, as an API to be used by other modules rather than call them directly from a shell. Nevertheless, I use them here because they are a very practical alternative to the web interface.

Configure a FreeSWITCH connection 

1> cpx_supervisor:add_conf(freeswitch_media_manager, freeswitch_media_manager, start_link, [freeswitch@myserver, [{domain,"myserver"},{voicegateway,"my_voice_gateway"}]], management_sup).

Enabling the Web Connection on port 5050 

2>  cpx_supervisor:add_conf(agent_web_listener, agent_web_listener,start_link, [5050],agent_connection_sup).

Agents may connect then to the "web connection" using username agent with password Password123 at:

http://myserver.mydomain:5050/

For the remote number you may:

• Leave it blank, if you want the agent call's to be routed via SIP to endpoint agent@mydomain. You will need to configure such account in FreeSWITCH.
• Use an extension number within the range 1-9999. You can take advantage then of the FreeSWITCH predefined extensions 1000 to 1019, or configure your own extension.
• Use a remote number at your VoIP gateway.

At the end of each test case it is recommended to go back to this basic configuration. Since this is a test installation, the easiest way to do is to quit Spice Telephony, remove the existing database and reconfigure again with the above mentioned commands.

To remove the database you can use the following command:

rm -Rf Mnesia.mynode@myserver

Test Cases

1. Basic Inbound Call
2. Inbound Queue with Recipes
3. Inbound Queue with Skills Routing

Debugging

If you have any problem and want to trace it you can take advantage of spice-telephony debug info:

rake
rake test:compile
ruby boot.rb -d

Additionally you can enable full debugging without doing a test-enabled build:

1>cpxlog:set_loglevel(debug).

Or you can enable/disable full debugging messages for only certain modules:

1>cpxlog:debug_module(cook).
2>cpxlog:debug_module(agent_manager).
3>cpxlog:nodebug_module(queue_manager).

Also it is useful to check the existing C Nodes from the bash shell:

[root@myserver ~]# epmd -names
epmd: up and running on port 4369 with data:
name testme at port 34874
name freeswitch at port 8031

The freeswitch port will be the same that you defined in the erlang_event.conf.xml configuration. The other two will most likely be different.

Tip 

Usefull commands to be run within the erl console:

[{Login, Apid}] = agent_manager:list().
agent:dump_state(Apid).
whereis(agent_manager).

Softphones

Zoiper 2.0

Zoiper Communicator

X-lite