Sipdroid 1.0.4 Primer [updated 2009-08-15]

[jashsu]

Sipdroid 1.0.4 Primer


Introduction

Originally Posted by jashsu 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!

Sipdroid is a bare-bones SIP client for Android. It does not provide a rich user experience like one would expect from Skype, as it is just client software, not a service. You need a SIP provider in order to use Sipdroid. I'll explain with some pictures how to setup and use Sipdroid. This primer was originally written for 0.9.4. Minor updates bring it in line with the current version, 1.0.4.


Preparation

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...

Gizmo5/SIPPhone
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.

Voipuser
They style themselves as a SIP service created by community. There seems to be limited free PSTN outbound access for numbers in Europe.

Ekiga
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.


Setup Sipdroid

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 echo@proxy01.sipphone.com. 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 echo@proxy01.sipphone.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.

[jashsu]

Making a call to a different VOIP network

So now you are able to call anyone with a SIP address or anyone in your SIP network with a number. What if you want to call someone on a different SIP network but you only have their SIP number? That's where SIPBroker comes in. Essentially, it lets you call someone on a different network using a special prefix. For example, if my number with Gizmo5 was 1-747-555-1212 and you were on Ekiga, you would find Gizmo5's prefix on SIPBroker (*747) and dial *747-1-747-555-1212 to reach me.

Now let's say you wanted to call someone on Google Talk or Yahoo/MSN Messengers. These are not SIP networks, so you could not natively communicate with them using SIP. No problem. Using the gtalk2voip service, you can voice chat with them for free.


Making a PSTN call

SIP isn't just useful for free VOIP calling. You can also call someone with a traditional phone number (a PSTN call) using VOIP and save a lot of money. The reason is because with a traditional PSTN-to-PSTN call, your carrier can control the price of the call and add a significant markup. If your VOIP service supports outbound PSTN, for the bulk of the trip your call is travelling over the internet for free. Only when it has neared its destination is it routed back into the public switched telephone network.

You ==> MobileCarrier =======================> Other Carrier ==> Friend
You --> SIP Provider ------------------------> PSTN outbound ==> Friend

=== Carrier controlled route ($$$) ---- Over the internet (cheap)

In order to make a PSTN call with Sipdroid, your SIP provider needs to support PSTN outbound. With Gizmo5, this is referred to as Call Out. Typically you will deposit a small amount of money into a prepaid account with your SIP provider and calls you make slowly draw out of this pool. The cost per minute depends only on the destination of the call. For some locations, this can mean a SIP call will be significantly cheaper than a standard PSTN call.

To make a call to a PSTN number, simply enter the number on the keypad and add a plus sign at the end, as if you were making a call to a SIP number. Your SIP provider should automatically detect it is a PSTN number and assuming it has an outbound function, route it using its PSTN outbound network. To quickly place calls to PSTN numbers using SIP from your contact list, open the contact and tap the "Text (number)" option, where (number) is the PSTN number you'd like to call using SIP. A context menu will appear letting you choose to call that number with SIP or to send a text message. Overloading the text intent is a bit of a hack, and it may change in future versions of Sipdroid.




The relationship between SIP and PSTN

Let's say you have a contact with two phone numbers, one for his PSTN number (1-510-555-1212) and one for his SIP account (1-747-123-4567).

If you tap Text 555-1212...

... and choose the Sipdroid option, you will make a SIP call and he will receive the call on his PSTN phone. You will not be able to make the call unless your SIP provider has a call out function.

... and choose the Phone option, you will make a PSTN call and he will receive the call on his PSTN phone. Your call will use up your voice minutes in accordance with your mobile carrier's voice plan. Sipdroid/SIP is not used at all in this call.

If you tap Text 123-4567...

... and choose the Sipdroid option, you will make a SIP call and he will receive the call on his SIP phone (or whatever he has his SIP number set up to ring). This call will not use the PSTN network at all (unless your friend has set up his SIP number to forward to the PSTN).

... and choose the Phone option, you will get an error message from your mobile carrier informing you the number is invalid or not connected.

Area code 800 numbers for testing outbound

If you want to test outbound calling on a SIP provider with outbound, you can call the below numbers for free. Remember to use a plus sign after the number to indicate you want to place it as a SIP call.

