Build a Twilio Hard Phone with SIP from Twilio, Raspberry Pi, Asterisk, FreePBX, and the Obihai OBi100

Build a Twilio Hard Phone with SIP from Twilio, Raspberry Pi, Asterisk, FreePBX, and the Obihai OBi100

This post used the Dial and SIP TwiML verbs and the Twilio Message Rest API

If you have worked with Twilio before, you have surely heard that sweet, sweet ring of your phone many times. But today, we are entering uncharted territory – you are going to learn how to make a phone ring without it even being connected to a traditional phone network! All you need are some simple pieces of hardware and that old landline phone that got shoved into the back of your closet years ago.

Now, you may have seen our previous Arduino-focused tutorials on building your own Twilio Robot and automating your home with Twilio SMS but today we are going to try something new and use the amazing miniature computer called Raspberry Pi.

Getting Started

First things first, we need some parts. You will need to get a Raspberry Pi, an Obihai OBi100, and a traditional landline phone. For the Raspberry Pi, you will also need an SD card (I recommend a 4GB one), an Ethernet cable, and a Micro-USB power cable. I would also recommend having a USB keyboard and mouse as well as an HDMI monitor handy if for some reason you can’t SSH into your Raspberry Pi.

Once you have gathered all your parts, we can kick things off right and set up our Raspberry Pi – but we wont plug it in just yet. Before turning it on, we need to install an operating system on the SD card that serves as the Pi’s hard drive. Normally, you would use Raspbian – an optimized version of Debian made for Raspberry Pi. However, for our purposes, we are going to use a pre-built Raspbian image called RasPBX which comes with Asterisk and FreePBX pre-installed.

Installing RasPBX on your Raspberry Pi

The installation process can be somewhat tricky, but I have worked out some step-by-step instructions for those of you using Mac OS X. If you have any trouble or are running a different operating system, I highly recommend reading through these installation instructions.

Step 1: Download our RasPBX image here. Once it is finished downloading, unzip the archive.

Step 2: Put the SD card into your computer and open up Disk Utility (just type it in to the Spotlight search) – in the Disk Utility you should see your SD card in the list on the left. Format it with a FAT partition. You will need to be on an account with Administrator permissions for this SD card setup process! (Instructions paraphrased from RPi Easy Setup Guide)

Step 3: Open a Terminal window and type ‘df -h‘ to see a list of your disk mounts.

Step 4: Unmount the disk using ‘sudo diskutil unmount /dev/disk3s1′ – replace /dev/disk3s1 with whatever the filesystem name of your SD card is in the previous results

Step 5: Work out the raw device name for the SD Card by removing ‘s1’ and replacing ‘disk’ with ‘rdisk’if you use the wrong device name, you could wipe your entire hard drive – be careful!)

For example, on my system /dev/disk3s1 becomes /dev/rdisk3

Then run the following command (replacing /dev/rdisk3 with your own SD card device name and replacing the raspbx.img file location with the location where you unzipped it on your system). Make sure you have the right device or you can wipe your entire system!

sudo dd bs=1m if=/Users/jonmarkgo/Downloads/raspbx-04-11-2012/raspbx-04-11-2012.img of=/dev/rdisk3

This will take some time to execute, so go grab a snack while you wait. When you come back, you should see output similar to what I have in my terminal below:

Step 6: Eject your SD card by typing ‘sudo diskutil eject /dev/rdisk3’ (replacing rdisk3 with your own SD card device name)

Step 7: Plug it into your Raspberry Pi, and turn that baby on. You should also have plugged your Raspberry PI into your Ethernet router as well. Look at all the blinky lights!

Configuring RasPBX and your Raspberry Pi

Now that we have our Raspberry Pi booted up running our modified RasPBX distro of Linux, we can get started with the soft configuration. The first thing to do is either SSH into your Raspberry Pi or use the keyboard/mouse/monitor hookup to get a terminal window open. On Mac, you can use ‘ssh root@raspbx.local‘ or on Windows ‘ssh root@raspbx‘ – the default username is root and the password is raspberry.

A successful login looks something like this:

At this point we need to configure some basic settings on our Raspberry Pi, as well as find out its IP Address. To find out its IP Address, use ‘ifconfig‘ and to begin configuration type ‘raspi-config‘ – there are many options to use and play around with but for now we are just going to use ‘expand_rootfs’ as in the following image – after expanding the filesystem, reboot the device (you will be prompted to do so) and then log back in to the terminal:

