Poor Man's SMS Gateway is now Mercurio

Update:New version of Mercurio is now available - read post here.

Update: Installation instructions for Mercurio S60 were added.

I promised at MobileCampNYC to give away the code I showed during my Poor Man's SMS Gateway talk. To give the app a name shorter than "Poor Man's SMS Gateway", and to avoid using an acronynm like "PMS Gateway", I've decided to rename it under the codename Mercurio. Below are the files and instructions you'll need to get it going on Mac OS X. Instructions for Linux are very similar and I can write a post for it if people request it.

So what's Mercurio?

Mercurio is a barebones SMS framework that can run locally on any machine as well as on a server to send and receive sms messages. It includes a Rails based application as well as a Python script for Symbian S60 users.

The goal is to give everyone the chance to create a mobile application without the hurdles usually associated with mobile development.

Mercurio's features:

Mercurio Web App:
Sends SMS messages
Receives SMS messages
RSS feed for Received messages
Written in a RESTful manner

Mercurio S60:
Client that sends incoming messages to Mercurio Web without user intervention
Makes any Symbian S60 phone into a little sms receiving gateway

Requirements:
A Mac - it works with Linux as well.
A phone or GSM modem compatible with UltraSMS or a Symbian Series 60 phone

Mercurio

Instructions for Mercurio Web and UltraSMS on Mac OS X:

Download and install MySQL. Make sure you install the Preference Pane that comes with the installation files.

Download and install Cocoa UltraSMS and the command line version, UltraSMS. Make sure that
Cocoa UltraSMS and the command line version of it end up in your Applications folder.

Run Cocoa UltraSMS and click on the Setup button. It will create a new database for you
if you don't have one or you can use your own settings if you have previous experience with
MySQL.

Here are the steps for a new MySQL installation:
- For Hostname type: 127.0.0.1 or localhost
- For Port: 3306
- For Database: ultrasms
- Username: root
- Password: leave it blank

To make sure everything is working ok, click on the Test button. If it gives you an
error, you probably don't have MySQL running. Go to System Preferences and look for the
MySQL Preference Pane. Your MySQL Server Status should be green and running. If it isn't,
well... what are you waiting for? Start it up. Running? Cool. Moving on.

Back to Cocoa UltraSMS.

Once your Test is successful, we need to tell it what phone to use. Turn on Bluetooth on your Mac
and on your phone. Make sure your phone is compatible with UltraSMS by checking the list, if
you don't see it, try it anyway. It may work. If you've never paired your phone with your Mac go to
System Preferences -> Bluetooth and click on the Devices tab on the top. Click on the
"Setup New Device..." button and follow the instructions. Come back when you're done.

Now that you have your phone paired, go to the Phone section of the Cocoa UltraSMS Setup and click
on the Select button to pick your phone. Check the Save Settings box and hit the OK button to close
the window.

Are you still alive? Great. Go back to the small UltraSMS window and click on Start this time. To
test it, go to here and type in your number and carrier. If everything is working ok you'll receive a message and the UltraSMS "SMS In:" counter will change to 1.

Now that Cocoa UltraSMS is installed and running, we can get Mercurio running and installed. To do that we
need to install Mercurio and Ruby on Rails. If you're a developer and you don't have Rails, follow these instructions. If when you hear of "Rails" you think of trains, download this application here and you'll be up and running
in no time.

Locomotive - the app you just downloaded - contains a full Ruby on Rails environment for Mercurio to work. Add Mercurio to Locomotive by going to the Menu bar->Applications->Add existing. When it asks you to choose an application, point it to the mercurio folder right under Mercurio Web - here's the file path: Mercurio->Mercurio Web->mercurio. Make the port number 3000 and click the Add button.

Still there? Good. A few more things and we're done.

Via the Finder, go to mercurio->db->database.yml and add the database name and the username. Leave password blank if you just installed MySQL and save the file. What we're doing here is telling Mercurio Web where the SMS will be stored.

What we need to do now is add one more table to the database. Go back to Locomotive's toolbar->Applications->Open in Terminal. Type the following command in the same Terminal window: rake db:migrate and you're done.

To test Mercurio Web, go to Locomotive and start mercurio by clicking on the "Run" green circle. If you see
a shebang warning from Locomotive, don't worry about it, tell it to "Continue without changing." Then
open your browser and go this URL http://localhost:3000/inboxes You should see the message you sent your phone at the beginning of these instructions. You're now ready receive messages.

Testing the command line version of UltraSMS and outgoing messages:

