Getting Started

Ben Langfeld edited this page Apr 11, 2012 · 15 revisions

DEPRECATION NOTICE: This is old documentation relevant to Adhearsion 1.x and will soon be removed. See the main documentation for up-to-date info.

##Using Adhearsion with Asterisk##

These are the high-level steps to get started with Adhearsion:

  1. Install Asterisk
  2. Install Ruby, RubyGems and Adhearsion
  3. Create a new Adhearsion application
  4. Optional: Configure your new application for AMI
  5. Add stuff to dialplan.rb
  6. Start your application
  7. Call your application!

##Shortcuts##

If your distribution is listed below, follow the link to a pre-made script for bootstrapping a fully functional ready-to-run Adhearsion environment:

These scripts will install Ruby, RubyGems and Adhearsion for you. If Asterisk does not come bundled, it will install the distribution's Asterisk package.

If you used a Shortcut script you may now skip directly to the "Create a new Adhearsion application" step below.

##Installing Asterisk##

Instructions to help install Asterisk can be found here

##Installing Ruby, RubyGems and Adhearsion##

###Linux (Red Hat, CentOS, Ubuntu, Debian, others), BSD, Solaris### ####Option 1: RVM (Recommended)####

The easiest way to get started quickly is likely to use RVM. Installing Ruby can be as simple as:

bash < <( curl http://rvm.beginrescueend.com/releases/rvm-install-head )

This shell one-liner will download and install RVM. Read the instructions printed on the screen to complete its installation. Once complete, install your preferred Ruby interpreter:

# Ruby 1.8.7:
rvm install 1.8.7

# ... or Ruby 1.9.2:
rvm install 1.9.2

# ... or JRuby:
rvm install jruby

Once the RVM installation completes, install Adhearsion using the gem command:

gem install adhearsion

That's it! Continue on down to "Creating and running your first application."

####Option 2: System Ruby#### You may prefer to use the Ruby package that comes with your operating system.

Note that Adhearsion requires at least Ruby 1.8.6, which is not available on Red Hat Enterprise Linux 5 and CentOS 5. If you are using CentOS 5 (this includes Trixbox CE, Elastix, AsteriskNOW and PBX-in-a-Flash) you will need to use the Shortcut script at the top of this page, the RVM method above or compile and install Ruby manually to use Adhearsion.

On Debian and Ubuntu, you can install Ruby and RubyGems this way:

sudo apt-get install -y ruby1.8-dev rubygems1.8   irb1.8 libsqlite3-ruby1.8

On the Red Hat variants such as RHEL, Fedora, and CentOS, run the following command:

sudo yum install -y ruby ruby-rdoc ruby-irb   ruby-sqlite3

####Updating RubyGems####

Before we install any gems with RubyGems, let's make sure we're using the latest version. Upgrade RubyGems by running the following command.

sudo gem update --system

Now, we'll use the gem command to install Adhearsion:

sudo gem install adhearsion

This will automatically add the ahn command to your system, allowing you to create and start applications in the following step.

Installing Adhearsion is very simple on all platforms. The Ruby language has an official package manager named RubyGems, which conveniently streamlines the installation of third-party software. Once you install Ruby and RubyGems, you can use RubyGems to install Adhearsion. Each operating system works with RubyGems, but with slight differences:


###Mac OS X Leopard/Snow Leopard###

Since you use Leopard, you already have Ruby and RubyGems installed! All you have to do is install Adhearsion using the gem command:

sudo gem install adhearsion

This will automatically add the ahn command to your system, allowing you to create and start applications in the following step.

Yep, that's it!


###Mac OS X Tiger###

We recommend installing Ruby and RubyGems together using MacPorts. MacPorts is a package manager for Mac OS X, similar to the package managers that come with virtually every Linux distribution. Download MacPorts from here and follow the installation instructions on the website.

MacPorts installs the port command; you'll use it to install Ruby and RubyGems:

sudo port install ruby rb-rubygems

Now, just install Adhearsion by doing

sudo gem install adhearsion

This will automatically add the ahn command to your system, allowing you to create and start applications in the following step.


###Microsoft Windows###

On Microsoft Windows, you would install Ruby and RubyGems using these steps:

  1. Download and install the Ruby on Windows One-Click Installer (includes Ruby Gems)

  2. Open a Command Prompt and enter:

    gem install adhearsion

Note: Currently Adhearsion does not work as a Windows Service and therefore will only run interactively on Windows.

##Creating and running your first application##

Test that you have Adhearsion installed by running the following command:

ahn --help

This should print out the usage of the ahn command. This ahn command is the main way you create and run applications with Adhearsion.

###Creating an application###

Use the ahn command to create a new application in any directory you wish:

ahn create my_first_app

You will see the program print out a list of files it just created in the my_first_app folder.

###Add content to dialplan.rb###

Next, open the dialplan.rb file in your favorite text editor. This file contains the logic that is executed when you call into it. You should see something like the following:

adhearsion {
  simon_game
}

The name adhearsion in this file defines a dialplan context. The code within the curly braces is the implementation of the context. The simon_game text is a dialplan command or method. Methods often have arguments but the parenthesis around the methods are not required.

Next, to create a new context you'll add the following code to the bottom of your dialplan.rb file:

sandbox {
  play "hello-world"
}

We added a context named sandbox because this is where calls from into the sandbox will go. If you have other systems handled by this Adhearsion application, they can each go into their own respective Adhearsion context. In the sandbox context, you can also see the use of a dialplan method with arguments, in this case the string of text "hello-world" which corresponds to a sound filename on the sandbox server into which we'll now call.

Note: If you would like to access additional sound files beyond 'hello-world' , there's a listing of additional available sound files here.

##Starting your application##

Once you've done this, you're ready to start your application! Next, change back into the my_first_app directory and start it using this:

ahn start .

Where "." simply means the current directory. Alternatively, you can do...

ahn -

...which is a shortcut for starting the application in the current directory.

You should see Adhearsion output text as it starts the application.

##Conclusion##

That's it! Feel free to play around with your dialplan.rb file and add more code.

##What you haven't seen yet##

You just created your first Adhearsion dialplan but there's much more to Adhearsion than the dialplan! Here is a cursory overview of what you haven't seen yet:

###Using and writing Adhearsion components###

Adhearsion components are plugins which you can install into your individual application.

###Calling real telephones### ###Handling realtime events### ###Integrating with a database###

Here are a few ideas to explore further:

  • Try invoking the simon_game method that came with in your dialplan. Hint: it's a memory game.
  • Try out some of the Examples.

Enjoy!