+18004664411 (GOOG411)
+18005558355 (Microsoft's Tell Me news service)


DID and Incoming

Recent versions of Sipdroid are now finally capable of ringing on an incoming call. However, you may be wondering, how can your friends, family and coworkers call you using SIP rather than your cellular number? The answer is using a DID number, or Direct Inward Dialling. A DID number is simply a PSTN phone number. DID numbers can be configured to forward calls to voip networks. For consumers, there are a couple of options to set up a DID for SIP. Here are a few (only discussing US DID numbers for now):

Through your SIP provider - Some SIP providers targeted toward end-users offer DID numbers as a premium service. Gizmo5 calls their DID number service "Call In".

ipkall - One of the original free DID number service. Provides a free DID number in a select number of area codes around Seattle. Only forwards to SIP.

Google Voice - This is considered by some to be the ultimate free DID service, as you can choose a number from any US area code. However, GV is much more than a DID to forward to SIP, as it is designed to completely replace all your individual contact numbers with a single number that can be programmed to forward to your other numbers. GV also offers some other services such as advanced voicemail (automatic text transcriptions, forward to email, etc) and free calling and texting to US numbers.

[alexhtcg1]

Hello

I might be sound silly but I don't have much experience with either getting root or upgrading firmware. My HTC G1 is 1.1 firmware, 2.6.25-01845-g85d4f0d android-build@apa27 kernel, RC33. The phone is unlocked, I am not in the US or Europe, and the main issue is that I don't want to take the risk of screwing all up and sending it back to restore.

From what I read in this thread, and also at
http://code.google.com/p/sipdroid/wiki/FAQ
http://www.htc.com/www/support/android/adp.html
etc.

it seems it's best that I'd wait for official 1.5 being pushed, or someone can advise me some other (safe) solutions to upgrade?

I do need a SIP / VoIP client on my device really badly And some other things that come with the 1.5

Thanks...

[jashsu]

Sipdroid does not require root.

[alexhtcg1]

Originally Posted by jashsu Sipdroid does not require root.

Thanks for your reply. But it certainly won't run on 1.1 ???

[jashsu]

Originally Posted by alexhtcg1 Thanks for your reply. But it certainly won't run on 1.1 ???

I don't know. I haven't tried myself since I have already updated to ADP1.5. Posts on the sipdroid issue tracker seem to suggest that it will not run on 1.1. However at the current time you're not missing out on much. Sipdroid still needs a lot of work. It will not connect to all SIP providers, it does not ring/alert on an incoming call, and there are some call reliability issues. In other words, its not robust enough at the current time to be a full-time calling app.

I mainly wrote this guide to get interest in Sipdroid rolling (and hopefully stimulate more developers to contribute to the project).

[phantasybm]

this is still a bit complicated to understand...

Soecifically how to correctly set up a pbx account. the website itself is very confusing for a novice... maybe a little help with step by step would be great!

[jashsu]

Originally Posted by phantasybm this is still a bit complicated to understand... Soecifically how to correctly set up a pbx account. the website itself is very confusing for a novice... maybe a little help with step by step would be great!

You don't necessarily need to set up a pbxes.org account. As I described above, many SIP providers will work with Sipdroid without a virtual pbx in the middle.

And yes, I agree pbxes.org's site is pretty confusing. Not the most well-designed interface.

[liamw]

Has anyone tried this out in the UK on T-Mobile 3g, I keep getting Registration failed (Timeout) and the red spot, I have tried this with both Ekiga and Gizmo5, any ideas what I might be doing wrong. Will try on wifi tonight.

Update: Looking at the Mobile Broadband Plus ( handset as modem) terms and conditions it says you cannot make internet phone calls, so I guess they are blocking the port.

[jashsu]

Originally Posted by liamw Has anyone tried this out in the UK on T-Mobile 3g, I keep getting Registration failed (Timeout) and the red spot, I have tried this with both Ekiga and Gizmo5, any ideas what I might be doing wrong. Will try on wifi tonight. Update: Looking at the Mobile Broadband Plus ( handset as modem) terms and conditions it says you cannot make internet phone calls, so I guess they are blocking the port.

Did you get to check on wifi? Dunno if Gizmo5 supports it, but you could try port 5061 too?