Close Cocoa UltraSMS and make sure MySQL is running. Then go to UltraSMS folder and look for the ultrasms.conf file.

Open it up and add the following settings:

DEVICE = "/dev/tty.LOOK AT BLUETOOTH PREFERENCES" - follow the steps below
DAEMON = "FALSE"
DEBUG = "FALSE"
MYSQL_HOST = "localhost"
MYSQL_DB = "name of the database"
MYSQL_USER = "root"
MYSQL_PASS = "leave it blank if this is a fresh MySQL install"

To get the DEVICE setting for your ultrasms.conf go to System Preferences->Bluetooth->Devices->Edit Serial Ports.

Copy the Port Name that has as a Device Service Serial Port 1 - it could also be 2. In my case, my Port Name is Jose-2 and my Device Service is Serial Port 1. As a result my ultrasms.conf file has this setting:
DEVICE = "/dev/tty.Jose-2".

Save your ultrasms.conf file and open a Terminal window by going to
Finder->Applications->Utilities->Terminal. Go to the directory that has the UltraSMS command
line utility and issue the ./UltraSMS command.

This is what it looks like on my machine:
"Jet:/Applications/Utilities/UltraSMS jose$ ./UltraSMS /dev/tty.Jose-2 localhost:3306 smsgateway root"

"Jet" is the name of my machine. "/Applications/Utilities/UltraSMS" is the path to the directory where
I saved the command line version of UltraSMS. To get there I had to "change directory" by using the
following Unix command in the Terminal:
jose$ cd /Applications/Utilities/UltraSMS

Once you get to the UltraSMS directory you have, issue the command that runs UltraSMS.
"./UltraSMS" is the command that runs UltraSMS and
"/dev/tty.Jose-2 localhost:3306 ultrasms root" is how I tell UltraSMS what device I'm using (from DEVICE in ultrasms.conf), the name of the database and the database user, which is root.

Once you issue the ./UltraSMS command, you'll see a few [Initialising] lines in the Terminal. Something
like this:

[Initialising] - Connected to MySQL database
[Initialising] - Initialising phone
[Initialising] - Changing phone memory settings
[Initialising] - Phone initialised

You can now go to http://localhost:3000/outboxes in your browser and click on "Send a new message."
Add a cell phone number and message and let it rip. The message will be sent in a few seconds.

Installation instructions for Mercurio S60:

Mercurio S60 works hand in hand with Mercurio Web. It was built as an altenative for those that don't have a phone that's compatible with UltraSMS. Using Mercurio S60, if you have a Symbian S60 phone, it will forward all incoming SMS directly to Mercurio Web.

You'll need to have Python for S60 interpreter and scriptshell installed. You can download both files for 2nd and 3rd Edition phones here.

Which version of Python should you install?

If you have a 2nd Edition phone: models such as: 6600, 6630, 6670, 7610
Download: PythonForS60_1_3_21_2ndEd.SIS
PythonScriptShell_1_3_21_2ndEd.SIS

If you have a 2nd Edition phone: models such as: N70, N90
Download: PythonForS60_1_3_21_2ndEdFP3.SIS
PythonScriptShell_1_3_21_2ndEdFP3.SIS

For a 3rd Edition phone: model such as: N80, N93, E61, E62, N95
Download: PythonForS60_1_3_21_3rdEd_selfsigned.SIS
PythonScriptShell_1_3_21_3rdEd_selfsigned.SIS

Once you have Python installed, go to the Mercurio S60 folder and open up the mercurio.py file. Change line 78 from conn = httplib.HTTPConnection("peoplelab.gotdns.com", 80) to conn = httplib.HTTPConnection("YOUR MERCURIO WEB URL", 80). Save the file and send it to your phone via Bluetooth or cable - for 3rd Edition phones, you'll need to save the file in your phone's E:/Python folder.

To run it, locate the Python interpreter in your Applications folder of your phone, hit the "Options" softkey and choose "Run Script". Look for mercurio.py and your phone will be ready to receive SMS messages. To test it for the first time, send a message to your own phone and go through the setup screen. Immediately you'll see the phone fowarding messages to Mercurio Web.

That's all folks!

Please let me know if there's something I need to change or any recommendations you may have.

Comments

[Ali Ozoren]

Jose - I was looking for something like this but a completely standalone version would work better (at least for me). Since I have zero knowledge of Python, I cannot tell how much effort it would take it to change the code so that it posts the incoming sms directly to a web server (..?sender=123&msg=abc) over gprs without a computer, bluetooth, ultrasms, etc. That would be a little costly connection-wise but totally eliminate the need for a dedicated phone. I can pitch in via PayPal as well. Thanks. -a

