Adhearsion Setup

My first experience with Asterisk involved showing that Asterisk was programmable and could be hooked up to a database. I asked some friends and they pointed me to Adhearsion.

Adhearsion is inspired Ruby on Rails (RoR). RoR is a popular Model-View-Controller (MVC) framework for the Ruby programming language. Using MVC for handling calls that require some database interaction makes a lot of sense.

While there is a Getting Started guide on the Adhearsion site, it does not cover setting up a connection from a SIP provider. I'll outline a process that you can use to get a simple app that connects to a MySQL database to retrieve and store information.

Set Up Asterisk

First, of course, you have to set up Asterisk. If you just wanted a nice little PBX, this would be all you need. However, the configuration I'm providing here will give you set up the start of a zipcode lookup service.

1. Get CD image for AsteriskNow.

2. While it installs, go to SIPNumber and sign up. For no cost, you'll get a phone number in Iowa and an account that you can use to connect Asterisk to. This number is useful for testing your Asterisk configuration skills or for demonstrating Asterisk apps to your clients. If you want to change it to a local number (for a small one-time fee), go to http://myaccount.calldigits.com/ and click the "Change" link that appears in the upper right hand corner.

N.B. I have no affiliation with SIPNumber except as a user.

3. When AsteriskNow comes up, it will present you with information on how to perform an initial setup over its web interface. Go through the wizard, but don't set up any providers just yet. You may want to set up a local extension, though, for yourself.

4. Use ssh to connect to the IP address of the box. Use the username admin and the password you set during the installation for the admin user. You'll be able to get to root using sudo -s at the command line.

5. Modify /etc/asterisk/extensions.conf:

Add the following to the [default] section. This will allow local users of your system (e.g. you) to dial 900 to get to the Adhearsion script.

         exten => 900,1,AGI(agi://127.0.0.1)

At the end of the file, add the following bit. Note that the name zip_lookup isn't important, but it must match a block in your Adhearsion script. In the next step, sip.conf points to this zip_lookup extension so that anyone who dials the number will be presented with the adhearsion program.

         [zip_lookup]
         exten => s,1,AGI(agi://127.0.0.1)

6. Modify /etc/asterisk/sip.conf:

In the [general] section, put

         register => YOURSIPNUMBER:YOURSIPPASSWORD@sipnumber.net

Put the following bit at the end of the file. Note the context line here matches what is in extensions.conf. Asterisk now knows to route all calls from your SIP number to the Adhearsion instance you'll be running.

         [sipnumber]
         type=peer
         insecure=very
         host=67.55.159.160 # this is proxy.freedigits.com
         context=zip_lookup
         disallow=all
         allow=ulaw
         allow=gsm

Set Up Your Router

Since I'm assuming that you want to communicate with the wider world via Asterisk, this is the most important step and the hardest to describe. I spent most of my time struggling with this since I didn't understand what was needed. Hopefully, I can help you avoid some of that pain.

Asterisk will use SIP to communicate with the outside world. Incoming connections will be UDP connections to port 5060 and will then be bounced to a higher UDP port. For testing, only reserve ports 10000 to 10100 for Asterisk (100 ports should be more than enough for testing).

Assuming you have a router doing NAT from a public IP address to your private address, you need to make sure that anything the router recieves in that port range (10000-10100) will go to the IP address of the box on which you installed Asterisk. I've included a screenshot of the necessary configuration for DD-WRT (the router firmware I use) but you'll need to do something similar.

Adhearsion Setup

Next, you'll need to install the Adhearsion framework.

1. Edit /etc/conaryrc to include the Ruby repository by typing the following command:

    sudo sed -i 's,^installLabelPath ,installLabelPath ruby.rpath.org@rpl:devel ,' /etc/conaryrc

2. Install Mysql, Ruby, and RubyGems:

    sudo conary update +mysql +ruby +rubygems

3. Log out of your ssh session and log back in. While this isn't strictly necessary, it is a quick, easy way to get an updated environment.

4. Update the Ruby Gems repository and install adhearsion:

    sudo gem update
    sudo gem install adhearsion

Allow gem to install all dependencies by answering Yes to all questions.

5. Install the MySQL extension for Ruby.

    sudo gem install mysql -- --with-mysql-dir=/usr

(I was surprised this wasn't included in the inital installation.)

Demo Project

Now, you are ready to start working with Adhearsion. You can use Bazaar to check out my zip code lookup project. As a bonus, you'll get all the terrible sounding voice recordings I made.

1. Install bzr:

    sudo conary update +bzr

2. Check out my project:

    bzr co http://mah.everybody.org/bzr/zip-lookup

3. Create a database for Adhearsion to use.

    mysqladmin -u root create adhearsion

4. Populate the database. (You can look at the scripts in the util subdirectory for how I created these sql files.)

    mysql -u root adhearsion < util/setup.sql

5. Make the recorded sounds available to Asterisk:

    sudo ln -s `pwd`/zip-lookup/sounds /var/lib/asterisk/sounds/record

6. Start up Adhearsion

    ahn start zip-lookup

Try It!

That's all that should be needed. You should now be able to call the SIPNumber you received and you'll hear my wonderful voice telling you "Press one for..."

Note that the first option is to dial me. I only know that it will work when I am extension 100 on the same system. I don't know enough about Asterisk or SIP yet to know how what will happen if you run it on your own system. I suggest you replace that.

In fact, I suggest replacing all the sound files with better ones. Then send them to me and I'll put them in the repository for other people to use.

Debugging Tips

The best way to debug SIP sessions is to use the Asterisk console. At a shell prompt, type sudo asterisk -r and you'll be on the console. Help is available if you ask for it (type help) but, for SIP session, you need two things.

sip show peers

First is the command sip show peers. This will show you the SIP peers you are connected to. Here is the output of when I run this command:

    localhost*CLI> sip show peers
    Name/username              Host            Dyn Nat ACL Port     Status
    sipnumber                  67.55.159.160        N      5060     Unmonitored
    sipnumber-out/6412377272   67.55.159.160        N      5060     Unmonitored
    100/100                    (Unspecified)    D          0        Unmonitored
    3 sip peers [Monitored: 0 online, 0 offline Unmonitored: 2 online, 1 offline]

Note that the 100/100 line is listed as offline. It would be online if I connected my SIP client (e.g. OpenWengo).

sip set debug

The other command that will come in handy is sip set debug and sip set debug off. Turning SIP debugging on will allow you to see Asterisk handling SIP connections in real time. Careful, though, as there is a ton of information and you'll need to use your scrollback buffer.

show dialplan

It may be that your AGI connection isn't set up properly. Typing show dialplan will flood your screen with information. Make sure there is a line that looks like this:

   [ Context 'zip_lookup' created by 'pbx_config' ]
     's' =>            1. AGI(agi://127.0.0.1)                       [pbx_config]

reload

Finally, if you have make changes to your Asterisk configuration, you can load them from the console by simply typing reload.

Contact Me

Let me know by email if you have any problems.