Your First Adhearsion Application

So you can dive in head-first, we'll first create an Adhearsion application before we have Adhearsion installed.

If you're new to Adhearsion, you should definitely be using Adhearsion version 0.8.0. This is presently only available from the Subversion repository but it will soon be made available through RubyGems. To download the code for version 0.8.0, run the following command (with the Subversion client installed):

svn co http://svn.adhearsion.com/trunk adhearsion

Within the folder you just downloaded exists a script called ahn in the bin directory. This is the main executable of Adhearsion. You'll be using it a lot so we recommend adding the absolute path to this bin folder to your $PATH variable. If you don't know how to do this, don't worry. You can just use the full path to the executable to run it.

Creating your first application

Using the ahn command, run the following command:

~/Desktop % ahn create helloworld
      create 
      create  components/simon_game/lib
      create  components/simon_game/test
      create  config
      create  .ahnrc
      create  components/simon_game/configuration.rb
      create  components/simon_game/lib/simon_game.rb
      create  components/simon_game/test/test_helper.rb
      create  components/simon_game/test/test_simon_game.rb
      create  config/startup.rb
      create  dialplan.rb
      create  events.rb
      create  README
      create  Rakefile

If you get an error saying ahn is not found, try supplying the full path to the command. On OS X, this would look like "/Users/jicksta/Desktop/adhearsion/bin/ahn create foobar". When your output looks like the output shown above, you now have a new Adhearsion app ready for your modification!

Understanding the directory structure

dialplan.rb

This file contains the implementation of how your app responds to incoming phone calls. It's separated into contexts which perform some definiable unit of functionality. We'll take a look at this in more detail soon.

config/startup.rb

This file contains the necessary information to instruct Adhearsion how to initialize your application. More importantly, it contains application-specific configuration such as which aspects or features of the framework are enabled and with what parameters. For simple applications, you may not need to touch this at all.

components/

This folder is a place to store extensions to Adhearsion. If you come from the Rails universe, these are like plugins.

Note: the components system is about to undergo a huge refactoring. For now, you only need to understand the aforementioned concept. Specifics of writing a component will be documented later as things solidify.

Writing your first dialplan

Using your favorite text editor, open the dialplan.rb file. You'll see a sample application that runs a Simon game. This is a simple game that just tests your memory.

adhearsion {
  simon = new_simon_game
  simon.start
}

Starting your application

Installing Asterisk

While binary distributions are available for most platforms, Asterisk has always been simple to install from source, and it will likely stay that way.

There are three packages you will need to download. The first pack- age, libpri is Asterisk’s ISDN/Q.931 library which you’ll need to talk to PRI lines or other ISDN devices. You definitely need this if you intend to hook up a T1/E1 to your system. Second, you’ll need zaptel, which provides the hardware kernel drivers for the Zaptel telephony hard- ware. Even if you do not intend to use Zaptel hardware, it’s a good idea to install Zaptel anyway, as it installs a special driver called ztdummy which uses the hardware real-time clock to emulate a Zaptel device. This is important for generating the 1000 times-per -second timing needed to properly coordinate G.711 calls with services like conference calling and music-on-hold.

Getting the Source

The Asterisk sources are distributed either via tarball or via Subversion. If you’re not using Subversion yourself now to manage your Ruby or Rails projects, you should be. Check it out.

Here are some links to the current (April 2007) release of Asterisk. By the time you read this, the links will be out of date. You should check asterisk.org for the links to the latest version numbers. Regardless, this gives you a starting point.

Using Tarballs

You should go ahead and untar them: 

tar xzf asterisk-1.4.2.tar.gz
tar xzf zaptel-1.4.1.tar.gz
tar xzf libpri-1.4.0.tar.gz

Using Subversion

svn co http://svn.digium.com/svn/asterisk/tags/1.4.2
svn co http://svn.digium.com/svn/zaptel/tags/1.4.1
svn co http://svn.digium.com/svn/libpri/tags/1.4.0

Leading Edge or Bleeding Edge?

With Asterisk, much as with the Linux kernel, you have a choice between running stable release code, or running experimental development code. Sometimes, it pays to use the development code because features (and less often, bugfixes) are present in the development code that are not available in the stable code. This decision is up to you. We recommend that you run the stable code until or unless you find there is a feature or bugfix in the development ’trunk’ that you need to use.

If you do want to use the ’trunk’, (with the caveat that it can be pretty wild and woolly), you can download it using Subversion here:

svn co http://svn.digium.com/svn/asterisk/trunk asterisk-trunk
svn co http://svn.digium.com/svn/zaptel/trunk zaptel-trunk
svn co http://svn.digium.com/svn/libpri/trunk libpri-trunk

Compiling and Installing

There are a few pre-requisites necessary to compile and install Asterisk. Please be sure you have each of these installed. Often the easiest way to install these is using your distribution’s package management system (yum or apt-get, for example).

• openssl
• kernel-devel
• kernel-smp-devel (for SMP systems)
• ncurses
• ncurses-devel
• readline
• GCC
• bison
• libtermcap
• libtermap-devel
• newt-devel
• wget, or fetch

Compiling and installing Asterisk is straightforward. Once you have a source directory for each of libpri, zaptel, and asterisk (and we recom- mend you put these into one ’asterisk’ directory, wherever you keep your source files), you can go ahead and compile and install it. Aster - isk assumes you’re logged in and doing this as root, for reasons having mostly to do with the fact that Asterisk is often a dedicated use of a box and can have considerable hardware requirements. It is possible to install Asterisk as a non-root user, and this process is covered in the documentation. In practice, it’s rarely done, despite the negative security implications.

If you have all the requirements and dependencies in place, this should be a fairly painless process. It may take a little while to compile and install Asterisk, but generally not more than a few minutes. Asterisk will place its configuration files into ’/etc/asterisk’, and we’ll be spend- ing some time there in order to setup Asterisk to be useful with Ruby in our later examples.

ConfigureAsterisk

There's a couple of files we'll need to edit, first, sip.conf:

[general]
 bindport=5060                   ; UDP Port to bind to (SIP standard port is 506$
 bindaddr=0.0.0.0                ; IP address to bind to (0.0.0.0 binds to all)
 [softphone]
 type=friend                     ; always use friend, nobody uses user or peer anymore
 host=dynamic                    ; device has a dynamic host, not a fixed domain
 username=softphone              ; this needs to match the entry in []'s
 secret=1234                     ; obvious...
 context=default                 ; context calls from this client will start from
 disallow=all                    ; no codecs used except the ones we like
 allow=gsm                       ; GSM consumes far less bandwidth than ulaw
 allow=ulaw
 allow=alaw

now edit extensions.conf:

[general]
 static=yes
 [globals]
 [default]
 exten => _X.,1,AGI(agi://192.168.50.52) ; change this to the IP of the server running adhearsion

start asterisk (just run "asterisk"), and we're ready to configure the softphone

Configure Client

For this example, I used kphone, since it was already installed. Set your identity up, specifying the ip address of your asterisk box, and the username and authentication username. You will then be prompted for a password, enter whatever you set "secret" to in sip.conf

Directory Structure

Hello World

 Create your own educational wiki!Support CommunityPublic, not yet premium Privacy Policy RSS