[Jose]

Hi Ali,

Thanks for your comment and interest in Mercurio.

I'm trying to understand what you mean by a standalone version. Are you looking for an all-in-one appliance that accepts the messages and has a web server?

If this is what you're looking for, please let me know. I started thinking about it as I was writing the Mercurio installation instructions. I'm thinking something the size of a Mac Mini with GSM capabilities and Mercurio built right in. You can then take it with you anywhere, turn it on and you're ready to accept messages. Is that what you have in mind?

Jose

[Ali Ozoren]

Jose - A standalone version meaning, only phone, and nothing else (except the web server listening in the cloud). The phone will receive the sms and post it to a web server on the Internet via gprs. It is a low cost, albeit low bandwidth too, solution to my inbound sms problem. If that too is not clear, my email address is also my msn address for further discussion. Thanks.

[Jose]

Hi Ali,

What you are looking for is already in Mercurio. You see, Mercurio is really 2 SMS Gateway solutions in one. The first solution involves UltraSMS, a mobile and a computer running Mercurio Web. The second solution - using Mercurio S60 - is closer to what you're asking. If you install Mercurio S60 on a Series 60 Symbian phone, it will "forward" your incoming messages directly to the web server - running Mercurio Web - via GPRS or any other connection available to your mobile - EDGE, 3G, Wi-fi, etc.

I hope this helps.

Jose

[Ali Ozoren]

Jose - Is it possible to run the "phone part" as a deamon? I wouldn't want it to exit when a call comes in or when I make a call. In other words, I wish to continue using the phone while it still is in the background.. I also would like it to delete the messages as they arrive since they pile up and consume memory.. Thanks. Ali

[Jose]

Hi Ali,

As it is Mercurio S60 - aka mercurio.py - runs in the background if you leave it running. Due to Symbian's multitasking, if a call comes in the data connection pauses and reconnects when the call is over.
To delete messages after uploading to the web server and Mercurio Web all you need to add is one line of code to the end of the read_sms() function in mercurio.py:

i.delete(id)

Regards,

Jose

[lambo4jos]

Hello. Thank you for such a great post. I noticed you mentioned writing a post for linux if someone requests it. Unfortunately I don't have a Mac. I'm using ubuntu, but I'm sure its the same across different versions of linux. I would be more than appreciative if you could offer some guidance to me of how I can get the sample app up and running on linux to test out your poor mans sms gateway. I would also be willing to give some bug fixes if I come across any and feedback on my usage as well. Thanks in advance.

[Jose]

Hi lambo4jos. Do you need the linux instructions immediately? I can post them this upcoming week if that's ok or we can communicate via email if you're in desperate need.

Thanks for the kind remarks.

[Amit]

Hi Jose,

Excellent stuff. I have a quick question. What kind of throughput can one expect, as in messages sent or received per second?

Also, when sending messages, can one set any phone-number as sender-id? Or will it always be the number of the phone being used?

Thanks!

Regards,
Amit.

[Jose]

Hi Amit,

Throughput is one of the hardest things to measure when dealing with SMS applications because each component of the system has a certain amount of latency and their behavior is unpredictable. Try sending a message to 3 people in the room at the same time and you'll notice that they will all get it at different times.

Sending and receiving takes a few seconds per message. If you send or receive multiple messages at the same time you don't have to worry about it much. Messages get qued in your phone when you receive. At that point it all depends on the amount of memory your phone has. When you send, the message gets deleted from the phone so you don't have to worrry about running out of memory. Normally, a text message is limited to 140 bytes, or 160 7-bit characters. Most "feature" phones have at least 4MB available and smartphones have at least 20MB so you do the math.

So... to answer your question I would say that if you expect your service to send/receive between 2k and 5k messages per day you're in good shape with Mercurio. If your users start experiencing slowdowns then it's time to move away from this prototyping solution and move on to a shortcode.

CallerID/Send id:
People will receive messages from the number that's attached to your phone. However, there are ways to change the CallerID depending on your phone's manufacturer.

I hope this helps.

Thanks for your interest in Mercurio.

Jose

[Tony Hansen]

I am imagining a script running on a web connected cell phone that can post an SMS message to a webpage and send a text message in response to a post from a webpage. Would this device not be a fully functional gateway? Could I then not write a web page in PHP, for example, that could make it possible to do a google search from a text message?