[2010-02-26] THIS DOC IS OBSOLETE. PLEASE VIEW THE UPDATED PRIMER.
Sipdroid 1.0.4 Primer
First off, this document is constantly in flux and being revised. If you have any suggestions on how to make it better/clearer or have a correction, please post a reply or PM me. Thanks and enjoy!
First, you need to sign up with a SIP provider. Most SIP providers offer free accounts and free SIP calling. In addition to free VOIP-to-VOIP calls, you can also call people with traditional, or PSTN (public switched telephone network), phone numbers. This is usually referred to as PSTN outbound or call out and is charged on a per-minute basis. More on this later. There are many SIP providers on the internet, more than I can list here. I will name a couple to get you started, but there are more options out there. Google it...
One of the more polished consumer SIP services. They offer free VOIP calling and a decent outbound PSTN service with average rates. Cost for a call terminating in United States (landline and mobile) is $0.019/min. For inbound, you can lease a number from them, prices vary per area code. Gizmo5 also happens to be the only voip service that Google Voice will forward to at the time of this writing. For the purposes of this primer, I will assume Gizmo5 as the SIP provider.
They style themselves as a SIP service created by community. There seems to be limited free PSTN outbound access for numbers in Europe.
This service is actually the companion service for the VOIP phone application of the same name bundled with GNOME (default Ubuntu desktop). It has no PSTN outbound services, so consider this option if you only want to make calls to other VOIP users.
There are some others like FWD/Pulver and of course there is also the option of using a company SIP.
Now of course you'll also need to download a copy of Sipdroid. There are two places to get it: 1) Android Market. This is the easy way. Just open the Market app, search for Sipdroid and tap Install. 2) Sipdroid.org. Enable off-market app installation in your settings, then visit the sipdroid site and tap the apk link. Alternatively, you can download it on your PC and install with adb. The version from the Android Market is referred to as the "lite" version, whereas the Sipdroid.org version is "full". The main, and only, difference is the full version allows SIP connections over 2G/3G, whereas the lite version only allows SIP over WiFi.
Okay, now I assume you have your SIP account details and Sipdroid 0.9.4 installed. Open Sipdroid and press the menu button. Now tap Settings. Here, enter the username and password you registered with your SIP provider, as well as the server address. If your SIP provider specified a port other than the default (port 5060) then enter that as well.
Under the Options, check off the air interfaces which you want Sipdroid to connect with. If you downloaded the Market version, you will not be able to choose 2G/3G. Keep in mind that some carriers may forbid VOIP usage in their data plans, if you are using the webpage version. For preferred call type, choose Phone (more on this later).
Now press back to go to Sipdroid's main screen (the dark grey one). At this point hopefully you should have a green dot indicator in your windowshade, indicating that Sipdroid has successfully connected to your SIP provider. If the indicator stays yellow or red, that means Sipdroid was not able to connect properly. Sometimes Sipdroid will lose connectivity to your SIP provider, especially during a transition between 2G and 3G. If this occurs, open the Sipdroid application and go into the settings menu and exit. The connection should automatically reinitialize.
Making a call to a SIP address
A SIP address is somewhat like an email address. Both are types of URIs, or uniform resource identifiers, which in simple terms means they tell you where something is. A SIP address takes the form of sip:user@domain or simply user@domain.
To make a call to a SIP address, open the Sipdroid application, type it into the field labeled "Called Party Address" and press the return key. For your first test call, call firstname.lastname@example.org. Once the call has connected, you should see the in-call screen and an emerald-colored call indicator in the windowshade. The emerald color differentiates a SIP call from a standard voice call (which uses a green color).
After a brief introductory message, you should be able to hear SIPPhone's echo test, which echoes back whatever you say. This allows you to test that your SIP setup is working and that both parties can communicate properly. Note that if you are connecting over 2G/3G, you may experience a noticeable delay. This is due to the delay introduced by your cellular provider having to route packets from the cell network through to their datacenters and then onto the internet. Calls over WiFi should have significantly reduced delay (assuming the WiFi itself is connected to a good broadband internet connection). Since Android apps are not allowed to control the end call button, press the back button to terminate the call.
Making a call to a SIP number
Here's where it gets confusing (atleast it did for me). Many SIP providers not only issue a SIP address which is based on a user's username, they also issue a SIP number. The reasoning is that in many cases, people will want to make a VOIP call on a device which has no alpha keypad. In this case, the only way to make a call is a number pad. When you call a number using SIP, your SIP provider will do one of several things depending on what the number is. First of all though, we have to make sure that we're actually dialing the number using SIP, rather than using our mobile carrier.
Here, we will dial the number for the echo test we performed in the last step. For Gizmo5 users, the number 17474743246 corresponds to the SIP address email@example.com. Open your Android dialpad and enter it, followed by a plus sign(+), then press call. The plus sign at the end of the number tells Sipdroid to intercept your dial action and route the call over SIP/voip rather than let it go to your cellular carrier. To enter a + sign from the dialpad, long press the 0 button. If all went well, you should hear the same message you heard in the previous call.
note: in the above left image from 0.9.4, the escape char used is a hash (#). However, in 0.9.6 and newer, the escape char is a plus sign (+)
Now let's talk about that Preferred Call Type option. When we set the Preferred Call Type to Phone, we told Sipdroid that whenever we make a call in the Contacts/Dialer app, we want to by default use our mobile carrier. As I mentioned above, postpending a plus sign indicated to Sipdroid that we wanted to take the opposite of our Preferred Call Type action. So if your PCT is set to Phone, then adding a plus sign will change that call to SIP. Again, you can tell the difference between a SIP call and a PSTN call by looking at the color of the call indicator. Another way to tell if you are performing a SIP call is that your network traffic indicator should start showing some bidirectional traffic.
However, if you set the Preferred Call Type to SIP, the behavior is reversed. Any time you attempt to perform a call in the Contacts/Dialer app, it will by default be made as a SIP call. If you add a plus sign will it be made as a Phone (mobile carrier) call. I don't recommend setting it up this way unless you are very comfortable with SIP and/or don't use your phone with a SIM. Note that emergency numbers will be dialed as Phone (mobile carrier) calls regardless of the PCT setting.