Now we can go ahead and start configuring FreePBX (which controls Asterisk’s configuration files). You can log in to FreePBX by opening http://raspbx.local/ (or whichever hostname you used to access it) in your browser and then clicking on ‘FreePBX Administration’. The default username and password are both admin. Now we are going to configure Asterisk to accept incoming calls from Twilio and pass them through to our OBi100.

Step 1: Go to Settings->Asterisk SIP Settings and configure your NAT settings. In my case, I set up my Static and local IP addresses manually though you may need to configure it differently based on how your network is set up. Note that you will need the Raspberry Pi to be exposed to the web via a public IP address of some sort.

In my configuration, I simply opened up a DMZ on my network (note: this is not a secure setup) but you may need to have a different setup based on your network configuration.

You will also want to uncheck every codec except for ‘ulaw’, as this is the only one that Twilio currently supports.

Step 2: Go to the Applications tab and add a new ‘Generic SIP Device’ – this is where we configure the extension that Asterisk will forward to our OBi100 and eventually our land line phone. I am going to use extension number ‘1337’ so I will enter this number into the User Extension and Display Name fields.

Then you need to enter a password (called a secret) under the Device Options heading. I am going to make mine somewhat insecure and simply set my secret as ‘obihai100’.  Believe it or not, that is all the configuration we need to do to allow Asterisk to work with our OBi100.

Now just click ‘Submit’ – we will apply the configuration later.

Step 3: Next we need to configure Asterisk to accept inbound calls from Twilio. This requires some manual configuration via our Terminal, so lets head back over there and use our editor of choice to modify the file ‘/etc/asterisk/sip_custom_post.conf’

We will then paste in the following configuration:

Lets head back over into FreePBX and click that big red ‘Apply Config’ button now to save all of our settings and restart Asterisk. Now we are finished configuring our Raspberry Pi, FreePBX, and Asterisk.

Setting up our Obihai OBi100

With our Raspberry Pi fully configured, we can now finish things off by setting up our OBi100 device. Lets plug it in to both a power outlet, your landline phone, and an Ethernet router using the included cables (thanks Obihai!) – once it is fully started up, you can open the control panel in your browser by heading to the OBi100’s local IP address. In order to find this, I needed to log into my router’s control panel and find out what IP address had been assigned to my device – this may take some experimentation if you have not used your router’s control panel before.

Once you have found the IP address of your OBi100 and opened it in your browser, you should get presented with an authentication dialog. The username and password are again both admin. Now we need to do some configuration.

Step 1: Click on the Voice Services->SP1 Service. Here you will need to configure the SIP Credentials. Your AuthUserName is the extension number that you configured in FreePBX (1337 for me), the AuthPassword is your secret (obihai100 for me). Then just click Submit to save your changes.

Step 2: Click on Service Providers->ITSP Profile A->SIP. Here we have some more configuration to do – we need to tell the OBi100 where to find our Asterisk server. First we need to set the ProxyServer variable to point to the local IP address of our Raspberry Pi.

Then we should change the X_SpoofCallerID to be active so that the Caller ID gets forwarded along properly from Asterisk.

Click Submit again to save your changes and then click the Reboot button in the top bar to restart your OBi100. All of your hardware is now configured, the next thing to do is set up a Twilio number that can call our new system.

Setting up Twilio

If you are brand new to Twilio I recommend watching our SMS Quickstart Screencastwhich shows you how to buy a number for the first time. Otherwise, simply go ahead and buy a number. Configure the Voice URL to point to a new TwiML file that we will create below.

In the TwiML file at that URL, enter the following:

The main change you have to make in this TwiML is to update the Uri that is being dialed. The format is @, so in the example my extension is 1337 and my IP address is 74.66.246.104.

Update: We have heard that some users are experiencing issues with the IP-based authorization. It is possible to reconfigure Asterisk to accept any incoming connections regardless of authorization – this is an insecure solution, but should be a fine temporary one if you would like to test out the system!

Some explanation may be required here. Earlier, we configured our Asterisk server to only accept connections from three distinct IP addresses – those that belong to Twilio’s SIPOut API servers. Because of how Asterisk configuration files work, we actually had to create three separate inbound users, one for each IP. Here, we dial all three at the same time as only one of them will be successful (based on which Twilio server is making the request to your Asterisk server).

After that, we are finished setting everything up. Simply call your new Twilio number and your landline phone should ring – AWESOME!

Now go out there and build your own Twilio hard phone or connect Twilio to your existing SIP server using our new SIPOut feature. Happy hacking!

If you have any questions, feedback, or angry rants please feel free to Tweet @jonmarkgo or e-mail me at jonmarkgo@twilio.com